agent-supra 1.0.0__py3-none-any.whl

agent_supra/__init__.py

@@ -0,0 +1,27 @@
+"""Agent Supra: notice when an unattended agent is stuck, pause it, show why.
+
+The SDK (this package's top level) has no dependencies. The server lives in
+``agent_supra.server`` and needs ``pip install 'agent-supra[server]'``.
+"""
+
+__version__ = "1.0.0"
+
+from .client import Client, SupervisorAPIError, SupervisorUnavailable  # noqa: E402
+from .detector import DEFAULT_POLICY, Finding, evaluate  # noqa: E402
+from .pricing import estimate_cost_micros, register_price  # noqa: E402
+from .sdk import SupervisedRun, SupervisorPaused, error_fingerprint, fingerprint  # noqa: E402
+
+__all__ = [
+    "Client", "SupervisedRun", "SupervisorPaused", "SupervisorAPIError", "SupervisorUnavailable",
+    "DEFAULT_POLICY", "Finding", "evaluate", "estimate_cost_micros", "register_price",
+    "error_fingerprint", "fingerprint", "Supervisor", "SupervisorError",
+]
+
+
+def __getattr__(name):
+    # Local, in-process supervisor (needs the server extra). Imported lazily so the
+    # SDK stays dependency-free.
+    if name in ("Supervisor", "SupervisorError"):
+        from . import server
+        return getattr(server, name)
+    raise AttributeError(name)

agent_supra/cli.py

@@ -0,0 +1,88 @@
+"""Command line: ``agent-supra serve | migrate | create-user | prune | demo``."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import sys
+
+
+def _settings():
+    from .server.settings import Settings
+    return Settings.from_env()
+
+
+def cmd_serve(args) -> int:
+    import uvicorn
+    from .server import db
+    db.migrate(db.make_engine(_settings().database_url))   # once, before workers start
+    uvicorn.run("agent_supra.server.app:create_app", factory=True, host=args.host, port=args.port,
+                workers=args.workers, proxy_headers=True, forwarded_allow_ips=os.environ.get("FORWARDED_ALLOW_IPS", "*"),
+                log_level="info")
+    return 0
+
+
+def cmd_migrate(_args) -> int:
+    from .server import db
+    version = db.migrate(db.make_engine(_settings().database_url))
+    print(f"Database is at schema version {version}.")
+    return 0
+
+
+def cmd_create_user(args) -> int:
+    from .server.accounts import Accounts
+    from .server.core import Supervisor, SupervisorError
+    sup = Supervisor(_settings().database_url)
+    password = os.environ.get("AGENT_SUPRA_NEW_PASSWORD") or getpass.getpass("Password (10+ characters): ")
+    try:
+        _, workspace = Accounts(sup.engine).signup(args.email, password, args.workspace)
+    except SupervisorError as exc:
+        print(f"Couldn't create the user: {exc}", file=sys.stderr)
+        return 1
+    print(f"Created {args.email} with workspace {workspace}.")
+    return 0
+
+
+def cmd_prune(args) -> int:
+    from .server.core import Supervisor
+    days = args.days if args.days is not None else _settings().retention_days
+    removed = Supervisor(_settings().database_url).prune(days)
+    print(f"Removed {removed} run(s) older than {days} days.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["demo"]:
+        # Hand everything after "demo" to the demo's own parser (--observe, --report, ...).
+        from .demo import main as demo_main
+        return demo_main(argv[1:])
+    parser = argparse.ArgumentParser(prog="agent-supra", description="Agent Supra server tools")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="run the web server (reads DATABASE_URL, BASE_URL, ...)")
+    serve.add_argument("--host", default=os.environ.get("HOST", "0.0.0.0"))
+    serve.add_argument("--port", type=int, default=int(os.environ.get("PORT", "8000")))
+    serve.add_argument("--workers", type=int, default=int(os.environ.get("WEB_CONCURRENCY", "2")))
+    serve.set_defaults(fn=cmd_serve)
+
+    sub.add_parser("migrate", help="create or upgrade database tables").set_defaults(fn=cmd_migrate)
+
+    user = sub.add_parser("create-user", help="create an account (useful with ALLOW_SIGNUP=false)")
+    user.add_argument("email")
+    user.add_argument("--workspace", help="workspace name")
+    user.set_defaults(fn=cmd_create_user)
+
+    prune = sub.add_parser("prune", help="delete runs older than the retention window")
+    prune.add_argument("--days", type=int)
+    prune.set_defaults(fn=cmd_prune)
+
+    sub.add_parser("demo", help="run the two-agent demo locally (try: agent-supra demo --help)")
+
+    args = parser.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_supra/client.py

@@ -0,0 +1,240 @@
+"""HTTP client for the hosted (or self-hosted) supervisor. Standard library only.
+
+    sup = Client()   # reads AGENT_SUPRA_API_KEY and AGENT_SUPRA_URL
+
+If the service can't be reached, ``fail_mode`` decides what your agent does:
+
+* ``"open"`` (default): keep working. Events are buffered in memory and sent
+  when the service is reachable again; tasks and runs are created then too.
+* ``"closed"``: treat it as paused (``SupervisorPaused`` is raised on the next
+  step). Use this when an unsupervised agent is worse than a stopped one.
+
+Authentication or permission errors (401/403) always raise immediately: they
+mean the configuration is wrong, and retrying won't fix them.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from collections import deque
+from typing import Any, Callable
+
+from . import __version__
+
+log = logging.getLogger("agent_supra")
+DEFAULT_URL = "http://localhost:8000"
+BATCH = 500
+
+
+class SupervisorUnavailable(Exception):
+    """The service couldn't be reached (network error, timeout, 5xx, rate limit)."""
+
+
+class SupervisorAPIError(Exception):
+    """The service rejected the request (bad key, bad input, unknown run)."""
+
+    def __init__(self, status: int, message: str):
+        self.status = status
+        super().__init__(f"{status}: {message}")
+
+
+Transport = Callable[[str, str, dict | None, dict], tuple[int, dict]]
+
+
+class Client:
+    def __init__(self, api_key: str | None = None, base_url: str | None = None, fail_mode: str = "open",
+                 timeout: float = 5.0, retries: int = 2, max_buffer: int = 5000,
+                 transport: Transport | None = None):
+        self.api_key = api_key or os.environ.get("AGENT_SUPRA_API_KEY")
+        if not self.api_key:
+            raise ValueError("No API key: pass api_key= or set AGENT_SUPRA_API_KEY")
+        if fail_mode not in ("open", "closed"):
+            raise ValueError("fail_mode must be 'open' or 'closed'")
+        self.base_url = (base_url or os.environ.get("AGENT_SUPRA_URL") or DEFAULT_URL).rstrip("/")
+        self.fail_mode = fail_mode
+        self.timeout = timeout
+        self.retries = retries
+        self.max_buffer = max_buffer
+        self._transport = transport or self._urllib
+        self._lock = threading.RLock()
+        self._tasks: dict[str, str] = {}             # local id -> server id
+        self._pending_tasks: dict[str, dict] = {}
+        self._runs: dict[str, str] = {}
+        self._pending_runs: dict[str, tuple[str, str | None]] = {}
+        self._buffers: dict[str, deque] = {}
+        self._warned = False
+        self._down_until = 0.0
+        self.cooldown = 30.0   # after an outage, skip the network for this long
+        self.dropped_events = 0
+
+    # ------------------------------------------------------------------ transport
+    def _urllib(self, method: str, path: str, body: dict | None, params: dict) -> tuple[int, dict]:
+        url = self.base_url + path + (("?" + urllib.parse.urlencode(params)) if params else "")
+        data = json.dumps(body).encode() if body is not None else None
+        request = urllib.request.Request(url, data=data, method=method, headers={
+            "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json",
+            "Accept": "application/json", "User-Agent": f"agent-supra/{__version__}"})
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:  # noqa: S310
+                return response.status, json.loads(response.read() or b"{}")
+        except urllib.error.HTTPError as exc:
+            try:
+                payload = json.loads(exc.read() or b"{}")
+            except ValueError:
+                payload = {}
+            return exc.code, payload
+
+    def _call(self, method: str, path: str, body: dict | None = None, params: dict | None = None) -> dict:
+        if time.monotonic() < self._down_until:
+            raise SupervisorUnavailable("in cooldown after a recent outage")
+        delay = 0.25
+        last: Exception | None = None
+        for attempt in range(self.retries + 1):
+            try:
+                status, payload = self._transport(method, path, body, params or {})
+            except (OSError, ValueError) as exc:   # URLError, timeouts, bad JSON
+                last = SupervisorUnavailable(str(exc))
+            else:
+                if status < 400:
+                    return payload
+                message = payload.get("error") or payload.get("detail") or "request failed"
+                if status in (429, 500, 502, 503, 504):
+                    last = SupervisorUnavailable(f"{status}: {message}")
+                else:
+                    raise SupervisorAPIError(status, str(message))
+            if attempt < self.retries:
+                time.sleep(delay)
+                delay *= 3
+        self._down_until = time.monotonic() + self.cooldown
+        raise last or SupervisorUnavailable("unknown error")
+
+    def _degraded(self, why: Exception) -> dict:
+        if not self._warned:
+            log.warning("Agent Supra unreachable (%s); fail_mode=%s", why, self.fail_mode)
+            self._warned = True
+        if self.fail_mode == "open":
+            return {"allowed": True, "state": "unknown", "reason": "supervisor unreachable", "degraded": True}
+        return {"allowed": False, "state": "unreachable",
+                "reason": "supervisor unreachable and fail_mode is 'closed'", "degraded": True}
+
+    # ------------------------------------------------------------------ id resolution
+    def _resolve_task(self, task_id: str) -> str:
+        if task_id in self._pending_tasks:
+            real = self._call("POST", "/v1/tasks", self._pending_tasks[task_id])["task_id"]
+            self._tasks[task_id] = real
+            del self._pending_tasks[task_id]
+        return self._tasks.get(task_id, task_id)
+
+    def _resolve_run(self, run_id: str) -> str:
+        if run_id in self._pending_runs:
+            task_id, parent = self._pending_runs[run_id]
+            body = {"parent_run_id": self._resolve_run(parent) if parent else None}
+            real = self._call("POST", f"/v1/tasks/{self._resolve_task(task_id)}/runs", body)["run_id"]
+            self._runs[run_id] = real
+            del self._pending_runs[run_id]
+        return self._runs.get(run_id, run_id)
+
+    # ------------------------------------------------------------------ backend interface
+    def create_task(self, objective: str, budget_usd: float | None = None, max_calls: int | None = None,
+                    policy: dict | None = None) -> str:
+        body = {"objective": objective, "budget_usd": budget_usd, "max_calls": max_calls, "policy": policy}
+        with self._lock:
+            try:
+                return self._call("POST", "/v1/tasks", body)["task_id"]
+            except SupervisorUnavailable as exc:
+                self._degraded(exc)
+                local = f"pending_task_{uuid.uuid4().hex[:12]}"
+                self._pending_tasks[local] = body
+                return local
+
+    def create_run(self, task_id: str, parent_run_id: str | None = None) -> str:
+        with self._lock:
+            try:
+                parent = self._resolve_run(parent_run_id) if parent_run_id else None
+                return self._call("POST", f"/v1/tasks/{self._resolve_task(task_id)}/runs",
+                                  {"parent_run_id": parent})["run_id"]
+            except SupervisorUnavailable as exc:
+                self._degraded(exc)
+                local = f"pending_run_{uuid.uuid4().hex[:12]}"
+                self._pending_runs[local] = (task_id, parent_run_id)
+                return local
+
+    def ingest(self, run_id: str, event: dict) -> dict:
+        with self._lock:
+            buffer = self._buffers.setdefault(run_id, deque())
+            buffer.append(event)
+            while len(buffer) > self.max_buffer:
+                buffer.popleft()
+                self.dropped_events += 1
+            try:
+                decision = self._flush(run_id)
+            except SupervisorUnavailable as exc:
+                return self._degraded(exc)
+            return decision if decision is not None else self.decide(run_id)
+
+    def _flush(self, run_id: str) -> dict | None:
+        buffer = self._buffers.get(run_id)
+        if not buffer:
+            return None
+        real = self._resolve_run(run_id)
+        decision = None
+        while buffer:
+            chunk = [buffer[i] for i in range(min(BATCH, len(buffer)))]
+            try:
+                decision = self._call("POST", f"/v1/runs/{real}/events", {"events": chunk})
+            except SupervisorAPIError as exc:
+                if exc.status in (401, 403):
+                    raise
+                log.error("Agent Supra rejected %d event(s): %s", len(chunk), exc)
+                decision = None
+            for _ in chunk:
+                buffer.popleft()
+        self._warned = False
+        return decision
+
+    def decide(self, run_id: str, before_model_call: bool = False) -> dict:
+        with self._lock:
+            try:
+                self._flush(run_id)
+                real = self._resolve_run(run_id)
+                decision = self._call("GET", f"/v1/runs/{real}/decision",
+                                      params={"before_model_call": "true" if before_model_call else "false"})
+                self._warned = False
+                return decision
+            except SupervisorUnavailable as exc:
+                return self._degraded(exc)
+
+    def flush(self) -> bool:
+        """Try to send everything buffered. True if nothing is left."""
+        with self._lock:
+            for run_id in list(self._buffers):
+                try:
+                    self._flush(run_id)
+                except SupervisorUnavailable:
+                    return False
+            return not any(self._buffers.values())
+
+    # ------------------------------------------------------------------ reviewer actions
+    def pause(self, run_id: str, reason: str = "") -> dict:
+        return self._call("POST", f"/v1/runs/{self._resolve_run(run_id)}/pause", {"reason": reason})
+
+    def continue_run(self, run_id: str, reason: str, add_budget_usd: float = 0.0) -> dict:
+        return self._call("POST", f"/v1/runs/{self._resolve_run(run_id)}/continue",
+                          {"reason": reason, "add_budget_usd": add_budget_usd})
+
+    def stop(self, run_id: str, reason: str = "") -> dict:
+        return self._call("POST", f"/v1/runs/{self._resolve_run(run_id)}/stop", {"reason": reason})
+
+    def timeline(self, run_id: str) -> dict[str, Any]:
+        return self._call("GET", f"/v1/runs/{self._resolve_run(run_id)}/timeline")
+
+    def whoami(self) -> dict:
+        return self._call("GET", "/v1/whoami")

agent_supra/demo.py

@@ -0,0 +1,202 @@
+"""Two-run demo: one agent gets stuck and is paused, one struggles but succeeds untouched.
+
+    python -m agent_supra.demo                 # pausing enabled for loop rules
+    python -m agent_supra.demo --observe       # observation mode: flag only
+    python -m agent_supra.demo --http http://localhost:8000   # needs AGENT_SUPRA_API_KEY
+
+Each run works on a real tiny repository in a temp folder and runs real
+pytest. The "model" is scripted (FakeModel) so the demo is free and repeatable;
+swap in a real client via ``run.wrap_anthropic(anthropic.Anthropic())``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+from types import SimpleNamespace
+
+from .pricing import usd
+from .report import render_report
+from .sdk import SupervisedRun, SupervisorPaused
+
+SOURCE = '''def apply_discount(price: float, pct: float) -> float:
+    """Return the price after a percentage discount (pct is 0-100)."""
+    return {expr}
+'''
+
+TESTS = '''from shop import apply_discount
+
+
+def test_no_discount():
+    assert apply_discount(100, 0) == 100
+
+
+def test_ten_percent():
+    assert apply_discount(100, 10) == 90
+
+
+def test_full_discount():
+    assert apply_discount(100, 100) == 0
+
+
+def test_returns_number():
+    assert isinstance(apply_discount(50, 20), (int, float))
+'''
+
+BUG = "price * pct"
+
+# Every attempt edits the code, but the same two tests keep failing.
+STUCK_PATCHES = [
+    "price * (1 - pct)",
+    "price * (1 + pct / 100)",
+    "price + pct * 0",
+    "price / (1 + pct)",
+    "round(price * (1 - pct), 2)",
+    "price - pct * 0.1",
+    "price * (1 - pct) + 0",
+    "abs(price * (1 - pct))",
+]
+
+# Fails twice, changes approach, passes.
+HEALTHY_PATCHES = [
+    "price * (1 - pct)",
+    "price * (1 + pct / 100)",
+    "price * (100 - pct) / 100",
+]
+
+
+# ---------------------------------------------------------------- the sandbox repo
+def make_repo() -> Path:
+    repo = Path(tempfile.mkdtemp(prefix="supervised-repo-"))
+    (repo / "shop.py").write_text(SOURCE.format(expr=BUG))
+    (repo / "test_shop.py").write_text(TESTS)
+    return repo
+
+
+def rev(repo: Path) -> str:
+    return hashlib.sha1((repo / "shop.py").read_bytes()).hexdigest()[:10]
+
+
+def edit_file(repo: Path, expr: str) -> None:
+    (repo / "shop.py").write_text(SOURCE.format(expr=expr))
+
+
+@dataclass
+class SuiteResult:
+    suite: list[str]
+    failing: list[str]
+
+
+def run_tests(repo: Path) -> SuiteResult:
+    report = repo / ".junit.xml"
+    subprocess.run([sys.executable, "-m", "pytest", "-q", "-p", "no:cacheprovider",
+                    f"--junitxml={report}"], cwd=repo, capture_output=True, text=True, timeout=120)
+    suite, failing = [], []
+    for case in ET.parse(report).getroot().iter("testcase"):
+        test_id = f"{case.get('classname')}::{case.get('name')}"
+        suite.append(test_id)
+        if case.find("failure") is not None or case.find("error") is not None:
+            failing.append(test_id)
+    return SuiteResult(suite, failing)
+
+
+# ---------------------------------------------------------------- a scripted "model"
+class FakeModel:
+    """Looks like ``anthropic.Anthropic()`` to the SDK. Context grows every turn,
+    the way a real agent transcript does."""
+
+    def __init__(self, patches: list[str]):
+        self._patches = list(patches)
+        self._turn = 0
+        self.messages = self
+
+    def create(self, model: str, messages: list, max_tokens: int = 1024, **_):
+        patch = self._patches[min(self._turn, len(self._patches) - 1)]
+        usage = SimpleNamespace(input_tokens=12_000 + 9_000 * self._turn, output_tokens=800)
+        self._turn += 1
+        return SimpleNamespace(model=model, usage=usage,
+                               content=[SimpleNamespace(type="text", text=patch)])
+
+
+# ---------------------------------------------------------------- the agent loop
+def run_agent(backend, task_id: str, patches: list[str], max_steps: int = 8, log=print) -> str:
+    repo = make_repo()
+    with SupervisedRun(backend, task_id) as run:
+        client = run.wrap_anthropic(FakeModel(patches))
+        result = run.tool("run_tests", run_tests, repo, rev=rev(repo))
+        run.report_tests(result.suite, result.failing, rev=rev(repo))
+        log(f"  start: {len(result.failing)} failing test(s)")
+        try:
+            for step in range(1, max_steps + 1):
+                run.check()
+                reply = client.messages.create(model="demo-model", max_tokens=1024,
+                                               messages=[{"role": "user", "content": "Fix the failing tests."}])
+                patch = reply.content[0].text
+                run.tool("edit_file", edit_file, repo, patch, rev=rev(repo))
+                result = run.tool("run_tests", run_tests, repo, rev=rev(repo))
+                decision = run.report_tests(result.suite, result.failing, rev=rev(repo))
+                status = "all tests pass" if not result.failing else f"{len(result.failing)} failing"
+                log(f"  attempt {step}: return {patch:<28} -> {status}")
+                if not result.failing:
+                    run.finish("success")
+                    return run.run_id
+                if not decision["allowed"]:
+                    raise SupervisorPaused(decision)
+            run.finish("failed")
+        except SupervisorPaused as paused:
+            log(f"  PAUSED by supervisor: {paused.reason}")
+    return run.run_id
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--observe", action="store_true", help="observation mode: flag, never pause")
+    parser.add_argument("--db", default=":memory:", help="SQLite file (default: in memory)")
+    parser.add_argument("--http", help="send events to a running supervisor API instead")
+    parser.add_argument("--report", default="supervisor_report.html", help="where to write the HTML report")
+    args = parser.parse_args(argv)
+    try:
+        import pytest  # noqa: F401  (the sample repo's tests run under pytest)
+    except ImportError:
+        print("The demo runs real tests and needs pytest: pip install pytest")
+        return 1
+
+    policy = {"observation_mode": args.observe}
+    if args.http:
+        from .client import Client
+        backend, sup = Client(base_url=args.http), None
+    else:
+        from .server import Supervisor
+        backend = sup = Supervisor("sqlite://" if args.db == ":memory:" else f"sqlite:///{args.db}")
+
+    mode = "observation mode (flag only)" if args.observe else "pausing enabled"
+    print(f"Agent Supra demo · {mode}\n")
+    print("Run A: an agent that keeps editing code while the same tests fail")
+    task_a = backend.create_task("Run A: stuck agent fixing apply_discount", budget_usd=5.0, policy=policy)
+    run_a = run_agent(backend, task_a, STUCK_PATCHES)
+    print("\nRun B: an agent that fails twice, changes approach, and succeeds")
+    task_b = backend.create_task("Run B: healthy agent fixing apply_discount", budget_usd=5.0, policy=policy)
+    run_b = run_agent(backend, task_b, HEALTHY_PATCHES)
+
+    if sup is not None:
+        print()
+        for run_id in (run_a, run_b):
+            tl = sup.timeline(run_id)
+            flags = [i for i in tl["interventions"] if i["actor"] == "supervisor"]
+            print(f"{tl['task']['objective'].split(':')[0]}: {tl['run']['state']}, "
+                  f"estimated spend {usd(tl['run_spend_micros'])}, "
+                  f"{len(flags)} supervisor intervention(s)"
+                  + "".join(f"\n   - {f['action']} [{f['rule']}] {f['message']}" for f in flags))
+        Path(args.report).write_text(render_report(sup, [run_a, run_b]))
+        print(f"\nTimeline report written to {args.report}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())