Architecture

Components

• Worker → Transport → PullQueue → CommandDispatcher / DeficitScheduler / TaskRepository

• PullQueue — orchestrates heartbeat hooks, management commands, WDRR, and storage claims.

• DeficitScheduler — pure deficit ledger (credits per epoch, debit on claim, zero-out on empty priority).

• CommandDispatcher — per-worker_id FIFO of pulq.models.ManagementCommand.

• TaskRepository — protocol for enqueue + atomic claim + completion (default: pulq.storage.memory.InMemoryTaskRepository).

• Transport — protocol for request_work / report_completion (default: pulq.transport.local.LocalTransport).

Data models (pulq.models)

The package groups Pydantic types by concern:

• pulq.models.enums — TaskStatus, CommandType, NoWorkReason

• pulq.models.task — Task

• pulq.models.work — ManagementCommand, NoWork, NoPendingTask

• pulq.models.unions — WorkResponse and ClaimResult type aliases with discriminated union validation

• pulq.models.scheduler_config — DeficitSchedulerConfig (WDRR parameters; also re-exported from pulq.core.scheduler for convenience)

Wire formats are parsed with pulq.parsing using Pydantic’s TypeAdapter.

Discriminated unions

Work items returned from pulls use a type discriminator:

• task → pulq.models.Task

• command → pulq.models.ManagementCommand

• no_work → pulq.models.NoWork (null object instead of None)

Use pulq.parse_work_response() to validate untrusted data. Pydantic’s discriminated union validation automatically handles routing to the correct model based on the type field.