openroar 1.0.0b1

The safe interface between any agent and any LLM. Manifest-enforced. Audit-logged. Apache 2.0.

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

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 — 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.

---

Install

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

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:

openroar doctor          # diagnoses missing keys / config with exact fixes

Full walkthrough: 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:

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:

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.

Start from the bundled examples in 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.

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

---

Contributing & security

• CONTRIBUTING.md — dev setup, proposing a sample agent, the spec-and-ADR discipline.
• SECURITY.md — coordinated disclosure. Please report vulnerabilities privately.
• 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 and the Charter for the full picture. Small ship, real signal.

Apache-2.0. Built in the open.