verdicter 1.0.0__py3-none-any.whl

verdicter/__init__.py

@@ -0,0 +1,22 @@
+from .client import Verdicter
+from .errors import VerdicterError
+from .types import (
+    Decision,
+    EvaluateRequest,
+    EvaluateResponse,
+    TraceStep,
+    VerdicterConfig,
+    WrapOptions,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "Verdicter",
+    "VerdicterError",
+    "Decision",
+    "EvaluateRequest",
+    "EvaluateResponse",
+    "TraceStep",
+    "VerdicterConfig",
+    "WrapOptions",
+]

verdicter/adapters/langchain.py

@@ -0,0 +1,82 @@
+"""
+LangChain adapter for Verdicter.
+
+Wraps LangChain tools so every invocation passes through Verdicter's
+policy engine before execution.
+
+Example::
+
+    from verdicter.adapters.langchain import wrap_tools
+
+    safe_tools = wrap_tools(tools, client, agent_id="support_bot")
+    agent = create_react_agent(llm=llm, tools=safe_tools)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ..errors import VerdicterError
+from ..types import WrapOptions
+
+if TYPE_CHECKING:
+    from ..client import Verdicter
+
+
+def wrap_tools(tools: list[Any], client: "Verdicter", *, agent_id: str, **kwargs: Any) -> list[Any]:
+    """Wrap a list of LangChain tools with Verdicter policy enforcement."""
+    options = WrapOptions(agent_id=agent_id, **kwargs)
+    return [wrap_tool(t, client, options) for t in tools]
+
+
+def wrap_tool(tool: Any, client: "Verdicter", options: WrapOptions) -> Any:
+    """Wrap a single LangChain tool with Verdicter policy enforcement."""
+    try:
+        from langchain_core.tools import BaseTool
+    except ImportError:
+        raise ImportError(
+            "langchain-core is required for the LangChain adapter. "
+            "Install it with: pip install verdicter[langchain]"
+        )
+
+    original_invoke = tool._run if hasattr(tool, "_run") else tool.invoke
+    tool_name = tool.name
+
+    async def guarded_ainvoke(input: Any, **kw: Any) -> Any:
+        payload = input if isinstance(input, dict) else {"input": input}
+        res = await client.evaluate(
+            agent_id=options.agent_id,
+            tool=tool_name,
+            payload=payload,
+            session_id=options.session_id,
+            context=options.context,
+            credential_name=options.credential_name,
+        )
+
+        if res.decision == "DENY":
+            if options.on_deny:
+                return options.on_deny(res)
+            raise VerdicterError(
+                f'Tool "{tool_name}" denied: {res.reason or "policy match"}', "UNKNOWN"
+            )
+
+        if res.decision == "ESCALATE":
+            if options.on_escalate:
+                return options.on_escalate(res)
+            raise VerdicterError(
+                f'Tool "{tool_name}" requires human approval: {res.reason or "escalation policy"}',
+                "UNKNOWN",
+            )
+
+        effective = (
+            res.modified_payload
+            if res.decision == "MODIFY" and res.modified_payload
+            else payload
+        )
+
+        if hasattr(tool, "ainvoke"):
+            return await tool.ainvoke(effective, **kw)
+        return original_invoke(effective, **kw)
+
+    tool.ainvoke = guarded_ainvoke  # type: ignore[method-assign]
+    return tool

verdicter/client.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Callable, TypeVar
+
+import httpx
+
+from .errors import VerdicterError
+from .types import (
+    EvaluateRequest,
+    EvaluateResponse,
+    TraceStep,
+    VerdicterConfig,
+    WrapOptions,
+)
+
+SDK_VERSION = "1.0.0"
+RETRYABLE_STATUSES = {429, 502, 503, 504}
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class Verdicter:
+    """
+    Runtime security client for AI agents.
+
+    Example::
+
+        from verdicter import Verdicter
+
+        client = Verdicter(api_key="verdicter_live_...")
+
+        result = await client.evaluate(
+            agent_id="support_bot",
+            tool="send_email",
+            payload={"to": user_email, "subject": subject, "body": body},
+        )
+
+        if result.decision == "ALLOW":
+            await send_email(payload)
+        elif result.decision == "DENY":
+            raise PermissionError(result.reason)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.verdicter.dev",
+        timeout: float = 5.0,
+        max_retries: int = 2,
+        retry_backoff: float = 0.2,
+        fail_open: bool = False,
+    ) -> None:
+        if not api_key:
+            raise VerdicterError("api_key is required", "UNAUTHORIZED")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._retry_backoff = retry_backoff
+        self._fail_open = fail_open
+
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "X-Verdicter-SDK": f"python/{SDK_VERSION}",
+        }
+
+    async def evaluate(
+        self,
+        *,
+        agent_id: str,
+        tool: str,
+        payload: dict[str, Any],
+        session_id: str | None = None,
+        context: dict[str, Any] | None = None,
+        credential_name: str | None = None,
+    ) -> EvaluateResponse:
+        """Evaluate an agent tool call against your policies."""
+        if not agent_id:
+            raise VerdicterError("agent_id is required", "VALIDATION_ERROR")
+        if not tool:
+            raise VerdicterError("tool is required", "VALIDATION_ERROR")
+        if not isinstance(payload, dict):
+            raise VerdicterError("payload must be a dict", "VALIDATION_ERROR")
+
+        body: dict[str, Any] = {
+            "agent_id": agent_id,
+            "tool": tool,
+            "payload": payload,
+            "context": context or {},
+        }
+        if session_id:
+            body["session_id"] = session_id
+        if credential_name:
+            body["credential_name"] = credential_name
+
+        try:
+            return await self._post("/v1/evaluate", body)
+        except VerdicterError as e:
+            if self._fail_open and e.code in ("NETWORK_ERROR", "TIMEOUT"):
+                return EvaluateResponse(
+                    call_id="failopen",
+                    decision="ALLOW",
+                    reason="Verdicter unreachable — fail-open policy applied",
+                    risk_score=0,
+                    trace=[],
+                    latency_ms=0,
+                    timestamp="",
+                )
+            raise
+
+    def wrap(self, tool: str, fn: F, options: WrapOptions) -> F:
+        """
+        Wrap a coroutine function so every call is evaluated first.
+
+        Example::
+
+            safe_send = client.wrap("send_email", send_email, WrapOptions(agent_id="bot"))
+            await safe_send(to=email, subject=subject, body=body)
+        """
+        async def wrapped(*args: Any, **kwargs: Any) -> Any:
+            payload = kwargs if kwargs else (args[0] if args and isinstance(args[0], dict) else {})
+            res = await self.evaluate(
+                agent_id=options.agent_id,
+                tool=tool,
+                payload=payload,
+                session_id=options.session_id,
+                context=options.context,
+                credential_name=options.credential_name,
+            )
+
+            if res.decision == "DENY":
+                if options.on_deny:
+                    return await _maybe_await(options.on_deny(res))
+                raise VerdicterError(
+                    f'Action "{tool}" denied: {res.reason or "policy match"}', "UNKNOWN"
+                )
+
+            if res.decision == "ESCALATE":
+                if options.on_escalate:
+                    return await _maybe_await(options.on_escalate(res))
+                raise VerdicterError(
+                    f'Action "{tool}" requires human approval: {res.reason or "escalation policy"}',
+                    "UNKNOWN",
+                )
+
+            effective_payload = (
+                res.modified_payload
+                if res.decision == "MODIFY" and res.modified_payload
+                else payload
+            )
+
+            if isinstance(effective_payload, dict) and kwargs:
+                return await _maybe_await(fn(**effective_payload))
+            return await _maybe_await(fn(effective_payload))
+
+        wrapped.__name__ = getattr(fn, "__name__", tool)  # type: ignore[attr-defined]
+        return wrapped  # type: ignore[return-value]
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    async def _post(self, path: str, body: dict[str, Any], attempt: int = 0) -> EvaluateResponse:
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            try:
+                resp = await client.post(
+                    f"{self._base_url}{path}",
+                    json=body,
+                    headers=self._headers,
+                )
+            except httpx.TimeoutException:
+                if attempt < self._max_retries:
+                    await asyncio.sleep(self._retry_backoff * (2 ** attempt))
+                    return await self._post(path, body, attempt + 1)
+                raise VerdicterError(
+                    f"Request timed out after {self._timeout}s", "TIMEOUT"
+                )
+            except httpx.RequestError as e:
+                if attempt < self._max_retries:
+                    await asyncio.sleep(self._retry_backoff * (2 ** attempt))
+                    return await self._post(path, body, attempt + 1)
+                raise VerdicterError(f"Network error: {e}", "NETWORK_ERROR")
+
+        if resp.status_code in (401, 403):
+            raise VerdicterError("Invalid or revoked API key", "UNAUTHORIZED", resp.status_code)
+        if resp.status_code == 404:
+            data = _safe_json(resp)
+            raise VerdicterError(str(data.get("error", "Agent not found")), "AGENT_NOT_FOUND", 404)
+        if resp.status_code == 422:
+            data = _safe_json(resp)
+            raise VerdicterError(str(data.get("error", "Validation failed")), "VALIDATION_ERROR", 422)
+        if resp.status_code == 429:
+            raise VerdicterError("Rate limit exceeded", "RATE_LIMITED", 429)
+        if resp.status_code in RETRYABLE_STATUSES and attempt < self._max_retries:
+            await asyncio.sleep(self._retry_backoff * (2 ** attempt))
+            return await self._post(path, body, attempt + 1)
+        if not resp.is_success:
+            data = _safe_json(resp)
+            raise VerdicterError(
+                str(data.get("error", f"HTTP {resp.status_code}")), "UNKNOWN", resp.status_code
+            )
+
+        return _parse_response(resp.json())
+
+
+def _safe_json(resp: httpx.Response) -> dict[str, Any]:
+    try:
+        return resp.json()
+    except Exception:
+        return {}
+
+
+def _parse_response(data: dict[str, Any]) -> EvaluateResponse:
+    trace = [
+        TraceStep(
+            step=s["step"],
+            result=s["result"],
+            detail=s.get("detail"),
+            policy_id=s.get("policyId"),
+        )
+        for s in data.get("trace", [])
+    ]
+    return EvaluateResponse(
+        call_id=data["callId"],
+        decision=data["decision"],
+        reason=data.get("reason"),
+        policy_id=data.get("policyId"),
+        modified_payload=data.get("modifiedPayload"),
+        risk_score=data["riskScore"],
+        trace=trace,
+        latency_ms=data["latencyMs"],
+        timestamp=data["timestamp"],
+    )
+
+
+async def _maybe_await(value: Any) -> Any:
+    if inspect.isawaitable(value):
+        return await value
+    return value

verdicter/errors.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Optional
+from .types import ErrorCode
+
+
+class VerdicterError(Exception):
+    def __init__(
+        self,
+        message: str,
+        code: ErrorCode = "UNKNOWN",
+        status_code: Optional[int] = None,
+        call_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.call_id = call_id
+
+    def __repr__(self) -> str:
+        return f"VerdicterError(code={self.code!r}, message={str(self)!r})"

verdicter/types.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Coroutine, Literal, Optional
+
+Decision = Literal["ALLOW", "DENY", "ESCALATE", "MODIFY"]
+
+ErrorCode = Literal[
+    "UNAUTHORIZED",
+    "AGENT_NOT_FOUND",
+    "VALIDATION_ERROR",
+    "RATE_LIMITED",
+    "TIMEOUT",
+    "NETWORK_ERROR",
+    "UNKNOWN",
+]
+
+
+@dataclass
+class TraceStep:
+    step: str
+    result: Literal["pass", "fail", "skip"]
+    detail: Optional[str] = None
+    policy_id: Optional[str] = None
+
+
+@dataclass
+class EvaluateResponse:
+    call_id: str
+    decision: Decision
+    risk_score: int
+    trace: list[TraceStep]
+    latency_ms: int
+    timestamp: str
+    reason: Optional[str] = None
+    policy_id: Optional[str] = None
+    modified_payload: Optional[dict[str, Any]] = None
+
+
+@dataclass
+class EvaluateRequest:
+    agent_id: str
+    tool: str
+    payload: dict[str, Any]
+    session_id: Optional[str] = None
+    context: Optional[dict[str, Any]] = None
+    credential_name: Optional[str] = None
+
+
+@dataclass
+class VerdicterConfig:
+    api_key: str
+    base_url: str = "https://api.verdicter.dev"
+    timeout: float = 5.0
+    max_retries: int = 2
+    retry_backoff: float = 0.2
+    fail_open: bool = False
+
+
+@dataclass
+class WrapOptions:
+    agent_id: str
+    session_id: Optional[str] = None
+    context: Optional[dict[str, Any]] = None
+    credential_name: Optional[str] = None
+    on_deny: Optional[Callable[[EvaluateResponse], Any]] = None
+    on_escalate: Optional[Callable[[EvaluateResponse], Any]] = None

verdicter-1.0.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: verdicter
+Version: 1.0.0
+Summary: Runtime security for AI agents — evaluate tool calls against policies in real time
+Project-URL: Homepage, https://verdicter.dev
+Project-URL: Documentation, https://docs.verdicter.dev
+Project-URL: Repository, https://github.com/QuackaDuck/arbiter-app
+Author: Verdicter
+License: MIT
+Keywords: agents,ai,policy,runtime,sdk,security,verdicter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# verdicter
+
+**Runtime security for AI agents.** Evaluate every tool call against your policies — get ALLOW, DENY, MODIFY, or ESCALATE in under 50ms.
+
+[![PyPI version](https://img.shields.io/pypi/v/verdicter)](https://pypi.org/project/verdicter/)
+[![Python versions](https://img.shields.io/pypi/pyversions/verdicter)](https://pypi.org/project/verdicter/)
+[![license](https://img.shields.io/pypi/l/verdicter)](./LICENSE)
+
+→ **[Get your free API key at verdicter.dev](https://verdicter.dev)**
+
+---
+
+## Install
+
+```bash
+pip install verdicter
+```
+
+With LangChain support:
+
+```bash
+pip install "verdicter[langchain]"
+```
+
+---
+
+## Quick start
+
+```python
+import asyncio
+from verdicter import Verdicter
+
+client = Verdicter(api_key="verdicter_live_...")
+
+async def main():
+    result = await client.evaluate(
+        agent_id="support_bot",   # registered in your Verdicter dashboard
+        tool="send_email",
+        payload={"to": user_email, "subject": subject, "body": body},
+    )
+
+    if result.decision == "ALLOW":
+        await send_email(payload)
+    elif result.decision == "MODIFY":
+        await send_email(result.modified_payload)   # Verdicter rewrote the payload
+    elif result.decision == "DENY":
+        raise PermissionError(f"Blocked: {result.reason}")
+    elif result.decision == "ESCALATE":
+        await request_human_approval(payload)
+```
+
+---
+
+## Wrap a function
+
+Zero per-call boilerplate — evaluation happens automatically on every invocation:
+
+```python
+from verdicter import Verdicter, WrapOptions
+
+client = Verdicter(api_key="verdicter_live_...")
+
+safe_send_email = client.wrap(
+    "send_email",
+    send_email,
+    WrapOptions(agent_id="support_bot"),
+)
+
+# Policy enforcement is automatic
+await safe_send_email(to=user_email, subject=subject, body=body)
+```
+
+---
+
+## LangChain adapter
+
+```python
+from verdicter import Verdicter
+from verdicter.adapters.langchain import wrap_tools
+from langchain_core.tools import tool
+
+client = Verdicter(api_key="verdicter_live_...")
+
+@tool
+def send_email(to: str, subject: str, body: str) -> str:
+    """Send an email."""
+    ...
+
+# Wrap your tools — every invocation goes through Verdicter
+safe_tools = wrap_tools([send_email], client, agent_id="support_bot")
+
+agent = create_react_agent(llm=llm, tools=safe_tools)
+```
+
+---
+
+## Configuration
+
+```python
+client = Verdicter(
+    api_key="verdicter_live_...",
+    timeout=5.0,        # seconds, default 5.0
+    max_retries=2,      # default 2
+    fail_open=False,    # if True, ALLOW on network errors (default: False = fail closed)
+)
+```
+
+---
+
+## Decisions
+
+| Decision | Meaning |
+|----------|---------|
+| `ALLOW` | Policy passed — run the tool |
+| `DENY` | Policy blocked it — don't run |
+| `MODIFY` | Policy rewrote the payload — use `result.modified_payload` |
+| `ESCALATE` | Needs human review — route to your approval flow |
+
+---
+
+## Links
+
+- [Sign up free → verdicter.dev](https://verdicter.dev)
+- [Dashboard → app.verdicter.dev](https://app.verdicter.dev)
+- [Documentation → docs.verdicter.dev](https://docs.verdicter.dev)
+- [npm package → npmjs.com/package/verdicter](https://www.npmjs.com/package/verdicter)
+
+---
+
+MIT License © [Verdicter](https://verdicter.dev)

verdicter-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+verdicter/__init__.py,sha256=3ae6Z7fQML9UwI_vqPyLAK5vPqtkQkAUORdbFWd3doo,396
+verdicter/client.py,sha256=DeGGlaccLsjbPCqtL6YBcjR69jciD_bDMzw3UiIrNts,8451
+verdicter/errors.py,sha256=sSgjgzCa5ffvrlT6AW-Vvokpm88pzoeQTSgLlENFhXY,553
+verdicter/types.py,sha256=tJYhmb-pcfaqaA0UulQn6aBC4O8AdF1xFBnkbnkC9zQ,1540
+verdicter/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+verdicter/adapters/langchain.py,sha256=60Wp-LM4HDe9gsjlKBB9bb9p0_0-heYizCo4JyQ-GmA,2671
+verdicter-1.0.0.dist-info/METADATA,sha256=1Y3VMT0dzf7ShBkY650Nm7Qp7Mbe4-rTGKzBg0Byxmw,4456
+verdicter-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+verdicter-1.0.0.dist-info/RECORD,,

verdicter-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any