# Mimir v0.4.0 - Table of Contents

> Embeddable routing oracle, pricing, and decision vocabulary for LLM workloads

## Pages

- [Mimir](readme.md)
- [Changelog](changelog.md)
- [LICENSE](license.md)

## Modules

- [Mimir](Mimir.md): 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.
- [Mimir.Candidate](Mimir.Candidate.md): One catalog entry's verdict in a routing decision: `:chosen`, `:ranked`
(viable but not chosen), or `{:excluded, reason}`.

- [Mimir.Catalog](Mimir.Catalog.md): 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.
- [Mimir.Catalog.Entry](Mimir.Catalog.Entry.md): One routable catalog entry.
- [Mimir.DecisionRecord](Mimir.DecisionRecord.md): 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`.
- [Mimir.Descriptor](Mimir.Descriptor.md): The workload descriptor — the public contract a workflow step presents to a
routing oracle. Pure validation: no persistence, no process state.
- [Mimir.Event](Mimir.Event.md): Domain-typed event envelope — the vocabulary root for everything that
travels the `llm.* / agent.* / workflow.*` streams. `domain`/`type` are
closed atom unions, `usage`/`tool` are the promoted commons consumers
actually query, and anything provider-specific rides `raw` (the documented
verbatim carve-out).
- [Mimir.Event.OTel](Mimir.Event.OTel.md): Canonical export-edge rendering for `Mimir.Event` — one mapper, one private
renderer per domain, no per-consumer drift (spec §3.3: "`gen_ai` is a wire
format at the export edge, not a domain model").
- [Mimir.Grant](Mimir.Grant.md): 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`.

- [Mimir.Guard](Mimir.Guard.md): Turn-guard builders for a session loop's between-turn hook (RMA's
`turn_guard:` option; 0.5.0+, hook shape unchanged through 0.10). Plain
data in, plain verdict out — no RMA types.
- [Mimir.Health](Mimir.Health.md): Failure-streak table for router lanes.
- [Mimir.Ingest](Mimir.Ingest.md): 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.
- [Mimir.Oracle](Mimir.Oracle.md): 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.
- [Mimir.Oracle.Decision](Mimir.Oracle.Decision.md): A chosen entry, why it was chosen, and every candidate's verdict.
- [Mimir.Oracle.Policy](Mimir.Oracle.Policy.md): Routing constraints layered on top of the catalog itself.
- [Mimir.Placement](Mimir.Placement.md): 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.

- [Mimir.Pricing](Mimir.Pricing.md): Token usage -> integer microdollar cost.
- [Mimir.Redact](Mimir.Redact.md): Helpers for masking secrets and gating payload capture.
- [Mimir.RouteLog](Mimir.RouteLog.md): 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.
- [Mimir.RouteResponse](Mimir.RouteResponse.md): The parsed result of a routing call (`c: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.
- [Mimir.RouterClient](Mimir.RouterClient.md): Behaviour for routing oracle clients. This package ships one implementation
- [Mimir.RouterClient.HTTP](Mimir.RouterClient.HTTP.md): `RouterClient` implementation that calls `POST /v1/route` over HTTP via Req.
- [Mimir.Sessions](Mimir.Sessions.md): 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.
- [Mimir.Snapshot](Mimir.Snapshot.md): 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.
- [Mimir.TurnEvents](Mimir.TurnEvents.md): Per-request ordered `Mimir.Event` buffer.

## Mix Tasks

- [mix mimir.pricing.refresh](Mix.Tasks.Mimir.Pricing.Refresh.md): Refresh the vendored token-pricing DB used by `Mimir.Pricing`.
- [mix mimir.smoke](Mix.Tasks.Mimir.Smoke.md): 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.

