orditect-flow
Async task orchestration and lifecycle management for the Orditect ecosystem — recursive composite task governance
orditect-flow is the orchestration plane of the Orditect ecosystem. Its core
capability is recursive composition: every task node, at any depth, can be
independently governed — concurrency, state, cancellation, resources — with
governance delegated to any layer of the call stack.
Core Capabilities
Recursive Composition
Any BaseBackEndTask can submit child tasks inside its own execute(), and
children can submit grandchildren — depth is limited only by business logic:
- Automatic lineage registration: nested
submit()injectsparent_task_idvia contextvar, zero boilerplate - Cascade cancellation:
cancel()/terminate()recurse along the lineage, no orphan tasks - Resource lineage exemption: a child sharing an ancestor's resource is exempted (ancestor's slot covers the whole subtree), no self-deadlock
- Idempotent submit:
submit(if_not_exists=True)prevents parent retry from re-submitting children
Task Governance
- FastAPI-native: no extra worker process, runs inside the app
- Full state machine:
pending → queued → running → succeeded/failed/cancelled - Dual-layer governance: task-level
resource_type+ call-siteGovernedClient - Dual-mode cancellation:
cancel()graceful mark /terminate()force-kill - Retry: exponential backoff, dead letter queue (DLQ)
- Workflow orchestration: DAG dependencies + Saga rollback
- Callbacks: Webhook, WebSocket, composite
- Progress tracking
Recovery Plane (v0.1.0)
Breakpoint-resume and mid-point custom replay over the recursive task tree:
from orditect.flow import RecoveryService
svc = RecoveryService(
storage=task_db, # orditect-core TaskRedisDB
snapshot_reader=pg_snapshot_reader, # protocol SnapshotReader (adapter)
executor=orchestrator.executor,
reuse_terminal_words=frozenset({"succeeded"}),
task_factory=my_task_factory, # caller-injected reconstruction
)
# Breakpoint-resume: reuse succeeded nodes, rerun the rest
plan = await svc.resume(root_task_id)
# Mid-point replay: force-rerun an explicit node set
plan = await svc.rerun(root_task_id, scope={"node_a", "node_b"})
Snapshot persistence is opt-in (snapshot_sink on the orchestrator) — zero
cost by default. See docs/recovery.md.
Governed Calls & Actions (v0.1.3)
Standard form for governed resource calls and protocolized action channel:
from orditect.flow import GovernedCallClient, ActionDispatcher
# Governed call (semaphore + budget + audit + content)
client = GovernedCallClient(
governor, "llm", handler=call_llm,
budget=ledger, audit_writer=audit, task_id=task_id,
)
result = await client.call(call_id="c-1")
# Action sink (command-queue form for HITL/MCP/agent)
dispatcher = ActionDispatcher(queue, orchestrator, recovery)
await dispatcher.start()
See docs/integration-guide.md for the three-category integration guide.
Installation
pip install orditect-flow
# depends on orditect-core>=0.1, orditect-protocol>=0.1
Quick Start
from orditect.flow import BaseBackEndTask, TaskOrchestrator
from orditect.flow.storage.factory import get_default_storage
from orditect.flow.governor.factory import get_default_governor
class MyTask(BaseBackEndTask):
async def execute(self, task_id: str, **kwargs):
return await process(kwargs["data"])
storage = get_default_storage(redis_client)
await storage.connect()
governor = get_default_governor()
orchestrator = TaskOrchestrator(storage, governor)
task = MyTask(storage, governor)
task_id = await orchestrator.submit(task, data={"key": "value"})
status = await orchestrator.get_status(task_id)
Architecture
TaskOrchestrator (submit / cancel / terminate / cascade / recovery)
|
TaskExecutor (resource exemption / timeout sentinel / shielded release /
snapshot sink / result reuse short-circuit)
|
RecoveryService (resume / rerun — per-node reuse-or-rerun decision)
|
orditect-core (governance engine: task store, semaphore, reopen primitive)
orditect-protocol (storage contracts: snapshot / content / audit domains)
Multi-Parent Dependency Governance (v0.1.1)
DependencyGovernor is a passive, protocol-layer API for tasks with
multiple parents. It governs the dependency relationship only — task
creation, scheduling, and DAG semantics stay with the external
orchestration system:
from orditect.flow.governance import DependencyGovernor
gov = DependencyGovernor(
storage,
success_words=frozenset({"succeeded"}), # caller-declared (T6)
lifecycle=orchestrator.lifecycle, # vote-triggered cancel
dep_graph_store=my_graph_store, # optional cold path
)
# after creating the child task (external system's job):
await gov.register_dependency(child_id, [p1, p2, p3])
# after ANY task reaches a terminal state (external system's job):
await gov.notify_task_terminal(parent_id, "succeeded")
# poll readiness (never schedules anything):
ready = await gov.get_ready_tasks()
- Success never auto-votes; abnormal terminals auto-vote (hang prevention).
- Votes are atomic: exactly one concurrent voter triggers cancellation.
- Without
dep_graph_store, the hot path works fully andget_dependency_graph()raisesUnsupportedCapabilityError(T8).
Documentation
- Recovery plane: resume / rerun design and wiring
- Architecture: orchestration internals
Testing
pytest tests/unit -v # pure logic (in-memory infra)
pytest tests/ -v # full suite (requires Redis, default db15)
Related Projects
- orditect-core: governance engine (task store, rate limiting, reopen)
- orditect-protocol: storage interaction contracts
- orditect-stream: output plane (SSE streaming)
License
Apache-2.0
Metadata
Release files for orditect-flow 0.1.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| orditect_flow-0.1.7.tar.gz | 77.3 kB | With provenance | Details for orditect_flow-0.1.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| orditect_flow-0.1.7-py3-none-any.whl | Python 3 | none | any | Details for orditect_flow-0.1.7-py3-none-any.whl |
Total release size: 176.9 kB
Release files / orditect_flow-0.1.7.tar.gz
| Download URL | orditect_flow-0.1.7.tar.gz |
|---|---|
| Size | 77.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f8cd515ef0192397416a3aabbea559715f2f8fe24a2a36b10adfb9fb6d95807e
|
|
BLAKE2b-256 checksum How to use checksums |
64b7c98af8b7a5071d83a142d94bf4524a2b0d862ab2a73b05f6a0103ab2e7b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / orditect_flow-0.1.7-py3-none-any.whl
| Download URL | orditect_flow-0.1.7-py3-none-any.whl |
|---|---|
| Size | 99.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0b8ff2187500cca5b34bb88e71a1292ad568507449e0305b3efc210dc091e919
|
|
BLAKE2b-256 checksum How to use checksums |
21387c7bfcfa8052661d76faed1c1424cd61cefa906d255cf8cfec497cfb8af4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logSecurity for orditect-flow 0.1.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for orditect_flow-0.1.7.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.