mixle.pool package

Pool execution primitives for offloading selected units of work.

The pool API keeps local execution as the default. A job is sent to a backend only when a planner or caller provides a reason, an estimated cost, and a budget. The default LocalBackend executes the same protocol in-process, so workflows can use the pool abstraction before a remote GPU backend exists.

class PoolJob(run, kind='block', reason='', est_cost=0.0, budget=inf, inputs=<factory>, id=<factory>)[source]

Bases: object

A runnable unit of work destined for local-or-pool execution, with its reason and budget.

run is any callable returning an artifact (a fitted model, an index, a dataset). est_cost is the estimated dollar cost the economics assigned; budget is the ceiling the submitter set. reason is the placement justification the planner produced (“8.2 TFLOP gradient residual”).

Parameters:
run: Callable[[], Any]
kind: str = 'block'
reason: str = ''
est_cost: float = 0.0
budget: float = inf
inputs: dict[str, Any]
id: str
class PoolResult(job_id, status, artifact=None, cost=0.0, duration_s=0.0, reason='')[source]

Bases: object

The outcome of a pool job: the artifact that round-trips home, plus realized cost/timing.

Parameters:
job_id: str
status: str
artifact: Any = None
cost: float = 0.0
duration_s: float = 0.0
reason: str = ''
property ok: bool
class Backend(*args, **kwargs)[source]

Bases: Protocol

Executes a PoolJob. Real backends set billable=True and honor the confirm gate.

billable: bool
submit(job)[source]
Parameters:

job (PoolJob)

Return type:

PoolResult

class LocalBackend(clock=None)[source]

Bases: object

The pool degraded to this machine: runs the job in-process, free, no confirm needed.

This is what a user with no remote pool configured gets: the abstraction works end-to-end and every result is a real local artifact. clock is injectable for deterministic timing in tests.

Parameters:

clock (Callable[[], float] | None)

billable = False
submit(job)[source]
Parameters:

job (PoolJob)

Return type:

PoolResult

submit(job, backend=None, *, confirm=False, telemetry=None)[source]

Submit job to backend (default LocalBackend), enforcing budget + confirm rails.

A job whose est_cost exceeds its budget is REJECTED before running. A BILLABLE backend (a real GPU pool) additionally requires confirm=True – spend is never incurred implicitly. Every submission emits a pool_job telemetry event (features + realized outcome).

Parameters:

  • job (PoolJob)

  • backend (Backend | None)

  • confirm (bool)

  • telemetry (Any)

Return type:

PoolResult

Submodules