# `GEPA.Embeddings`
[🔗](https://github.com/nshkrdotcom/gepa_ex/blob/v0.3.0/lib/gepa/embeddings.ex#L1)

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.

# `provider`

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

# `text`

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

# `vector`

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

# `dimensions`
*optional* 

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

# `embed`

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

# `embed_batch`

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

# `model`
*optional* 

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

# `dimensions`

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

Return the configured embedding dimension when the provider exposes it.

# `embed`

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

Generate one embedding vector.

# `embed!`

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

Generate one embedding vector or raise.

# `embed_batch`

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

Generate embeddings for a batch of texts.

# `embed_batch!`

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

Generate a batch of embedding vectors or raise.

# `model`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*