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:

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.