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>)[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