uxok 0.1.0

A hot-loading plugin microkernel for Python

uxok

Status: 0.x, pre-1.0. Functional and well-tested, but the public API is still settling and may change between releases. If you build on it now, pin to a commit and expect to adjust on upgrade.

A hot-loading plugin microkernel for building self-modifying agentic systems in Python.

Read the docs to learn more!

The docs are a WIP but I will be updating them actively: if you notice something off with them (or the code), please drop me an issue.

Installation

pip install uxok

Quick start

Basic functionality in a single script. The same program split into modules — the structure a real project uses — is in examples/getting_started/ and walked through by the Getting started tutorial. For a fuller host with hot reload and graceful shutdown, see examples/example_host/.

import asyncio
from uxok import Core, Plugin, event, hook

# Plugins are declared by subclassing `Plugin` and defining their name and what they provide in the capability metadata. 
class Model(Plugin):
    def __init__(self):
        super().__init__(name="model", provides={"llm"})

    # Methods are async so that other plugins can call them at random through capabilities.
    async def reply(self, text, persona):
        return f"{persona} you said '{text}'."

    # Hooks are set using a decorator and can be triggered by any plugin. 
    @hook("persona")
    async def voice(self):
        return "Cheerfully:"

# Other plugins can declare dependencies on other plugins' capabilities with "requires=". This builds a dependency graph the kernel resolves for you.
class Agent(Plugin):
    def __init__(self, done):
        super().__init__(name="agent", requires={"llm"})
        self.lines = ["hello there", "what's the weather like?"]
        self.done = done
    
    # Required capabilities are then acquired by name; the kernel hands back the provider.
    async def on_start(self):
        self.llm = await self.get_capability("llm")  # kernel wires it up
        await self.emit("turn")

    # Events are subscribed to in the same fashion as hooks. 
    @event("turn")
    async def speak(self, ev):
        if not self.lines:
            self.done.set()
            return
        line = self.lines.pop(0)
        persona = await self.hook("persona", firstresult=True)
        print(f"user:  {line}")
        print(f"agent: {await self.llm.reply(line, persona)}")
        await self.emit("turn")

# The main program just opens a core and loads plugins onto it; registration order matters, providers first.
async def main():
    done = asyncio.Event()
    async with Core() as core:                # async context manager starts/stops the kernel
        await core.register_plugin(Model())   # provider first
        await core.register_plugin(Agent(done))
        await done.wait()

asyncio.run(main())

Features

• Hot-Loading — Add/remove/replace plugins at runtime without restart
• Capability System — Kernel-style dependency resolution with tag-based selection
• Event-Driven — Non-blocking pub/sub messaging for loose coupling
• Hook System — Priority-based extension points for pipelines
• Introspectable — Query the live plugin graph at runtime: filter by capability, hook, event, or status
• Type Safety — Full protocol-based typing with mypy support

uxok has a microkernel-style architecture: the core provides only essential primitives for building extensible, self-modifying agentic applications — event-driven communication, hook-based extension points, hot-loading plugins with lifecycle management, and capability-based dependency resolution. Everything else is a plugin you can add, remove, or swap at runtime.

Development

git clone https://github.com/hiddenfalls42/uxok.git
cd uxok
pip install -e .[dev]

pytest                       # Run tests
ruff check src tests examples  # Lint
mypy src                     # Type check

Contributing

Contributions welcome!

License

MIT — see LICENSE