openroar 1.0.0b1__py3-none-any.whl

openroar/__init__.py

@@ -0,0 +1,56 @@
+"""openroar — the safe interface between any agent and any LLM.
+
+The manifesto pledges: artificial intelligence should serve the people who use
+it, not the people who own it. This package is that pledge in code.
+
+Five-line hello world:
+
+    from openroar import Agent, run
+    agent = Agent.from_soul("agents/example/safe-default.md")
+    result = run(agent, "Summarize today's news in 3 bullets.")
+    print(result.text)
+
+Behind that: the agent's manifest is checked before and after every model call,
+every action is audit-logged (append-only, hash-chained), and the provider is
+swappable by changing one config field. Manifest. Audit. Provider-agnostic. Open.
+
+License: Apache-2.0. Charter: https://openroar.org/charter
+"""
+
+from openroar.__version__ import __version__
+from openroar.agent import Agent
+from openroar.audit import AuditLog
+from openroar.consent import (
+    ConsentDecision,
+    ConsentDeclined,
+    ConsentPolicy,
+    ConsentScope,
+)
+from openroar.errors import (
+    AuditError,
+    ConfigError,
+    OpenroarError,
+    ProviderError,
+)
+from openroar.manifest import Manifest, ManifestViolation, load_manifest
+from openroar.runtime import Result, RunConfig, run
+
+__all__ = [
+    "Agent",
+    "AuditError",
+    "AuditLog",
+    "ConfigError",
+    "ConsentDecision",
+    "ConsentDeclined",
+    "ConsentPolicy",
+    "ConsentScope",
+    "Manifest",
+    "ManifestViolation",
+    "OpenroarError",
+    "ProviderError",
+    "Result",
+    "RunConfig",
+    "__version__",
+    "load_manifest",
+    "run",
+]

openroar/__version__.py

@@ -0,0 +1,7 @@
+"""Single source of version truth.
+
+Bumping this triggers a release.
+1.x.y is the beta line; 2.0 requires a Charter Article 26 amendment.
+"""
+
+__version__ = "1.0.0b1"

openroar/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""Internal helpers — not part of the public API.
+
+Anything here may change without semver. Import from `openroar.*` (the public
+surface) instead.
+"""

openroar/_internal/eggs.py

@@ -0,0 +1,263 @@
+"""Easter-egg registry + scanner per VM16 (2026-05-28 23:59 CEST).
+
+VM16 directive: AG wants a marker convention he can plant throughout the
+codebase + docs + manifests at *intent time*, before he's decided what the
+egg's payload is. Later, each marker is defined and activated (or retired)
+through the registry.
+
+Design choices (AG steering 2026-05-29):
+- **Marker form:** `ROAR::EGG(slug, hint="...")` inside the host file's native
+  comment syntax. Parser-safe in Python / YAML / Markdown / HTML / shell.
+- **Registry:** central sidecar at `eggs/REGISTRY.yaml`.
+- **Payloads through manifest:** any egg whose payload *executes behaviour*
+  (rather than just reveals text) goes through `openroar.runtime.run` like any
+  other agent action. The surprise is discovery, not safety bypass.
+- **Lifecycle:** unplanted → planted → defined → live → retired.
+  Special: `legacy-proposal` for items carried from prior design docs that
+  haven't been re-ratified by AG.
+
+Public surface:
+    scan_repo(root)         → list[MarkerHit]
+    load_registry(path)     → dict
+    validate(root, registry) → ValidationReport
+    transitions(state)      → list of valid next states
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+# ─── Marker syntax ──────────────────────────────────────────────────────────
+# Captures: ROAR::EGG(slug-here)  OR  ROAR::EGG(slug-here, hint="...")
+# Slug = lowercase kebab-case; hint = optional double-quoted string.
+MARKER_RE = re.compile(
+    r"""
+    ROAR::EGG\(
+        \s*
+        (?P<slug>[a-z][a-z0-9-]+)
+        (?:
+            \s*,\s*
+            hint\s*=\s*
+            "(?P<hint>[^"]*)"
+        )?
+        \s*
+    \)
+    """,
+    re.VERBOSE,
+)
+
+# File extensions worth scanning. Other types are tolerated but skipped to
+# keep the scan fast and false-positive-free.
+SCAN_EXTENSIONS = {
+    ".py", ".pyi", ".md", ".markdown",
+    ".yaml", ".yml", ".toml",
+    ".html", ".htm", ".css", ".js", ".ts",
+    ".sh", ".bash", ".zsh",
+    ".txt", ".cfg", ".ini", ".conf",
+}
+
+# Lifecycle states.
+VALID_STATUSES = {
+    "unplanted",       # registered but no marker exists in code yet
+    "legacy-proposal", # carried from prior design doc; awaiting AG ratification
+    "planted",         # marker exists in code; payload undefined
+    "defined",         # payload exists in registry; not activated/shipped
+    "live",            # payload is active in the running system
+    "retired",         # kept for audit; no longer active
+}
+
+# Allowed transitions per state. Used by `openroar egg <transition>` CLI.
+TRANSITIONS: dict[str, set[str]] = {
+    "unplanted":       {"planted", "retired"},
+    "legacy-proposal": {"planted", "live", "retired"},  # may go live if already shipped
+    "planted":         {"defined", "retired"},
+    "defined":         {"live", "retired"},
+    "live":            {"retired"},
+    "retired":         set(),
+}
+
+
+@dataclass(frozen=True)
+class MarkerHit:
+    """One occurrence of `ROAR::EGG(slug, ...)` in the source tree."""
+
+    slug: str
+    hint: str | None
+    path: Path
+    line: int
+
+
+@dataclass
+class ValidationReport:
+    """Discrepancies between markers in code and entries in the registry."""
+
+    in_code_not_in_registry: list[str]
+    in_registry_not_in_code: list[str]
+    in_both: list[str]
+    duplicate_slugs_in_code: dict[str, list[Path]]
+    status_implied_violations: list[str]  # e.g. status=planted but slug not found in code
+
+    def ok(self) -> bool:
+        return not (
+            self.in_code_not_in_registry
+            or self.duplicate_slugs_in_code
+            or self.status_implied_violations
+        )
+
+
+def scan_repo(root: Path) -> list[MarkerHit]:
+    """Walk `root`, return every `ROAR::EGG(...)` marker found.
+
+    Skips `.git`, `__pycache__`, `node_modules`, `models/ollama/`, the registry
+    file itself, and any file matching `eggs/SCHEMA.md`-class registry docs.
+    """
+    skip_dir_names = {".git", "__pycache__", "node_modules", ".hypothesis", ".pytest_cache"}
+    skip_path_substrings = {"/models/ollama/", "/.venv/", "/data/", "/artifacts/"}
+    skip_files = {root / "eggs" / "REGISTRY.yaml"}
+
+    hits: list[MarkerHit] = []
+    for p in sorted(root.rglob("*")):
+        if not p.is_file():
+            continue
+        if any(part in skip_dir_names for part in p.parts):
+            continue
+        if any(sub in str(p) for sub in skip_path_substrings):
+            continue
+        if p in skip_files:
+            continue
+        if p.suffix.lower() not in SCAN_EXTENSIONS:
+            continue
+        try:
+            content = p.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for m in MARKER_RE.finditer(content):
+            line = content[: m.start()].count("\n") + 1
+            hits.append(
+                MarkerHit(
+                    slug=m.group("slug"),
+                    hint=m.group("hint"),
+                    path=p,
+                    line=line,
+                )
+            )
+    return hits
+
+
+def load_registry(path: Path) -> dict[str, Any]:
+    """Load and lightly validate the YAML registry. Raises on hard schema breaches."""
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"{path}: registry root must be a mapping")
+    if raw.get("schema_version") != 1:
+        raise ValueError(f"{path}: unsupported schema_version {raw.get('schema_version')!r}")
+    eggs = raw.get("eggs") or []
+    if not isinstance(eggs, list):
+        raise ValueError(f"{path}: `eggs` must be a list")
+    for i, egg in enumerate(eggs):
+        if not isinstance(egg, dict):
+            raise ValueError(f"{path}: egg #{i} must be a mapping")
+        slug = egg.get("slug")
+        if not slug or not isinstance(slug, str):
+            raise ValueError(f"{path}: egg #{i} missing/invalid `slug`")
+        if egg.get("status") not in VALID_STATUSES:
+            raise ValueError(
+                f"{path}: egg {slug!r} has invalid status {egg.get('status')!r}; "
+                f"must be one of {sorted(VALID_STATUSES)}"
+            )
+        tags = egg.get("tags", [])
+        if tags is not None and not isinstance(tags, list):
+            raise ValueError(f"{path}: egg {slug!r} has non-list tags: {tags!r}")
+        for tag in tags or []:
+            if not isinstance(tag, str) or not re.match(r"^[a-z][a-z0-9-]+$", tag):
+                raise ValueError(
+                    f"{path}: egg {slug!r} has invalid tag {tag!r}; tags must be kebab-case strings"
+                )
+    return raw
+
+
+def by_tag(registry: dict[str, object], tag: str) -> list[dict[str, object]]:
+    """Return all eggs whose `tags` list contains `tag`."""
+    eggs = registry.get("eggs") or []
+    out: list[dict[str, object]] = []
+    for e in eggs:
+        if not isinstance(e, dict):
+            continue
+        tags = e.get("tags") or []
+        if isinstance(tags, list) and tag in tags:
+            out.append(e)
+    return out
+
+
+def all_tags(registry: dict[str, object]) -> dict[str, int]:
+    """Return {tag: count} across the whole registry."""
+    counts: dict[str, int] = {}
+    eggs = registry.get("eggs") or []
+    for e in eggs:
+        if not isinstance(e, dict):
+            continue
+        for tag in e.get("tags") or []:
+            if isinstance(tag, str):
+                counts[tag] = counts.get(tag, 0) + 1
+    return counts
+
+
+def validate(root: Path, registry: dict[str, Any]) -> ValidationReport:
+    """Cross-reference code markers against the registry."""
+    hits = scan_repo(root)
+    code_slugs: dict[str, list[Path]] = {}
+    for h in hits:
+        code_slugs.setdefault(h.slug, []).append(h.path)
+
+    reg_eggs = registry.get("eggs") or []
+    reg_slug_to_status = {e["slug"]: e.get("status") for e in reg_eggs}
+    reg_slugs = set(reg_slug_to_status.keys())
+
+    in_code = set(code_slugs.keys())
+
+    duplicates = {s: paths for s, paths in code_slugs.items() if len(paths) > 1}
+
+    # Status-implied violations: status=planted requires a marker in code.
+    status_violations: list[str] = []
+    for slug, status in reg_slug_to_status.items():
+        if status == "planted" and slug not in in_code:
+            status_violations.append(
+                f"{slug}: registry status=planted but no ROAR::EGG marker found in code"
+            )
+        if status == "unplanted" and slug in in_code:
+            status_violations.append(
+                f"{slug}: registry status=unplanted but ROAR::EGG marker exists in code "
+                "(promote to planted via `openroar egg promote`)"
+            )
+
+    return ValidationReport(
+        in_code_not_in_registry=sorted(in_code - reg_slugs),
+        in_registry_not_in_code=sorted(reg_slugs - in_code),
+        in_both=sorted(in_code & reg_slugs),
+        duplicate_slugs_in_code=duplicates,
+        status_implied_violations=status_violations,
+    )
+
+
+def transitions(state: str) -> list[str]:
+    """Return the list of valid next states from `state`."""
+    return sorted(TRANSITIONS.get(state, set()))
+
+
+__all__ = [
+    "MARKER_RE",
+    "SCAN_EXTENSIONS",
+    "TRANSITIONS",
+    "VALID_STATUSES",
+    "MarkerHit",
+    "ValidationReport",
+    "load_registry",
+    "scan_repo",
+    "transitions",
+    "validate",
+]

openroar/_internal/env.py

@@ -0,0 +1,67 @@
+"""Environment variable + .env loader for openroar.
+
+Centralised so the framework can document exactly which env vars it reads.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def load_env_file(path: str | Path | None = None) -> None:
+    """Load environment variables from a .env file if present.
+
+    Default search order:
+    1. Path passed explicitly.
+    2. $OPENROAR_ENV_FILE
+    3. ./.env in current directory.
+    4. ~/.openroar/.env
+
+    Existing env vars are NOT overwritten; .env values fill in missing ones only.
+    """
+    candidates: list[Path] = []
+    if path is not None:
+        candidates.append(Path(path))
+    if env_path := os.environ.get("OPENROAR_ENV_FILE"):
+        candidates.append(Path(env_path))
+    candidates.append(Path(".env"))
+    candidates.append(Path.home() / ".openroar" / ".env")
+
+    for candidate in candidates:
+        if candidate.exists() and candidate.is_file():
+            _parse_env_file(candidate)
+            return  # first found wins
+
+
+def _parse_env_file(path: Path) -> None:
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+def get_required(name: str) -> str:
+    """Get an env var or raise ConfigError with a helpful message."""
+    from openroar.errors import ConfigError  # local import to avoid cycle
+
+    value = os.environ.get(name)
+    if value is None or value == "":
+        raise ConfigError(
+            f"Required environment variable {name!r} is not set. "
+            f"Set it via shell, .env file, or your secret manager.",
+            source="env",
+        )
+    return value
+
+
+def get_optional(name: str, default: str | None = None) -> str | None:
+    """Get an env var or return the default."""
+    return os.environ.get(name, default)

openroar/_internal/hardware.py

@@ -0,0 +1,174 @@
+"""Hardware-tier detection.
+
+Returns one of: mac_apple_silicon, linux_x86_gpu, linux_x86_cpu, pi_arm,
+windows_x86, unknown.
+
+Used by `openroar doctor` and `install.sh --local-llm` to pick the right
+default model for the user's machine. The first call writes the tier to
+`~/.openroar/hardware_tier`; subsequent calls read from cache.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import platform
+import shutil
+import subprocess  # nosec B404  # subprocess used for hardware detection (sysctl, lscpu); inputs are static commands only
+from pathlib import Path
+from typing import Literal
+
+Tier = Literal[
+    "mac_apple_silicon",
+    "linux_x86_gpu",
+    "linux_x86_cpu",
+    "pi_arm",
+    "windows_x86",
+    "unknown",
+]
+
+_CACHE_PATH = Path.home() / ".openroar" / "hardware_tier"
+
+
+def _read_cache() -> str | None:
+    try:
+        if _CACHE_PATH.exists():
+            value = _CACHE_PATH.read_text().strip()
+            if value:
+                return value
+    except OSError:
+        pass
+    return None
+
+
+def _write_cache(tier: str) -> None:
+    try:
+        _CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        _CACHE_PATH.write_text(tier + "\n")
+    except OSError:
+        pass
+
+
+def _has_nvidia_gpu(min_vram_mb: int = 8000) -> bool:
+    if not shutil.which("nvidia-smi"):
+        return False
+    try:
+        out = subprocess.run(  # nosec B603,B607 # static command, no user input
+            ["nvidia-smi", "--query-gpu=memory.total", "--format=csv,noheader,nounits"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    if out.returncode != 0:
+        return False
+    for line in out.stdout.splitlines():
+        try:
+            if int(line.strip()) >= min_vram_mb:
+                return True
+        except ValueError:
+            continue
+    return False
+
+
+def _is_raspberry_pi() -> bool:
+    model_path = Path("/proc/device-tree/model")
+    if not model_path.exists():
+        return False
+    try:
+        return "Raspberry Pi" in model_path.read_text(errors="ignore")
+    except OSError:
+        return False
+
+
+def detect_tier(*, use_cache: bool = True) -> Tier:
+    """Return the user's hardware tier.
+
+    With `use_cache=True` (the default), reads from `~/.openroar/hardware_tier`
+    if present. Pass `use_cache=False` to force a re-detection.
+    """
+    if use_cache:
+        cached = _read_cache()
+        if cached in _ALLOWED_TIERS:
+            return cached  # type: ignore[return-value]
+
+    tier = _detect_uncached()
+    _write_cache(tier)
+    return tier
+
+
+def _detect_uncached() -> Tier:
+    system = platform.system()
+    machine = platform.machine().lower()
+
+    if system == "Darwin" and machine in ("arm64", "aarch64"):
+        return "mac_apple_silicon"
+
+    if system == "Linux":
+        if _is_raspberry_pi():
+            return "pi_arm"
+        if machine in ("x86_64", "amd64"):
+            if _has_nvidia_gpu():
+                return "linux_x86_gpu"
+            return "linux_x86_cpu"
+
+    if system == "Windows" or system.startswith(("MINGW", "CYGWIN", "MSYS")):
+        return "windows_x86"
+
+    return "unknown"
+
+
+_ALLOWED_TIERS: set[str] = {
+    "mac_apple_silicon",
+    "linux_x86_gpu",
+    "linux_x86_cpu",
+    "pi_arm",
+    "windows_x86",
+    "unknown",
+}
+
+
+def recommended_default_model(tier: Tier) -> str:
+    """Default `ollama:` model id per hardware tier."""
+    return {
+        "mac_apple_silicon": "ollama:gemma4-e2b",
+        "linux_x86_gpu": "ollama:gemma4-e4b",
+        "linux_x86_cpu": "ollama:gemma4-e2b",
+        "pi_arm": "ollama:gemma3-1b",
+        "windows_x86": "ollama:gemma4-e2b",
+        "unknown": "ollama:gemma3-1b",
+    }[tier]
+
+
+def recommended_fallback_model(tier: Tier) -> str:
+    """Lighter fallback per tier — used when the default model OOMs or isn't pulled."""
+    return {
+        "mac_apple_silicon": "ollama:gemma3-1b",
+        "linux_x86_gpu": "ollama:gemma4-e2b",
+        "linux_x86_cpu": "ollama:gemma3-1b",
+        "pi_arm": "ollama:gemma3-1b",
+        "windows_x86": "ollama:gemma3-1b",
+        "unknown": "ollama:gemma3-1b",
+    }[tier]
+
+
+def cache_path() -> Path:
+    """Return the canonical cache path. Exposed for tests and `openroar doctor`."""
+    return _CACHE_PATH
+
+
+def clear_cache() -> None:
+    """Remove the cached tier (forces re-detection on the next call)."""
+    with contextlib.suppress(FileNotFoundError):
+        _CACHE_PATH.unlink()
+
+
+__all__ = [
+    "Tier",
+    "cache_path",
+    "clear_cache",
+    "detect_tier",
+    "recommended_default_model",
+    "recommended_fallback_model",
+]

openroar/_internal/intro.py

@@ -0,0 +1,82 @@
+"""openroar.intro — the pride-gathering animation (the 5-star onboarding open).
+
+A lion appears. Another draws closer. Another. Suddenly there are seven — the
+pride gathered. The fifth one is the emotional one (🥺) — a small easter egg
+(five is always the emotional number). Then Rory takes it from here.
+
+#neverroaralone, made literal in the first three seconds.
+
+Frame generation is pure + testable. play() animates on a real terminal and
+degrades to a single clean line when piped / NO_COLOR (so CI + logs stay clean).
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import Callable, TextIO
+
+from openroar._internal import style
+
+LION = "\U0001F981"          # 🦁
+EGG_LION = "\U0001F97A"      # 🥺  — the emotional one, position 5
+PRIDE_SIZE = 7
+EGG_POSITION = 5             # 1-indexed: the fifth lion is the soft-hearted egg
+_WIDTH = 30                  # render field width (chars) the pride converges into
+
+
+def _glyph(i: int) -> str:
+    """The i-th (1-indexed) pride member: the egg at position 5, else a lion."""
+    return EGG_LION if i == EGG_POSITION else LION
+
+
+def pride_frames() -> list[str]:
+    """The ordered animation frames: members arrive one by one and converge from
+    a loose spread into a tight pride. Pure → testable.
+
+    Frame k (k=1..PRIDE_SIZE) shows k members; spacing tightens as the pride forms.
+    """
+    frames: list[str] = []
+    for count in range(1, PRIDE_SIZE + 1):
+        members = [_glyph(i) for i in range(1, count + 1)]
+        # spacing: wide while they're still gathering, tight once the pride is whole
+        if count < PRIDE_SIZE:
+            sep = " " * max(1, (PRIDE_SIZE - count))
+        else:
+            sep = " "
+        frames.append(sep.join(members))
+    return frames
+
+
+def final_pride() -> str:
+    """The settled pride (the last frame) — 7 members, the 5th is the egg."""
+    return pride_frames()[-1]
+
+
+def play(
+    stream: TextIO | None = None,
+    *,
+    frame_delay: float = 0.16,
+    enabled: bool | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> None:
+    """Render the pride gathering. On a real TTY: redraw the line per frame. When
+    colour/animation is off (piped, NO_COLOR): print the settled pride once."""
+    out = stream if stream is not None else sys.stdout
+    animate = style.color_enabled(out) if enabled is None else enabled
+
+    if not animate:
+        out.write(style.dim("the pride gathers…\n", enabled=False))
+        out.write(final_pride() + "\n")
+        out.flush()
+        return
+
+    for frame in pride_frames():
+        out.write("\r" + " " * _WIDTH + "\r")  # clear the line
+        out.write("  " + frame)
+        out.flush()
+        sleep(frame_delay)
+    out.write("\n\n")
+    out.write("  " + style.bold("the pride has gathered.", enabled=animate) + " "
+              + style.dim("#neverroaralone", enabled=animate) + "\n")
+    out.flush()