agentrust-py 0.0.3__py3-none-any.whl

agentrust_sdk/config.py

@@ -0,0 +1,192 @@
+"""
+AgentTrust SDK — centralized configuration.
+
+Config is resolved lazily on first access so that env-var injection at
+runtime (secrets managers, test fixtures) takes effect. The singleton
+SDK_CONFIG is still the primary entry point; call SDK_CONFIG.reload() after
+mutating os.environ in tests or container entrypoints.
+
+Environment variables
+---------------------
+AGENTRUST_ENABLED          "true"/"false"  — master kill-switch (default true)
+AGENTRUST_GATEWAY_URL      Gateway base URL (default http://localhost:8000)
+AGENTRUST_KEY              API key (overrides ~/.agentrust/config.yaml)
+AGENTRUST_TIMEOUT_SEC      Per-request HTTP timeout in seconds (default 10)
+AGENTRUST_RETRY_ATTEMPTS   Max retry attempts on transient failure (default 3)
+AGENTRUST_RETRY_BACKOFF    Initial backoff in seconds for exponential retry (default 0.5)
+AGENTRUST_FAILURE_MODE     open | closed | queue  (default open)
+                             open   — log and continue on gateway unreachable
+                             closed — raise BlockedError on gateway unreachable
+                             queue  — buffer locally and replay when gateway returns
+AGENTRUST_QUEUE_DB         SQLite path for failure-mode=queue buffer
+                             (default ~/.agentrust/queue.db)
+AGENTRUST_SDK_VERSION      Set automatically; override only in tests
+
+Webhook environment variables (Team tier and above)
+----------------------------------------------------
+AGENTRUST_WEBHOOK_URL      Single webhook URL to register on SDK init.
+                             Supports Discord (https://discord.com/api/webhooks/...)
+                             and any generic HTTPS endpoint.
+AGENTRUST_WEBHOOK_EVENTS   Comma-separated decision filter for the env-var webhook.
+                             Valid values: all | approve | block | escalate | request_evidence
+                             Defaults to "all" when AGENTRUST_WEBHOOK_URL is set.
+AGENTRUST_WEBHOOK_DB       SQLite path for the webhook registry
+                             (default ~/.agentrust/webhooks.db)
+AGENTRUST_WEBHOOK_TIMEOUT  Per-dispatch HTTP timeout in seconds (default 5)
+AGENTRUST_WEBHOOK_AUTO_DISPATCH
+                           "true"/"false" — fire webhooks automatically after
+                             every validate() call when a dispatcher is attached
+                             to the client (default true)
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_VALID_FAILURE_MODES = frozenset({"open", "closed", "queue"})
+_SDK_VERSION = "0.0.1a1"
+_MIN_GATEWAY_VERSION = "0.0.1a1"
+
+
+def _bool(key: str, default: bool) -> bool:
+    val = os.environ.get(key, "").lower()
+    if val in ("1", "true", "yes"):
+        return True
+    if val in ("0", "false", "no"):
+        return False
+    return default
+
+
+def _float(key: str, default: float) -> float:
+    try:
+        return float(os.environ[key])
+    except (KeyError, ValueError):
+        return default
+
+
+def _int(key: str, default: int) -> int:
+    try:
+        return int(os.environ[key])
+    except (KeyError, ValueError):
+        return default
+
+
+def _failure_mode(key: str, default: str) -> str:
+    val = os.environ.get(key, default).lower()
+    if val not in _VALID_FAILURE_MODES:
+        logger.warning(
+            "[AgentTrust] Invalid %s=%r — must be one of %s. Falling back to 'open'.",
+            key, val, sorted(_VALID_FAILURE_MODES),
+        )
+        return "open"
+    return val
+
+
+class _SDKConfig:
+    """
+    Lazily-resolved env-var config. All properties are read from os.environ
+    on each attribute access so runtime mutations (secrets managers, test
+    fixtures) take effect without a process restart.
+
+    Call reload() to invalidate any cached state (currently a no-op since
+    nothing is cached, but provided for forward-compat and test ergonomics).
+    """
+
+    # Immutable constants — never come from env
+    sdk_version: str = _SDK_VERSION
+    min_gateway_version: str = _MIN_GATEWAY_VERSION
+
+    @property
+    def enabled(self) -> bool:
+        return _bool("AGENTRUST_ENABLED", True)
+
+    @property
+    def gateway_url(self) -> str:
+        return os.environ.get("AGENTRUST_GATEWAY_URL", "http://localhost:8000")
+
+    @gateway_url.setter
+    def gateway_url(self, value: str) -> None:
+        # Allow embed_gateway() to override after the fact.
+        os.environ["AGENTRUST_GATEWAY_URL"] = value
+
+    @property
+    def api_key(self) -> str | None:
+        return os.environ.get("AGENTRUST_KEY") or None
+
+    @property
+    def timeout_sec(self) -> float:
+        return _float("AGENTRUST_TIMEOUT_SEC", 10.0)
+
+    @property
+    def retry_attempts(self) -> int:
+        return _int("AGENTRUST_RETRY_ATTEMPTS", 3)
+
+    @property
+    def retry_backoff_sec(self) -> float:
+        return _float("AGENTRUST_RETRY_BACKOFF", 0.5)
+
+    @property
+    def failure_mode(self) -> str:
+        return _failure_mode("AGENTRUST_FAILURE_MODE", "open")
+
+    @property
+    def queue_db(self) -> Path:
+        return Path(
+            os.environ.get("AGENTRUST_QUEUE_DB",
+                           str(Path.home() / ".agentrust" / "queue.db"))
+        )
+
+    # ── Webhook configuration (Team tier and above) ──────────────────────────
+
+    @property
+    def webhook_url(self) -> str | None:
+        """Single webhook URL bootstrapped from AGENTRUST_WEBHOOK_URL (optional)."""
+        return os.environ.get("AGENTRUST_WEBHOOK_URL") or None
+
+    @property
+    def webhook_events(self) -> list[str]:
+        """
+        Decision filter for the env-var webhook.
+
+        Parsed from AGENTRUST_WEBHOOK_EVENTS (comma-separated).
+        Defaults to ["all"] when the env var is absent or empty.
+        """
+        raw = os.environ.get("AGENTRUST_WEBHOOK_EVENTS", "all").strip()
+        parts = [e.strip() for e in raw.split(",") if e.strip()]
+        return parts if parts else ["all"]
+
+    @property
+    def webhook_db(self) -> Path:
+        """SQLite path for the webhook registry (default ~/.agentrust/webhooks.db)."""
+        return Path(
+            os.environ.get(
+                "AGENTRUST_WEBHOOK_DB",
+                str(Path.home() / ".agentrust" / "webhooks.db"),
+            )
+        )
+
+    @property
+    def webhook_timeout(self) -> float:
+        """Per-dispatch HTTP timeout in seconds (default 5)."""
+        return _float("AGENTRUST_WEBHOOK_TIMEOUT", 5.0)
+
+    @property
+    def webhook_auto_dispatch(self) -> bool:
+        """
+        Whether the client should fire webhooks automatically after every
+        validate() call when a dispatcher is attached (default True).
+        """
+        return _bool("AGENTRUST_WEBHOOK_AUTO_DISPATCH", True)
+
+    def is_failure_mode(self, mode: str) -> bool:
+        return self.failure_mode == mode
+
+    def reload(self) -> None:
+        """No-op — all properties are already live. Provided for test ergonomics."""
+
+
+# Module-level singleton — import as `from .config import SDK_CONFIG`
+SDK_CONFIG = _SDKConfig()

agentrust_sdk/decorator.py

@@ -0,0 +1,276 @@
+"""
+@harness — the single-line AgentTrust integration for any agent function.
+
+Replaces the old @validate decorator. Reads config automatically from
+~/.agentrust/config.yaml so no arguments are required in most cases.
+
+Usage (zero config after `agentrust init`)::
+
+    from agentrust import harness
+
+    @harness
+    def run_payment(user: str, input: str) -> dict:
+        return {"amount": 500, "status": "processed"}
+
+Advanced usage::
+
+    @harness(
+        agent_id="payment-agent",       # override auto-detected name
+        block_on_block=True,            # raise BlockedError when blocked
+        block_on_review=False,
+        raise_on_tier_gate=False,       # don't raise when capability above tier
+    )
+    async def run_async_agent(user: str, input: str) -> dict:
+        return {"result": "done"}
+"""
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import logging
+import time
+from typing import Any, Callable
+
+from .auth import read_config, resolve_key
+from .config import SDK_CONFIG
+from .tiers import Capability, Tier, is_allowed
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# BlockedError
+# ---------------------------------------------------------------------------
+
+class BlockedError(RuntimeError):
+    """Raised when AgentTrust blocks or escalates an execution."""
+
+    def __init__(self, outcome: str, reason: str, envelope_id: str) -> None:
+        super().__init__(f"AgentTrust [{outcome}]: {reason}")
+        self.outcome = outcome
+        self.reason = reason
+        self.envelope_id = envelope_id
+
+
+# ---------------------------------------------------------------------------
+# @harness — supports both @harness and @harness(...) usage
+# ---------------------------------------------------------------------------
+
+def harness(
+    fn: Callable | None = None,
+    *,
+    agent_id: str | None = None,
+    user_kwarg: str = "user",
+    input_kwarg: str = "input",
+    base_url: str | None = None,
+    api_key: str | None = None,
+    block_on_block: bool = True,
+    block_on_review: bool = False,
+    raise_on_tier_gate: bool = False,
+    framework: str | None = None,
+    raise_on_error: bool = False,
+) -> Any:
+    """
+    Decorator that validates agent output via AgentTrust after the function returns.
+
+    Can be used bare (@harness) or with arguments (@harness(...)).
+    Config is auto-resolved from ~/.agentrust/config.yaml if not provided.
+    """
+    def _decorator(f: Callable) -> Callable:
+        # ── kill-switch: AGENTRUST_ENABLED=false → return original function unchanged ──
+        if not SDK_CONFIG.enabled:
+            return f
+
+        _agent_id = agent_id or f.__name__
+        _framework = framework or _detect_framework()
+        _base_url = base_url or _resolve_base_url()
+        _api_key = api_key
+
+        if inspect.iscoroutinefunction(f):
+            return _async_wrapper(
+                f, _agent_id, user_kwarg, input_kwarg,
+                _base_url, _api_key, block_on_block, block_on_review,
+                raise_on_tier_gate, _framework, raise_on_error,
+            )
+        return _sync_wrapper(
+            f, _agent_id, user_kwarg, input_kwarg,
+            _base_url, _api_key, block_on_block, block_on_review,
+            raise_on_tier_gate, _framework, raise_on_error,
+        )
+
+    if fn is not None:
+        if isinstance(fn, str):
+            # Used as @validate("agent-id") — legacy positional agent_id arg
+            _positional_id = fn
+            def _decorator_with_id(f: Callable) -> Callable:
+                _aid = _positional_id
+                _framework = framework or _detect_framework()
+                _base_url = base_url or _resolve_base_url()
+                if inspect.iscoroutinefunction(f):
+                    return _async_wrapper(
+                        f, _aid, user_kwarg, input_kwarg,
+                        _base_url, api_key, block_on_block, block_on_review,
+                        raise_on_tier_gate, _framework, raise_on_error,
+                    )
+                return _sync_wrapper(
+                    f, _aid, user_kwarg, input_kwarg,
+                    _base_url, api_key, block_on_block, block_on_review,
+                    raise_on_tier_gate, _framework, raise_on_error,
+                )
+            return _decorator_with_id
+        # Used as @harness (no parentheses)
+        return _decorator(fn)
+
+    # Used as @harness(...) (with arguments)
+    return _decorator
+
+
+# ---------------------------------------------------------------------------
+# Internal sync/async wrappers
+# ---------------------------------------------------------------------------
+
+def _sync_wrapper(
+    fn: Callable,
+    agent_id: str,
+    user_kwarg: str,
+    input_kwarg: str,
+    base_url: str,
+    api_key: str | None,
+    block_on_block: bool,
+    block_on_review: bool,
+    raise_on_tier_gate: bool,
+    framework: str,
+    raise_on_error: bool,
+) -> Callable:
+    from .client import AgentTrustClient
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        t0 = time.perf_counter()
+        result = fn(*args, **kwargs)
+        latency_ms = (time.perf_counter() - t0) * 1000
+
+        user = kwargs.get(user_kwarg, "unknown")
+        inp = kwargs.get(input_kwarg, "")
+        output = result if isinstance(result, dict) else {"result": str(result)}
+
+        try:
+            with AgentTrustClient(
+                base_url=base_url,
+                api_key=api_key,
+                raise_on_tier_gate=raise_on_tier_gate,
+            ) as client:
+                resp = client.validate(
+                    agent_id=agent_id,
+                    user=str(user),
+                    input=str(inp),
+                    output=output,
+                    framework=framework,
+                    latency_ms=latency_ms,
+                )
+            _check_decision(resp, block_on_block, block_on_review)
+        except BlockedError:
+            raise
+        except Exception as exc:
+            if raise_on_error:
+                raise
+            logger.warning("[AgentTrust] Validation failed (non-fatal): %s", exc)
+
+        return result
+
+    return wrapper
+
+
+def _async_wrapper(
+    fn: Callable,
+    agent_id: str,
+    user_kwarg: str,
+    input_kwarg: str,
+    base_url: str,
+    api_key: str | None,
+    block_on_block: bool,
+    block_on_review: bool,
+    raise_on_tier_gate: bool,
+    framework: str,
+    raise_on_error: bool,
+) -> Callable:
+    from .client import AsyncAgentTrustClient
+
+    @functools.wraps(fn)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        t0 = time.perf_counter()
+        result = await fn(*args, **kwargs)
+        latency_ms = (time.perf_counter() - t0) * 1000
+
+        user = kwargs.get(user_kwarg, "unknown")
+        inp = kwargs.get(input_kwarg, "")
+        output = result if isinstance(result, dict) else {"result": str(result)}
+
+        try:
+            async with AsyncAgentTrustClient(
+                base_url=base_url,
+                api_key=api_key,
+                raise_on_tier_gate=raise_on_tier_gate,
+            ) as client:
+                resp = await client.validate(
+                    agent_id=agent_id,
+                    user=str(user),
+                    input=str(inp),
+                    output=output,
+                    framework=framework,
+                    latency_ms=latency_ms,
+                )
+            _check_decision(resp, block_on_block, block_on_review)
+        except BlockedError:
+            raise
+        except Exception as exc:
+            if raise_on_error:
+                raise
+            logger.warning("[AgentTrust] Async validation failed (non-fatal): %s", exc)
+
+        return result
+
+    return wrapper
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _check_decision(resp: Any, block_on_block: bool, block_on_review: bool) -> None:
+    outcome = resp.decision.outcome
+    if block_on_block and outcome == "block":
+        raise BlockedError(outcome, resp.decision.reason, resp.envelope_id)
+    if block_on_review and outcome in ("escalate", "request_evidence"):
+        raise BlockedError(outcome, resp.decision.reason, resp.envelope_id)
+
+
+def _detect_framework() -> str:
+    """Best-effort framework detection from installed packages."""
+    try:
+        import importlib
+        for name, label in [
+            ("langgraph", "LangGraph"),
+            ("crewai", "CrewAI"),
+            ("langchain", "LangChain"),
+            ("autogen", "AutoGen"),
+            ("llama_index", "LlamaIndex"),
+        ]:
+            if importlib.util.find_spec(name):
+                return label
+    except Exception:
+        pass
+    return "REST"
+
+
+def _resolve_base_url() -> str:
+    # Env var takes priority, then config file, then default
+    if SDK_CONFIG.gateway_url != "http://localhost:8000":
+        return SDK_CONFIG.gateway_url
+    cfg = read_config("project") or read_config("global")
+    return cfg.get("control_plane_url", SDK_CONFIG.gateway_url)
+
+
+# Keep old name as alias for backward compat
+validate = harness