Skip to main content
Execution-backend contract. Exposes the Backend ABC, the BackendRuntime ABC one launch subcommand implements with its liveness declarations, the CallbackSchema, the scheduling protocol’s names and models, and the three seams a backend plugs its engine into: the TaskDoor (its queue), the ScheduleStore (its schedule storage, read back as StoredSchedule; its ScheduleWriter part is the one schedule writer) and the WorkerInspection (its worker views).

CONSUMING_RUNTIME

tai42_contract.backend.runtime.CONSUMING_RUNTIME
Canonical launch-subcommand name of the runtime that pulls queued work. The host exports the resolved manifest into the env only for this runtime: the CLI sniffs argv BEFORE the plugin module is imported, so it cannot ask the backend. A backend that names its consuming runtime anything else does not get the manifest export.

CRONTAB_FIELDS

tai42_contract.backend.scheduling.CRONTAB_FIELDS

PROCESS_PRELUDE_ENV

tai42_contract.backend.runtime.PROCESS_PRELUDE_ENV
The environment variable naming the process prelude the running process was started with. The host’s entry sets it once it has run the prelude, before it imports anything else (BackendRuntime.process_prelude); the launch compares it with the prelude the selected runtime declares.

SCHEDULE_BRANCH_SUFFIX

tai42_contract.backend.scheduling.SCHEDULE_BRANCH_SUFFIX

SCHEDULE_CADENCE_ADAPTER

tai42_contract.backend.scheduling.SCHEDULE_CADENCE_ADAPTER

SCHEDULE_CADENCE_KEY

tai42_contract.backend.scheduling.SCHEDULE_CADENCE_KEY

SCHEDULE_DELETE_TOOL

tai42_contract.backend.scheduling.SCHEDULE_DELETE_TOOL

SCHEDULE_EXPORT_TOOL

tai42_contract.backend.scheduling.SCHEDULE_EXPORT_TOOL

SCHEDULE_EXTENSION

tai42_contract.backend.scheduling.SCHEDULE_EXTENSION

SCHEDULE_IMPORT_TOOL

tai42_contract.backend.scheduling.SCHEDULE_IMPORT_TOOL

SCHEDULE_LIST_TOOL

tai42_contract.backend.scheduling.SCHEDULE_LIST_TOOL

SCHEDULE_MARKER_TOOLS

tai42_contract.backend.scheduling.SCHEDULE_MARKER_TOOLS

SCHEDULE_NAME_KEY

tai42_contract.backend.scheduling.SCHEDULE_NAME_KEY

Backend

tai42_contract.backend.base.Backend
Abstract execution backend for a Tai app. A backend runs the task runtime (launch) and executes the work its workers pull from the broker. The app core depends only on this interface and stays backend-agnostic; concrete backends (celery/rq/arq) implement it and register via @tai42_app.backends.register_backend. Fleet propagation of config changes is not a backend concern: it is the app’s own worker bus, internal to the app. A backend-runtime process receives fleet ops through the app’s bus subscription exactly like a serving HTTP worker — the backend carries no control-plane surface of its own. Each backend declares its own drain bound (drain_timeout); the app announces it, together with its own shutdown bounds, when the process leaves, so a fleet restart waits for the worker to finish its in-flight work rather than reporting it timed out.

Members

drain_timeout

tai42_contract.backend.base.Backend.drain_timeout
How long, in seconds, this backend’s worker may take to finish its in-flight work and exit when stopped. Read at call time, so a settings change applies to the next stop.

launch

tai42_contract.backend.base.Backend.launch
Start the worker runtime for the backend registered via @tai42_app.backends.register_backend. Parameters

BackendRuntime

tai42_contract.backend.runtime.BackendRuntime
ONE launchable runtime of an execution backend, named by its launch subcommand. The vendor binding answers only “how MY engine starts, drains, and recycles”; readiness gating, signal wiring, drain-on-cancellation and pool turnover belong to the host base that drives this object. The liveness signal is the host’s too: the runtime declares which kind it has (liveness), and a progress runtime reports from its own loop. A runtime runs only on the objects its build produced. The host re-imports the package a runtime comes from on every config reload, so that the package’s registrations re-fire into the new configuration, and a reload can land between build and the run body as well as during it. The runtime is a process-lifetime object and stays whole across those re-imports: it holds what it built and never resolves its own objects again through the import system. It hands its engine the objects themselves wherever the engine’s interface takes an object; it imports nothing of its own package after build; the state its engine reads lives on the objects it built, never in its package’s module globals; and it connects receivers to an engine’s process-wide signals from build, never at import. Where an engine’s interface takes only an import path (a setting that names a class, a stored job that names its function), the engine resolves that name itself, possibly after a reload, and so may reach the re-imported copy. An object handed over by name therefore keeps no state of its own: it reads what it needs from its arguments, from the objects the build produced that the engine passes it, or from the process environment, so the re-imported copy behaves as the built one.

Members

name

tai42_contract.backend.runtime.BackendRuntime.name
The launch subcommand that selects this runtime.

mode

tai42_contract.backend.runtime.BackendRuntime.mode
How the host must drive the run body.

consumes_work

tai42_contract.backend.runtime.BackendRuntime.consumes_work
True when this runtime pulls queued work. Only a consuming runtime is readiness-gated, drain-wired, and turnover-wired.

pool_turnover_required

tai42_contract.backend.runtime.BackendRuntime.pool_turnover_required
True when work executes in worker processes that PERSIST ACROSS JOBS and therefore hold a snapshot of this process’s tool registry: a registry mutation does not reach them, so the pool must be turned over. False for a runtime that runs work in-process, and for one that spawns a fresh child per job (the next child inherits the mutation). Declared per class like the rest, but deliberately NOT a ClassVar: a launch option can decide whether this engine’s pool persists, so an instance may set it. The host therefore reads it off the live runtime.

process_prelude

tai42_contract.backend.runtime.BackendRuntime.process_prelude
The module:callable the process must have run before any other import, or None. Declared by a runtime whose engine reshapes the interpreter’s blocking primitives (its threads, locks, sockets and sleeps) and so must do it before any other module has bound them. The host’s entry runs it, with no arguments, first thing in a fresh process, and the launch refuses a runtime whose prelude this process was not started with (ProcessPreludeRequired). Not a ClassVar, like pool_turnover_required: a launch option can decide it, so the host reads it off the live runtime.

liveness

tai42_contract.backend.runtime.BackendRuntime.liveness
How this process signals it is alive. REQUIRED: the host refuses a runtime without it. A consuming runtime declares ProgressLiveness: what it is alive for is consuming, and its loop is what consumes. An HTTP server declares HttpLiveness with the path an orchestrator’s HTTP probe requests.

bind_progress

tai42_contract.backend.runtime.BackendRuntime.bind_progress
Bind the host’s progress reporter: once, before build. A second bind raises RuntimeError. Parameters

report_progress

tai42_contract.backend.runtime.BackendRuntime.report_progress
Report one pass of this runtime’s engine loop and promise the next one within next_within seconds. Called from inside the loop on every pass, idle or busy, from any thread. next_within is the loop’s own sleep or poll bound for the pass that follows; the probe judges this process against it, so a loop that stops passing stops reporting and is seen as such. Raises RuntimeError when no reporter is bound (a runtime driven without the host’s binding, or one that declares HttpLiveness) and ValueError when next_within is not positive. Parameters

from_args

tai42_contract.backend.runtime.BackendRuntime.from_args
Parse this runtime’s own options and return the runtime. Strict — an unknown option aborts the launch loudly. Parses only; starts nothing. Parameters

build

tai42_contract.backend.runtime.BackendRuntime.build
Construct engine objects. Runs BEFORE the readiness gate — building is not consuming — and before any run body. Default: nothing to build. What it builds is everything the run body and the stop path use: a config reload re-imports this runtime’s package after it returns (see the class docstring). Concrete rather than abstract: a runtime whose engine object is built by from_args alone must not be forced to declare an empty override.

run_on_loop

tai42_contract.backend.runtime.BackendRuntime.run_on_loop
Consume until stopped, driven by the serving loop. REQUIRED iff mode is on_loop.

run_blocking

tai42_contract.backend.runtime.BackendRuntime.run_blocking
Consume until stopped, blocking the calling thread. REQUIRED iff mode is worker_thread or inline.

request_drain

tai42_contract.backend.runtime.BackendRuntime.request_drain
Stop accepting new work, let in-flight work finish, and make the run body RETURN once drained. Called from the loop thread — while a worker_thread body runs on another thread — so it MUST NOT block and MUST NOT touch main-thread-only APIs (signal.signal above all: the host owns the process’s signal disposition and a vendor rebind destroys it). MUST BE IDEMPOTENT: the host calls it on signal AND again on the cancellation path. Escalation belongs to request_terminate, never to a second request_drain. REQUIRED iff consumes_work.

request_terminate

tai42_contract.backend.runtime.BackendRuntime.request_terminate
Cold stop: abandon in-flight work now. Called on a repeated signal. Default: report that this runtime declares no cold stop and let the warm drain continue — the supervisor’s kill is the backstop.

turn_over_pool

tai42_contract.backend.runtime.BackendRuntime.turn_over_pool
Replace every worker that predates the mutation named by reason, and CONFIRM it. On return, no pre-mutation worker may take new work; one still finishing the job it holds exits after it, and is not waited for. Raise loudly if it cannot be confirmed within budget seconds — the caller is inside a fleet-op apply, and a raise makes that op report failed rather than a false applied. Called from the fleet-op hook, which the host wires BEFORE build so an op landing during a long boot is not missed. So this may run before the engine objects exist, and it runs CONCURRENTLY with the run body once they do. A no-op is the correct answer whenever there is no pool yet, or the live pool turns out not to hold a snapshot: the workers that do not exist cannot be stale, and the next ones are built after the mutation. REQUIRED iff pool_turnover_required. Parameters

aclose

tai42_contract.backend.runtime.BackendRuntime.aclose
Release engine resources once the run body is done with them. Always awaited, on every exit path. Default: nothing to release. The run body has normally LEFT by then, but there is one exception the binding has to survive: a blocking body cannot be cancelled, so a cancellation that arrives while it is still on its thread abandons it there (the host reports this) and teardown runs anyway. Release what can be released without assuming the body let go. Concrete rather than abstract: a runtime that owns no resource must not be forced to declare an empty override.

CallbackSchema

tai42_contract.backend.callback.CallbackSchema
A backend task’s follow-up: an optional guard condition and a follow-up tool kwargs expr. Attributes

CrontabCadence

tai42_contract.backend.scheduling.CrontabCadence
Fire on a five-field crontab (minute, hour, day of month, month, day of week). Attributes

Members

expression

tai42_contract.backend.scheduling.CrontabCadence.expression
The five-field crontab expression; validating {"expression": ...} with it gives this cadence back.

ExecutionMode

tai42_contract.backend.runtime.ExecutionMode
How a runtime’s run body must be driven.

Members

on_loop

tai42_contract.backend.runtime.ExecutionMode.on_loop
The run body is a coroutine driven by the serving loop.

worker_thread

tai42_contract.backend.runtime.ExecutionMode.worker_thread
The run body blocks; the host runs it on a dedicated daemon thread.

inline

tai42_contract.backend.runtime.ExecutionMode.inline
The run body blocks the serving loop deliberately; the host wires nothing.

FleetOpApplied

tai42_contract.backend.runtime.FleetOpApplied
A worker-bus op that applied in this process, as a post-apply handler receives it. effects is what the op changed here (empty for a query or a process exit); a handler decides on it, never on op, which names the op for logs and a turnover reason. budget is the seconds left before the publisher’s report cut, measured from this process’s receipt of the op; a post-apply obligation that cannot finish within it must raise. Attributes

FleetOpEffect

tai42_contract.backend.runtime.FleetOpEffect
What applying a worker-bus op changed in this process — the vocabulary a post-apply handler decides on.

Members

registry

tai42_contract.backend.runtime.FleetOpEffect.registry
This process’s tool registry changed.

templates

tai42_contract.backend.runtime.FleetOpEffect.templates
This process’s compiled-template cache was dropped.

HttpLiveness

tai42_contract.backend.runtime.HttpLiveness
The process is alive while its HTTP server answers GET path with a success status on the port it serves. path is absolute (starts with /) and needs neither a session nor data from a backing store, so the answer depends on the server alone; a process whose every route sits behind credentials (basic auth) needs them on the probe too. Attributes

IntervalCadence

tai42_contract.backend.scheduling.IntervalCadence
Fire every every seconds; relative aligns the schedule to the interval’s own clock. Attributes

Liveness

tai42_contract.backend.runtime.Liveness
How a backend process signals it is alive: by its loop’s progress, or by its HTTP server.

ProcessPreludeRequired

tai42_contract.backend.runtime.ProcessPreludeRequired
The selected runtime declares a process prelude this process was not started with. Raised by the launch before anything of the runtime starts. The host answers it by starting the process again with the prelude run first; prelude names it. Attributes

ProgressLiveness

tai42_contract.backend.runtime.ProgressLiveness
The process is alive while its engine loop keeps reporting progress. The host binds a reporter before build (BackendRuntime.bind_progress); the runtime calls BackendRuntime.report_progress from inside its loop on every pass.

ProgressReporter

tai42_contract.backend.runtime.ProgressReporter
The host’s receiver of a loop runtime’s progress reports. next_within is a positive number of seconds. A loop whose own interval is zero (it passes again without sleeping) promises a fixed positive floor instead: its engine’s own floor for the wait, where the engine has one, else a bound its next pass returns within.

ScheduleCadence

tai42_contract.backend.scheduling.ScheduleCadence

ScheduleCreate

tai42_contract.backend.scheduling.ScheduleCreate
Create a schedule that runs tool_name on cadence, or once now when no cadence is given. tool_kwargs are the arguments each fire passes to the tool, the tool’s alone and forwarded untouched — a tool whose OWN argument is named subject carries it here like any argument. subject is the OPTIONAL top-level door field naming the schedule-door state context each fire re-establishes: the create door stamps it onto the job, and the fire keys its state writes and parks on it (it never reaches the base tool). state_binding is the OPTIONAL door-layer binding the fire applies around the started tool alone (never the base tool’s). schedule_name names a recurring schedule; without it the door derives one from the tool, its arguments and the cadence. A schedule is a parkable-driving door: it carries the four ParkableDoorMixin jqs (start_expr builds the fired tool’s kwargs; cancel_expr / resume_expr act on the run’s parked interactions; extras_expr builds the started run’s extras), each evaluated over the fired tool’s arguments with the run’s parked interactions bound as $parked. Any contract jq needs an execution_key (the api-key user_id the recurring fire runs as, so a park it raises can be rebound and resumed under that authority). Attributes

ScheduleDetail

tai42_contract.backend.scheduling.ScheduleDetail
One schedule as its read replies it: the listing row plus the arguments it fires with. args and kwargs are the fired tool’s arguments plus the reserved door stamps the fire needs, as in ScheduleRecord. Attributes

ScheduleImportError

tai42_contract.backend.scheduling.ScheduleImportError
One import row the backend refused, at its index in the rows it was handed. Attributes

ScheduleImportMode

tai42_contract.backend.scheduling.ScheduleImportMode

ScheduleImportReport

tai42_contract.backend.scheduling.ScheduleImportReport
What a schedule import did: counts per outcome and the refused rows. Attributes

ScheduleListRow

tai42_contract.backend.scheduling.ScheduleListRow
One row of the schedule listing: no arguments, no kwargs. next_run_at_ts is the next run’s POSIX timestamp, None when the schedule has no next run (0.0 is a timestamp like any other). next_run_at_iso is derived from it, the UTC ISO-8601 form or None: a row is built without it, and a given value that disagrees with the timestamp is refused. Attributes

ScheduleRecord

tai42_contract.backend.scheduling.ScheduleRecord
One exported or imported schedule: the durable definition, never runtime state. Attributes

ScheduleRowError

tai42_contract.backend.scheduling.ScheduleRowError
A backend’s last scheduling failure for a schedule, when the backend records one. Attributes

ScheduleStore

tai42_contract.backend.schedule_store.ScheduleStore
A backend’s schedule storage: its capabilities, its reads and its writes. A write or a read raises on a store failure; False or None answers only “no such schedule”.

Members

holds_disabled

tai42_contract.backend.schedule_store.ScheduleStore.holds_disabled
Whether the store holds a disabled schedule (enabled=False) as such. A store that holds none keeps every schedule it stores enabled: write refuses a disabled record and set_enabled is never called on it.

exists

tai42_contract.backend.schedule_store.ScheduleStore.exists
Whether a schedule named name is stored. Parameters

read

tai42_contract.backend.schedule_store.ScheduleStore.read
The schedule named name, or None when none is stored. Parameters

read_all

tai42_contract.backend.schedule_store.ScheduleStore.read_all
Every stored schedule, enabled or disabled; one deleted while the store is read is left out.

delete

tai42_contract.backend.schedule_store.ScheduleStore.delete
Remove the schedule name; False when none was stored. Parameters

set_enabled

tai42_contract.backend.schedule_store.ScheduleStore.set_enabled
Enable or disable the schedule name; False when none is stored. Parameters

run_now

tai42_contract.backend.schedule_store.ScheduleStore.run_now
Make the schedule name run at once, its recurrence kept; False when none is stored. Parameters

update

tai42_contract.backend.schedule_store.ScheduleStore.update
Change the schedule name in one step; False when none is stored. cadence, when given, replaces its cadence; next_run_at_ts, when given, moves its next run to that POSIX timestamp. At least one is given. A new cadence without a next_run_at_ts takes its next run from the store’s own rule for a new cadence. Parameters

ScheduleWriter

tai42_contract.backend.schedule_store.ScheduleWriter
A backend’s schedule writer: the one write every schedule write door goes through. A write door checks a cadence against relative_intervals before it writes.

Members

relative_intervals

tai42_contract.backend.schedule_store.ScheduleWriter.relative_intervals
Whether the store honours an interval cadence with relative=True.

write

tai42_contract.backend.schedule_store.ScheduleWriter.write
Create or replace the schedule record names, as record defines it. The one writer behind the schedule branch, create, update and import. record.tool is stored inside the job kwargs under the backend’s tool-name argument. The write is durable when this returns; it raises on a store failure. Parameters

StoredSchedule

tai42_contract.backend.schedule_store.StoredSchedule
One schedule as its store holds it, with its runtime state. kwargs are the stored job kwargs: the fired tool’s name under the backend’s tool-name argument, the tool’s arguments and the reserved stamps. next_run_at_ts is the next run’s POSIX timestamp, None when the store records no next run. error is the store’s last scheduling failure for the schedule, when it records one. Attributes

TaskDoor

tai42_contract.backend.dispatch.TaskDoor
A backend’s queue door: submit a job, name it, wait for it. HandleT is the vendor’s own handle on a submitted job (a result object, a job record); only the door reads it.

Members

task_opts

tai42_contract.backend.dispatch.TaskDoor.task_opts
The vendor’s own task options, by name and annotation, beyond the platform’s set. Each becomes a keyword-only argument (default None) of the sync and async branch tools, and reaches submit in its options when the caller gave a value.

submit

tai42_contract.backend.dispatch.TaskDoor.submit
Queue one job running the dispatched tool with args and kwargs; return its handle. kwargs are the prepared job kwargs (the tool name and the reserved stamps inside). options are the task options the caller gave, None values already dropped and the callback taken out: the door maps each onto its queue’s API and raises on one it cannot honour. callback, when given, already carries what its follow-up job needs; the door chains it to run on the job’s result. Parameters

task_id

tai42_contract.backend.dispatch.TaskDoor.task_id
The id a caller looks the submitted job up by. Parameters

wait

tai42_contract.backend.dispatch.TaskDoor.wait
Wait up to timeout seconds for the job to finish and return its result. A failed job raises its failure as the vendor retains it. A job still unfinished at timeout raises TaskWaitTimeoutError; the job itself is left running. Parameters

TaskWaitTimeoutError

tai42_contract.backend.dispatch.TaskWaitTimeoutError
Raised by TaskDoor.wait when the job is still unfinished at its timeout. Its own class, so a job that itself failed with a TimeoutError is never read as an unfinished one.

WorkerInspection

tai42_contract.backend.inspection.WorkerInspection
A backend’s read-only views of its workers and their tasks, plus cancelling a task. worker_name narrows a view to one worker; None covers every worker. A view is handed a worker_name only when addresses_workers, and cancel a terminate=True only when terminates.

Members

addresses_workers

tai42_contract.backend.inspection.WorkerInspection.addresses_workers
Whether the views can narrow to one worker by its name.

terminates

tai42_contract.backend.inspection.WorkerInspection.terminates
Whether cancel serves terminate=True: the backend’s workers stop a task while it runs.

ping

tai42_contract.backend.inspection.WorkerInspection.ping
Ask the workers whether they are alive, and return their answers. Parameters

active_workers

tai42_contract.backend.inspection.WorkerInspection.active_workers
The names of the workers alive now.

task_status

tai42_contract.backend.inspection.WorkerInspection.task_status
The vendor’s status word for the task task_id. Parameters

task_result

tai42_contract.backend.inspection.WorkerInspection.task_result
The task’s (ready, status, value): whether it finished, its status word, its result. With a timeout it waits up to that many seconds for the task to finish; with None it reads the current state at once. value is the result when ready. A failed task raises its failure as the vendor retains it. Parameters

cancel

tai42_contract.backend.inspection.WorkerInspection.cancel
Cancel the task task_id; return what was done. Without terminate a task that has not started is kept from running and a running one is left to finish; with terminate a running task is stopped as well. A backend that cannot cancel a running task without stopping it refuses the call without terminate for a running task rather than stopping it. The reply says what was done; when a worker answers that it cannot stop the task it runs, the call is refused rather than leaving the task running behind a reply that says otherwise, and a stop the workers did not confirm within the time the backend waits for it is reported as not confirmed, with the status the task reached. Parameters

active_tasks

tai42_contract.backend.inspection.WorkerInspection.active_tasks
The tasks running now. Parameters

reserved_tasks

tai42_contract.backend.inspection.WorkerInspection.reserved_tasks
The tasks taken off the queue and waiting for a free worker slot.

scheduled_tasks

tai42_contract.backend.inspection.WorkerInspection.scheduled_tasks
The tasks waiting for a later time (an eta or countdown).

registered_tasks

tai42_contract.backend.inspection.WorkerInspection.registered_tasks
The task names the workers can run. Parameters

failed_tasks

tai42_contract.backend.inspection.WorkerInspection.failed_tasks
The tasks that failed, as the vendor retains them.

worker_stats

tai42_contract.backend.inspection.WorkerInspection.worker_stats
The workers’ runtime statistics. Parameters

worker_queues

tai42_contract.backend.inspection.WorkerInspection.worker_queues
The queues the workers consume. Parameters