turingpulse-sdk 1.0.0__py3-none-any.whl

turingpulse_sdk/__init__.py

@@ -0,0 +1,44 @@
+"""TuringPulse SDK public interface."""
+
+from .config import TuringPulseConfig, GovernanceDefaults, FingerprintConfig
+from .context import current_context
+from .decorators import instrument
+from .deploy import DeployInfo, register_deploy
+from .exceptions import ConfigurationError, GovernanceBlockedError
+from .governance import GovernanceDirective
+from .kpi import KPIConfig, KPIResult
+from .attachments import AttachmentManager
+from .plugin import TuringPulsePlugin, get_plugin, init
+from .client import PolicyCheckResult
+
+__all__ = [
+    # Config
+    "TuringPulseConfig",
+    "GovernanceDefaults",
+    "FingerprintConfig",
+    # Plugin
+    "TuringPulsePlugin",
+    "init",
+    "get_plugin",
+    # Decorators
+    "instrument",
+    # Governance
+    "GovernanceDirective",
+    "GovernanceBlockedError",
+    # Exceptions
+    "ConfigurationError",
+    # KPIs
+    "KPIConfig",
+    "KPIResult",
+    # Deploy Tracking
+    "register_deploy",
+    "DeployInfo",
+    # Context
+    "current_context",
+    # Policy Check
+    "PolicyCheckResult",
+    # Attachments
+    "AttachmentManager",
+    # Framework integrations (lazy-loaded)
+    "integrations",
+]

turingpulse_sdk/attachments.py

@@ -0,0 +1,176 @@
+"""Document attachment support for the TuringPulse Python SDK.
+
+Provides ``attach_document``, ``attach_bytes``, and ``attach_text_file``
+which upload files to the ingestion service and inject attachment metadata
+into the current span's event payload.
+
+Design principle: NEVER crash customer code.  All upload failures are logged
+and silently ignored — the span completes normally without the attachment.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from .client import TuringPulseHttpClient
+
+logger = logging.getLogger("turingpulse.sdk.attachments")
+
+_CONTROL_CHAR_RE = None
+
+_global_pending: List[Dict[str, Any]] = []
+
+
+def _validate_file_path(file_path: str) -> str:
+    """Resolve and validate a file path to prevent path-traversal attacks.
+
+    Rejects paths that resolve outside the original directory intent
+    (e.g. ``../../etc/passwd``) and non-regular files.
+    """
+    resolved = os.path.realpath(os.path.normpath(file_path))
+    if not os.path.isfile(resolved):
+        raise ValueError(f"Not a regular file: {file_path}")
+    return resolved
+
+
+def _sanitize_filename(filename: str) -> str:
+    """Strip path components and control characters from a filename."""
+    import re
+    global _CONTROL_CHAR_RE
+    if _CONTROL_CHAR_RE is None:
+        _CONTROL_CHAR_RE = re.compile(r"[\x00-\x1f\x7f]")
+    name = os.path.basename(filename)
+    name = _CONTROL_CHAR_RE.sub("", name)
+    return name[:255] if name else "attachment"
+
+
+def drain_global_pending() -> List[Dict[str, Any]]:
+    """Return and clear module-level pending attachments."""
+    items = list(_global_pending)
+    _global_pending.clear()
+    return items
+
+
+class AttachmentManager:
+    """Manages document uploads and metadata injection.
+
+    Uploaded attachments are automatically injected into the current
+    ``ExecutionContext`` when one is active.  Attachments uploaded outside
+    a span are stored in ``pending_attachments`` so the next root span
+    can pick them up.
+    """
+
+    def __init__(self, http_client: "TuringPulseHttpClient", enabled: bool = True) -> None:
+        self._http = http_client
+        self._enabled = enabled
+        self.pending_attachments: List[Dict[str, Any]] = []
+
+    def attach_document(
+        self,
+        file_path: str,
+        direction: str = "input",
+        mime_type: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Upload a document from a file path.
+
+        Returns attachment metadata dict on success, None on failure.
+        """
+        if not self._enabled:
+            return None
+        try:
+            validated_path = _validate_file_path(file_path)
+            filename = _sanitize_filename(validated_path)
+            with open(validated_path, "rb") as f:
+                data = f.read()
+            return self._upload(data, filename, direction, mime_type)
+        except Exception:
+            logger.warning("Failed to attach document: %s", type(file_path).__name__)
+            return None
+
+    def attach_bytes(
+        self,
+        data: bytes,
+        filename: str,
+        direction: str = "input",
+        mime_type: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Upload raw bytes as an attachment."""
+        if not self._enabled:
+            return None
+        try:
+            return self._upload(data, _sanitize_filename(filename), direction, mime_type)
+        except Exception as exc:
+            logger.warning("Failed to attach bytes: %s", type(exc).__name__)
+            return None
+
+    def attach_text_file(
+        self,
+        text: str,
+        filename: str = "document.txt",
+        direction: str = "input",
+    ) -> Optional[Dict[str, Any]]:
+        """Upload a string as a text attachment."""
+        return self.attach_bytes(
+            text.encode("utf-8"),
+            filename,
+            direction,
+            mime_type="text/plain",
+        )
+
+    def _upload(
+        self,
+        data: bytes,
+        filename: str,
+        direction: str,
+        mime_type: Optional[str],
+    ) -> Optional[Dict[str, Any]]:
+        """Core upload via the HTTP client's multipart upload.
+
+        If an ``ExecutionContext`` is active the metadata is injected into
+        ``ctx.attachments`` automatically.  Otherwise it is stored in
+        ``pending_attachments`` for later injection by the plugin.
+        """
+        try:
+            result = self._http.upload_attachment(
+                data=data,
+                filename=filename,
+                direction=direction,
+                mime_type=mime_type,
+            )
+            if result:
+                meta = {
+                    "attachment_id": result.get("attachment_id"),
+                    "filename": result.get("filename"),
+                    "mime_type": result.get("mime_type"),
+                    "size_bytes": result.get("size_bytes"),
+                    "storage_path": result.get("storage_path"),
+                    "direction": direction,
+                    "deduplicated": result.get("deduplicated", False),
+                }
+                self._inject_into_context(meta)
+                return meta
+        except Exception as exc:
+            logger.warning("Attachment upload failed: %s", type(exc).__name__)
+        return None
+
+    def _inject_into_context(self, meta: Dict[str, Any]) -> None:
+        """Push attachment metadata into the active span or the global pending list."""
+        try:
+            from .context import current_context
+            ctx = current_context()
+            if ctx is not None:
+                ctx.attachments.append(meta)
+                return
+        except Exception:
+            pass
+        self.pending_attachments.append(meta)
+        _global_pending.append(meta)
+
+    def drain_pending(self) -> List[Dict[str, Any]]:
+        """Return and clear any attachments uploaded outside a span."""
+        items = list(self.pending_attachments)
+        self.pending_attachments.clear()
+        return items

turingpulse_sdk/client.py

@@ -0,0 +1,435 @@
+"""HTTP client utilities for TuringPulse services.
+
+All outbound HTTP from the SDK flows through ``TuringPulseHttpClient``.
+Authentication is done exclusively via the ``X-API-Key`` header — the
+backend resolves tenant_id and project_id from the key.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, Optional, Sequence
+
+import re
+
+import httpx
+from turingpulse_interfaces import AgentEvent
+
+from .config import TuringPulseConfig
+
+logger = logging.getLogger("turingpulse.sdk.client")
+
+SDK_LANGUAGE = "python"
+MAX_PAYLOAD_BYTES = 5 * 1024 * 1024  # 5 MB
+_SAFE_PATH_SEGMENT = re.compile(r"^[a-zA-Z0-9_\-]+$")
+
+
+def _sdk_version() -> str:
+    try:
+        from importlib.metadata import version
+        return version("turingpulse-sdk")
+    except Exception:
+        return "0.1.0"
+
+
+SDK_VERSION = _sdk_version()
+
+
+def _sanitize_headers(headers: Dict[str, str]) -> Dict[str, str]:
+    """Return a copy of headers with sensitive values redacted for safe logging."""
+    sensitive = {"x-api-key", "authorization"}
+    return {k: ("***" if k.lower() in sensitive else v) for k, v in headers.items()}
+
+
+class TuringPulseHttpClient:
+    """Centralised HTTP client for all SDK -> backend communication."""
+
+    def __init__(self, config: TuringPulseConfig):
+        self._config = config
+        self._base_url = config.endpoint.rstrip("/")
+        limits = httpx.Limits(max_keepalive_connections=10, max_connections=20, keepalive_expiry=30)
+        self._sync = httpx.Client(timeout=config.timeout_seconds, limits=limits)
+        self._async = httpx.AsyncClient(timeout=config.timeout_seconds, limits=limits)
+
+    def close(self) -> None:
+        """Close both sync and async HTTP clients."""
+        self._sync.close()
+        try:
+            import asyncio
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(self._async.aclose())
+            except RuntimeError:
+                asyncio.run(self._async.aclose())
+        except Exception as exc:
+            logger.debug("Failed to close async HTTP client: %s", type(exc).__name__)
+
+    async def aclose(self) -> None:
+        """Close both async and sync HTTP clients."""
+        self._sync.close()
+        await self._async.aclose()
+
+    # ------------------------------------------------------------------
+    # Event emission
+    # ------------------------------------------------------------------
+
+    def emit_events(self, events: Sequence[AgentEvent]) -> None:
+        if not events:
+            return
+        self.emit_serialized_payload(self.serialize_events(events))
+
+    async def emit_events_async(self, events: Sequence[AgentEvent]) -> None:
+        if not events:
+            return
+        await self.emit_serialized_payload_async(self.serialize_events(events))
+
+    def serialize_events(self, events: Sequence[AgentEvent]) -> Dict[str, Any]:
+        return {"events": [event.model_dump(mode="json") for event in events]}
+
+    def emit_serialized_payload(self, payload: Dict[str, Any]) -> None:
+        payload = self._enforce_payload_limit(payload)
+        result = self._post(f"{self._base_url}/api/v1/sdk/events", payload)
+        self._check_batch_result(result, payload)
+
+    async def emit_serialized_payload_async(self, payload: Dict[str, Any]) -> None:
+        payload = self._enforce_payload_limit(payload)
+        result = await self._apost(f"{self._base_url}/api/v1/sdk/events", payload)
+        self._check_batch_result(result, payload)
+
+    def _check_batch_result(self, result: Any, payload: Dict[str, Any]) -> None:
+        """Warn if the backend accepted the HTTP request but failed to process events."""
+        if not isinstance(result, dict):
+            return
+        if result.get("success") is False:
+            failed = result.get("failed", 0)
+            total = result.get("total", len(payload.get("events", [])))
+            logger.warning(
+                "Backend accepted request but failed to process %d/%d events "
+                "(Kafka/pipeline may be down)",
+                failed,
+                total,
+            )
+
+    @staticmethod
+    def _enforce_payload_limit(payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Drop events from the tail until the payload fits within MAX_PAYLOAD_BYTES.
+
+        Returns a new dict if truncation is needed — never mutates the input.
+        """
+        import json as _json
+        serialized = _json.dumps(payload)
+        if len(serialized) <= MAX_PAYLOAD_BYTES:
+            return payload
+        events = payload.get("events", [])
+        if not events:
+            logger.warning("Non-event payload exceeds %d bytes, sending truncated", MAX_PAYLOAD_BYTES)
+            return payload
+        overhead = len(serialized) - len(_json.dumps(events))
+        avg_per_event = max(1, (len(serialized) - overhead) // len(events))
+        target_count = max(1, (MAX_PAYLOAD_BYTES - overhead) // avg_per_event)
+        if target_count < len(events):
+            truncated = events[:target_count]
+            logger.warning("Payload exceeded %d bytes, truncated to %d events", MAX_PAYLOAD_BYTES, len(truncated))
+            return {**payload, "events": truncated}
+        logger.warning("Payload exceeded %d bytes, truncated to %d events", MAX_PAYLOAD_BYTES, len(events))
+        return payload
+
+    # ------------------------------------------------------------------
+    # Task / HITL helpers
+    # ------------------------------------------------------------------
+
+    def create_task(self, payload: Dict[str, Any]) -> Optional[str]:
+        url = f"{self._base_url}/api/v1/tasks"
+        response = self._post(url, payload)
+        if isinstance(response, dict):
+            return response.get("task_id") or payload.get("task_id")
+        return payload.get("task_id")
+
+    def add_hitl_action(self, task_id: str, payload: Dict[str, Any]) -> None:
+        if not _SAFE_PATH_SEGMENT.match(task_id):
+            logger.warning("Invalid task_id rejected (possible path traversal): %s", type(task_id).__name__)
+            return
+        self._post(f"{self._base_url}/api/v1/tasks/{task_id}/hitl", payload)
+
+    # ------------------------------------------------------------------
+    # Fingerprint / deploy / custom-change helpers
+    # ------------------------------------------------------------------
+
+    def post_fingerprint(self, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        return self._post(f"{self._base_url}/api/v1/fingerprints", payload)
+
+    def post_deploy(self, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        return self._post(f"{self._base_url}/api/v1/deploys", payload)
+
+    def post_custom_change(self, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        return self._post(f"{self._base_url}/api/v1/changes", payload)
+
+    # ------------------------------------------------------------------
+    # Headers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        headers: Dict[str, str] = {
+            "Content-Type": "application/json",
+            "X-SDK-Version": SDK_VERSION,
+            "X-SDK-Language": SDK_LANGUAGE,
+        }
+        if self._config.api_key:
+            headers["X-API-Key"] = self._config.api_key
+        return headers
+
+    # ------------------------------------------------------------------
+    # Core POST with retries — shared response handling
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _handle_response(response: httpx.Response, url: str) -> Any:
+        """Process an httpx response — shared by sync and async paths."""
+        if response.status_code == 402:
+            TuringPulseHttpClient._log_quota_exceeded(response)
+            response.raise_for_status()
+        if response.status_code == 403:
+            logger.warning("TuringPulse 403 Forbidden: %s", url)
+        response.raise_for_status()
+        if not response.content:
+            return None
+        content_type = response.headers.get("content-type", "")
+        if "application/json" in content_type:
+            return response.json()
+        return None
+
+    @staticmethod
+    def _is_terminal_status(status_code: int) -> bool:
+        return status_code in (401, 402, 403, 404)
+
+    def _backoff(self, attempt: int, retry_after: float | None = None) -> float:
+        default = min(self._config.retry_backoff_base * (attempt + 1), self._config.retry_backoff_max)
+        if retry_after is not None and retry_after > 0:
+            return min(retry_after, self._config.retry_backoff_max)
+        return default
+
+    @staticmethod
+    def _parse_retry_after(response: httpx.Response) -> float | None:
+        header = response.headers.get("retry-after")
+        if header is None:
+            return None
+        try:
+            return float(header)
+        except (ValueError, TypeError):
+            return None
+
+    def _post(self, url: str, json_payload: Dict[str, Any]) -> Any:
+        last_exc: Exception | None = None
+        headers = self._headers()
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._sync.post(url, json=json_payload, headers=headers)
+                return self._handle_response(response, url)
+            except httpx.HTTPStatusError as exc:
+                if self._is_terminal_status(exc.response.status_code):
+                    raise
+                last_exc = exc
+                retry_after = self._parse_retry_after(exc.response)
+                time.sleep(self._backoff(attempt, retry_after))
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                time.sleep(self._backoff(attempt))
+        if last_exc:
+            logger.warning("TuringPulse request failed after retries: %s", type(last_exc).__name__)
+            raise last_exc
+        return None
+
+    async def _apost(self, url: str, json_payload: Dict[str, Any]) -> Any:
+        last_exc: Exception | None = None
+        headers = self._headers()
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._async.post(url, json=json_payload, headers=headers)
+                return self._handle_response(response, url)
+            except httpx.HTTPStatusError as exc:
+                if self._is_terminal_status(exc.response.status_code):
+                    raise
+                last_exc = exc
+                retry_after = self._parse_retry_after(exc.response)
+                await _async_sleep(self._backoff(attempt, retry_after))
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                await _async_sleep(self._backoff(attempt))
+        if last_exc:
+            logger.warning("TuringPulse async request failed after retries: %s", type(last_exc).__name__)
+            raise last_exc
+        return None
+
+    # ------------------------------------------------------------------
+    # Policy check — same pattern, unified payload builder
+    # ------------------------------------------------------------------
+
+    def _build_policy_payload(self, **kwargs: Any) -> Dict[str, Any]:
+        """Build and clean the policy check payload, auto-populating context fields.
+
+        Applies size caps to text fields to prevent oversized payloads
+        and strips None values.
+        """
+        span_id = kwargs.get("span_id")
+        node_type = kwargs.get("node_type")
+        if span_id is None or node_type is None:
+            try:
+                from .context import current_context
+                ctx = current_context()
+                if ctx:
+                    span_id = span_id or getattr(ctx, "span_id", None)
+                    node_type = node_type or getattr(ctx, "node_type", None)
+            except Exception:
+                pass
+            kwargs["span_id"] = span_id
+            kwargs["node_type"] = node_type
+
+        text_cap = 10_000
+        for key in ("output_text", "input_text"):
+            val = kwargs.get(key)
+            if isinstance(val, str) and len(val) > text_cap:
+                kwargs[key] = val[:text_cap]
+
+        return {k: v for k, v in kwargs.items() if v is not None}
+
+    def _policy_check_url_and_timeout(self):
+        url = f"{self._base_url}/api/v1/hitl/policy/check"
+        total = self._config.policy_check_timeout
+        timeout = httpx.Timeout(total, connect=min(0.5, total / 2))
+        return url, self._headers(), timeout
+
+    @staticmethod
+    def _parse_policy_response(data: Dict[str, Any]) -> "PolicyCheckResult":
+        return PolicyCheckResult(
+            action=data.get("action", "allow"),
+            triggered=data.get("triggered", False),
+            reason=data.get("reason"),
+            policy_ids=data.get("policy_ids", []),
+        )
+
+    @staticmethod
+    def _policy_check_fallback(e: Exception) -> "PolicyCheckResult":
+        safe_msg = type(e).__name__
+        logger.warning("Policy check failed (fail-open): %s", safe_msg)
+        return PolicyCheckResult(action="flag", triggered=True, reason=f"check_error: {safe_msg}")
+
+    def policy_check(self, **kwargs: Any) -> "PolicyCheckResult":
+        """Synchronous policy check. Fail-open on infrastructure failures."""
+        payload = self._build_policy_payload(**kwargs)
+        url, headers, timeout = self._policy_check_url_and_timeout()
+        try:
+            response = self._sync.post(url, json=payload, headers=headers, timeout=timeout)
+            response.raise_for_status()
+            return self._parse_policy_response(response.json())
+        except Exception as e:
+            return self._policy_check_fallback(e)
+
+    async def policy_check_async(self, **kwargs: Any) -> "PolicyCheckResult":
+        """Async policy check. Fail-open on infrastructure failures."""
+        payload = self._build_policy_payload(**kwargs)
+        url, headers, timeout = self._policy_check_url_and_timeout()
+        try:
+            response = await self._async.post(url, json=payload, headers=headers, timeout=timeout)
+            response.raise_for_status()
+            return self._parse_policy_response(response.json())
+        except Exception as e:
+            return self._policy_check_fallback(e)
+
+    # ------------------------------------------------------------------
+    # Attachment upload (multipart/form-data)
+    # ------------------------------------------------------------------
+
+    def _upload_headers(self) -> Dict[str, str]:
+        """Headers for multipart uploads (no Content-Type — httpx sets it)."""
+        headers: Dict[str, str] = {
+            "X-SDK-Version": SDK_VERSION,
+            "X-SDK-Language": SDK_LANGUAGE,
+        }
+        if self._config.api_key:
+            headers["X-API-Key"] = self._config.api_key
+        return headers
+
+    def upload_attachment(
+        self,
+        data: bytes,
+        filename: str,
+        direction: str = "input",
+        mime_type: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Upload a document attachment via multipart/form-data."""
+        url = f"{self._base_url}/api/v1/attachments"
+        effective_mime = mime_type or "application/octet-stream"
+        files = {"file": (filename, data, effective_mime)}
+        form_data = {"direction": direction}
+        try:
+            response = self._sync.post(url, headers=self._upload_headers(), files=files, data=form_data)
+            response.raise_for_status()
+            content_type = response.headers.get("content-type", "")
+            if "application/json" in content_type:
+                return response.json()
+            return None
+        except Exception as exc:
+            logger.warning("Attachment upload failed: %s", type(exc).__name__)
+            return None
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _log_quota_exceeded(response: httpx.Response) -> None:
+        try:
+            error_data = response.json()
+            detail = error_data.get("detail", {})
+            if isinstance(detail, dict):
+                logger.warning(
+                    "TuringPulse quota exceeded: resource=%s, current=%d, limit=%d",
+                    detail.get("resource", "unknown"),
+                    detail.get("current", 0),
+                    detail.get("limit", 0),
+                )
+        except (ValueError, KeyError):
+            logger.warning("TuringPulse quota exceeded (HTTP %d)", response.status_code)
+
+
+class PolicyCheckResult:
+    """Result of a policy check."""
+
+    __slots__ = ("action", "triggered", "reason", "policy_ids")
+
+    def __init__(
+        self,
+        action: str = "allow",
+        triggered: bool = False,
+        reason: Optional[str] = None,
+        policy_ids: Optional[list] = None,
+    ):
+        self.action = action
+        self.triggered = triggered
+        self.reason = reason
+        self.policy_ids = policy_ids or []
+
+    @property
+    def allowed(self) -> bool:
+        return self.action == "allow"
+
+    @property
+    def blocked(self) -> bool:
+        return self.action == "block"
+
+    @property
+    def flagged(self) -> bool:
+        return self.action == "flag"
+
+    def __repr__(self) -> str:
+        return f"PolicyCheckResult(action={self.action!r}, triggered={self.triggered})"
+
+
+async def _async_sleep(delay: float) -> None:
+    try:
+        import anyio
+        await anyio.sleep(delay)
+    except ModuleNotFoundError:
+        import asyncio
+        await asyncio.sleep(delay)