embeddings

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 2, 2026 License: MIT Imports: 8 Imported by: 0

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

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

type EmbedResult struct {
	Embeddings []Embedding
	Usage      Usage
}

EmbedResult contains the result of an embedding operation.

type Embedding

type Embedding struct {
	Vector  []float32
	Model   string
	Tokens  int
	Created time.Time
}

Embedding represents a vector embedding.

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

func (p *OllamaProvider) EmbedSingle(ctx context.Context, text string) (*Embedding, error)

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

func (p *OpenAIProvider) EmbedSingle(ctx context.Context, text string) (*Embedding, error)

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 WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey sets the API key.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL sets the base URL.

func WithDimensions

func WithDimensions(dims int) Option

WithDimensions sets the embedding dimensions.

func WithModel

func WithModel(model string) Option

WithModel sets the model name.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

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 NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new embeddings registry.

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) Get

func (r *Registry) Get(name string) (Provider, error)

Get retrieves a provider by name.

func (*Registry) List

func (r *Registry) List() []string

List returns all registered provider names.

func (*Registry) Register

func (r *Registry) Register(provider Provider) error

Register adds a provider to the registry.

func (*Registry) Unregister

func (r *Registry) Unregister(name string)

Unregister removes a provider from the registry.

type Usage

type Usage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

Usage represents token usage statistics.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL