rippletide-python 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

rippletide/client.py

@@ -1,33 +1,35 @@
-"""The small synchronous Python counterpart to rippletide-package/sdk.
+"""The small 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.
+urllib/requests/httpx provider call, synchronous or asynchronous, streamed or
+not, and never owns the customer's traffic.
 """
 
 from __future__ import annotations
 
+import asyncio
+import inspect
 import json
 import math
 import os
 import re
-import secrets
+import sys
 import time
 import uuid
 from hashlib import sha256
 from http.client import HTTPException
-from contextlib import contextmanager
-from contextvars import ContextVar
+from contextlib import contextmanager, nullcontext
 from datetime import datetime, timezone
-from typing import Any, Callable, Iterator, Mapping, TypeVar
+from typing import Any, Awaitable, Callable, Iterator, Mapping, TypeVar
 from urllib.error import HTTPError, URLError
 from urllib.parse import quote, unquote, urlsplit
 from urllib.request import Request, urlopen
+from opentelemetry import trace
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from .telemetry import Telemetry, capture_value, sanitized_text
 
 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)
+_UNSET = object()
 _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)
@@ -38,10 +40,6 @@ 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("/")
 
@@ -90,30 +88,6 @@ def load_rippletide_env(path: str) -> None:
         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:
@@ -242,59 +216,210 @@ class RippletidePolicyDecisionError(RuntimeError):
 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.root, self.traceparent = root, traceparent
+        self.options = {key: value for key, value in options.items() if value is not _UNSET}
+        self.ended = False
+        self.native = trace.NonRecordingSpan(trace.INVALID_SPAN_CONTEXT)
         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"))
+        try:
+            if not self.client.disabled and self.client.agent_id and self.client.runtime_traces:
+                if self.client._telemetry is None:
+                    self.client._telemetry = Telemetry(self.client)
+                self.native = self.client._telemetry.start(self.kind, self.name, self.options, self.root, self.traceparent)
+        except Exception:
+            self.client._warn("Rippletide span capture unavailable; continuing normally")
+        self.trace_id = format(self.native.get_span_context().trace_id, "032x")
+        self.span_id = format(self.native.get_span_context().span_id, "016x")
+        self.scope = self._activation()
+        self.scope.__enter__()
         return self
 
+    def _activation(self) -> Any:
+        return trace.use_span(self.native, end_on_exit=False, record_exception=False, set_status_on_exception=False) if self.native.is_recording() else nullcontext()
+
+    def detach(self) -> None:
+        """Leave the current context while the span stays open for a deferred result."""
+        self.scope.__exit__(None, None, None)
+        self.scope = nullcontext()
+
     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
+        try:
+            if self.native.is_recording():
+                options = {**self.options, **({"output": self.output} if self.output_set else {})}
+                self.native.set_attributes(self.client._telemetry.attributes(self.kind, options, self.end_attributes))
+                outcome = "blocked" if isinstance(exc, RippletidePolicyBlockedError) else "error" if exc else "ok"
+                self.native.set_attribute("rippletide.outcome", outcome)
+                self.native.set_status(trace.StatusCode.ERROR if outcome == "error" else trace.StatusCode.UNSET)
+                if exc:
+                    details = {"exception.type": type(exc).__name__}
+                    if self.client.capture_content:
+                        details["exception.message"] = sanitized_text(str(exc))[:4000]
+                    self.native.add_event("exception", details)
+        except Exception:
+            self.native.set_attribute("rippletide.capture.completeness", "capture_error")
+        finally:
+            self.native.end()
+            self.scope.__exit__(exc_type, exc, _traceback)
+            self.ended = True
         return False
 
 
+def _span_kind(kind: str) -> str:
+    normalized = {"llm": "model", "other": "operation"}.get(kind, kind)
+    return normalized if normalized in {"run", "agent", "model", "tool", "policy", "operation"} else "operation"
+
+
+def _complete(span: _Span, result: Any, after: Callable[[], None] | None = None) -> Any:
+    """Close the span with a plain result now, or once an awaited result settles."""
+    if inspect.isawaitable(result):
+        span.detach()
+        return _settle(span, result, after)
+    if after:
+        after()
+    span.set_output(result)
+    span.__exit__(None, None, None)
+    return result
+
+
+async def _settle(span: _Span, awaitable: Awaitable[Any], after: Callable[[], None] | None = None) -> Any:
+    with span._activation():
+        try:
+            result = await awaitable
+        except BaseException:
+            if after:
+                await asyncio.to_thread(after)
+            span.__exit__(*sys.exc_info())
+            raise
+        if after:
+            await asyncio.to_thread(after)
+        span.set_output(result)
+        span.__exit__(None, None, None)
+        return result
+
+
+class _TracedStream:
+    """Passes a stream through untouched and ends its span once the stream is exhausted, closed, or abandoned.
+
+    `finish(chunks, complete)` runs first when given and returns extra end attributes.
+    """
+
+    def __init__(self, span: _Span, stream: Any, finish: Callable[[list[Any], bool], dict[str, Any]] | None = None) -> None:
+        self._span, self._stream, self._finish, self._chunks, self._ended = span, stream, finish, [], False
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return getattr(self._stream, name)
+
+    def __iter__(self) -> "_TracedStream":
+        return self
+
+    def __aiter__(self) -> "_TracedStream":
+        return self
+
+    def __next__(self) -> Any:
+        try:
+            return self._collect(next(self._stream))
+        except BaseException as error:
+            self._end(isinstance(error, StopIteration), error)
+            raise
+
+    async def __anext__(self) -> Any:
+        try:
+            return self._collect(await self._stream.__anext__())
+        except BaseException as error:
+            self._end(isinstance(error, StopAsyncIteration), error)
+            raise
+
+    def __enter__(self) -> "_TracedStream":
+        if hasattr(self._stream, "__enter__"):
+            self._stream.__enter__()
+        return self
+
+    def __exit__(self, *exc: Any) -> Any:
+        self._end(False)
+        return self._stream.__exit__(*exc) if hasattr(self._stream, "__exit__") else False
+
+    async def __aenter__(self) -> "_TracedStream":
+        if hasattr(self._stream, "__aenter__"):
+            await self._stream.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> Any:
+        self._end(False)
+        return await self._stream.__aexit__(*exc) if hasattr(self._stream, "__aexit__") else False
+
+    def close(self) -> None:
+        self._end(False)
+        if hasattr(self._stream, "close"):
+            self._stream.close()
+
+    async def aclose(self) -> None:
+        self._end(False)
+        if hasattr(self._stream, "aclose"):
+            await self._stream.aclose()
+
+    def __del__(self) -> None:
+        try:
+            self._end(False)
+        except Exception:
+            pass
+
+    def _collect(self, chunk: Any) -> Any:
+        if self._finish or len(self._chunks) < 51:
+            self._chunks.append(chunk)
+        return chunk
+
+    def _end(self, complete: bool, error: BaseException | None = None) -> None:
+        if self._ended:
+            return
+        self._ended = True
+        error = None if complete else error
+        attributes = {"streaming": True, **({} if complete else {"captureCompleteness": "stream_not_consumed"})}
+        if self._finish:
+            attributes.update(self._finish(self._chunks, complete))
+        self._span.set_output(self._chunks, **attributes)
+        self._span.__exit__(type(error) if error else None, error, getattr(error, "__traceback__", None))
+
+
 class Rippletide:
-    """Synchronous, dependency-free client with the TypeScript SDK's core semantics."""
+    """Policy client with native OpenTelemetry instrumentation for synchronous and asyncio agents."""
 
-    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:
+    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_content: bool = False, runtime_traces: bool = True, 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.capture_content = capture_content is True
+        self.runtime_traces = runtime_traces is not False
         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._telemetry: Telemetry | None = None
         self._registered = False
-        self._warn = warn or (lambda _message: None)
+        self._warning_handler = warn
 
-    def _request(self, method: str, path: str, body: Any | None = None) -> Any:
+    def _warn(self, message: str) -> None:
+        try:
+            if self._warning_handler:
+                self._warning_handler(message)
+        except Exception:
+            pass
+
+    def _request(self, method: str, path: str, body: Any | None = None, *, timeout: float | 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:
+            with urlopen(request, timeout=self.timeout if timeout is None else timeout) as response:
                 return json.loads(response.read() or b"{}")
         except HTTPError as error:
             try:
@@ -319,68 +444,73 @@ class Rippletide:
             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:
+    def run(self, *, name: str = "run", input: Any = _UNSET, conversation_id: str | None = None, traceparent: str | None = None, tracestate: str | None = None, attributes: Mapping[str, Any] | None = None) -> Iterator[_Span]:
+        with _Span(self, "run", name, traceparent=traceparent, tracestate=tracestate, 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]:
+    def agent(self, *, name: str = "agent", input: Any = _UNSET, 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:
+    def span(self, kind: str, *, name: str, input: Any = _UNSET, tool_call_id: str | None = None, invocation_id: str | None = None, decision_id: str | None = None, attributes: Mapping[str, Any] | None = None, links: list[trace.Link] | None = None) -> Iterator[_Span]:
+        with _Span(self, _span_kind(kind), name, input=input, toolCallId=tool_call_id, invocationId=invocation_id, decisionId=decision_id, attributes=attributes, links=links) as current:
             yield current
 
     def traced(self, fn: Callable[..., T], *, name: str | None = None, kind: str = "tool") -> Callable[..., T]:
+        """Record each call as a span; an awaited result or a returned (async) iterator keeps it open until settled or exhausted."""
+        label = name or getattr(fn, "__name__", None) or "anonymous"
+
         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:
+            span = _Span(self, _span_kind(kind), label, input={"args": args, "kwargs": kwargs}).__enter__()
+            try:
                 result = fn(*args, **kwargs)
-                current.set_output(result)
-                return result
+            except BaseException:
+                span.__exit__(*sys.exc_info())
+                raise
+            if hasattr(result, "__next__") or hasattr(result, "__anext__"):
+                span.detach()
+                return _TracedStream(span, result)  # type: ignore[return-value]
+            return _complete(span, result)
         return wrapped
 
+    def _guarded(self, decide: Callable[[], tuple[str, dict[str, Any], Any, Callable[[], None] | None, Callable[[], None] | None]], callback: Callable[[Any], Any]) -> Any:
+        """Run the blocking policy round trip in decide(), then the callback inside the action span.
+
+        A coroutine-function callback yields a coroutine that moves the HTTP work to a
+        worker thread, so an asyncio agent is never blocked by decisions or receipts.
+        """
+        if not inspect.iscoroutinefunction(callback):
+            kind, options, argument, before, after = decide()
+            span = _Span(self, kind, **options).__enter__()
+            if before:
+                before()
+            try:
+                result = callback(argument)
+            except BaseException:
+                if after:
+                    after()
+                span.__exit__(*sys.exc_info())
+                raise
+            return _complete(span, result, after)
+
+        async def guarded() -> Any:
+            kind, options, argument, before, after = await asyncio.to_thread(decide)
+            span = _Span(self, kind, **options).__enter__()
+            span.detach()
+            if before:
+                await asyncio.to_thread(before)
+            return await _settle(span, callback(argument), after)
+
+        return guarded()
+
     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 {}
+        headers: dict[str, str] = {}
+        TraceContextTextMapPropagator().inject(headers)
+        return headers
 
     def heartbeat(self, **attributes: Any) -> None:
         with _Span(self, "operation", "heartbeat", root=True, attributes={"signal": "heartbeat", **attributes}):
@@ -396,7 +526,7 @@ class Rippletide:
             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})
+                self._request("POST", f"/api/apps/{quote(self.agent_id, safe='')}/prompts/{quote(str(name), safe='')}", {"seed": True, "type": prompt_type, "prompt": capture_value(fallback)[0] 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')
 
@@ -536,23 +666,25 @@ class Rippletide:
         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 decide() -> tuple[str, dict[str, Any], Any, Callable[[], None] | None, Callable[[], None] | None]:
+            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")
+            options: dict[str, Any] = {"name": tool, "input": params, "links": [trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], "toolCallId": tool_call_id, "invocationId": invocation_id, "decisionId": decision_id}
+            if decision and decision.get("disposition") == "BLOCK":
+                self._receipt(decision, "PREVENTED", elapsed)
+                with _Span(self, "tool", **options, attributes={"action": action, "executed": False, "applicationOutcome": "PREVENTED"}):
+                    raise RippletidePolicyBlockedError(action, decision)
+            options["attributes"] = {"action": action, "executed": True, "disposition": decision.get("disposition") if decision else "FALLBACK"}
+            return "tool", options, params, lambda: self._receipt(decision, "EXECUTED", elapsed), None
+
+        return self._guarded(decide, execute)
 
     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.
@@ -571,84 +703,119 @@ class Rippletide:
         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 decide() -> tuple[str, dict[str, Any], Any, Callable[[], None] | None, Callable[[], None] | None]:
+            decision: Mapping[str, Any] | None = None
+            elapsed = 0
+            policy_span = None
+
+            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)
+                    policy_span.options["decisionId"] = decision.get("decisionId") if decision else None
+                    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}
+            options = {"name": "result_application", "input": filtered, "links": [trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})] if policy_span else [], "toolCallId": tool_call_id, "invocationId": decision.get("invocationId") if decision else None, "decisionId": decision.get("decisionId") if decision else None, "attributes": {"action": action, "applicationOutcome": outcome, "deliveredItemCount": len(delivered_items), "excludedItemCount": len(excluded_items), "executed": True}}
+            after = (lambda: 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,
+            })) if decision else None
+            return "operation", options, filtered, None, after
+
+        return self._guarded(decide, apply)
 
     def deliver_response(self, *, request: Any, response: Any, deliver: Callable[[Any], T], context: Mapping[str, Any] | None = None) -> T:
+        """Decide on the complete candidate, then deliver it.
+
+        A sync or async iterator as `response` is streamed delivery: chunks pass
+        through to `deliver` untouched, and the decision runs on the assembled
+        text once the stream ends. It is recorded, never enforced: the outcome is
+        always DELIVERED and a BLOCK is marked as decided after delivery.
+        """
         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
+        if hasattr(response, "__next__") or hasattr(response, "__anext__"):
+            span = _Span(self, "operation", "response_delivery", invocationId=invocation_id, attributes={"action": action, "executed": True, "applicationOutcome": "DELIVERED", "decidedAfterDelivery": True}).__enter__()
+            span.detach()
+
+            def finish(chunks: list[Any], _complete: bool) -> dict[str, Any]:
+                text = "".join(chunk for chunk in chunks if isinstance(chunk, str))
+                started = time.monotonic()
+                body = {"invocationId": invocation_id, "request": request, "response": text if text or not chunks else [capture_value(chunk)[0] for chunk in chunks], "context": dict(context or {})}
+                links = [trace.Link(span.native.get_span_context(), {"rippletide.link.type": "follows_from"})]
+                with self.span("policy", name="before_response:rippletide/response", input=body, invocation_id=invocation_id, links=links, attributes={"trigger": "before_response", "action": action, "decidedAfterDelivery": True}) as policy_span:
+                    try:
+                        decision = self._decide("/decide-response", body, action)
+                    except RippletidePolicyDecisionError as error:
+                        self._warn(f"{error}; streamed response already delivered")
+                        decision = None
+                    policy_span.options["decisionId"] = span.options["decisionId"] = decision.get("decisionId") if decision else None
+                    elapsed = int((time.monotonic() - started) * 1000)
+                    policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
+                self._receipt(decision, "DELIVERED", elapsed)
+                return {"disposition": decision.get("disposition") if decision else "FALLBACK"}
+
+            return deliver(_TracedStream(span, response, finish))  # type: ignore[arg-type]
+
+        def decide() -> tuple[str, dict[str, Any], Any, Callable[[], None] | None, Callable[[], None] | None]:
+            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")
+            options: dict[str, Any] = {"name": "response_delivery", "input": response, "links": [trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], "invocationId": invocation_id, "decisionId": decision_id}
+            if decision and decision.get("disposition") == "BLOCK":
+                self._receipt(decision, "SUPPRESSED", elapsed)
+                with _Span(self, "operation", **options, attributes={"action": action, "executed": False, "applicationOutcome": "SUPPRESSED"}):
+                    raise RippletidePolicyBlockedError(action, decision)
+            options["attributes"] = {"action": action, "executed": True, "applicationOutcome": "DELIVERED", "disposition": decision.get("disposition") if decision else "FALLBACK"}
+            return "operation", options, response, lambda: self._receipt(decision, "DELIVERED", elapsed), None
+
+        return self._guarded(decide, deliver)
 
     def flush(self) -> bool:
-        if self.disabled or not self.agent_id or not self.events:
+        if self.disabled or not self.agent_id or not self.runtime_traces or self._telemetry is None:
             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
+        return self._telemetry.flush()
+
+    async def aflush(self) -> bool:
+        return await asyncio.to_thread(self.flush)
+
+    def shutdown(self) -> None:
+        self.flush()
+        if self._telemetry:
+            self._telemetry.shutdown()
+
+    async def ashutdown(self) -> None:
+        await asyncio.to_thread(self.shutdown)

rippletide/telemetry.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import base64
+import json
+import math
+import re
+import time
+import uuid
+from collections import deque
+from collections.abc import Mapping
+from importlib.metadata import PackageNotFoundError, version
+from threading import Lock
+from typing import Any
+
+from google.protobuf.json_format import MessageToDict
+from opentelemetry import context, trace
+from opentelemetry._logs import LogRecord
+from opentelemetry.exporter.otlp.proto.common._log_encoder import encode_logs
+from opentelemetry.exporter.otlp.proto.common.trace_encoder import encode_spans
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import LogRecordExporter, LogRecordExportResult, SimpleLogRecordProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import SpanLimits, TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor, SpanExporter, SpanExportResult
+from opentelemetry.sdk.trace.sampling import ALWAYS_ON
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+SCHEMA_URL = "https://opentelemetry.io/schemas/1.37.0"
+SENSITIVE = re.compile(r"^(api[_-]?key|access[_-]?token|auth[_-]?token|authorization|client[_-]?secret|cookie|password|private[_-]?key|proxy-authorization|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)
+INLINE_SECRET = re.compile(r'''(["']?(?:api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|password|private[_-]?key|refresh[_-]?token|secret|session[_-]?token)["']?\s*[:=]\s*)(["']?)[^\s,;}"']{4,}(["']?)''', re.I)
+CORRELATIONS = {"conversationId": "gen_ai.conversation.id", "toolCallId": "gen_ai.tool.call.id", "invocationId": "rippletide.invocation.id", "decisionId": "rippletide.policy.decision.id"}
+INDEXED = {
+    "provider": "gen_ai.provider.name", "model": "gen_ai.request.model", "responseId": "gen_ai.response.id",
+    "inputTokens": "gen_ai.usage.input_tokens", "outputTokens": "gen_ai.usage.output_tokens", "totalTokens": "rippletide.model.total_tokens",
+    "streaming": "rippletide.model.streaming", "toolCallIds": "rippletide.model.tool_call_ids", "toolCallCount": "rippletide.model.tool_call_count",
+    "captureCompleteness": "rippletide.capture.completeness", "trigger": "rippletide.policy.trigger", "action": "rippletide.policy.action",
+    "disposition": "rippletide.policy.disposition", "decisionRoundtripMs": "rippletide.policy.roundtrip_ms", "failOpen": "rippletide.policy.fail_open",
+    "policyFallback": "rippletide.policy.fallback", "decidedAfterDelivery": "rippletide.policy.decided_after_delivery",
+    "executed": "rippletide.action.executed", "applicationOutcome": "rippletide.action.application_outcome",
+    "deliveredItemCount": "rippletide.result.delivered_item_count", "excludedItemCount": "rippletide.result.excluded_item_count",
+    "signal": "rippletide.signal", "source": "rippletide.source", "standalone": "rippletide.standalone",
+}
+
+
+def sanitized_text(value: str) -> str:
+    value = INLINE_SECRET.sub(r"\1\2[REDACTED]\3", INLINE_AUTH.sub(r"\1 [REDACTED]", value))
+    return value.replace("\0", "\ufffd").encode("utf-8", errors="replace").decode("utf-8")
+
+
+def capture_value(value: Any) -> tuple[Any, bool]:
+    remaining, truncated, ancestors = 200, False, set()
+
+    def visit(item: Any, depth: int = 0, key: str = "") -> Any:
+        nonlocal remaining, truncated
+        if depth > 6 or remaining <= 0:
+            truncated = True
+            return "…"
+        remaining -= 1
+        if SENSITIVE.match(key):
+            return "[REDACTED]"
+        if item is None or isinstance(item, (bool, int)):
+            return item
+        if isinstance(item, float):
+            return item if math.isfinite(item) else str(item)
+        if isinstance(item, str):
+            clean = sanitized_text(item)
+            truncated |= len(clean) > 4000
+            return clean[:4000]
+        if isinstance(item, (Mapping, list, tuple)):
+            if id(item) in ancestors:
+                truncated = True
+                return "[Circular]"
+            ancestors.add(id(item))
+            truncated |= len(item) > 50
+            if isinstance(item, Mapping):
+                result = {sanitized_text(str(child_key))[:128]: visit(child, depth + 1, str(child_key)) for child_key, child in list(item.items())[:50]}
+            else:
+                result = [visit(child, depth + 1) for child in item[:50]]
+            ancestors.remove(id(item))
+            return result
+        return visit(str(item), depth)
+
+    captured = visit(value)
+    encoded = json.dumps(captured, ensure_ascii=False, separators=(",", ":"))
+    if len(encoded) > 8000:
+        return {"truncated": True, "preview": encoded[:3980]}, True
+    return captured, truncated
+
+
+def otlp_json(message: Any) -> dict:
+    value = MessageToDict(message, use_integers_for_enums=True)
+
+    def normalize(item: Any) -> Any:
+        if isinstance(item, list):
+            return [normalize(child) for child in item]
+        if isinstance(item, dict):
+            return {key: base64.b64decode(child).hex() if key in {"traceId", "spanId", "parentSpanId"} and isinstance(child, str) else normalize(child) for key, child in item.items()}
+        return item
+
+    return normalize(value)
+
+
+class _SpanExporter(SpanExporter):
+    def __init__(self, telemetry: "Telemetry") -> None:
+        self.telemetry = telemetry
+
+    def export(self, spans: Any) -> SpanExportResult:
+        self.telemetry.enqueue("traces", otlp_json(encode_spans(spans)))
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        pass
+
+
+class _LogExporter(LogRecordExporter):
+    def __init__(self, telemetry: "Telemetry") -> None:
+        self.telemetry = telemetry
+
+    def export(self, records: Any) -> LogRecordExportResult:
+        self.telemetry.enqueue("logs", otlp_json(encode_logs(records)))
+        return LogRecordExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        pass
+
+
+class Telemetry:
+    def __init__(self, client: Any) -> None:
+        self.client = client
+        self.pending = {"traces": deque(maxlen=2000), "logs": deque(maxlen=2000)}
+        self.lock = Lock()
+        resource = Resource.create({"service.name": "rippletide-instrumented-agent"})
+        self.provider = TracerProvider(resource=resource, sampler=ALWAYS_ON, span_limits=SpanLimits(max_attributes=128, max_events=128, max_links=32), shutdown_on_exit=False)
+        self.provider.add_span_processor(SimpleSpanProcessor(_SpanExporter(self)))
+        try:
+            sdk_version = version("rippletide-python")
+        except PackageNotFoundError:
+            sdk_version = None
+        self.tracer = self.provider.get_tracer("rippletide-python", sdk_version, SCHEMA_URL)
+        self.logger_provider = LoggerProvider(resource=resource, shutdown_on_exit=False)
+        self.logger_provider.add_log_record_processor(SimpleLogRecordProcessor(_LogExporter(self)))
+        self.logger = self.logger_provider.get_logger("rippletide-python", sdk_version, SCHEMA_URL)
+
+    def enqueue(self, signal: str, packet: dict) -> None:
+        with self.lock:
+            self.pending[signal].append(packet)
+
+    def attributes(self, kind: str, options: dict, extra: dict | None = None) -> dict:
+        raw = {**(options.get("attributes") or {}), **(extra or {})}
+        captured, truncated = capture_value(raw if self.client.capture_content else {key: value for key, value in raw.items() if key in INDEXED or key == "finishReason"})
+        result = {"rippletide.schema.version": "1", "rippletide.agent.id": self.client.agent_id, "rippletide.span.kind": kind, "rippletide.capture.mode": "full", "rippletide.evidence.fidelity": "runtime_trace"}
+        loss = []
+        for source, target in {**INDEXED, **CORRELATIONS}.items():
+            value = options.get(source) if source in CORRELATIONS else raw.get(source)
+            if isinstance(value, str):
+                clean = sanitized_text(value)
+                result[target] = clean[:512]
+                if len(clean) > 512:
+                    loss.append(target)
+            elif isinstance(value, (bool, int, float)) and (not isinstance(value, (int, float)) or math.isfinite(value)):
+                result[target] = value
+            elif isinstance(value, list) and all(isinstance(item, str) for item in value):
+                result[target] = [sanitized_text(item)[:512] for item in value[:50]]
+                if len(value) > 50 or any(len(item) > 512 for item in value[:50]):
+                    loss.append(target)
+        if isinstance(raw.get("finishReason"), str):
+            result["gen_ai.response.finish_reasons"] = [sanitized_text(raw["finishReason"])[:512]]
+        if self.client.capture_content:
+            result["rippletide.attributes.json"] = json.dumps(captured, ensure_ascii=False, separators=(",", ":"))
+            if truncated:
+                loss.append("rippletide.attributes.json")
+            for field in ("input", "output"):
+                if field in options:
+                    value, cut = capture_value(options[field])
+                    result[f"rippletide.{field}.json"] = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+                    if cut:
+                        loss.append(f"rippletide.{field}.json")
+        completeness = raw.get("captureCompleteness")
+        result["rippletide.capture.completeness"] = completeness if isinstance(completeness, str) and completeness in {"capture_error", "stream_not_consumed"} else "complete" if self.client.capture_content else "not_captured"
+        if loss:
+            result["rippletide.capture.completeness"] = "truncated"
+        if loss:
+            result["rippletide.capture.truncated_fields"] = loss
+        return result
+
+    def start(self, kind: str, name: str, options: dict, root: bool, traceparent: str | None) -> Any:
+        parent = TraceContextTextMapPropagator().extract({"traceparent": traceparent, "tracestate": options.get("tracestate") or ""}) if traceparent else context.Context() if root else context.get_current()
+        attributes = self.attributes(kind, options)
+        if kind == "tool":
+            attributes["gen_ai.tool.name"] = sanitized_text(name)[:512]
+        if kind == "agent":
+            attributes["gen_ai.agent.name"] = sanitized_text(name)[:512]
+        links = [trace.Link(link.context, {"rippletide.link.type": link.attributes["rippletide.link.type"]})
+                 for link in (options.get("links") or [])[:32]
+                 if isinstance(link, trace.Link) and link.context.is_valid and (link.attributes or {}).get("rippletide.link.type") in {"depends_on", "follows_from"}]
+        span = self.tracer.start_span(sanitized_text(name)[:512], context=parent, kind=trace.SpanKind.CLIENT if kind in {"policy", "model"} else trace.SpanKind.INTERNAL, attributes=attributes, links=links)
+        span.add_event("rippletide.span.started", attributes, span.start_time)
+        span_context = span.get_span_context()
+        start_attributes = {**attributes, "rippletide.event.id": str(uuid.uuid4())}
+        if links:
+            start_attributes["rippletide.start.links.json"] = json.dumps([{
+                "traceId": format(link.context.trace_id, "032x"), "spanId": format(link.context.span_id, "016x"),
+                "flags": int(link.context.trace_flags), "traceState": link.context.trace_state.to_header(),
+                "attributes": [{"key": key, "value": {"stringValue": str(value)}} for key, value in (link.attributes or {}).items()],
+            } for link in links], separators=(",", ":"))
+        parent_span = trace.get_current_span(parent).get_span_context()
+        if parent_span.is_valid:
+            start_attributes["rippletide.parent.span_id"] = format(parent_span.span_id, "016x")
+        self.logger.emit(LogRecord(timestamp=span.start_time, trace_id=span_context.trace_id, span_id=span_context.span_id, trace_flags=span_context.trace_flags, event_name="rippletide.span.started", body=span.name, attributes=start_attributes))
+        return span
+
+    def flush(self) -> bool:
+        success = True
+        deadline = time.monotonic() + self.client.timeout
+        for signal, queue in self.pending.items():
+            while queue and time.monotonic() < deadline:
+                with self.lock:
+                    batch = [queue.popleft() for _ in range(min(4, len(queue)))]
+                field = "resourceSpans" if signal == "traces" else "resourceLogs"
+                packet = {field: [resource for item in batch for resource in item.get(field, [])]}
+                for attempt in range(3):
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        success = False
+                        break
+                    try:
+                        response = self.client._request("POST", f"/v1/{signal}", packet, timeout=remaining)
+                        rejected = int(response.get("partialSuccess", {}).get("rejectedSpans" if signal == "traces" else "rejectedLogRecords", 0))
+                        success &= rejected == 0
+                        break
+                    except Exception as error:
+                        if getattr(error, "status", None) not in {429, 502, 503, 504} or attempt == 2:
+                            success = False
+                            self.client._warn("Rippletide runtime export unavailable; dropped batch")
+                            break
+                        time.sleep(min(0.05 * 2 ** attempt, max(0, deadline - time.monotonic())))
+        return success and not any(self.pending.values())
+
+    def shutdown(self) -> None:
+        self.provider.shutdown()
+        self.logger_provider.shutdown()

rippletide_python-0.3.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: rippletide-python
+Version: 0.3.0
+Summary: Monitor-first Python SDK for Rippletide-connected agents
+License: UNLICENSED
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-sdk==1.40.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-common==1.40.0
+
+# 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.
+
+## Install and connect
+
+The current release is `rippletide-python==0.3.0`. It requires
+the platform's OTLP ingestion/readers and does not provide V1 trace compatibility.
+Until it is published, validate it by installing a locally built wheel; do not
+assume the unversioned registry install below contains candidate changes.
+
+Requires Python 3.10 or later. From the existing agent repository, use its Python
+environment, or create one if it has none:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install rippletide-python
+```
+
+On Windows, activate with `.venv\Scripts\Activate.ps1` in PowerShell instead.
+Keep the dependency in the project's requirements or package-manager manifest.
+
+In Rippletide, choose **Connect an agent → Agent (Python)**. Save the generated
+credentials in the repository's git-ignored `.env`, then apply the generated
+prompt with your coding agent in that repository. The CLI also supports
+`rippletide connect --kind agent --language python --print-prompt`.
+
+Run a real turn that uses a tool and delivers a response. Confirm **Runtime
+verified (5/5)** in Fleet and the run's tool calls and **Delivered** outcome in
+Activity. Copying a prompt or storing credentials alone does not prove a
+connection.
+
+## Instrument existing call sites
+
+The following fragment belongs inside the existing request handler; reuse the
+agent's own provider, messages, tools, context, and response sink.
+
+```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`.
+
+## Async and streaming agents
+
+The same client serves synchronous and asyncio code. `guard_tool_call()`,
+`guard_tool_result()` and `deliver_response()` accept `async def` callbacks and
+then return a coroutine to await; the policy round trip and receipts run in a
+worker thread, so the event loop is never blocked. `run()`, `agent()` and
+`span()` are plain `with` blocks in both cases. `traced()` wraps sync
+functions, coroutine functions, and calls that return a provider stream: the
+stream is passed through untouched and its span ends once the stream is
+consumed, closed, or abandoned, in which case the span is marked
+`stream_not_consumed`. Policy decides on the complete response: pass the text
+the agent has assembled from the stream to `deliver_response()` before the
+existing sink delivers it. When the tokens must reach the caller as they arrive,
+pass the stream itself as `response`: chunks flow through to `deliver` untouched
+and the decision is recorded on the assembled text once the stream ends, with no
+suppression possible, so a BLOCK is marked as decided after delivery.
+Use `await rippletide.aflush()` and
+`await rippletide.ashutdown()` from asyncio code.
+
+```python
+async def handle(request):
+    with rippletide.run(name="inbound_request", input=request):
+        stream = rippletide.traced(open_model_stream, name=MODEL_OPERATION, kind="model")(messages)
+        candidate = "".join([chunk.text async for chunk in stream])
+        await rippletide.guard_tool_call(toolset="core", tool="lookup", params=args, execute=lookup_async)
+        return await rippletide.deliver_response(request=request, response=candidate, deliver=send_async)
+```
+
+## Policy failures and capture
+
+The client starts disabled when no Connection key is present. For
+`guard_tool_call()` and `deliver_response()`:
+
+- Network failures, 5xx responses, rate limits, and malformed or interrupted HTTP
+  responses fail open: the protected callback can still run.
+- An enforce-mode `BLOCK` raises `RippletidePolicyBlockedError` before the
+  protected callback runs. An observe-only `WOULD_BLOCK` permits execution.
+- HTTP `400`, `401`, `403`, or `404` from the policy decision endpoint raises
+  `RippletidePolicyDecisionError` before the callback runs. These request,
+  authentication, authorization, or routing failures are not swallowed as
+  telemetry outages.
+
+Result filtering has its own fallback rules, described below. Application input
+validation and exceptions from the agent's own callbacks can also propagate.
+
+Runtime instrumentation uses native OpenTelemetry spans and start logs, exported as
+OTLP/HTTP JSON to `/v1/traces` and `/v1/logs`. Providers are local to the client;
+the SDK does not replace application providers. The only profile is `full`, but
+content is omitted unless `Rippletide(capture_content=True)` is explicit. Captured
+content is bounded and credential-redacted, including nested Python mappings
+such as `UserDict` and `MappingProxyType`, not generally PII-filtered. The old
+capture modes are unsupported. `runtime_traces=False` disables evidence export
+without disabling policy checks. Always call `flush()` before a short-lived
+worker exits, and `shutdown()` when the client is no longer needed.
+
+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
+the default content-withheld posture. 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. Transient policy failures and malformed or mismatched plans forward
+every item unchanged. A missing result endpoint (`404` with no error code or
+`NOT_FOUND`) also uses this fallback. Other deterministic request or permission
+rejections raise `RippletidePolicyDecisionError` before `apply` runs.
+
+```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.
+
+Python MCP servers remain unsupported. A response that is streamed to the
+caller before it is complete cannot be protected by `deliver_response()`; the
+SDK does not represent such a path as complete response-delivery protection.

rippletide_python-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+rippletide/__init__.py,sha256=lPw2FwwCVSYhMQdQlgZufRLZLZrECKYPvtrMELUxYdI,304
+rippletide/client.py,sha256=3qFew8n5s-Dknjxs_waqh_ixP_t5XiF3GH36POVt4rM,45301
+rippletide/telemetry.py,sha256=l4bia3FBdqbARXPwSdVcxDMCL1cJOb8n6VhLrzcFcFk,13801
+rippletide_python-0.3.0.dist-info/METADATA,sha256=KmhuIYdBuA5wzDjCjDPX5zkPxmlV6sGH9Jweoem1YIo,9225
+rippletide_python-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rippletide_python-0.3.0.dist-info/top_level.txt,sha256=NAEYCFwQDE0G96JlVKq00OiKb0YLZ_Er8rcAhOiYHzo,11
+rippletide_python-0.3.0.dist-info/RECORD,,

rippletide_python-0.1.0.dist-info/METADATA

@@ -1,101 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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,,