mixle.pool.core module

Pool jobs, results, and backend protocol.

A PoolJob describes a runnable unit of work, its input manifest, the placement reason, estimated cost, and budget. A Backend executes the job and returns a PoolResult whose artifact can be used by the submitter locally.

The included LocalBackend runs jobs in-process and is useful for tests or systems without a remote pool. Billable backends must require explicit confirmation, and jobs whose estimated cost exceeds their budget are rejected before execution.

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

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)

• reason (str)

• est_cost (float)

• budget (float)

• inputs (dict[str, Any])

• id (str)

class PoolResult(job_id, status, artifact=None, cost=0.0, duration_s=0.0, reason='')

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)

• cost (float)

• duration_s (float)

• reason (str)

property ok: bool

Whether the job completed successfully.

class Backend(*args, **kwargs)

Bases: Protocol

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

submit(job)

Execute job and return a PoolResult.

Parameters:

job (PoolJob)

Return type:

PoolResult

class LocalBackend(clock=None)

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)

submit(job)

Run job in this process and wrap the outcome as a pool result.

Parameters:

job (PoolJob)

Return type:

PoolResult

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

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