mixle.fault module

Degradation policy with named failure modes for receipts.

Subsystem failures should not silently serve degraded answers as ordinary successes. with_fallback() runs a primary path and, on exception, runs a named fallback. The result records whether the primary path succeeded or which degradation mode produced the fallback value. abstain_on_timeout() and route_past() apply the same receipt discipline to timeout abstention and multi-tier routing.

The named modes are teacher_down (fall back to captured or store-only reasoning; see mixle.system.System.answer()), store_down (reason without accumulated knowledge; see mixle.system.System.ingest()), oracle_timeout (abstain or escalate rather than guess), and model_error (route past the failing tier to the next one). The timeout and routing helpers are reusable fault-boundary primitives.

class DegradedResult(value, degraded, mode=None, reason=None)[source]

Bases: object

The outcome of a fault-boundary call: a value, whether it came from a fallback, and, if so, why.

Parameters:

  • value (Any)

  • degraded (bool)

  • mode (str | None)

  • reason (str | None)

to_receipt_fields()[source]

Return degraded_mode and degraded_reason receipt fields.

Return type:

dict[str, Any]

with_fallback(fn, fallback, *, mode)[source]

Run fn(); on any exception, run fallback(exc) instead and flag the result under mode.

If fallback itself raises, that exception propagates. A fallback that cannot produce a value is a real failure, not a second implicit fallback.

Parameters:
Return type:

DegradedResult

abstain_on_timeout(fn, *, timeout_error=TimeoutError)[source]

oracle_timeout mode: run fn(); if it raises timeout_error, abstain (value=None) rather than guess. Other exceptions propagate.

Parameters:
Return type:

DegradedResult

route_past(tiers, *, names=None)[source]

model_error mode: try each tier in order; a raising tier is skipped (not fatal) in favor of the next. The result is degraded unless the first tier answers cleanly. Raises the last tier’s exception if every tier fails.

Parameters:
Return type:

DegradedResult