synth-ai 0.2.6.dev1__py3-none-any.whl → 0.4.3__py3-none-any.whl

synth_ai/core/config/base.py

@@ -0,0 +1,168 @@
+"""Base configuration classes for Synth AI SDK.
+
+This module defines the base config class that all job configs inherit from,
+ensuring consistent handling of common fields like API keys and backend URLs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from synth_ai.core.env import get_api_key, get_backend_url
+from synth_ai.core.errors import ConfigError
+
+
+@dataclass
+class BaseJobConfig:
+    """Base class for all job configuration dataclasses.
+    
+    This class provides common functionality shared across all job types
+    (prompt learning, SFT, RL, research agent). Subclasses should inherit
+    from this and add job-specific fields.
+    
+    The base class ensures consistent handling of:
+    - Backend URL resolution
+    - API key validation
+    - Common configuration patterns
+    
+    Example:
+        >>> from synth_ai.core.config import BaseJobConfig
+        >>> from dataclasses import dataclass
+        >>> 
+        >>> @dataclass
+        ... class MyJobConfig(BaseJobConfig):
+        ...     model: str
+        ...     temperature: float = 0.7
+    """
+    """Base configuration shared by all job types.
+
+    All job configs should inherit from this class to ensure consistent
+    handling of common fields like API keys and backend URLs.
+
+    Attributes:
+        task_app_url: URL of the task app to use
+        backend_url: Synth backend URL (defaults to production)
+        api_key: Synth API key (resolved from env if not provided)
+        environment_api_key: API key for environment access
+        timeout_seconds: Job timeout in seconds
+        metadata: Optional metadata dict attached to job
+    """
+
+    task_app_url: str | None = None
+    backend_url: str | None = None
+    api_key: str | None = None
+    environment_api_key: str | None = None
+    timeout_seconds: int = 3600
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def resolve_credentials(self) -> tuple[str, str]:
+        """Resolve API key and backend URL.
+
+        Uses provided values or falls back to environment resolution.
+
+        Returns:
+            Tuple of (backend_url, api_key)
+
+        Raises:
+            ConfigError: If required credentials cannot be resolved
+        """
+        api_key = self.api_key or get_api_key(required=True)
+        backend_url = self.backend_url or get_backend_url()
+
+        if not api_key:
+            raise ConfigError("API key is required")
+
+        return backend_url, api_key
+
+    def validate(self) -> list[str]:
+        """Validate the configuration.
+
+        Returns:
+            List of validation error messages (empty if valid)
+        """
+        errors: list[str] = []
+        if self.timeout_seconds <= 0:
+            errors.append("timeout_seconds must be positive")
+        return errors
+
+
+class ConfigValidator:
+    """Base class for configuration validators.
+    
+    Validators provide a way to validate and normalize configuration
+    before it's used to create jobs. This is useful for:
+    - Type checking
+    - Value validation
+    - Default value injection
+    - Cross-field validation
+    
+    Subclasses should implement the `validate()` method to perform
+    job-specific validation logic.
+    
+    Example:
+        >>> from synth_ai.core.config import ConfigValidator
+        >>> 
+        >>> class MyJobValidator(ConfigValidator):
+        ...     def validate(self, config: dict) -> dict:
+        ...         if config.get("temperature", 0) < 0:
+        ...             raise ValueError("temperature must be >= 0")
+        ...         return config
+    """
+    """Utility for validating configurations."""
+
+    @staticmethod
+    def require_field(
+        config: dict[str, Any],
+        field_name: str,
+        field_type: type | tuple[type, ...] | None = None,
+    ) -> Any:
+        """Require a field to be present in config.
+
+        Args:
+            config: Configuration dict
+            field_name: Name of required field
+            field_type: Optional type(s) to validate against
+
+        Returns:
+            The field value
+
+        Raises:
+            ConfigError: If field is missing or wrong type
+        """
+        if field_name not in config:
+            raise ConfigError(f"Missing required field: {field_name}")
+
+        value = config[field_name]
+        if field_type is not None and not isinstance(value, field_type):
+            expected = (
+                field_type.__name__
+                if isinstance(field_type, type)
+                else " | ".join(t.__name__ for t in field_type)
+            )
+            raise ConfigError(
+                f"Field '{field_name}' must be {expected}, got {type(value).__name__}"
+            )
+
+        return value
+
+    @staticmethod
+    def validate_positive(value: int | float, field_name: str) -> None:
+        """Validate that a numeric value is positive.
+
+        Args:
+            value: Value to check
+            field_name: Name for error message
+
+        Raises:
+            ConfigError: If value is not positive
+        """
+        if value <= 0:
+            raise ConfigError(f"{field_name} must be positive, got {value}")
+
+
+__all__ = [
+    "BaseJobConfig",
+    "ConfigValidator",
+]
+

synth_ai/core/config/resolver.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Optional, overload
+
+import click
+
+from synth_ai.core.telemetry import log_info
+
+
+def _get_required_value(*args, **kwargs):
+    """Lazy import to avoid circular dependency."""
+    from synth_ai.cli.lib.errors import get_required_value
+    return get_required_value(*args, **kwargs)
+
+
+class ConfigResolver:
+    """Resolve configuration values with consistent precedence and messaging."""
+
+    @overload
+    @staticmethod
+    def resolve(
+        name: str,
+        *,
+        cli_value: Optional[str] = None,
+        env_value: Optional[str] = None,
+        config_value: Optional[str] = None,
+        default: Optional[str] = None,
+        required: bool = False,
+        docs_url: Optional[str] = None,
+    ) -> Optional[str]: ...
+
+    @overload
+    @staticmethod
+    def resolve(
+        name: str,
+        *,
+        cli_value: Optional[str] = None,
+        env_value: Optional[str] = None,
+        config_value: Optional[str] = None,
+        default: Optional[str] = None,
+        required: bool = True,
+        docs_url: Optional[str] = None,
+    ) -> str: ...
+
+    @staticmethod
+    def resolve(
+        name: str,
+        *,
+        cli_value: Optional[str] = None,
+        env_value: Optional[str] = None,
+        config_value: Optional[str] = None,
+        default: Optional[str] = None,
+        required: bool = False,
+        docs_url: Optional[str] = None,
+    ) -> Optional[str]:
+        """Resolve value with CLI > ENV > CONFIG > DEFAULT precedence."""
+        ctx = {"name": name, "required": required, "has_cli": cli_value is not None, "has_env": env_value is not None}
+        log_info("ConfigResolver.resolve invoked", ctx=ctx)
+
+        def _clean(value: Optional[str]) -> Optional[str]:
+            if value is None:
+                return None
+            stripped = value.strip()
+            return stripped if stripped else None
+
+        cli_clean = _clean(cli_value)
+        env_clean = _clean(env_value)
+        config_clean = _clean(config_value)
+        default_clean = _clean(default)
+
+        if cli_clean and config_clean and cli_clean != config_clean:
+            click.secho(
+                f"⚠️  {name}: CLI flag overrides config file "
+                f"(using {cli_clean}, ignoring {config_clean})",
+                err=True,
+                fg="yellow",
+            )
+
+        resolved = cli_clean or env_clean or config_clean or default_clean
+        if required:
+            return _get_required_value(
+                name,
+                cli_value=cli_clean,
+                env_value=env_clean,
+                config_value=config_clean,
+                default=default_clean,
+                docs_url=docs_url,
+            )
+        return resolved

synth_ai/core/env.py

@@ -0,0 +1,231 @@
+"""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://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)
+        if not base:
+            raise ConfigError("BACKEND_OVERRIDE is set but empty or invalid")
+        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")
+        # If explicitly set to empty string, use default
+        if not base or not base.strip():
+            base = "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"
+        # If explicitly set to empty string, use default
+        if not base or not base.strip():
+            base = "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)
+    # If explicitly set to empty string, use default
+    if not base or not base.strip():
+        base = 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",
+]
+