mixle.task.traces module

Harvest stored agent-session traces for task distillation.

The mixle-agent server persists every conversation (~/.mixle-agent/conversations/*.json) with the full message stream, including the tool_use blocks the frontier model emitted. Those traces can serve as deterministic teachers for agentic distillation workflows:

traces = harvest_agent_traces()                       # or (dir=...) for a custom store
tools  = traces.tool_specs()                           # ToolSpecs inferred from observed usage
tc     = distill_tool_caller(traces.call_teacher(), traces.requests(), tools)
gp     = sft_planner(traces.plan_teacher(), traces.requests(min_steps=1), tools)

Each trace pairs a user request with the ordered tool calls the assistant made before the next user turn, plus the final text reply. Tool specs are inferred from observed usage: a tool’s argument set is the union of keys ever passed, and required is the keys present in every observed call. The teachers are lookup tables over harvested requests; they do not call a model.

exception TraceFormatError[source]

Bases: ValueError

Raised when a stored trace row violates the conversation schema.

exception AmbiguousTraceError[source]

Bases: LookupError

Raised when one request text has multiple conflicting harvested executions.

class TraceRejection(source, location, reason)[source]

Bases: object

A file or row rejected during harvesting, with enough location to repair it.

Parameters:
class AgentTrace(request, plan, reply='', conversation_id='', trace_id='', outcomes_verified=False)[source]

Bases: object

One request, ordered tool calls, and final text reply.

Parameters:
class AgentTraces(traces=<factory>, rejections=<factory>)[source]

Bases: object

The harvested corpus plus the teacher views the distillers consume.

Parameters:

  • traces (list[AgentTrace])

  • rejections (list[TraceRejection])

requests(*, min_steps=0)[source]

The request texts (optionally only those whose plan has at least min_steps calls).

Parameters:

min_steps (int)

Return type:

list[str]

by_id(trace_id)[source]

Return one execution by its stable harvested ID.

Parameters:

trace_id (str)

Return type:

AgentTrace

tool_specs()[source]

Infer tool specs from observed argument usage.

Return type:

list[ToolSpec]

call_teacher()[source]

Return a distill_tool_caller teacher over the first tool call.

Return type:

Any

plan_teacher()[source]

Return a planner teacher over the full harvested tool-call plan.

Return type:

Any

parse_conversation(doc, *, source_id='', rejections=None)[source]

Split one stored conversation into request-to-tool-plan traces.

Parameters:

  • doc (dict)

  • source_id (str)

  • rejections (list[TraceRejection] | None)

Return type:

list[AgentTrace]

harvest_agent_traces(directory=None)[source]

Read stored conversations, preserving traces and a ledger of rejected files/rows.

Parameters:

directory (str | Path | None)

Return type:

AgentTraces