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')[source]

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)

max_chars: int = 2000
max_items: int = 20
shape: str = 'passages'
class ContextPacket(task, items=<factory>, scores=<factory>, budget=<factory>, used_chars=0, n_candidates=0, texts=<factory>, compressed=False)[source]

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 = 0
n_candidates: int = 0
texts: list[str]
compressed: bool = False
render(*, header=True)[source]

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

Parameters:

header (bool)

Return type:

str

preservation()[source]

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()[source]

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

Return type:

list[dict[str, Any]]

as_dict()[source]
Return type:

dict[str, Any]

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

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 tiny 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)[source]

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:
Return type:

str