mixle.task.toolcall module

Distill single-step tool calling into a calibrated local model.

Tool calling decomposes into two problems the task spine already solves, composed under one gate:

• which tool (or none) – a calibrated classification student (solve() over the request text: conformal answer-or-escalate + optional OOD gate);

• the arguments – one token-level extractor per tool (distill_extractor()), distilled from the teacher’s own argument fills.

teacher(request) -> {"tool": name, "args": {...}} (or {"tool": None}) can be a frontier LLM behind mixle.task.llm, an agent loop, or a rule. The returned ToolCaller emits a call only when the selector is conformally confident and every required argument extracts. Anything else escalates to the teacher and is harvested for the next distillation round.

This covers single-step function calling. Multi-step planning is handled by the planner distillation surfaces.

class ToolSpec(name, args, required=None)

Bases: object

One callable tool: its name and the argument fields to extract from the request text.

Parameters:

• name (str)

• args (list[str])

• required (list[str] | None)

property required_args: list[str]

Return required argument names, defaulting to all declared arguments.

class ToolCaller(selector, extractors, tools, teacher, selection_agreement, n_requests=0, n_escalated=0, harvested=<factory>)

Bases: object

Distilled function caller with calibrated selection and argument extraction.

Parameters:

• selector (Solution)

• extractors (dict[str, Any])

• tools (dict[str, ToolSpec])

• teacher (Callable[[str], dict])

• selection_agreement (float)

• n_requests (int)

• n_escalated (int)

• harvested (list[tuple[str, dict]])

try_local(request)

Return the local decision, or None when the request must escalate.

This method does not call the teacher.

Parameters:

request (str)

Return type:

dict[str, Any] | None

report()

Return serving counts, escalation rate, and selector agreement diagnostics.

Return type:

dict[str, Any]

save(path)

Persist selector, per-tool extractors, and tool specs.

Parameters:

path (str)

Return type:

str

classmethod load(path, teacher, *, device='cpu')

Reconstitute a serving ToolCaller from save() output plus the teacher fallback.

Parameters:

• path (str)

• teacher (Callable[[str], dict])

• device (str)

Return type:

ToolCaller

distill_tool_caller(teacher, requests, tools, *, seed=0, selector_kw=None, extractor_kw=None)

Distill the teacher’s function-calling into a local selector plus per-tool argument extractors.

Parameters:

• teacher (Callable[[str], dict]) – teacher(request) -> {"tool": name-or-None, "args": {field: value}} — the frontier LLM / agent / rule currently doing the calling. It labels everything; it remains the fallback.

• requests (Sequence[str]) – example request texts covering the tools.

• tools (Sequence[ToolSpec]) – the tool specs (names + argument fields; required defaults to all).

• extractor_kw (dict | None) – knobs forwarded to solve() and distill_extractor().

• seed (int)

• selector_kw (dict | None)

• extractor_kw

Return type:

ToolCaller