Why

Model-driven runtimes often hide state changes and tool calls inside one loop. Proteum separates the loop into typed stages, then puts deterministic checks between model output and execution. The architecture is the point of v0.1.

Install

git clone https://github.com/xhillman/proteum.git
cd proteum
uv sync --locked

Requires: Python 3.14+ and uv. The included examples need no API key or network access after installation.

Quick start

uv run python examples/hello_proteum.py

Hello, world!
Task status: completed

Features

• Typed reasoning. Pydantic contracts validate model-generated Goals, Tasks, and Actions before Proteum uses them.
• Policy-checked execution. Every capability call crosses an authorization boundary before local code runs.
• Explicit state. Objects and Facts live in a World Model instead of a prompt transcript.
• Optional persistence. One database argument stores Objects, Facts, Events, Goals, Tasks, and execution records in SQLite.
• Offline tests. FakeModel returns queued structured responses for deterministic examples and tests.

Usage

Register a capability

Capabilities are asynchronous functions. Proteum derives their input schema from the function signature and registers them with the policy boundary.

@app.capability(
    name="diagnostics.inspect_ci",
    effects=("reads_ci_results",),
)
async def inspect_ci(repository: str) -> dict[str, str]:
    return {"repository": repository, "status": "failed"}

Persist state between sessions

In-memory storage is the default. Pass a database path when state must survive the current Proteum instance.

app = Proteum(model=model, database="proteum.db")
await app.start()
try:
    await app.publish(event)
finally:
    await app.stop()

restarted = Proteum(model=new_model, database="proteum.db")
repository = restarted.world.get_object("repo:proteum")
await restarted.stop()

stop() ends the session and closes resources owned by the application. Create a new instance to load the SQLite state.

Configuration

database owns the World Model and Event Bus composition. Do not combine it with world or event_bus. Memory remains in-process when SQLite is enabled.

How it works

1. An Event enters Proteum and updates recognized World Model Facts.
2. Attention decides whether the Event deserves further processing.
3. The Executive proposes a Goal, and the planner creates one Task.
4. The Worker receives bounded Context and may request a registered capability.
5. Policy authorizes the request. Execution records the result and updates the Task, Goal, and World Model.

The full path is:

Event
→ World Model
→ Attention
→ Goal
→ Task
→ Context
→ Worker
→ Capability
→ Policy
→ Execution
→ Result
→ World Model

Development

git clone https://github.com/xhillman/proteum.git
cd proteum
uv sync --locked
uv run ruff check .
uv run pyright
uv run pytest

Both examples use FakeModel. Development and test runs do not need external services.

Roadmap & known limitations

• Build the v0.1 package and run both examples from a fresh installation.
• Tag and publish v0.1 after the release gate passes.
• SQLite preserves records, but v0.1 does not resume unfinished Goals or Tasks.
• Memory remains in-process. Persistent Memory is post-v0.1 work.
• Not planned for v0.1. Distributed execution, dynamic Workers, plugin systems, and production-readiness claims.