API Reference mimir_analytics v#0.8.1

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.

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.

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).

Shared ingest behaviour for session, evaluation and gateway files. Summaries count rows by table; already-ingested and rejected contents return their corresponding status atoms.

eval_runs/*.json report → eval_outcomes rows (the original eval-ingest long format, widened with agent/suite/runtime/run_id). Idempotent by file contents.

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.

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.

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.

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.

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.

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.

One row of memory_provenance. Current mappers do not write this table; callers can construct rows with new/1.

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.

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.

One captured session mapped onto the run-record correlation columns.

One row of steps. Current mappers do not write this table; callers can construct rows with new/1.

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.

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.

One row of workflow_runs. Current mappers do not write this table; callers can construct rows with new/1.

Canonical run-record DDL. Tables are created if absent, then missing columns are added to existing tables. apply/1 is idempotent.

DuckDB run-record store for local files or MotherDuck databases. Inserts accept structs and derive SQL columns from their fields.

Re-appliable analytical views over the run-record tables.

Ingests every non-ledgered buffer file, resolves model-call run ids, and (re)applies the consumer views. See the README.

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.