Crate amberfork_ingest 

Forgiving loader from plain-JSON trace files into the canonical amberfork_model::Run.

This is the input edge of the pipeline. docs/trace-format.md promises a deliberately forgiving format: a step’s unknown fields are preserved into attrs and surfaced as an “unmapped attributes” warning rather than failing the parse. That forgiveness lives here, not in the frozen model — amberfork_model::Step is strict and cannot hold unknown fields, so this crate deserializes into private Raw* mirror types that capture the extras (#[serde(flatten)]) and folds them into attrs during conversion.

What stays strict: the canonical kind vocabulary. A step whose kind is not one of llm/tool/agent/other is a IngestError::NotATrace, not a forgiven value — mapping framework-specific span kinds down onto the canonical four is a normalizer’s job, not this canonical loader’s.

Sync by design: this is std::fs only. tokio is reserved for the genuine async I/O edge (record/serve), so the ingest path stays a pure, testable function.

Modules

genai

Framework source adapters. Unlike the canonical loader above, these map a foreign trace shape onto Run; each is namespaced so its quirks stay isolated from the canonical format. Adapter from native OTel GenAI (gen_ai.*) OTLP/JSON span exports into canonical amberfork_model::Runs.

hal

Adapter from a HAL hal_traces config dump into canonical amberfork_model::Runs — the reference side of the natural-pair benchmark (issue #41 S4b).

openinference

Adapter from OpenInference OTLP/JSON span exports into canonical amberfork_model::Runs.

tape

Adapter from ServiceNow TapeAgents tapes into the canonical amberfork_model::Run plus the metadata needed to pair one. Ported from spike/make_realpairs.py’s convert_tape (TapeAgents = ServiceNow/TapeAgents, Apache-2.0).

trail

Adapter from TRAIL / Patronus-SDK trace trees into canonical amberfork_model::Runs.

whowhen

Adapter from Who&When failure logs into the canonical amberfork_model::Run plus its gold label. Ported from spike/convert_whowhen.py (Who&When = ag2ai/Agents_Failure_Attribution, MIT).

Structs

Ingested

A loaded run together with any non-fatal diagnostics raised while normalizing it. The warnings flow onward into amberfork_model::DiffResult::warnings.

Enums

IngestError

Everything that can go wrong loading a trace. The library path returns this rather than panicking.

Functions

from_json_str

Parse a canonical trace from a JSON string.

load_file

Load a canonical trace from a file on disk.