kerneva-runtime-trust 0.3.0__py3-none-any.whl

kerneva_runtime_trust/__init__.py

@@ -0,0 +1,43 @@
+from .client import KernevaClient
+from .context import (
+    current_agent_id,
+    current_customer_id,
+    current_metadata,
+    current_session_id,
+    new_session_id,
+    session,
+)
+from .exceptions import KernevaBlocked, KernevaError
+from .models import (
+    AgentSummary,
+    EvaluationDetail,
+    EvaluationResult,
+    ExecutionOutcome,
+    HistoryEntry,
+    SignalEntry,
+    TraceEntry,
+)
+from .runtime_trust import ReviewContext, RuntimeTrustBlock, guard, with_runtime_trust
+
+__all__ = [
+    "with_runtime_trust",
+    "guard",
+    "RuntimeTrustBlock",
+    "ReviewContext",
+    "session",
+    "new_session_id",
+    "current_agent_id",
+    "current_session_id",
+    "current_customer_id",
+    "current_metadata",
+    "KernevaClient",
+    "KernevaError",
+    "KernevaBlocked",
+    "EvaluationResult",
+    "ExecutionOutcome",
+    "EvaluationDetail",
+    "HistoryEntry",
+    "AgentSummary",
+    "SignalEntry",
+    "TraceEntry",
+]

kerneva_runtime_trust/client.py

@@ -0,0 +1,509 @@
+import json
+import logging
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Literal, Optional
+from urllib.parse import urlencode
+
+from .exceptions import (
+    KernevaAuthError, KernevaBlocked, KernevaError,
+    KernevaFatalError, KernevaRetryableError, KernevaTimeoutError,
+    KernevaValidationError,
+)
+from .models import (
+    AgentSummary,
+    EvaluationDetail,
+    EvaluationResult,
+    HistoryEntry,
+)
+
+logger = logging.getLogger("kerneva_runtime_trust")
+
+ExecutionStatus = Literal[
+    "completed",
+    "failed",
+    "blocked",
+    "abandoned",
+    "timed_out",
+]
+
+_EXECUTION_TO_REVIEW: Dict[str, Dict[str, str]] = {
+    "completed": {"status": "resolved", "resolution": "completed"},
+    "failed": {"status": "resolved", "resolution": "failed"},
+    "blocked": {"status": "resolved", "resolution": "blocked_by_external"},
+    "abandoned": {"status": "dismissed", "resolution": "abandoned"},
+    "timed_out": {"status": "dismissed", "resolution": "timed_out"},
+}
+
+_DEFAULT_API_URL = "https://api.kerneva.com"
+
+# Retry configuration
+_RETRYABLE_STATUSES = {429, 503}
+_MAX_RETRIES = 3
+_BASE_DELAY = 1.0  # seconds
+_MAX_DELAY = 10.0  # seconds
+
+
+def _build_url(base: str, path: str, query: Optional[Dict[str, Any]] = None) -> str:
+    base = base.rstrip("/")
+    url = f"{base}{path}"
+    if query:
+        params = {k: v for k, v in query.items() if v is not None}
+        if params:
+            url = f"{url}?{urlencode(params)}"
+    return url
+
+
+def _retry_delay(attempt: int) -> float:
+    """Exponential backoff with jitter."""
+    delay = min(_BASE_DELAY * (2 ** attempt), _MAX_DELAY)
+    # Add ±25% jitter
+    import random
+    jitter = delay * 0.25 * (2 * random.random() - 1)
+    return delay + jitter
+
+
+class KernevaClient:
+    """Low-level client for the Kerneva API.
+
+    Usage:
+        client = KernevaClient(api_key="krv_test_...")
+        result = client.evaluate(
+            agent_id="bot-1",
+            session_id="ses-abc",
+            action_type="refund",
+            amount=150.0,
+        )
+        client.confirm_execution(result.evaluation_id, status="completed")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = 30,
+        endpoint_timeouts: Optional[dict[str, int]] = None,
+    ):
+        from .exceptions import KernevaConfigError
+
+        self.api_key = (
+            api_key
+            or os.environ.get("KERNEVA_API_KEY")
+            or os.environ.get("RUNTIME_TRUST_API_KEY", "")
+        )
+        if not self.api_key:
+            raise KernevaConfigError(
+                "api_key is required. Pass it explicitly or set KERNEVA_API_KEY"
+            )
+
+        self.base_url = (
+            base_url
+            or os.environ.get("KERNEVA_API_URL")
+            or os.environ.get("RUNTIME_TRUST_API_URL")
+            or _DEFAULT_API_URL
+        ).rstrip("/")
+
+        self.timeout = timeout
+        self.endpoint_timeouts = endpoint_timeouts or {}
+
+    # ------------------------------------------------------------------
+    # Internal request helpers
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[dict] = None,
+        query: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        endpoint_timeout: Optional[int] = None,
+    ) -> Any:
+        url = _build_url(self.base_url, path, query)
+        data = json.dumps(body).encode() if body is not None else None
+        timeout = endpoint_timeout or self.timeout
+
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        logger.debug(
+            "Sending %s %s (body=%s, query=%s, timeout=%ds)",
+            method, url,
+            json.dumps(body) if body else None,
+            query, timeout,
+        )
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(_MAX_RETRIES + 1):
+            if attempt > 0:
+                delay = _retry_delay(attempt - 1)
+                logger.debug(
+                    "Retry %d/%d after %.2fs for %s %s",
+                    attempt, _MAX_RETRIES, delay, method, url,
+                )
+                time.sleep(delay)
+
+            try:
+                req = urllib.request.Request(
+                    url, data=data, headers=headers, method=method,
+                )
+                with urllib.request.urlopen(req, timeout=timeout) as resp:
+                    response_data = json.loads(resp.read().decode())
+                    logger.debug(
+                        "Response %d for %s %s: %s",
+                        resp.status, method, url,
+                        json.dumps(response_data)[:500],
+                    )
+                    return response_data
+            except urllib.error.HTTPError as e:
+                body_text = e.read().decode(errors="replace")
+                logger.debug(
+                    "HTTP error %d for %s %s: %s",
+                    e.code, method, url, body_text,
+                )
+                if e.code == 401 or e.code == 403:
+                    raise KernevaAuthError(
+                        f"Authentication failed ({e.code}) for {method} {path}: {body_text}"
+                    ) from e
+                if e.code == 422:
+                    raise KernevaValidationError(
+                        f"Validation error for {method} {path}: {body_text}"
+                    ) from e
+                if e.code in _RETRYABLE_STATUSES and attempt < _MAX_RETRIES:
+                    last_exc = KernevaRetryableError(
+                        f"Retryable API error {e.code} for {method} {path}: {body_text}"
+                    )
+                    continue
+                if 500 <= e.code < 600 and e.code not in _RETRYABLE_STATUSES:
+                    raise KernevaFatalError(
+                        f"Non-retryable server error {e.code} for {method} {path}: {body_text}"
+                    ) from e
+                raise KernevaError(
+                    f"API error {e.code} for {method} {path}: {body_text}"
+                ) from e
+            except urllib.error.URLError as e:
+                logger.debug("URL error for %s %s: %s", method, url, e.reason)
+                raise KernevaRetryableError(
+                    f"Connection error for {method} {url}: {e.reason}"
+                ) from e
+            except TimeoutError as e:
+                raise KernevaTimeoutError(
+                    f"Request timed out after {timeout}s for {method} {url}"
+                ) from e
+            except OSError as e:
+                logger.debug("OS error for %s %s: %s", method, url, e)
+                raise KernevaError(
+                    f"Request failed for {method} {url}: {e}"
+                ) from e
+
+        if last_exc:
+            raise last_exc
+
+    # ------------------------------------------------------------------
+    # Core API methods
+    # ------------------------------------------------------------------
+
+    def evaluate(
+        self,
+        agent_id: str,
+        session_id: str,
+        action_type: str,
+        amount: float,
+        metadata: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        customer_id: Optional[str] = None,
+    ) -> EvaluationResult:
+        """Evaluate a single agent action.
+
+        Returns EvaluationResult. Raises KernevaBlocked if decision is BLOCK.
+        Pass an idempotency_key to safely retry without creating duplicate evaluations.
+
+        Pass customer_id to identify the *end-customer* this action concerns
+        (e.g. "cust_123"). It segments recent-activity lookups so one
+        end-customer's trajectory never bleeds into another's — omit it and all
+        end-customers collapse into a single trajectory, which produces spurious
+        escalation/clustering signals.
+
+        The caller should check result.decision and handle REVIEW/ALLOW
+        appropriately.
+        """
+        payload = {
+            "agent_id": agent_id,
+            "session_id": session_id,
+            "action_type": action_type,
+            "amount": amount,
+            "metadata": metadata or {},
+        }
+        if customer_id is not None:
+            payload["customer_id"] = customer_id
+        data = self._request(
+            "POST", "/evaluate", body=payload,
+            idempotency_key=idempotency_key,
+            endpoint_timeout=self.endpoint_timeouts.get("evaluate"),
+        )
+
+        if data.get("decision") == "BLOCK":
+            evaluation_id = data.get("evaluation_id", "")
+            raise KernevaBlocked(
+                f"Kerneva blocked {action_type} for ${amount:.2f}: "
+                f"{data.get('reason', 'No reason provided')}",
+                evaluation_id=evaluation_id,
+            )
+
+        return EvaluationResult(
+            decision=data.get("decision", "ALLOW"),
+            risk_score=float(data.get("risk_score", 0)),
+            trust_score=float(data.get("trust_score", 0)),
+            reason=data.get("reason", ""),
+            signals=data.get("signals", []),
+            failure_classes=data.get("failure_classes_detected", []),
+            evaluation_id=data.get("evaluation_id"),
+            observation_mode=bool(data.get("observation_mode", True)),
+            versions=data.get("versions", {}),
+            warnings=data.get("warnings") or [],
+            recommended_decision=data.get("recommended_decision"),
+        )
+
+    def confirm_execution(
+        self,
+        evaluation_id: str,
+        status: ExecutionStatus,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> dict:
+        """Report the outcome of an evaluated action.
+
+        Maps SDK-level execution statuses to the backend review system:
+          completed -> resolved/completed
+          failed    -> resolved/failed
+          blocked   -> resolved/blocked_by_external
+          abandoned -> dismissed/abandoned
+          timed_out -> dismissed/timed_out
+        """
+        mapping = _EXECUTION_TO_REVIEW.get(status)
+        if not mapping:
+            raise KernevaError(
+                f"Invalid execution status: {status}. "
+                f"Must be one of: completed, failed, blocked, abandoned, timed_out"
+            )
+
+        payload = {
+            "status": mapping["status"],
+            "resolution": mapping["resolution"],
+        }
+        if metadata:
+            payload["impact"] = json.dumps(metadata)
+
+        return self._request(
+            "PUT",
+            f"/evaluations/{evaluation_id}/review",
+            body=payload,
+        )
+
+    def fetch_evaluation(self, evaluation_id: str) -> EvaluationDetail:
+        """Fetch the full trace for a single evaluation.
+
+        Returns EvaluationDetail containing all entries, signals, and
+        metadata for the evaluation.
+        """
+        data = self._request("GET", f"/trace/{evaluation_id}")
+        if isinstance(data, list):
+            return EvaluationDetail.from_api(data)
+        return EvaluationDetail.from_api([data])
+
+    def fetch_history(
+        self,
+        agent: Optional[str] = None,
+        decision: Optional[str] = None,
+        review_status: Optional[str] = None,
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+        limit: int = 50,
+        cursor: Optional[str] = None,
+        offset: Optional[int] = None,
+    ) -> List[HistoryEntry]:
+        """Fetch investigation history with optional filters.
+
+        Supports cursor-based and offset-based pagination via the
+        *cursor* and *offset* parameters.
+
+        Returns a list of HistoryEntry objects representing recent
+        non-ALLOW evaluations.
+        """
+        query: Dict[str, Any] = {"limit": limit}
+        if agent:
+            query["agent"] = agent
+        if decision:
+            query["decision"] = decision
+        if review_status:
+            query["review_status"] = review_status
+        if start:
+            query["start"] = start
+        if end:
+            query["end"] = end
+        if cursor is not None:
+            query["cursor"] = cursor
+        if offset is not None:
+            query["offset"] = offset
+
+        data = self._request("GET", "/investigations", query=query)
+        entries: List[HistoryEntry] = []
+        for item in data if isinstance(data, list) else []:
+            entries.append(
+                HistoryEntry(
+                    id=item.get("id", ""),
+                    timestamp=item.get("timestamp", ""),
+                    agent=item.get("agent", ""),
+                    session_id=item.get("session_id", ""),
+                    decision=item.get("decision", ""),
+                    amount=float(item.get("amount", 0)),
+                    trust_score=_safe_float(item.get("trust_score")),
+                    risk_score=_safe_float(item.get("risk_score")),
+                    failure_class=item.get("failure_class"),
+                    review_status=item.get("review_status", "unreviewed"),
+                    resolution=item.get("resolution"),
+                    impact=item.get("impact"),
+                )
+            )
+        return entries
+
+    def list_agents(self) -> List[AgentSummary]:
+        """List all registered agents for this account."""
+        data = self._request("GET", "/agents")
+        agents: List[AgentSummary] = []
+        for item in data if isinstance(data, list) else []:
+            agents.append(
+                AgentSummary(
+                    agent_id=item.get("agent_id", ""),
+                    agent_name=item.get("agent_name", ""),
+                    total_decisions=int(item.get("total_decisions", 0)),
+                    review_count=int(item.get("review_count", 0)),
+                    block_count=int(item.get("block_count", 0)),
+                    avg_trust=_safe_float(item.get("avg_trust")),
+                )
+            )
+        return agents
+
+    def health(self) -> dict:
+        """Check API health.
+
+        Returns the raw health response dict, e.g. {"status": "ok"}.
+        Raises KernevaError if the API is unreachable.
+        """
+        return self._request("GET", "/health")
+
+    # ------------------------------------------------------------------
+    # Config endpoints
+    # ------------------------------------------------------------------
+
+    def get_config(self) -> dict:
+        """Fetch the current runtime configuration.
+
+        Returns the full configuration dict, e.g.:
+            {"thresholds": {"refund": 75.0}, "observation_mode": True}
+        """
+        return self._request("GET", "/config")
+
+    def update_config(self, config: dict) -> dict:
+        """Update the runtime configuration.
+
+        Args:
+            config: A dictionary of configuration values to set.
+                    This replaces the entire configuration on the server.
+
+        Returns the updated configuration dict from the server.
+        """
+        return self._request("PUT", "/config", body=config)
+
+    # ------------------------------------------------------------------
+    # Async convenience wrappers
+    # ------------------------------------------------------------------
+
+    async def evaluate_async(
+        self,
+        agent_id: str,
+        session_id: str,
+        action_type: str,
+        amount: float,
+        metadata: Optional[Dict[str, Any]] = None,
+        customer_id: Optional[str] = None,
+    ) -> EvaluationResult:
+        """Async version of evaluate()."""
+        return self.evaluate(
+            agent_id=agent_id,
+            session_id=session_id,
+            action_type=action_type,
+            amount=amount,
+            metadata=metadata,
+            customer_id=customer_id,
+        )
+
+    async def confirm_execution_async(
+        self,
+        evaluation_id: str,
+        status: ExecutionStatus,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> dict:
+        """Async version of confirm_execution()."""
+        return self.confirm_execution(
+            evaluation_id=evaluation_id,
+            status=status,
+            metadata=metadata,
+        )
+
+    async def fetch_evaluation_async(self, evaluation_id: str) -> EvaluationDetail:
+        """Async version of fetch_evaluation()."""
+        return self.fetch_evaluation(evaluation_id)
+
+    async def fetch_history_async(
+        self,
+        agent: Optional[str] = None,
+        decision: Optional[str] = None,
+        review_status: Optional[str] = None,
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+        limit: int = 50,
+        cursor: Optional[str] = None,
+        offset: Optional[int] = None,
+    ) -> List[HistoryEntry]:
+        """Async version of fetch_history()."""
+        return self.fetch_history(
+            agent=agent,
+            decision=decision,
+            review_status=review_status,
+            start=start,
+            end=end,
+            limit=limit,
+            cursor=cursor,
+            offset=offset,
+        )
+
+    async def list_agents_async(self) -> List[AgentSummary]:
+        """Async version of list_agents()."""
+        return self.list_agents()
+
+    async def health_async(self) -> dict:
+        """Async version of health()."""
+        return self.health()
+
+    async def get_config_async(self) -> dict:
+        """Async version of get_config()."""
+        return self.get_config()
+
+    async def update_config_async(self, config: dict) -> dict:
+        """Async version of update_config()."""
+        return self.update_config(config)
+
+
+def _safe_float(value: Any) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

kerneva_runtime_trust/context.py

@@ -0,0 +1,106 @@
+"""Ambient interaction context for the Kerneva SDK.
+
+The engine's whole value is *longitudinal* — it reasons over an agent's
+trajectory within a session and across a tenant's end-customers. Those three
+identifiers (agent, session, end-customer) are business/temporal facts that a
+single function call does not carry, so the SDK cannot reliably infer them by
+reflection. Instead of forcing them into every function signature, this module
+lets you declare them once for a logical interaction:
+
+    import kerneva_runtime_trust as kerneva
+
+    with kerneva.session(session_id=ticket_id, customer_id="cust_123",
+                         agent_id="refund-bot"):
+        process_refund(amount=40)   # shares one trajectory
+        process_refund(amount=75)
+
+Anything guarded by ``@with_runtime_trust`` (aka ``@guard``) inside the block
+picks these up automatically. ``ContextVar`` makes this correct under asyncio
+and threads. If no session is active, each guarded call falls back to its own
+fresh session id (so unrelated calls never collapse into one trajectory).
+"""
+
+import contextlib
+import contextvars
+import uuid
+from typing import Any, Dict, Iterator, Optional
+
+_agent_id: "contextvars.ContextVar[Optional[str]]" = contextvars.ContextVar(
+    "kerneva_agent_id", default=None
+)
+_session_id: "contextvars.ContextVar[Optional[str]]" = contextvars.ContextVar(
+    "kerneva_session_id", default=None
+)
+_customer_id: "contextvars.ContextVar[Optional[str]]" = contextvars.ContextVar(
+    "kerneva_customer_id", default=None
+)
+_metadata: "contextvars.ContextVar[Dict[str, Any]]" = contextvars.ContextVar(
+    "kerneva_metadata", default={}
+)
+
+
+def new_session_id() -> str:
+    """A fresh, opaque session identifier."""
+    return str(uuid.uuid4())
+
+
+def current_agent_id() -> Optional[str]:
+    return _agent_id.get()
+
+
+def current_session_id() -> Optional[str]:
+    return _session_id.get()
+
+
+def current_customer_id() -> Optional[str]:
+    return _customer_id.get()
+
+
+def current_metadata() -> Dict[str, Any]:
+    return dict(_metadata.get())
+
+
+@contextlib.contextmanager
+def session(
+    session_id: Optional[str] = None,
+    *,
+    agent_id: Optional[str] = None,
+    customer_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> Iterator[str]:
+    """Bind an interaction context for the duration of the ``with`` block.
+
+    Args:
+        session_id: Identifier for this logical interaction (a support
+            conversation, one agent task-run, one request). If omitted, a fresh
+            id is generated so the block is still a single, bounded session.
+        agent_id: The logical AI actor making the calls (e.g. ``"refund-bot"``).
+        customer_id: The end-customer this interaction concerns. This is what
+            keeps one end-customer's trajectory from bleeding into another's.
+        metadata: Extra context merged into every evaluation inside the block
+            (shallow-merged over any enclosing session's metadata).
+
+    Yields:
+        The resolved ``session_id``.
+
+    Nesting is supported; on exit each value is restored to what it was before
+    the block, so contexts compose cleanly.
+    """
+    if session_id is None:
+        session_id = new_session_id()
+
+    tokens = [(_session_id, _session_id.set(session_id))]
+    if agent_id is not None:
+        tokens.append((_agent_id, _agent_id.set(agent_id)))
+    if customer_id is not None:
+        tokens.append((_customer_id, _customer_id.set(customer_id)))
+    if metadata is not None:
+        merged = {**_metadata.get(), **metadata}
+        tokens.append((_metadata, _metadata.set(merged)))
+
+    try:
+        yield session_id
+    finally:
+        # Restore in reverse order so nested contexts unwind correctly.
+        for var, token in reversed(tokens):
+            var.reset(token)

kerneva_runtime_trust/exceptions.py

@@ -0,0 +1,38 @@
+class KernevaError(Exception):
+    """Base exception for all Kerneva SDK errors."""
+
+
+class KernevaRetryableError(KernevaError):
+    """Raised when a request failed but may succeed on retry (e.g., 429, 503)."""
+
+
+class KernevaFatalError(KernevaError):
+    """Raised when a request failed with a non-retryable server error (e.g., 500, 502, 504)."""
+
+
+class KernevaBlocked(KernevaError):
+    """Raised when Kerneva blocks an action (decision = BLOCK).
+
+    Attributes:
+        evaluation_id: The ID of the evaluation that was blocked, if available.
+    """
+
+    def __init__(self, message: str = "", evaluation_id: str = ""):
+        super().__init__(message)
+        self.evaluation_id = evaluation_id
+
+
+class KernevaAuthError(KernevaError):
+    """Raised when authentication fails (401, 403)."""
+
+
+class KernevaTimeoutError(KernevaRetryableError):
+    """Raised when a request times out."""
+
+
+class KernevaValidationError(KernevaError):
+    """Raised when the API returns a validation error (422)."""
+
+
+class KernevaConfigError(KernevaError):
+    """Raised when the SDK is misconfigured (e.g., missing API key)."""