mixle.substrate.context module

Budgeted, provenanced context packets assembled from the substrate.

A ContextPacket is a task-specific view of selected substrate items: the task, items in relevance order, rendered text, budget, and provenance for the included evidence. A ContextBudget describes how much context a target can accept and in what shape.

Assembly combines substrate retrieval with greedy budgeted selection. The most relevant items are packed until the budget is reached, and an optional telemetry event records the budget, usage, and number of selected items.

class ContextBudget(max_chars=2000, max_items=20, shape='passages')

Bases: object

What a target can take – the DeviceSpec of context. shape hints the rendering style.

Parameters:

• max_chars (int)

• max_items (int)

• shape (str)

class ContextPacket(task, items=<factory>, scores=<factory>, budget=<factory>, used_chars=0, n_candidates=0, texts=<factory>, compressed=False)

Bases: object

A budgeted, provenanced view of the substrate assembled for one target + task.

texts holds the text actually used per item – the full item surface, or (when the packet was compressed) an extractive summary that keeps only the query-relevant sentences. preservation receipts how much of each item’s query-relevant content survived, so compression is measured, not trusted.

Parameters:

• task (str)

• items (list[SubstrateItem])

• scores (list[float])

• budget (ContextBudget)

• used_chars (int)

• n_candidates (int)

• texts (list[str])

• compressed (bool)

render(*, header=True)

The assembled context string the target consumes (respecting the budget shape).

Parameters:

header (bool)

Return type:

str

preservation()

Per item, the fraction of the task’s query terms retained in the used text (1.0 = all kept).

The receipt for compression: a value near 1.0 means the summary kept what the query cares about; a low value flags an item whose relevant content was squeezed out.

Return type:

list[float]

property compression_ratio: float

Used chars / full chars over the selected items (1.0 = uncompressed).

provenance()

Where every included piece came from – ids, kinds, sources, relevance scores.

Return type:

list[dict[str, Any]]

as_dict()

Return a JSON-serializable context-packet summary.

Return type:

dict[str, Any]

to_knowledge_dict(*, id, project_id, target_kind, target_id=None, expected_output_schema=None, factuality=None)

Return a plain dict shaped like mixle_knowledge.contracts.ContextPacket.

The exported fields cover id, project_id, task, target_kind, target_id, token and byte budgets, evidence item identifiers, constraints, citations, expected_output_schema, and payload. Constructing a validated pydantic object is the receiving package’s responsibility; core mixle intentionally keeps this as a dependency-free dictionary so platform contract packages can depend on core rather than the reverse.

When factuality is a FactualityReceipt, it is included in payload["factuality"] so receivers can inspect grounding metadata before trusting the packet.

Parameters:

• id (str)

• project_id (str)

• target_kind (str)

• target_id (str | None)

• expected_output_schema (dict[str, Any] | None)

• factuality (Any)

Return type:

dict[str, Any]

assemble_context(substrate, task, *, budget=None, kind=None, scope=None, compress=False, telemetry=None)

Assemble the best-affordable ContextPacket for task from substrate.

Retrieves relevant items (Substrate.search()), then packs them in descending relevance until the character budget or item cap is reached – always keeping at least the single most relevant item so a small budget still yields something. With compress=True, an item too large to fit whole is extractively summarized to its query-relevant sentences instead of dropped; packet.preservation() reports what was kept. Emits a context event when telemetry is supplied.

Parameters:

• substrate (Substrate)

• task (str)

• budget (ContextBudget | None)

• kind (str | None)

• scope (str | None)

• compress (bool)

• telemetry (Any)

Return type:

ContextPacket

compress_text(text, task, max_chars)

Extractive, torch-free summary of text keeping the sentences most relevant to task, within max_chars (the standalone compressor used by assemble_context() with compress=True).

Parameters:

• text (str)

• task (str)

• max_chars (int)

Return type:

str

class ReceiverProfile(name, max_chars=2000, max_items=20, shape='passages', compress=False)

Bases: object

A named receiver’s capacity – what assemble_for_receivers() budgets and shapes for it.

A frontier LM and a local student are not the same target: the LM affords a large, prose-shaped context; the student needs a small, feature-shaped one. ReceiverProfile names that difference so it is set once per receiver, not re-derived ad hoc at every call site.

Parameters:

• name (str)

• max_chars (int)

• max_items (int)

• shape (str)

• compress (bool)

to_budget()

Convert this receiver profile to a context budget.

Return type:

ContextBudget

assemble_for_receivers(substrate, task, receivers, *, kind=None, scope=None, telemetry=None)

Assemble ONE task-conditioned ContextPacket per named receiver – the concrete receiver-conditioned compression path.

Two receivers reading the same substrate for the same task get genuinely different renderings: budget, shape, and, via compress, which sentences survive. The result is not the same blob truncated to fit each consumer.

packets = assemble_for_receivers(substrate, task, [

ReceiverProfile(“frontier_llm”, max_chars=2000, shape=”passages”), ReceiverProfile(“local_student”, max_chars=200, shape=”features”, compress=True),

]) packets[“frontier_llm”].render(), packets[“local_student”].render()

Parameters:

• substrate (Substrate)

• task (str)

• receivers (Sequence[ReceiverProfile])

• kind (str | None)

• scope (str | None)

• telemetry (Any)

Return type:

dict[str, ContextPacket]