mixle.system module¶

Facade for answering, ingesting knowledge, and improving a Mixle system.

The facade exposes three verbs: answer serves a query, ingest stores a model output as credence-weighted knowledge, and improve spends a budget on measured improvement. The shell is deliberately thin: answer routes to the configured teacher and attaches a receipt, ingest writes through the available store boundary, and improve promotes harvested answers into an explicit captured cache.

The Spend ledger treats budget as a hard ceiling measured in total_units(). A request that cannot afford the minimum-cost answer path is refused with the shortfall named on the receipt. Successful calls add incremental spend to System.total_spend, and receipts carry both incremental and running totals.

Named degraded modes from mixle.fault use the same verbs. answer can fall back to captured or store-only reasoning when the teacher raises (teacher_down), and ingest can acknowledge without accumulating when a store write raises (store_down). Both paths flag degraded_mode and degraded_reason on the returned receipt or report.

The cold-start loop harvests teacher-produced answers. improve promotes the harvest into a verbatim captured cache; answer checks that cache before spending. Capture only promotes after an explicit improve() call, so measured savings are attributable to improvement rather than implicit caching.

class SystemConfig(teacher, registry_dir=None, store=None, default_budget=1, scope='local')[source]

Bases: object

Configuration required to run a System.

Secrets such as endpoints and keys are read from the environment by from_env(); they are not hardcoded in the config object.

Parameters:

teacher (LLM | Callable[[...], str])
registry_dir (str | None)
store (Any)
default_budget (int)
scope (str)

classmethod from_env(*, store=None, registry_dir=None)[source]

Build a config whose teacher is an OpenAICompatLLM sourced entirely from env vars.

Reads MIXLE_TEACHER_BASE_URL (required), MIXLE_TEACHER_MODEL (required), and the optional MIXLE_TEACHER_API_KEY. Raises ValueError naming the missing variable rather than silently constructing an unusable teacher.

Parameters:

store (Any)
registry_dir (str | None)

Return type:

SystemConfig

class Query(text, task='', fingerprint=None, expected_output=None, scope='local')[source]

Bases: object

The typed problem contract for System.answer().

task and expected_output align with the mixle-knowledge ContextPacket contract’s task and expected_output_schema fields (see from_knowledge_dict()). scope is a Query-level routing boundary and is not inferred from the packet.

Parameters:

text (str)
task (str)
fingerprint (Any)
expected_output (dict[str, Any] | None)
scope (str)

classmethod from_knowledge_dict(packet, *, scope='local')[source]

Build a Query from a mixle-knowledge-shaped ContextPacket dict.

text comes from payload["rendered"]. task and expected_output map from the packet’s task and expected_output_schema. scope is supplied by the caller.

Parameters:

packet (dict[str, Any])
scope (str)

Return type:

Query

class System(config)[source]

Bases: object

Constructed from a SystemConfig; exposes answer/ingest/improve.

Parameters:: config (SystemConfig)

answer(query, *, budget=None)[source]

Thin shell: route straight to the teacher, wrap the reply in a minimal H-style receipt.

Checks the captured cache first (see improve()): an exact repeat of a query (same text, task, AND scope – two queries that merely share text but differ in task/scope are different questions and must not share a cache entry) already promoted by a prior improve() call is served free, no budget spent, captured=True.

budget is a hard ceiling (total_units): if it cannot afford even one frontier call, the request is refused – reply is None and the receipt names the exact shortfall – rather than silently answering over budget. A served answer’s cost is added to total_spend, which every receipt also carries as total_spend.

If the teacher call itself raises, this falls back to teacher_down degraded mode: answer from the store alone (a plain retrieval over config.store) when one is configured and has anything relevant, flagging degraded_mode="teacher_down" on the receipt; if there is no store (or nothing relevant in it), the failure is reported explicitly (status="failed"), never masked as a normal answer.

Parameters:

query (Query)
budget (int | None)

Return type:

tuple[str | None, dict[str, Any]]

ingest(model_output, *, source)[source]

Turn a model output into stored knowledge.

Uses the belief store when it is importable; otherwise records a plain substrate item rather than requiring optional knowledge-substrate components.

If the store write raises, this falls back to store_down degraded mode. The model output is acknowledged but not accumulated, and the report is flagged with degraded_mode="store_down".

Parameters:

model_output (str)
source (dict[str, Any])

Return type:

dict[str, Any]

improve(budget)[source]

Promote every harvested (query, reply) pair from answer() into the captured cache.

Reports that there is nothing to improve when nothing has been harvested yet. Otherwise this is the cold-start capture step: after this call, a repeat of a captured query is answered from the local cache (see answer()).

Parameters:: budget (int)
Return type:: dict[str, Any]