mixle.substrate.harness module

Application harnesses around a configured reasoner.

A Harness wraps a Reasoner with input validation, an immutable per-harness action whitelist, secret-redaction guardrails applied at every boundary (input, action evidence, escalation payload, retained trace), and an optional escalation callback. Each request returns a HarnessResult whose status is refused, answered, or escalated.

support_triage_harness and monitoring_harness provide ready-made templates. register_harness and find_harnesses store harnesses as scoped substrate artifacts so teams can discover reusable shells.

class HarnessResult(status, answer=None, reason='', investigation=None, redactions=0)[source]

Bases: object

One request’s outcome: which gate decided (refused/answered/escalated), and the evidence.

Parameters:

  • status (str)

  • answer (str | None)

  • reason (str)

  • investigation (Any)

  • redactions (int)

as_dict()[source]

Return a JSON-serializable harness result.

Return type:

dict[str, Any]

class Harness(reasoner, *, name, description='', validate=None, allowed_kinds=None, escalate=None, min_confidence=0.15, on_result=None)[source]

Bases: object

Schema + whitelist + guardrails + escalation around a reasoner (see module docstring).

Parameters:

  • reasoner (Reasoner) – the configured Reasoner (answerer + substrate + skills + actions).

  • description (str) – identity, used by the registry.

  • validate (Callable[[str], str | None] | None) – (request) -> None | str – return an error string to REFUSE the request before any model runs (the input schema, as a callable so any validator plugs in).

  • allowed_kinds (tuple[str, ...] | None) – action kinds this harness may fire (whitelist; None = all).

  • escalate (Callable[[str, Any], str] | None) – (request, result) -> str – called on abstention with the REDACTED request and a redacted Investigation; its return is the escalated answer handed back (e.g. a ticket id). None = abstentions surface as ‘escalated’ with no handler note.

  • min_confidence (float) – the answer bar (passed through to ask).

  • on_result (Callable[[HarnessResult], None] | None) – optional UI hook, called with every HarnessResult (fire-and-forget).

  • name (str)

  • description

Action-view immutability: reasoner._actions is a shared, mutable structure – other Harness instances built from the same reasoner, or a later reasoner.add_action() call, can change it at any time. So that one harness’s whitelist can never be corrupted by another harness’s construction, or bypassed by a later add_action(), a Harness never mutates reasoner._actions and never re-reads reasoner.actions after __init__: it snapshots its own immutable action view – the whitelist-filtered (or, with allowed_kinds=None, full) action list, each action wrapped to redact its own evidence – exactly once, at construction time, and every request the harness ever serves uses only that view. Attach every action a harness should be able to use to the reasoner BEFORE constructing that harness; reasoner.add_action() calls (or another harness’s construction) after that point affect only the shared reasoner and any harnesses built afterward, never one already built. The frozen view is available for inspection as harness.actions.

property actions: tuple[Action, ...]

This harness’s own immutable, redaction-wrapped action view (frozen at construction).

handle(request)[source]

Run one request through every gate: schema -> guardrails -> reasoner -> escalation.

Parameters:

request (str)

Return type:

HarnessResult

support_triage_harness(substrate, answerer, *, escalate=None, max_chars=2000)[source]

Support triage: retrieve-only over the team’s knowledge, refuse empty/oversized requests, escalate anything the knowledge base cannot support – the canonical ‘never guess at a customer’.

Parameters:
Return type:

Harness

monitoring_harness(reasoner, *, escalate=None)[source]

Monitoring/alerting: compute + simulate allowed (run checks, what-ifs), no delegation out.

Parameters:
Return type:

Harness

register_harness(substrate, harness, *, scope='local')[source]

Index a harness on the substrate as a scoped artifact – discoverable and shareable (P-scoped).

Parameters:

  • substrate (Substrate)

  • harness (Harness)

  • scope (str)

Return type:

str

find_harnesses(substrate, query='', *, scope=None)[source]

Discover registered harnesses (optionally by query / scope). Returns their manifests.

Parameters:

  • substrate (Substrate)

  • query (str)

  • scope (str | None)

Return type:

list[dict[str, Any]]