watchlight 0.1.0__tar.gz

watchlight-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,205 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "watchlight"
+version = "0.1.0"
+description = "Watchlight Developer Edition — govern AI agents in-process, with zero infrastructure."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Watchlight AI" }]
+keywords = ["authorization", "ai-agents", "cedar", "policy", "governance"]
+dependencies = [
+    # The in-process authorization engine — the real Watchlight policy engine
+    # (Cedar evaluation + the surrounding pipeline), embedded via PyO3 and
+    # published to PyPI as `watchlight-engine`.
+    "watchlight-engine>=0.1,<0.2",
+]
+
+[project.optional-dependencies]
+# Govern an existing framework agent in-process. Each extra pulls the published
+# framework plugin (which pulls the Watchlight SDK); the SAME plugin you ship to
+# production, wired here to the in-process engine via
+# `watchlight.<framework>.governed_plugin`.
+langgraph = ["watchlight-langgraph>=0.4"]
+pydantic-ai = ["watchlight-pydantic-ai>=0.3"]
+claude-agent = ["watchlight-claude-agent>=0.2"]
+# Govern an MCP server: the Watchlight MCP Runtime PEP — a policy enforcement
+# point in front of any MCP (2026-07-28) server. See examples/governed_mcp_server.py.
+mcp = ["watchlight-mcp>=0.1"]
+
+[project.scripts]
+# `watchlight dev` → the local decision dashboard (stdlib-only, zero extra deps).
+watchlight = "watchlight.cli:main"
+
+[project.urls]
+Homepage = "https://watchlight.ai"
+Documentation = "https://docs.watchlight.ai/de"
+
+[tool.setuptools.packages.find]
+where = ["src"]

watchlight-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

watchlight-0.1.0/src/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()