Documentation
¶
Overview ¶
Package embeddings provides AI embeddings provider plugins.
This package implements the plugin system for AI embeddings providers, following hexagonal architecture principles.
Supported Providers ¶
- OpenAI (text-embedding-3-small, text-embedding-3-large)
- Anthropic (via OpenAI-compatible API)
- Ollama (local models)
- Azure OpenAI
Usage ¶
provider := embeddings.NewOpenAIProvider(apiKey) embeddings, err := provider.Embed(ctx, "Hello, world!")
Law of Demeter (LoD) ¶
This package follows the Law of Demeter:
- Only talk to immediate collaborators
- No "train-wreck" method calls (a.GetB().GetC().Do())
- Use dependency injection for dependencies
See ADR-005 for architectural details.
Index ¶
- type Config
- type EmbedRequest
- type EmbedResponse
- type EmbedResult
- type Embedding
- type OllamaConfig
- type OllamaEmbedRequest
- type OllamaEmbedResponse
- type OllamaProvider
- func (p *OllamaProvider) Dimensions() int
- func (p *OllamaProvider) Embed(ctx context.Context, texts []string) (*EmbedResult, error)
- func (p *OllamaProvider) EmbedSingle(ctx context.Context, text string) (*Embedding, error)
- func (p *OllamaProvider) Manifest() *plugins.Manifest
- func (p *OllamaProvider) Model() string
- func (p *OllamaProvider) Name() string
- type OpenAIProvider
- func (p *OpenAIProvider) Dimensions() int
- func (p *OpenAIProvider) Embed(ctx context.Context, texts []string) (*EmbedResult, error)
- func (p *OpenAIProvider) EmbedSingle(ctx context.Context, text string) (*Embedding, error)
- func (p *OpenAIProvider) Manifest() *plugins.Manifest
- func (p *OpenAIProvider) Model() string
- func (p *OpenAIProvider) Name() string
- type Option
- type Provider
- type Registry
- func (r *Registry) Embed(ctx context.Context, providerName string, texts []string) (*EmbedResult, error)
- func (r *Registry) EmbedSingle(ctx context.Context, providerName string, text string) (*Embedding, error)
- func (r *Registry) Get(name string) (Provider, error)
- func (r *Registry) List() []string
- func (r *Registry) Register(provider Provider) error
- func (r *Registry) Unregister(name string)
- type Usage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
APIKey string
BaseURL string
Model string
Dimensions int
Timeout time.Duration
}
Config holds common configuration for embeddings providers.
type EmbedRequest ¶
type EmbedRequest struct {
Model string `json:"model"`
Input []string `json:"input"`
Dimension int `json:"dimensions,omitempty"`
}
EmbedRequest represents the OpenAI embeddings API request.
type EmbedResponse ¶
type EmbedResponse struct {
Object string `json:"object"`
Data []struct {
Object string `json:"object"`
Embedding []float32 `json:"embedding"`
Index int `json:"index"`
} `json:"data"`
Model string `json:"model"`
Usage struct {
PromptTokens int `json:"prompt_tokens"`
CompletionTokens int `json:"completion_tokens"`
TotalTokens int `json:"total_tokens"`
} `json:"usage"`
}
EmbedResponse represents the OpenAI embeddings API response.
type EmbedResult ¶
EmbedResult contains the result of an embedding operation.
type OllamaConfig ¶
type OllamaConfig struct {
Config
KeepAlive string // How long to keep model loaded (e.g., "5m", "0")
}
OllamaConfig extends Config with Ollama-specific options.
type OllamaEmbedRequest ¶
type OllamaEmbedRequest struct {
Model string `json:"model"`
Prompt string `json:"prompt"`
KeepAlive string `json:"keep_alive,omitempty"`
}
OllamaEmbedRequest represents the Ollama embeddings API request.
type OllamaEmbedResponse ¶
type OllamaEmbedResponse struct {
Embedding []float32 `json:"embedding"`
}
OllamaEmbedResponse represents the Ollama embeddings API response.
type OllamaProvider ¶
type OllamaProvider struct {
// contains filtered or unexported fields
}
OllamaProvider implements Provider for Ollama API.
func NewOllamaProvider ¶
func NewOllamaProvider(opts ...Option) *OllamaProvider
NewOllamaProvider creates a new Ollama embeddings provider.
func (*OllamaProvider) Dimensions ¶
func (p *OllamaProvider) Dimensions() int
Dimensions returns the embedding dimensions.
func (*OllamaProvider) Embed ¶
func (p *OllamaProvider) Embed(ctx context.Context, texts []string) (*EmbedResult, error)
Embed generates embeddings for the given texts.
func (*OllamaProvider) EmbedSingle ¶
EmbedSingle generates an embedding for a single text.
func (*OllamaProvider) Manifest ¶
func (p *OllamaProvider) Manifest() *plugins.Manifest
Manifest returns the plugin manifest.
func (*OllamaProvider) Model ¶
func (p *OllamaProvider) Model() string
Model returns the model name.
func (*OllamaProvider) Name ¶
func (p *OllamaProvider) Name() string
Name returns the provider name.
type OpenAIProvider ¶
type OpenAIProvider struct {
// contains filtered or unexported fields
}
OpenAIProvider implements Provider for OpenAI API.
func NewOpenAIProvider ¶
func NewOpenAIProvider(opts ...Option) *OpenAIProvider
NewOpenAIProvider creates a new OpenAI embeddings provider.
func (*OpenAIProvider) Dimensions ¶
func (p *OpenAIProvider) Dimensions() int
Dimensions returns the embedding dimensions.
func (*OpenAIProvider) Embed ¶
func (p *OpenAIProvider) Embed(ctx context.Context, texts []string) (*EmbedResult, error)
Embed generates embeddings for the given texts.
func (*OpenAIProvider) EmbedSingle ¶
EmbedSingle generates an embedding for a single text.
func (*OpenAIProvider) Manifest ¶
func (p *OpenAIProvider) Manifest() *plugins.Manifest
Manifest returns the plugin manifest.
func (*OpenAIProvider) Model ¶
func (p *OpenAIProvider) Model() string
Model returns the model name.
func (*OpenAIProvider) Name ¶
func (p *OpenAIProvider) Name() string
Name returns the provider name.
type Option ¶
type Option func(*Config)
Option defines functional options for provider configuration.
func WithDimensions ¶
WithDimensions sets the embedding dimensions.
func WithTimeout ¶
WithTimeout sets the request timeout.
type Provider ¶
type Provider interface {
// Embed generates embeddings for the given texts.
Embed(ctx context.Context, texts []string) (*EmbedResult, error)
// EmbedSingle generates an embedding for a single text.
EmbedSingle(ctx context.Context, text string) (*Embedding, error)
// Name returns the provider name.
Name() string
// Model returns the default model name.
Model() string
// Dimensions returns the embedding dimensions.
Dimensions() int
}
Provider defines the interface for embeddings providers. Following Interface Segregation Principle (ISP) - minimal interface.
Law of Demeter Compliance ¶
Implementations must:
- Accept dependencies via constructor (not service locator)
- Return value objects (not internal state)
- Not expose internal components via getters
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages embeddings providers. Following Law of Demeter - only exposes necessary operations.
func DefaultRegistry ¶
func DefaultRegistry() *Registry
DefaultRegistry returns a registry pre-configured with default providers.
func (*Registry) Embed ¶
func (r *Registry) Embed(ctx context.Context, providerName string, texts []string) (*EmbedResult, error)
Embed delegates to a named provider.
func (*Registry) EmbedSingle ¶
func (r *Registry) EmbedSingle(ctx context.Context, providerName string, text string) (*Embedding, error)
EmbedSingle delegates to a named provider for single text.
func (*Registry) Unregister ¶
Unregister removes a provider from the registry.