synth-ai 0.2.9.dev0__py3-none-any.whl → 0.2.23.dev3__py3-none-any.whl

synth_ai/tracing_v3/utils.py

@@ -1,16 +1,17 @@
-from __future__ import annotations
 """Utility functions for tracing v3."""
 
+from __future__ import annotations
+
 import hashlib
 import json
 import uuid
-from datetime import datetime
+from datetime import UTC, datetime
 from typing import Any
 
 
 def iso_now() -> str:
-    """Get current UTC time as ISO format string."""
-    return datetime.utcnow().isoformat()
+    """Get current timezone.utc time as ISO format string."""
+    return datetime.now(UTC).isoformat()
 
 
 def json_dumps(obj: Any) -> str:

synth_ai/tunnel.py

@@ -0,0 +1,143 @@
+"""
+Cloudflare Tunnel client module.
+
+Provides functions to spawn and manage cloudflared processes for quick and managed tunnels.
+"""
+import os
+import re
+import shutil
+import subprocess
+import time
+from typing import Optional, Tuple
+
+_URL_RE = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com", re.I)
+
+
+def _which_cloudflared() -> str:
+    """Find cloudflared binary in PATH or common install locations."""
+    path = shutil.which("cloudflared")
+    if path:
+        return path
+    
+    # Check common install locations
+    common_paths = [
+        "/usr/local/bin/cloudflared",
+        "/opt/homebrew/bin/cloudflared",
+        os.path.expanduser("~/bin/cloudflared"),
+    ]
+    for common_path in common_paths:
+        if os.path.exists(common_path) and os.access(common_path, os.X_OK):
+            return common_path
+    
+    raise FileNotFoundError(
+        "cloudflared not found. Install it:\n"
+        "  macOS: brew install cloudflare/cloudflare/cloudflared\n"
+        "  Linux/Windows: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/create-local-tunnel/"
+    )
+
+
+def open_quick_tunnel(port: int, wait_s: float = 10.0) -> Tuple[str, subprocess.Popen]:
+    """
+    Open a quick (ephemeral) Cloudflare tunnel.
+    
+    Args:
+        port: Local port to tunnel to
+        wait_s: Maximum time to wait for URL in seconds
+    
+    Returns:
+        Tuple of (public_url, process_handle)
+    
+    Raises:
+        FileNotFoundError: If cloudflared is not installed
+        RuntimeError: If tunnel fails to start or URL cannot be parsed
+    """
+    bin_path = _which_cloudflared()
+    proc = subprocess.Popen(
+        [bin_path, "tunnel", "--url", f"http://127.0.0.1:{port}"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    
+    start = time.time()
+    url: Optional[str] = None
+    
+    # Stream stdout to detect the trycloudflare URL
+    while time.time() - start < wait_s:
+        if proc.poll() is not None:
+            # Process exited early
+            stdout, _ = proc.communicate()
+            raise RuntimeError(
+                f"cloudflared exited early with code {proc.returncode}. "
+                f"Output: {stdout[:500] if stdout else 'no output'}"
+            )
+        
+        if proc.stdout is None:
+            raise RuntimeError("cloudflared process has no stdout")
+        
+        line = proc.stdout.readline()
+        if not line:
+            time.sleep(0.05)
+            continue
+        
+        match = _URL_RE.search(line)
+        if match:
+            url = match.group(0)
+            break
+    
+    if not url:
+        proc.terminate()
+        stdout, _ = proc.communicate(timeout=2.0)
+        raise RuntimeError(
+            f"Failed to parse trycloudflare URL from cloudflared output after {wait_s}s. "
+            f"Output: {stdout[:500] if stdout else 'no output'}"
+        )
+    
+    return url, proc
+
+
+def open_managed_tunnel(tunnel_token: str) -> subprocess.Popen:
+    """
+    Open a managed (named) Cloudflare tunnel using a token.
+    
+    Args:
+        tunnel_token: Cloudflare tunnel token from backend API
+    
+    Returns:
+        Process handle for the tunnel
+    
+    Raises:
+        FileNotFoundError: If cloudflared is not installed
+    """
+    bin_path = _which_cloudflared()
+    # cloudflared v2023.4+ accepts --token for named tunnels
+    return subprocess.Popen(
+        [bin_path, "tunnel", "run", "--token", tunnel_token],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+
+
+def stop_tunnel(proc: Optional[subprocess.Popen]) -> None:
+    """
+    Gracefully stop a tunnel process.
+    
+    Args:
+        proc: Process handle to terminate, or None
+    """
+    if proc is None:
+        return
+    
+    if proc.poll() is None:
+        # Process is still running
+        proc.terminate()
+        try:
+            proc.wait(timeout=5.0)
+        except subprocess.TimeoutExpired:
+            # Force kill if graceful termination fails
+            proc.kill()
+            proc.wait()
+

synth_ai/tunnel_deploy.py

@@ -0,0 +1,278 @@
+"""
+Cloudflare Tunnel deployment handler.
+
+Manages the full lifecycle of deploying a task app via Cloudflare Tunnel:
+1. Start local task app (uvicorn) in background
+2. Wait for health check
+3. Open tunnel (quick or managed)
+4. Write credentials to .env
+5. Optionally keep processes alive (blocking mode)
+
+This module provides a clean abstraction that shields users from:
+- Process management details (uvicorn threads, cloudflared subprocesses)
+- Health check polling logic
+- Credential storage
+- Cleanup on errors
+"""
+import asyncio
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+import httpx
+from synth_ai.cfgs import CloudflareTunnelDeployCfg
+from synth_ai.tunnel import open_managed_tunnel, open_quick_tunnel, stop_tunnel
+from synth_ai.utils.apps import get_asgi_app, load_file_to_module
+from synth_ai.utils.env import resolve_env_var
+from synth_ai.utils.paths import REPO_ROOT, configure_import_paths
+from synth_ai.utils.tunnel import store_tunnel_credentials
+
+import uvicorn
+from uvicorn._types import ASGIApplication
+
+_TUNNEL_PROCESSES: dict[int, subprocess.Popen] = {}  # Store tunnel process handles for cleanup
+
+
+async def _wait_for_health_check(
+    host: str,
+    port: int,
+    api_key: str,
+    timeout: float = 30.0,
+) -> None:
+    """
+    Wait for task app health endpoint to be ready.
+    
+    Args:
+        host: Host to check
+        port: Port to check
+        api_key: API key for authentication
+        timeout: Maximum time to wait in seconds
+    
+    Raises:
+        RuntimeError: If health check fails or times out
+    """
+    health_url = f"http://{host}:{port}/health"
+    headers = {"X-API-Key": api_key}
+    start = time.time()
+    
+    while time.time() - start < timeout:
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(health_url, headers=headers)
+                # Accept both 200 (success) and 400 (auth error means server is up)
+                if response.status_code in (200, 400):
+                    return
+        except (httpx.RequestError, httpx.TimeoutException):
+            pass
+        
+        await asyncio.sleep(0.5)
+    
+    raise RuntimeError(
+        f"Health check failed: {health_url} not ready after {timeout}s. "
+        "Make sure your task app has a /health endpoint."
+    )
+
+
+def _start_uvicorn_background(
+    app: ASGIApplication,
+    host: str,
+    port: int,
+    daemon: bool = True,
+) -> None:
+    """
+    Start uvicorn server in a background thread.
+    
+    Args:
+        app: ASGI application
+        host: Host to bind to
+        port: Port to bind to
+        daemon: If True, thread dies when main process exits. If False, thread keeps running.
+    """
+    import threading
+    
+    def serve():
+        try:
+            uvicorn.run(
+                app,
+                host=host,
+                port=port,
+                reload=False,
+                log_level="info",
+            )
+        except Exception as exc:
+            # Log error but don't raise (background thread)
+            print(f"Uvicorn error: {exc}", flush=True)
+    
+    thread = threading.Thread(
+        target=serve,
+        name=f"synth-uvicorn-tunnel-{port}",
+        daemon=daemon,
+    )
+    thread.start()
+
+
+async def deploy_app_tunnel(
+    cfg: CloudflareTunnelDeployCfg,
+    env_file: Optional[Path] = None,
+    keep_alive: bool = False,
+) -> str:
+    """
+    Deploy task app via Cloudflare Tunnel.
+    
+    This function provides a clean abstraction that handles:
+    1. Starting the local task app (uvicorn) in background
+    2. Waiting for health check
+    3. Opening tunnel (quick or managed)
+    4. Writing tunnel URL and Access credentials to .env
+    5. Optionally keeping processes alive (blocking vs non-blocking mode)
+    
+    When `keep_alive=True`, this function blocks and keeps the tunnel running
+    until interrupted (Ctrl+C). This is similar to how `deploy_app_uvicorn`
+    blocks for local deployments.
+    
+    When `keep_alive=False`, this function returns immediately after deployment.
+    Processes run in the background and will continue until explicitly stopped
+    or the parent process exits. Use this for headless/background deployments.
+    
+    Args:
+        cfg: Tunnel deployment configuration
+        env_file: Optional path to .env file (defaults to .env in current directory)
+        keep_alive: If True, block and keep tunnel alive until interrupted.
+                   If False, return immediately after deployment (background mode).
+    
+    Returns:
+        Public tunnel URL
+    
+    Raises:
+        RuntimeError: If deployment fails at any step
+    
+    Example:
+        # Non-blocking (background mode, returns immediately)
+        url = await deploy_app_tunnel(cfg, keep_alive=False)
+        
+        # Blocking (keeps tunnel alive, similar to local deployment)
+        url = await deploy_app_tunnel(cfg, keep_alive=True)
+    """
+    # Set up environment
+    os.environ["ENVIRONMENT_API_KEY"] = cfg.env_api_key
+    if cfg.trace:
+        os.environ["TASKAPP_TRACING_ENABLED"] = "1"
+    else:
+        os.environ.pop("TASKAPP_TRACING_ENABLED", None)
+    
+    # Load and configure task app
+    configure_import_paths(cfg.task_app_path, REPO_ROOT)
+    module = load_file_to_module(
+        cfg.task_app_path,
+        f"_synth_tunnel_task_app_{cfg.task_app_path.stem}",
+    )
+    app = get_asgi_app(module)
+    
+    # Start uvicorn in background
+    # Use daemon=False if keep_alive=True (so thread doesn't die when we block)
+    # Use daemon=True if keep_alive=False (background mode, dies with parent)
+    _start_uvicorn_background(app, cfg.host, cfg.port, daemon=not keep_alive)
+    
+    # Wait for health check (with API key for authentication)
+    await _wait_for_health_check(cfg.host, cfg.port, cfg.env_api_key)
+    
+    tunnel_proc = None
+    try:
+        if cfg.mode == "quick":
+            # Quick tunnel: ephemeral, no backend API call
+            url, tunnel_proc = open_quick_tunnel(cfg.port)
+            _TUNNEL_PROCESSES[cfg.port] = tunnel_proc
+            store_tunnel_credentials(url, None, None, env_file)
+        else:
+            # Managed tunnel: provision via backend API
+            try:
+                from synth_ai.api.tunnel import create_tunnel  # type: ignore[import-untyped]
+            except ImportError as err:
+                raise RuntimeError(
+                    "Managed tunnel mode requires synth_ai.api.tunnel module. "
+                    "This is only available in the managed tunnel implementation."
+                ) from err
+            
+            synth_api_key = resolve_env_var("SYNTH_API_KEY")
+            data = await create_tunnel(synth_api_key, cfg.port, cfg.subdomain)
+            
+            tunnel_token = data["tunnel_token"]
+            hostname = data["hostname"]
+            access_client_id = data.get("access_client_id")
+            access_client_secret = data.get("access_client_secret")
+            
+            tunnel_proc = open_managed_tunnel(tunnel_token)
+            _TUNNEL_PROCESSES[cfg.port] = tunnel_proc
+            
+            url = f"https://{hostname}"
+            store_tunnel_credentials(url, access_client_id, access_client_secret, env_file)
+        
+        # If keep_alive is True, block and keep processes alive until interrupted
+        if keep_alive:
+            _keep_tunnel_alive(cfg.port, url)
+        else:
+            # Background mode: print URL and return immediately
+            # Processes will keep running in background
+            print(f"✓ Tunnel ready: {url}")
+            print(f"⏳ Tunnel running in background (PID: {tunnel_proc.pid if tunnel_proc else 'N/A'})")
+            print("   Press Ctrl+C in this process to stop, or use: pkill -f cloudflared")
+        
+        return url
+    
+    except Exception as exc:
+        # Clean up tunnel process on error
+        if tunnel_proc:
+            stop_tunnel(tunnel_proc)
+            _TUNNEL_PROCESSES.pop(cfg.port, None)
+        raise RuntimeError(f"Failed to deploy tunnel: {exc}") from exc
+
+
+def _keep_tunnel_alive(port: int, url: str) -> None:
+    """
+    Keep tunnel processes alive until interrupted.
+    
+    This function blocks and monitors the tunnel process, similar to how
+    local deployments block. Users can interrupt with Ctrl+C to stop.
+    
+    Args:
+        port: Port the tunnel is running on
+        url: Public tunnel URL (for display)
+    """
+    import subprocess
+    
+    def signal_handler(signum, frame):  # noqa: ARG001
+        """Handle SIGINT/SIGTERM to cleanup gracefully."""
+        if port in _TUNNEL_PROCESSES:
+            stop_tunnel(_TUNNEL_PROCESSES[port])
+            _TUNNEL_PROCESSES.pop(port, None)
+        sys.exit(0)
+    
+    # Register signal handlers for graceful shutdown
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+    
+    print(f"✓ Tunnel ready: {url}")
+    print("⏳ Keeping tunnel running... (Press Ctrl+C to stop)")
+    
+    try:
+        # Monitor tunnel process and keep alive
+        while True:
+            if port in _TUNNEL_PROCESSES:
+                proc = _TUNNEL_PROCESSES[port]
+                if isinstance(proc, subprocess.Popen) and proc.poll() is not None:
+                    print(f"❌ Tunnel process exited with code {proc.returncode}")
+                    break
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        # Cleanup on exit
+        if port in _TUNNEL_PROCESSES:
+            stop_tunnel(_TUNNEL_PROCESSES[port])
+            _TUNNEL_PROCESSES.pop(port, None)
+        print("\n🛑 Tunnel stopped")
+

synth_ai/types.py

@@ -0,0 +1,8 @@
+import typing
+from typing import Literal
+
+ModelName = Literal[
+    "synth-small",
+    "synth-medium"
+]
+MODEL_NAMES = list(typing.get_args(ModelName))

synth_ai/urls.py

@@ -0,0 +1,11 @@
+# Base URL for all backends
+BACKEND_URL_BASE = "https://agent-learning.onrender.com"
+
+# Synth Research API base (supports OpenAI, Anthropic, and custom formats)
+# Real routes: /api/synth-research/chat/completions, /api/synth-research/messages
+# V1 routes: /api/synth-research/v1/chat/completions, /api/synth-research/v1/messages
+BACKEND_URL_SYNTH_RESEARCH_BASE = BACKEND_URL_BASE + "/api/synth-research"
+
+# Provider-specific URLs (for SDKs that expect standard paths)
+BACKEND_URL_SYNTH_RESEARCH_OPENAI = BACKEND_URL_SYNTH_RESEARCH_BASE + "/v1"  # For OpenAI SDKs (appends /chat/completions)
+BACKEND_URL_SYNTH_RESEARCH_ANTHROPIC = BACKEND_URL_SYNTH_RESEARCH_BASE  # For Anthropic SDKs (appends /v1/messages)

synth_ai/utils/__init__.py

@@ -0,0 +1,166 @@
+from . import task_app_state
+from .agents import write_agents_md
+from .apps import (
+    extract_routes_from_app,
+    get_asgi_app,
+    load_file_to_module,
+    validate_modal_app,
+    validate_task_app,
+)
+from .base_url import PROD_BASE_URL_DEFAULT, get_backend_from_env, get_learning_v2_base_url
+from .bin import install_bin, verify_bin
+from .claude import ClaudeConfig
+from .cli import (
+    PromptedChoiceOption,
+    PromptedChoiceType,
+    PromptedPathOption,
+    print_next_step,
+    prompt_choice,
+    prompt_for_path,
+)
+from .env import (
+    mask_str,
+    read_env_var_from_file,
+    resolve_env_var,
+    write_env_var_to_dotenv,
+    write_env_var_to_json,
+)
+from .http import AsyncHttpClient, HTTPError, http_request
+from .json import create_and_write_json, load_json_to_dict, strip_json_comments
+from .logging import flush_logger, log_batch, log_error, log_event, log_info, log_warning
+from .modal import (
+    ensure_modal_installed,
+    ensure_task_app_ready,
+    find_asgi_apps,
+    is_local_demo_url,
+    is_modal_public_url,
+    normalize_endpoint_url,
+)
+from .paths import (
+    REPO_ROOT,
+    cleanup_paths,
+    configure_import_paths,
+    find_config_path,
+    get_bin_path,
+    get_env_file_paths,
+    get_home_config_file_paths,
+    is_py_file,
+)
+from .process import ensure_local_port_available, popen_capture, popen_stream, popen_stream_capture
+from .sqld import SQLD_VERSION, find_sqld_binary, install_sqld
+from .task_app_discovery import AppChoice, discover_eval_config_paths, select_app_choice
+from .task_app_env import ensure_env_credentials, ensure_port_free, preflight_env_key
+from .task_app_state import (
+    DEFAULT_TASK_APP_SECRET_NAME,
+    current_task_app_id,
+    load_demo_dir,
+    load_template_id,
+    now_iso,
+    persist_api_key,
+    persist_demo_dir,
+    persist_env_api_key,
+    persist_task_url,
+    persist_template_id,
+    read_task_app_config,
+    record_task_app,
+    resolve_task_app_entry,
+    task_app_config_path,
+    task_app_id_from_path,
+    update_task_app_entry,
+    write_task_app_config,
+)
+from .user_config import (
+    USER_CONFIG_PATH,
+    load_user_config,
+    load_user_env,
+    save_user_config,
+    update_user_config,
+)
+
+__all__ = [
+    "AppChoice",
+    "AsyncHttpClient",
+    "DEFAULT_TASK_APP_SECRET_NAME",
+    "HTTPError",
+    "PROD_BASE_URL_DEFAULT",
+    "PromptedChoiceOption",
+    "PromptedChoiceType",
+    "PromptedPathOption",
+    "prompt_for_path",
+    "SQLD_VERSION",
+    "USER_CONFIG_PATH",
+    "ClaudeConfig",
+    "cleanup_paths",
+    "REPO_ROOT",
+    "create_and_write_json",
+    "current_task_app_id",
+    "configure_import_paths",
+    "discover_eval_config_paths",
+    "ensure_env_credentials",
+    "ensure_local_port_available",
+    "ensure_modal_installed",
+    "ensure_port_free",
+    "ensure_task_app_ready",
+    "extract_routes_from_app",
+    "find_asgi_apps",
+    "get_bin_path",
+    "find_config_path",
+    "find_sqld_binary",
+    "get_backend_from_env",
+    "get_env_file_paths",
+    "get_asgi_app",
+    "get_home_config_file_paths",
+    "get_learning_v2_base_url",
+    "http_request",
+    "install_bin",
+    "install_sqld",
+    "is_local_demo_url",
+    "is_modal_public_url",
+    "is_py_file",
+    "flush_logger",
+    "log_batch",
+    "log_error",
+    "log_event",
+    "log_info",
+    "log_warning",
+    "load_demo_dir",
+    "load_json_to_dict",
+    "load_file_to_module",
+    "load_template_id",
+    "load_user_config",
+    "load_user_env",
+    "mask_str",
+    "normalize_endpoint_url",
+    "now_iso",
+    "persist_api_key",
+    "persist_demo_dir",
+    "persist_env_api_key",
+    "persist_task_url",
+    "persist_template_id",
+    "popen_capture",
+    "popen_stream",
+    "popen_stream_capture",
+    "preflight_env_key",
+    "print_next_step",
+    "prompt_choice",
+    "read_env_var_from_file",
+    "read_task_app_config",
+    "record_task_app",
+    "resolve_env_var",
+    "resolve_task_app_entry",
+    "save_user_config",
+    "select_app_choice",
+    "strip_json_comments",
+    "task_app_config_path",
+    "task_app_id_from_path",
+    "task_app_state",
+    "update_task_app_entry",
+    "update_user_config",
+    "validate_modal_app",
+    "validate_task_app",
+    "verify_bin",
+    'write_agents_md',
+    "write_env_var_to_dotenv",
+    "write_env_var_to_json",
+    "write_task_app_config",
+]

synth_ai/utils/agents.py

@@ -0,0 +1,74 @@
+from pathlib import Path
+
+AGENTS_TEXT = """
+sinf
+"""
+SYNTH_DIV_START = "### --- SYNTH SECTION START ---"
+SYNTH_DIV_END = "### ---- SYNTH SECTION END ----"
+
+
+def _render_block() -> str:
+    return f"{SYNTH_DIV_START}\n{AGENTS_TEXT}\n{SYNTH_DIV_END}"
+
+
+def _append_block(prefix: str) -> str:
+    prefix = prefix.rstrip()
+    block = _render_block()
+    if prefix:
+        return f"{prefix}\n\n{block}\n"
+    return f"{block}\n"
+
+
+def write_agents_md() -> None:
+    path = Path.cwd() / "AGENTS.md"
+    if not path.exists():
+        path.write_text(_append_block(""), encoding="utf-8")
+        return
+
+    file_text = path.read_text(encoding="utf-8")
+
+    # Remove orphan end markers first (end markers without a preceding start marker)
+    cleaned = file_text
+    end_pos = cleaned.find(SYNTH_DIV_END)
+    start_pos = cleaned.find(SYNTH_DIV_START)
+    
+    # If there's an end marker before any start marker
+    if end_pos != -1 and (start_pos == -1 or end_pos < start_pos):
+        if start_pos == -1:
+            # No start markers at all - remove everything including content before orphan
+            cleaned = cleaned[end_pos + len(SYNTH_DIV_END):].lstrip()
+        else:
+            # There are start markers after the orphan - preserve content before orphan
+            before_orphan = cleaned[:end_pos].rstrip()
+            after_orphan = cleaned[end_pos + len(SYNTH_DIV_END):].lstrip()
+            cleaned = "\n\n".join(filter(None, [before_orphan, after_orphan]))
+    
+    # Find the first start and last end marker to consolidate multiple sections
+    first_start = cleaned.find(SYNTH_DIV_START)
+    last_end = cleaned.rfind(SYNTH_DIV_END)
+    
+    if first_start != -1 and last_end != -1 and last_end > first_start:
+        # We have at least one valid section, consolidate all into one
+        before = cleaned[:first_start].rstrip()
+        after = cleaned[last_end + len(SYNTH_DIV_END):].lstrip()
+        
+        parts: list[str] = []
+        if before:
+            parts.append(before)
+        parts.append(_render_block())
+        if after:
+            parts.append(after)
+        
+        new_text = "\n\n".join(parts)
+        if not new_text.endswith("\n"):
+            new_text += "\n"
+        path.write_text(new_text, encoding="utf-8")
+        return
+    
+    # No valid sections found, remove any remaining orphan markers
+    cleaned = cleaned.replace(SYNTH_DIV_END, "")
+    cleaned = cleaned.replace(AGENTS_TEXT, "")
+    cleaned = cleaned.strip()
+    if cleaned:
+        cleaned += "\n\n"
+    path.write_text(f"{cleaned}{_render_block()}\n", encoding="utf-8")