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

rippletide/client.py

@@ -10,24 +10,22 @@ 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 contextlib import contextmanager, nullcontext
 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
+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 +36,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 +84,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,19 +212,26 @@ 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 = trace.use_span(self.native, end_on_exit=False, record_exception=False, set_status_on_exception=False) if self.native.is_recording() else nullcontext()
+        self.scope.__enter__()
         return self
 
     def set_output(self, output: Any, **attributes: Any) -> None:
@@ -262,39 +239,57 @@ class _Span:
         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
 
 
 class Rippletide:
-    """Synchronous, dependency-free client with the TypeScript SDK's core semantics."""
+    """Synchronous policy client with native OpenTelemetry instrumentation."""
 
-    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 _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) -> Any:
+    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,55 +314,23 @@ 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]:
+    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]:
         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:
+        with _Span(self, normalized, 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]:
@@ -379,8 +342,9 @@ class Rippletide:
         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 {}
+        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 +360,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')
 
@@ -546,9 +510,9 @@ class Rippletide:
             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"}):
+            with self.span("tool", name=tool, input=params, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], 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:
+        with self.span("tool", name=tool, input=params, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], 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)
@@ -573,6 +537,7 @@ class Rippletide:
         evaluated_context = _clone_policy_value(dict(context or {}), "trusted context")
         decision: Mapping[str, Any] | None = None
         elapsed = 0
+        policy_span = None
 
         if allow_result_export and not self.disabled:
             invocation_id = str(uuid.uuid4())
@@ -580,6 +545,7 @@ class Rippletide:
             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")
 
@@ -601,7 +567,7 @@ class Rippletide:
                 })
         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:
+        with self.span("operation", name="result_application", input=filtered, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})] if policy_span else [], 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)
@@ -631,24 +597,21 @@ class Rippletide:
             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"}):
+            with self.span("operation", name="response_delivery", input=response, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], 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:
+        with self.span("operation", name="response_delivery", input=response, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], 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:
+        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()
+
+    def shutdown(self) -> None:
+        self.flush()
+        if self._telemetry:
+            self._telemetry.shutdown()

rippletide/telemetry.py

@@ -0,0 +1,241 @@
+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", "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.1.0.dist-info → rippletide_python-0.2.0.dist-info}/METADATA

@@ -1,10 +1,12 @@
 Metadata-Version: 2.4
 Name: rippletide-python
-Version: 0.1.0
+Version: 0.2.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
 
@@ -12,6 +14,41 @@ Description-Content-Type: text/markdown
 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 native OTel release candidate is `rippletide-python==0.2.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. The SDK supports synchronous call sites. Async execution and
+streaming are not supported.
+
+## 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
 
@@ -48,18 +85,36 @@ 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.
+## 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
-metadata capture mode. These IDs correlate the action with its policy receipt.
+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
@@ -70,7 +125,10 @@ owner has explicitly approved storing the prompt text in Rippletide.
 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.
+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={

rippletide_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+rippletide/__init__.py,sha256=lPw2FwwCVSYhMQdQlgZufRLZLZrECKYPvtrMELUxYdI,304
+rippletide/client.py,sha256=gAxI38pg9a1kNvyV6s_lmfauCNgeGrwOXXM-CEz-cl8,36623
+rippletide/telemetry.py,sha256=oG6YaRZLwUvIshl3egXeMN5ViD5mDMMVWClCvH3nnM0,13729
+rippletide_python-0.2.0.dist-info/METADATA,sha256=k8jWdR_NzOpRbHK4dOhgstK1AiwLsaK65YMcX3gNFoQ,7659
+rippletide_python-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rippletide_python-0.2.0.dist-info/top_level.txt,sha256=NAEYCFwQDE0G96JlVKq00OiKb0YLZ_Er8rcAhOiYHzo,11
+rippletide_python-0.2.0.dist-info/RECORD,,

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,,