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

synth_ai/cli/commands/help/__init__.py

@@ -0,0 +1,185 @@
+"""Help content for CLI commands."""
+
+DEPLOY_HELP = """
+Deploy a Synth AI task app locally, to Modal, or via Cloudflare Tunnel.
+
+OVERVIEW
+--------
+The deploy command supports three runtimes:
+  • modal: Deploy to Modal's cloud platform (default)
+  • local: Run locally with FastAPI/Uvicorn
+  • tunnel: Expose local app via Cloudflare Tunnel (for RL/prompt optimization)
+
+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=local --port 8001
+
+  # Deploy via Cloudflare Tunnel (for training)
+  uvx synth-ai deploy --runtime=tunnel --tunnel-mode quick
+
+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" (local/tunnel)
+   → Use --force to kill existing process
+   → Or specify different --port
+
+5. "cloudflared not found" (tunnel)
+   → Install: brew install cloudflare/cloudflare/cloudflared
+   → Or: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/
+
+6. "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/scan/__init__.py

@@ -0,0 +1,19 @@
+"""Scan command for discovering active task apps."""
+
+from __future__ import annotations
+
+import click
+
+from synth_ai.cli.commands.scan.core import scan_command
+
+
+def register(cli: click.Group) -> None:
+    """Register the scan command with the CLI."""
+    cli.add_command(scan_command)
+
+
+
+
+
+
+

synth_ai/cli/commands/scan/cloudflare_scanner.py

@@ -0,0 +1,403 @@
+"""Cloudflare app discovery for scan command."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from synth_ai.cli.commands.scan.health_checker import check_app_health, extract_app_info
+from synth_ai.cli.commands.scan.models import ScannedApp
+from synth_ai.core.urls import BACKEND_URL_BASE
+
+# Regex for parsing quick tunnel URLs from cloudflared output
+_QUICK_TUNNEL_URL_RE = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com", re.I)
+
+
+def scan_cloudflare_processes() -> list[dict[str, Any]]:
+    """Scan running cloudflared processes to find tunnels.
+
+    Returns:
+        List of tunnel info dicts with keys: port, mode, pid, cmdline, url (if discoverable)
+    """
+    tunnels: list[dict[str, Any]] = []
+
+    # Try using psutil if available
+    try:
+        import psutil  # type: ignore[import-untyped]
+
+        for proc in psutil.process_iter(["pid", "name", "cmdline"]):
+            try:
+                if proc.info["name"] and "cloudflared" in proc.info["name"].lower():
+                    cmdline = proc.info.get("cmdline") or []
+                    pid = proc.info.get("pid")
+                    
+                    # Check for quick tunnel: cloudflared tunnel --url http://127.0.0.1:PORT
+                    for i, arg in enumerate(cmdline):
+                        if arg == "--url" and i + 1 < len(cmdline):
+                            local_url = cmdline[i + 1]
+                            # Extract port from URL like http://127.0.0.1:8000
+                            port_match = re.search(r":(\d+)$", local_url)
+                            if port_match:
+                                port = int(port_match.group(1))
+                                # Try to get tunnel URL from process stdout/stderr or log files
+                                tunnel_url = _try_get_quick_tunnel_url(pid, port)
+                                tunnels.append({
+                                    "port": port,
+                                    "mode": "quick",
+                                    "pid": pid,
+                                    "cmdline": cmdline,
+                                    "url": tunnel_url,
+                                    "local_url": local_url,
+                                })
+                            break
+                        
+                        # Check for managed tunnel: cloudflared tunnel run --token TOKEN
+                        if arg == "run" and i > 0 and cmdline[i - 1] == "tunnel":
+                            # Managed tunnel - we can't get URL from process alone
+                            tunnels.append({
+                                "port": None,  # Unknown from process
+                                "mode": "managed",
+                                "pid": pid,
+                                "cmdline": cmdline,
+                                "url": None,  # Need backend API
+                            })
+                            break
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                continue
+    except ImportError:
+        # Fallback to subprocess + ps/pgrep
+        try:
+            result = subprocess.run(
+                ["pgrep", "-fl", "cloudflared"],
+                capture_output=True,
+                text=True,
+                timeout=2.0,
+            )
+            if result.returncode == 0:
+                for line in result.stdout.splitlines():
+                    # Parse line like "12345 cloudflared tunnel --url http://127.0.0.1:8000"
+                    parts = line.split(None, 1)
+                    if len(parts) < 2:
+                        continue
+                    pid_str, rest = parts
+                    try:
+                        pid = int(pid_str)
+                    except ValueError:
+                        continue
+                    
+                    # Check for quick tunnel
+                    url_match = re.search(r"--url\s+(\S+)", rest)
+                    if url_match:
+                        local_url = url_match.group(1)
+                        port_match = re.search(r":(\d+)$", local_url)
+                        if port_match:
+                            port = int(port_match.group(1))
+                            tunnel_url = _try_get_quick_tunnel_url(pid, port)
+                            tunnels.append({
+                                "port": port,
+                                "mode": "quick",
+                                "pid": pid,
+                                "cmdline": rest.split(),
+                                "url": tunnel_url,
+                                "local_url": local_url,
+                            })
+                    # Check for managed tunnel
+                    elif "tunnel run" in rest or "tunnel run --token" in rest:
+                        tunnels.append({
+                            "port": None,
+                            "mode": "managed",
+                            "pid": pid,
+                            "cmdline": rest.split(),
+                            "url": None,
+                        })
+        except Exception:
+            pass
+
+    return tunnels
+
+
+def _try_get_quick_tunnel_url(pid: int | None, port: int) -> str | None:
+    """Try to get quick tunnel URL from process stdout/stderr or log files.
+    
+    Args:
+        pid: Process ID
+        port: Local port being tunneled
+        
+    Returns:
+        Tunnel URL if found, None otherwise
+    """
+    if pid is None:
+        return None
+    
+    # Try to read from common log file locations
+    log_paths = [
+        Path(f"/tmp/cloudflared_{port}.log"),
+        Path.home() / f".cloudflared_{port}.log",
+        Path(f"/tmp/cloudflared_{pid}.log"),
+    ]
+    
+    for log_path in log_paths:
+        try:
+            if log_path.exists():
+                with log_path.open("r") as f:
+                    content = f.read()
+                    match = _QUICK_TUNNEL_URL_RE.search(content)
+                    if match:
+                        return match.group(0)
+        except Exception:
+            continue
+    
+    # Try to read from process file descriptors (if accessible)
+    try:
+        import psutil  # type: ignore[import-untyped]
+        proc = psutil.Process(pid)
+        # Try to read from stdout/stderr if they're pipes/files
+        for fd in [proc.stdout, proc.stderr]:
+            if fd and hasattr(fd, 'read'):
+                try:
+                    # Read last few KB
+                    content = fd.read(8192) if hasattr(fd, 'read') else None
+                    if content:
+                        if isinstance(content, bytes):
+                            content = content.decode('utf-8', errors='ignore')
+                        match = _QUICK_TUNNEL_URL_RE.search(content)
+                        if match:
+                            return match.group(0)
+                except Exception:
+                    pass
+    except Exception:
+        pass
+    
+    return None
+
+
+async def fetch_managed_tunnels(api_key: str | None) -> list[dict[str, Any]]:
+    """Fetch active managed tunnels from backend API.
+
+    Args:
+        api_key: SYNTH_API_KEY for authentication
+
+    Returns:
+        List of tunnel metadata dicts
+    """
+    if not api_key:
+        return []
+
+    try:
+        headers: dict[str, str] = {}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            url = f"{BACKEND_URL_BASE.rstrip('/')}/api/v1/tunnels/"
+            resp = await client.get(url, headers=headers)
+            if resp.status_code == 200:
+                data = resp.json()
+                if isinstance(data, list):
+                    # Filter for active tunnels
+                    return [t for t in data if isinstance(t, dict) and t.get("status") == "active"]
+    except Exception:
+        pass
+
+    return []
+
+
+def get_tunnel_processes() -> dict[int, Any]:
+    """Get tunnel processes from global state.
+
+    Returns:
+        Dict mapping port -> process handle
+    """
+    try:
+        from synth_ai.core.integrations.cloudflare import _TUNNEL_PROCESSES
+
+        return _TUNNEL_PROCESSES.copy()
+    except Exception:
+        return {}
+
+
+async def scan_cloudflare_apps(
+    api_key: str | None,
+    env_api_key: str | None,
+    env_file: Path | None = None,
+    timeout: float = 2.0,
+) -> list[ScannedApp]:
+    """Scan for Cloudflare tunnel apps using process-based discovery.
+
+    Args:
+        api_key: SYNTH_API_KEY for backend API
+        env_api_key: ENVIRONMENT_API_KEY for health checks
+        env_file: Not used (kept for API compatibility)
+        timeout: Health check timeout
+
+    Returns:
+        List of discovered ScannedApp instances
+    """
+    apps: list[ScannedApp] = []
+    seen_urls: set[str] = set()
+
+    # Method 1: Check cloudflared processes (primary discovery method)
+    process_tunnels = scan_cloudflare_processes()
+    for tunnel_info in process_tunnels:
+        tunnel_url = tunnel_info.get("url")
+        port = tunnel_info.get("port")
+        mode = tunnel_info.get("mode")
+        pid = tunnel_info.get("pid")
+        
+        if mode == "quick" and tunnel_url:
+            # Quick tunnel with discovered URL
+            if tunnel_url not in seen_urls:
+                seen_urls.add(tunnel_url)
+                health_status, metadata = await check_app_health(tunnel_url, env_api_key, timeout)
+                app_id, task_name, dataset_id, version = extract_app_info(metadata)
+                
+                tunnel_hostname = tunnel_url.replace("https://", "").split("/")[0]
+                name = app_id or task_name or tunnel_hostname or tunnel_url
+                
+                apps.append(
+                    ScannedApp(
+                        name=name,
+                        url=tunnel_url,
+                        type="cloudflare",
+                        health_status=health_status,
+                        port=port,
+                        tunnel_mode="quick",
+                        tunnel_hostname=tunnel_hostname,
+                        app_id=app_id,
+                        task_name=task_name,
+                        dataset_id=dataset_id,
+                        version=version,
+                        metadata={**metadata, "pid": pid, "local_port": port},
+                        discovered_via="cloudflared_process",
+                    )
+                )
+        elif mode == "quick" and port:
+            # Quick tunnel process found but URL not discoverable
+            # We know there's a tunnel but can't get the public URL
+            # Skip for now - could potentially match with backend API later
+            pass
+        elif mode == "managed":
+            # Managed tunnel - need backend API to get URL
+            # Will be handled by backend API query below
+            pass
+
+    # Method 2: Query backend API for managed tunnels
+    synth_api_key = api_key or os.getenv("SYNTH_API_KEY")
+    managed_tunnels = await fetch_managed_tunnels(synth_api_key)
+    for tunnel in managed_tunnels:
+        hostname = tunnel.get("hostname")
+        local_port = tunnel.get("local_port")
+        if hostname:
+            url = f"https://{hostname}"
+            if url not in seen_urls:
+                seen_urls.add(url)
+                health_status, metadata = await check_app_health(url, env_api_key, timeout)
+                app_id, task_name, dataset_id, version = extract_app_info(metadata)
+
+                name = app_id or task_name or hostname.split(".")[0] or url
+
+                apps.append(
+                    ScannedApp(
+                        name=name,
+                        url=url,
+                        type="cloudflare",
+                        health_status=health_status,
+                        port=local_port,
+                        tunnel_mode="managed",
+                        tunnel_hostname=hostname,
+                        app_id=app_id,
+                        task_name=task_name,
+                        dataset_id=dataset_id,
+                        version=version,
+                        metadata={**metadata, **tunnel},
+                        discovered_via="backend_api",
+                    )
+                )
+
+    # Method 3: Check global tunnel processes state (if tunnels started in same Python process)
+    tunnel_procs = get_tunnel_processes()
+    for port, proc in tunnel_procs.items():
+        # These are tunnels we started - try to match with discovered URLs
+        # or check if we can get URL from process
+        if proc and proc.poll() is None:  # Process still running
+            # Try to get URL from quick tunnel
+            tunnel_url = _try_get_quick_tunnel_url(proc.pid, port)
+            if tunnel_url and tunnel_url not in seen_urls:
+                seen_urls.add(tunnel_url)
+                health_status, metadata = await check_app_health(tunnel_url, env_api_key, timeout)
+                app_id, task_name, dataset_id, version = extract_app_info(metadata)
+                
+                tunnel_hostname = tunnel_url.replace("https://", "").split("/")[0]
+                name = app_id or task_name or tunnel_hostname or tunnel_url
+                
+                apps.append(
+                    ScannedApp(
+                        name=name,
+                        url=tunnel_url,
+                        type="cloudflare",
+                        health_status=health_status,
+                        port=port,
+                        tunnel_mode="quick",
+                        tunnel_hostname=tunnel_hostname,
+                        app_id=app_id,
+                        task_name=task_name,
+                        dataset_id=dataset_id,
+                        version=version,
+                        metadata={**metadata, "pid": proc.pid},
+                        discovered_via="cloudflared_process",
+                    )
+                )
+
+    # Method 4: Check service records file (tunnels deployed via synth-ai)
+    try:
+        from synth_ai.cli.lib.tunnel_records import cleanup_stale_records, load_service_records
+        
+        # Clean up stale records first
+        cleanup_stale_records()
+        
+        records = load_service_records()
+        # Filter for tunnels only
+        records = {k: v for k, v in records.items() if v.get("type") == "tunnel"}
+        for _, record in records.items():
+            tunnel_url = record.get("url")
+            port = record.get("port")
+            mode = record.get("mode", "quick")
+            hostname = record.get("hostname")
+            
+            if tunnel_url and tunnel_url not in seen_urls:
+                seen_urls.add(tunnel_url)
+                health_status, metadata = await check_app_health(tunnel_url, env_api_key, timeout)
+                app_id, task_name, dataset_id, version = extract_app_info(metadata)
+                
+                if not hostname and tunnel_url.startswith("https://"):
+                    hostname = tunnel_url.replace("https://", "").split("/")[0]
+                
+                name = app_id or task_name or hostname or tunnel_url
+                
+                apps.append(
+                    ScannedApp(
+                        name=name,
+                        url=tunnel_url,
+                        type="cloudflare",
+                        health_status=health_status,
+                        port=port,
+                        tunnel_mode=mode,
+                        tunnel_hostname=hostname,
+                        app_id=app_id,
+                        task_name=task_name,
+                        dataset_id=dataset_id,
+                        version=version,
+                        metadata={**metadata, **record},
+                        discovered_via="tunnel_records",
+                    )
+                )
+    except Exception:
+        pass  # Fail silently if records unavailable
+
+    return apps
+