watchlight 0.1.0__py3-none-any.whl

watchlight/__init__.py

@@ -0,0 +1,171 @@
+"""watchlight — Developer Edition.
+
+Govern an AI agent in-process, with zero infrastructure. Decorate a tool with
+an *intent*, load a local policy, run your script, and the policy engine
+authorizes every call — allowing what a policy permits and refusing everything
+else **before the tool body runs**.
+
+    from watchlight import govern, Denied
+
+    govern.load("watchlight.policy.json")     # or govern.allow("permit(...);")
+
+    @govern.tool(intent="research")
+    def web_search(query: str) -> str:
+        ...
+
+The engine is the REAL Watchlight authorization engine (Cedar evaluation + the
+surrounding pipeline) embedded via the ``watchlight-engine`` extension — the
+same authorization model that runs in production, just in-process. Going to
+production is pointing at a running policy service, not a rewrite.
+
+Guarantees that are identical to production and MUST NOT be relaxed here:
+  * **Fail-closed** — no matching policy denies; an unreachable decision denies.
+  * **Explicit intent** — a tool is governed by the intent you declare, never
+    inferred from its name or body.
+  * **Value-free audit** — argument *values* never enter the trail; only who,
+    what intent, which resource, and the decision.
+"""
+
+from __future__ import annotations
+
+import datetime
+import functools
+import json
+import os
+import pathlib
+from typing import Any, Callable, TypeVar
+
+import watchlight_engine as _engine
+
+__all__ = ["Watchlight", "Denied", "govern"]
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+class Denied(PermissionError):
+    """Raised when the policy engine refuses a governed tool call (fail-closed).
+
+    The decorated function's body never runs — the refusal happens *before*
+    the side effect, which is the whole point.
+    """
+
+    def __init__(self, tool: str, intent: str, reason: str) -> None:
+        self.tool = tool
+        self.intent = intent
+        self.reason = reason
+        super().__init__(f"watchlight denied intent '{intent}' on tool/{tool}: {reason}")
+
+
+class Watchlight:
+    """An in-process policy decision point for a single agent.
+
+    Wraps the ``watchlight-engine`` in-process authorization core. Policies are
+    loaded from a local file or added inline; each governed tool call is
+    authorized against them.
+    """
+
+    def __init__(self, agent: str | None = None, audit_dir: str | os.PathLike[str] = ".watchlight") -> None:
+        self._engine = _engine.PolicyEngine()
+        self.agent = agent or os.environ.get("WATCHLIGHT_AGENT", "my-agent")
+        self._audit_path = pathlib.Path(audit_dir) / "audit.jsonl"
+        self._announced = False
+        self._policy_count = 0
+
+    # ── policy loading ──────────────────────────────────────────────
+
+    def allow(self, cedar_code: str, name: str | None = None) -> "Watchlight":
+        """Add one Cedar policy inline. Returns self for chaining."""
+        self._engine.add_policy(
+            json.dumps({"name": name or f"policy-{self._policy_count}", "code": cedar_code})
+        )
+        self._policy_count += 1
+        return self
+
+    def load(self, path: str | os.PathLike[str]) -> "Watchlight":
+        """Load policies from a JSON file — a list of ``{"name", "code"}`` objects
+        (or ``{"policies": [...]}``). Fail-closed: a missing file loads nothing,
+        so every governed call is denied until a policy permits it."""
+        p = pathlib.Path(path)
+        if not p.exists():
+            return self
+        data = json.loads(p.read_text())
+        entries = data if isinstance(data, list) else data.get("policies", [])
+        for entry in entries:
+            self.allow(entry["code"], entry.get("name"))
+        return self
+
+    # ── governing tools ─────────────────────────────────────────────
+
+    def tool(self, intent: str) -> Callable[[_F], _F]:
+        """Decorate a function as a governed tool with the given *intent*.
+
+        On every call the engine authorizes ``(agent, intent, tool/<name>)``.
+        On ALLOW the function runs; on anything else a :class:`Denied` is raised
+        and the body never executes.
+        """
+
+        def decorator(fn: _F) -> _F:
+            resource = f"tool/{fn.__name__}"
+
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                decision, reason = self._authorize(intent, resource)
+                self._audit(intent, resource, decision, reason)
+                if decision != "Allow":
+                    raise Denied(fn.__name__, intent, reason or "no matching policy")
+                return fn(*args, **kwargs)
+
+            return wrapper  # type: ignore[return-value]
+
+        return decorator
+
+    # ── internals ───────────────────────────────────────────────────
+
+    def _authorize(self, intent: str, resource: str) -> tuple[str, str]:
+        response = json.loads(
+            self._engine.authorize(
+                json.dumps(
+                    {
+                        "principal": self.agent,
+                        "action": intent,
+                        "resource": resource,
+                        "context": {},
+                    }
+                )
+            )
+        )
+        return response.get("decision", "Deny"), response.get("reason", "")
+
+    def _announce(self) -> None:
+        if not self._announced:
+            print(f"watchlight: governing '{self.agent}' (dev mode, in-process engine)")
+            self._announced = True
+
+    def _audit(self, intent: str, resource: str, decision: str, reason: str) -> None:
+        self._announce()
+        allowed = decision == "Allow"
+        tag = "ALLOW" if allowed else "DENY"
+        trailer = "" if allowed else f"     {reason or 'no matching policy'}"
+        print(f"watchlight: {tag:5} {intent:9} {resource}{trailer}")
+        # Value-free audit: argument VALUES never enter the trail — only the
+        # governance decision. This mirrors the production audit contract.
+        record = {
+            "ts": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            "agent": self.agent,
+            "intent": intent,
+            "resource": resource,
+            "decision": decision,
+        }
+        try:
+            self._audit_path.parent.mkdir(parents=True, exist_ok=True)
+            with self._audit_path.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(record) + "\n")
+        except OSError:
+            # Audit is best-effort in dev mode; never let it break the app.
+            pass
+
+
+# A ready-to-use default governor so `from watchlight import govern` just works.
+# It starts with NO policies — fail-closed by default — until you `govern.load(...)`
+# a policy file or `govern.allow(...)` a policy inline.
+govern = Watchlight()

watchlight/claude_agent.py

@@ -0,0 +1,50 @@
+"""Govern a Claude Agent SDK agent in-process, with zero infrastructure.
+
+    from watchlight.claude_agent import governed_plugin
+
+    plugin = governed_plugin("watchlight.policy.json")
+    async with await plugin.start_run("research-agent") as handle:
+        if not await handle.authorize_action("read", "tool/web_search"):
+            raise PermissionError("denied before it executed")
+        ...  # run the tool
+
+The returned object is an ordinary ``WatchlightClaudeAgentSDKPlugin`` — the SAME
+plugin you ship to production, wired here to the in-process engine (local Cedar
+policies, local value-free audit). Set ``WATCHLIGHT_APDP_URL`` to a running
+policy service and the identical code runs against production APDP — one
+environment variable, not a rewrite.
+
+Requires the Claude Agent extra: ``pip install 'watchlight[claude-agent]'``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .inprocess import Policies, _select_backend_kwargs
+
+
+def governed_plugin(
+    policies: Policies = None,
+    *,
+    audit_path: Optional[str] = ".watchlight/audit.jsonl",
+    **plugin_kwargs: Any,
+) -> Any:
+    """Return a governed ``WatchlightClaudeAgentSDKPlugin``.
+
+    :param policies: local Cedar policies — a path to a JSON policy file or an
+        in-memory list of ``{"name", "code"}`` objects. ``None`` → fail-closed.
+    :param audit_path: local JSONL lineage sink (value-free). ``None`` disables.
+    :param plugin_kwargs: forwarded to ``WatchlightClaudeAgentSDKPlugin`` (e.g.
+        ``tenant_id``, ``log_decisions``).
+    """
+    try:
+        from watchlight_claude_agent import WatchlightClaudeAgentSDKPlugin
+    except ImportError as exc:  # pragma: no cover - import-guard message
+        raise ImportError(
+            "governed Claude Agent support requires the claude-agent extra: "
+            "pip install 'watchlight[claude-agent]'"
+        ) from exc
+    return WatchlightClaudeAgentSDKPlugin(
+        **_select_backend_kwargs(policies, audit_path, plugin_kwargs)
+    )

watchlight/cli.py

@@ -0,0 +1,276 @@
+"""``watchlight`` command-line entry point.
+
+Currently one command:
+
+    watchlight dev        # a local dashboard for the in-process audit trail
+
+``watchlight dev`` serves a tiny, dependency-free web page that tails the local
+``.watchlight/audit.jsonl`` and shows every governance decision as it happens —
+the ALLOWs, and (the point) the DENYs that stopped a tool **before** it ran. It
+reads the same value-free audit the engine writes; no argument values, tokens,
+or secrets are ever displayed because they are never in the trail.
+
+It is deliberately minimal: the Developer-Edition dashboard shows *your one
+process*. Fleet-wide lineage, signed tamper-evident audit, and drift→quarantine
+live in the governed control plane (Enterprise).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+
+# --------------------------------------------------------------------------- #
+# Reading the value-free audit trail
+# --------------------------------------------------------------------------- #
+
+def _read_events(audit_path: pathlib.Path, limit: int = 500) -> list[dict[str, Any]]:
+    """Parse the audit JSONL into normalized decision records (newest last).
+
+    Robust to both the `watchlight.govern` shape ({ts, agent, intent, resource,
+    decision}) and the plugin/in-process shape — fields are looked up with
+    fallbacks. Malformed lines are skipped. Never raises."""
+    if not audit_path.exists():
+        return []
+    events: list[dict[str, Any]] = []
+    try:
+        lines = audit_path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    for line in lines[-limit:]:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            raw = json.loads(line)
+        except (ValueError, TypeError):
+            continue
+        decision = str(raw.get("decision", "")).strip()
+        events.append(
+            {
+                "ts": raw.get("ts") or raw.get("timestamp") or "",
+                "agent": raw.get("agent") or raw.get("agent_id") or raw.get("principal") or "agent",
+                "action": raw.get("intent") or raw.get("action") or "",
+                "resource": raw.get("resource") or raw.get("tool") or "",
+                "decision": decision,
+                "allowed": decision.lower() in ("allow", "permit"),
+            }
+        )
+    return events
+
+
+def _summary(events: list[dict[str, Any]]) -> dict[str, Any]:
+    allowed = sum(1 for e in events if e["allowed"])
+    denied = len(events) - allowed
+    agents = sorted({e["agent"] for e in events if e["agent"]})
+    return {"total": len(events), "allowed": allowed, "denied": denied, "agents": agents}
+
+
+# --------------------------------------------------------------------------- #
+# HTTP server
+# --------------------------------------------------------------------------- #
+
+def _make_handler(audit_path: pathlib.Path):
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *_: Any) -> None:  # silence access logging
+            pass
+
+        def do_GET(self) -> None:  # noqa: N802 (http.server API)
+            if self.path.startswith("/api/events"):
+                events = _read_events(audit_path)
+                body = json.dumps(
+                    {"summary": _summary(events), "events": events, "audit_path": str(audit_path)}
+                ).encode("utf-8")
+                self.send_response(200)
+                self.send_header("content-type", "application/json")
+                self.send_header("content-length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+                return
+            if self.path in ("/", "/index.html"):
+                body = _PAGE.encode("utf-8")
+                self.send_response(200)
+                self.send_header("content-type", "text/html; charset=utf-8")
+                self.send_header("content-length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+                return
+            self.send_response(404)
+            self.end_headers()
+
+    return Handler
+
+
+def _cmd_dev(args: argparse.Namespace) -> int:
+    audit_path = pathlib.Path(args.audit).expanduser()
+    server = ThreadingHTTPServer((args.host, args.port), _make_handler(audit_path))
+    url = f"http://{args.host}:{args.port}"
+    print(f"watchlight dev — dashboard on {url}")
+    print(f"  reading audit: {audit_path}")
+    print("  run your governed agent in another terminal; decisions appear live.")
+    print("  Ctrl-C to stop.")
+    if not args.no_open:
+        try:
+            import webbrowser
+
+            webbrowser.open(url)
+        except Exception:  # pragma: no cover - best effort
+            pass
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nwatchlight dev — stopped.")
+    finally:
+        server.server_close()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="watchlight", description="Watchlight Developer Edition.")
+    sub = parser.add_subparsers(dest="command")
+
+    dev = sub.add_parser("dev", help="serve the local decision dashboard")
+    dev.add_argument("--port", type=int, default=7000, help="port (default: 7000)")
+    dev.add_argument("--host", default="127.0.0.1", help="bind host (default: 127.0.0.1)")
+    dev.add_argument(
+        "--audit",
+        default=".watchlight/audit.jsonl",
+        help="audit JSONL to tail (default: .watchlight/audit.jsonl)",
+    )
+    dev.add_argument("--no-open", action="store_true", help="do not open a browser")
+    dev.set_defaults(func=_cmd_dev)
+
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 0
+    return int(args.func(args))
+
+
+# --------------------------------------------------------------------------- #
+# The dashboard page (self-contained: no external CSS/JS/fonts)
+# --------------------------------------------------------------------------- #
+
+_PAGE = """<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Watchlight · dev</title>
+<style>
+  :root {
+    --bg:#0b0f17; --panel:#111827; --panel2:#0f1521; --border:rgba(148,163,184,.14);
+    --text:#e5e7eb; --muted:#94a3b8; --amber:#fbbf24; --green:#34d399; --red:#f87171;
+  }
+  * { box-sizing:border-box; }
+  body { margin:0; background:var(--bg); color:var(--text);
+    font:14px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif; }
+  a { color:var(--amber); text-decoration:none; }
+  header { display:flex; align-items:center; gap:12px; padding:18px 24px;
+    border-bottom:1px solid var(--border); position:sticky; top:0; background:rgba(11,15,23,.85);
+    backdrop-filter:blur(8px); z-index:2; }
+  .logo { width:26px;height:26px;border-radius:7px;background:linear-gradient(135deg,var(--amber),#f59e0b);
+    display:grid;place-items:center;color:#111;font-weight:800; }
+  h1 { font-size:15px; margin:0; font-weight:700; letter-spacing:.2px; }
+  .sub { color:var(--muted); font-size:12px; }
+  .live { margin-left:auto; display:flex; align-items:center; gap:7px; color:var(--muted); font-size:12px; }
+  .dot { width:8px;height:8px;border-radius:50%;background:var(--green); box-shadow:0 0 0 0 rgba(52,211,153,.5);
+    animation:pulse 1.8s infinite; }
+  @keyframes pulse { 0%{box-shadow:0 0 0 0 rgba(52,211,153,.45)} 70%{box-shadow:0 0 0 7px rgba(52,211,153,0)} 100%{box-shadow:0 0 0 0 rgba(52,211,153,0)} }
+  main { max-width:1000px; margin:0 auto; padding:24px; }
+  .cards { display:grid; grid-template-columns:repeat(4,1fr); gap:14px; }
+  @media (max-width:640px){ .cards{ grid-template-columns:repeat(2,1fr);} }
+  .card { background:var(--panel); border:1px solid var(--border); border-radius:14px; padding:16px 18px; }
+  .card .n { font-size:26px; font-weight:750; font-variant-numeric:tabular-nums; }
+  .card .l { color:var(--muted); font-size:12px; text-transform:uppercase; letter-spacing:.6px; margin-top:2px; }
+  .card.deny .n { color:var(--red); } .card.allow .n { color:var(--green); }
+  h2 { font-size:13px; text-transform:uppercase; letter-spacing:.7px; color:var(--muted); margin:26px 0 10px; }
+  table { width:100%; border-collapse:collapse; }
+  th,td { text-align:left; padding:10px 12px; border-bottom:1px solid var(--border); font-variant-numeric:tabular-nums; }
+  th { color:var(--muted); font-weight:600; font-size:12px; text-transform:uppercase; letter-spacing:.5px; }
+  tr.deny td { background:rgba(248,113,113,.05); }
+  .pill { display:inline-flex; align-items:center; gap:6px; font-weight:700; font-size:12px;
+    padding:3px 9px; border-radius:999px; }
+  .pill.allow { color:var(--green); background:rgba(52,211,153,.12); }
+  .pill.deny { color:var(--red); background:rgba(248,113,113,.12); }
+  .mono { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; color:#cbd5e1; }
+  .empty { text-align:center; color:var(--muted); padding:52px 20px; border:1px dashed var(--border); border-radius:14px; }
+  .upsell { margin-top:30px; background:linear-gradient(180deg,rgba(251,191,36,.07),rgba(251,191,36,.02));
+    border:1px solid rgba(251,191,36,.22); border-radius:16px; padding:20px 22px; }
+  .upsell h3 { margin:0 0 6px; font-size:15px; }
+  .upsell p { margin:0 0 12px; color:var(--muted); }
+  .upsell ul { margin:0 0 14px; padding-left:18px; color:var(--muted); }
+  .cta { display:inline-block; background:var(--amber); color:#111; font-weight:700; padding:9px 16px; border-radius:10px; }
+  footer { text-align:center; color:var(--muted); font-size:12px; padding:24px; }
+</style>
+</head>
+<body>
+<header>
+  <div class="logo">W</div>
+  <div>
+    <h1>Watchlight <span style="color:var(--amber)">·</span> dev</h1>
+    <div class="sub" id="audit-path">in-process engine · value-free audit</div>
+  </div>
+  <div class="live"><span class="dot"></span> live</div>
+</header>
+<main>
+  <div class="cards">
+    <div class="card"><div class="n" id="c-total">0</div><div class="l">Decisions</div></div>
+    <div class="card allow"><div class="n" id="c-allow">0</div><div class="l">Allowed</div></div>
+    <div class="card deny"><div class="n" id="c-deny">0</div><div class="l">Denied before exec</div></div>
+    <div class="card"><div class="n" id="c-agents">0</div><div class="l">Agents</div></div>
+  </div>
+
+  <h2>Decisions</h2>
+  <div id="feed"></div>
+
+  <div class="upsell">
+    <h3>Governing more than one agent — or more than one environment?</h3>
+    <p>The Developer Edition dashboard shows <em>this one process</em>. A fleet in production needs guarantees a single in-process engine structurally can't provide:</p>
+    <ul>
+      <li><b>Signed, tamper-evident audit &amp; lineage</b> — court-defensible, KMS-backed.</li>
+      <li><b>Drift &amp; anomaly detection → automatic quarantine</b> — stop a misbehaving agent before its next action.</li>
+      <li><b>Fleet-wide revocation</b> and one authority model across dev, staging, and prod.</li>
+    </ul>
+    <a class="cta" href="https://watchlight.ai" target="_blank" rel="noopener">Explore Enterprise →</a>
+  </div>
+</main>
+<footer>Watchlight Developer Edition · the same engine you ship to production, in-process.</footer>
+
+<script>
+function esc(s){ return String(s).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])); }
+function timefmt(ts){ if(!ts) return ''; const d=new Date(ts); return isNaN(d)? esc(ts) : d.toLocaleTimeString(); }
+async function tick(){
+  let data; try { data = await (await fetch('/api/events')).json(); } catch(e){ return; }
+  const s = data.summary || {total:0,allowed:0,denied:0,agents:[]};
+  document.getElementById('c-total').textContent = s.total;
+  document.getElementById('c-allow').textContent = s.allowed;
+  document.getElementById('c-deny').textContent  = s.denied;
+  document.getElementById('c-agents').textContent = (s.agents||[]).length;
+  if (data.audit_path) document.getElementById('audit-path').textContent = 'audit · ' + data.audit_path;
+  const feed = document.getElementById('feed');
+  const evs = (data.events||[]).slice().reverse();  // newest first
+  if (!evs.length){ feed.innerHTML = '<div class="empty">No decisions yet.<br>Run your governed agent — every ALLOW and DENY appears here, live.</div>'; return; }
+  let rows = '';
+  for (const e of evs){
+    const cls = e.allowed ? 'allow' : 'deny';
+    const label = e.allowed ? 'ALLOW' : 'DENY';
+    rows += `<tr class="${cls}"><td>${timefmt(e.ts)}</td><td class="mono">${esc(e.agent)}</td>`
+         +  `<td class="mono">${esc(e.action)}</td><td class="mono">${esc(e.resource)}</td>`
+         +  `<td><span class="pill ${cls}">${label}</span></td></tr>`;
+  }
+  feed.innerHTML = `<table><thead><tr><th>Time</th><th>Agent</th><th>Intent / action</th><th>Resource</th><th>Decision</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+tick(); setInterval(tick, 1500);
+</script>
+</body>
+</html>"""
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

watchlight/inprocess.py

@@ -0,0 +1,89 @@
+"""In-process governance backend for Watchlight framework plugins.
+
+The Developer Edition runs the *same* framework plugins you ship to production
+(``watchlight-langgraph``, ``watchlight-pydantic-ai``, ``watchlight-claude-agent``,
+…) — but against the compiled authorization engine **in-process**, with zero
+infrastructure. The seam is one object: a ``GovernanceBackend``.
+
+- **Production**: the plugin talks to a running policy service over TLS
+  (``ApdpClient``).
+- **Developer Edition**: the plugin talks to :func:`in_process_backend` — the
+  real ``watchlight-engine`` (the Watchlight authorization engine, Cedar)
+  embedded in your process, writing a local, value-free audit trail.
+
+Same plugin, same agent code. Going to production is pointing at a policy
+service — not a rewrite.
+
+    from watchlight.inprocess import in_process_backend
+    from watchlight_langgraph import WatchlightLangGraphPlugin
+
+    plugin = WatchlightLangGraphPlugin(
+        governance=in_process_backend("watchlight.policy.json")
+    )
+
+Most users never import this directly — the per-framework helpers
+(``watchlight.langgraph.governed_plugin`` etc.) call it for you.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional, Union
+
+# A local policy source: a path to a JSON policy file, or an in-memory list of
+# ``{"name", "code"}`` Cedar policy objects. ``None`` loads no policies —
+# fail-closed, so every action is denied until a policy permits it.
+Policies = Optional[Union[str, "os.PathLike[str]", List[Dict[str, Any]]]]
+
+
+def in_process_backend(
+    policies: Policies = None,
+    *,
+    audit_path: Optional[str] = ".watchlight/audit.jsonl",
+) -> Any:
+    """Build an in-process ``GovernanceBackend`` over the compiled engine.
+
+    :param policies: a path to a JSON policy file (a list of
+        ``{"name", "code"}`` objects, or ``{"policies": [...]}``), or that list
+        in memory. ``None`` → no policies (fail-closed: everything denies).
+    :param audit_path: local JSONL lineage sink. Value-free — argument VALUES
+        never enter the trail, only the governance decision. Pass ``None`` to
+        disable the local audit file.
+    :returns: a ``watchlight_core.InProcessClient`` — pass it to any Watchlight
+        framework plugin via ``governance=``.
+
+    Requires the Watchlight SDK (installed transitively by any framework extra,
+    e.g. ``pip install 'watchlight[langgraph]'``).
+    """
+    try:
+        from watchlight_core import InProcessClient
+    except ImportError as exc:  # pragma: no cover - import-guard message
+        raise ImportError(
+            "in_process_backend requires the Watchlight SDK. Install a framework "
+            "extra, e.g. `pip install 'watchlight[langgraph]'`, or the SDK "
+            "directly: `pip install watchlight-agent-sdk`."
+        ) from exc
+    return InProcessClient(policies, audit_path=audit_path)
+
+
+def _select_backend_kwargs(
+    policies: Policies,
+    audit_path: Optional[str],
+    plugin_kwargs: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Compute the constructor kwargs for a framework plugin: production when
+    ``WATCHLIGHT_APDP_URL`` is set (networked APDP), in-process otherwise.
+
+    One environment variable flips dev↔prod with no code change — the shared
+    logic behind every ``watchlight.<framework>.governed_plugin`` helper.
+    """
+    apdp_url = os.getenv("WATCHLIGHT_APDP_URL")
+    if apdp_url:
+        # Production: the plugin builds its own networked ApdpClient (which
+        # enforces channel safety). We only pass the URL through.
+        return {"apdp_url": apdp_url, **plugin_kwargs}
+    # Developer Edition: in-process engine, zero infra.
+    return {
+        "governance": in_process_backend(policies, audit_path=audit_path),
+        **plugin_kwargs,
+    }

watchlight/langgraph.py

@@ -0,0 +1,50 @@
+"""Govern a LangGraph agent in-process, with zero infrastructure.
+
+    from watchlight.langgraph import governed_plugin
+
+    plugin = governed_plugin("watchlight.policy.json")
+    async with await plugin.start_run("research-agent") as handle:
+        if not await handle.authorize_action("read", "tool/web_search"):
+            raise PermissionError("denied before it executed")
+        ...  # run the tool
+
+The returned object is an ordinary ``WatchlightLangGraphPlugin`` — the SAME
+plugin you ship to production. In the Developer Edition it is wired to the
+in-process engine (local Cedar policies, local value-free audit). Set
+``WATCHLIGHT_APDP_URL`` to a running policy service and the identical code runs
+against production APDP — one environment variable, not a rewrite.
+
+Requires the LangGraph extra: ``pip install 'watchlight[langgraph]'``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .inprocess import Policies, _select_backend_kwargs
+
+
+def governed_plugin(
+    policies: Policies = None,
+    *,
+    audit_path: Optional[str] = ".watchlight/audit.jsonl",
+    **plugin_kwargs: Any,
+) -> Any:
+    """Return a governed ``WatchlightLangGraphPlugin``.
+
+    :param policies: local Cedar policies — a path to a JSON policy file or an
+        in-memory list of ``{"name", "code"}`` objects. ``None`` → fail-closed.
+    :param audit_path: local JSONL lineage sink (value-free). ``None`` disables.
+    :param plugin_kwargs: forwarded to ``WatchlightLangGraphPlugin`` (e.g.
+        ``tenant_id``, ``log_decisions``).
+    """
+    try:
+        from watchlight_langgraph import WatchlightLangGraphPlugin
+    except ImportError as exc:  # pragma: no cover - import-guard message
+        raise ImportError(
+            "governed LangGraph support requires the langgraph extra: "
+            "pip install 'watchlight[langgraph]'"
+        ) from exc
+    return WatchlightLangGraphPlugin(
+        **_select_backend_kwargs(policies, audit_path, plugin_kwargs)
+    )

watchlight/pydantic_ai.py

@@ -0,0 +1,50 @@
+"""Govern a Pydantic AI agent in-process, with zero infrastructure.
+
+    from watchlight.pydantic_ai import governed_plugin
+
+    plugin = governed_plugin("watchlight.policy.json")
+    async with await plugin.start_run("research-agent") as handle:
+        if not await handle.authorize_action("read", "tool/web_search"):
+            raise PermissionError("denied before it executed")
+        ...  # run the tool
+
+The returned object is an ordinary ``WatchlightPydanticAIPlugin`` — the SAME
+plugin you ship to production, wired here to the in-process engine (local Cedar
+policies, local value-free audit). Set ``WATCHLIGHT_APDP_URL`` to a running
+policy service and the identical code runs against production APDP — one
+environment variable, not a rewrite.
+
+Requires the Pydantic AI extra: ``pip install 'watchlight[pydantic-ai]'``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .inprocess import Policies, _select_backend_kwargs
+
+
+def governed_plugin(
+    policies: Policies = None,
+    *,
+    audit_path: Optional[str] = ".watchlight/audit.jsonl",
+    **plugin_kwargs: Any,
+) -> Any:
+    """Return a governed ``WatchlightPydanticAIPlugin``.
+
+    :param policies: local Cedar policies — a path to a JSON policy file or an
+        in-memory list of ``{"name", "code"}`` objects. ``None`` → fail-closed.
+    :param audit_path: local JSONL lineage sink (value-free). ``None`` disables.
+    :param plugin_kwargs: forwarded to ``WatchlightPydanticAIPlugin`` (e.g.
+        ``tenant_id``, ``auto_instrument``).
+    """
+    try:
+        from watchlight_pydantic_ai import WatchlightPydanticAIPlugin
+    except ImportError as exc:  # pragma: no cover - import-guard message
+        raise ImportError(
+            "governed Pydantic AI support requires the pydantic-ai extra: "
+            "pip install 'watchlight[pydantic-ai]'"
+        ) from exc
+    return WatchlightPydanticAIPlugin(
+        **_select_backend_kwargs(policies, audit_path, plugin_kwargs)
+    )

watchlight-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: watchlight
+Version: 0.1.0
+Summary: Watchlight Developer Edition — govern AI agents in-process, with zero infrastructure.
+Author: Watchlight AI
+License: Apache-2.0
+Project-URL: Homepage, https://watchlight.ai
+Project-URL: Documentation, https://docs.watchlight.ai/de
+Keywords: authorization,ai-agents,cedar,policy,governance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: watchlight-engine<0.2,>=0.1
+Provides-Extra: langgraph
+Requires-Dist: watchlight-langgraph>=0.4; extra == "langgraph"
+Provides-Extra: pydantic-ai
+Requires-Dist: watchlight-pydantic-ai>=0.3; extra == "pydantic-ai"
+Provides-Extra: claude-agent
+Requires-Dist: watchlight-claude-agent>=0.2; extra == "claude-agent"
+Provides-Extra: mcp
+Requires-Dist: watchlight-mcp>=0.1; extra == "mcp"
+
+# Watchlight — Developer Edition
+
+**Govern an AI agent in five minutes. One install, zero infrastructure, same API as production.**
+
+Watchlight puts a policy decision point in front of every action your AI agents
+take — authorizing tool calls, attenuating sub-agent authority to a strict
+subset, and recording a tamper-evident, value-free audit trail. The Developer
+Edition runs that *entire* authorization model **in-process**, so you can see it
+work in your own terminal with no server, no database, and no signup.
+
+The code you write here is the code you ship to production. Going to production
+is pointing at a running policy service — not a rewrite.
+
+---
+
+## Quickstart
+
+> **Status: in active development.** The target experience is below; see the
+> [Developer Edition docs](https://docs.watchlight.ai/de) for the current state.
+
+```bash
+pip install watchlight
+```
+
+```python
+from watchlight import govern
+
+@govern.tool(intent="research")
+def web_search(query: str) -> str:
+    ...
+
+@govern.tool(intent="transfer")           # governed, but no policy permits it
+def transfer_funds(to: str, amount: int) -> str:
+    ...
+```
+
+```text
+$ python agent.py
+watchlight: governing 'my-agent' (dev mode, in-process engine)
+watchlight: ALLOW  read     tool/web_search
+watchlight: DENY   execute  tool/transfer_funds     no matching policy
+```
+
+**That `DENY` line — in your own terminal, in under five minutes, with no
+account — is the product.**
+
+---
+
+## Already using a framework? Govern it in-process
+
+Bring your existing **LangGraph**, **Pydantic AI**, or **Claude Agent SDK**
+agent under governance with zero infrastructure — the *same* plugin you ship to
+production, wired to the in-process engine:
+
+```bash
+pip install 'watchlight[langgraph]'   # or [pydantic-ai], [claude-agent]
+```
+
+```python
+from watchlight.langgraph import governed_plugin   # .pydantic_ai / .claude_agent
+
+plugin = governed_plugin("watchlight.policy.json")   # in-process, zero infra
+
+async with await plugin.start_run("research-agent") as handle:
+    if not await handle.authorize_action("read", "tool/web_search"):
+        raise PermissionError("denied before it executed")
+    ...  # your tool runs, every action governed + recorded to .watchlight/audit.jsonl
+```
+
+Going to production is one environment variable, not a rewrite — set
+`WATCHLIGHT_APDP_URL` and the identical code authorizes against a running policy
+service. Runnable examples for all three frameworks are in
+[`examples/`](examples/).
+
+---
+
+## Watch every decision live — `watchlight dev`
+
+A zero-dependency local dashboard that tails your value-free audit trail and
+shows every governance decision as it happens — the ALLOWs, and the DENYs that
+stopped a tool **before** it ran.
+
+```bash
+watchlight dev            # → http://127.0.0.1:7000
+```
+
+Run your governed agent in another terminal and watch the decisions stream in.
+It shows only *this* process — fleet-wide lineage, signed audit, and
+drift→quarantine are the governed control plane (Enterprise).
+
+---
+
+## Govern an MCP server
+
+Put a policy decision point in front of any [MCP](https://modelcontextprotocol.io)
+server (spec `2026-07-28`). Every `tools/call` is authorized in-process **before**
+it reaches the server — a denied call never executes.
+
+```bash
+pip install watchlight-mcp
+```
+
+```python
+import watchlight_mcp
+
+watchlight_mcp.serve(
+    listen_addr="127.0.0.1:9700",
+    upstream_url="http://localhost:3000/mcp",   # the MCP server you're governing
+    upstream_server="github",
+    policy_files=["examples/mcp.policy.json"],
+)
+```
+
+Point your MCP client at `http://127.0.0.1:9700/mcp` instead of the server. A
+self-contained, self-demonstrating example (it fires an allowed and a denied
+call and proves the denied one never ran) is in
+[`examples/governed_mcp_server.py`](examples/governed_mcp_server.py).
+
+---
+
+## What runs locally
+
+| Capability | Developer Edition (free / open) | Enterprise |
+|---|---|---|
+| Policy engine | in-process Cedar, policies from a local `.cedar` file | a running, scaled policy service |
+| Sub-agent scope attenuation | engine-side strict-subset validation | same, server-side |
+| Content / PII screening | policy-based, in-process | a running guardrails service |
+| Audit | local JSONL, greppable, value-free | a signed, tamper-evident audit service |
+| Dashboard | `watchlight dev` → `localhost:7000` (policies + execution lineage) | the full operator console |
+
+Everything the Developer Edition removes is **infrastructure**, never a
+**guarantee**. Fail-closed semantics, engine-side attenuation, explicit scopes,
+and value-free audit are identical in every mode.
+
+---
+
+## Progressive disclosure
+
+Each level is one environment variable away from the next. **Nothing is
+rewritten between levels.**
+
+- **Level 0** — `pip install watchlight`. In-process engine, audit to stdout.
+- **Level 1** — `watchlight dev`. Adds a local dashboard (decisions, denials, scope tree, execution lineage).
+- **Level 2** — `docker compose up`. Real policy service + database; policies still from your local file.
+- **Level 3** — Production. The full governed platform.
+
+---
+
+## Developer Edition vs Enterprise
+
+The Developer Edition is the **real engine** — free, open, and running
+in-process so you can evaluate the entire authorization model on your laptop
+with zero infrastructure. Enterprise is the **same code** pointed at the
+governed control plane; it doesn't replace anything, it adds what a fleet in
+production needs:
+
+- **Signed, tamper-evident lineage & audit** — every decision and lineage event
+  cryptographically signed (KMS-backed), so the trail is court-defensible.
+- **Multi-tenant isolation + roll-up administration** — tenant hierarchy, scoped
+  admins, and a cross-tenant authorization matrix.
+- **Drift & anomaly detection → automatic quarantine** — behavioural,
+  goal-drift, and argument-shape detectors that quarantine a misbehaving agent
+  *before* the next action.
+- **Full enforcement-effect taxonomy** — beyond allow/deny: block, terminate,
+  quarantine, sever-subtree, and revoke, enforced at runtime across the plane.
+- **Fleet-wide revocation & cross-environment governance** — revoke authority
+  across every agent at once, and govern dev, staging, and prod under one
+  authority model (including **sovereign / air-gapped deployment**).
+- **Content / PII guardrails service** and **global execution-graph lineage**
+  with the full **operator console**.
+- **SSO / RBAC / enterprise audit**, high availability, support, and SLAs.
+
+### You've outgrown the Developer Edition when…
+
+- Compliance asks *"prove who authorized this in production"* → you need
+  **signed, tamper-evident lineage**.
+- You're governing **more than one agent, or more than one environment** →
+  central policy lifecycle + the **global execution graph**.
+- Security wants a misbehaving agent **stopped before its next action** →
+  **drift/anomaly detection → automatic quarantine**.
+- You need to **revoke authority fleet-wide**, not process-by-process.
+- Procurement needs **SSO, RBAC, HA, SLAs, or sovereign/air-gapped deployment**.
+
+Each of these is a governance guarantee a single in-process engine structurally
+cannot provide — it needs the control plane.
+
+**Migrating is one environment variable — never a rewrite.** The tools you
+decorate, the policies you write, and the guarantees you rely on
+(fail-closed, engine-side attenuation, explicit scopes, value-free audit) are
+identical in every mode. Enterprise simply points the same code at a running
+plane.
+
+> The engine ships as a compiled wheel and the Developer Edition is a deliberate
+> *subset* of the platform — the governed control plane (signing, multi-tenant,
+> guardrails, drift, execution-graph) is the enterprise product, never bundled
+> here.
+
+→ **[Talk to us about Enterprise](mailto:enterprise@watchlight.ai)** when you're
+ready for production.
+
+---
+
+## License
+
+Apache-2.0.

watchlight-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+watchlight/__init__.py,sha256=pvEVYBT1MluRWDBU6fd6nbkOX6vwlckwR7BJcPAGnW4,7001
+watchlight/claude_agent.py,sha256=oZXBT9jJ8JJn3KKt2rmdGM6V06n1gzFe_PX-XJL_K8s,2025
+watchlight/cli.py,sha256=-mBOTOByiCEMCmPzwXuArRVSGQIWbX5YlSghE493JYE,13145
+watchlight/inprocess.py,sha256=L1bt_-QgkXMLT1NL6A5imVeVlxxAtfXY3GaOkxMxb0M,3809
+watchlight/langgraph.py,sha256=ymJvg1zbJRTQRhEbObGpqPto0hLXNO2zXOFBjLGNQ4k,1998
+watchlight/pydantic_ai.py,sha256=t1ixCUjzeRSHiCnl2cMdp0BTQTcY_I6cUQnimNu2DeQ,1995
+watchlight-0.1.0.dist-info/METADATA,sha256=HvLXuJemBIMj2JDxQrJy662jIFIc3FuLMG8QkiXhDbQ,8755
+watchlight-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+watchlight-0.1.0.dist-info/entry_points.txt,sha256=Kt25AFPFZcp5Z6w6YfbE7nqu_ougsi38bJqWK_2JM2Q,51
+watchlight-0.1.0.dist-info/top_level.txt,sha256=BxOOJbx57PaqZINnHdkQshTYtpjIvtUl5vGULmVcUkg,11
+watchlight-0.1.0.dist-info/RECORD,,

watchlight-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

watchlight-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+watchlight = watchlight.cli:main

watchlight-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+watchlight