Skip to main content

Ouroboros

A plugin framework for Python built on reversible registration as a first-class citizen.

Phase 1 core is implemented and validated, but the public API remains pre-1.0 and may change without notice.

What is this?

Ouroboros is a general-purpose composition framework that lets any Python application decompose itself into plugins that can be dynamically mounted, safely unmounted, and discover each other by service key rather than by import. A synchronous root Context composes the registry, event bus, service resolver, logger, and root lifecycle; every runtime operation still receives its invoking Context explicitly so derived scopes retain ownership.

It is a Python-native reimplementation of the architectural protocol pioneered by Cordis, the meta-framework extracted from the Koishi chatbot by Shigma and later vendored by DeepSeek Harness as its plugin substrate.

Relationship to Cordis

Ouroboros is not a line-by-line port of Cordis. It is an independent Python implementation that shares the same core protocol:

  • Reversible effects — every registration returns a disposer; unloading a plugin unwinds all its registrations in reverse order.
  • Dynamic fiber lifecycle — plugins mount and unmount at runtime; dependencies are resolved reactively, not by topological sort.
  • Key-based service discovery — plugins obtain dependencies via ctx.get("name") rather than importing concrete implementations.
  • Multi-semantics event bus — emit, serial, bail, parallel, and waterfall dispatch modes cover observation, short-circuit, concurrent, and around-middleware patterns.
  • Scope isolation — ctx.isolate("name", label) creates independent service scopes so the same service key can coexist in multiple instances.

The implementation diverges where Python's language semantics and standard library offer a simpler path than Cordis's TypeScript original:

Cordis (TypeScript) Ouroboros (Python) Why
Hand-written effect disposal Explicit DisposerStack Preserves synchronous rollback before setup errors escape, then joins mixed async cleanup
Traceable Proxy system (~120 LOC) Not needed Python's bound methods preserve self — no JS this-binding problem
Schemastery (vendored schema lib) Pydantic v2 Python ecosystem standard
Custom logger service (246 LOC) logging module Standard library
String-concatenated epoch ":3:5:7" frozenset of (service, provider id) pairs Order-insensitive, name-preserving snapshot
Symbol for isolate keys object() instances Python objects are naturally unique
AggregateError ExceptionGroup (3.11+) Standard library

No Cordis source code is included in this repository. The design is documented as an architectural reference; the code is an original Python implementation.

Quick start

import asyncio

from ouroboros import Context


async def main() -> None:
    async with Context() as ctx:
        def greeting(plugin_ctx: Context, config: str) -> None:
            plugin_ctx.provide("greeting", config)

        fiber = ctx.plugin(greeting, "hello")
        await fiber
        print(ctx.greeting)


asyncio.run(main())

See examples/basic.py for dependency activation, events, and automatic teardown in one runnable example.

Phase 1 scope

Phase 1 includes synchronous Context bootstrap, reversible mixed-mode Effects, reactive Fibers, scoped services, five event modes, plugin registry/runtime tracking, Pydantic validation, config intercepts, and stdlib logging.

Current limitations:

  • Python 3.11+ and one running asyncio loop per active root;
  • plugin mounting requires a running loop, although Context() does not;
  • config validation supports Pydantic v2 BaseModel subclasses and is synchronous;
  • event names and service names are strings, with best-effort typing for core events;
  • circular dependencies remain PENDING; Phase 1 does not diagnose the cycle;
  • there is no persistence/loader layer or cross-process transport.

Target use cases

Any system that satisfies all three criteria:

  1. Runtime evolution — components join and leave while the process runs.
  2. Reversible extensions — side effects of an extension must unwind cleanly when it is removed.
  3. Swappable implementations — the same interface may have multiple implementations switchable at runtime.

Examples: AI agent harnesses, chatbot frameworks, data pipelines, IDE extension systems, game server mod systems, test infrastructure.

License

Apache-2.0. See LICENSES/Apache-2.0.txt.

SPDX headers are used throughout the codebase in compliance with the REUSE specification.

Metadata

Release files for cordis-ouroboros 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cordis-ouroboros 0.2.0
File Size Uploaded Provenance Actions
cordis_ouroboros-0.2.0.tar.gz 44.3 kB With provenance Details for cordis_ouroboros-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cordis-ouroboros 0.2.0
File Interpreter ABI Platform Actions
cordis_ouroboros-0.2.0-py3-none-any.whl Python 3 none any Details for cordis_ouroboros-0.2.0-py3-none-any.whl

Total release size: 75.1 kB

Release files / cordis_ouroboros-0.2.0.tar.gz

Download URL cordis_ouroboros-0.2.0.tar.gz
Size 44.3 kB
Tags Source
SHA-256 checksum
How to use checksums
336c6c5ac5c2edd3da913944c2f0045e50dcd39f0469ff1bd07f7421d9e9edba
BLAKE2b-256 checksum
How to use checksums
23e7e7a1023335362bc37a5829f487417be2364cd3e1d26fafe3add62c535285
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 20, 2026.

Transparency log

Release files / cordis_ouroboros-0.2.0-py3-none-any.whl

Download URL cordis_ouroboros-0.2.0-py3-none-any.whl
Size 30.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a9b16da16cbb530a8ef7cbd477c4da6df5dcb82d5abd3f8a6ed5c7fa666d80cb
BLAKE2b-256 checksum
How to use checksums
cb07616a5f51475b8b1bd87bf4b60602d3a5e16835e8c3a9a3cd3eab5316af88
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 20, 2026.

Transparency log

Security for cordis-ouroboros 0.2.0

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 cordis_ouroboros-0.2.0.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 20, 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.2.0 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