API Reference Mimir v#0.3.0

Mimir is an embeddable routing oracle, pricing source, and decision vocabulary for LLM workloads. Consult it in-process: hand it a workload descriptor and an operational snapshot, and it hands back a placement (or a reasoned no-candidate answer) plus an auditable decision record. A gateway service built on top of Mimir is one possible embedder — not a requirement.

One catalog entry's verdict in a routing decision: :chosen, :ranked (viable but not chosen), or {:excluded, reason}.

The routable universe: config-sourced entries (:mimir, :catalog) joining a model with the routing metadata the oracle filters on — lane, runtime, capabilities, latency, priority. Config-first by design; richer sourcing can replace the source without touching the oracle.

One routable catalog entry.

Typed routing-decision record. build/5 returns a %DecisionRecord{}; to_event/1 renders the binary-keyed audit map suitable for appending as a turn event. No Repo, no clock beyond accepting the snapshot's snapshot_at.

The workload descriptor — the public contract a workflow step presents to a routing oracle. Pure validation: no persistence, no process state.

A minted routing grant from a route response: the granted key and its budget and expiry. Wire vocabulary — plain data parsed by Mimir.RouteResponse.new/1.

Turn-guard builders for a session loop's between-turn hook (RMA 0.5.0's turn_guard: option). Plain data in, plain verdict out — no RMA types.

Failure-streak table for router lanes.

Decision-correlated ingestion of raw agent-session events into Mimir.TurnEvents. Targets RMA's documented plain-data event maps — raw provider events plus the synthetic "rma.text_delta" — but accepts any binary-keyed %{"type" => ...} map. No RMA types.

The pure routing decision: filter-then-rank over catalog entries. Every input entry receives a verdict (:chosen | :ranked | {:excluded, reason}) — the verdict table IS the decision record's body. No Repo, no process state, no side effects; the operational world arrives as a Snapshot argument.

A chosen entry, why it was chosen, and every candidate's verdict.

Routing constraints layered on top of the catalog itself.

The flat chosen-model placement from a route response: which lane, model, and runtime the workload was placed on. Wire vocabulary — distinct from Mimir.Oracle.Decision, the rich server-side decision.

Token usage -> integer microdollar cost.

Helpers for masking secrets and gating payload capture.

The typed record of one routing decision — who asked (caller), which workflow step (correlation), how it ended (outcome), and the decision record. to_meta/2 translates it into request-log meta vocabulary; how (and whether) that meta is persisted belongs to the embedder.

The parsed result of a routing call (Mimir.RouterClient.route/2). This is the single boundary where an atom- or string-keyed decoded JSON response is turned into mimir's struct vocabulary: build with new/1, then consume assertively (resp.grant.budget_microdollars, pattern-match on verdict). Downstream code never touches a raw route map.

Behaviour for routing oracle clients. This package ships one implementation

RouterClient implementation that calls POST /v1/route over HTTP via Req.

The one canonical recipe for wiring a routed placement into an agent session: granted key + routed base_url into model_config, budget guard from the grant, correlation metadata for decision-linked ingestion. Produces a plain keyword list targeting RMA's documented session options — no RMA types imported.

A point-in-time view of the operational state the oracle ranks against. Assembled from explicit inputs — the embedder wires its own health, pricing, and budget sources; the oracle only ever sees this struct. Staleness affects optimality, never safety: enforcement happens where budgets are enforced, not here.

Per-request ordered gen_ai.* event buffer.

Dependency-free builders for binary-keyed gen_ai.* attribute maps (OpenTelemetry GenAI semantic conventions).

Refresh the vendored token-pricing DB used by Mimir.Pricing.

Drives the public mimir API surface end-to-end as one repeatable command — no network, no external services. The HTTP client stage runs a real Req request against an in-process plug, so JSON encoding, response atomization, and error mapping execute production code at the transport seam. The health and turn-event stages run the real GenServers, ETS tables, and telemetry handlers.