# mimir_analytics v0.8.1 - API Reference

## Modules

- [MimirAnalytics](MimirAnalytics.md): Analytical run-record store for the mimir agent stack: the canonical,
queryable record of an agent run — workflow → step → run (session) → turn
→ tool_call, plus model calls, routing decisions, eval outcomes, and raw
events. Mappers ingest from gateway pull-buffers, session drops, and eval
reports into a shared correlation-id contract (`workflow_id`, `step_id`,
`run_id`, `mimir_request_id`, and friends), backed by a local DuckDB file
in dev/test and a MotherDuck-hosted DuckLake in deployment. This library
depends on nothing else in-house — see the dependency-direction invariant
in the README.

- [MimirAnalytics.Capture](MimirAnalytics.Capture.md): Session-finish capture: writes `{"meta": ..., "result": ...}` as a one-line
JSONL file into a sessions spool directory. Explicit call from the
step-runner / eval harness rather than a telemetry attachment. Takes plain maps; structs must be Jason-encoded to maps by the
caller.
- [MimirAnalytics.Ingest.GatewayPull](MimirAnalytics.Ingest.GatewayPull.md): Pulls the gateway's read-only Observability API (`updated_since` cursor)
and buffers each page as run-record JSONL — the same line shapes the
gateway-export mapper ingests, so the buffer file is the contract wherever
the bytes came from. Plain HTTP + maps only (dependency-direction
invariant).
- [MimirAnalytics.Mapper](MimirAnalytics.Mapper.md): Shared ingest behaviour for session, evaluation and gateway files.
Summaries count rows by table; already-ingested and rejected contents
return their corresponding status atoms.

- [MimirAnalytics.Mappers.EvalReport](MimirAnalytics.Mappers.EvalReport.md): `eval_runs/*.json` report → `eval_outcomes` rows (the original eval-ingest
long format, widened with agent/suite/runtime/run_id). Idempotent by
file contents.
- [MimirAnalytics.Mappers.GatewayExport](MimirAnalytics.Mappers.GatewayExport.md): Gateway JSONL buffer files → `model_calls` + `routing_decisions` + `events_raw`.
Line kinds: "request_log", "routing_decision" — written by
`MimirAnalytics.Ingest.GatewayPull` from the gateway Observability API;
the fixture is the contract, wherever the bytes came from.
- [MimirAnalytics.Mappers.Session](MimirAnalytics.Mappers.Session.md): Session JSONL into `runs`, `tool_calls` and optional `events_raw` rows.
Accepts either a `meta`/`result` envelope or a flat run record containing
`run_id`. Flat records are normalized once at ingress. Other shapes raise.
- [MimirAnalytics.Row](MimirAnalytics.Row.md): Typed row structs for the run-record tables. `tables/0` maps table names
to their row modules. Each module owns source-field coercion in `new/1`.
- [MimirAnalytics.Row.EvalOutcome](MimirAnalytics.Row.EvalOutcome.md): One evaluation case joined with its matching judge result by `case_id`.
Report-level agent, suite and runtime fields accompany the case.
Missing optional source fields remain `nil`.

- [MimirAnalytics.Row.EvalOutcome.Case](MimirAnalytics.Row.EvalOutcome.Case.md): One typed, named case record: an eval report's `results[]` entry joined
with its matching `judge_results[]` entry (by `case_id`) — replaces the
untyped positional `c`/judge-map digs that used to feed `eval_row/4`
directly at the `MimirAnalytics.Mappers.EvalReport` call site.

- [MimirAnalytics.Row.EventRaw](MimirAnalytics.Row.EventRaw.md): One row of `events_raw` — a single raw event from either a Capture session
result or a gateway request log's `turn_events`, tagged by `source` so
downstream consumers can tell which shape `payload` carries, and by `domain`
(`llm | agent | workflow`) when the source event carries the typed vocabulary.
- [MimirAnalytics.Row.MemoryProvenance](MimirAnalytics.Row.MemoryProvenance.md): One row of `memory_provenance`. Current mappers do not write this table;
callers can construct rows with `new/1`.

- [MimirAnalytics.Row.ModelCall](MimirAnalytics.Row.ModelCall.md): One row of `model_calls` — a gateway `"request_log"` line. `new/1` owns the
rename off the wire shape (`request_id` → `mimir_request_id`,
`inserted_at` → `ts`) and the usage/fallback defaults. `run_id` starts
`nil`; `GatewayExport.resolve_run_ids/1` backfills it via
`(workflow_id, step_id)` against `runs` after ingest.

- [MimirAnalytics.Row.RoutingDecision](MimirAnalytics.Row.RoutingDecision.md): One row of `routing_decisions` — a gateway `"routing_decision"` line.
`new/1` owns flattening the nested `descriptor`/`verdict`/`snapshot`
(and `descriptor.agent`) wire shape onto the table's flat columns —
formerly positional `d`/`v`/`s`/`agent` digs at the mapper call site.

- [MimirAnalytics.Row.Run](MimirAnalytics.Row.Run.md): One captured session mapped onto the run-record correlation columns.
- [MimirAnalytics.Row.Step](MimirAnalytics.Row.Step.md): One row of `steps`. Current mappers do not write this table;
callers can construct rows with `new/1`.

- [MimirAnalytics.Row.ToolCall](MimirAnalytics.Row.ToolCall.md): One row of `tool_calls` — a single custom/server tool use from a Capture
session result, or one occurrence of a `RunRecord` name/count roll-up.
`new/1` owns extracting `id`/`name`/`input` off the tool-use map (formerly
positional digs at the mapper call site) and defaulting `input` to `%{}`
when the tool use carried none.
- [MimirAnalytics.Row.Turn](MimirAnalytics.Row.Turn.md): One per-turn row. The session mapper currently writes a run-level turn
count, not rows in this table. Callers with per-turn data can construct
rows with `new/1`.

- [MimirAnalytics.Row.WorkflowRun](MimirAnalytics.Row.WorkflowRun.md): One row of `workflow_runs`. Current mappers do not write this table;
callers can construct rows with `new/1`.

- [MimirAnalytics.Schema](MimirAnalytics.Schema.md): Canonical run-record DDL. Tables are created if absent, then missing
columns are added to existing tables. `apply/1` is idempotent.
- [MimirAnalytics.Store](MimirAnalytics.Store.md): DuckDB run-record store for local files or MotherDuck databases. Inserts
accept structs and derive SQL columns from their fields.
- [MimirAnalytics.Views](MimirAnalytics.Views.md): Re-appliable analytical views over the run-record tables.

## Mix Tasks

- [mix mimir_analytics.ingest](Mix.Tasks.MimirAnalytics.Ingest.md): Ingests every non-ledgered buffer file, resolves model-call run ids, and
(re)applies the consumer views. See the README.
- [mix mimir_analytics.setup](Mix.Tasks.MimirAnalytics.Setup.md): Downloads the `json` and `core_functions` DuckDB extensions into the local
extension directory (network). Run once per machine / CI runner; after
that, `Schema.apply/1` only LOADs from disk and tests stay offline.