mixle.task.traces module

Harvest real agent-session traces – turn what your agent already did into training data.

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 are exactly the teacher traces the agentic distillers need – no synthetic teacher, no labeling budget: the agent’s own history teaches the tiny models:

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 (its plan), plus the final text reply. Tool specs are inferred honestly from usage: a tool’s argument set is the union of keys ever passed; required is the keys present in EVERY observed call. The teachers are lookup tables over the harvested requests – they never call a model, so distilling from history is free and deterministic.

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

Bases: object

One request -> what the agent did: the ordered tool calls and the final text reply.

Parameters:

• request (str)

• plan (list[dict])

• reply (str)

• conversation_id (str)

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

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 ToolSpecs from observed usage: args = union of keys, required = keys in EVERY call.

Return type:

list[ToolSpec]

call_teacher()

A distill_tool_caller teacher: request -> the FIRST tool call the agent made (or no-op).

Return type:

Any

plan_teacher()

A distill_planner / sft_planner teacher: request -> the agent’s full tool-call plan.

Return type:

Any

parse_conversation(doc)

Split one stored conversation into traces: user request -> assistant tool calls until the next user turn.

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