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.

class AgentTrace(request, plan, reply='', conversation_id='')

Bases: object

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

Parameters:

• request (str)

• plan (list[dict])

• reply (str)

• conversation_id (str)

class AgentTraces(traces=<factory>)

Bases: object

The harvested corpus plus the teacher views the distillers consume.

Parameters:

traces (list[AgentTrace])

requests(*, min_steps=0)

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

Parameters:

min_steps (int)

Return type:

list[str]

tool_specs()

Infer tool specs from observed argument usage.

Return type:

list[ToolSpec]

call_teacher()

Return a distill_tool_caller teacher over the first tool call.

Return type:

Any

plan_teacher()

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

Return type:

Any

parse_conversation(doc)

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

Parameters:

doc (dict)

Return type:

list[AgentTrace]

harvest_agent_traces(directory=None)

Read every stored mixle-agent conversation and return the trace corpus (skips unreadable files).

Parameters:

directory (str | Path | None)

Return type:

AgentTraces