rippletide-python 0.1.0__py3-none-any.whl

rippletide/__init__.py

@@ -0,0 +1,5 @@
+"""Monitor-first tracing and policy guards for code-owned Python agents."""
+
+from .client import Rippletide, RippletidePolicyBlockedError, RippletidePolicyDecisionError, load_rippletide_env
+
+__all__ = ["Rippletide", "RippletidePolicyBlockedError", "RippletidePolicyDecisionError", "load_rippletide_env"]

rippletide/client.py

@@ -0,0 +1,654 @@
+"""The small synchronous Python counterpart to rippletide-package/sdk.
+
+The client intentionally has no provider dependency.  It can surround a raw
+urllib/requests/httpx provider call and never owns the customer's traffic.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import secrets
+import time
+import uuid
+from hashlib import sha256
+from http.client import HTTPException
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import datetime, timezone
+from typing import Any, Callable, Iterator, Mapping, TypeVar
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, unquote, urlsplit
+from urllib.request import Request, urlopen
+
+T = TypeVar("T")
+_CURRENT: ContextVar[dict[str, str] | None] = ContextVar("rippletide_current_span", default=None)
+_TRACEPARENT = re.compile(r"^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$", re.I)
+_SENSITIVE_KEY = re.compile(r"^(?:api[_-]?key|access[_-]?token|auth[_-]?token|authorization|client[_-]?secret|cookie|password|private[_-]?key|refresh[_-]?token|secret|session[_-]?token|set-cookie|x-api-key)$", re.I)
+_INLINE_AUTH = re.compile(r"\b(Bearer|Basic)\s+[A-Za-z0-9+/_=.,:;~-]{8,}", re.I)
+_DEFAULT_BASE_URL = "https://agent-evalserver-production.up.railway.app"
+_STAGING_BASE_URL = "https://agent-evalserver-staging.up.railway.app"
+_SHA256 = re.compile(r"^[0-9a-f]{64}$", re.I)
+_MAX_RESULT_ITEMS = 500
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _hex(size: int) -> str:
+    return secrets.token_hex(size)
+
+
+def _trim_url(value: str) -> str:
+    return value.rstrip("/")
+
+
+def _base_url_for_key(key: str | None) -> str:
+    return _STAGING_BASE_URL if key and key.startswith("rt_staging_") else _DEFAULT_BASE_URL
+
+
+def _connection_env() -> dict[str, str]:
+    """Decode the CLI's single-env connection, falling back to legacy values."""
+    try:
+        url = urlsplit(os.getenv("RIPPLETIDE", "").strip())
+        api_key = unquote(url.username or "", errors="strict")
+        agent_id = unquote(url.path.lstrip("/").split("/")[0], errors="strict")
+        hostname = url.hostname
+        port = url.port  # Validate the port before using the authority.
+        if url.scheme == "rippletide" and api_key and agent_id and hostname:
+            host = f"[{hostname}]" if ":" in hostname else hostname
+            if port is not None:
+                host += f":{port}"
+            scheme = "http" if hostname in {"localhost", "127.0.0.1", "0.0.0.0"} else "https"
+            return {"agent_id": agent_id, "api_key": api_key, "base_url": f"{scheme}://{host}"}
+    except (ValueError, UnicodeError):
+        pass
+    return {
+        "agent_id": os.getenv("RIPPLETIDE_AGENT_ID") or os.getenv("RIPPLETIDE_APP", ""),
+        "api_key": os.getenv("RIPPLETIDE_API_KEY", ""),
+        "base_url": os.getenv("RIPPLETIDE_BASE_URL", ""),
+    }
+
+
+def load_rippletide_env(path: str) -> None:
+    """Load only RIPPLETIDE and RIPPLETIDE_* values from an explicit, git-ignored .env path.
+
+    This deliberately does not override a host-provided environment and never
+    raises. Call it from the connected repository's real entry module, not from
+    a package-local working directory.
+    """
+    try:
+        with open(path, encoding="utf-8") as source:
+            for raw in source:
+                key, separator, value = raw.strip().partition("=")
+                if separator and (key == "RIPPLETIDE" or key.startswith("RIPPLETIDE_")) and key not in os.environ:
+                    os.environ[key] = value.strip().strip('"').strip("'")
+    except OSError:
+        pass
+
+
+def _redact_text(value: str) -> str:
+    return _INLINE_AUTH.sub(r"\1 [REDACTED]", value)[:4000]
+
+
+def _safe(value: Any, *, redacted: bool = False, key: str = "", depth: int = 0) -> Any:
+    if depth > 6 or key and _SENSITIVE_KEY.match(key):
+        return "[REDACTED]"
+    if value is None or isinstance(value, (bool, int, float)):
+        return "[REDACTED]" if redacted and value is not None else value
+    if isinstance(value, str):
+        return "[REDACTED]" if redacted else _redact_text(value)
+    if isinstance(value, Mapping):
+        return {str(k)[:128]: _safe(v, redacted=redacted, key=str(k), depth=depth + 1) for k, v in list(value.items())[:50]}
+    if isinstance(value, (list, tuple)):
+        return [_safe(item, redacted=redacted, key=key, depth=depth + 1) for item in value[:50]]
+    return "[REDACTED]" if redacted else _redact_text(str(value))
+
+
+def _capture(value: Any, mode: str) -> Any | None:
+    if mode == "metadata":
+        return None
+    return _safe(value, redacted=mode == "redacted")
+
+
+def _clone_policy_value(value: Any, label: str) -> Any:
+    """Detach the exact JSON snapshot that policy evaluates and apply receives."""
+    try:
+        encoded = json.dumps(value, allow_nan=False, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+        return json.loads(encoded)
+    except (TypeError, ValueError) as error:
+        raise TypeError(f"{label} must be JSON-compatible.") from error
+
+
+def _policy_json(value: Any) -> str:
+    """Match the server's stableStringifyPolicyJson (ECMAScript JSON)."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        # The server parses all JSON numbers as IEEE-754 doubles. Python's
+        # shortest round-trip representation uses the same significant digits,
+        # but different fixed/exponent thresholds and preserves negative zero.
+        number = float(value)
+        if not math.isfinite(number):
+            raise ValueError("Policy JSON numbers must be finite.")
+        if number == 0:
+            return "0"
+        sign = "-" if number < 0 else ""
+        mantissa, _, exponent = repr(abs(number)).partition("e")
+        whole, _, fraction = mantissa.partition(".")
+        point = len(whole) + int(exponent or "0")
+        digits = whole + fraction
+        leading = len(digits) - len(digits.lstrip("0"))
+        digits = digits.lstrip("0").rstrip("0")
+        point -= leading
+        if 0 < point <= 21:
+            encoded = (digits + "0" * max(0, point - len(digits)))[:point]
+            if len(digits) > point:
+                encoded += "." + digits[point:]
+        elif -6 < point <= 0:
+            encoded = "0." + "0" * -point + digits
+        else:
+            encoded = digits[0] + ("." + digits[1:] if len(digits) > 1 else "")
+            encoded += f"e{point - 1:+d}" if point > 0 else f"e{point - 1}"
+        return sign + encoded
+    if isinstance(value, str):
+        # JSON.stringify escapes lone UTF-16 surrogates, not ordinary Unicode.
+        encoded = json.dumps(value, ensure_ascii=False)
+        return re.sub(r"[\ud800-\udfff]", lambda match: f"\\u{ord(match[0]):04x}", encoded)
+    if isinstance(value, list):
+        return "[" + ",".join(_policy_json(item) for item in value) + "]"
+    if isinstance(value, Mapping):
+        keys = sorted(value, key=lambda key: key.encode("utf-16-be", "surrogatepass"))
+        return "{" + ",".join(_policy_json(key) + ":" + _policy_json(value[key]) for key in keys) + "}"
+    raise TypeError("Policy values must be JSON-compatible.")
+
+
+def _policy_fingerprint(value: Any) -> str:
+    return sha256(_policy_json(value).encode()).hexdigest()
+
+
+def _withheld_prompt(prompt_type: str) -> Any:
+    if prompt_type == "chat":
+        return [{"role": "system", "content": "[Prompt content withheld]"}]
+    return "[Prompt content withheld]"
+
+
+def _result_contracts(value: Mapping[str, Mapping[str, Any]] | None, tool_names: set[str]) -> dict[str, dict[str, Any]]:
+    """Validate the small contract surface needed by result policy evaluation."""
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise TypeError("tool result contracts must be a mapping.")
+    contracts: dict[str, dict[str, Any]] = {}
+    for tool_name, contract in value.items():
+        if not isinstance(tool_name, str) or tool_name not in tool_names:
+            raise TypeError(f"Unknown tool result contract: {tool_name}.")
+        if not isinstance(contract, Mapping) or set(contract) - {"resultSchema", "resultCollection"}:
+            raise TypeError(f'result contract for "{tool_name}" contains an unknown field.')
+        schema = contract.get("resultSchema")
+        if not isinstance(schema, Mapping):
+            raise TypeError(f'resultSchema for "{tool_name}" must be a JSON object.')
+        normalized: dict[str, Any] = {"resultSchema": _clone_policy_value(schema, f'resultSchema for "{tool_name}"')}
+        collection = contract.get("resultCollection")
+        if collection is not None:
+            if not isinstance(collection, Mapping) or set(collection) - {"itemsPath", "itemIdPath"}:
+                raise TypeError(f'resultCollection for "{tool_name}" contains an unknown field.')
+            paths: dict[str, list[str]] = {}
+            for key, allow_empty in (("itemsPath", True), ("itemIdPath", False)):
+                path = collection.get(key)
+                if not isinstance(path, list) or len(path) > 16 or (not allow_empty and not path) or not all(
+                    isinstance(segment, str)
+                    and 0 < len(segment) <= 128
+                    and segment == segment.strip()
+                    and segment not in {"__proto__", "constructor", "prototype"}
+                    for segment in path
+                ):
+                    raise TypeError(f'{key} for "{tool_name}" must be a safe property path.')
+                paths[key] = list(path)
+            normalized["resultCollection"] = paths
+        contracts[tool_name] = normalized
+    return contracts
+
+
+class RippletideHttpError(RuntimeError):
+    def __init__(self, status: int, code: str | None = None) -> None:
+        super().__init__(f"HTTP {status}" + (f" ({code})" if code else ""))
+        self.status, self.code = status, code
+
+
+class RippletidePolicyBlockedError(RuntimeError):
+    code = "RIPPLETIDE_POLICY_BLOCKED"
+
+    def __init__(self, action: str, decision: Mapping[str, Any]) -> None:
+        detail = decision.get("decision") if isinstance(decision.get("decision"), Mapping) else {}
+        reason = detail.get("reason") if isinstance(detail, Mapping) else None
+        super().__init__(f'Action "{action}" was blocked by policy' + (f": {reason}" if isinstance(reason, str) else "") + ".")
+        self.action, self.decision_id = action, decision.get("decisionId")
+
+
+class RippletidePolicyDecisionError(RuntimeError):
+    code = "RIPPLETIDE_POLICY_DECISION_REJECTED"
+
+    def __init__(self, action: str, status: int, server_code: str | None = None) -> None:
+        super().__init__(f'Action "{action}" was rejected by policy with HTTP {status}' + (f" ({server_code})" if server_code else "") + ".")
+        self.action, self.status, self.server_code = action, status, server_code
+
+
+class _Span:
+    def __init__(self, client: "Rippletide", kind: str, name: str, *, root: bool = False, traceparent: str | None = None, **options: Any) -> None:
+        self.client, self.kind, self.name = client, kind, name
+        parent = _CURRENT.get()
+        inbound = _TRACEPARENT.match(traceparent or "") if root else None
+        self.trace_id = inbound.group(1).lower() if inbound else parent["trace_id"] if parent else _hex(16)
+        self.span_id = _hex(8)
+        self.parent_span_id = inbound.group(2).lower() if inbound else parent["span_id"] if parent else None
+        self.options, self.token, self.ended = options, None, False
+        self.output: Any = None
+        self.output_set = False
+        self.end_attributes: dict[str, Any] = {}
+
+    def __enter__(self) -> "_Span":
+        self.token = _CURRENT.set({"trace_id": self.trace_id, "span_id": self.span_id, "trace_flags": "01"})
+        self.client._record("span_start", self, input=self.options.get("input"))
+        return self
+
+    def set_output(self, output: Any, **attributes: Any) -> None:
+        self.output, self.output_set = output, True
+        self.end_attributes.update(attributes)
+
+    def __exit__(self, exc_type: Any, exc: BaseException | None, _traceback: Any) -> bool:
+        if exc:
+            self.client._record("span_end", self, status="error", error=exc)
+        else:
+            self.client._record("span_end", self, status="ok", output=self.output if self.output_set else None, attributes=self.end_attributes)
+        if self.token is not None:
+            _CURRENT.reset(self.token)
+        self.ended = True
+        return False
+
+
+class Rippletide:
+    """Synchronous, dependency-free client with the TypeScript SDK's core semantics."""
+
+    def __init__(self, *, agent_id: str | None = None, api_key: str | None = None, base_url: str | None = None, name: str | None = None, description: str | None = None, capture_mode: str | None = None, disabled: bool | None = None, timeout_ms: int | None = None, warn: Callable[[str], None] | None = None) -> None:
+        from_env = _connection_env()
+        self.agent_id = agent_id or from_env["agent_id"] or None
+        self.api_key = api_key or from_env["api_key"] or None
+        self.base_url = _trim_url(base_url or from_env["base_url"] or _base_url_for_key(self.api_key))
+        self.capture_mode = capture_mode or os.getenv("RIPPLETIDE_CAPTURE_MODE", "metadata")
+        self.capture_mode = self.capture_mode if self.capture_mode in {"metadata", "redacted", "full"} else "metadata"
+        self.disabled = bool(disabled) if disabled is not None else os.getenv("RIPPLETIDE_DISABLED") == "1" or not bool(self.api_key)
+        self.timeout = (timeout_ms or int(os.getenv("RIPPLETIDE_TIMEOUT_MS", "5000"))) / 1000
+        self.agent_meta = {key: value for key, value in {"name": name, "description": description}.items() if value}
+        self.events: list[dict[str, Any]] = []
+        self._registered = False
+        self._warn = warn or (lambda _message: None)
+
+    def _request(self, method: str, path: str, body: Any | None = None) -> Any:
+        if not self.api_key:
+            raise RippletideHttpError(401, "UNAUTHENTICATED")
+        request = Request(f"{self.base_url}{path}", data=json.dumps(body).encode() if body is not None else None, headers={"x-api-key": self.api_key, **({"content-type": "application/json"} if body is not None else {})}, method=method)
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                return json.loads(response.read() or b"{}")
+        except HTTPError as error:
+            try:
+                payload = json.loads(error.read() or b"{}")
+            except (ValueError, OSError, HTTPException):
+                payload = {}
+            finally:
+                error.close()
+            raise RippletideHttpError(error.code, payload.get("error") if isinstance(payload, Mapping) else None) from error
+        except (URLError, OSError, HTTPException, ValueError) as error:
+            raise RippletideHttpError(503, "UNAVAILABLE") from error
+
+    def _ensure_registered(self) -> bool:
+        if self.disabled or not self.agent_id or self._registered:
+            return self._registered
+        try:
+            self._request("POST", f"/api/apps/{quote(self.agent_id, safe='')}/agent", {"seed": True, **self.agent_meta})
+            self._registered = True
+            self.heartbeat(source="sdk")
+            return True
+        except RippletideHttpError:
+            self._warn("Rippletide registration unavailable; continuing normally")
+            return False
+
+    def _record(self, event_type: str, span: _Span, *, status: str | None = None, input: Any = None, output: Any = None, error: BaseException | None = None, attributes: Mapping[str, Any] | None = None) -> None:
+        if self.disabled or not self.agent_id:
+            return
+        base: dict[str, Any] = {"eventId": str(uuid.uuid4()), "traceId": span.trace_id, "spanId": span.span_id, "kind": span.kind, "name": span.name, "occurredAt": _now(), "captureMode": self.capture_mode, "fidelity": "runtime_trace", "instrumentation": {"name": "rippletide-python", "version": "0.1.0", "language": "python"}}
+        if span.parent_span_id:
+            base["parentSpanId"] = span.parent_span_id
+        for key in ("conversationId", "toolCallId", "invocationId", "decisionId"):
+            value = span.options.get(key)
+            if isinstance(value, str) and value:
+                base[key] = value
+        links = span.options.get("links")
+        if isinstance(links, list):
+            base["links"] = links[:32]
+        initial_attributes = _safe(span.options.get("attributes") or {})
+        final_attributes = _safe(attributes or {})
+        merged_attributes = {**initial_attributes, **final_attributes}
+        if merged_attributes:
+            base["attributes"] = merged_attributes
+        if event_type == "span_start":
+            captured = _capture(input, self.capture_mode)
+            if captured is not None:
+                base["input"] = captured
+            base["eventType"] = "span_start"
+        else:
+            base.update({"eventType": "span_end", "status": status or "ok"})
+            captured = _capture(output, self.capture_mode)
+            if captured is not None:
+                base["output"] = captured
+            if error:
+                base["error"] = {"name": type(error).__name__, "message": _redact_text(str(error)) if self.capture_mode == "full" else "[REDACTED]"}
+        if len(self.events) < 2000:
+            self.events.append(base)
+
+    @contextmanager
+    def run(self, *, name: str = "run", input: Any = None, conversation_id: str | None = None, traceparent: str | None = None, attributes: Mapping[str, Any] | None = None) -> Iterator[_Span]:
+        with _Span(self, "run", name, root=True, traceparent=traceparent, input=input, conversationId=conversation_id, attributes=attributes) as span:
+            yield span
+
+    @contextmanager
+    def agent(self, *, name: str = "agent", input: Any = None, attributes: Mapping[str, Any] | None = None) -> Iterator[_Span]:
+        with _Span(self, "agent", name, input=input, attributes=attributes) as span:
+            yield span
+
+    @contextmanager
+    def span(self, kind: str, *, name: str, input: Any = None, tool_call_id: str | None = None, invocation_id: str | None = None, decision_id: str | None = None, attributes: Mapping[str, Any] | None = None) -> Iterator[_Span]:
+        normalized = {"llm": "model", "other": "operation"}.get(kind, kind)
+        if normalized not in {"run", "agent", "model", "tool", "policy", "operation"}:
+            normalized = "operation"
+        with _Span(self, normalized, name, input=input, toolCallId=tool_call_id, invocationId=invocation_id, decisionId=decision_id, attributes=attributes) as current:
+            yield current
+
+    def traced(self, fn: Callable[..., T], *, name: str | None = None, kind: str = "tool") -> Callable[..., T]:
+        def wrapped(*args: Any, **kwargs: Any) -> T:
+            with self.span(kind, name=name or fn.__name__ or "anonymous", input={"args": args, "kwargs": kwargs}) as current:
+                result = fn(*args, **kwargs)
+                current.set_output(result)
+                return result
+        return wrapped
+
+    def trace_headers(self) -> dict[str, str]:
+        current = _CURRENT.get()
+        return {"traceparent": f"00-{current['trace_id']}-{current['span_id']}-{current['trace_flags']}"} if current else {}
+
+    def heartbeat(self, **attributes: Any) -> None:
+        with _Span(self, "operation", "heartbeat", root=True, attributes={"signal": "heartbeat", **attributes}):
+            pass
+
+    def register_prompts(self, prompts: Mapping[str, Any], *, allow_content_export: bool = False) -> None:
+        """Declare prompts without exporting their text unless explicitly approved."""
+        if self.disabled or not self.agent_id or not self._ensure_registered():
+            return
+        export_content = allow_content_export is True
+        for name, value in prompts.items():
+            options = value if isinstance(value, Mapping) and "fallback" in value else {"fallback": value}
+            fallback = options.get("fallback")
+            prompt_type = options.get("type") or ("chat" if isinstance(fallback, list) else "text")
+            try:
+                self._request("POST", f"/api/apps/{quote(self.agent_id, safe='')}/prompts/{quote(str(name), safe='')}", {"seed": True, "type": prompt_type, "prompt": _safe(fallback) if export_content else _withheld_prompt(prompt_type), "config": options.get("config", {}), "source": "sdk", "contentExported": export_content})
+            except RippletideHttpError:
+                self._warn(f'Rippletide prompt "{name}" unavailable; using local prompt')
+
+    def tools(self, set_name: str, tools: list[Mapping[str, Any]], *, results: Mapping[str, Mapping[str, Any]] | None = None) -> list[Mapping[str, Any]]:
+        """Declare tools and, optionally, result contracts for after-action guards."""
+        if self.disabled or not self.agent_id or not tools or not self._ensure_registered():
+            return tools
+        normalized = []
+        for tool in tools:
+            source = tool.get("function") if isinstance(tool.get("function"), Mapping) else tool
+            if not isinstance(source, Mapping) or not isinstance(source.get("name"), str):
+                continue
+            normalized.append({"name": source["name"], "description": source.get("description", ""), "parameters": source.get("parameters", source.get("input_schema", {})), "source": "sdk"})
+        try:
+            contracts = _result_contracts(results, {tool["name"] for tool in normalized})
+            payload = {"tools": [{**tool, **contracts.get(tool["name"], {})} for tool in normalized]}
+            self._request("POST", f"/api/apps/{quote(self.agent_id, safe='')}/toolsets/{quote(set_name, safe='')}/sync", payload)
+        except (RippletideHttpError, TypeError):
+            self._warn(f'Rippletide toolset "{set_name}" unavailable; using local tools')
+        return tools
+
+    def connection(self, provider: str, *, env: Mapping[str, str] | None = None, config: Mapping[str, str] | None = None) -> dict[str, Any]:
+        values = {key: os.getenv(env_name, "") for key, env_name in (env or {}).items()}
+        if not self.disabled and self.agent_id and self._ensure_registered():
+            try:
+                self._request("POST", f"/api/apps/{quote(self.agent_id, safe='')}/connections/{quote(provider, safe='')}", {"seed": True, "config": dict(config or {}), "secrets": {key: "configured" if value else "" for key, value in values.items()}})
+            except RippletideHttpError:
+                self._warn(f'Rippletide connection "{provider}" unavailable; using local configuration')
+        return {"provider": provider, "config": dict(config or {}), "secrets": values}
+
+    def _decide(self, path: str, body: Mapping[str, Any], action: str) -> Mapping[str, Any] | None:
+        try:
+            response = self._request("POST", f"/v1/policy{path}", body)
+            if not isinstance(response, Mapping) or not isinstance(response.get("decisionId"), str):
+                raise RippletideHttpError(503, "INVALID_RESPONSE")
+            return response
+        except RippletideHttpError as error:
+            if error.status in {401, 400, 403, 404}:
+                raise RippletidePolicyDecisionError(action, error.status, error.code) from error
+            self._warn("Rippletide policy decision unavailable; proceeding")
+            return None
+
+    def _receipt(self, decision: Mapping[str, Any] | None, outcome: str, elapsed_ms: int) -> None:
+        if not decision or not isinstance(decision.get("decisionId"), str):
+            return
+        self._receipt_body(decision["decisionId"], {"outcome": outcome, "occurredAt": _now(), "decisionRoundtripMs": elapsed_ms})
+
+    def _receipt_body(self, decision_id: str, body: Mapping[str, Any]) -> None:
+        try:
+            self._request("POST", f"/v1/policy/decisions/{quote(decision_id, safe='')}/receipt", dict(body))
+        except RippletideHttpError:
+            self._warn("Rippletide receipt unavailable; applied action is unchanged")
+
+    def _decide_result(self, body: Mapping[str, Any], action: str, result: Any, result_items: list[Mapping[str, Any]]) -> Mapping[str, Any] | None:
+        """Return only a plan that matches the immutable result snapshot.
+
+        Any unavailable, unsupported, or malformed plan fails open by returning
+        None. A deterministic client/configuration error remains visible before
+        the host applies a result it expected us to evaluate.
+        """
+        try:
+            response = self._request("POST", "/v1/policy/decide-result", body)
+        except RippletideHttpError as error:
+            unsupported = error.status == 404 and error.code in {None, "NOT_FOUND"}
+            transient = error.status >= 500 or error.status in {408, 425, 429} or (error.status == 409 and error.code == "POLICY_SNAPSHOT_CHANGED")
+            if not unsupported and not transient:
+                raise RippletidePolicyDecisionError(action, error.status, error.code) from error
+            self._warn(f'Result policy decision unavailable for "{action}"; forwarding every item')
+            return None
+
+        if not isinstance(response, Mapping):
+            self._warn(f'Result policy decision was malformed for "{action}"; forwarding every item')
+            return None
+        result_fingerprint = _policy_fingerprint(result)
+        items = response.get("items")
+        expected_disposition = "ALLOW"
+        if not isinstance(items, list) or len(items) != len(result_items) or len(items) > _MAX_RESULT_ITEMS:
+            self._warn(f'Result policy plan did not match "{action}"; forwarding every item')
+            return None
+        item_ids: set[str] = set()
+        delivered = excluded = would_exclude = 0
+        for index, item in enumerate(items):
+            if not isinstance(item, Mapping) or item.get("index") != index:
+                self._warn(f'Result policy plan did not match "{action}"; forwarding every item')
+                return None
+            item_id, disposition = item.get("itemId"), item.get("disposition")
+            if not isinstance(item_id, str) or not item_id.strip() or item_id != item_id.strip() or item_id in item_ids:
+                self._warn(f'Result policy plan did not match "{action}"; forwarding every item')
+                return None
+            if item.get("itemFingerprint") != _policy_fingerprint(result_items[index]) or disposition not in {"ALLOW", "WOULD_BLOCK", "BLOCK"}:
+                self._warn(f'Result policy plan did not match "{action}"; forwarding every item')
+                return None
+            item_ids.add(item_id)
+            if disposition == "BLOCK":
+                excluded += 1
+            else:
+                delivered += 1
+            if disposition == "WOULD_BLOCK":
+                would_exclude += 1
+        expected_disposition = "FILTER" if excluded else "WOULD_FILTER" if would_exclude else "ALLOW"
+        summary = response.get("summary")
+        try:
+            uuid.UUID(str(response.get("decisionId")))
+        except (TypeError, ValueError, AttributeError):
+            self._warn(f'Result policy plan did not match "{action}"; forwarding every item')
+            return None
+        expected_plan_fingerprint = _policy_fingerprint({
+            "formatVersion": 1,
+            "resultFingerprint": result_fingerprint,
+            "catalogFingerprint": response.get("catalogFingerprint"),
+            "evaluatedRuleReleases": response.get("evaluatedRuleReleases"),
+            "items": items,
+        })
+        if (
+            not isinstance(response.get("decisionId"), str)
+            or response.get("invocationId") != body["invocationId"]
+            or response.get("action") != action
+            or response.get("resultFingerprint") != result_fingerprint
+            or not isinstance(response.get("catalogFingerprint"), str)
+            or not _SHA256.match(response["catalogFingerprint"])
+            or not isinstance(response.get("resultPlanFingerprint"), str)
+            or not _SHA256.match(response["resultPlanFingerprint"])
+            or response["resultPlanFingerprint"] != expected_plan_fingerprint
+            or not isinstance(response.get("evaluatedRuleReleases"), list)
+            or response.get("disposition") != expected_disposition
+            or not isinstance(summary, Mapping)
+            or summary.get("total") != len(items)
+            or summary.get("delivered") != delivered
+            or summary.get("excluded") != excluded
+            or summary.get("wouldExclude") != would_exclude
+        ):
+            self._warn(f'Result policy plan did not match "{action}"; forwarding every item')
+            return None
+        return response
+
+    def guard_tool_call(self, *, toolset: str, tool: str, params: Mapping[str, Any], execute: Callable[[Mapping[str, Any]], T], context: Mapping[str, Any] | None = None, tool_call_id: str | None = None) -> T:
+        action, invocation_id = f"{quote(toolset, safe='')}/{quote(tool, safe='')}", str(uuid.uuid4())
+        if self.disabled:
+            return execute(params)
+        started = time.monotonic()
+        body = {"invocationId": invocation_id, "action": action, "params": dict(params), "context": dict(context or {})}
+        with self.span("policy", name=f"before_action:{action}", input=body, tool_call_id=tool_call_id, invocation_id=invocation_id, attributes={"trigger": "before_action", "action": action}) as policy_span:
+            decision = self._decide("/decide", body, action)
+            decision_id = decision.get("decisionId") if decision else None
+            policy_span.options["decisionId"] = decision_id
+            elapsed = int((time.monotonic() - started) * 1000)
+            policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
+        if decision and decision.get("disposition") == "BLOCK":
+            self._receipt(decision, "PREVENTED", elapsed)
+            with self.span("tool", name=tool, input=params, tool_call_id=tool_call_id, invocation_id=invocation_id, decision_id=decision_id, attributes={"action": action, "executed": False, "applicationOutcome": "PREVENTED"}):
+                raise RippletidePolicyBlockedError(action, decision)
+        with self.span("tool", name=tool, input=params, tool_call_id=tool_call_id, invocation_id=invocation_id, decision_id=decision_id, attributes={"action": action, "executed": True, "disposition": decision.get("disposition") if decision else "FALLBACK"}) as tool_span:
+            self._receipt(decision, "EXECUTED", elapsed)
+            result = execute(params)
+            tool_span.set_output(result)
+            return result
+
+    def guard_tool_result(self, *, toolset: str, tool: str, params: Mapping[str, Any], result: Any, result_items: list[Mapping[str, Any]], apply: Callable[[Mapping[str, Any]], T], context: Mapping[str, Any] | None = None, tool_call_id: str | None = None, allow_result_export: bool = False) -> T:
+        """Filter an already-completed tool result before its next local sink.
+
+        `allow_result_export` is deliberately false by default: result-policy
+        evaluation transmits the complete result to Rippletide. The callback is
+        always invoked with a detached snapshot; with no consent or an
+        unavailable service, it contains every item and `policyDecision=None`.
+        """
+        if not callable(apply):
+            raise TypeError("Rippletide guard_tool_result requires an apply function.")
+        if not isinstance(result_items, list) or len(result_items) > _MAX_RESULT_ITEMS or not all(isinstance(item, Mapping) for item in result_items):
+            raise TypeError("result_items must contain at most 500 JSON objects.")
+        action = f"{quote(toolset, safe='')}/{quote(tool, safe='')}"
+        evaluated_params = _clone_policy_value(dict(params), "params")
+        evaluated_result = _clone_policy_value(result, "result")
+        evaluated_items = [_clone_policy_value(item, f"result_items[{index}]") for index, item in enumerate(result_items)]
+        evaluated_context = _clone_policy_value(dict(context or {}), "trusted context")
+        decision: Mapping[str, Any] | None = None
+        elapsed = 0
+
+        if allow_result_export and not self.disabled:
+            invocation_id = str(uuid.uuid4())
+            body = {"invocationId": invocation_id, "action": action, "params": evaluated_params, "result": evaluated_result, "context": evaluated_context}
+            started = time.monotonic()
+            with self.span("policy", name=f"after_action:{action}", input=body, tool_call_id=tool_call_id, invocation_id=invocation_id, attributes={"trigger": "after_action", "action": action, "rawResultExport": True}) as policy_span:
+                decision = self._decide_result(body, action, evaluated_result, evaluated_items)
+                elapsed = int((time.monotonic() - started) * 1000)
+                policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
+
+        delivered_items = list(evaluated_items)
+        excluded_items: list[dict[str, Any]] = []
+        if decision:
+            delivered_items = []
+            for item, item_decision in zip(evaluated_items, decision["items"]):
+                if item_decision["disposition"] != "BLOCK":
+                    delivered_items.append(item)
+                    continue
+                detail = item_decision.get("decision") if isinstance(item_decision.get("decision"), Mapping) else {}
+                excluded_items.append({
+                    "index": item_decision["index"],
+                    "itemId": item_decision["itemId"],
+                    "item": item,
+                    "reason": detail.get("reason") if isinstance(detail.get("reason"), str) else "Blocked by policy",
+                    "blockingRuleIds": list(detail.get("blockingRuleIds", [])) if isinstance(detail.get("blockingRuleIds"), list) else [],
+                })
+        outcome = "RESULT_FILTERED" if excluded_items else "RESULT_DELIVERED"
+        filtered = {"result": evaluated_result, "deliveredItems": delivered_items, "excludedItems": excluded_items, "policyDecision": _clone_policy_value(decision, "policy decision") if decision else None}
+        with self.span("operation", name="result_application", input=filtered, tool_call_id=tool_call_id, invocation_id=decision.get("invocationId") if decision else None, decision_id=decision.get("decisionId") if decision else None, attributes={"action": action, "applicationOutcome": outcome, "deliveredItemCount": len(delivered_items), "excludedItemCount": len(excluded_items), "executed": True}) as result_span:
+            try:
+                applied = apply(filtered)
+                result_span.set_output(applied)
+                return applied
+            finally:
+                if decision:
+                    self._receipt_body(decision["decisionId"], {
+                        "outcome": outcome,
+                        "occurredAt": _now(),
+                        "resultPlanFingerprint": decision["resultPlanFingerprint"],
+                        "deliveredItemIndexes": [index for index, item in enumerate(decision["items"]) if item["disposition"] != "BLOCK"],
+                        "excludedItemIndexes": [index for index, item in enumerate(decision["items"]) if item["disposition"] == "BLOCK"],
+                        "decisionRoundtripMs": elapsed,
+                    })
+
+    def deliver_response(self, *, request: Any, response: Any, deliver: Callable[[Any], T], context: Mapping[str, Any] | None = None) -> T:
+        invocation_id, action = str(uuid.uuid4()), "rippletide/response"
+        if self.disabled:
+            return deliver(response)
+        started = time.monotonic()
+        body = {"invocationId": invocation_id, "request": request, "response": response, "context": dict(context or {})}
+        with self.span("policy", name="before_response:rippletide/response", input=body, invocation_id=invocation_id, attributes={"trigger": "before_response", "action": action}) as policy_span:
+            decision = self._decide("/decide-response", body, action)
+            decision_id = decision.get("decisionId") if decision else None
+            policy_span.options["decisionId"] = decision_id
+            elapsed = int((time.monotonic() - started) * 1000)
+            policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
+        if decision and decision.get("disposition") == "BLOCK":
+            self._receipt(decision, "SUPPRESSED", elapsed)
+            with self.span("operation", name="response_delivery", input=response, invocation_id=invocation_id, decision_id=decision_id, attributes={"action": action, "executed": False, "applicationOutcome": "SUPPRESSED"}):
+                raise RippletidePolicyBlockedError(action, decision)
+        with self.span("operation", name="response_delivery", input=response, invocation_id=invocation_id, decision_id=decision_id, attributes={"action": action, "executed": True, "applicationOutcome": "DELIVERED", "disposition": decision.get("disposition") if decision else "FALLBACK"}) as delivery_span:
+            self._receipt(decision, "DELIVERED", elapsed)
+            result = deliver(response)
+            delivery_span.set_output(result)
+            return result
+
+    def flush(self) -> bool:
+        if self.disabled or not self.agent_id or not self.events:
+            return False
+        self._ensure_registered()
+        all_sent = True
+        while self.events:
+            batch, self.events = self.events[:50], self.events[50:]
+            try:
+                self._request("POST", f"/v1/runtime/traces/{quote(self.agent_id, safe='')}", {"schemaVersion": "runtime_trace.v1", "events": batch})
+            except RippletideHttpError:
+                all_sent = False
+                self._warn("Rippletide runtime export unavailable; dropped trace batch")
+        return all_sent

rippletide_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: rippletide-python
+Version: 0.1.0
+Summary: Monitor-first Python SDK for Rippletide-connected agents
+License: UNLICENSED
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Rippletide Python
+
+`rippletide-python` connects a code-owned Python agent to Rippletide without
+taking ownership of its model traffic. It has no provider dependencies: wrap a
+hand-written provider or internal HTTP call at the existing model seam.
+
+```python
+from rippletide import Rippletide, load_rippletide_env
+
+# Keep these values aligned with the agent's existing provider call.
+PROVIDER_NAME = "existing-provider"
+PROVIDER_API_KEY_ENV = "EXISTING_PROVIDER_API_KEY"
+MODEL_OPERATION = "existing-provider.request"
+
+load_rippletide_env("/path/to/connected-repo/.env")
+rippletide = Rippletide(name="Support agent")
+
+try:
+    rippletide.register_prompts({"system": {"fallback": SYSTEM_PROMPT}})  # prompt text is withheld by default
+    rippletide.tools("core", TOOLS)
+    rippletide.connection(PROVIDER_NAME, env={"api_key": PROVIDER_API_KEY_ENV})
+    with rippletide.run(name="inbound_request", input=request, conversation_id=conversation_id):
+        with rippletide.agent(name="orchestrator"):
+            call_model = rippletide.traced(raw_model_call, name=MODEL_OPERATION, kind="model")
+            candidate = call_model(messages)
+            return rippletide.deliver_response(
+                request=request, response=candidate, context=trusted_context,
+                deliver=send_to_caller,
+            )
+finally:
+    rippletide.flush()
+```
+
+The CLI writes an agent-scoped `RIPPLETIDE=rippletide://…` connection string
+into the connected repository's `.env`. `load_rippletide_env()` loads it without
+overriding the process environment. The SDK also accepts the legacy
+`RIPPLETIDE_API_KEY`, `RIPPLETIDE_AGENT_ID` (or `RIPPLETIDE_APP`), and optional
+`RIPPLETIDE_BASE_URL` generated by the Connection page. A valid `RIPPLETIDE`
+connection takes precedence over those legacy values; explicit constructor
+arguments take precedence over either format. Never use a Platform key in the
+agent or commit the `.env`.
+
+The client starts disabled when no Connection key is present. Network, 5xx, and
+rate-limit failures fail open; a valid enforce-mode policy `BLOCK` is the only
+case that prevents a protected callback. Runtime capture defaults to metadata;
+use `RIPPLETIDE_CAPTURE_MODE=redacted` or explicitly opt into `full` when the
+privacy posture allows it. Always call `flush()` before a short-lived worker,
+CLI, or serverless invocation exits.
+
+Malformed or interrupted HTTP responses also fail open.
+
+Tool and response policy spans include the invocation ID; once a decision arrives, their end
+events and the protected action spans include its decision ID, including in
+metadata capture mode. These IDs correlate the action with its policy receipt.
+
+Prompt inventory is recorded with its content withheld by default. Pass
+`allow_content_export=True` to `register_prompts(...)` only when the prompt
+owner has explicitly approved storing the prompt text in Rippletide.
+
+## Filter a completed tool result (explicit opt-in)
+
+For an eligible collection returned by a tool, declare its result contract and
+pass `allow_result_export=True`. This evaluates the complete result transiently
+at Rippletide; do this only with the owner's explicit approval. It is false by
+default, and unavailable policy service forwards every item unchanged.
+
+```python
+rippletide.tools("catalog", TOOLS, results={
+    "list_products": {
+        "resultSchema": {"type": "object", "properties": {"products": {"type": "array"}}},
+        "resultCollection": {"itemsPath": ["products"], "itemIdPath": ["id"]},
+    },
+})
+
+result = list_products(params)
+return rippletide.guard_tool_result(
+    toolset="catalog", tool="list_products", params=params,
+    result=result, result_items=result["products"], context=trusted_context,
+    allow_result_export=True,
+    apply=lambda guarded: {**guarded["result"], "products": guarded["deliveredItems"]},
+)
+```
+
+`ALLOW` and observe-only `WOULD_BLOCK` items are delivered; only enforce-mode
+`BLOCK` items are excluded. The callback receives the original result snapshot,
+the delivered and excluded items, and the decision. It is responsible for the
+native response shape, and the SDK records the applied outcome as a receipt.
+Result fingerprints use the server's ECMAScript JSON encoding, including its
+number formatting and UTF-16 object-key ordering.
+
+This first release supports synchronous Python call sites. Python MCP servers,
+async generators, and response streaming remain unsupported rather than being
+silently represented as complete response-delivery protection.

rippletide_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+rippletide/__init__.py,sha256=lPw2FwwCVSYhMQdQlgZufRLZLZrECKYPvtrMELUxYdI,304
+rippletide/client.py,sha256=kb1x4AlOx-20ABVpuyEiXAFyq6OmKVnoFlEcA94WKOM,38176
+rippletide_python-0.1.0.dist-info/METADATA,sha256=JjBGhn3keRNNGmOUDtT4BtaK0I6Xwtmy3KCREVSZgK8,4704
+rippletide_python-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rippletide_python-0.1.0.dist-info/top_level.txt,sha256=NAEYCFwQDE0G96JlVKq00OiKb0YLZ_Er8rcAhOiYHzo,11
+rippletide_python-0.1.0.dist-info/RECORD,,

rippletide_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rippletide_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rippletide