synth-ai 0.2.14__py3-none-any.whl → 0.4.1__py3-none-any.whl

synth_ai/core/env.py

@@ -0,0 +1,220 @@
+"""Environment resolution utilities.
+
+This module provides non-interactive environment variable resolution
+for use by SDK and CLI. It consolidates the various env resolution
+patterns into a clean API.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+from .errors import AuthenticationError, ConfigError
+
+# Default production URL
+PROD_BASE_URL = "https://www.api.usesynth.ai"
+PROD_BASE_URL_DEFAULT = PROD_BASE_URL  # Alias for backward compatibility
+
+
+def get_api_key(env_key: str = "SYNTH_API_KEY", required: bool = True) -> str | None:
+    """Get API key from environment.
+
+    Args:
+        env_key: Environment variable name to check
+        required: If True, raises AuthenticationError when not found
+
+    Returns:
+        API key string or None if not required and not found
+
+    Raises:
+        AuthenticationError: If required and not found
+    """
+    value = os.environ.get(env_key)
+    if not value and required:
+        raise AuthenticationError(
+            f"Missing required API key: {env_key}\n"
+            f"Set it via: export {env_key}=<your-key>\n"
+            f"Or add to .env file: {env_key}=<your-key>"
+        )
+    return value
+
+
+def get_backend_url(
+    mode: Literal["prod", "dev", "local"] | None = None,
+) -> str:
+    """Resolve backend URL.
+
+    Priority order:
+    1. SYNTH_BACKEND_URL env var (if set)
+    2. Mode-specific URL based on SYNTH_BACKEND_MODE or explicit mode
+    3. Default to production
+
+    Args:
+        mode: Force a specific mode (prod/dev/local), or detect from env
+
+    Returns:
+        Backend URL (without trailing /api)
+    """
+    # Direct override takes precedence
+    direct = os.environ.get("SYNTH_BACKEND_URL")
+    if direct:
+        return _normalize_url(direct)
+
+    # Determine mode
+    if mode is None:
+        mode_env = os.environ.get("SYNTH_BACKEND_MODE", "").lower()
+        mode = mode_env if mode_env in ("prod", "dev", "local") else "prod"  # type: ignore
+
+    if mode == "local":
+        url = os.environ.get("SYNTH_LOCAL_URL", "http://localhost:8000")
+    elif mode == "dev":
+        url = os.environ.get("SYNTH_DEV_URL", "http://localhost:8000")
+    else:
+        url = os.environ.get("SYNTH_PROD_URL", PROD_BASE_URL)
+
+    return _normalize_url(url)
+
+
+def _normalize_url(url: str) -> str:
+    """Normalize URL: strip trailing slashes and /api suffix."""
+    url = url.strip().rstrip("/")
+    if url.endswith("/api"):
+        url = url[:-4]
+    if url.endswith("/v1"):
+        url = url[:-3]
+    return url
+
+
+def resolve_env_file(
+    explicit_path: str | Path | None = None,
+    search_cwd: bool = True,
+) -> Path | None:
+    """Find and return path to .env file.
+
+    Args:
+        explicit_path: If provided, use this path directly
+        search_cwd: If True, search current directory for .env
+
+    Returns:
+        Path to .env file, or None if not found
+    """
+    if explicit_path:
+        path = Path(explicit_path).expanduser().resolve()
+        if path.exists():
+            return path
+        raise ConfigError(f"Env file not found: {path}")
+
+    if search_cwd:
+        cwd_env = Path.cwd() / ".env"
+        if cwd_env.exists():
+            return cwd_env.resolve()
+
+    return None
+
+
+def load_env_file(path: Path) -> dict[str, str]:
+    """Parse a .env file into a dictionary.
+
+    Args:
+        path: Path to .env file
+
+    Returns:
+        Dict mapping env var names to values
+    """
+    result: dict[str, str] = {}
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if line.lower().startswith("export "):
+                    line = line[7:].strip()
+                if "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip()
+                # Strip quotes
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+                    value = value[1:-1]
+                result[key] = value
+    except (OSError, UnicodeDecodeError) as e:
+        raise ConfigError(f"Failed to read env file {path}: {e}") from e
+    return result
+
+
+def mask_value(value: str, visible_chars: int = 4) -> str:
+    """Mask a sensitive value for display.
+
+    Args:
+        value: The value to mask
+        visible_chars: Number of characters to show at start and end
+
+    Returns:
+        Masked string like "abc...xyz"
+    """
+    if len(value) <= visible_chars * 2:
+        return "***"
+    return f"{value[:visible_chars]}...{value[-visible_chars:]}"
+
+
+def get_backend_from_env() -> tuple[str, str]:
+    """Resolve (base_url, api_key) using LOCAL/DEV/PROD override scheme.
+
+    Env vars consulted:
+    - BACKEND_OVERRIDE = full URL (with or without /api)
+    - SYNTH_BACKEND_URL_OVERRIDE = local|dev|prod (case-insensitive)
+    - LOCAL_BACKEND_URL, TESTING_LOCAL_SYNTH_API_KEY
+    - DEV_BACKEND_URL, DEV_SYNTH_API_KEY
+    - PROD_BACKEND_URL, TESTING_PROD_SYNTH_API_KEY (fallback to SYNTH_API_KEY)
+
+    Base URL is normalized (no trailing /api).
+    Defaults: prod base URL → https://api.usesynth.ai
+
+    Returns:
+        Tuple of (base_url, api_key)
+    """
+    direct_override = (os.environ.get("BACKEND_OVERRIDE") or "").strip()
+    if direct_override:
+        base = _normalize_url(direct_override)
+        api_key = os.environ.get("SYNTH_API_KEY", "").strip()
+        return base, api_key
+
+    # Determine mode from env
+    mode_override = (os.environ.get("SYNTH_BACKEND_URL_OVERRIDE", "") or "").strip().lower()
+    mode = mode_override if mode_override in ("local", "dev", "prod") else "prod"
+
+    if mode == "local":
+        base = os.environ.get("LOCAL_BACKEND_URL", "http://localhost:8000")
+        key = os.environ.get("TESTING_LOCAL_SYNTH_API_KEY", "")
+        return _normalize_url(base), key
+
+    if mode == "dev":
+        base = os.environ.get("DEV_BACKEND_URL", "") or "http://localhost:8000"
+        key = os.environ.get("DEV_SYNTH_API_KEY", "")
+        return _normalize_url(base), key
+
+    # prod
+    base = os.environ.get("PROD_BACKEND_URL", PROD_BASE_URL)
+    key = (
+        os.environ.get("PROD_SYNTH_API_KEY", "")
+        or os.environ.get("TESTING_PROD_SYNTH_API_KEY", "")
+        or os.environ.get("SYNTH_API_KEY", "")
+    )
+    return _normalize_url(base), key
+
+
+__all__ = [
+    "get_api_key",
+    "get_backend_url",
+    "get_backend_from_env",
+    "resolve_env_file",
+    "load_env_file",
+    "mask_value",
+    "PROD_BASE_URL",
+    "PROD_BASE_URL_DEFAULT",
+]
+

synth_ai/core/errors.py

@@ -0,0 +1,126 @@
+"""Consolidated error types for Synth AI SDK.
+
+This module provides base exception classes used throughout the SDK.
+CLI-specific errors remain in cli/ modules; these are for SDK/core use.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+class SynthError(Exception):
+    """Base exception for all Synth AI SDK errors."""
+
+    pass
+
+
+class ConfigError(SynthError):
+    """Raised when configuration is invalid or missing."""
+
+    pass
+
+
+class AuthenticationError(SynthError):
+    """Raised when API authentication fails."""
+
+    pass
+
+
+class ValidationError(SynthError):
+    """Raised when data validation fails."""
+
+    pass
+
+
+@dataclass
+class HTTPError(SynthError):
+    """Raised when an HTTP request fails."""
+
+    status: int
+    url: str
+    message: str
+    body_snippet: str | None = None
+    detail: Any | None = None
+
+    def __str__(self) -> str:
+        base = f"HTTP {self.status} for {self.url}: {self.message}"
+        if self.body_snippet:
+            base += f" | body[0:200]={self.body_snippet[:200]}"
+        return base
+
+
+class JobError(SynthError):
+    """Raised when a job operation fails."""
+
+    pass
+
+
+class TimeoutError(SynthError):
+    """Raised when an operation times out."""
+
+    pass
+
+
+class StorageError(SynthError):
+    """Raised when storage operations fail."""
+
+    pass
+
+
+class ModelNotSupportedError(SynthError):
+    """Raised when a model is not supported."""
+
+    def __init__(self, model: str, provider: str | None = None) -> None:
+        self.model = model
+        self.provider = provider
+        msg = f"Model '{model}' is not supported"
+        if provider:
+            msg += f" by provider '{provider}'"
+        super().__init__(msg)
+
+
+@dataclass
+class UsageLimitError(SynthError):
+    """Raised when an org rate limit is exceeded.
+
+    Attributes:
+        limit_type: The type of limit exceeded (e.g., "inference_tokens_per_day")
+        api: The API that hit the limit (e.g., "inference", "judges", "prompt_opt")
+        current: Current usage value
+        limit: The limit value
+        tier: The org's tier (e.g., "free", "starter", "growth")
+        retry_after_seconds: Seconds until the limit resets (if available)
+        upgrade_url: URL to upgrade tier
+    """
+
+    limit_type: str
+    api: str
+    current: int | float
+    limit: int | float
+    tier: str = "free"
+    retry_after_seconds: int | None = None
+    upgrade_url: str = "https://usesynth.ai/pricing"
+
+    def __str__(self) -> str:
+        return (
+            f"Rate limit exceeded: {self.limit_type} "
+            f"({self.current}/{self.limit}) for tier '{self.tier}'. "
+            f"Upgrade at {self.upgrade_url}"
+        )
+
+
+__all__ = [
+    "SynthError",
+    "ConfigError",
+    "AuthenticationError",
+    "ValidationError",
+    "HTTPError",
+    "JobError",
+    "TimeoutError",
+    "StorageError",
+    "ModelNotSupportedError",
+    "UsageLimitError",
+]
+

synth_ai/core/http.py

@@ -0,0 +1,230 @@
+"""HTTP client utilities for Synth AI SDK.
+
+This module provides async HTTP client functionality used by SDK modules
+for communicating with the Synth backend.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+import aiohttp
+
+from .errors import HTTPError
+
+
+class AsyncHttpClient:
+    """Async HTTP client for Synth API calls.
+
+    Usage:
+        async with AsyncHttpClient(base_url, api_key) as client:
+            result = await client.get("/api/jobs/123")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize the HTTP client.
+
+        Args:
+            base_url: Base URL for the API (without trailing /api)
+            api_key: API key for authentication
+            timeout: Request timeout in seconds
+        """
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._session: aiohttp.ClientSession | None = None
+
+    async def __aenter__(self) -> AsyncHttpClient:
+        if self._session is None:
+            headers = {"authorization": f"Bearer {self._api_key}"}
+            # Optional dev overrides for user/org context
+            user_id = os.getenv("SYNTH_USER_ID") or os.getenv("X_USER_ID")
+            if user_id:
+                headers["X-User-ID"] = user_id
+            org_id = os.getenv("SYNTH_ORG_ID") or os.getenv("X_ORG_ID")
+            if org_id:
+                headers["X-Org-ID"] = org_id
+            self._session = aiohttp.ClientSession(
+                headers=headers, timeout=self._timeout
+            )
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: Any,
+    ) -> None:
+        if self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    def _abs(self, path: str) -> str:
+        """Convert relative path to absolute URL."""
+        if path.startswith(("http://", "https://")):
+            return path
+        # Handle /api prefix
+        if self._base_url.endswith("/api") and path.startswith("/api"):
+            path = path[4:]
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    async def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Make a GET request."""
+        url = self._abs(path)
+        assert self._session is not None, "Must use as async context manager"
+        async with self._session.get(url, params=params, headers=headers) as resp:
+            return await self._handle_response(resp, url)
+
+    async def post_json(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any],
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Make a POST request with JSON body."""
+        url = self._abs(path)
+        assert self._session is not None, "Must use as async context manager"
+        async with self._session.post(url, json=json, headers=headers) as resp:
+            return await self._handle_response(resp, url)
+
+    async def post_multipart(
+        self,
+        path: str,
+        *,
+        data: dict[str, Any],
+        files: dict[str, tuple[str, bytes, str | None]],
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Make a POST request with multipart form data."""
+        url = self._abs(path)
+        assert self._session is not None, "Must use as async context manager"
+        form = aiohttp.FormData()
+        for k, v in data.items():
+            form.add_field(k, str(v))
+        for field, (filename, content, content_type) in files.items():
+            form.add_field(
+                field,
+                content,
+                filename=filename,
+                content_type=content_type or "application/octet-stream",
+            )
+        async with self._session.post(url, data=form, headers=headers) as resp:
+            return await self._handle_response(resp, url)
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Make a DELETE request."""
+        url = self._abs(path)
+        assert self._session is not None, "Must use as async context manager"
+        async with self._session.delete(url, headers=headers) as resp:
+            return await self._handle_response(resp, url)
+
+    async def _handle_response(
+        self, resp: aiohttp.ClientResponse, url: str
+    ) -> Any:
+        """Handle HTTP response, raising HTTPError on failure."""
+        text = await resp.text()
+        body_snippet = text[:200] if text else None
+
+        if 200 <= resp.status < 300:
+            ctype = resp.headers.get("content-type", "")
+            if "application/json" in ctype:
+                try:
+                    return await resp.json()
+                except Exception:
+                    return text
+            return text
+
+        # Error response
+        detail: Any | None = None
+        try:
+            detail = await resp.json()
+        except Exception:
+            detail = None
+
+        raise HTTPError(
+            status=resp.status,
+            url=url,
+            message="request_failed",
+            body_snippet=body_snippet,
+            detail=detail,
+        )
+
+
+async def sleep(seconds: float) -> None:
+    """Async sleep helper."""
+    await asyncio.sleep(seconds)
+
+
+def http_request(
+    method: str,
+    url: str,
+    headers: dict[str, str] | None = None,
+    body: dict[str, Any] | None = None,
+) -> tuple[int, dict[str, Any] | str]:
+    """Synchronous HTTP request using stdlib.
+
+    Args:
+        method: HTTP method (GET, POST, etc.)
+        url: Full URL to request
+        headers: Optional headers dict
+        body: Optional JSON body dict
+
+    Returns:
+        Tuple of (status_code, response_data)
+    """
+    import json as _json
+    import ssl
+    import urllib.error
+    import urllib.request
+
+    data = None
+    if body is not None:
+        data = _json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(url, method=method, headers=headers or {}, data=data)
+    try:
+        ctx = ssl._create_unverified_context()
+        if os.getenv("SYNTH_SSL_VERIFY", "0") == "1":
+            ctx = None
+        with urllib.request.urlopen(req, timeout=60, context=ctx) as resp:
+            code = getattr(resp, "status", 200)
+            txt = resp.read().decode("utf-8", errors="ignore")
+            try:
+                return int(code), _json.loads(txt)
+            except Exception:
+                return int(code), txt
+    except urllib.error.HTTPError as exc:
+        txt = exc.read().decode("utf-8", errors="ignore")
+        try:
+            return int(exc.code or 0), _json.loads(txt)
+        except Exception:
+            return int(exc.code or 0), txt
+    except Exception as exc:
+        return 0, str(exc)
+
+
+__all__ = [
+    "AsyncHttpClient",
+    "HTTPError",
+    "http_request",
+    "sleep",
+]
+

synth_ai/core/integrations/__init__.py

@@ -0,0 +1,11 @@
+"""Core integrations for Synth AI SDK.
+
+This module provides integration points with external systems
+that are core to SDK functionality.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []
+
+