Module embedding 

The embedder-supplied seam for submilli:embedding — batches of text embedded by a remote provider from inside a Submilli program.

Mirrors crate::runtime::llm: the HTTP, key resolution and retry live in the embedder behind EmbeddingProvider, and token accounting runs on the shared TokenLedger.

No input text appears here. Not in an error Display, not in a log line, not in a settlement. Errors carry the alias, numbers, an input index, and a fixed kebab-case classification string; provider response bodies are dropped at this boundary.

Settlement protocol

A call is split by the provider into sub-batches, each sent as one outbound request. The stdlib reserves the whole estimate up front (EmbeddingTokenBudget::reserve) and hands the provider the budget. For every sub-batch the provider:

1. calls EmbeddingTokenBudget::mark_sent with that sub-batch’s estimate immediately before sending. This counts the request against the per-run cap (refusing past it) and moves the estimate from “reserved” to “held”, so a future dropped mid-flight leaves the sub-batch held while unsent sub-batches are returned when the budget drops;
2. records a SubBatchSettlement when the response (or failure) arrives.

Settlements travel back on EmbeddingBatch::settlements or inside the error, and the stdlib applies them with EmbeddingTokenBudget::settle, which also releases whatever was reserved but never sent. The outcome table the provider applies to each sent sub-batch:

Sub-batch outcome	reported	indeterminate
Succeeded with nonzero usage	usage	0
Succeeded without usage, or usage 0	0	estimate
Never sent (credential unresolved, blocked by network policy, connect failure)	0	0 (released)
Rejected by provider with 4xx (incl. 429)	0	0 (released)
Sent, then 5xx / transport / timeout / failed validation	usage if reported	else estimate
Sent, then the future is dropped (cancelled)	0	estimate

Sub-batches never sent have no settlement; they are released by settle.

Re-exports

pub use super::token_ledger::SharedTokenBudget;

Structs

EmbeddingBatch

The result of one successful call: count vectors of dimensions floats, row-major, labeled with the embedding-space identity.

EmbeddingLimits

The ceilings an embedding call is checked against.

EmbeddingModel

An embedding model alias the provider serves.

EmbeddingTokenBudget

One execution’s embedding budget: tokens against its own ceiling and the server-wide one, plus the outbound request counter.

SubBatchSettlement

What one sent sub-batch cost. estimate is what was passed to EmbeddingTokenBudget::mark_sent; see the module table for the other two. The remainder (estimate - reported - indeterminate) is released.

Enums

EmbeddingBoundKind

Which input bound a call ran into.

EmbeddingError

Why an embedding call failed. Variants after the pre-send group carry the settlements of every sub-batch that was sent before the failure.

EmbeddingFailureReason

Why a sent request failed, as a closed vocabulary (the wire form is Self::as_str).

EmbeddingLimitKind

Which ceiling refused a call. Carries numbers, never inputs.

EmbeddingMalformedReason

Why a provider response was unusable.

EmbeddingShapeError

Row access or construction outside an EmbeddingBatch’s shape.

Purpose

What an embedding is for. Some providers embed queries and documents differently.

Constants

DEFAULT_MAX_BYTES_PER_CALL

UTF-8 bytes across one call’s texts.

DEFAULT_MAX_EMBEDDING_REQUESTS

Outbound provider requests one execution may send.

DEFAULT_MAX_EXECUTION_EMBEDDING_TOKENS

Tokens one execution may spend across every embedding call it makes.

DEFAULT_MAX_HELD_EMBEDDING_TOKENS

Tokens one execution may hold as indeterminate reserve.

DEFAULT_MAX_TEXTS_PER_CALL

Texts in one call.

EMBEDDING_MODULE_NAME

The single internal host module every submilli:embedding call dispatches through.

Traits

EmbeddingProvider

The embedder-provided embedding provider: resolves credentials, performs the requests, and reports what each cost.

Functions

estimate_embedding_tokens

The token estimate for one input: ceil(utf8_bytes / 3).