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

synth_ai/core/cfgs.py

@@ -0,0 +1,240 @@
+import os
+from pathlib import Path
+from typing import Any, Literal, Optional, cast
+
+from pydantic import BaseModel
+
+from synth_ai.core.paths import get_bin_path
+from synth_ai.core.telemetry import log_error, log_info
+
+
+class LocalDeployCfg(BaseModel):
+    task_app_path: Path
+    env_api_key: str
+    trace: bool = True
+    host: str = "127.0.0.1"
+    port: int = 8000
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        task_app_path: Path,
+        env_api_key: str,
+        trace: bool = True,
+        host: str = "127.0.0.1",
+        port: int = 8000
+    ) -> "LocalDeployCfg":
+        ctx: dict[str, Any] = {
+            "task_app_path": str(task_app_path),
+            "trace": trace,
+            "host": host,
+            "port": port,
+        }
+        log_info("creating LocalDeployCfg", ctx=ctx)
+        try:
+            cfg = cls(
+                task_app_path=task_app_path,
+                env_api_key=env_api_key,
+                trace=trace,
+                host=host,
+                port=port,
+            )
+            return cfg
+        except Exception as exc:
+            ctx["error"] = type(exc).__name__
+            log_error("LocalDeployCfg creation failed", ctx=ctx)
+            raise
+
+    @classmethod
+    def create_from_dict(
+        cls,
+        data: dict[str, Any]
+    ) -> "LocalDeployCfg":
+        path = Path(data["task_app_path"])
+        trace = bool(data.get("trace", True))
+        host = str(data.get("host", "127.0.0.1"))
+        port = int(data.get("port", 8000))
+        ctx: dict[str, Any] = {
+            "task_app_path": str(path),
+            "trace": trace,
+            "host": host,
+            "port": port,
+        }
+        log_info("creating LocalDeployCfg from dict", ctx=ctx)
+        env_api_key = data.get("env_api_key")
+        if not env_api_key or not isinstance(env_api_key, str):
+            raise ValueError("env_api_key is required in local deploy configuration")
+
+        try:
+            cfg = cls(
+                task_app_path=path,
+                env_api_key=env_api_key,
+                trace=trace,
+                host=host,
+                port=port,
+            )
+            return cfg
+        except (KeyError, TypeError, ValueError) as err:
+            ctx["error"] = type(err).__name__
+            log_error("LocalDeployCfg from dict failed", ctx=ctx)
+            raise ValueError(f"Invalid local deploy configuration: {err}") from err
+        
+
+class ModalDeployCfg(BaseModel):
+    task_app_path: Path
+    modal_app_path: Path
+    modal_bin_path: Path
+    synth_api_key: str
+    env_api_key: str
+    cmd_arg: Literal["deploy", "serve"] = "deploy"
+    modal_app_name: Optional[str] = None
+    dry_run: bool = False
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        task_app_path: Path,
+        modal_app_path: Path,
+        synth_api_key: str,
+        env_api_key: str,
+        modal_bin_path: Path | None = None,
+        cmd_arg: Literal["deploy", "serve"] = "deploy",
+        modal_app_name: Optional[str] = None,
+        dry_run: bool = False,
+    ) -> "ModalDeployCfg":
+        ctx: dict[str, Any] = {
+            "task_app_path": str(task_app_path),
+            "modal_app_path": str(modal_app_path),
+            "cmd_arg": cmd_arg,
+            "dry_run": dry_run,
+            "modal_app_name": modal_app_name,
+            "modal_bin_path": str(modal_bin_path) if modal_bin_path else None,
+        }
+        log_info("creating ModalDeployCfg", ctx=ctx)
+        modal_bin_path = modal_bin_path or get_bin_path("modal")
+        if modal_bin_path is None:
+            ctx["error"] = "ModalCLINotFound"
+            log_error("ModalDeployCfg creation failed", ctx=ctx)
+            raise ValueError("Modal CLI not found; install `modal` or pass --modal-cli with its path.")
+        ctx["modal_bin_path"] = str(modal_bin_path)
+        try:
+            cfg = cls(
+                task_app_path=task_app_path,
+                modal_app_path=modal_app_path,
+                modal_bin_path=modal_bin_path,
+                synth_api_key=synth_api_key,
+                env_api_key=env_api_key,
+                cmd_arg=cmd_arg,
+                modal_app_name=modal_app_name,
+                dry_run=dry_run,
+            )
+            return cfg
+        except Exception as exc:
+            ctx["error"] = type(exc).__name__
+            log_error("ModalDeployCfg creation failed", ctx=ctx)
+            raise
+
+    @classmethod
+    def create_from_kwargs(cls, **kwargs: Any) -> "ModalDeployCfg":
+        ctx: dict[str, Any] = {**kwargs}
+        log_info("creating ModalDeployCfg from kwargs", ctx=ctx)
+
+        synth_api_key = kwargs.get("synth_api_key")
+        if not synth_api_key or not isinstance(synth_api_key, str):
+            raise ValueError("synth_api_key must be provided as a string")
+        env_api_key = kwargs.get("env_api_key")
+        if not env_api_key or not isinstance(env_api_key, str):
+            raise ValueError("env_api_key must be provided as a string")
+
+        cmd_arg = str(kwargs.get("modal_mode", "deploy")).strip().lower()
+        if cmd_arg not in {"deploy", "serve"}:
+            raise ValueError("`--modal-mode` must be either 'deploy' or 'serve'.")
+
+        dry_run = bool(kwargs.get("dry_run", False))
+        if dry_run and os.getenv("CTX") == "mcp":
+            ctx["error"] = "dry_run_mcp"
+            log_error("ModalDeployCfg create_from_kwargs blocked", ctx=ctx)
+            raise ValueError("`synth-ai deploy --runtime modal --dry-run` cannot be used by MCP")
+        if dry_run and cmd_arg == "serve":
+            ctx["error"] = "dry_run_serve"
+            log_error("ModalDeployCfg create_from_kwargs blocked", ctx=ctx)
+            raise ValueError("`synth-ai deploy --runtime modal --modal-mode serve` cannot be used with `--dry-run`")
+
+        modal_bin_path_arg = kwargs.get("modal_cli")
+        modal_bin_path = Path(str(modal_bin_path_arg)).expanduser() if modal_bin_path_arg else get_bin_path("modal")
+        if modal_bin_path is None or not modal_bin_path.exists():
+            ctx["error"] = "ModalCLINotFound"
+            log_error("ModalDeployCfg create_from_kwargs failed", ctx=ctx)
+            raise ValueError('Modal binary not found via shutil.which("modal"). Install `modal` or pass --modal-cli with its path.')
+        modal_bin_path = modal_bin_path.resolve()
+
+        modal_app_name = kwargs.get("name")
+        if modal_app_name is not None:
+            modal_app_name = str(modal_app_name).strip() or None
+
+        literal_cmd = cast(Literal["deploy", "serve"], cmd_arg)
+
+        task_app_path = kwargs.get("task_app_path")
+        modal_app_path = kwargs.get("modal_app")
+
+        if not task_app_path:
+            raise ValueError("task_app_path is required")
+        if not modal_app_path:
+            raise ValueError("modal_app is required")
+
+        if not isinstance(task_app_path, Path):
+            task_app_path = Path(task_app_path)
+        if not isinstance(modal_app_path, Path):
+            modal_app_path = Path(modal_app_path)
+
+        try:
+            cfg = cls(
+                task_app_path=task_app_path,
+                modal_app_path=modal_app_path,
+                modal_bin_path=modal_bin_path,
+                synth_api_key=synth_api_key,
+                env_api_key=env_api_key,
+                cmd_arg=literal_cmd,
+                modal_app_name=modal_app_name,
+                dry_run=dry_run,
+            )
+            return cfg
+        except Exception as exc:
+            ctx["error"] = type(exc).__name__
+            log_error("ModalDeployCfg from kwargs failed", ctx=ctx)
+            raise
+
+
+class CFDeployCfg(BaseModel):
+    task_app_path: Path
+    env_api_key: str
+    host: str = "127.0.0.1"
+    port: int = 8000
+    mode: Literal["quick", "managed"] = "quick"
+    tunnel_token: Optional[str] = None
+    subdomain: Optional[str] = None
+    trace: bool = True
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        task_app_path: Path,
+        env_api_key: str,
+        host: str = "127.0.0.1",
+        port: int = 8000,
+        mode: Literal["quick", "managed"] = "quick",
+        subdomain: Optional[str] = None,
+        trace: bool = True,
+    ) -> "CFDeployCfg":
+        return cls(
+            task_app_path=task_app_path,
+            env_api_key=env_api_key,
+            host=host,
+            port=port,
+            mode=mode,
+            subdomain=subdomain,
+            trace=trace,
+        )

synth_ai/core/config/__init__.py

@@ -0,0 +1,16 @@
+"""Configuration base classes and utilities.
+
+This module provides base classes for job configs and common
+configuration patterns used across the SDK.
+"""
+
+from __future__ import annotations
+
+from .base import BaseJobConfig, ConfigValidator
+
+__all__ = [
+    "BaseJobConfig",
+    "ConfigValidator",
+]
+
+

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