Candil.Embeddings (Candil v2.1.0)

Embedding generation abstraction over multiple providers.

Provides a unified embed/2 that dispatches to the correct provider (ollama, local llama.cpp, OpenAI-compatible API). Used as a lower-level embedding backend independent from Candil.Llm — this module accepts raw provider parameters (URL, model, api_key) rather than Candil structs.

Summary

Types

embedding()

Embedding vector

Functions

embed(text, opts \\ [])

Generates an embedding vector for a single text string.

embed_batch(texts, opts \\ [])

Generates embeddings for multiple texts in a single batch request.

Types

embedding()

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

Embedding vector

Functions

embed(text, opts \\ [])

@spec embed(
  String.t(),
  keyword()
) :: {:ok, embedding()} | {:error, String.t()}

Generates an embedding vector for a single text string.

Provider-specific behaviour

"ollama" — POST /api/embed with model and input
"local" — POST /v1/embeddings with model and input
"openai" — POST /v1/embeddings with model, input, auth header

Options

:provider — provider type (default: "local")
:url — base URL
:model — model name
:api_key — API key for authenticated providers
:timeout — request timeout in ms (default: 30_000)

embed_batch(texts, opts \\ [])

@spec embed_batch(
  [String.t()],
  keyword()
) :: {:ok, [embedding()]} | {:error, String.t()}

Generates embeddings for multiple texts in a single batch request.

Falls back to individual requests if batching is not supported by the provider.