mixle.task.structured_out module

solve_structured – replace rigid code that returns a DICT, field by field, honestly.

The structured-output shape of the solve loop: teacher(x) -> {"field": value, ...} with a consistent schema (an enricher, a triager, a quote builder). Rather than inventing new machinery, each output field decomposes onto the shape that already carries guarantees:

• a categorical/string field -> a solve() classifier (conformal singleton);

• a numeric field -> a solve_regression() student (conformal interval + the caller’s tol precision rule – required per numeric field).

The composition rule is strict: the input is answered locally ONLY when every field’s sub-solution answers locally; one unsure field escalates the whole request to the teacher (harvested), so a locally-returned dict never contains a guessed field. The teacher is called exactly once per training example – per-field sub-teachers are lookups over that single pass.

improve() pushes each harvested (input, dict) down into every field’s own harvest buffer and runs each sub-solution’s anti-regression improve. No structured-level OOD gate yet (the classifier fields’ own gates are off here to avoid redundant vetoes) – noted, not hidden.

class StructuredSolution(fields_cat, fields_num, teacher, n_requests=0, n_escalated=0, harvested_inputs=<factory>, harvested_outputs=<factory>)

Bases: object

Per-field calibrated students in front of the dict-valued routine they replace.

Parameters:

• fields_cat (dict[str, Solution])

• fields_num (dict[str, RegressionSolution])

• teacher (Callable[[...], Any])

• n_requests (int)

• n_escalated (int)

• harvested_inputs (list)

• harvested_outputs (list)

fields_cat: dict[str, Solution]

fields_num: dict[str, RegressionSolution]

teacher: Callable[[...], Any]

n_requests: int = 0

n_escalated: int = 0

harvested_inputs: list

harvested_outputs: list

property schema: dict[str, str]

try_local(x)

The fully-decided output dict, or None when ANY field is unsure (= must escalate).

Parameters:

x (Any)

Return type:

dict[str, Any] | None

report()

Return type:

dict[str, Any]

save(path)

Persist every field’s sub-artifact under one directory; load() restores the whole schema.

Parameters:

path (str)

Return type:

str

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

Reconstitute a serving StructuredSolution (fields serve locally; escalation runs teacher).

Parameters:

• path (str)

• teacher (Callable[[...], Any])

• device (str)

Return type:

StructuredSolution

improve()

Push the harvested dicts down into every field’s buffer; each sub improves anti-regressively.

Return type:

bool

solve_structured(teacher, inputs, *, tol=None, alpha=0.1, prelabeled=None, seed=0, **sub_kw)

Replace a dict-valued routine with per-field calibrated students (see module docstring).

Parameters:

• teacher (Callable[[...], Any]) – teacher(x) -> dict with a consistent schema; called once per example input.

• inputs (Sequence[Any]) – example inputs (text or dict/tuple records).

• tol (dict[str, float] | float | None) – the precision requirement for numeric fields — a scalar for all, or {field: tol}. Required when the schema has numeric fields.

• alpha (float) – shared miscoverage level for every field’s calibration.

• prelabeled (tuple[Sequence[Any], Sequence[dict]] | None) – already-teacher-labeled (inputs, output_dicts) — typically harvested escalations from a serving deployment — fanned down into every field’s TRAINING split only, never calibration (each sub-solution’s guarantee stays a fresh split of inputs). The schema stays authoritative from the inputs pass; a pair missing a field is simply skipped for that field.

• **sub_kw (Any) – knobs forwarded to every sub-solve (epochs, hidden, dim, …).

• seed (int)

• **sub_kw

Return type:

StructuredSolution