mixle.task.catalog_router module

IC-10 tool/model catalog -> verified Router wiring (M3-core).

Every routable capability – a physics forward, an economic model, a climate projection, an external domain model (IC-7) – registers with the same uniform shape (CatalogEntry, IC-10) so a decomposer/router never special-cases a tool family. build_catalog_router() turns a flat list of entries into one calibrated Router tier per entry (cheapest first), falling through to a frontier/teacher callable exactly the way Cascade already escalates uncertain calls.

Local convention (not part of the frozen IC-10 shape, documented here because M3 owns the wiring): CatalogEntry.schema is a plain dict[str, Any] (IC-10 imposes no further shape on it), so a registrant MAY stash two well-known keys on it: "output" (the JSON-schema of what this entry produces, used for schema-compatibility matching in mixle.task.knowledge_routing) and "invoke" (a Callable[[dict], Any] that actually runs the tool/model given a request dict). Both are required by build_catalog_router(): the router returns a verified output, never an entry id standing in for an answer.

class CatalogCalibration(verified, trials, confidence=0.95)[source]

Bases: object

Held-out verifier outcomes used to gate a catalog capability.

Parameters:
property lower_bound: float

One-sided Clopper-Pearson lower confidence bound.

class CatalogEntry(id, schema, owner, cost=0.0, reliability=1.0, verifier=None)[source]

Bases: object

A routable capability: identity, its JSON schema, owning subsystem, cost, prior reliability, and an optional verifier (the IC-10 tuple).

IC-10 (notes/exec/contracts.md) freezes verifier as str | None – the name of the IC-6 verifier kind that gates this entry’s output. M3’s own algorithm (step 5: “attach each verifier; verified item ids resolve gaps”) needs to actually CALL a verifier, not just look one up by name, so this field is typed Any | None here and accepts either an IC-10-style string tag or a live IC-6 Verifier-shaped object (anything exposing .verify(claim, context)) – a thin, additive shim over the frozen contract, not a rename of it. Field names/order/defaults are otherwise identical to the frozen stub.

Parameters:
build_catalog_router(catalog, teacher, *, teacher_cost, calibration, min_verified_reliability)[source]

Build executable, schema-checked, verified tiers and one explicitly-priced frontier.

calibration supplies held-out verifier outcomes for every entry. A local tier is eligible only when its one-sided reliability lower bound clears min_verified_reliability; the entry’s caller-supplied reliability prior is documentary and never authorizes an answer.

Parameters:

  • catalog (list[CatalogEntry])

  • teacher (Any)

  • teacher_cost (float)

  • calibration (Mapping[str, CatalogCalibration])

  • min_verified_reliability (float)

Return type:

Router