revoc-sdk 1.0.0__tar.gz

revoc_sdk-1.0.0/.gitignore

@@ -0,0 +1,159 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# REVOC .gitignore
+# Rust + Python + Node.js + IDE + OS
+# IMPORTANT: crates/revoc-dashboard/ui/dist/ is NOT ignored — it must be
+#            committed so the single-container image works without a Node build.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Rust ──────────────────────────────────────────────────────────────────────
+/target/
+debug/
+**/*.rs.bk
+*.pdb
+**/mutants.out*/
+
+# ── Fuzz ──────────────────────────────────────────────────────────────────────
+# Keep: fuzz/Cargo.toml, fuzz/Cargo.lock, fuzz/fuzz_targets/, fuzz/artifacts/
+# Ignore: compiled binaries and generated corpus (too large, too noisy)
+fuzz/target/
+fuzz/corpus/
+
+# ── Cargo Chef artifacts ──────────────────────────────────────────────────────
+recipe.json
+req.json
+
+# ── Environment & Secrets ─────────────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+api_keys.txt
+api-keys.txt
+
+# ── Python ────────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+*.pyd
+.Python
+.venv/
+venv/
+env/
+ENV/
+pip-wheel-metadata/
+*.egg-info/
+.eggs/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pytype/
+
+# ── Node.js ───────────────────────────────────────────────────────────────────
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+.npm
+.yarn/
+.pnp.*
+# Build output for SDK packages (NOT for revoc-dashboard/ui/dist — see below)
+sdk/node/dist/
+sdk/node/lib/
+
+# ── Dashboard React SPA ───────────────────────────────────────────────────────
+# CRITICAL: DO NOT add crates/revoc-dashboard/ui/dist/ here.
+# The pre-built SPA must be committed to git so the Rust binary can embed it
+# via include_dir! without requiring a Node build step in the container.
+crates/revoc-dashboard/ui/node_modules/
+crates/revoc-dashboard/ui/.parcel-cache/
+crates/revoc-dashboard/ui/.vite/
+
+# ── Database & Storage ────────────────────────────────────────────────────────
+*.db
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+revoc-audit.db*
+
+# ── Logs ──────────────────────────────────────────────────────────────────────
+*.log
+logs/
+*.log.*
+
+# ── ML Models ────────────────────────────────────────────────────────────────
+# ONNX models and tokenizer files are large binaries — downloaded via models/download.sh
+models/*.onnx
+models/*.json
+!models/README.md
+!models/download.sh
+
+# ── Test Artifacts ───────────────────────────────────────────────────────────
+# Locust CSV output and load test result files — generated on every run
+tests/load/results/
+
+# ── Generated / Build Artifacts ───────────────────────────────────────────────
+site/
+lcov.info
+lcov-*.info
+coverage/
+*.profraw
+*.profdata
+
+# ── Claude IDE local settings ─────────────────────────────────────────────────
+.claude/settings.local.json
+
+# ── IDE ───────────────────────────────────────────────────────────────────────
+.idea/
+.vscode/
+*.iml
+*.ipr
+*.iws
+.fleet/
+.zed/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.settings/
+
+# ── OS ────────────────────────────────────────────────────────────────────────
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# ── Helm ──────────────────────────────────────────────────────────────────────
+helm/revoc/charts/
+helm/revoc/*.tgz
+
+# ── Misc ──────────────────────────────────────────────────────────────────────
+.cargo-ok
+flamegraph.svg
+perf.data
+perf.data.old
+heaptrack.*
+massif.out.*
+dist/
+build/
+# CRITICAL: revoc-dashboard pre-built SPA must be committed (SPEC.md §6)
+!crates/revoc-dashboard/ui/dist/
+!crates/revoc-dashboard/ui/dist/**

revoc_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: revoc-sdk
+Version: 1.0.0
+Summary: Zero-code-change governance SDK for REVOC — drop-in OpenAI client wrapper.
+Project-URL: Homepage, https://revoc.io
+Project-URL: Documentation, https://revoc.io
+Project-URL: Repository, https://github.com/revoc-ai/revoc
+Project-URL: Bug Tracker, https://github.com/revoc-ai/revoc/issues
+Project-URL: Changelog, https://github.com/revoc-ai/revoc/blob/main/CHANGELOG.md
+Author: REVOC
+License: Apache-2.0
+Keywords: ai,governance,llm,openai,pii,proxy,redaction,security
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.50
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# revoc-sdk
+
+Zero-code-change governance SDK for [REVOC](https://revoc.io) — drop-in
+subclasses of the official `openai` Python client that route traffic through
+the REVOC proxy and translate governance decisions into typed exceptions.
+
+## Install
+
+```bash
+pip install revoc-sdk
+```
+
+## Usage
+
+```python
+from revoc_sdk import RevocOpenAI, RevocGovernanceError
+
+client = RevocOpenAI(api_key="sk-...", revoc_base_url="http://revoc:8080")
+
+try:
+    resp = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello"}],
+    )
+except RevocGovernanceError as exc:
+    print(f"Blocked by {exc.blocked_by}: {exc.reason}")
+    print(f"See {exc.dashboard_url}")
+```
+
+## Zero-code-change activation
+
+```bash
+export REVOC_BASE_URL=http://revoc:8080
+```
+
+```python
+import revoc_sdk
+revoc_sdk.patch()  # patches openai.OpenAI / openai.AsyncOpenAI
+
+from openai import OpenAI
+client = OpenAI(api_key="sk-...")  # transparently routed through REVOC
+```
+
+## Governance API
+
+```python
+import asyncio
+from datetime import datetime, timedelta, timezone
+
+async def main():
+    stats = await client.governance.get_audit_stats(
+        start_time=datetime.now(timezone.utc) - timedelta(days=1),
+        end_time=datetime.now(timezone.utc),
+    )
+    print(stats)
+
+asyncio.run(main())
+```
+
+## Exceptions
+
+| Exception | Raised when |
+|---|---|
+| `RevocGovernanceError` | A policy rule blocked the request |
+| `RevocKillSwitchError` | The emergency kill-switch is active |
+| `RevocDepthExceededError` | Governance depth reached the maximum (10) |
+| `RevocRateLimitError` | The caller exceeded their rate limit |
+| `RevocMcpError` | An MCP `tools/call` was blocked before reaching the server |
+
+## License
+
+Apache 2.0

revoc_sdk-1.0.0/README.md

@@ -0,0 +1,72 @@
+# revoc-sdk
+
+Zero-code-change governance SDK for [REVOC](https://revoc.io) — drop-in
+subclasses of the official `openai` Python client that route traffic through
+the REVOC proxy and translate governance decisions into typed exceptions.
+
+## Install
+
+```bash
+pip install revoc-sdk
+```
+
+## Usage
+
+```python
+from revoc_sdk import RevocOpenAI, RevocGovernanceError
+
+client = RevocOpenAI(api_key="sk-...", revoc_base_url="http://revoc:8080")
+
+try:
+    resp = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello"}],
+    )
+except RevocGovernanceError as exc:
+    print(f"Blocked by {exc.blocked_by}: {exc.reason}")
+    print(f"See {exc.dashboard_url}")
+```
+
+## Zero-code-change activation
+
+```bash
+export REVOC_BASE_URL=http://revoc:8080
+```
+
+```python
+import revoc_sdk
+revoc_sdk.patch()  # patches openai.OpenAI / openai.AsyncOpenAI
+
+from openai import OpenAI
+client = OpenAI(api_key="sk-...")  # transparently routed through REVOC
+```
+
+## Governance API
+
+```python
+import asyncio
+from datetime import datetime, timedelta, timezone
+
+async def main():
+    stats = await client.governance.get_audit_stats(
+        start_time=datetime.now(timezone.utc) - timedelta(days=1),
+        end_time=datetime.now(timezone.utc),
+    )
+    print(stats)
+
+asyncio.run(main())
+```
+
+## Exceptions
+
+| Exception | Raised when |
+|---|---|
+| `RevocGovernanceError` | A policy rule blocked the request |
+| `RevocKillSwitchError` | The emergency kill-switch is active |
+| `RevocDepthExceededError` | Governance depth reached the maximum (10) |
+| `RevocRateLimitError` | The caller exceeded their rate limit |
+| `RevocMcpError` | An MCP `tools/call` was blocked before reaching the server |
+
+## License
+
+Apache 2.0

revoc_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "revoc-sdk"
+version = "1.0.0"
+description = "Zero-code-change governance SDK for REVOC — drop-in OpenAI client wrapper."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+authors = [{ name = "REVOC" }]
+keywords = ["ai", "governance", "llm", "proxy", "security", "pii", "redaction", "openai"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "openai>=1.50",
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.7",
+    "mypy>=1.13",
+]
+
+[project.urls]
+Homepage = "https://revoc.io"
+Documentation = "https://revoc.io"
+Repository = "https://github.com/revoc-ai/revoc"
+"Bug Tracker" = "https://github.com/revoc-ai/revoc/issues"
+Changelog = "https://github.com/revoc-ai/revoc/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["revoc_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "DTZ"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

revoc_sdk-1.0.0/revoc_sdk/__init__.py

@@ -0,0 +1,38 @@
+"""revoc_sdk — zero-code-change governance SDK for REVOC.
+
+    from revoc_sdk import RevocOpenAI
+    client = RevocOpenAI(api_key="sk-...")
+
+See https://revoc.io/docs for full documentation.
+"""
+
+from __future__ import annotations
+
+from revoc_sdk.client import RevocAsyncOpenAI, RevocOpenAI
+from revoc_sdk.exceptions import (
+    RevocDepthExceededError,
+    RevocGovernanceError,
+    RevocKillSwitchError,
+    RevocRateLimitError,
+)
+from revoc_sdk.governance import GovernanceClient
+from revoc_sdk.mcp import RevocMcpClient, RevocMcpError, governed_tool_call
+from revoc_sdk.patch import patch, unpatch
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "GovernanceClient",
+    "RevocAsyncOpenAI",
+    "RevocDepthExceededError",
+    "RevocGovernanceError",
+    "RevocKillSwitchError",
+    "RevocMcpClient",
+    "RevocMcpError",
+    "RevocOpenAI",
+    "RevocRateLimitError",
+    "__version__",
+    "governed_tool_call",
+    "patch",
+    "unpatch",
+]

revoc_sdk-1.0.0/revoc_sdk/client.py

@@ -0,0 +1,194 @@
+"""revoc_sdk.client — drop-in OpenAI client subclasses routed through REVOC.
+
+Usage (zero-code-change beyond the constructor):
+
+    from revoc_sdk import RevocOpenAI
+    client = RevocOpenAI(api_key="sk-...")          # reads REVOC_BASE_URL
+    client = RevocOpenAI(api_key="sk-...", revoc_base_url="http://revoc:8080")
+
+Both subclasses transparently translate REVOC governance error responses
+(`RevocErrorResponse`, see SPEC.md Section 7.5) into typed Python
+exceptions so callers can branch on governance outcomes instead of parsing
+raw HTTP error bodies.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+from openai import AsyncOpenAI, OpenAI
+
+from revoc_sdk.exceptions import (
+    RevocDepthExceededError,
+    RevocGovernanceError,
+    RevocKillSwitchError,
+    RevocRateLimitError,
+)
+from revoc_sdk.governance import GovernanceClient
+
+
+def _response_hook(response: httpx.Response) -> None:
+    """httpx event hook: parse REVOC error bodies and raise typed exceptions.
+
+    Only fires on 4xx/5xx responses, and only acts when the body matches the
+    `RevocErrorResponse` shape (`{"error": {"code": "REVOC_...", ...}}`).
+    Upstream provider errors are passed through untouched (Rule 8: forward
+    verbatim, never wrap).
+    """
+    if response.status_code < 400:
+        return
+    try:
+        response.read()
+        payload = response.json()
+    except Exception:  # noqa: BLE001 — malformed/non-JSON bodies pass through
+        return
+    if not isinstance(payload, dict):
+        return
+    error = payload.get("error")
+    if not isinstance(error, dict):
+        return
+    code = error.get("code", "")
+    if not isinstance(code, str) or not code.startswith("REVOC_"):
+        return
+    if code == "REVOC_RATE_LIMIT_EXCEEDED":
+        retry_after = 0
+        try:
+            retry_after = int(response.headers.get("retry-after", "0"))
+        except ValueError:
+            retry_after = 0
+        raise RevocRateLimitError(retry_after_secs=retry_after)
+    if code == "REVOC_KILL_SWITCH_ACTIVE":
+        raise RevocKillSwitchError(
+            scope="global", dashboard_url=error.get("dashboard_url", "")
+        )
+    if code == "REVOC_GOVERNANCE_DEPTH_EXCEEDED":
+        depth = 10
+        message = error.get("message", "")
+        try:
+            fraction = message.split("(", 1)[1].split(")", 1)[0]
+            depth = int(fraction.split("/", 1)[0])
+        except (IndexError, ValueError):
+            pass
+        raise RevocDepthExceededError(depth=depth, max_depth=10)
+    if code == "REVOC_GOVERNANCE_BLOCK":
+        raise RevocGovernanceError(
+            reason=error.get("message", ""),
+            decision="block",
+            blocked_by=error.get("blocked_by"),
+            rules=error.get("rules") or [],
+            trace_id=error.get("trace_id", ""),
+            dashboard_url=error.get("dashboard_url", ""),
+            documentation_url=error.get("documentation_url"),
+        )
+
+
+def _resolve_base_url(revoc_base_url: str | None, kwargs: dict[str, Any]) -> str | None:
+    """Resolution order: explicit kwarg > REVOC_BASE_URL env > caller-supplied base_url."""
+    if revoc_base_url:
+        return revoc_base_url
+    env_url = os.environ.get("REVOC_BASE_URL")
+    if env_url:
+        return env_url
+    existing = kwargs.pop("base_url", None)
+    return existing if isinstance(existing, str) or existing is None else None
+
+
+class RevocOpenAI(OpenAI):
+    """Synchronous OpenAI client transparently governed by REVOC.
+
+    Drop-in replacement for ``openai.OpenAI``. All requests are routed
+    through the REVOC proxy (`base_url`), and governance error responses are
+    raised as typed exceptions (`RevocGovernanceError`, `RevocKillSwitchError`,
+    `RevocDepthExceededError`, `RevocRateLimitError`).
+    """
+
+    def __init__(self, *, revoc_base_url: str | None = None, **kwargs: Any) -> None:
+        base_url = _resolve_base_url(revoc_base_url, kwargs)
+        http_client = kwargs.pop("http_client", None)
+        if http_client is None:
+            http_client = httpx.Client(event_hooks={"response": [_response_hook]})
+        super().__init__(base_url=base_url, http_client=http_client, **kwargs)
+        self._revoc_governance: GovernanceClient | None = None
+
+    @property
+    def governance(self) -> GovernanceClient:
+        """Lazily-constructed client for the REVOC dashboard / admin-api."""
+        if self._revoc_governance is None:
+            base = str(self.base_url) if self.base_url else ""
+            self._revoc_governance = GovernanceClient(base_url=base)
+        return self._revoc_governance
+
+
+class RevocAsyncOpenAI(AsyncOpenAI):
+    """Asynchronous OpenAI client transparently governed by REVOC.
+
+    Drop-in replacement for ``openai.AsyncOpenAI`` with the same governance
+    exception translation as `RevocOpenAI`.
+    """
+
+    def __init__(self, *, revoc_base_url: str | None = None, **kwargs: Any) -> None:
+        base_url = _resolve_base_url(revoc_base_url, kwargs)
+        http_client = kwargs.pop("http_client", None)
+        if http_client is None:
+            http_client = httpx.AsyncClient(event_hooks={"response": [_async_response_hook]})
+        super().__init__(base_url=base_url, http_client=http_client, **kwargs)
+        self._revoc_governance: GovernanceClient | None = None
+
+    @property
+    def governance(self) -> GovernanceClient:
+        """Lazily-constructed client for the REVOC dashboard / admin-api."""
+        if self._revoc_governance is None:
+            base = str(self.base_url) if self.base_url else ""
+            self._revoc_governance = GovernanceClient(base_url=base)
+        return self._revoc_governance
+
+
+async def _async_response_hook(response: httpx.Response) -> None:
+    """Async variant of `_response_hook` for `httpx.AsyncClient` event hooks."""
+    if response.status_code < 400:
+        return
+    try:
+        await response.aread()
+        payload = response.json()
+    except Exception:  # noqa: BLE001
+        return
+    if not isinstance(payload, dict):
+        return
+    error = payload.get("error")
+    if not isinstance(error, dict):
+        return
+    code = error.get("code", "")
+    if not isinstance(code, str) or not code.startswith("REVOC_"):
+        return
+    if code == "REVOC_RATE_LIMIT_EXCEEDED":
+        retry_after = 0
+        try:
+            retry_after = int(response.headers.get("retry-after", "0"))
+        except ValueError:
+            retry_after = 0
+        raise RevocRateLimitError(retry_after_secs=retry_after)
+    if code == "REVOC_KILL_SWITCH_ACTIVE":
+        raise RevocKillSwitchError(
+            scope="global", dashboard_url=error.get("dashboard_url", "")
+        )
+    if code == "REVOC_GOVERNANCE_DEPTH_EXCEEDED":
+        depth = 10
+        message = error.get("message", "")
+        try:
+            fraction = message.split("(", 1)[1].split(")", 1)[0]
+            depth = int(fraction.split("/", 1)[0])
+        except (IndexError, ValueError):
+            pass
+        raise RevocDepthExceededError(depth=depth, max_depth=10)
+    if code == "REVOC_GOVERNANCE_BLOCK":
+        raise RevocGovernanceError(
+            reason=error.get("message", ""),
+            decision="block",
+            blocked_by=error.get("blocked_by"),
+            rules=error.get("rules") or [],
+            trace_id=error.get("trace_id", ""),
+            dashboard_url=error.get("dashboard_url", ""),
+            documentation_url=error.get("documentation_url"),
+        )

revoc_sdk-1.0.0/revoc_sdk/exceptions.py

@@ -0,0 +1,91 @@
+"""revoc_sdk.exceptions — typed exceptions raised when REVOC governs a request.
+
+These map 1:1 onto the `error.code` values produced by `RevocErrorResponse`
+(see SPEC.md Section 7.5 / types/openai.rs). The REVOC client inspects the
+JSON error body returned by the proxy and raises the matching exception type
+so application code can branch on governance outcomes without parsing HTTP
+responses by hand.
+"""
+
+from __future__ import annotations
+
+
+class RevocGovernanceError(Exception):
+    """Raised when REVOC blocks a request due to a policy violation.
+
+    Corresponds to `error.code == "REVOC_GOVERNANCE_BLOCK"`.
+    """
+
+    def __init__(
+        self,
+        decision: str,
+        blocked_by: str | None,
+        rules: list[str],
+        trace_id: str,
+        dashboard_url: str,
+        documentation_url: str | None = None,
+        *,
+        reason: str | None = None,
+    ) -> None:
+        self.decision = decision
+        self.blocked_by = blocked_by
+        self.rules = rules
+        self.trace_id = trace_id
+        self.dashboard_url = dashboard_url
+        self.documentation_url = documentation_url
+        rule_list = ", ".join(rules) or blocked_by or "unknown"
+        self.reason = reason or f"Request blocked by rule(s): {rule_list}"
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return (
+            f"REVOC blocked [{self.blocked_by}]: {self.reason}\n"
+            f"Trace: {self.trace_id}\nDashboard: {self.dashboard_url}"
+        )
+
+
+class RevocKillSwitchError(Exception):
+    """Raised when the emergency kill-switch is active.
+
+    Corresponds to `error.code == "REVOC_KILL_SWITCH_ACTIVE"`.
+    """
+
+    def __init__(self, *, scope: str, dashboard_url: str) -> None:
+        self.scope = scope
+        self.dashboard_url = dashboard_url
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return "REVOC emergency stop active. Contact your AI platform team."
+
+
+class RevocDepthExceededError(Exception):
+    """Raised when governance depth reaches the configured maximum.
+
+    Corresponds to `error.code == "REVOC_GOVERNANCE_DEPTH_EXCEEDED"`.
+    """
+
+    def __init__(self, *, depth: int, max_depth: int = 10) -> None:
+        self.depth = depth
+        self.max_depth = max_depth
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return (
+            f"Governance depth {self.depth}/{self.max_depth} reached. "
+            "Possible infinite agent loop."
+        )
+
+
+class RevocRateLimitError(Exception):
+    """Raised when the caller has exceeded their configured rate limit.
+
+    Corresponds to `error.code == "REVOC_RATE_LIMIT_EXCEEDED"`.
+    """
+
+    def __init__(self, *, retry_after_secs: int) -> None:
+        self.retry_after_secs = retry_after_secs
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return f"REVOC rate limit exceeded. Retry after {self.retry_after_secs} seconds."

revoc_sdk-1.0.0/revoc_sdk/governance.py

@@ -0,0 +1,96 @@
+"""revoc_sdk.governance — async client for the REVOC dashboard / admin-api.
+
+Exposed via `client.governance` on `RevocOpenAI` / `RevocAsyncOpenAI`. All
+methods are thin wrappers over the admin-api REST surface (see
+admin-api/app/routers/*) using httpx.AsyncClient under the hood.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+
+class GovernanceClient:
+    """Async helper for querying audit data and controlling governance state.
+
+    Parameters
+    ----------
+    base_url:
+        Base URL of the REVOC dashboard / admin-api (e.g. ``http://revoc:3000``).
+    api_key:
+        Optional bearer token / API key used to authenticate against the
+        admin-api. Sent as ``Authorization: Bearer <api_key>`` when present.
+    """
+
+    def __init__(self, base_url: str, *, api_key: str | None = None) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+    async def get_audit_events(self, **kwargs: Any) -> list[dict[str, Any]]:
+        """Fetch audit events matching the given query parameters.
+
+        Accepts the same query parameters as ``GET /api/v1/audit`` (e.g.
+        ``org_id``, ``decision``, ``limit``, ``offset``).
+        """
+        async with httpx.AsyncClient(base_url=self._base_url) as client:
+            resp = await client.get("/api/v1/audit", params=kwargs, headers=self._headers())
+            resp.raise_for_status()
+            data: list[dict[str, Any]] = resp.json()
+            return data
+
+    async def get_audit_stats(self, start_time: datetime, end_time: datetime) -> dict[str, Any]:
+        """Fetch aggregate audit statistics for a time window."""
+        params = {"start_time": start_time.isoformat(), "end_time": end_time.isoformat()}
+        async with httpx.AsyncClient(base_url=self._base_url) as client:
+            resp = await client.get("/api/v1/audit/stats", params=params, headers=self._headers())
+            resp.raise_for_status()
+            data: dict[str, Any] = resp.json()
+            return data
+
+    async def validate_policy(self, yaml_content: str) -> dict[str, Any]:
+        """Validate a policy bundle YAML manifest without activating it."""
+        async with httpx.AsyncClient(base_url=self._base_url) as client:
+            resp = await client.post(
+                "/api/v1/policies/validate",
+                json={"yaml_content": yaml_content},
+                headers=self._headers(),
+            )
+            resp.raise_for_status()
+            data: dict[str, Any] = resp.json()
+            return data
+
+    async def activate_kill_switch(self, scope: str, reason: str) -> dict[str, Any]:
+        """Activate the emergency kill-switch for the given scope.
+
+        ``scope`` is one of ``"global"``, ``"org"``, or ``"caller"``.
+        """
+        async with httpx.AsyncClient(base_url=self._base_url) as client:
+            resp = await client.post(
+                "/api/v1/emergency/kill-switch/activate",
+                json={"scope": scope, "reason": reason, "activated_by": "revoc-sdk"},
+                headers=self._headers(),
+            )
+            resp.raise_for_status()
+            data: dict[str, Any] = resp.json()
+            return data
+
+    async def deactivate_kill_switch(self, scope: str) -> dict[str, Any]:
+        """Deactivate the emergency kill-switch for the given scope."""
+        async with httpx.AsyncClient(base_url=self._base_url) as client:
+            resp = await client.post(
+                "/api/v1/emergency/kill-switch/deactivate",
+                json={"scope": scope},
+                headers=self._headers(),
+            )
+            resp.raise_for_status()
+            data: dict[str, Any] = resp.json()
+            return data

revoc_sdk-1.0.0/revoc_sdk/mcp.py

@@ -0,0 +1,138 @@
+"""revoc_sdk.mcp — helpers for governed Model Context Protocol tool calls.
+
+REVOC inspects MCP traffic bidirectionally (SPEC.md Section 11, MCP Handler
+12-step lifecycle). When a `tools/call` request is blocked, the proxy returns
+a JSON-RPC error response shaped like `McpBlockResponse`
+(`{"error": {"code": -32603, "data": {"code": "REVOC_GOVERNANCE_BLOCK", ...}}}`).
+
+This module provides a small helper that posts a governed `tools/call`
+request through REVOC and raises :class:`RevocMcpError` when the call was
+blocked, so MCP client code can handle governance outcomes uniformly with
+the LLM-side exceptions in :mod:`revoc_sdk.exceptions`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class RevocMcpError(Exception):
+    """Raised when REVOC blocks an MCP `tools/call` request.
+
+    Mirrors the JSON-RPC error payload (`McpBlockResponse` /
+    `McpBlockData`, see SPEC.md Section 7.4): the upstream MCP server never
+    receives a blocked request (Rule 9 in Section 23).
+    """
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        code: str,
+        rules: list[str],
+        trace_id: str,
+        dashboard_url: str,
+    ) -> None:
+        self.message = message
+        self.code = code
+        self.rules = rules
+        self.trace_id = trace_id
+        self.dashboard_url = dashboard_url
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return (
+            f"REVOC blocked MCP tool call [{self.code}]: {self.message}\n"
+            f"Trace: {self.dashboard_url}"
+        )
+
+
+class RevocMcpClient:
+    """Stateful client for governed MCP `tools/call` requests through REVOC.
+
+    Wraps :func:`governed_tool_call` with a persistent base URL, default
+    headers, and an auto-incrementing JSON-RPC request id, so callers can
+    issue repeated governed tool calls without repeating boilerplate.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self.headers = headers or {}
+        self._next_id = 1
+
+    def _request_id(self) -> str:
+        request_id = str(self._next_id)
+        self._next_id += 1
+        return request_id
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        *,
+        server_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Issue a governed `tools/call` request.
+
+        Raises :class:`RevocMcpError` if REVOC blocks the call before it
+        ever reaches the upstream MCP server (SPEC.md §23 Rule 9).
+        """
+        return await governed_tool_call(
+            self.base_url,
+            tool_name=tool_name,
+            arguments=arguments,
+            server_id=server_id,
+            request_id=self._request_id(),
+            headers=self.headers,
+        )
+
+
+async def governed_tool_call(
+    base_url: str,
+    *,
+    tool_name: str,
+    arguments: dict[str, Any],
+    server_id: str | None = None,
+    request_id: str = "1",
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """POST a `tools/call` JSON-RPC request through the REVOC MCP endpoint.
+
+    Returns the parsed JSON-RPC result on success. Raises
+    :class:`RevocMcpError` if REVOC blocked the call before it ever reached
+    the upstream MCP server.
+    """
+    payload: dict[str, Any] = {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "method": "tools/call",
+        "params": {"name": tool_name, "arguments": arguments},
+    }
+    if server_id is not None:
+        payload["params"]["server_id"] = server_id
+
+    async with httpx.AsyncClient(base_url=base_url) as client:
+        resp = await client.post("/mcp", json=payload, headers=headers or {})
+        resp.raise_for_status()
+        body: dict[str, Any] = resp.json()
+
+    error = body.get("error")
+    if isinstance(error, dict):
+        raw_data = error.get("data")
+        data: dict[str, Any] = raw_data if isinstance(raw_data, dict) else {}
+        if data.get("code") == "REVOC_GOVERNANCE_BLOCK":
+            raise RevocMcpError(
+                message=error.get("message", ""),
+                code=data.get("code", "REVOC_GOVERNANCE_BLOCK"),
+                rules=data.get("rules") or [],
+                trace_id=data.get("trace_id", ""),
+                dashboard_url=data.get("dashboard_url", ""),
+            )
+    return body

revoc_sdk-1.0.0/revoc_sdk/patch.py

@@ -0,0 +1,76 @@
+"""revoc_sdk.patch — zero-code-change activation for existing OpenAI clients.
+
+Calling :func:`patch` once at process startup monkey-patches
+``openai.OpenAI.__init__`` and ``openai.AsyncOpenAI.__init__`` so that *any*
+existing code that constructs an ``OpenAI()`` or ``AsyncOpenAI()`` client is
+transparently routed through REVOC — provided the ``REVOC_BASE_URL``
+environment variable is set. No source changes required (SPEC.md Section 2).
+
+    export REVOC_BASE_URL=http://revoc:8080
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import openai
+
+_PATCHED_ATTR = "_revoc_patched"
+_ORIGINAL_SYNC_INIT_ATTR = "_revoc_original_sync_init"
+_ORIGINAL_ASYNC_INIT_ATTR = "_revoc_original_async_init"
+
+
+def patch() -> None:
+    """Monkey-patch ``openai.OpenAI``/``openai.AsyncOpenAI`` to honor REVOC_BASE_URL.
+
+    Idempotent — calling this more than once is a no-op after the first call.
+    If ``REVOC_BASE_URL`` is not set at call time, this function does nothing
+    (existing client construction behaves exactly as before).
+    """
+    revoc_url = os.environ.get("REVOC_BASE_URL")
+    if not revoc_url:
+        return
+
+    if getattr(openai.OpenAI, _PATCHED_ATTR, False):
+        return
+
+    _original_sync_init = openai.OpenAI.__init__
+    _original_async_init = openai.AsyncOpenAI.__init__
+
+    def _patched_sync_init(self: openai.OpenAI, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("base_url", os.environ.get("REVOC_BASE_URL"))
+        _original_sync_init(self, *args, **kwargs)
+
+    def _patched_async_init(self: openai.AsyncOpenAI, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("base_url", os.environ.get("REVOC_BASE_URL"))
+        _original_async_init(self, *args, **kwargs)
+
+    setattr(openai.OpenAI, _ORIGINAL_SYNC_INIT_ATTR, _original_sync_init)
+    setattr(openai.AsyncOpenAI, _ORIGINAL_ASYNC_INIT_ATTR, _original_async_init)
+    openai.OpenAI.__init__ = _patched_sync_init  # type: ignore[method-assign]
+    openai.AsyncOpenAI.__init__ = _patched_async_init  # type: ignore[method-assign]
+    setattr(openai.OpenAI, _PATCHED_ATTR, True)
+    setattr(openai.AsyncOpenAI, _PATCHED_ATTR, True)
+
+
+def unpatch() -> None:
+    """Reverse the effect of :func:`patch`.
+
+    Restores ``openai.OpenAI.__init__`` and ``openai.AsyncOpenAI.__init__`` to
+    their pre-patch implementations. Idempotent — calling this when no patch
+    is active (or more than once) is a no-op.
+    """
+    if not getattr(openai.OpenAI, _PATCHED_ATTR, False):
+        return
+
+    original_sync_init = getattr(openai.OpenAI, _ORIGINAL_SYNC_INIT_ATTR)
+    original_async_init = getattr(openai.AsyncOpenAI, _ORIGINAL_ASYNC_INIT_ATTR)
+
+    openai.OpenAI.__init__ = original_sync_init  # type: ignore[method-assign]
+    openai.AsyncOpenAI.__init__ = original_async_init  # type: ignore[method-assign]
+
+    delattr(openai.OpenAI, _PATCHED_ATTR)
+    delattr(openai.AsyncOpenAI, _PATCHED_ATTR)
+    delattr(openai.OpenAI, _ORIGINAL_SYNC_INIT_ATTR)
+    delattr(openai.AsyncOpenAI, _ORIGINAL_ASYNC_INIT_ATTR)

revoc_sdk-1.0.0/tests/conftest.py

@@ -0,0 +1,11 @@
+"""tests/conftest.py — shared fixtures for revoc-sdk tests."""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Ensure REVOC_BASE_URL doesn't leak between tests."""
+    monkeypatch.delenv("REVOC_BASE_URL", raising=False)

revoc_sdk-1.0.0/tests/test_client.py

@@ -0,0 +1,141 @@
+"""tests/test_client.py — RevocOpenAI / RevocAsyncOpenAI behavior."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from openai import AsyncOpenAI, OpenAI
+
+from revoc_sdk import (
+    RevocAsyncOpenAI,
+    RevocDepthExceededError,
+    RevocGovernanceError,
+    RevocKillSwitchError,
+    RevocOpenAI,
+    patch,
+)
+from revoc_sdk.client import _async_response_hook, _response_hook
+
+_REVOC_URL = "http://revoc.local:8080"
+
+
+def test_base_url_set_from_arg() -> None:
+    client = RevocOpenAI(api_key="sk-test", revoc_base_url=_REVOC_URL)
+    assert str(client.base_url).rstrip("/") == _REVOC_URL
+
+
+def test_base_url_from_env_var(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("REVOC_BASE_URL", _REVOC_URL)
+    client = RevocOpenAI(api_key="sk-test")
+    assert str(client.base_url).rstrip("/") == _REVOC_URL
+
+
+def test_is_instance_of_openai() -> None:
+    client = RevocOpenAI(api_key="sk-test", revoc_base_url=_REVOC_URL)
+    assert isinstance(client, OpenAI)
+
+
+def test_async_client_is_instance_of_async_openai() -> None:
+    client = RevocAsyncOpenAI(api_key="sk-test", revoc_base_url=_REVOC_URL)
+    assert isinstance(client, AsyncOpenAI)
+
+
+def _build_response(status_code: int, payload: dict[str, object]) -> httpx.Response:
+    request = httpx.Request("POST", "http://revoc.local:8080/v1/chat/completions")
+    return httpx.Response(status_code, json=payload, request=request)
+
+
+def test_governance_block_raises_error() -> None:
+    payload = {
+        "error": {
+            "code": "REVOC_GOVERNANCE_BLOCK",
+            "message": "Prompt injection detected",
+            "blocked_by": "sec_prompt_injection_v1",
+            "rules": ["sec_prompt_injection_v1"],
+            "trace_id": "01911f6e-0000-7000-8000-000000000000",
+            "dashboard_url": "http://localhost:3000/traces/01911f6e",
+            "documentation_url": "https://revoc.io/docs/policies/sec_prompt_injection_v1",
+        }
+    }
+    response = _build_response(403, payload)
+    with pytest.raises(RevocGovernanceError) as exc_info:
+        _response_hook(response)
+    err = exc_info.value
+    assert err.blocked_by == "sec_prompt_injection_v1"
+    assert err.rules == ["sec_prompt_injection_v1"]
+    assert err.trace_id == "01911f6e-0000-7000-8000-000000000000"
+
+
+def test_kill_switch_raises_kill_switch_error() -> None:
+    payload = {
+        "error": {
+            "code": "REVOC_KILL_SWITCH_ACTIVE",
+            "message": "All AI traffic suspended by emergency stop.",
+            "trace_id": "trace-123",
+            "dashboard_url": "http://localhost:3000/emergency",
+        }
+    }
+    response = _build_response(503, payload)
+    with pytest.raises(RevocKillSwitchError):
+        _response_hook(response)
+
+
+def test_depth_raises_depth_error() -> None:
+    payload = {
+        "error": {
+            "code": "REVOC_GOVERNANCE_DEPTH_EXCEEDED",
+            "message": "Governance depth limit (10/10) reached. Possible infinite agent loop.",
+            "trace_id": "trace-456",
+            "dashboard_url": "http://localhost:3000/traces/trace-456",
+        }
+    }
+    response = _build_response(503, payload)
+    with pytest.raises(RevocDepthExceededError) as exc_info:
+        _response_hook(response)
+    assert exc_info.value.depth == 10
+    assert exc_info.value.max_depth == 10
+
+
+def test_error_str_contains_dashboard_url() -> None:
+    err = RevocGovernanceError(
+        reason="Blocked: secret detected",
+        decision="block",
+        blocked_by="secret_block_v1",
+        rules=["secret_block_v1"],
+        trace_id="trace-789",
+        dashboard_url="http://localhost:3000/traces/trace-789",
+    )
+    text = str(err)
+    assert "http://localhost:3000/traces/trace-789" in text
+    assert "secret_block_v1" in text
+
+
+def test_patch_injects_base_url(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("REVOC_BASE_URL", _REVOC_URL)
+    patch()
+    client = OpenAI(api_key="sk-test")
+    assert str(client.base_url).rstrip("/") == _REVOC_URL
+
+
+@pytest.mark.asyncio
+async def test_async_response_hook_raises_governance_error() -> None:
+    payload = {
+        "error": {
+            "code": "REVOC_GOVERNANCE_BLOCK",
+            "message": "Blocked",
+            "blocked_by": "secret_block_v1",
+            "rules": ["secret_block_v1"],
+            "trace_id": "trace-async",
+            "dashboard_url": "http://localhost:3000/traces/trace-async",
+        }
+    }
+    response = _build_response(403, payload)
+    with pytest.raises(RevocGovernanceError):
+        await _async_response_hook(response)
+
+
+def test_non_revoc_error_passes_through() -> None:
+    """Upstream provider errors (forwarded verbatim) must not raise REVOC exceptions."""
+    payload = {"error": {"message": "invalid_api_key", "type": "invalid_request_error"}}
+    response = _build_response(401, payload)
+    _response_hook(response)  # should not raise

revoc_sdk-1.0.0/tests/test_governance.py

@@ -0,0 +1,83 @@
+"""tests/test_governance.py — GovernanceClient HTTP wrapper behavior."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import httpx
+import pytest
+
+from revoc_sdk import GovernanceClient
+
+# Captured before any monkeypatching replaces httpx.AsyncClient, so the
+# patched factory below can construct a real client against a mock transport
+# without recursing into itself.
+_RealAsyncClient = httpx.AsyncClient
+
+
+@pytest.fixture
+def governance_client() -> GovernanceClient:
+    return GovernanceClient(base_url="http://revoc.local:3000", api_key="test-admin-key")
+
+
+@pytest.mark.asyncio
+async def test_get_audit_stats_sends_authorization_header(
+    governance_client: GovernanceClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(200, json={"total": 0, "blocked": 0, "redacted": 0, "allowed": 0})
+
+    transport = httpx.MockTransport(handler)
+    monkeypatch.setattr(
+        httpx,
+        "AsyncClient",
+        lambda **kw: _RealAsyncClient(transport=transport, base_url=kw.get("base_url", "")),
+    )
+
+    await governance_client.get_audit_stats(
+        datetime(2026, 6, 6, tzinfo=UTC), datetime(2026, 6, 7, tzinfo=UTC)
+    )
+    assert captured["request"].headers["authorization"] == "Bearer test-admin-key"
+    assert captured["request"].url.path == "/api/v1/audit/stats"
+
+
+@pytest.mark.asyncio
+async def test_validate_policy_returns_json(monkeypatch: pytest.MonkeyPatch) -> None:
+    client = GovernanceClient(base_url="http://revoc.local:3000")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"is_valid": True, "errors": []})
+
+    transport = httpx.MockTransport(handler)
+    monkeypatch.setattr(
+        httpx,
+        "AsyncClient",
+        lambda **kw: _RealAsyncClient(transport=transport, base_url=kw.get("base_url", "")),
+    )
+
+    result = await client.validate_policy("apiVersion: revoc.io/v1\nkind: PolicyManifest\n")
+    assert result["is_valid"] is True
+
+
+@pytest.mark.asyncio
+async def test_activate_kill_switch_posts_scope(monkeypatch: pytest.MonkeyPatch) -> None:
+    client = GovernanceClient(base_url="http://revoc.local:3000")
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(200, json={"scope": "global", "action": "activate"})
+
+    transport = httpx.MockTransport(handler)
+    monkeypatch.setattr(
+        httpx,
+        "AsyncClient",
+        lambda **kw: _RealAsyncClient(transport=transport, base_url=kw.get("base_url", "")),
+    )
+
+    result = await client.activate_kill_switch("global", "incident-123")
+    assert result["action"] == "activate"
+    assert captured["request"].url.path == "/api/v1/emergency/kill-switch/activate"