mixle.substrate.act module

Action-based investigation over retrieve, compute, simulate, and create steps.

investigate() accepts a question and a set of Action objects. It scores actions by relevance per unit cost, executes them under an optional budget, accumulates evidence fragments, and returns an Investigation containing either an answer or an abstention.

Each action is a small adapter around run(question) -> list[str] plus cost and description metadata. Helper builders adapt substrate retrieval, registered skills, simulators, and creators into the same action protocol.

class Action(name, kind, run, cost=1.0, description='', base_score=0.0)[source]

Bases: object

One evidence-acquiring move: run it on a question, get back evidence fragments, at a cost.

Parameters:
name: str
kind: str
run: Callable[[str], list[str]]
cost: float = 1.0
description: str = ''
base_score: float = 0.0
class Step(action, kind, fragments, cost, score, relevance=0.0)[source]

Bases: object

A fired action and what it yielded – the audit trail behind an investigated answer.

Parameters:
action: str
kind: str
fragments: list[str]
cost: float
score: float
relevance: float = 0.0
class Investigation(question, answer, abstained, confidence, steps=<factory>, note='', factuality=None, proposal=None)[source]

Bases: object

A cited answer (or abstention) plus the sequence of actions that acquired its evidence.

Parameters:
question: str
answer: str | None
abstained: bool
confidence: float
steps: list[Step]
note: str = ''
factuality: Any = None
proposal: Any = None
property evidence: list[str]
property spent: float
trace()[source]

The actions taken, in order – the provenance the answer must be checkable against.

Return type:

list[dict[str, Any]]

as_dict()[source]
Return type:

dict[str, Any]

relevance_of(action, question)[source]

How on-topic an action is for a question (lexical overlap + its base floor), ignoring cost.

Parameters:

  • action (Action)

  • question (str)

Return type:

float

score_action(action, question)[source]

EIG-per-cost proxy: lexical relevance of the action to the question, divided by its cost.

This heuristic can be replaced with a learned or calibrated expected-information-gain estimate. Retrieval-style actions carry a base_score floor because retrieval is always at least weakly informative.

Parameters:

  • action (Action)

  • question (str)

Return type:

float

investigate(question, actions, answerer, *, budget_cost=None, min_evidence=1, min_confidence=0.15, target_confidence=None, max_actions=None, scorer=None, telemetry=None)[source]

Answer question by firing evidence-acquiring actions under a cost budget, or abstain.

Actions are ordered by scorer (default score_action(), EIG-per-cost) and fired highest-first. The loop stops early once it holds at least min_evidence fragments and confidence clears target_confidence (default: min_confidence). It also stops at the cost budget or max_actions. scorer can be replaced with a learned acquisition policy such as mixle.inference.learn_action_policy(). The answerer is called only when the evidence clears the bar. The returned Investigation carries the ordered action trace as provenance, and each fired action can emit telemetry for later policy learning.

Parameters:
Return type:

Investigation

retrieve_action(substrate, *, name='retrieve', k=6, scope=None, cost=1.0, min_score=0.0)[source]

A RETRIEVE action over a Substrate (the always-available floor action).

min_score filters out weak matches: a tiny embedder returns SOMETHING for every query, so a positive floor keeps genuinely-irrelevant items from becoming false evidence. It defaults to 0.0 (keep everything) but a small positive value makes retrieval honest on a noisy index.

Parameters:
Return type:

Action

compute_action(skill, *, name=None, cost=1.0, description=None)[source]

A COMPUTE action that runs a Skill and reports its result.

Parameters:
Return type:

Action

simulate_action(simulator, field_index, scenario, *, name=None, cost=2.0, description='')[source]

A SIMULATE action that runs a what-if scenario and reports the simulated outcome mean.

Parameters:
Return type:

Action

create_action(build, *, name='create', cost=4.0, description='', report=None)[source]

A CREATE action that builds a model / dataset on demand and reports what it made.

build(question) -> artifact fits/synthesizes something (e.g. via mixle.inference.create() or mixle.inference.synthesize()); report renders the artifact to an evidence fragment (default: a certificate/guarantee summary when present, else repr). Creation is the most expensive action, so it defaults to cost=4 – the reasoner reaches for it only when cheaper retrieve/compute/simulate actions cannot answer.

Parameters:
Return type:

Action

delegate_action(delegate, *, name='delegate', cost=8.0, description='', priced=True)[source]

A DELEGATE action that hands the question to an external worker (pool job / remote tool / agent).

delegate(question) -> answer is any priced external capability. This is the reasoner’s most expensive move (default cost=8) and the escalation of last resort: it fires only when nothing local clears the bar, honoring the 99%-local topology. priced=True records that the call incurs real spend (the pool/interop layers own the actual budget-reject + confirm rails).

Parameters:
Return type:

Action

action_features(action, question)[source]

The features a learned acquisition policy keys on: the action’s kind, cost, and query overlap.

Parameters:

  • action (Action)

  • question (str)

Return type:

dict[str, Any]