Module embedder 

Local embedding generation (LLM-only, one-shot per invocation). Embedding generation for the GraphRAG memory.

v1.0.76: the default build is LLM-only — the binary does NOT bundle fastembed / ort / ndarray / tokenizers. All embeddings are produced by the OpenRouter REST embeddings API and stored as a BLOB in memory_embeddings(memory_id, embedding, source). Vector similarity is computed in pure Rust at query time.

Workload classification (G42/S3, BLOCK 1 — MANDATORY)

LLM embedding is I/O-bound: each call waits on a network round-trip to the OpenRouter REST API while the local CPU stays idle. Concurrency therefore uses tokio (async I/O concurrency) and NEVER rayon (reserved for CPU-bound work).

Permit formula (G42/S3, BLOCO 2)

permits = clamp(--llm-parallelism, 1, 32)
          .min(available_parallelism())
          .min(available_ram_mb * 0.5 / LLM_WORKER_RSS_MB)

LLM_WORKER_RSS_MB = 350 (crate::constants): the historical per-worker RSS budget, retained as the RAM bound on the permit formula.

Structs

EmbedCacheStats

G56: stats snapshot returned by embed_entity_texts_cached.

Enums

EmbeddingErrorKind

GAP-004 (v1.0.88): typed classifier for embedding error messages.

FallbackReason

G58/S1: reason an embedding call could not be completed and the caller must fall back to a non-vector retrieval path (FTS5 prefix + LIKE).

LlmBackendKind

LLM backend kind for the fallback chain. Mirrors the CLI --llm-backend enum so users can pass the same value to --llm-fallback without translation.

Constants

CHUNK_EMBED_BATCH_SIZE

Calibration base: chunk (long-text) batch size per LLM call at the calibration dimensionality (G42/S2). Use chunk_embed_batch_size for the dim-adaptive value (G44).

EMBED_BATCH_CALIBRATION_DIM

Dimensionality the batch bases above were calibrated against (G44).

ENTITY_EMBED_BATCH_SIZE

Calibration base: entity-name (short-text) batch size per LLM call at the calibration dimensionality (G42/S2). Use entity_embed_batch_size for the dim-adaptive value (G44).

Functions

bytes_to_f32

Bytes to f 32.

chunk_embed_batch_size

Dim-adaptive batch size for chunk (long-text) embedding calls (G44).

classify_embedding_error

Classify an embedding AppError into a typed FallbackReason.

effective_permits

G42/S3 BLOCO 2: effective permit count.

embed_entity_texts_cached

G56: embeds entity-name texts through a process-wide cache.

embed_passage_or_skip

v1.0.89 (BUG-SKIP-EMBED + GAP-EMBED-PROPAGATION): embed a passage honouring both --llm-backend and --skip-embedding-on-failure.

embed_passage_with_choice

Embed a single passage using the LLM backend selected by the user via --llm-backend. Routes to embed_with_fallback so failures fall through to the next backend in the chain before giving up.

embed_passage_with_embedding_choice

v1.0.93: embedding with EmbeddingBackendChoice awareness.

embed_passages_parallel_shared

Embeds many passages with EmbeddingBackendChoice awareness (GAP-SG-147).

embed_via_backend

Embeds a single text via the given backend. Used by embed_with_fallback and exposed to allow direct one-shot selection without a chain. Embeds a single text via the given backend. Used by embed_with_fallback and exposed to allow direct one-shot selection without a chain.

embed_via_backend_legacy

Legacy one-shot wrapper around embed_via_backend that discards the resolved backend. Kept for call sites that only care about the vector and ignore the executed-backend signal. New code should prefer embed_via_backend directly.

embed_via_backend_strict

Embed via backend strict.

embed_with_fallback

Tries each LLM backend in chain in order, returning the first successful embedding. On failure, the diagnostic tail of the last error is preserved in the returned AppError::Embedding so the operator can see WHY every backend failed.

embedding_dim

Returns the dimensionality of the embedding space. Used to validate LLM responses and to size the in-memory cache.

entity_embed_batch_size

Dim-adaptive batch size for entity-name (short-text) embedding calls (G44).

f32_to_bytes

F 32 to bytes.

get_openrouter_chat_client

v1.0.95 (ADR-0054): initialises the process-wide OpenRouter chat client on first use and returns it. model is the text model the enrich JUDGE will call (no default; the caller validates presence upfront).

get_openrouter_embedder

Initialises the process-wide OpenRouter embedding client on first use and returns it.

is_openrouter_initialized

Returns true when the process-wide OpenRouter embed client is ready.

openrouter_chat_client

v1.0.95: returns the process-wide OpenRouter chat client if it has already been initialised via get_openrouter_chat_client. Used by the enrich JUDGE dispatch, which initialises the singleton once at startup and then fetches it per item without re-threading the API key.

should_skip_embedding_on_failure

v1.0.89 (BUG-SKIP-EMBED): reads --skip-embedding-on-failure / runtime_config (flag > XDG; product env is not read). Returns true when the user opted to persist with NULL embedding on failure.

try_embed_query_with_choice

failure, returns a structured FallbackReason so the caller can surface vec_degraded instead of a hard exit 11.

try_embed_query_with_deterministic_fallback

G58 / ADR-0043 (v1.0.85): deterministic fallback for recall and hybrid-search.

try_embed_query_with_embedding_choice

v1.0.93 (GAP-OR-INGEST): query embedding with EmbeddingBackendChoice awareness. Mirrors try_embed_query_with_choice but routes through embed_passage_with_embedding_choice so OpenRouter API is used when configured.

try_embed_query_with_fallback

G58/S1: try to embed a query, mapping any failure to a structured FallbackReason so callers can route to FTS5 + LIKE fallback instead of returning exit 11 to the user.