ALLM.EmbeddingRequest (allm v0.5.0)

Copy Markdown View Source

A text-embedding request — Layer A serializable data.

iex> req = ALLM.EmbeddingRequest.new(input: ["a kestrel"], task_type: :search_document)
iex> req.truncate
true

:input is always a list

The bare-string call shape belongs to the façade — ALLM.embedding_request/2 normalizes "one chunk" to ["one chunk"]. On the struct, :input is always [String.t()], so no adapter or validator arm has to handle a union. There is deliberately no @enforce_keys: input: [] must be constructible so that ALLM.Validate.embedding_request/1 — not struct!/2 — is what rejects it.

:task_type

A provider-neutral closed enum for asymmetric embedding: encoding a search query differently from the documents it will be matched against measurably improves retrieval. It maps to Gemini's taskType and Voyage's input_type. OpenAI has no equivalent and its adapter drops the field rather than erroring, matching the contract images set for response_format on gpt-image-1.

:task_type is one of ALLM's closed atom enums; an unknown value at decode time raises ArgumentError and surfaces as {:_unknown, :atom_decode_failed} per the serializer's rescue contract. A value that happens to already exist as an atom decodes through — call ALLM.Validate.embedding_request/1 if you need the enum enforced.

Other fields

:truncate defaults to true, matching the provider-side default on every bundled target, so adapters omit it from the wire body when true and send it explicitly only when false. :options is the documented home for provider-specific opaque opts (OpenAI's request-level user identifier, for example). :dimensions requests a truncated output dimensionality where the model supports it; per-model caps are not checked here — that is ALLM.Capability.preflight_embedding/2's job.

Summary

Types

t()
task_type()

Closed enum of provider-neutral embedding task types.

Functions

new(opts \\ [])

Build an %EmbeddingRequest{} from keyword opts.

Types

t()

@type t() :: %ALLM.EmbeddingRequest{
  dimensions: pos_integer() | nil,
  input: [String.t()],
  metadata: map(),
  model: String.t() | nil,
  options: map(),
  task_type: task_type() | nil,
  truncate: boolean()
}

task_type()

@type task_type() ::
  :search_document | :search_query | :classification | :clustering | :similarity

Closed enum of provider-neutral embedding task types.

Functions

new(opts \\ [])

@spec new(keyword()) :: t()

Build an %EmbeddingRequest{} from keyword opts.

Unknown keys raise KeyError via struct!/2. No validation — call ALLM.Validate.embedding_request/1 to check the field rules.

Examples

iex> req = ALLM.EmbeddingRequest.new()
iex> req.input
[]
iex> req.task_type
nil

iex> req = ALLM.EmbeddingRequest.new(input: ["a", "b"], dimensions: 512)
iex> length(req.input)
2
iex> req.dimensions
512