mixle.system.spend module

Unified budget ledger for subsystem and query-level spending.

One cost total is summed across query paths: cascade or router tiers (frontier_calls), oracle-scored search loops (oracle_calls), and wall-clock or dollar cost wherever those are tracked. System.answer carries the incremental Spend of the current call plus the running total_spend on every receipt, and treats budget as a hard ceiling.

class Spend(frontier_calls=0, oracle_calls=0, wall_ms=0.0, dollars=0.0)

Bases: object

A summable cost total. total_units() is the scalar figure budget= is checked against.

Every dimension is checked on construction, and therefore again after each __add__() and after deserialization, because a receipt is a ledger: work only ever consumes budget. Without these invariants Spend(frontier_calls=-5).total_units() returned -5, so doing work could hand budget back, and a NaN wall_ms serialized as an ordinary receipt field while making every hard-ceiling comparison against it false – failing open on the check meant to stop overspending.

Parameters:

• frontier_calls (int)

• oracle_calls (int)

• wall_ms (float)

• dollars (float)

total_units()

The scalar cost a budget= integer is measured against.

Currently frontier_calls + oracle_calls – the two countable, per-call costs the existing routes measure budget in. wall_ms and dollars are carried and reported on every receipt but are not yet priced into the hard-ceiling check; extend this method when a concrete dollar cost model is introduced.

Return type:

float

to_dict()

Serialize the spend ledger into primitive numeric fields.

Return type:

dict[str, float | int]