trazio-telemetry 0.3.0__py3-none-any.whl

hyperlake_telemetry/__init__.py

@@ -0,0 +1,20 @@
+"""Deprecated alias: the SDK is now ``trazio_telemetry`` (package ``trazio-telemetry``)."""
+
+import sys
+import warnings
+
+import trazio_telemetry as _trazio
+from trazio_telemetry import *  # noqa: F401,F403
+from trazio_telemetry import __all__, __version__  # noqa: F401
+from trazio_telemetry import client, integrations, semantic_query  # noqa: F401
+
+warnings.warn(
+    "hyperlake_telemetry is renamed to trazio_telemetry; update your imports",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+for _name in ("client", "semantic_query", "integrations", "integrations.openinference", "integrations.temporal"):
+    __import__(f"trazio_telemetry.{_name}")
+    sys.modules[f"{__name__}.{_name}"] = sys.modules[f"trazio_telemetry.{_name}"]
+del _name, _trazio

trazio_telemetry/__init__.py

@@ -0,0 +1,16 @@
+"""Standards-first OTLP telemetry and artifact helpers."""
+
+from .client import AdminClient, Client, Privacy, Run, Span, stable_event_id
+from .semantic_query import (
+    DeterministicSemanticPlanner,
+    ModelSemanticPlanner,
+    deterministic_plan,
+    normalize_semantic_query,
+)
+
+__all__ = [
+    "AdminClient", "Client", "Privacy", "Run", "Span", "stable_event_id",
+    "DeterministicSemanticPlanner", "ModelSemanticPlanner",
+    "deterministic_plan", "normalize_semantic_query",
+]
+__version__ = "0.3.0"

trazio_telemetry/client.py

@@ -0,0 +1,819 @@
+"""Small dependency-free OTLP/HTTP client with explicit privacy controls."""
+
+from __future__ import annotations
+
+import hashlib
+import base64
+import json
+import os
+import re
+import secrets
+import ssl
+import time
+from contextlib import AbstractContextManager
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, Mapping, Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode, urlparse
+from urllib.request import Request, HTTPRedirectHandler, HTTPSHandler, build_opener
+
+
+class _NoCredentialRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        raise HTTPError(req.full_url, code, "Redirect refused", headers, fp)
+
+
+def urlopen(request, *, timeout, context):
+    return build_opener(_NoCredentialRedirect(), HTTPSHandler(context=context)).open(request, timeout=timeout)
+
+import certifi
+
+from .semantic_query import DeterministicSemanticPlanner, normalize_semantic_query
+
+
+_SENSITIVE_KEY = re.compile(
+    r"(^|[._-])(authorization|cookie|password|passwd|secret|token|api[._-]?key|private[._-]?key)([._-]|$)",
+    re.IGNORECASE,
+)
+
+
+def _segment(value: Any) -> str:
+    return quote(str(value), safe="")
+
+
+def _decode_jwt(token: Optional[str]) -> Optional[Dict[str, Any]]:
+    if not token:
+        return None
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("tenant_jwt must be a three-segment JWT")
+    try:
+        payload = parts[1] + "=" * (-len(parts[1]) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(payload).decode("utf-8"))
+        if not claims.get("tenant_id") or not claims.get("pipeline_id"):
+            raise ValueError("scope missing")
+        if claims.get("exp") and int(claims["exp"]) <= int(time.time()):
+            raise ValueError("expired")
+        return claims
+    except Exception as exc:
+        raise ValueError(f"tenant_jwt claims are invalid: {exc}") from exc
+
+
+def stable_event_id(*parts: Any) -> str:
+    """Return a deterministic identity for a logical event or evaluation."""
+    canonical = json.dumps(parts, sort_keys=True, separators=(",", ":"), default=str)
+    return "evt_" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class Privacy:
+    """Content and secret handling applied before telemetry leaves the process."""
+
+    capture_content: bool = False
+    redacted_keys: tuple[str, ...] = ()
+    max_string_length: int = 4096
+    replacement: str = "[REDACTED]"
+
+    def sanitize(self, value: Any, *, content: bool = False) -> Any:
+        if content and not self.capture_content:
+            return self.replacement
+        return self._walk(value)
+
+    def _walk(self, value: Any, key: str = "") -> Any:
+        if key in self.redacted_keys or _SENSITIVE_KEY.search(key):
+            return self.replacement
+        if isinstance(value, Mapping):
+            return {str(k): self._walk(v, str(k)) for k, v in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [self._walk(item, key) for item in value]
+        if isinstance(value, str) and len(value) > self.max_string_length:
+            return value[: self.max_string_length] + "…[TRUNCATED]"
+        if value is None or isinstance(value, (str, bool, int, float)):
+            return value
+        return str(value)
+
+
+def _any_value(value: Any) -> Dict[str, Any]:
+    if value is None:
+        return {"stringValue": ""}
+    if isinstance(value, bool):
+        return {"boolValue": value}
+    if isinstance(value, int):
+        return {"intValue": str(value)}
+    if isinstance(value, float):
+        return {"doubleValue": value}
+    if isinstance(value, (dict, list, tuple)):
+        return {"stringValue": json.dumps(value, sort_keys=True, separators=(",", ":"))}
+    return {"stringValue": str(value)}
+
+
+def _attributes(values: Mapping[str, Any]) -> list[Dict[str, Any]]:
+    return [{"key": str(k), "value": _any_value(v)} for k, v in values.items() if v is not None]
+
+
+@dataclass
+class Span(AbstractContextManager["Span"]):
+    client: "Client"
+    name: str
+    trace_id: str
+    span_id: str
+    parent_span_id: Optional[str]
+    attributes: Dict[str, Any]
+    start_ns: int = field(default_factory=time.time_ns)
+    end_ns: Optional[int] = None
+    status_code: int = 0
+    status_message: str = ""
+    events: list[Dict[str, Any]] = field(default_factory=list)
+    _ended: bool = False
+
+    def __enter__(self) -> "Span":
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> bool:
+        if exc is not None:
+            self.status_code = 2
+            self.status_message = str(exc)
+            self.add_event("exception", {"exception.type": exc_type.__name__, "exception.message": str(exc)})
+        self.end()
+        return False
+
+    def set_attribute(self, key: str, value: Any, *, content: bool = False) -> "Span":
+        self.attributes[key] = self.client.privacy.sanitize(value, content=content)
+        return self
+
+    def add_event(self, name: str, attributes: Optional[Mapping[str, Any]] = None) -> "Span":
+        clean = self.client.privacy.sanitize(dict(attributes or {}))
+        self.events.append({"timeUnixNano": str(time.time_ns()), "name": name, "attributes": _attributes(clean)})
+        return self
+
+    def end(self, *, error: Optional[str] = None) -> None:
+        if self._ended:
+            return
+        if error:
+            self.status_code = 2
+            self.status_message = error
+        self.end_ns = time.time_ns()
+        self._ended = True
+        self.client._finish_span(self)
+
+    def as_otlp(self) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "traceId": self.trace_id,
+            "spanId": self.span_id,
+            "name": self.name,
+            "kind": 1,
+            "startTimeUnixNano": str(self.start_ns),
+            "endTimeUnixNano": str(self.end_ns or time.time_ns()),
+            "attributes": _attributes(self.attributes),
+            "events": self.events,
+            "status": {"code": self.status_code, "message": self.status_message},
+        }
+        if self.parent_span_id:
+            body["parentSpanId"] = self.parent_span_id
+        return body
+
+
+class Run(AbstractContextManager["Run"]):
+    def __init__(self, client: "Client", root: Span, goal_id: Optional[str]) -> None:
+        self.client = client
+        self.root = root
+        self.goal_id = goal_id
+
+    @property
+    def trace_id(self) -> str:
+        return self.root.trace_id
+
+    @property
+    def run_id(self) -> str:
+        return str(self.root.attributes["run.id"])
+
+    def __enter__(self) -> "Run":
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> bool:
+        return self.root.__exit__(exc_type, exc, traceback)
+
+    def span(
+        self,
+        name: str,
+        *,
+        kind: str = "CHAIN",
+        attributes: Optional[Mapping[str, Any]] = None,
+    ) -> Span:
+        merged = {
+            "openinference.span.kind": kind.upper(),
+            "run.id": self.run_id,
+            "goal.id": self.goal_id,
+            **dict(attributes or {}),
+        }
+        return self.client.start_span(
+            name,
+            trace_id=self.trace_id,
+            parent_span_id=self.root.span_id,
+            attributes=merged,
+        )
+
+    def evaluate(self, name: str, *, score: float, label: str, explanation: str = "") -> None:
+        self.root.add_event(
+            "gen_ai.evaluation",
+            {
+                "gen_ai.evaluation.name": name,
+                "gen_ai.evaluation.score.value": score,
+                "gen_ai.evaluation.score.label": label,
+                "gen_ai.evaluation.explanation": explanation,
+            },
+        )
+
+
+class Client:
+    """OTLP sender plus authenticated event and artifact helpers."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        tenant_id: Optional[str] = None,
+        pipeline_id: Optional[str] = None,
+        protocol_token: Optional[str] = None,
+        tenant_jwt: Optional[str] = None,
+        service_name: str = "application",
+        service_version: Optional[str] = None,
+        environment: Optional[str] = None,
+        privacy: Optional[Privacy] = None,
+        timeout: float = 30.0,
+        spool_directory: Optional[str] = None,
+        max_spool_files: int = 256,
+        auto_flush_spans: int = 64,
+        ssl_context: Optional[ssl.SSLContext] = None,
+        semantic_planner: Any = None,
+    ) -> None:
+        parsed_base = urlparse(base_url)
+        if parsed_base.scheme != "https" or not parsed_base.netloc:
+            raise ValueError("base_url must be an HTTPS origin")
+        claims = _decode_jwt(tenant_jwt)
+        if claims and tenant_id and tenant_id != claims["tenant_id"]:
+            raise ValueError("tenant_id does not match tenant_jwt scope")
+        if claims and pipeline_id and pipeline_id != claims["pipeline_id"]:
+            raise ValueError("pipeline_id does not match tenant_jwt scope")
+        self.base_url = f"https://{parsed_base.netloc}"
+        self.tenant_id = tenant_id or (claims or {}).get("tenant_id")
+        self.pipeline_id = pipeline_id or (claims or {}).get("pipeline_id")
+        if not self.tenant_id or not self.pipeline_id:
+            raise ValueError("tenant_id and pipeline_id are required when tenant_jwt cannot supply scope")
+        self.claims = claims
+        self.protocol_token = protocol_token
+        self.tenant_jwt = tenant_jwt
+        self.service_name = service_name
+        self.service_version = service_version
+        self.environment = environment
+        self.privacy = privacy or Privacy()
+        self.timeout = timeout
+        self.max_spool_files = max_spool_files
+        self.auto_flush_spans = auto_flush_spans
+        self.ssl_context = ssl_context or ssl.create_default_context(cafile=certifi.where())
+        self.semantic_planner = semantic_planner or DeterministicSemanticPlanner()
+        self._pending: list[Span] = []
+        self.spool_directory = Path(spool_directory) if spool_directory else None
+        if self.spool_directory:
+            self.spool_directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+
+    def scope(self) -> Dict[str, Any]:
+        return {
+            "tenant_id": self.tenant_id,
+            "pipeline_id": self.pipeline_id,
+            "subject": (self.claims or {}).get("sub"),
+            "cluster_id": (self.claims or {}).get("cluster_id"),
+            "app_id": (self.claims or {}).get("app_id"),
+        }
+
+    def run(
+        self,
+        name: str,
+        *,
+        run_id: Optional[str] = None,
+        goal_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        attributes: Optional[Mapping[str, Any]] = None,
+    ) -> Run:
+        actual_run_id = run_id or secrets.token_hex(16)
+        root = self.start_span(
+            name,
+            attributes={
+                "openinference.span.kind": "AGENT",
+                "gen_ai.operation.name": "invoke_agent",
+                "gen_ai.agent.id": agent_id,
+                "gen_ai.agent.name": name,
+                "run.id": actual_run_id,
+                "goal.id": goal_id,
+                **dict(attributes or {}),
+            },
+        )
+        return Run(self, root, goal_id)
+
+    def start_span(
+        self,
+        name: str,
+        *,
+        trace_id: Optional[str] = None,
+        parent_span_id: Optional[str] = None,
+        attributes: Optional[Mapping[str, Any]] = None,
+    ) -> Span:
+        clean = self.privacy.sanitize(dict(attributes or {}))
+        return Span(
+            client=self,
+            name=name,
+            trace_id=trace_id or secrets.token_hex(16),
+            span_id=secrets.token_hex(8),
+            parent_span_id=parent_span_id,
+            attributes=clean,
+        )
+
+    def _finish_span(self, span: Span) -> None:
+        self._pending.append(span)
+        if len(self._pending) >= self.auto_flush_spans:
+            self.flush()
+
+    def _otlp_payload(self, spans: Iterable[Span]) -> Dict[str, Any]:
+        resource = {
+            "service.name": self.service_name,
+            "service.version": self.service_version,
+            "deployment.environment.name": self.environment,
+        }
+        return {
+            "resourceSpans": [{
+                "resource": {"attributes": _attributes(resource)},
+                "scopeSpans": [{
+                    "scope": {"name": "trazio-telemetry", "version": "0.3.0"},
+                    "spans": [span.as_otlp() for span in spans],
+                }],
+            }],
+        }
+
+    def flush(self) -> None:
+        self._drain_spool()
+        if not self._pending:
+            return
+        spans, self._pending = self._pending, []
+        payload = self._otlp_payload(spans)
+        try:
+            self._request("POST", "/v1/traces", payload, protocol=True)
+        except Exception:
+            self._spool(payload)
+            raise
+
+    def record_event(
+        self,
+        event: Mapping[str, Any],
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        key = idempotency_key or stable_event_id(self.tenant_id, self.pipeline_id, event)
+        path = f"/v1/ingest/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}"
+        return self._request("POST", path, self.privacy.sanitize(dict(event)), jwt=True, extra_headers={"Idempotency-Key": key})
+
+    def upload_artifact(
+        self,
+        path: str,
+        *,
+        format: str = "auto",
+        device_id: Optional[str] = None,
+        goal_id: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        source = Path(path)
+        base = f"/v1/artifacts/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/sessions"
+        session = self._request(
+            "POST",
+            base,
+            {
+                "filename": source.name,
+                "format": format,
+                "device_id": device_id,
+                "goal_id": goal_id,
+                "metadata": self.privacy.sanitize(dict(metadata or {})),
+            },
+            jwt=True,
+        )
+        session_id = session["session_id"]
+        content = source.read_bytes()
+        self._request("PUT", f"{base}/{_segment(session_id)}/content", content, jwt=True, content_type="application/octet-stream")
+        return self._request("POST", f"{base}/{_segment(session_id)}/complete", None, jwt=True)
+
+    def list_notice_deliveries(self, *, transport="room", limit=50, cursor=None):
+        if transport not in {"room", "moq"}:
+            raise ValueError("transport must be room or moq")
+        params = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        base = "livekit" if transport == "room" else "live"
+        return self._request("GET", f"/v1/{base}/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/notice-deliveries?{urlencode(params)}", None, jwt=True)
+
+    def replay_notice_delivery(self, body, *, transport="room"):
+        if transport not in {"room", "moq"}:
+            raise ValueError("transport must be room or moq")
+        base = "livekit" if transport == "room" else "live"
+        return self._request("POST", f"/v1/{base}/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/notice-replay", dict(body), jwt=True)
+
+    def analyze_live_frame(
+        self,
+        path: str,
+        *,
+        stream_session_id: str,
+        frame_id: str,
+        observed_at: Optional[str] = None,
+        device_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        goal_id: Optional[str] = None,
+        content_type: str = "image/jpeg",
+    ) -> Dict[str, Any]:
+        if not stream_session_id or not frame_id:
+            raise ValueError("stream_session_id and frame_id are required")
+        headers = {
+            "X-Stream-Session-Id": stream_session_id,
+            "X-Frame-Id": frame_id,
+            "X-Observed-At": observed_at or datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        }
+        for name, value in (("X-Device-Id", device_id), ("X-Run-Id", run_id), ("X-Goal-Id", goal_id)):
+            if value:
+                headers[name] = value
+        live_path = f"/v1/live/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/analyze-frame"
+        return self._request(
+            "POST", live_path, Path(path).read_bytes(), jwt=True,
+            content_type=content_type, extra_headers=headers,
+        )
+
+    def _query_path(self, suffix: str = "") -> str:
+        return f"/v1/query/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}{suffix}"
+
+    def _artifact_path(self, suffix: str = "") -> str:
+        return f"/v1/artifacts/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}{suffix}"
+
+    def _tenant_path(self, suffix: str = "") -> str:
+        return f"/v1/tenant/pipelines/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}{suffix}"
+
+    def list_events(self, *, limit: int = 100, cursor: Optional[str] = None, include_ai: bool = True) -> Dict[str, Any]:
+        params = {"limit": min(max(int(limit), 1), 100), "include_ai": str(include_ai).lower()}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", f"{self._query_path()}?{urlencode(params)}", None, jwt=True)
+
+    @staticmethod
+    def _event(row: Mapping[str, Any]) -> Dict[str, Any]:
+        event = row.get("event") or {}
+        metadata = row.get("metadata") or {}
+        evaluation = row.get("rule_evaluation") or {}
+        timestamps = event.get("timestamps") or {}
+        return {
+            "event_id": metadata.get("event_id") or event.get("event_id"),
+            "timestamp": timestamps.get("observed") or timestamps.get("received") or event.get("received_at") or metadata.get("received_at"),
+            "source_type": event.get("source_type") or (event.get("source") or {}).get("type") or "unknown",
+            "event_type": event.get("event_type"),
+            "severity": evaluation.get("severity") or event.get("severity") or "info",
+            "message": str(event.get("message") or ((event.get("content") or {}).get("normalized") or {}).get("message") or "")[:2000],
+            "device_id": event.get("device_id"),
+            "run_id": event.get("run_id") or event.get("goal_id") or event.get("mission_id") or event.get("recording_id"),
+            "rule_evaluation": row.get("rule_evaluation"),
+            "ai_enrichment": row.get("ai_enrichment"),
+        }
+
+    def search_events(self, query: str | Mapping[str, Any]) -> Dict[str, Any]:
+        plan = normalize_semantic_query({"question": query, "targets": ["events"]} if isinstance(query, str) else {**query, "targets": ["events"]})
+        rows, cursor = [], None
+        while len(rows) < plan["options"]["max_scan"]:
+            page = self.list_events(limit=min(100, plan["options"]["max_scan"] - len(rows)), cursor=cursor)
+            rows.extend(page.get("results") or [])
+            cursor = page.get("cursor")
+            if not cursor or page.get("list_complete"):
+                break
+        filters = plan["filters"]
+        words = list(dict.fromkeys(filters["keywords"] + re.findall(r"[a-z0-9_.:-]{2,}", plan["question"].lower())))
+        matches = []
+        for row in rows:
+            event = self._event(row)
+            source = str(event["source_type"])
+            if filters["source_types"] and not any(source.startswith(item[:-1]) if item.endswith(".*") else source == item for item in filters["source_types"]):
+                continue
+            if filters["event_types"] and event["event_type"] not in filters["event_types"]:
+                continue
+            if filters["severities"] and event["severity"] not in filters["severities"]:
+                continue
+            if filters["device_id"] and event["device_id"] != filters["device_id"]:
+                continue
+            if filters["run_id"] and event["run_id"] != filters["run_id"]:
+                continue
+            event_time = _timestamp_value(event["timestamp"])
+            if filters["from"] and event_time is not None and event_time < _timestamp_value(filters["from"]):
+                continue
+            if filters["to"] and event_time is not None and event_time > _timestamp_value(filters["to"]):
+                continue
+            haystack = json.dumps(event, default=str).lower()
+            matched = [word for word in words if word in haystack]
+            if words and not matched:
+                continue
+            matches.append({"event": event, "score": len(matched) / len(words) if words else 1, "matched_terms": matched})
+        matches.sort(key=lambda item: item["score"], reverse=True)
+        matches = matches[: plan["options"]["limit"]]
+        return {"scope": self.scope(), "plan": plan, "scanned": len(rows), "count": len(matches), "matches": matches, "retrieval": "structured_lexical"}
+
+    def search_artifacts(self, query: str | Mapping[str, Any]) -> Dict[str, Any]:
+        plan = normalize_semantic_query({"question": query, "targets": ["artifacts"]} if isinstance(query, str) else {**query, "targets": ["artifacts"]})
+        filters = plan["filters"]
+        payload = {"query": plan["question"], "top_k": plan["options"]["top_k"]}
+        for key in ("session_id", "device_id", "run_id"):
+            if filters[key]:
+                payload[key] = filters[key]
+        return self._request("POST", self._artifact_path("/search"), payload, jwt=True)
+
+    def correlation_graph(self, **options: Any) -> Dict[str, Any]:
+        params = {key: options[key] for key in ("query", "node_id", "event_id", "edge_id", "relationship", "rule_id") if options.get(key)}
+        if options.get("event_ids"):
+            params["event_ids"] = ",".join(options["event_ids"][:50])
+        params["hops"] = min(max(int(options.get("hops", 1)), 0), 3)
+        params["limit"] = min(max(int(options.get("limit", 100)), 1), 500)
+        return self._request("GET", f"{self._query_path('/graph')}?{urlencode(params)}", None, jwt=True)
+
+    def get_artifact_session(self, session_id: str) -> Dict[str, Any]:
+        return self._request("GET", self._artifact_path(f"/sessions/{_segment(session_id)}"), None, jwt=True)
+
+    def get_telemetry(self, session_id: str) -> str:
+        return self._request("GET", self._artifact_path(f"/sessions/{_segment(session_id)}/telemetry"), None, jwt=True, response_type="text")
+
+    def download_artifact(self, session_id: str) -> bytes:
+        return self._request("GET", self._artifact_path(f"/sessions/{_segment(session_id)}/content"), None, jwt=True, response_type="bytes")
+
+    def open_video(self, session_id: str, *, title: Optional[str] = None, ttl_seconds: int = 900, embed_origin: Optional[str] = None) -> Dict[str, Any]:
+        result = self._request("POST", self._artifact_path(f"/sessions/{_segment(session_id)}/playback"), {"title": title, "ttl_seconds": min(max(ttl_seconds, 60), 3600), **({"embed_origin": embed_origin} if embed_origin else {})}, jwt=True)
+        result["viewer_url"] = self.base_url + result["viewer_url"]
+        return result
+
+    def renew_playback(self, session_id: str, token: str) -> Dict[str, Any]:
+        return self._request("POST", self._artifact_path(f"/sessions/{_segment(session_id)}/playback-renew"), {"token": token}, jwt=True)
+
+    def create_live_embed(self, options: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", f"/v1/live/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/viewer-grants", options, jwt=True)
+
+    def renew_live_embed(self, grant_id: str) -> Dict[str, Any]:
+        return self._request("PATCH", f"/v1/live/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/viewer-grants/{_segment(grant_id)}", None, jwt=True)
+
+    def revoke_live_embed(self, grant_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/live/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/viewer-grants/{_segment(grant_id)}", None, jwt=True)
+
+    def revoke_playback(self, session_id: str, token: str) -> Dict[str, Any]:
+        return self._request("POST", self._artifact_path(f"/sessions/{_segment(session_id)}/playback-revoke"), {"token": token}, jwt=True)
+
+    def request_video_export(self, session_id: str, *, start_seconds: float, end_seconds: float, idempotency_key: str) -> Dict[str, Any]:
+        return self._request("POST", self._artifact_path(f"/sessions/{_segment(session_id)}/exports"), {"start_seconds": start_seconds, "end_seconds": end_seconds}, jwt=True, extra_headers={"Idempotency-Key": idempotency_key})
+
+    def get_video_export(self, session_id: str, export_id: str) -> Dict[str, Any]:
+        return self._request("GET", self._artifact_path(f"/sessions/{_segment(session_id)}/exports/{_segment(export_id)}"), None, jwt=True)
+
+    def download_video_export(self, session_id: str, export_id: str) -> bytes:
+        return self._request("GET", self._artifact_path(f"/sessions/{_segment(session_id)}/exports/{_segment(export_id)}/content"), None, jwt=True, response_type="bytes")
+
+    def timeline(self, viewer_url: str, *, start_seconds: float = 0, end_seconds: Optional[float] = None, padding_seconds: float = 5) -> Dict[str, Any]:
+        parsed = urlparse(viewer_url)
+        expected = urlparse(self.base_url)
+        if parsed.scheme != expected.scheme or parsed.netloc != expected.netloc or not re.fullmatch(r"/v1/artifacts/play/(?:pc_[a-f0-9]{32}/)?pb_[A-Za-z0-9_-]+", parsed.path):
+            raise ValueError("viewer_url must be an opaque URL issued by this regional service")
+        params = urlencode({"start": start_seconds, "end": start_seconds if end_seconds is None else end_seconds, "padding": min(max(padding_seconds, 0), 60)})
+        return self._request("GET", f"{parsed.path}/timeline?{params}", None, public=True)
+
+    def list_runs(self) -> Dict[str, Any]:
+        return self._request("GET", self._artifact_path("/runs"), None, jwt=True)
+
+    def get_run(self, run_id: str) -> Dict[str, Any]:
+        return self._request("GET", self._artifact_path(f"/runs/{_segment(run_id)}"), None, jwt=True)
+
+    def get_tenant_config(self) -> Dict[str, Any]:
+        return self._request("GET", self._tenant_path("/config"), None, jwt=True)
+
+    def operations_snapshot(self) -> Dict[str, Any]:
+        """Replace the dashboard state with this bounded, pipeline-scoped snapshot."""
+        path = f"/v1/operations/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/snapshot"
+        return self._request("GET", path, None, jwt=True)
+
+    def operations_overview(self) -> Dict[str, Any]:
+        path = f"/v1/operations/{_segment(self.tenant_id)}/{_segment(self.pipeline_id)}/overview"
+        return self._request("GET", path, None, jwt=True)
+
+    def update_tenant_config(self, patch: Mapping[str, Any]) -> Dict[str, Any]:
+        return self._request("PATCH", self._tenant_path("/config"), dict(patch), jwt=True)
+
+    def rotate_protocol_token(self) -> Dict[str, Any]:
+        return self._request("POST", self._tenant_path("/protocol-token/rotate"), {}, jwt=True)
+
+    def validate_rule_pack(self, pack: Mapping[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", self._tenant_path("/rule-packs/validate"), dict(pack), jwt=True)
+
+    def dry_run_rule_pack(self, pack: Mapping[str, Any], events: list[Mapping[str, Any]]) -> Dict[str, Any]:
+        return self._request("POST", self._tenant_path("/rule-packs/dry-run"), {"pack": dict(pack), "events": [dict(event) for event in events]}, jwt=True)
+
+    def publish_rule_pack(self, name: str, version: str, pack: Mapping[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", self._tenant_path(f"/rule-packs/{_segment(name)}/{_segment(version)}"), dict(pack), jwt=True)
+
+    def validate_source_contract(self, contract: Mapping[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", self._tenant_path("/contracts/validate"), dict(contract), jwt=True)
+
+    def dry_run_source_contract(self, contract: Mapping[str, Any], events: list[Mapping[str, Any]]) -> Dict[str, Any]:
+        return self._request("POST", self._tenant_path("/contracts/dry-run"), {"contract": dict(contract), "events": [dict(event) for event in events]}, jwt=True)
+
+    def get_audit(self, *, cursor: Optional[str] = None, limit: int = 100) -> Dict[str, Any]:
+        params = {"limit": min(max(limit, 1), 100)}
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", f"{self._tenant_path('/audit')}?{urlencode(params)}", None, jwt=True)
+
+    def semantic_query(self, question: str, *, planner: Any = None) -> Dict[str, Any]:
+        plan = normalize_semantic_query((planner or self.semantic_planner).plan(question), question=question)
+        result: Dict[str, Any] = {"scope": self.scope(), "plan": plan, "events": None, "artifacts": None, "graph": None, "errors": {}}
+        operations = {
+            "events": lambda: self.search_events(plan),
+            "artifacts": lambda: self.search_artifacts(plan),
+            "graph": lambda: self.correlation_graph(query=plan["question"], relationship=plan["filters"]["relationship"], rule_id=plan["filters"]["rule_id"], hops=plan["options"]["graph_hops"], limit=min(plan["options"]["limit"] * 5, 500)),
+        }
+        for target in plan["targets"]:
+            try:
+                result[target] = operations[target]()
+            except Exception as exc:
+                result["errors"][target] = {"name": type(exc).__name__, "message": str(exc)[:500]}
+        result["reliability"] = {"scope_source": "jwt_claims_server_verified_per_request", "plan_validated": True, "raw_records_merged": False}
+        return result
+
+    def _auth_headers(self, *, protocol: bool = False, jwt: bool = False) -> Dict[str, str]:
+        token = self.protocol_token if protocol else self.tenant_jwt if jwt else None
+        if not token:
+            needed = "protocol_token" if protocol else "tenant_jwt"
+            raise ValueError(f"{needed} is required for this operation")
+        headers = {"Authorization": f"Bearer {token}"}
+        if protocol:
+            headers.update({
+                "X-Platform-Tenant": self.tenant_id,
+                "X-Platform-Pipeline": self.pipeline_id,
+            })
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload: Any,
+        *,
+        protocol: bool = False,
+        jwt: bool = False,
+        content_type: str = "application/json",
+        extra_headers: Optional[Mapping[str, str]] = None,
+        public: bool = False,
+        response_type: str = "json",
+    ) -> Any:
+        headers = {} if public else self._auth_headers(protocol=protocol, jwt=jwt)
+        headers.update(extra_headers or {})
+        headers["Content-Type"] = content_type
+        headers["Accept"] = "application/json"
+        headers["User-Agent"] = "trazio-telemetry-python/0.3.0"
+        data = payload if isinstance(payload, bytes) else None if payload is None else json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        request = Request(self.base_url + path, data=data, method=method, headers=headers)
+        try:
+            with urlopen(request, timeout=self.timeout, context=self.ssl_context) as response:
+                body = response.read()
+                if response_type == "bytes":
+                    return body
+                if response_type == "text":
+                    return body.decode("utf-8", errors="replace")
+                return json.loads(body) if body else {"status": response.status}
+        except HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:2048]
+            raise RuntimeError(f"HTTP {exc.code} from {path}: {detail}") from exc
+        except URLError as exc:
+            raise RuntimeError(f"Transport failure for {path}: {exc.reason}") from exc
+
+    def _spool(self, payload: Mapping[str, Any]) -> None:
+        if not self.spool_directory:
+            return
+        files = sorted(self.spool_directory.glob("*.json"))
+        while len(files) >= self.max_spool_files:
+            files.pop(0).unlink(missing_ok=True)
+        target = self.spool_directory / f"{time.time_ns()}-{secrets.token_hex(4)}.json"
+        target.write_text(json.dumps(payload, separators=(",", ":")), encoding="utf-8")
+        os.chmod(target, 0o600)
+
+    def _drain_spool(self) -> None:
+        if not self.spool_directory:
+            return
+        for item in sorted(self.spool_directory.glob("*.json")):
+            payload = json.loads(item.read_text(encoding="utf-8"))
+            self._request("POST", "/v1/traces", payload, protocol=True)
+            item.unlink()
+
+
+def _timestamp_value(value: Any) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00")).timestamp()
+    except (TypeError, ValueError):
+        return None
+
+
+class AdminClient:
+    """Regional operator client. Keep this credential separate from tenant clients."""
+
+    def __init__(self, *, base_url: str, admin_token: str, timeout: float = 30.0, ssl_context: Optional[ssl.SSLContext] = None) -> None:
+        parsed = urlparse(base_url)
+        if parsed.scheme != "https" or not parsed.netloc:
+            raise ValueError("base_url must be an HTTPS origin")
+        if not admin_token:
+            raise ValueError("admin_token is required")
+        self.base_url = f"https://{parsed.netloc}"
+        self.admin_token = admin_token
+        self.timeout = timeout
+        self.ssl_context = ssl_context or ssl.create_default_context(cafile=certifi.where())
+
+    def request(self, method: str, path: str, body: Any = None) -> Dict[str, Any]:
+        if not path.startswith("/v1/admin/"):
+            raise ValueError("admin requests must use /v1/admin paths")
+        data = None if body is None else json.dumps(body, separators=(",", ":")).encode()
+        request = Request(self.base_url + path, data=data, method=method, headers={
+            "X-Admin-Token": self.admin_token, "Accept": "application/json", "Content-Type": "application/json",
+            "User-Agent": "trazio-telemetry-python/0.3.0",
+        })
+        try:
+            with urlopen(request, timeout=self.timeout, context=self.ssl_context) as response:
+                payload = response.read()
+                return json.loads(payload) if payload else {"status": response.status}
+        except HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:2048]
+            raise RuntimeError(f"HTTP {exc.code} from {path}: {detail}") from exc
+        except URLError as exc:
+            raise RuntimeError(f"Transport failure for {path}: {exc.reason}") from exc
+
+    @staticmethod
+    def _pipeline_path(tenant_id: str, pipeline_id: str, suffix: str = "") -> str:
+        return f"/v1/admin/pipelines/{_segment(tenant_id)}/{_segment(pipeline_id)}{suffix}"
+
+    def create_tenant(self, *, name: str, description: Optional[str] = None) -> Dict[str, Any]:
+        return self.request("POST", "/v1/admin/customers", {"name": name, "description": description})
+
+    def list_pipelines(self, *, cursor: Optional[str] = None, limit: int = 100) -> Dict[str, Any]:
+        params = {"limit": min(max(limit, 1), 100)}
+        if cursor:
+            params["cursor"] = cursor
+        return self.request("GET", f"/v1/admin/pipelines?{urlencode(params)}")
+
+    def get_pipeline(self, tenant_id: str, pipeline_id: str) -> Dict[str, Any]:
+        return self.request("GET", self._pipeline_path(tenant_id, pipeline_id))
+
+    def create_pipeline(self, tenant_id: str, pipeline_id: str, config: Mapping[str, Any]) -> Dict[str, Any]:
+        return self.request("POST", self._pipeline_path(tenant_id, pipeline_id), dict(config))
+
+    def replace_pipeline(self, tenant_id: str, pipeline_id: str, config: Mapping[str, Any]) -> Dict[str, Any]:
+        return self.request("PUT", self._pipeline_path(tenant_id, pipeline_id), dict(config))
+
+    def update_pipeline(self, tenant_id: str, pipeline_id: str, patch: Mapping[str, Any]) -> Dict[str, Any]:
+        return self.request("PATCH", self._pipeline_path(tenant_id, pipeline_id), dict(patch))
+
+    def delete_pipeline(self, tenant_id: str, pipeline_id: str) -> Dict[str, Any]:
+        return self.request("DELETE", self._pipeline_path(tenant_id, pipeline_id))
+
+    def validate_rule_pack(self, pack: Mapping[str, Any]) -> Dict[str, Any]:
+        return self.request("POST", "/v1/admin/rule-packs/validate", dict(pack))
+
+    def dry_run_rule_pack(self, pack: Mapping[str, Any], events: list[Mapping[str, Any]]) -> Dict[str, Any]:
+        return self.request("POST", "/v1/admin/rule-packs/dry-run", {"pack": dict(pack), "events": [dict(event) for event in events]})
+
+    def publish_rule_pack(self, owner: str, name: str, version: str, pack: Mapping[str, Any]) -> Dict[str, Any]:
+        path = f"/v1/admin/rule-packs/{_segment(owner)}/{_segment(name)}/{_segment(version)}"
+        return self.request("POST", path, dict(pack))
+
+    def publish_model_profile(self, name: str, version: str, profile: Mapping[str, Any]) -> Dict[str, Any]:
+        path = f"/v1/admin/model-profiles/{_segment(name)}/{_segment(version)}"
+        return self.request("POST", path, dict(profile))
+
+    def get_model_profile(self, name: str, version: str) -> Dict[str, Any]:
+        path = f"/v1/admin/model-profiles/{_segment(name)}/{_segment(version)}"
+        return self.request("GET", path)
+
+    def stats(self) -> Dict[str, Any]:
+        return self.request("GET", "/v1/admin/stats")
+
+    def reindex_artifact(self, tenant_id: str, pipeline_id: str, session_id: str) -> Dict[str, Any]:
+        path = f"/v1/admin/artifacts/{_segment(tenant_id)}/{_segment(pipeline_id)}/{_segment(session_id)}/reindex"
+        return self.request("POST", path, {})
+
+    def reliability_summary(self) -> Dict[str, Any]:
+        return self.request("GET", "/v1/admin/reliability/summary")
+
+    def reliability_list(self, kind: str, *, cursor: Optional[str] = None, limit: int = 100) -> Dict[str, Any]:
+        if kind not in {"receipts", "outbox", "quarantine", "artifacts"}:
+            raise ValueError("unsupported reliability collection")
+        params = {"limit": min(max(limit, 1), 100)}
+        if cursor:
+            params["cursor"] = cursor
+        return self.request("GET", f"/v1/admin/reliability/{kind}?{urlencode(params)}")
+
+    def replay(self, body: Mapping[str, Any]) -> Dict[str, Any]:
+        return self.request("POST", "/v1/admin/reliability/replay", dict(body))
+
+    def reconcile(self, body: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
+        return self.request("POST", "/v1/admin/reliability/reconcile", dict(body or {}))

trazio_telemetry/integrations/__init__.py

@@ -0,0 +1,6 @@
+"""Helpers for established workflow and agent runtimes."""
+
+from .openinference import span_attributes
+from .temporal import temporal_attributes
+
+__all__ = ["span_attributes", "temporal_attributes"]

trazio_telemetry/integrations/openinference.py

@@ -0,0 +1,18 @@
+"""OpenInference-compatible attribute construction without a second tracer."""
+
+from typing import Any, Dict, Optional
+
+
+def span_attributes(
+    kind: str,
+    *,
+    input_value: Optional[Any] = None,
+    output_value: Optional[Any] = None,
+    **attributes: Any,
+) -> Dict[str, Any]:
+    values: Dict[str, Any] = {"openinference.span.kind": kind.upper(), **attributes}
+    if input_value is not None:
+        values["input.value"] = input_value
+    if output_value is not None:
+        values["output.value"] = output_value
+    return values

trazio_telemetry/integrations/temporal.py

@@ -0,0 +1,23 @@
+"""Correlation mapping for Temporal's native OpenTelemetry interceptor."""
+
+from typing import Any, Dict, Optional
+
+
+def temporal_attributes(
+    *,
+    workflow_id: str,
+    run_id: str,
+    workflow_type: Optional[str] = None,
+    task_queue: Optional[str] = None,
+    activity_id: Optional[str] = None,
+    attempt: Optional[int] = None,
+) -> Dict[str, Any]:
+    return {
+        "temporal.workflow.id": workflow_id,
+        "temporal.run.id": run_id,
+        "temporal.workflow.type": workflow_type,
+        "temporal.task_queue": task_queue,
+        "temporal.activity.id": activity_id,
+        "temporal.activity.attempt": attempt,
+        "run.id": run_id,
+    }

trazio_telemetry/semantic_query.py

@@ -0,0 +1,143 @@
+"""Versioned, scope-free semantic query plans with deterministic validation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Callable, Mapping
+
+SEVERITY_ORDER = ("info", "low", "medium", "high", "critical")
+SEVERITIES = set(SEVERITY_ORDER)
+TARGETS = {"events", "artifacts", "graph"}
+MODES = {"hybrid", "semantic", "lexical", "structured"}
+SOURCE_ALIASES = {
+    "kubernetes": "kubernetes.*", "k8s": "kubernetes.*", "otel": "otel.*",
+    "opentelemetry": "otel.*", "robot": "robot.*", "robotics": "robot.*",
+    "desktop": "desktop.*", "endpoint": "desktop.security", "argocd": "argocd", "mqtt": "mqtt",
+}
+
+
+def _unique(values: Any, *, allowed: set[str] | None = None, limit: int = 32) -> list[str]:
+    if values is None:
+        return []
+    if not isinstance(values, list):
+        raise ValueError("semantic query list fields must be arrays")
+    result = list(dict.fromkeys(str(value).strip() for value in values if str(value).strip()))[:limit]
+    if allowed and any(value not in allowed for value in result):
+        raise ValueError("semantic query contains an unsupported value")
+    return result
+
+
+def _timestamp(value: Any, name: str) -> str | None:
+    if value in (None, ""):
+        return None
+    try:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ValueError(f"{name} must be an ISO-8601 timestamp") from exc
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def deterministic_plan(question: str, *, now: datetime | None = None) -> dict[str, Any]:
+    question = str(question).strip()
+    if not question or len(question) > 4000:
+        raise ValueError("question must contain 1-4000 characters")
+    lower = question.lower()
+    targets = ["events"]
+    if re.search(r"\b(video|scene|recording|mcap|image|artifact|file)\b", lower):
+        targets.append("artifacts")
+    if re.search(r"\b(correlat|relationship|related|graph|trace|neighbor)\w*\b", lower):
+        targets.append("graph")
+    source_types = [source for alias, source in SOURCE_ALIASES.items() if re.search(rf"\b{re.escape(alias)}\b", lower)]
+    from_time = None
+    recent = re.search(r"\b(?:last|past)\s+(\d{1,4})\s*(minute|hour|day|week)s?\b", lower)
+    if recent:
+        units = {"minute": "minutes", "hour": "hours", "day": "days", "week": "weeks"}
+        current = now or datetime.now(timezone.utc)
+        from_time = (current - timedelta(**{units[recent.group(2)]: int(recent.group(1))})).isoformat().replace("+00:00", "Z")
+    return normalize_semantic_query({
+        "version": "1.0", "question": question, "mode": "hybrid", "targets": targets,
+        "filters": {
+            "source_types": list(dict.fromkeys(source_types)), "event_types": [],
+            "severities": [item for item in SEVERITY_ORDER if re.search(rf"\b{item}\b", lower)],
+            "from": from_time, "to": None,
+        },
+        "options": {"limit": 20, "max_scan": 300, "top_k": 10, "graph_hops": 1},
+        "planner": {"kind": "deterministic", "model": None},
+    })
+
+
+def normalize_semantic_query(value: Mapping[str, Any], *, question: str | None = None, planner: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ValueError("semantic query must be an object")
+    for forbidden in ("tenant_id", "pipeline_id", "base_url", "authorization", "token"):
+        if forbidden in value:
+            raise ValueError(f"semantic query cannot set {forbidden}")
+    actual_question = str(question or value.get("question") or "").strip()
+    if not actual_question or len(actual_question) > 4000:
+        raise ValueError("question must contain 1-4000 characters")
+    mode = str(value.get("mode") or "hybrid")
+    if mode not in MODES:
+        raise ValueError("unsupported semantic query mode")
+    filters = value.get("filters") if isinstance(value.get("filters"), Mapping) else {}
+    options = value.get("options") if isinstance(value.get("options"), Mapping) else {}
+    from_time, to_time = _timestamp(filters.get("from"), "filters.from"), _timestamp(filters.get("to"), "filters.to")
+    if from_time and to_time and from_time > to_time:
+        raise ValueError("filters.from must not be after filters.to")
+    source = planner or (value.get("planner") if isinstance(value.get("planner"), Mapping) else {})
+    result = {
+        "version": "1.0", "question": actual_question, "mode": mode,
+        "targets": _unique(value.get("targets") or ["events"], allowed=TARGETS, limit=3),
+        "filters": {
+            "source_types": _unique(filters.get("source_types"), limit=20),
+            "event_types": _unique(filters.get("event_types"), limit=20),
+            "severities": _unique(filters.get("severities"), allowed=SEVERITIES, limit=5),
+            "keywords": _unique(filters.get("keywords"), limit=32),
+            **{key: (str(filters[key])[:limit] if filters.get(key) else None) for key, limit in {
+                "device_id": 200, "run_id": 300, "session_id": 200, "relationship": 100, "rule_id": 200,
+            }.items()},
+            "from": from_time, "to": to_time,
+        },
+        "options": {
+            "limit": min(max(int(options.get("limit") or 20), 1), 100),
+            "max_scan": min(max(int(options.get("max_scan") or 300), 1), 500),
+            "top_k": min(max(int(options.get("top_k") or 10), 1), 50),
+            "graph_hops": min(max(int(options.get("graph_hops") or 1), 0), 3),
+        },
+        "planner": {"kind": str(source.get("kind") or "deterministic"), "model": source.get("model")},
+    }
+    result["plan_hash"] = hashlib.sha256(json.dumps(result, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+    return result
+
+
+@dataclass
+class DeterministicSemanticPlanner:
+    def plan(self, question: str) -> dict[str, Any]:
+        return deterministic_plan(question)
+
+
+@dataclass
+class ModelSemanticPlanner:
+    generate_object: Callable[[dict[str, Any]], Mapping[str, Any]]
+    model: str = "unspecified"
+    fallback: Any = None
+
+    def plan(self, question: str) -> dict[str, Any]:
+        try:
+            candidate = self.generate_object({
+                "question": question, "contract": "semantic-query-plan/1.0",
+                "allowed_targets": sorted(TARGETS), "allowed_modes": sorted(MODES),
+                "allowed_severities": sorted(SEVERITIES),
+                "instruction": "Return only a query plan; never include tenant, pipeline, URL, token, SQL, or authorization fields.",
+            })
+            return normalize_semantic_query(candidate, question=question, planner={"kind": "model", "model": self.model})
+        except Exception as exc:
+            plan = (self.fallback or DeterministicSemanticPlanner()).plan(question)
+            plan = normalize_semantic_query(plan, question=question, planner={"kind": "deterministic_fallback", "model": self.model})
+            plan["planner_error"] = type(exc).__name__
+            return plan

trazio_telemetry-0.3.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: trazio-telemetry
+Version: 0.3.0
+Summary: Scoped telemetry, artifact, investigation, and semantic-query SDK
+Author-email: Trazio <vc@hyperlake.cloud>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://hyperlake.cloud
+Project-URL: Documentation, https://hyperlake.cloud/docs
+Project-URL: Repository, https://github.com/cerebrixos-org/sovereign-telemetry-platform
+Keywords: opentelemetry,otlp,openinference,agents,temporal,langflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: certifi>=2024.2.2
+Provides-Extra: temporal
+Requires-Dist: temporalio[opentelemetry]>=1.20; extra == "temporal"
+Provides-Extra: langflow
+Requires-Dist: langflow>=1.6; extra == "langflow"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.30; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30; extra == "otel"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+
+# Trazio Telemetry SDK for Python
+
+Version 0.3.0 renames the package from `hyperlake-telemetry`; the API is unchanged.
+See [SDK integration and release status](https://github.com/cerebrixos-org/sovereign-telemetry-platform/blob/main/sovereign-telemetry-platform/sdk/README.md).
+
+`trazio-telemetry` sends standards-compatible OTLP/HTTP JSON, attaches
+events and immutable artifacts, manages tenant-editable settings, and performs
+scoped event, artifact, video, Run, and evidence-graph investigations. It does not replace the
+OpenTelemetry SDK: applications with existing instrumentation should continue
+using their normal exporter and use this package only for run context, stable
+event identity, evaluations, and artifact attachment.
+
+```bash
+pip install trazio-telemetry
+```
+
+```python
+from trazio_telemetry import Client, Privacy
+
+client = Client(
+    base_url="https://us.hyperlake.cloud",
+    protocol_token="write-only-protocol-token",
+    tenant_jwt="short-lived-jwks-jwt",
+    privacy=Privacy(capture_content=False),
+)
+
+with client.run("invoice-agent", goal_id="goal-42") as run:
+    with run.span("lookup-account", kind="RETRIEVER"):
+        pass
+    run.evaluate("groundedness", score=0.97, label="pass")
+
+client.flush()
+
+result = client.semantic_query(
+    "Show critical robot video and related faults from the last 2 hours"
+)
+
+detection = client.analyze_live_frame(
+    "./frame.jpg",
+    stream_session_id="camera-session-17",
+    frame_id="frame-42",
+    device_id="robot-17",
+)
+```
+
+`analyze_live_frame()` uses the immutable model profile pinned to the JWT's
+pipeline. It requires a short-lived JWT with `live:analyze` and `event:ingest`.
+The response is a factual object-detection result; the attached live Rule Packs
+determine whether it becomes an alert or notification.
+
+The JWT determines tenant and pipeline routing. Explicit routing IDs are
+optional with a JWT and are rejected when they conflict with its claims. Local
+claim decoding is not signature verification; the regional service verifies
+signature, issuer, audience, expiry, permissions, tenant, and pipeline for every
+request.
+Prompt, response, tool argument, and tool result content is suppressed by
+default. Set `capture_content=True` only after applying an approved data policy.
+
+See the repository integration guides for Temporal, Langflow, OpenInference,
+Collector, and Alloy examples.
+
+## Reliable semantic queries
+
+`semantic_query()` creates and validates a versioned, bounded query plan before
+calling any endpoint. Plans may target event retrieval, artifact/vector search,
+and evidence-graph traversal, but cannot contain tenant, pipeline, URL, token,
+SQL, or authorization fields. Every response includes the plan hash and scope
+provenance.
+
+`DeterministicSemanticPlanner` works without an LLM. `ModelSemanticPlanner`
+accepts any callable that returns a JSON-like object; unsafe or invalid model
+output falls back to the deterministic plan. A model therefore interprets user
+intent but cannot expand authorization or execute arbitrary queries.
+
+Artifact and video retrieval uses configured vector embeddings. Event retrieval
+is bounded structured/lexical retrieval, while graph results come from recorded
+scoped evidence edges. These signals remain separate and similarity is not
+treated as causation.
+
+The client also exposes event listing/search, artifact search/upload/download,
+typed telemetry, video playback/timeline, Runs, evidence graphs, tenant config,
+protocol-token rotation, and Rule Pack validate/dry-run/publish helpers.

trazio_telemetry-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+hyperlake_telemetry/__init__.py,sha256=SdQYQa525QhPCqWD3ywwhjebsVjg4d7SJDnBH_vy3SQ,749
+trazio_telemetry/__init__.py,sha256=qAjZeJg9D2hNagXGuwb0y7Nokv8CChuLIgjTZ08zh9Q,508
+trazio_telemetry/client.py,sha256=x-tH7MTR-bShoq6mrcMRTQm4QUiRjX3nKvpuruT_fs8,38704
+trazio_telemetry/semantic_query.py,sha256=m94KduI5oznQSysfhyI1v_GOp98FkGe8-yTB5-hxv8I,7178
+trazio_telemetry/integrations/__init__.py,sha256=FXPNdoH9stxeM6DWlSEHfOjtg6ZWUsDRFJhR4pgsXN4,199
+trazio_telemetry/integrations/openinference.py,sha256=KEfWjFBhd56BtH_jLiAZqJ9n0U3s8it8WDqQx0Fr8mc,545
+trazio_telemetry/integrations/temporal.py,sha256=bPP9m-TE9LPE0ay-U9VNPOboe5OPCB49UqIv0DO4EvU,670
+trazio_telemetry-0.3.0.dist-info/METADATA,sha256=HfWPNfKJl6FSBmidgoKbS62s1SuRKa-wVJ2nBxFWDr8,4858
+trazio_telemetry-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+trazio_telemetry-0.3.0.dist-info/top_level.txt,sha256=Fu_LSWQvNm83gwFuHzsN-oGSpS6CPeBBTt4_ZyN-Z6o,37
+trazio_telemetry-0.3.0.dist-info/RECORD,,

trazio_telemetry-0.3.0.dist-info/WHEEL

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

trazio_telemetry-0.3.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+hyperlake_telemetry
+trazio_telemetry