Skip to main content

orditect-core

Async task governance engine for the Orditect ecosystem

Python 3.12+

orditect-core is the governance engine of the Orditect ecosystem: Redis task store (state machine hosting), distributed rate limiting (lease semaphore + reservation token bucket), unified connection pool management.

Core Capabilities

Task Store (TaskRedisDB)

  • State machine hosting: terminal_statuses / transitions instance-level injection — upper frameworks declare their own state machine semantics, Lua terminal protection and Python transfer validation bound to the same source
  • Lua atomic operations: task updates (merge + status index maintenance) completed in a single script atomically
  • Lineage index (B2): parent_task_id registration + list_children() query (data foundation for cascade cancel / observation tree)
  • Idempotent initialization (B3): initialize_task(if_not_exists=True) prevents retry from resetting running task state
  • Index and primary record share the same expiry: same TTL, naturally no ghost members (design contract, T9 pinned)

Distributed Rate Limiting

  • AsyncLeaseSemaphore: ZSET lease semaphore + watchdog renewal (long task holding without expiry, crash auto-recovery, capacity no doubling no leakage)
  • AsyncTokenBucket: reservation token bucket (server-side clock, zero Redis connection occupancy during wait, rejected requests don't burn future quota)
  • @limited decorator: declarative resource governance (wait/reject dual mode)
  • LimiterRegistry: global resource registry + status query interface (limit/usage/available/utilization five-field unified format)

Connection Pool Management

  • RedisPoolManager: global singleton, unified register/monitor/close
  • Dependency injection: RedisDB(client=...) shares connection pool, RedisDB(redis_url=...) self-managed (backward compatible)

Installation

pip install orditect-core

Quick Start

Task Store (standalone, default vocabulary)

from orditect.core import TaskRedisDB

db = TaskRedisDB("redis://localhost:6379/0")
await db.connect()

await db.initialize_task("task_001")
await db.update_task("task_001", {"status": "in_progress"})
task = await db.get_task("task_001")

State Machine Hosting (custom vocabulary)

from orditect.core import TaskRedisDB

# Upper framework declares its own state machine (e.g. flow's vocabulary)
db = TaskRedisDB(
    "redis://localhost:6379/0",
    terminal_statuses=("succeeded", "failed", "cancelled"),
    transitions={
        "": {"pending", "queued"},
        "pending": {"queued", "cancelled"},
        "queued": {"running", "cancelled"},
        "running": {"succeeded", "failed", "cancelled"},
        "succeeded": set(), "failed": set(), "cancelled": set(),
    },
)
await db.connect()

# succeeded is a declared terminal state: any overwrite is atomically rejected by Lua

Lineage & Idempotency (recursive composition)

# Parent task submits child task: lineage registration + idempotency
await db.initialize_task(
    "child_task",
    parent_task_id="parent_task",
    if_not_exists=True,  # skip if exists (returns False), don't reset state
)

children = await db.list_children("parent_task")  # ["child_task", ...]

Distributed Semaphore

from orditect.core import AsyncLeaseSemaphore

sem = AsyncLeaseSemaphore(redis_client, "llm", limit=30, lease_time=30.0)

async with sem.hold():  # hold() produces independent context per call (concurrency-safe)
    await long_running_llm_call()  # watchdog auto-renews, holding 5 hours no problem

Declarative Decorator

from orditect.core import limited, get_registry

registry = get_registry()
registry.register_semaphore("llm", redis_client, limit=30)

@limited(resource="llm", mode="wait", timeout=5.0)
async def call_llm(prompt: str):
    return await llm_client.chat(prompt)

@limited(resource="gpu_pool", mode="reject")  # reject immediately (app maps 429)
async def submit_task(data: dict):
    return await heavy_computation(data)

Connection Pool Management

from orditect.core import get_pool_manager, TaskRedisDB

pool_manager = get_pool_manager()
redis_client = pool_manager.register_pool(
    "default", "redis://localhost:6379/0", max_connections=200,
)

# All modules share connection pool (dependency injection)
task_db = TaskRedisDB(client=redis_client)

# Monitoring
stats = await pool_manager.get_pool_stats("default")
# {"name": "default", "max_connections": 200, "in_use": 15, ...}

# On application shutdown
await pool_manager.close_all()

Important Changes

  • Bare async with sem: removed (breaking): semaphore instances shared across coroutines, context state on instance attributes causes concurrent overwrites (mutual exclusion failure + slot permanent leakage). Use async with sem.hold(): — each call produces independent context object, naturally concurrency-safe.
  • update_task without expiry preserves remaining expiry (behavior change): no longer resets to default_expire_time; explicit expiry advances the lease.
  • task_update.lua ARGV spec change: new ARGV[7] (fallback TTL for preserve mode), see docs/lua_contract.md.

Documentation

Testing

pytest -m unit          # pure logic
pytest -m pinning       # behavior pinning (requires Redis, default db15)
pytest -m integration   # acceptance tests
python -m pytest tests/ -v -m "not chaos"   # full suite

License

Apache-2.0


Metadata

Release files for orditect-core 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-core 0.1.7
File Size Uploaded Provenance Actions
orditect_core-0.1.7.tar.gz 40.9 kB With provenance Details for orditect_core-0.1.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for orditect-core 0.1.7
File Interpreter ABI Platform Actions
orditect_core-0.1.7-py3-none-any.whl Python 3 none any Details for orditect_core-0.1.7-py3-none-any.whl

Total release size: 90.7 kB

Release files / orditect_core-0.1.7.tar.gz

Download URL orditect_core-0.1.7.tar.gz
Size 40.9 kB
Tags Source
SHA-256 checksum
How to use checksums
455d56a2c7e0ad73c399bf3df9153118e293d10611374a7482686aed84d7bf29
BLAKE2b-256 checksum
How to use checksums
1f325e0f42f7b8c9eb3601919e92b4eadf5106b3db57586dfd18714831caf9c1
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_core-0.1.7-py3-none-any.whl

Download URL orditect_core-0.1.7-py3-none-any.whl
Size 49.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eb6c413d671db6b80991b43f343034819080307c0a83efca6e0133cb6212dd31
BLAKE2b-256 checksum
How to use checksums
87f38035124fc981278992fe082e18b60348fff37f54a543de3cf0e1a1e16690
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-core 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_core-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