mixle.experimental.typed_runtime.measurement module

Measured work catalogs and effective-context vocabulary for runtime planning.

class EffectiveContextMeasurement(source_horizon_tokens=None, materialized_tokens=0, attended_tokens=0, evidence_nodes=0, evidence_edges=0, context_actions=0, retrieval_actions=0, generation_actions=0, verification_actions=0, tool_calls=0, latency_seconds=0.0, monetary_cost=0.0, verified_claim_fraction=None, stopped_reason=None)

Bases: object

Receipt separating source horizon from bounded active computation.

source_horizon_tokens may be unknown for graph/database/tool sources. It is never inferred from attended tokens. Generated context is counted separately so it cannot be mislabeled as retrieved evidence.

Parameters:

• source_horizon_tokens (int | None)

• materialized_tokens (int)

• attended_tokens (int)

• evidence_nodes (int)

• evidence_edges (int)

• context_actions (int)

• retrieval_actions (int)

• generation_actions (int)

• verification_actions (int)

• tool_calls (int)

• latency_seconds (float)

• monetary_cost (float)

• verified_claim_fraction (float | None)

• stopped_reason (str | None)

property active_to_source_ratio: float | None

Materialized/source ratio when the source horizon is known and nonzero.

as_dict()

Return the complete measurement vocabulary as JSON-compatible data.

Return type:

dict[str, Any]

class MeasurementCatalog(records=None)

Bases: object

In-memory measured-cost catalog used by the experimental compiler.

Medians make a small catalog robust to one noisy timing observation. A persistent/versioned catalog is deliberately deferred until the receipt schema has survived real backends.

Parameters:

records (Iterable[WorkMeasurement] | None)

property records: tuple[WorkMeasurement, ...]

The measurements, as a detached read-only view.

This was a public list, so a caller could append a fabricated measurement, delete a real one, or rewrite the catalog the compiler reads its cost estimates from – all without going through record(), which is the only place the type is checked (MXR-080-1878). The catalog is append-only evidence; record/extend are the way in.

record(measurement)

Append one immutable measurement.

Parameters:

measurement (WorkMeasurement)

Return type:

None

extend(measurements)

Append several measurements.

Parameters:

measurements (Iterable[WorkMeasurement])

Return type:

None

matching(node_type, update_kind, backend)

Return exact-key measurements.

Parameters:

• node_type (str)

• update_kind (UpdateKind)

• backend (str)

Return type:

tuple[WorkMeasurement, …]

estimate(node_type, update_kind, backend)

Return a median measured cost, or None when no matching evidence exists.

Parameters:

• node_type (str)

• update_kind (UpdateKind)

• backend (str)

Return type:

CostEstimate | None

as_dict()

Return a JSON-compatible catalog.

Return type:

dict[str, Any]

class WorkMeasurement(node_type, update_kind, backend, wall_time_seconds, compute_units=0.0, communication_bytes=0, peak_memory_bytes=0, observations=0.0, tokens=0, model_evaluations=0, operation_count=0, bytes_read=0, bytes_written=0, collective_bytes=0, staleness_steps=0, run_id=None, extra=<factory>, work_counter_semantics=CounterSemantics.INCREMENTAL, peak_memory_semantics=CounterSemantics.HIGH_WATER_MARK, staleness_semantics=CounterSemantics.HIGH_WATER_MARK)

Bases: object

One measured execution of a typed node operation.

Parameters:

• node_type (str)

• update_kind (UpdateKind)

• backend (str)

• wall_time_seconds (float)

• compute_units (float)

• communication_bytes (int)

• peak_memory_bytes (int)

• observations (float)

• tokens (int)

• model_evaluations (int)

• operation_count (int)

• bytes_read (int)

• bytes_written (int)

• collective_bytes (int)

• staleness_steps (int)

• run_id (str | None)

• extra (dict[str, Any])

• work_counter_semantics (CounterSemantics)

• peak_memory_semantics (CounterSemantics)

• staleness_semantics (CounterSemantics)

as_dict()

Return a JSON-compatible receipt.

Return type:

dict[str, Any]