Module: Legion::LLM::Call::Embeddings

Extended by:
Legion::Logging::Helper
Defined in:
lib/legion/llm/call/embeddings.rb

Overview

SSOT v3 §21 — embeddings on the single execution engine.

generate/generate_batch build a per-call RoutingSession from RequestRequirements(operation: :embed, required_capabilities: [:embedding]), select ONE exact lane via Router.next_lane (through the session), then dispatch the lane's EXACT callable via Call::SelectionDispatch — no request_lane, no configured default model/provider/instance, no Call::Dispatch. An omitted model is an UNCONSTRAINED selection, never a default. Selection happens BEFORE the cache lookup (§21.2): a hit is only served after a current Selection proves the request has an eligible embedding function. Typed routing errors (RoutingRejected) propagate to the caller — they are never converted to a nil/zero-vector/safe hash.

Constant Summary collapse

PREFIX_REGISTRY =

Kept for reference/back-compat; the authoritative prefix table lives in settings (:llm, :embedding, :prefix_registry) and is model-keyed, so prefixing stays provider-neutral.

{
  'nomic-embed-text'  => { document: 'search_document: ', query: 'search_query: ' },
  'mxbai-embed-large' => { query: 'Represent this sentence for searching relevant passages: ' }
}.freeze
CHARS_PER_TOKEN =

Conservative provider-neutral estimate used ONLY for the preselection context bound and for post-selection chunk sizing. The router still authorizes lanes against the offering's authoritative context evidence; this estimate never retroactively authorizes an ineligible lane.

4
EMBED_CHUNK_TARGET_TOKENS =

Per-chunk conservative token bound (§21.1). A single embedding request is chunked so each chunk targets at most this many tokens; the selected offering's authoritative context can shrink the chunk further.

512
CACHE_NORMALIZATION =

Vector post-processing mode recorded in the cache-function identity. Vectors are returned exactly as the provider produced them (no L2 normalization, no truncate/pad), so this is a stable constant.

'none'

Class Method Summary collapse

Class Method Details

.generate(text:, model: nil, dimensions: nil, task: :document, provider: nil, instance: nil, request: nil, routing_session: nil, routing_seed: nil) ⇒ Hash

Returns { vector:, model:, provider:, instance:, dimensions:, tokens:, chunks:, tier:, cache_hit: }.

Returns:

  • (Hash) —

    { vector:, model:, provider:, instance:, dimensions:, tokens:, chunks:, tier:, cache_hit: }

Raises:



59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/legion/llm/call/embeddings.rb', line 59

def generate(text:, model: nil, dimensions: nil, task: :document,
             provider: nil, instance: nil, request: nil, routing_session: nil, routing_seed: nil, **)
  return not_started_result(model) unless LLM.started?

  coerced = coerce_text(text)
  session = routing_session || build_session(
    texts: [coerced], model: model, provider: provider, instance: instance,
    dimensions: dimensions, request: request, routing_seed: routing_seed
  )
  run_single(session: session, text: coerced, dimensions: dimensions, task: task)
end

.generate_batch(texts:, model: nil, dimensions: nil, task: :document, provider: nil, instance: nil, request: nil, routing_session: nil, routing_seed: nil) ⇒ Array<Hash>

Returns one entry per input, original order preserved (N -> N).

Returns:

  • (Array<Hash>) —

    one entry per input, original order preserved (N -> N).

Raises:



73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/legion/llm/call/embeddings.rb', line 73

def generate_batch(texts:, model: nil, dimensions: nil, task: :document,
                   provider: nil, instance: nil, request: nil, routing_session: nil, routing_seed: nil, **)
  return texts.map { not_started_result(model) } unless LLM.started?

  coerced = texts.map { |t| coerce_text(t) }
  session = routing_session || build_session(
    texts: coerced, model: model, provider: provider, instance: instance,
    dimensions: dimensions, request: request, routing_seed: routing_seed
  )
  run_batch(session: session, texts: coerced, dimensions: dimensions, task: task)
end