tracia 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

tracia/_constants.py

@@ -0,0 +1,39 @@
+"""Constants and configuration for the Tracia SDK."""
+
+from __future__ import annotations
+
+# SDK Version (defined here to avoid circular imports)
+SDK_VERSION = "0.1.0"
+
+# API Configuration
+BASE_URL = "https://app.tracia.io"
+
+# Timeout Configuration (in milliseconds)
+DEFAULT_TIMEOUT_MS = 120_000  # 2 minutes
+
+# Span Management
+MAX_PENDING_SPANS = 1000
+SPAN_RETRY_ATTEMPTS = 2
+SPAN_RETRY_DELAY_MS = 500
+
+# Span Status
+SPAN_STATUS_SUCCESS = "SUCCESS"
+SPAN_STATUS_ERROR = "ERROR"
+
+# ID Prefixes
+SPAN_ID_PREFIX = "sp_"
+TRACE_ID_PREFIX = "tr_"
+
+# Environment Variable Names for Provider API Keys
+ENV_VAR_MAP = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "google": "GOOGLE_API_KEY",
+}
+
+# Evaluation Constants
+class Eval:
+    """Evaluation value constants."""
+
+    POSITIVE = 1
+    NEGATIVE = 0

tracia/_errors.py

@@ -0,0 +1,87 @@
+"""Error handling for the Tracia SDK."""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+
+class TraciaErrorCode(str, Enum):
+    """Error codes for Tracia SDK errors."""
+
+    UNAUTHORIZED = "UNAUTHORIZED"
+    NOT_FOUND = "NOT_FOUND"
+    CONFLICT = "CONFLICT"
+    PROVIDER_ERROR = "PROVIDER_ERROR"
+    MISSING_VARIABLES = "MISSING_VARIABLES"
+    INVALID_REQUEST = "INVALID_REQUEST"
+    NETWORK_ERROR = "NETWORK_ERROR"
+    TIMEOUT = "TIMEOUT"
+    ABORTED = "ABORTED"
+    UNKNOWN = "UNKNOWN"
+    MISSING_PROVIDER_SDK = "MISSING_PROVIDER_SDK"
+    MISSING_PROVIDER_API_KEY = "MISSING_PROVIDER_API_KEY"
+    UNSUPPORTED_MODEL = "UNSUPPORTED_MODEL"
+
+
+class TraciaError(Exception):
+    """Exception raised for Tracia SDK errors."""
+
+    def __init__(
+        self,
+        code: TraciaErrorCode,
+        message: str,
+        status_code: int | None = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.code.value}] {self.message} (status: {self.status_code})"
+        return f"[{self.code.value}] {self.message}"
+
+    def __repr__(self) -> str:
+        return f"TraciaError(code={self.code!r}, message={self.message!r}, status_code={self.status_code!r})"
+
+
+# Patterns for sanitizing sensitive data from error messages
+_SENSITIVE_PATTERNS = [
+    re.compile(r"sk-[a-zA-Z0-9]{20,}"),  # OpenAI API keys
+    re.compile(r"sk-ant-[a-zA-Z0-9-]{20,}"),  # Anthropic API keys
+    re.compile(r"Bearer\s+[a-zA-Z0-9._-]+"),  # Bearer tokens
+    re.compile(r"Basic\s+[a-zA-Z0-9+/=]+"),  # Basic auth
+    re.compile(r"Authorization:\s*[^\s]+", re.IGNORECASE),  # Auth headers
+]
+
+
+def sanitize_error_message(message: str) -> str:
+    """Remove sensitive data from error messages.
+
+    Args:
+        message: The error message to sanitize.
+
+    Returns:
+        The sanitized error message.
+    """
+    result = message
+    for pattern in _SENSITIVE_PATTERNS:
+        result = pattern.sub("[REDACTED]", result)
+    return result
+
+
+def map_api_error_code(code: str) -> TraciaErrorCode:
+    """Map an API error code string to a TraciaErrorCode.
+
+    Args:
+        code: The error code from the API response.
+
+    Returns:
+        The corresponding TraciaErrorCode.
+    """
+    try:
+        return TraciaErrorCode(code)
+    except ValueError:
+        return TraciaErrorCode.UNKNOWN

tracia/_http.py

@@ -0,0 +1,362 @@
+"""HTTP client for the Tracia API."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+import httpx
+
+from ._constants import BASE_URL, DEFAULT_TIMEOUT_MS, SDK_VERSION
+from ._errors import TraciaError, TraciaErrorCode, map_api_error_code
+
+T = TypeVar("T")
+
+
+class HttpClient:
+    """Synchronous HTTP client for the Tracia API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = BASE_URL,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+    ) -> None:
+        """Initialize the HTTP client.
+
+        Args:
+            api_key: The Tracia API key.
+            base_url: The base URL for the API.
+            timeout_ms: Request timeout in milliseconds.
+        """
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout_ms / 1000.0  # Convert to seconds
+
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=self._get_headers(),
+            timeout=httpx.Timeout(self._timeout),
+        )
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get the default headers for requests."""
+        return {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": f"tracia-sdk-python/{SDK_VERSION}",
+        }
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        """Handle the API response and raise errors if needed."""
+        if response.status_code >= 400:
+            try:
+                data = response.json()
+                error_data = data.get("error", {})
+                code = map_api_error_code(error_data.get("code", "UNKNOWN"))
+                message = error_data.get("message", "Unknown error")
+            except Exception:
+                code = TraciaErrorCode.UNKNOWN
+                message = response.text or f"HTTP {response.status_code}"
+
+            raise TraciaError(
+                code=code,
+                message=message,
+                status_code=response.status_code,
+            )
+
+        if response.status_code == 204:
+            return None
+
+        return response.json()
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """Make a GET request.
+
+        Args:
+            path: The API path.
+            params: Optional query parameters.
+
+        Returns:
+            The JSON response.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        try:
+            response = self._client.get(path, params=params)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise TraciaError(
+                code=TraciaErrorCode.TIMEOUT,
+                message=f"Request timed out after {int(self._timeout * 1000)}ms",
+            ) from e
+        except httpx.RequestError as e:
+            raise TraciaError(
+                code=TraciaErrorCode.NETWORK_ERROR,
+                message=f"Network error: {e}",
+            ) from e
+
+    def post(self, path: str, body: Any = None) -> Any:
+        """Make a POST request.
+
+        Args:
+            path: The API path.
+            body: The request body.
+
+        Returns:
+            The JSON response.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        try:
+            response = self._client.post(path, json=body)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise TraciaError(
+                code=TraciaErrorCode.TIMEOUT,
+                message=f"Request timed out after {int(self._timeout * 1000)}ms",
+            ) from e
+        except httpx.RequestError as e:
+            raise TraciaError(
+                code=TraciaErrorCode.NETWORK_ERROR,
+                message=f"Network error: {e}",
+            ) from e
+
+    def put(self, path: str, body: Any = None) -> Any:
+        """Make a PUT request.
+
+        Args:
+            path: The API path.
+            body: The request body.
+
+        Returns:
+            The JSON response.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        try:
+            response = self._client.put(path, json=body)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise TraciaError(
+                code=TraciaErrorCode.TIMEOUT,
+                message=f"Request timed out after {int(self._timeout * 1000)}ms",
+            ) from e
+        except httpx.RequestError as e:
+            raise TraciaError(
+                code=TraciaErrorCode.NETWORK_ERROR,
+                message=f"Network error: {e}",
+            ) from e
+
+    def delete(self, path: str) -> Any:
+        """Make a DELETE request.
+
+        Args:
+            path: The API path.
+
+        Returns:
+            The JSON response (or None for 204).
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        try:
+            response = self._client.delete(path)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise TraciaError(
+                code=TraciaErrorCode.TIMEOUT,
+                message=f"Request timed out after {int(self._timeout * 1000)}ms",
+            ) from e
+        except httpx.RequestError as e:
+            raise TraciaError(
+                code=TraciaErrorCode.NETWORK_ERROR,
+                message=f"Network error: {e}",
+            ) from e
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client for the Tracia API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = BASE_URL,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+    ) -> None:
+        """Initialize the async HTTP client.
+
+        Args:
+            api_key: The Tracia API key.
+            base_url: The base URL for the API.
+            timeout_ms: Request timeout in milliseconds.
+        """
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout_ms / 1000.0  # Convert to seconds
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._get_headers(),
+            timeout=httpx.Timeout(self._timeout),
+        )
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get the default headers for requests."""
+        return {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": f"tracia-sdk-python/{SDK_VERSION}",
+        }
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        """Handle the API response and raise errors if needed."""
+        if response.status_code >= 400:
+            try:
+                data = response.json()
+                error_data = data.get("error", {})
+                code = map_api_error_code(error_data.get("code", "UNKNOWN"))
+                message = error_data.get("message", "Unknown error")
+            except Exception:
+                code = TraciaErrorCode.UNKNOWN
+                message = response.text or f"HTTP {response.status_code}"
+
+            raise TraciaError(
+                code=code,
+                message=message,
+                status_code=response.status_code,
+            )
+
+        if response.status_code == 204:
+            return None
+
+        return response.json()
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """Make a GET request.
+
+        Args:
+            path: The API path.
+            params: Optional query parameters.
+
+        Returns:
+            The JSON response.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        try:
+            response = await self._client.get(path, params=params)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise TraciaError(
+                code=TraciaErrorCode.TIMEOUT,
+                message=f"Request timed out after {int(self._timeout * 1000)}ms",
+            ) from e
+        except httpx.RequestError as e:
+            raise TraciaError(
+                code=TraciaErrorCode.NETWORK_ERROR,
+                message=f"Network error: {e}",
+            ) from e
+
+    async def post(self, path: str, body: Any = None) -> Any:
+        """Make a POST request.
+
+        Args:
+            path: The API path.
+            body: The request body.
+
+        Returns:
+            The JSON response.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        try:
+            response = await self._client.post(path, json=body)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise TraciaError(
+                code=TraciaErrorCode.TIMEOUT,
+                message=f"Request timed out after {int(self._timeout * 1000)}ms",
+            ) from e
+        except httpx.RequestError as e:
+            raise TraciaError(
+                code=TraciaErrorCode.NETWORK_ERROR,
+                message=f"Network error: {e}",
+            ) from e
+
+    async def put(self, path: str, body: Any = None) -> Any:
+        """Make a PUT request.
+
+        Args:
+            path: The API path.
+            body: The request body.
+
+        Returns:
+            The JSON response.
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        try:
+            response = await self._client.put(path, json=body)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise TraciaError(
+                code=TraciaErrorCode.TIMEOUT,
+                message=f"Request timed out after {int(self._timeout * 1000)}ms",
+            ) from e
+        except httpx.RequestError as e:
+            raise TraciaError(
+                code=TraciaErrorCode.NETWORK_ERROR,
+                message=f"Network error: {e}",
+            ) from e
+
+    async def delete(self, path: str) -> Any:
+        """Make a DELETE request.
+
+        Args:
+            path: The API path.
+
+        Returns:
+            The JSON response (or None for 204).
+
+        Raises:
+            TraciaError: If the request fails.
+        """
+        try:
+            response = await self._client.delete(path)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise TraciaError(
+                code=TraciaErrorCode.TIMEOUT,
+                message=f"Request timed out after {int(self._timeout * 1000)}ms",
+            ) from e
+        except httpx.RequestError as e:
+            raise TraciaError(
+                code=TraciaErrorCode.NETWORK_ERROR,
+                message=f"Network error: {e}",
+            ) from e
+
+    async def aclose(self) -> None:
+        """Close the async HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()