Metadata-Version: 2.5
Name: proteum
Version: 0.1.0
Summary: An experimental runtime for bounded, policy-controlled execution
Project-URL: Changelog, https://github.com/xhillman/proteum/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/xhillman/proteum/issues
Project-URL: Repository, https://github.com/xhillman/proteum
Requires-Python: >=3.14
Requires-Dist: openai>=3.1.0
Requires-Dist: pydantic>=2.12.5
Description-Content-Type: text/markdown

<div align="center">

# Proteum

Turn observed events into typed goals and policy-checked capability calls, with
explicit state at every step.

[Examples](./examples) · [Changelog](./CHANGELOG.md) ·
[Report a bug](https://github.com/xhillman/proteum/issues)

</div>

---

## 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

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

**Requires:** Python 3.14+ and [uv](https://docs.astral.sh/uv/). The included
examples need no API key or network access after installation.

## Quick start

```bash
uv run python examples/hello_proteum.py
```

```text
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.

```python
@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.

```python
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

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `model` | `Model` | Required | Produces structured Goal, Task, and Worker decisions. |
| `database` | `str \| Path \| None` | `None` | Enables SQLite persistence when set. |
| `world` | `WorldModel \| None` | In-memory | Replaces Object and Fact storage. |
| `memory` | `MemoryStore \| None` | In-memory | Replaces contextual Memory storage. |
| `event_bus` | `EventBus \| None` | In-memory | Replaces Event delivery. |
| `policy` | `PolicyEngine \| None` | `SimplePolicyEngine` | Authorizes capability requests. |
| `clock` | `Clock \| None` | `SystemClock` | Supplies timestamps for runtime behavior. |

`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:

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

## Development

```bash
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

- [x] 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.
