GEPA.Embeddings behaviour (GEPA v0.3.0)

Behaviour and facade for embedding providers.

GEPA keeps embedding generation separate from LLM text generation so RAG pipelines can mix a local/CLI inference adapter with a hosted embedding provider. Implementations return explicit {:ok, value} or {:error, reason} tuples; they should not silently fall back to synthetic vectors.

Summary

Types

provider()

text()

vector()

Callbacks

dimensions(provider)

embed(provider, text, keyword)

embed_batch(provider, list, keyword)

model(provider)

Functions

dimensions(provider)

Return the configured embedding dimension when the provider exposes it.

embed(provider, text, opts \\ [])

Generate one embedding vector.

embed!(provider, text, opts \\ [])

Generate one embedding vector or raise.

embed_batch(provider, texts, opts \\ [])

Generate embeddings for a batch of texts.

embed_batch!(provider, texts, opts \\ [])

Generate a batch of embedding vectors or raise.

model(provider)

Return the configured embedding model name when the provider exposes it.

Types

provider()

@type provider() :: module() | struct()

text()

@type text() :: String.t()

vector()

@type vector() :: [float()]

Callbacks

dimensions(provider)

(optional)

@callback dimensions(provider()) :: pos_integer() | nil

embed(provider, text, keyword)

@callback embed(provider(), text(), keyword()) :: {:ok, vector()} | {:error, term()}

embed_batch(provider, list, keyword)

@callback embed_batch(provider(), [text()], keyword()) ::
  {:ok, [vector()]} | {:error, term()}

model(provider)

(optional)

@callback model(provider()) :: String.t() | nil

Functions

dimensions(provider)

@spec dimensions(provider()) :: pos_integer() | nil

Return the configured embedding dimension when the provider exposes it.

embed(provider, text, opts \\ [])

@spec embed(provider(), text(), keyword()) :: {:ok, vector()} | {:error, term()}

Generate one embedding vector.

embed!(provider, text, opts \\ [])

@spec embed!(provider(), text(), keyword()) :: vector()

Generate one embedding vector or raise.

embed_batch(provider, texts, opts \\ [])

@spec embed_batch(provider(), [text()], keyword()) ::
  {:ok, [vector()]} | {:error, term()}

Generate embeddings for a batch of texts.

embed_batch!(provider, texts, opts \\ [])

@spec embed_batch!(provider(), [text()], keyword()) :: [vector()]

Generate a batch of embedding vectors or raise.

model(provider)

@spec model(provider()) :: String.t() | nil

Return the configured embedding model name when the provider exposes it.