synth-ai 0.2.16__py3-none-any.whl → 0.2.19__py3-none-any.whl

synth_ai/cli/commands/filter/errors.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class FilterCliError(RuntimeError):
+    """Base exception for filter CLI failures."""
+
+
+@dataclass(slots=True)
+class TomlUnavailableError(FilterCliError):
+    hint: str | None = None
+
+
+@dataclass(slots=True)
+class FilterConfigNotFoundError(FilterCliError):
+    path: str
+
+
+@dataclass(slots=True)
+class FilterConfigParseError(FilterCliError):
+    path: str
+    detail: str
+
+
+@dataclass(slots=True)
+class MissingFilterTableError(FilterCliError):
+    """Raised when the filter config lacks a [filter] table."""
+
+
+@dataclass(slots=True)
+class InvalidFilterConfigError(FilterCliError):
+    detail: str
+
+
+@dataclass(slots=True)
+class NoTracesFoundError(FilterCliError):
+    db_url: str
+
+
+@dataclass(slots=True)
+class NoSessionsMatchedError(FilterCliError):
+    hint: str | None = None
+
+
+__all__ = [
+    "FilterCliError",
+    "TomlUnavailableError",
+    "FilterConfigNotFoundError",
+    "FilterConfigParseError",
+    "MissingFilterTableError",
+    "InvalidFilterConfigError",
+    "NoTracesFoundError",
+    "NoSessionsMatchedError",
+]

synth_ai/cli/commands/filter/validation.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import math
+from collections.abc import MutableMapping
+from typing import Any
+
+__all__ = ["validate_filter_options"]
+
+
+def validate_filter_options(options: MutableMapping[str, Any]) -> MutableMapping[str, Any]:
+    """Validate parameters passed to the filter CLI command."""
+    # Coerce optional collections to the expected container types and strip blanks
+    result: dict[str, Any] = dict(options)
+
+    def _coerce_list(key: str) -> None:
+        value = result.get(key)
+        if value is None:
+            result[key] = []
+        elif isinstance(value, list | tuple | set):
+            result[key] = [str(item).strip() for item in value if str(item).strip()]
+        else:
+            result[key] = [str(value).strip()] if str(value).strip() else []
+
+    def _coerce_dict(key: str) -> None:
+        value = result.get(key)
+        if value is None:
+            result[key] = {}
+        elif isinstance(value, MutableMapping):
+            normalized: dict[str, float] = {}
+            for k, v in value.items():
+                if k is None:
+                    continue
+                try:
+                    number = float(v)
+                    if math.isnan(number) or math.isinf(number):
+                        continue
+                    normalized[str(k).strip()] = number
+                except Exception:
+                    continue
+            result[key] = normalized
+        else:
+            result[key] = {}
+
+    _coerce_list("splits")
+    _coerce_list("task_ids")
+    _coerce_list("models")
+    _coerce_dict("min_judge_scores")
+    _coerce_dict("max_judge_scores")
+
+    for duration_key in ("min_official_score", "max_official_score"):
+        value = result.get(duration_key)
+        if value is None or value == "":
+            result[duration_key] = None
+        else:
+            try:
+                result[duration_key] = float(value)
+            except Exception:
+                result[duration_key] = None
+
+    for int_key in ("limit", "offset", "shuffle_seed"):
+        value = result.get(int_key)
+        if value is None or value == "":
+            result[int_key] = None
+        else:
+            try:
+                result[int_key] = int(value)
+            except Exception:
+                result[int_key] = None
+
+    shuffle_value = result.get("shuffle")
+    if isinstance(shuffle_value, str):
+        result["shuffle"] = shuffle_value.strip().lower() in {"1", "true", "yes"}
+    else:
+        result["shuffle"] = bool(shuffle_value)
+
+    # Preserve extra keys (e.g., min_created_at) as-is for downstream handling
+    return result

synth_ai/cli/commands/help/__init__.py

@@ -0,0 +1,177 @@
+"""Help content for CLI commands."""
+
+DEPLOY_HELP = """
+Deploy a Synth AI task app locally or to Modal.
+
+OVERVIEW
+--------
+The deploy command supports two runtimes:
+  • modal: Deploy to Modal's cloud platform (default)
+  • uvicorn: Run locally with FastAPI/Uvicorn
+
+BASIC USAGE
+-----------
+  # Deploy to Modal (production)
+  uvx synth-ai deploy
+
+  # Deploy specific task app
+  uvx synth-ai deploy my-math-app
+
+  # Run locally for development
+  uvx synth-ai deploy --runtime=uvicorn --port 8001
+
+MODAL DEPLOYMENT
+----------------
+Modal deployment requires:
+  1. Modal authentication (run: modal token new)
+  2. ENVIRONMENT_API_KEY (run: uvx synth-ai setup)
+
+Options:
+  --modal-mode [deploy|serve]  Use 'deploy' for production (default), 
+                                'serve' for ephemeral development
+  --name TEXT                   Override Modal app name
+  --dry-run                     Preview the deploy command without executing
+  --env-file PATH               Env file(s) to load (can be repeated)
+
+Examples:
+  # Standard production deployment
+  uvx synth-ai deploy --runtime=modal
+
+  # Deploy with custom name
+  uvx synth-ai deploy --runtime=modal --name my-task-app-v2
+
+  # Preview deployment command
+  uvx synth-ai deploy --dry-run
+
+  # Deploy with custom env file
+  uvx synth-ai deploy --env-file .env.production
+
+LOCAL DEVELOPMENT
+-----------------
+Run locally with auto-reload and tracing:
+
+  uvx synth-ai deploy --runtime=uvicorn --port 8001 --reload
+
+Options:
+  --host TEXT                   Bind address (default: 0.0.0.0)
+  --port INTEGER                Port number (prompted if not provided)
+  --reload/--no-reload          Enable auto-reload on code changes
+  --force/--no-force            Kill existing process on port
+  --trace PATH                  Enable tracing to directory (default: traces/v3)
+  --trace-db PATH               SQLite DB for traces
+
+Examples:
+  # Basic local server
+  uvx synth-ai deploy --runtime=uvicorn
+
+  # Development with auto-reload
+  uvx synth-ai deploy --runtime=uvicorn --reload --port 8001
+
+  # With custom trace directory
+  uvx synth-ai deploy --runtime=uvicorn --trace ./my-traces
+
+TROUBLESHOOTING
+---------------
+Common issues:
+
+1. "ENVIRONMENT_API_KEY is required"
+   → Run: uvx synth-ai setup
+
+2. "Modal CLI not found"
+   → Install: pip install modal
+   → Authenticate: modal token new
+
+3. "Task app not found"
+   → Check app_id matches your task_app.py configuration
+   → Run: uvx synth-ai task-app list (if available)
+
+4. "Port already in use" (uvicorn)
+   → Use --force to kill existing process
+   → Or specify different --port
+
+5. "No env file discovered"
+   → Create .env file with required keys
+   → Or pass --env-file explicitly
+
+ENVIRONMENT VARIABLES
+---------------------
+  SYNTH_API_KEY              Your Synth platform API key
+  ENVIRONMENT_API_KEY        Task environment authentication
+  TASK_APP_BASE_URL          Base URL for deployed task app
+  DEMO_DIR                   Demo directory path
+  SYNTH_DEMO_DIR             Alternative demo directory
+
+For more information: https://docs.usesynth.ai/deploy
+"""
+
+SETUP_HELP = """
+Configure Synth AI credentials and environment.
+
+OVERVIEW
+--------
+The setup command initializes your Synth AI environment by:
+  1. Authenticating with the Synth platform via browser
+  2. Saving your API keys to ~/.synth/config
+  3. Verifying Modal authentication (for deployments)
+  4. Testing connectivity to backend services
+
+USAGE
+-----
+  uvx synth-ai setup
+
+The command will:
+  • Open your browser for authentication (or prompt for manual entry)
+  • Save SYNTH_API_KEY and ENVIRONMENT_API_KEY
+  • Verify Modal is authenticated
+  • Test backend connectivity
+
+WHAT YOU'LL NEED
+----------------
+  • Web browser for authentication
+  • Modal account (for deployments): https://modal.com
+  • Active internet connection
+
+TROUBLESHOOTING
+---------------
+1. "Failed to fetch keys from frontend"
+   → You'll be prompted to enter keys manually
+   → Get keys from: https://www.usesynth.ai/dashboard/settings
+
+2. "Modal authentication status: not authenticated"
+   → Run: modal token new
+   → Then re-run: uvx synth-ai setup
+
+3. Browser doesn't open
+   → Check your default browser settings
+   → Or enter keys manually when prompted
+
+WHERE ARE KEYS STORED?
+----------------------
+Keys are saved to: ~/.synth/config
+
+This file is read automatically by all Synth AI commands.
+You can also use .env files in your project directory.
+
+NEXT STEPS
+----------
+After setup completes:
+  1. Deploy your task app: uvx synth-ai deploy
+  2. Start local development: uvx synth-ai deploy --runtime=uvicorn
+  3. Run training: uvx synth-ai train
+
+For more information: https://docs.usesynth.ai/setup
+"""
+
+COMMAND_HELP = {
+    "deploy": DEPLOY_HELP,
+    "setup": SETUP_HELP,
+}
+
+
+def get_command_help(command: str) -> str | None:
+    """Get detailed help text for a command."""
+    return COMMAND_HELP.get(command)
+
+
+__all__ = ["DEPLOY_HELP", "SETUP_HELP", "COMMAND_HELP", "get_command_help"]
+

synth_ai/cli/commands/help/core.py

@@ -0,0 +1,72 @@
+"""Help command implementation."""
+
+import click
+from click.exceptions import Exit
+
+from . import COMMAND_HELP, get_command_help
+
+
+@click.command("help")
+@click.argument("command_name", type=str, required=False)
+def help_command(command_name: str | None) -> None:
+    """Display detailed help for Synth AI commands.
+    
+    USAGE
+    -----
+      uvx synth-ai help [COMMAND]
+    
+    EXAMPLES
+    --------
+      # List available help topics
+      uvx synth-ai help
+      
+      # Get detailed help for deploy
+      uvx synth-ai help deploy
+      
+      # Get detailed help for setup
+      uvx synth-ai help setup
+    """
+    if not command_name:
+        # Show list of available help topics
+        click.echo("Synth AI - Detailed Help")
+        click.echo("=" * 50)
+        click.echo("\nAvailable help topics:")
+        click.echo("")
+        
+        for cmd in sorted(COMMAND_HELP.keys()):
+            click.echo(f"  • {cmd}")
+        
+        click.echo("\nUsage:")
+        click.echo("  uvx synth-ai help [COMMAND]")
+        click.echo("")
+        click.echo("Examples:")
+        click.echo("  uvx synth-ai help deploy")
+        click.echo("  uvx synth-ai help setup")
+        click.echo("")
+        click.echo("You can also use standard --help flags:")
+        click.echo("  uvx synth-ai deploy --help")
+        click.echo("  uvx synth-ai setup --help")
+        return
+    
+    # Show detailed help for specific command
+    help_text = get_command_help(command_name)
+    if not help_text:
+        click.echo(f"No detailed help available for '{command_name}'", err=True)
+        click.echo(f"\nTry: uvx synth-ai {command_name} --help", err=True)
+        click.echo("Or: uvx synth-ai help (to see available topics)", err=True)
+        raise Exit(1)
+    
+    click.echo(help_text)
+
+
+def get_command() -> click.Command:
+    """Get the help command for registration."""
+    return help_command
+
+
+def register(group: click.Group) -> None:
+    """Register the help command with a Click group."""
+    group.add_command(help_command)
+
+
+__all__ = ["help_command", "get_command", "register"]

synth_ai/cli/commands/smoke/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .core import command, register
+
+__all__ = ["command", "register"]
+
+