Skip to content

Index

diapason.traces

Trace system — full interaction-level recording and analysis.

The trace system captures the complete sequence of steps an agent takes to handle a query. Unlike telemetry (which records per-inference metrics), traces record the decision-making process: which model was selected, what memory was retrieved, which tools were called, and the final response.

Traces are the primary input to the learning system.

TraceAnalyzer

Read-only query layer over a :class:TraceStore.

Computes aggregated statistics from stored traces, providing the inputs that the learning system needs to update routing policies.

export_traces(*, since=None, until=None, limit=1000)

Export traces as plain dicts (for JSON serialization).

per_route_stats(*, since=None, until=None)

Compute stats grouped by (model, agent) routing decisions.

per_tool_stats(*, since=None, until=None)

Compute stats grouped by tool name.

summary(*, since=None, until=None)

Compute an overall summary of all traces in the time range.

traces_for_query_type(*, has_code=False, min_length=None, max_length=None, since=None, until=None)

Retrieve traces matching query characteristics.

Useful for the learning system to find traces similar to a new query and learn which routing decisions worked best.

TraceCollector

Wraps a BaseAgent and records a :class:Trace for every run().

The collector subscribes to the EventBus to capture inference, tool, and memory events emitted during agent execution, converting them into TraceStep objects. When the agent finishes, the complete Trace is persisted to the TraceStore and published on the bus.

Enhanced to capture full model response content, tool call arguments and results, and the complete conversation message history.

Usage::

agent = OrchestratorAgent(engine, model, tools=tools, bus=bus)
collector = TraceCollector(agent, store=trace_store, bus=bus)
result = collector.run("What is 2+2?")
trace = collector.last_trace  # Rich trace with steps + messages

last_trace property

Return the trace from the most recent run().

run(input, context=None, **kwargs)

Execute the wrapped agent and record a trace.

TraceStore

Append-only SQLite store for interaction traces.

close()

Close the underlying SQLite connection.

count()

Return the total number of stored traces.

get(trace_id)

Retrieve a trace by id, or None if not found.

list_traces(*, agent=None, model=None, outcome=None, since=None, until=None, limit=100)

Query traces with optional filters.

save(trace)

Persist a complete trace with all its steps.

trace_id is a primary key: saving a second, different trace under an existing id raises sqlite3.IntegrityError (the external-corpus adapter relies on this to surface duplicate record ids). The server avoids re-saving the same trace by keeping the TraceCollector the single writer — see server/app.py — rather than swallowing collisions here.

search(query, *, agent=None, limit=20)

Full-text search across traces. Optionally filter by agent.

subscribe_to_bus(bus)

Subscribe to TRACE_COMPLETE events on bus.

update_feedback(trace_id, score)

Update the feedback score for a trace.

Returns True if the trace was found and updated, False otherwise.