Metadata-Version: 2.4
Name: openroar
Version: 1.0.0b1
Summary: The safe interface between any agent and any LLM. Manifest-enforced. Audit-logged. Apache 2.0.
Project-URL: Homepage, https://openroar.org
Project-URL: Repository, https://github.com/alexandercharlie-hub/openroar-alpha
Project-URL: Documentation, https://openroar.org/docs
Project-URL: Charter, https://openroar.org/charter
Author-email: openroar contributors <hello@openroar.org>
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,audit,llm,manifest,open-source,safety,verifiable
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=24.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: argon2-cffi>=23.1.0; extra == 'all'
Requires-Dist: cryptography>=42.0; extra == 'all'
Requires-Dist: google-generativeai>=0.7; extra == 'all'
Requires-Dist: groq>=0.10; extra == 'all'
Requires-Dist: keyring>=24.0; extra == 'all'
Requires-Dist: openai>=1.40; extra == 'all'
Requires-Dist: sandbox-runtime<0.3,>=0.2.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.7; extra == 'gemini'
Provides-Extra: groq
Requires-Dist: groq>=0.10; extra == 'groq'
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.27; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'observability'
Requires-Dist: prometheus-client>=0.21; extra == 'observability'
Requires-Dist: structlog>=24.0; extra == 'observability'
Provides-Extra: ollama
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Provides-Extra: panel
Requires-Dist: anthropic>=0.40; extra == 'panel'
Requires-Dist: google-generativeai>=0.7; extra == 'panel'
Requires-Dist: groq>=0.10; extra == 'panel'
Provides-Extra: sandbox
Requires-Dist: sandbox-runtime<0.3,>=0.2.0; extra == 'sandbox'
Provides-Extra: test
Requires-Dist: fastapi>=0.100; extra == 'test'
Requires-Dist: hypothesis>=6.100; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Provides-Extra: vault
Requires-Dist: argon2-cffi>=23.1.0; extra == 'vault'
Requires-Dist: cryptography>=42.0; extra == 'vault'
Requires-Dist: keyring>=24.0; extra == 'vault'
Description-Content-Type: text/markdown

# openroar

> **A vision for a prosperous future — with AI, with tech, with decentralised governance.**
>
> At the implementation layer, openroar is the **safe interface between any agent and any LLM**: a manifest-enforced, audit-logged safety layer you put between your agents and the models they call. You bring the keys. openroar makes every action declared, checked, and logged before it runs.

**Apache-2.0 · Python 3.11+ · alpha**

```python
from openroar import Agent, run

agent = Agent.from_soul("agents/example/safe-default.md")
result = run(agent, "Name three fruits.")
print(result.text)
```

---

## Why openroar

The viral generation of open-source AI agents proved the demand — and then proved the risk: exposed instances, key exfiltration, prompt-injection with no boundary behind it. openroar is the one built trust-first. Every model call passes a **safety gate** before it executes; nothing is implicit.

- **Manifest safety gate** — every model call is checked against the SOUL's declared red-lines *before* (the intent) and *after* (the output). Matching is deterministic (keyword + regex, normalised against common evasions). Denials are explicit and logged. (Optional semantic + LLM-judge cascade layers and capability-*pledge* enforcement are on the [roadmap](#status) — not the default guarantee today.)
- **First-party vault** — your API keys live in a local encrypted store. Agents request access by name; raw secrets never enter agent context.
- **Append-only audit log** — hash-chained record of every decision, with **Ed25519-signed Merkle snapshots** (signing key held in your OS keyring, never the log directory) so a later rewrite of the chain is detectable, not silently re-hashable. `openroar audit verify` checks both the chain and the snapshot signatures.
- **Provider-agnostic** — Anthropic, OpenAI, Gemini, Groq, or local Ollama. Swap the model by changing one field: `"provider:model-id"`.
- **Fully yours to customise** — opinions ship as *defaults*, not locks. Your own local LLM (or models you connect via keys) drives how you extend it. See [ADR-0001](./adrs/0001-architecture-decision-records.md).

---

## Install

During the alpha, install from source (the PyPI package `pip install openroar` is coming once we cut the first published release):

```bash
git clone https://github.com/alexandercharlie-hub/openroar-alpha.git
cd openroar-alpha && ./scripts/install.sh
```

Then set up your keys and run a sanity check:

```bash
openroar doctor          # diagnoses missing keys / config with exact fixes
```

Full walkthrough: [`docs/self-host/quickstart.md`](./docs/self-host/quickstart.md).

---

## Your first agent

An agent is a **SOUL** — a YAML declaration of who it is, what it may do, and what it must never touch:

```yaml
name: summariser
description: reads a local markdown file and returns a plain-english summary.
model: ollama/llama3            # or anthropic:claude-..., openai:gpt-..., etc.
capabilities: [read_file]       # only what's listed is permitted
constraints:
  file_access:
    allow_paths: ["~/Documents/notes"]
    deny_patterns: ["**/.env", "**/*.key"]
  network: none
behavior:
  on_uncertainty: ask
```

Run it:

```bash
openroar chat agents/my-agents/summariser/SOUL.md --intent "summarise notes.md"
```

The gate validates the SOUL, checks the intent and the model's output against the SOUL's red-lines, and logs every decision. Your SOUL *is* your audit surface — everything the agent declares is in one readable file. Full guide: [`docs/guides/your-first-agent.md`](./docs/guides/your-first-agent.md).

Start from the bundled examples in [`agents/example/`](./agents/example), or write your own.

---

## What's in here

```
openroar/        the framework — runtime, manifest gate, vault, providers, prism, conformance
agents/example/  tutorial agents to fork
manifests/       sample safety manifests (safe-default, research, customer-support)
scripts/         the terminal installer + setup
docs/            self-host guide, engineering principles, security model, patterns
adrs/            architecture decision records (start at ADR-0001)
tests/           the framework test suite (mocked — no network required)
tools/           the quality + security gates
```

---

## Philosophy

openroar is governed by a public **Charter** — written before the product, so you can hold us to it. Read [`CHARTER.md`](./CHARTER.md).

Engineering discipline is not optional here: the 20 principles in [`docs/engineering/ENGINEERING_PRINCIPLES.md`](./docs/engineering/ENGINEERING_PRINCIPLES.md) bind every line of code — DRY, YAGNI, fail-fast, idempotency, edge-case + mocking discipline.

---

## Contributing & security

- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — dev setup, proposing a sample agent, the spec-and-ADR discipline.
- [`SECURITY.md`](./SECURITY.md) — coordinated disclosure. Please report vulnerabilities privately.
- [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).

---

## Status

**Alpha.** We tell you exactly what's real today versus what's planned — that's the whole point of a trust-first project.

**Real and tested today:**

- Manifest safety gate with **deterministic** red-line checks (keyword + regex, evasion-normalised), before the intent and after the output, on every model call.
- First-party encrypted vault (AES-256-GCM + Argon2id); keys never enter agent context.
- Append-only, hash-chained audit log with signed Merkle snapshots.
- Provider adapters for Anthropic, OpenAI, Gemini, Groq, and local Ollama.
- Consent gate for remote providers (no silent network egress).
- Read-only tools: `file_read`, `http_fetch` (SSRF-guarded), `web_search`.
- Conformance + adversarial red-line eval suites; 20 sample agents.

**On the roadmap — NOT wired today (don't depend on these yet):**

- **Single-turn only.** No multi-turn conversation history or context-window management yet — each `run()` is one intent → one output.
- **Capability *pledge* enforcement** (the structural "an agent can only call what it pledged" floor) is implemented but not yet enforced in the runtime. Today's enforced guarantee is the manifest red-lines above.
- **Semantic + LLM-judge cascade** layers are opt-in/experimental; the default gate is deterministic only.
- **Spend / cost caps** are not in the public package yet.
- **Sandbox network-isolation**, **multi-agent orchestration**, **write/exec tools** (`file_write`, `bash`, `image_gen`), and **streaming** are planned.

See the [changelog](./CHANGELOG.md) and the Charter for the full picture. Small ship, real signal.

*Apache-2.0. Built in the open.*
