Metadata-Version: 2.4
Name: openroar
Version: 1.0.0b2
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**

```bash
pip install openroar
openroar init                                   # scaffolds ./agents/hello.md, picks a backend
openroar chat hello --intent "Name three fruits."
```

`openroar init` works with zero setup: with no API key and no local model yet, it pins a deterministic offline provider so your first *gated* agent responds immediately — then `openroar doctor` shows you how to add a real model. The same agent from Python:

```python
from openroar import Agent, run

agent = Agent.from_soul("agents/hello.md")      # created by `openroar init`
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.)
- **Gated agentic loop** — agents don't just answer; they *act*. The model calls a tool, the result is fed back, and it works across turns toward a goal — and **every** turn, tool call, and tool result passes the same gate (SOUL tool allow-list, path allowlist + denylist + size cap, tool-result quarantine, audit). An autonomous `openroar tick` can pursue a standing goal on a schedule, bounded by a step-count and a kill switch (not a cost ceiling — spend caps aren't shipped), with a human-approval gate for irreversible steps. See [Status](#status).
- **First-party vault** — an opt-in encrypted store (AES-256-GCM + Argon2id) for your API keys, reached via `openroar vault`; agents request access by name, and raw secrets never enter agent context. Without the vault, keys come from environment variables or a chmod-600 `~/.openroar/secrets.env` file (plaintext on disk) — encryption is the vault backend you opt into.
- **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

```bash
pip install openroar
# providers are optional extras — add what you use:
pip install 'openroar[anthropic]'   # or [openai], [gemini], [groq], [ollama], [all]
```

Or install from source for a full reference instance:

```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 `SOUL.md` file with a YAML frontmatter header (who it is and which manifest gates it) and a markdown body that becomes its system prompt:

```markdown
---
name: summariser
model: ollama:llama3.2:3b        # provider:model-id — or anthropic:claude-..., openai:gpt-..., etc.
manifest: safe-default           # the red-line policy this agent runs under
tools: [file_read]               # tools the agent may call in the agentic loop
---

You read a local markdown file and return a plain-english summary.
You decline politely if the manifest blocks the request.
```

The declared `tools` are the loop's allow-list (an agent can only call what it lists); *what it must never do* — the red-lines — comes from the `manifest`, not from SOUL fields.

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 its manifest'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.

Want to verify the safety claims yourself — fire the gate, run the conformance suite, check the audit log is tamper-evident? See [Evaluating openroar](./docs/guides/evaluating-openroar.md).

---

## 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** — deterministic red-line checks (keyword + regex, evasion-normalised) before the intent and after the output, on every model call, plus a **non-removable system-overlay floor** every agent inherits (an agent cannot point the gate at a weaker manifest).
- **Multi-turn agentic loop** (`run_agent`) — the model proposes a tool, the result is fed back, it acts on it, and the loop continues until it's done or a `max_turns` bound is hit; every turn is gated + audited. Works on Anthropic, Ollama, OpenAI, Groq. Validated end-to-end against a real model.
- **Tool execution** — `file_read` + `http_fetch` (SSRF-guarded) are advertised to the model and run **gated**: SOUL tool allow-list + `file_read`'s workspace-root path allowlist, sensitive-file denylist, and size cap + a tool-result (`TOOL_RESULT`) quarantine that blocks injected/dangerous content before it re-enters the agent. (The read itself is a direct filesystem read — OS-level sandbox containment and network isolation are *not* enforced yet; see the roadmap.)
- **Coordinator → specialist orchestration** — a coordinator delegates to specialists, each a *separate gated `run()`* (no ungated path; delegation is downward-only, so the audit trail is a tree).
- **Autonomous scheduler** — `openroar tick` (cron-runnable) takes the next gated step toward a standing goal, backed by a **persistent, hash-chained goal/step store** (continuity across wakes), a file **kill switch** (`openroar kill`, instant + restart-survivable), and a **human-in-the-loop approval gate** for irreversible steps (`openroar decide`).
- First-party **opt-in** encrypted vault (AES-256-GCM + Argon2id) via `openroar vault`; keys never enter agent context. (The default fallback secret store is a chmod-600 `~/.openroar/secrets.env` — plaintext on disk; encryption is the vault you opt into.)
- Append-only, hash-chained **audit log with Ed25519-signed Merkle snapshots** (signing key in the OS keyring); `openroar audit verify` checks the chain + signatures.
- Provider adapters for Anthropic, OpenAI, Gemini, Groq, local Ollama; consent gate for remote providers (no silent network egress).
- Conformance + adversarial red-line eval suites; 20 sample agents.

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

- **Gemini multi-turn + tool-calling** — deferred while the `google.generativeai` SDK is deprecated (a `google.genai` migration is pending); Gemini is single-shot only today. The other four providers cover the loop.
- **Parallel multi-agent fan-out** and an autonomous orchestration loop beyond a single synchronous coordinator.
- **Write/exec tools** (`file_write`, `bash`) and their four-gate install pipeline. **OS-level sandbox containment and network isolation** for tools are **not enforced** — `file_read` detects a sandbox backend but reads directly; today's tool guarantees are the path allowlist + denylist + size cap + `TOOL_RESULT` quarantine.
- **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** — the deterministic floor is the guaranteed gate; the LLM-judge layer engages when a judge provider is reachable, and the semantic layer is parked.
- **EVOI-scored auto-detection** of *which* steps need human approval — the pause/approve/resume mechanism exists; flagging an irreversible step is agent-signalled today, not auto-classified.
- **Spend / cost caps** and **streaming** are not in the public package yet.

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

*Apache-2.0. Built in the open.*
