Skip to main content

orditect-flow

Async task orchestration and lifecycle management for the Orditect ecosystem — recursive composite task governance

Python 3.12+

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() injects parent_task_id via 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-site GovernedClient
  • 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 and get_dependency_graph() raises UnsupportedCapabilityError (T8).

Documentation

Testing

pytest tests/unit -v    # pure logic (in-memory infra)
pytest tests/ -v        # full suite (requires Redis, default db15)

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)

Source distribution for orditect-flow 0.1.7
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)

Table of built distributions (wheels) for orditect-flow 0.1.7
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.7 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page