synth-ai 0.2.13.dev2__py3-none-any.whl → 0.2.16__py3-none-any.whl

synth_ai/utils/__init__.py

@@ -0,0 +1,101 @@
+from . import task_app_state
+from .base_url import PROD_BASE_URL_DEFAULT, get_backend_from_env, get_learning_v2_base_url
+from .cli import PromptedChoiceOption, PromptedChoiceType, print_next_step
+from .env import mask_str, resolve_env_var, write_env_var_to_dotenv, write_env_var_to_json
+from .http import AsyncHttpClient, HTTPError, http_request
+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 .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",
+    "SQLD_VERSION",
+    "USER_CONFIG_PATH",
+    "current_task_app_id",
+    "discover_eval_config_paths",
+    "ensure_env_credentials",
+    "ensure_local_port_available",
+    "ensure_modal_installed",
+    "ensure_port_free",
+    "ensure_task_app_ready",
+    "find_asgi_apps",
+    "find_sqld_binary",
+    "get_backend_from_env",
+    "get_learning_v2_base_url",
+    "http_request",
+    "install_sqld",
+    "is_local_demo_url",
+    "is_modal_public_url",
+    "load_demo_dir",
+    "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",
+    "read_task_app_config",
+    "record_task_app",
+    "resolve_env_var",
+    "resolve_task_app_entry",
+    "save_user_config",
+    "select_app_choice",
+    "task_app_config_path",
+    "task_app_id_from_path",
+    "task_app_state",
+    "update_task_app_entry",
+    "update_user_config",
+    "write_env_var_to_dotenv",
+    "write_env_var_to_json",
+    "write_task_app_config",
+]

synth_ai/utils/base_url.py

@@ -0,0 +1,94 @@
+"""
+Base URL resolution for learning-v2 and related backend APIs.
+
+Default to production, allow overrides via environment variables:
+- LEARNING_V2_BASE_URL (highest precedence)
+- SYNTH_BASE_URL (legacy)
+- SYNTH_LOCAL_BASE_URL
+- SYNTH_DEV_BASE_URL
+- SYNTH_PROD_BASE_URL (fallback if none provided)
+
+Normalization: ensure the returned URL ends with "/api".
+"""
+
+import os
+from typing import Literal
+
+PROD_BASE_URL_DEFAULT = "https://agent-learning.onrender.com"
+
+
+def _normalize_base(url: str) -> str:
+    url = url.strip()
+    if url.endswith("/v1"):
+        url = url[:-3]
+    url = url.rstrip("/")
+    if not url.endswith("/api"):
+        url = f"{url}/api"
+    return url
+
+
+def get_learning_v2_base_url(mode: Literal["dev", "prod"] = "prod") -> str:
+    if mode == "prod":
+        prod = os.getenv("SYNTH_PROD_BASE_URL") or PROD_BASE_URL_DEFAULT
+        return _normalize_base(prod)
+    env_url = os.getenv("LEARNING_V2_BASE_URL")
+    if env_url:
+        return _normalize_base(env_url)
+
+    legacy = os.getenv("SYNTH_BASE_URL")
+    if legacy:
+        return _normalize_base(legacy)
+
+    local = os.getenv("SYNTH_LOCAL_BASE_URL")
+    if local:
+        return _normalize_base(local)
+
+    dev = os.getenv("SYNTH_DEV_BASE_URL")
+    if dev:
+        return _normalize_base(dev)
+
+    raise ValueError("No base URL configured. Set one of: LEARNING_V2_BASE_URL, SYNTH_BASE_URL, SYNTH_LOCAL_BASE_URL, SYNTH_DEV_BASE_URL")
+
+
+def _resolve_override_mode() -> str:
+    ov = (os.getenv("SYNTH_BACKEND_URL_OVERRIDE", "") or "").strip().lower()
+    if ov in {"local", "dev", "prod"}:
+        return ov
+    return "prod"
+
+
+def get_backend_from_env() -> tuple[str, str]:
+    direct_override = (os.getenv("BACKEND_OVERRIDE") or "").strip()
+    if direct_override:
+        base = direct_override.rstrip("/")
+        if base.endswith("/api"):
+            base = base[: -len("/api")]
+        api_key = os.getenv("SYNTH_API_KEY", "").strip()
+        return base, api_key
+
+    mode = _resolve_override_mode()
+    if mode == "local":
+        base = os.getenv("LOCAL_BACKEND_URL", "http://localhost:8000")
+        key = os.getenv("TESTING_LOCAL_SYNTH_API_KEY", "")
+        return base.rstrip("/"), key
+    if mode == "dev":
+        base = os.getenv("DEV_BACKEND_URL", "") or "http://localhost:8000"
+        key = os.getenv("DEV_SYNTH_API_KEY", "")
+        return base.rstrip("/"), key
+    base = os.getenv("PROD_BACKEND_URL", f"{PROD_BASE_URL_DEFAULT}")
+    base = base.rstrip("/")
+    if base.endswith("/api"):
+        base = base[: -len("/api")]
+    key = (
+        os.getenv("PROD_SYNTH_API_KEY", "")
+        or os.getenv("TESTING_PROD_SYNTH_API_KEY", "")
+        or os.getenv("SYNTH_API_KEY", "")
+    )
+    return base, key
+
+
+__all__ = [
+    "PROD_BASE_URL_DEFAULT",
+    "get_backend_from_env",
+    "get_learning_v2_base_url",
+]

synth_ai/utils/cli.py

@@ -0,0 +1,131 @@
+from collections.abc import Sequence
+from typing import Any, cast
+
+import click
+
+
+class PromptedChoiceType(click.Choice):
+    """`click.Choice` variant that reprompts with an interactive menu on failure.
+
+    Example
+    -------
+    ```python
+    import click
+
+    from synth_ai.utils.cli import PromptedChoiceType, PromptedChoiceOption
+
+
+    @click.command()
+    @click.option(
+        "--mode",
+        cls=PromptedChoiceOption,
+        type=PromptedChoiceType(["sft", "rl"]),
+        required=True,
+    )
+    def train(mode: str) -> None:
+        click.echo(f"Selected mode: {mode}")
+    ```
+    """
+
+    def convert(
+        self,
+        value: Any,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> str:
+        """Validate *value*; prompt for a replacement when it is missing or invalid."""
+        if param is None:
+            raise RuntimeError("Invalid parameter")
+        if ctx is None:
+            raise RuntimeError("Invalid context")
+        if value in (None, ""):
+            return self._prompt_user(param, ctx)
+        try:
+            return super().convert(value, param, ctx)
+        except click.BadParameter:
+            cmd_name = self._get_cmd_name(ctx)
+            if getattr(param, "opts", None):
+                click.echo(f'\n[{cmd_name}] Invalid value "{value}" for {self._get_arg_name(param)}')
+            else:
+                click.echo(f'\n[{cmd_name}] Invalid value "{value}"')
+            return self._prompt_user(param, ctx)
+
+    def _prompt_user(
+        self,
+        param: click.Parameter,
+        ctx: click.Context | None,
+    ) -> str:
+        """Render a numbered picker and return the user’s selection."""
+        arg_name = self._get_arg_name(param)
+        click.echo(f"\n[{self._get_cmd_name(ctx)}] Please choose a value for {arg_name}")
+        for index, choice in enumerate(self.choices, 1):
+            click.echo(f" [{index}] {choice}")
+        while True:
+            selection = click.prompt("> ", type=int)
+            if 1 <= selection <= len(self.choices):
+                return cast(str, self.choices[selection - 1])
+            click.echo(f"Invalid selection for {arg_name}, please try again")
+
+    def _get_cmd_name(self, ctx: click.Context | None) -> str:
+        """Safely extract the current command name for diagnostic output."""
+        cmd = getattr(ctx, "command", None) if ctx is not None else None
+        if cmd is None:
+            return "?"
+        name = getattr(cmd, "name", None)
+        return name or "?"
+
+    def _get_arg_name(self, param: click.Parameter) -> str:
+        """Return the most human-friendly identifier for the parameter."""
+        opts = getattr(param, "opts", None)
+        if opts:
+            return opts[-1]
+        name = getattr(param, "name", None)
+        if name:
+            return name
+        human_name = getattr(param, "human_readable_name", None)
+        if human_name:
+            return human_name
+        return "?"
+
+
+class PromptedChoiceOption(click.Option):
+    """`click.Option` subclass that triggers the interactive picker when missing.
+
+    Example
+    -------
+    ```python
+    import click
+
+    from synth_ai.utils.cli import PromptedChoiceType, PromptedChoiceOption
+
+
+    @click.command()
+    @click.option(
+        "--mode",
+        cls=PromptedChoiceOption,
+        type=PromptedChoiceType(["sft", "rl"]),
+        required=True,
+    )
+    def train(mode: str) -> None:
+        click.echo(f"Selected mode: {mode}")
+    ```
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("prompt", True)
+        kwargs.setdefault("prompt_required", True)
+        super().__init__(*args, **kwargs)
+
+    def prompt_for_value(self, ctx: click.Context) -> Any:
+        """Invoke the choice picker when the option was omitted."""
+        option_type = getattr(self, "type", None)
+        if isinstance(option_type, PromptedChoiceType):
+            return option_type._prompt_user(self, ctx)
+        return super().prompt_for_value(ctx)
+    
+
+def print_next_step(message: str, lines: Sequence[str]) -> None:
+    print(f"\n➡️  Next, {message}:")
+    for line in lines:
+        print(f"   {line}")
+    print("")

synth_ai/utils/env.py

@@ -0,0 +1,287 @@
+import json
+import os
+import string
+from pathlib import Path
+
+import click
+
+_ENV_SAFE_CHARS = set(string.ascii_letters + string.digits + "_-./:@+=")
+
+
+def _format_env_value(value: str) -> str:
+    if value == "":
+        return '""'
+    if all(char in _ENV_SAFE_CHARS for char in value):
+        return value
+    return json.dumps(value)
+
+
+def _strip_inline_comment(value: str) -> str:
+    in_single = False
+    in_double = False
+    escaped = False
+    for idx, char in enumerate(value):
+        if escaped:
+            escaped = False
+            continue
+        if char == "\\":
+            escaped = True
+            continue
+        if char == "'" and not in_double:
+            in_single = not in_single
+            continue
+        if char == '"' and not in_single:
+            in_double = not in_double
+            continue
+        if char == '#' and not in_single and not in_double:
+            return value[:idx].rstrip()
+    return value.rstrip()
+
+
+def _parse_env_assignment(line: str) -> tuple[str, str] | None:
+    stripped = line.strip()
+    if not stripped or stripped.startswith('#'):
+        return None
+    if stripped.lower().startswith("export "):
+        stripped = stripped[7:].lstrip()
+    if '=' not in stripped:
+        return None
+    key_part, value_part = stripped.split('=', 1)
+    key = key_part.strip()
+    if not key:
+        return None
+    value_candidate = _strip_inline_comment(value_part.strip())
+    if not value_candidate:
+        return key, ""
+    if (
+        len(value_candidate) >= 2
+        and value_candidate[0] in {'"', "'"}
+        and value_candidate[-1] == value_candidate[0]
+    ):
+        value = value_candidate[1:-1]
+    else:
+        value = value_candidate
+    return key, value
+
+
+def _prompt_manual_env_value(key: str) -> str:
+    while True:
+        value = click.prompt(
+            f"Enter value for {key}",
+            hide_input=False,
+            default="",
+            show_default=False,
+            type=str,
+        ).strip()
+        if value:
+            return value
+        if click.confirm("Save empty value?", default=False):
+            return ""
+        click.echo("Empty value discarded; enter a value or confirm empty to continue")
+
+
+def mask_str(input: str, position: int = 3) -> str:
+    return input[:position] + "..." + input[-position:] if len(input) > position * 2 else "***"
+
+
+def get_env_file_paths(base_dir: str | Path = '.') -> list[Path]:
+    base = Path(base_dir).resolve()
+    return [path for path in base.rglob(".env*") if path.is_file()]
+
+
+def get_synth_config_file_paths() -> list[Path]:
+    dir = Path.home() / ".synth-ai"
+    if not dir.exists():
+        return []
+    return [path for path in dir.glob("*.json") if path.is_file()]
+
+
+def filter_env_files_by_key(key: str, paths: list[Path]) -> list[tuple[Path, str]]:
+    matches: list[tuple[Path, str]] = []
+    for path in paths:
+        try:
+            with path.open('r', encoding="utf-8") as file:
+                for line in file:
+                    parsed = _parse_env_assignment(line)
+                    if parsed is None:
+                        continue
+                    parsed_key, value = parsed
+                    if parsed_key == key:
+                        matches.append((path, value))
+                        break
+        except (OSError, UnicodeDecodeError):
+            continue
+    return matches
+
+
+def filter_json_files_by_key(key: str, paths: list[Path]) -> list[tuple[Path, str]]:
+    matches: list[tuple[Path, str]] = []
+    for path in paths:
+        try:
+            with path.open('r', encoding="utf-8") as file:
+                data = json.load(file)
+                if key in data and isinstance(data[key], str):
+                    matches.append((path, data[key]))
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+            continue
+    return matches
+
+
+def resolve_env_var(key: str) -> None:
+    env_value = os.getenv(key)
+    if env_value is not None:
+        click.echo(f"Using {key}={mask_str(env_value)} from process environment")
+        return
+
+    value: str = ""
+
+    env_file_paths = filter_env_files_by_key(key, get_env_file_paths())
+    synth_file_paths = filter_json_files_by_key(key, get_synth_config_file_paths())
+
+    options: list[tuple[str, str]] = []
+    for path, value in env_file_paths:
+        resolved_path = path.resolve()
+        try:
+            rel_path = str(resolved_path.relative_to(Path.cwd()))
+        except ValueError:
+            rel_path = str(resolved_path)
+        label = f"({rel_path})  {mask_str(value)}"
+        options.append((label, value))
+    for path, value in synth_file_paths:
+        label = f"({path})  {mask_str(value)}"
+        options.append((label, value))
+
+    if options:
+        click.echo(f"\nFound the following options for {key}")
+        for i, (label, _) in enumerate(options, start=1):
+            click.echo(f" [{i}] {label}")
+        click.echo(" [m] Enter value manually")
+        click.echo()
+
+        while True:
+            try:
+                choice = click.prompt(
+                    "Select option",
+                    default=1,
+                    type=str,
+                    show_choices=False,
+                ).strip()
+            except click.Abort:
+                return
+
+            if choice.lower() == 'm':
+                value = _prompt_manual_env_value(key)
+                break
+
+            try:
+                index = int(choice)
+            except ValueError:
+                click.echo('Invalid selection. Enter a number or "m".')
+                continue
+
+            if 1 <= index <= len(options):
+                _, value = options[index - 1]
+                break
+
+            click.echo(f"Invalid selection. Enter a number between 1 and {len(options)} or 'm'.")
+
+    else:
+        click.echo(f"No value found for {key}")
+        value = _prompt_manual_env_value(key)
+    
+    os.environ[key] = value
+    click.echo(f"Loaded {key}={mask_str(value)} into process environment")
+    return
+
+
+def write_env_var_to_dotenv(
+    key: str,
+    value: str,
+    output_file_path: str | Path,
+) -> None:
+    path = Path(output_file_path).expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    encoded_value = _format_env_value(value)
+
+    lines: list[str] = []
+    key_written = False
+
+    if path.is_file():
+        try:
+            with path.open('r', encoding="utf-8") as handle:
+                lines = handle.readlines()
+        except OSError as exc:
+            raise click.ClickException(f"Failed to read {path}: {exc}") from exc
+
+        for index, line in enumerate(lines):
+            parsed = _parse_env_assignment(line)
+            if parsed is None or parsed[0] != key:
+                continue
+
+            leading_len = len(line) - len(line.lstrip(' \t'))
+            leading = line[:leading_len]
+            stripped = line.lstrip()
+            has_export = stripped.lower().startswith('export ')
+            newline = '\n' if line.endswith('\n') else ''
+            prefix = 'export ' if has_export else ''
+            lines[index] = f"{leading}{prefix}{key}={encoded_value}{newline}"
+            key_written = True
+            break
+
+    if not key_written:
+        if lines and not lines[-1].endswith('\n'):
+            lines[-1] = f"{lines[-1]}\n"
+        lines.append(f"{key}={encoded_value}\n")
+
+    try:
+        with path.open('w', encoding="utf-8") as handle:
+            handle.writelines(lines)
+    except OSError as exc:
+        raise click.ClickException(f"Failed to write {path}: {exc}") from exc
+
+    click.echo(f"Wrote {key}={mask_str(value)} to {path}")
+
+
+def write_env_var_to_json(
+    key: str,
+    value: str,
+    output_file_path: str | Path,
+) -> None:
+    path = Path(output_file_path).expanduser()
+    if path.exists() and not path.is_file():
+        raise click.ClickException(f"{path} exists and is not a file")
+
+    data: dict[str, str] = {}
+
+    if path.is_file():
+        try:
+            with path.open('r', encoding="utf-8") as handle:
+                existing = json.load(handle)
+        except json.JSONDecodeError as exc:
+            raise click.ClickException(f"Invalid JSON in {path}: {exc}") from exc
+        except OSError as exc:
+            raise click.ClickException(f"Failed to read {path}: {exc}") from exc
+
+        if not isinstance(existing, dict):
+            raise click.ClickException(f"Expected JSON object in {path}")
+
+        for existing_key, existing_value in existing.items():
+            if existing_key == key:
+                continue
+            data[str(existing_key)] = (
+                existing_value if isinstance(existing_value, str) else str(existing_value)
+            )
+
+    data[key] = value
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        with path.open('w', encoding="utf-8") as handle:
+            json.dump(data, handle, indent=2, sort_keys=True)
+            handle.write('\n')
+    except OSError as exc:
+        raise click.ClickException(f"Failed to write {path}: {exc}") from exc
+
+    click.echo(f"Wrote {key}={mask_str(value)} to {path}")