akhu-observer 0.1.0__py3-none-any.whl

akhu_observer/__init__.py

@@ -0,0 +1,46 @@
+"""
+akhu-observer — Public API
+
+This is the only entry point. Everything exported here IS the SDK.
+Everything not exported here is internal implementation detail.
+"""
+
+from __future__ import annotations
+
+from .client import AkhuClient
+from .wrappers.openai import observe_openai
+from .wrappers.anthropic import observe_anthropic
+from ._constants import CHANNEL_ID_RE
+from ._types import (
+    ErrorCallback,
+    FlushCallback,
+    HealthStatus,
+    IngestResult,
+    IngestResponse,
+    BatchIngestData,
+    BatchIngestResponse,
+    ChannelHealth,
+    ChannelInfo,
+)
+
+__all__ = [
+    # Core
+    "AkhuClient",
+    # Wrappers
+    "observe_openai",
+    "observe_anthropic",
+    # Constants
+    "CHANNEL_ID_RE",
+    # Types
+    "ErrorCallback",
+    "FlushCallback",
+    "HealthStatus",
+    "IngestResult",
+    "IngestResponse",
+    "BatchIngestData",
+    "BatchIngestResponse",
+    "ChannelHealth",
+    "ChannelInfo",
+]
+
+__version__ = "0.1.0"

akhu_observer/_constants.py

@@ -0,0 +1,91 @@
+"""
+akhu-observer — Frozen constants
+
+These values define the SDK's behavior at compile time.
+Change here = contract change. Think before you touch.
+"""
+
+from __future__ import annotations
+
+import re
+
+# ---------------------------------------------------------------------------
+# API
+# ---------------------------------------------------------------------------
+
+API_PREFIX = "/api/v1"
+
+# ---------------------------------------------------------------------------
+# Defaults
+# ---------------------------------------------------------------------------
+
+DEFAULT_TIMEOUT_S: float = 5.0
+DEFAULT_MAX_RETRIES: int = 3
+DEFAULT_BUFFER_SIZE: int = 1
+DEFAULT_FLUSH_INTERVAL_S: float = 0.2
+
+# ---------------------------------------------------------------------------
+# Validation boundaries
+# ---------------------------------------------------------------------------
+
+MIN_BUFFER_SIZE: int = 1
+MIN_FLUSH_INTERVAL_S: float = 0.05   # 50ms
+MIN_TIMEOUT_S: float = 0.1           # 100ms
+MIN_MAX_RETRIES: int = 0
+
+# ---------------------------------------------------------------------------
+# Server limits
+# ---------------------------------------------------------------------------
+
+MAX_BATCH_SIZE: int = 5_000
+
+# ---------------------------------------------------------------------------
+# Channel ID
+# ---------------------------------------------------------------------------
+
+CHANNEL_ID_RE: re.Pattern[str] = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$")
+
+# ---------------------------------------------------------------------------
+# Environment variables
+# ---------------------------------------------------------------------------
+
+ENV_URL = "AKHU_URL"
+ENV_CHANNEL_ID = "AKHU_CHANNEL_ID"
+ENV_CHANNEL_NAME = "AKHU_CHANNEL_NAME"
+ENV_CAPTURE_CONTENT = "AKHU_CAPTURE_CONTENT"
+
+# ---------------------------------------------------------------------------
+# HTTP
+# ---------------------------------------------------------------------------
+
+MAX_RESPONSE_SIZE: int = 1_048_576  # 1MB
+
+# ---------------------------------------------------------------------------
+# Adapter identifiers
+# ---------------------------------------------------------------------------
+
+DEFAULT_ADAPTER = "akhu-observer-python"
+OPENAI_ADAPTER = "akhu-observer-openai"
+ANTHROPIC_ADAPTER = "akhu-observer-anthropic"
+
+# ---------------------------------------------------------------------------
+# Default channel IDs per wrapper
+# ---------------------------------------------------------------------------
+
+OPENAI_DEFAULT_CHANNEL_ID = "python-openai"
+ANTHROPIC_DEFAULT_CHANNEL_ID = "python-anthropic"
+
+# ---------------------------------------------------------------------------
+# Retry
+# ---------------------------------------------------------------------------
+
+BACKOFF_BASE_S: float = 0.1    # 100ms
+BACKOFF_CAP_S: float = 10.0    # 10s
+MAX_RETRY_AFTER_S: float = 3600.0  # 1 hour
+
+# ---------------------------------------------------------------------------
+# Redaction
+# ---------------------------------------------------------------------------
+
+MAX_REDACTION_DEPTH: int = 20
+MAX_STRING_LENGTH: int = 10_000

akhu_observer/_http.py

@@ -0,0 +1,166 @@
+"""
+akhu-observer — HTTP transport layer
+
+Uses Python stdlib http.client. Zero external dependencies.
+This is deliberate — the observer SDK must not pull in requests, httpx,
+or any other HTTP library that adds attack surface and dependency risk.
+
+Connection reuse: http.client.HTTP(S)Connection supports keepalive.
+We maintain a single persistent connection per HttpTransport instance.
+If the connection drops, we reconnect transparently (one retry).
+
+Timeout: Hard timeout on the socket level. If AKHU doesn't respond
+within timeout_s, the connection is destroyed. The observed system
+must never wait for us.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import ssl
+from typing import Any
+from urllib.parse import urlparse
+
+from ._constants import MAX_RESPONSE_SIZE
+
+# ---------------------------------------------------------------------------
+# Transport
+# ---------------------------------------------------------------------------
+
+
+class HttpTransport:
+    """Minimal HTTP client for AKHU API communication.
+
+    One instance per AkhuClient. Holds a persistent connection.
+    Thread-safe for sequential use (flush lock in client prevents concurrent sends).
+    """
+
+    __slots__ = ("_scheme", "_host", "_port", "_is_https", "_conn", "_destroyed")
+
+    def __init__(self, base_url: str) -> None:
+        parsed = urlparse(base_url)
+        self._scheme = parsed.scheme
+        self._host = parsed.hostname or "localhost"
+        self._port = parsed.port or (443 if self._scheme == "https" else 80)
+        self._is_https = self._scheme == "https"
+        self._conn: http.client.HTTPConnection | http.client.HTTPSConnection | None = None
+        self._destroyed = False
+
+    # ----- Public API -----
+
+    def send(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: Any = None,
+        headers: dict[str, str] | None = None,
+        timeout_s: float = 5.0,
+    ) -> dict[str, Any]:
+        """Send an HTTP request and return parsed response.
+
+        Returns dict with keys: status (int), headers (dict), body (Any).
+        Raises ConnectionError on network failure.
+        """
+        if self._destroyed:
+            raise RuntimeError("HttpTransport has been destroyed")
+
+        all_headers: dict[str, str] = {"Content-Type": "application/json"}
+        if headers:
+            all_headers.update(headers)
+
+        encoded_body: bytes | None = None
+        if body is not None:
+            encoded_body = json.dumps(body).encode("utf-8")
+            all_headers["Content-Length"] = str(len(encoded_body))
+
+        # Try with existing connection; retry once on connection drops.
+        # TimeoutError is NOT retried — retrying burns another timeout_s for no gain.
+        for attempt in range(2):
+            try:
+                return self._attempt_request(
+                    method, path, encoded_body, all_headers, timeout_s
+                )
+            except (http.client.HTTPException, OSError) as exc:
+                self._close_connection()
+                if attempt == 0 and not isinstance(exc, TimeoutError):
+                    continue
+                raise ConnectionError(
+                    f"Request failed after connection retry: {exc}"
+                ) from exc
+
+        raise ConnectionError("Request failed after connection retry")  # unreachable
+
+    def _attempt_request(
+        self,
+        method: str,
+        path: str,
+        encoded_body: bytes | None,
+        all_headers: dict[str, str],
+        timeout_s: float,
+    ) -> dict[str, Any]:
+        """Execute a single HTTP request attempt. Raises on network failure."""
+        conn = self._get_or_create_connection(timeout_s)
+        conn.request(method, path, body=encoded_body, headers=all_headers)
+        resp = conn.getresponse()
+
+        data = resp.read(MAX_RESPONSE_SIZE + 1)
+        if len(data) > MAX_RESPONSE_SIZE:
+            raise ValueError(f"Response exceeded {MAX_RESPONSE_SIZE} bytes")
+
+        try:
+            parsed_body = json.loads(data.decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            parsed_body = {"raw": data.decode("utf-8", errors="replace")}
+
+        retry_after = resp.getheader("Retry-After")
+        return {
+            "status": resp.status,
+            "headers": ({"retry-after": retry_after} if retry_after else {}),
+            "body": parsed_body,
+        }
+
+    def destroy(self) -> None:
+        """Close connection and mark transport as destroyed."""
+        if not self._destroyed:
+            self._destroyed = True
+            self._close_connection()
+
+    @property
+    def destroyed(self) -> bool:
+        return self._destroyed
+
+    # ----- Private -----
+
+    def _get_or_create_connection(
+        self, timeout_s: float
+    ) -> http.client.HTTPConnection:
+        """Get existing connection or create a new one."""
+        if self._conn is not None:
+            # Update timeout for this request
+            self._conn.timeout = timeout_s
+            return self._conn
+
+        if self._is_https:
+            ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+            ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+            ctx.load_default_certs()
+            self._conn = http.client.HTTPSConnection(
+                self._host, self._port, timeout=timeout_s, context=ctx
+            )
+        else:
+            self._conn = http.client.HTTPConnection(
+                self._host, self._port, timeout=timeout_s
+            )
+
+        return self._conn
+
+    def _close_connection(self) -> None:
+        """Close current connection, if any."""
+        if self._conn is not None:
+            try:
+                self._conn.close()
+            except (OSError, http.client.HTTPException):
+                pass
+            self._conn = None

akhu_observer/_redact.py

@@ -0,0 +1,350 @@
+"""
+akhu-observer — Redaction utilities
+
+Privacy by default. Content is stripped unless explicitly opted in.
+This module decides what leaves the observed system and what doesn't.
+
+Design: We use an allowlist approach, not a denylist. Only known-safe
+metadata fields pass through. Everything else is stripped. This is
+intentionally conservative — better to lose an observation field than
+to leak user PII into an evidence ledger.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._constants import MAX_REDACTION_DEPTH, MAX_STRING_LENGTH
+
+# ---------------------------------------------------------------------------
+# Forbidden keys — NEVER safe, regardless of opt-in (security, not privacy)
+# ---------------------------------------------------------------------------
+
+FORBIDDEN_KEYS: frozenset[str] = frozenset(
+    {
+        "api_key",
+        "apiKey",
+        "api-key",
+        "authorization",
+        "Authorization",
+        "x-api-key",
+        "X-Api-Key",
+        "secret",
+        "password",
+        "token",
+        "access_token",
+        "accessToken",
+        "refresh_token",
+        "refreshToken",
+        "private_key",
+        "privateKey",
+        "secret_key",
+        "secretKey",
+        "session_token",
+        "sessionToken",
+        "bearer",
+        "credential",
+        "credentials",
+        "ssn",
+        "credit_card",
+        "creditCard",
+        "card_number",
+        "cardNumber",
+    }
+)
+
+# ---------------------------------------------------------------------------
+# OpenAI-specific allowlists
+# ---------------------------------------------------------------------------
+
+OPENAI_REQUEST_SAFE_FIELDS: frozenset[str] = frozenset(
+    {
+        "model",
+        "temperature",
+        "top_p",
+        "max_tokens",
+        "max_completion_tokens",
+        "n",
+        "stream",
+        "stop",
+        "presence_penalty",
+        "frequency_penalty",
+        "logit_bias",
+        "user",
+        "seed",
+        "response_format",
+        "tool_choice",
+        "parallel_tool_calls",
+    }
+)
+
+OPENAI_RESPONSE_SAFE_FIELDS: frozenset[str] = frozenset(
+    {
+        "id",
+        "object",
+        "created",
+        "model",
+        "system_fingerprint",
+        "usage",
+        "service_tier",
+    }
+)
+
+OPENAI_CHOICE_SAFE_FIELDS: frozenset[str] = frozenset(
+    {
+        "index",
+        "finish_reason",
+        "logprobs",
+    }
+)
+
+# ---------------------------------------------------------------------------
+# Anthropic-specific allowlists
+# ---------------------------------------------------------------------------
+
+ANTHROPIC_REQUEST_SAFE_FIELDS: frozenset[str] = frozenset(
+    {
+        "model",
+        "max_tokens",
+        "temperature",
+        "top_p",
+        "top_k",
+        "stop_sequences",
+        "stream",
+        "metadata",
+    }
+)
+
+ANTHROPIC_RESPONSE_SAFE_FIELDS: frozenset[str] = frozenset(
+    {
+        "id",
+        "type",
+        "role",
+        "model",
+        "stop_reason",
+        "stop_sequence",
+        "usage",
+    }
+)
+
+# ---------------------------------------------------------------------------
+# Generic redaction
+# ---------------------------------------------------------------------------
+
+
+def strip_forbidden_keys(value: Any, depth: int = 0) -> Any:
+    """Strip forbidden keys from any value, recursively.
+
+    Always runs — this is security, not privacy.
+    Handles nested dicts, lists, and depth limits.
+    """
+    if depth > MAX_REDACTION_DEPTH:
+        return "[REDACTED:MAX_DEPTH]"
+
+    if value is None:
+        return value
+
+    if isinstance(value, str):
+        if len(value) > MAX_STRING_LENGTH:
+            return (
+                value[:MAX_STRING_LENGTH]
+                + f"... [truncated, original length: {len(value)}]"
+            )
+        return value
+
+    if isinstance(value, (int, float, bool)):
+        return value
+
+    if isinstance(value, list):
+        return [strip_forbidden_keys(item, depth + 1) for item in value]
+
+    if isinstance(value, dict):
+        result: dict[str, Any] = {}
+        for key, val in value.items():
+            if key in FORBIDDEN_KEYS:
+                result[key] = "[REDACTED]"
+            else:
+                result[key] = strip_forbidden_keys(val, depth + 1)
+        return result
+
+    # Other types (tuple, set, etc.) — return as-is
+    return value
+
+
+# ---------------------------------------------------------------------------
+# OpenAI redaction
+# ---------------------------------------------------------------------------
+
+
+def _redact_openai_choice_message(msg: dict[str, Any]) -> dict[str, Any]:
+    """Redact a single OpenAI choice message to metadata."""
+    tool_calls = msg.get("tool_calls", [])
+    if not isinstance(tool_calls, list):
+        tool_calls = []
+
+    return {
+        "role": msg.get("role"),
+        "content_length": len(msg["content"]) if isinstance(msg.get("content"), str) else None,
+        "has_tool_calls": len(tool_calls) > 0,
+        "tool_call_count": len(tool_calls),
+        "tool_call_names": [
+            (tc.get("function", {}).get("name", "unknown") if isinstance(tc, dict) else "unknown")
+            for tc in tool_calls
+        ],
+        "content": "[REDACTED]",
+    }
+
+
+def _redact_openai_choice(choice: dict[str, Any]) -> dict[str, Any]:
+    """Redact a single OpenAI choice to metadata."""
+    safe_choice: dict[str, Any] = {}
+    for key, val in choice.items():
+        if key in OPENAI_CHOICE_SAFE_FIELDS:
+            safe_choice[key] = val
+        elif key == "message" and isinstance(val, dict):
+            safe_choice["message"] = _redact_openai_choice_message(val)
+    return safe_choice
+
+
+def redact_openai_request(params: dict[str, Any]) -> dict[str, Any]:
+    """Redact an OpenAI chat completion request to metadata only.
+
+    Messages are replaced with structure info (role, count, has content).
+    Tool definitions are replaced with names only.
+    """
+    result: dict[str, Any] = {}
+
+    for key, val in params.items():
+        if key in OPENAI_REQUEST_SAFE_FIELDS:
+            result[key] = strip_forbidden_keys(val)
+        elif key == "messages" and isinstance(val, list):
+            result["message_count"] = len(val)
+            result["message_roles"] = [
+                (m.get("role", "unknown") if isinstance(m, dict) else "unknown")
+                for m in val
+            ]
+            result["messages"] = "[REDACTED]"
+        elif key == "tools" and isinstance(val, list):
+            result["tool_names"] = [
+                (
+                    t.get("function", {}).get("name", "unknown")
+                    if isinstance(t, dict)
+                    else "unknown"
+                )
+                for t in val
+            ]
+            result["tools"] = "[REDACTED]"
+        elif key == "functions" and isinstance(val, list):
+            result["function_names"] = [
+                (f.get("name", "unknown") if isinstance(f, dict) else "unknown")
+                for f in val
+            ]
+            result["functions"] = "[REDACTED]"
+        # Unknown fields are silently dropped — allowlist, not denylist
+
+    return result
+
+
+def redact_openai_response(response: dict[str, Any]) -> dict[str, Any]:
+    """Redact an OpenAI chat completion response to metadata only.
+
+    Message content is replaced with length info. Tool call arguments are stripped.
+    """
+    result: dict[str, Any] = {}
+
+    for key, val in response.items():
+        if key in OPENAI_RESPONSE_SAFE_FIELDS:
+            result[key] = strip_forbidden_keys(val)
+        elif key == "choices" and isinstance(val, list):
+            result["choices"] = [
+                _redact_openai_choice(c) if isinstance(c, dict) else c
+                for c in val
+            ]
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Anthropic redaction
+# ---------------------------------------------------------------------------
+
+
+def redact_anthropic_request(params: dict[str, Any]) -> dict[str, Any]:
+    """Redact an Anthropic message create request to metadata only."""
+    result: dict[str, Any] = {}
+
+    for key, val in params.items():
+        if key in ANTHROPIC_REQUEST_SAFE_FIELDS:
+            result[key] = strip_forbidden_keys(val)
+        elif key == "messages" and isinstance(val, list):
+            result["message_count"] = len(val)
+            result["message_roles"] = [
+                (m.get("role", "unknown") if isinstance(m, dict) else "unknown")
+                for m in val
+            ]
+            result["messages"] = "[REDACTED]"
+        elif key == "system":
+            result["has_system"] = True
+            result["system"] = "[REDACTED]"
+        elif key == "tools" and isinstance(val, list):
+            result["tool_names"] = [
+                (t.get("name", "unknown") if isinstance(t, dict) else "unknown")
+                for t in val
+            ]
+            result["tools"] = "[REDACTED]"
+
+    return result
+
+
+def redact_anthropic_response(response: dict[str, Any]) -> dict[str, Any]:
+    """Redact an Anthropic message response to metadata only."""
+    result: dict[str, Any] = {}
+
+    for key, val in response.items():
+        if key in ANTHROPIC_RESPONSE_SAFE_FIELDS:
+            result[key] = strip_forbidden_keys(val)
+        elif key == "content" and isinstance(val, list):
+            blocks: list[dict[str, Any]] = []
+            for block in val:
+                if not isinstance(block, dict):
+                    blocks.append({"content": "[REDACTED]"})
+                    continue
+                block_type = block.get("type")
+                if block_type == "text":
+                    blocks.append(
+                        {
+                            "type": "text",
+                            "text_length": (
+                                len(block["text"])
+                                if isinstance(block.get("text"), str)
+                                else 0
+                            ),
+                            "text": "[REDACTED]",
+                        }
+                    )
+                elif block_type == "tool_use":
+                    blocks.append(
+                        {
+                            "type": "tool_use",
+                            "id": block.get("id"),
+                            "name": block.get("name"),
+                            "input": "[REDACTED]",
+                        }
+                    )
+                else:
+                    blocks.append({"type": block_type, "content": "[REDACTED]"})
+            result["content"] = blocks
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Full content mode (opt-in)
+# ---------------------------------------------------------------------------
+
+
+def pass_with_security_strip(value: Any) -> Any:
+    """When captureContent is true, still strip forbidden keys (security)
+    but pass through all other content.
+    """
+    return strip_forbidden_keys(value)