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. A backend is third-party code, so its response is not taken on trust either: submit() settles it against the job it was given (identity, status vocabulary, finite economics, realized cost within budget) before the caller ever sees ok == True.

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:
POOL_STATUSES = frozenset({'done', 'error', 'rejected'})

The closed status vocabulary a PoolResult may use.

submit() refuses anything outside this set rather than letting an unrecognized status ride through: PoolResult.ok only tests equality with "done", so an unknown status would read as “not ok” while carrying none of the error handling a real failure gets.

class PoolResult(job_id, status, artifact=None, cost=0.0, duration_s=0.0, reason='', telemetry_error='')[source]

Bases: object

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

Parameters:
property ok: bool

Whether the job completed successfully.

property telemetry_recorded: bool

Whether this submission’s pool_job event actually reached the telemetry sink.

Separate from ok: the job itself can succeed while its record is lost, and the two failures need different responses – a dropped event means the spend and duration behind this result are missing from whatever ledger reconciles them.

class Backend(*args, **kwargs)[source]

Bases: Protocol

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

submit(job)[source]

Execute job and return a PoolResult.

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)

submit(job)[source]

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)[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). A telemetry sink that fails does not fail the job – but it does not disappear either: the reason lands on result.telemetry_error (and result.telemetry_recorded goes false), so a caller reconciling spend against that event stream can see which rows are missing from it.

The confirm gate demands the literal Boolean True, not merely a truthy value: confirm is routinely threaded through JSON payloads, CLI flags and form fields, where the string "false" (or "0", or an empty-but-present marker object) is a perfectly ordinary way to spell “no” – and every one of those is truthy in Python. Anything other than True therefore leaves the job unconfirmed and rejected rather than silently authorizing billable execution.

job.est_cost must be finite and non-negative and job.budget must be non-negative (inf allowed, meaning “no ceiling”) – raises ValueError otherwise. Costs are a dollar estimate, never a credit: a NaN or negative value would defeat the comparison below rather than be caught by it (NaN compares false against everything, so est_cost > budget silently passes; a negative value can “refund” budget that was never spent), so both are rejected outright rather than routed through the ordinary rejected-PoolResult path.

The backend’s response is checked too, by _settle(): it must be a PoolResult for this exact job, with a status in POOL_STATUSES and a finite non-negative cost and duration_s that settles within job.budget. A response failing any of those is returned as an "error" result instead of being passed through, so .ok is never true for work whose identity or economics do not check out. A backend that raises rather than responding is likewise an "error" result naming the backend and the exception, not an exception out of submit: the return contract and the telemetry guarantee both have to hold on the path where the pool is down, which is the path an operator most needs a record of.

Submission is NOT idempotent and deliberately keeps no durable job state: submitting the same PoolJob twice runs it twice, even when its id is a caller-supplied constant rather than the default fresh UUID (id is a correlation handle for telemetry and settlement, not a deduplication key). A caller whose work is irreversible or billable – and any orchestrator that retries after a crash or a lost response – must therefore carry its own idempotency key and committed-result lookup; that needs durable storage, and this library layer does no I/O.

Parameters:

  • job (PoolJob)

  • backend (Backend | None)

  • confirm (bool)

  • telemetry (Any)

Return type:

PoolResult