synth-ai 0.2.2.dev0__py3-none-any.whl → 0.2.3__py3-none-any.whl

synth_ai/cli/__init__.py

@@ -0,0 +1,66 @@
+"""CLI subcommands for Synth AI.
+
+This package hosts modular commands (watch, traces, recent, calc, status)
+and exposes a top-level Click group named `cli` compatible with the
+pyproject entry point `synth_ai.cli:cli`.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import sys
+
+# Load environment variables from a local .env if present (repo root)
+try:
+    from dotenv import load_dotenv, find_dotenv
+    # Source .env early so CLI subcommands inherit config; do not override shell
+    load_dotenv(find_dotenv(usecwd=True), override=False)
+except Exception:
+    # dotenv is optional at runtime; proceed if unavailable
+    pass
+
+
+from .root import cli  # new canonical CLI entrypoint
+
+# Register subcommands from this package onto the group
+try:
+    from . import watch as _watch
+    _watch.register(cli)
+except Exception:
+    pass
+try:
+    from . import balance as _balance
+    _balance.register(cli)
+except Exception:
+    pass
+try:
+    from . import man as _man
+    _man.register(cli)
+except Exception:
+    pass
+try:
+    from . import traces as _traces
+    _traces.register(cli)
+except Exception:
+    pass
+try:
+    from . import recent as _recent
+    _recent.register(cli)
+except Exception:
+    pass
+try:
+    from . import calc as _calc
+    _calc.register(cli)
+except Exception:
+    pass
+try:
+    from . import status as _status
+    _status.register(cli)
+except Exception:
+    pass
+try:
+    from . import demo as _demo
+    _demo.register(cli)
+except Exception:
+    pass

synth_ai/cli/balance.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+CLI: check remaining credit balance from Synth backend.
+"""
+
+from __future__ import annotations
+
+import os
+import click
+import requests
+from requests import Response
+from urllib.parse import urlparse
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+
+
+PROD_BACKEND_BASE = "https://agent-learning.onrender.com/api/v1"
+
+
+def _get_default_base_url() -> str:
+    # Prefer explicit backend variables that are NOT modal; else default to prod backend
+    for var in ("SYNTH_BACKEND_BASE_URL", "BACKEND_BASE_URL", "SYNTH_BASE_URL"):
+        val = os.getenv(var)
+        if val and ("modal" not in val.lower() and "modal.run" not in val.lower()):
+            return val
+    return PROD_BACKEND_BASE
+
+
+def _ensure_api_v1_prefix(base_url: str) -> str:
+    """Ensure the base URL includes the /api/v1 prefix.
+
+    Accepts either a full prefix (http://host:port/api/v1) or a root
+    service URL (http://host:port). If no '/api' segment is present, append
+    '/api/v1'.
+    """
+    b = base_url.rstrip("/")
+    if b.endswith("/api") or b.endswith("/api/v1") or "/api/" in b:
+        return b
+    return b + "/api/v1"
+
+
+def _resolve_api_key(explicit_key: str | None) -> tuple[str | None, str | None]:
+    if explicit_key:
+        return explicit_key, "--api-key"
+    # Try multiple env vars commonly used in this repo
+    for var in ("SYNTH_BACKEND_API_KEY", "SYNTH_API_KEY", "DEFAULT_DEV_API_KEY"):
+        val = os.getenv(var)
+        if val:
+            return val, var
+    return None, None
+
+
+def _auth_headers(api_key: str | None) -> dict[str, str]:
+    key, _ = _resolve_api_key(api_key)
+    if not key:
+        return {}
+    return {"Authorization": f"Bearer {key}"}
+
+
+def register(cli):
+    @cli.command()
+    @click.option(
+        "--base-url",
+        default=_get_default_base_url,
+        show_default=True,
+        help="Synth backend base URL (prefix like http://host:port/api/v1)",
+    )
+    @click.option(
+        "--api-key",
+        envvar="SYNTH_API_KEY",
+        help="API key for the Synth backend (or set SYNTH_API_KEY)",
+    )
+    @click.option(
+        "--usage/--no-usage",
+        default=False,
+        help="Also fetch recent usage summary",
+    )
+    def balance(base_url: str, api_key: str | None, usage: bool):
+        """Show your remaining credit balance from the Synth backend."""
+        console = Console()
+
+        key_val, key_src = _resolve_api_key(api_key)
+        if not key_val:
+            console.print(
+                "[red]Missing API key.[/red] Set via --api-key or SYNTH_API_KEY env var."
+            )
+            return
+
+        base = _ensure_api_v1_prefix(base_url)
+
+        # Hard guard: never hit Modal URLs for account balance
+        try:
+            parsed = urlparse(base)
+            host = (parsed.hostname or "").lower()
+        except Exception:
+            host = ""
+        if "modal" in host or "modal.run" in base.lower():
+            # Override to prod backend unconditionally
+            fallback = PROD_BACKEND_BASE
+            console.print(
+                f"[yellow]Detected remote Modal URL ({base}). Using backend instead:[/yellow] {fallback}"
+            )
+            base = fallback
+
+        try:
+            resp: Response = requests.get(
+                f"{base}/balance/current",
+                headers=_auth_headers(api_key),
+                timeout=10,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            cents = int(data.get("balance_cents", 0))
+            dollars = float(data.get("balance_dollars", cents / 100.0))
+            console.print(f"Balance: [bold]${dollars:,.2f}[/bold]")
+
+            # Try to print compact spend summary for 24h and 7d
+            try:
+                u: Response = requests.get(
+                    f"{base}/balance/usage/windows",
+                    params={"hours": "24,168"},
+                    headers=_auth_headers(api_key),
+                    timeout=10,
+                )
+                if u.ok:
+                    uj = u.json()
+                    rows = uj.get("windows", [])
+                    windows = {int(r.get("window_hours")): r for r in rows if isinstance(r.get("window_hours"), int)}
+                    def _usd(c):
+                        try:
+                            return f"${(int(c)/100):,.2f}"
+                        except Exception:
+                            return "$0.00"
+                    if 24 in windows or 168 in windows:
+                        t = Table(title="Spend (Tokens vs GPU)", box=box.SIMPLE, header_style="bold")
+                        t.add_column("Window")
+                        t.add_column("Tokens", justify="right")
+                        t.add_column("GPU", justify="right")
+                        t.add_column("Total", justify="right")
+                        for h,label in ((24,"24h"),(168,"7d")):
+                            if h in windows:
+                                w = windows[h]
+                                t.add_row(
+                                    label,
+                                    _usd(w.get("token_spend_cents", 0)),
+                                    _usd(w.get("gpu_spend_cents", 0)),
+                                    _usd(w.get("total_spend_cents", 0)),
+                                )
+                        console.print(t)
+                elif usage:
+                    # Fallback to older summary if requested explicitly
+                    u2: Response = requests.get(
+                        f"{base}/balance/usage",
+                        headers=_auth_headers(api_key),
+                        timeout=10,
+                    )
+                    if u2.ok:
+                        uj = u2.json()
+                        cm = uj.get("current_month", {})
+                        l30 = uj.get("last_30_days", {})
+                        t = Table(title="Usage Summary", box=box.SIMPLE, header_style="bold")
+                        t.add_column("Window")
+                        t.add_column("Token Spend", justify="right")
+                        t.add_column("GPU Spend", justify="right")
+                        t.add_column("Total", justify="right")
+                        t.add_row(
+                            "Current Month",
+                            f"${(cm.get('token_spend_cents',0)/100):,.2f}",
+                            f"${(cm.get('gpu_spend_cents',0)/100):,.2f}",
+                            f"${(cm.get('total_spend_cents',0)/100):,.2f}",
+                        )
+                        t.add_row(
+                            "Last 30 days",
+                            f"${(l30.get('token_spend_cents',0)/100):,.2f}",
+                            f"${(l30.get('gpu_spend_cents',0)/100):,.2f}",
+                            f"${(l30.get('total_spend_cents',0)/100):,.2f}",
+                        )
+                        console.print(t)
+            except Exception:
+                # Silent failure on usage summary
+                pass
+
+        except requests.HTTPError as e:
+            try:
+                detail = e.response.json().get("detail") if e.response else None
+            except Exception:
+                detail = None
+            if e.response is not None and e.response.status_code == 401:
+                key_dbg, key_src = _resolve_api_key(api_key)
+                shown = (key_dbg[:6] + "…" + key_dbg[-4:]) if key_dbg else "<none>"
+                console.print(
+                    "[red]Unauthorized (401).[/red] The API key was not accepted by the backend."
+                )
+                console.print(
+                    f"- Using base URL: {base}\n- API key (masked): {shown}\n- Key source: {key_src or '<none>'}\n- Ensure this key exists in the backend DB (table api_keys) and is active."
+                )
+                console.print(
+                    "If running locally, you can seed a dev key by setting ENVIRONMENT=dev and ensuring the DB has no API keys (auto-seed path), or create one via your admin path."
+                )
+            else:
+                console.print(f"[red]HTTP error:[/red] {e} {detail or ''}")
+        except Exception as e:
+            console.print(f"[red]Error:[/red] {e}")

synth_ai/cli/calc.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+CLI: basic calculator for quick math in terminal.
+Safe evaluation of arithmetic expressions.
+"""
+
+import ast
+import operator as op
+import click
+from rich.console import Console
+
+
+# Supported operators
+_OPS = {
+    ast.Add: op.add,
+    ast.Sub: op.sub,
+    ast.Mult: op.mul,
+    ast.Div: op.truediv,
+    ast.FloorDiv: op.floordiv,
+    ast.Mod: op.mod,
+    ast.Pow: op.pow,
+    ast.USub: op.neg,
+    ast.UAdd: op.pos,
+}
+
+
+def _safe_eval(expr: str) -> float:
+    node = ast.parse(expr, mode="eval")
+
+    def _eval(n):
+        if isinstance(n, ast.Expression):
+            return _eval(n.body)
+        if isinstance(n, ast.Num):  # 3.8 and earlier
+            return n.n
+        if isinstance(n, ast.Constant):  # 3.8+
+            if isinstance(n.value, (int, float)):
+                return n.value
+            raise ValueError("Only numeric constants are allowed")
+        if isinstance(n, ast.BinOp) and type(n.op) in _OPS:
+            return _OPS[type(n.op)](_eval(n.left), _eval(n.right))
+        if isinstance(n, ast.UnaryOp) and type(n.op) in _OPS:
+            return _OPS[type(n.op)](_eval(n.operand))
+        if isinstance(n, ast.Expr):
+            return _eval(n.value)
+        raise ValueError("Unsupported expression")
+
+    return _eval(node)
+
+
+def register(cli):
+    @cli.command(name="calc")
+    @click.argument("expr", nargs=-1)
+    def calc(expr: tuple[str, ...]):
+        """Evaluate a basic math expression, e.g., "(12_345 + 6789) / 100".
+
+        Supports + - * / // % ** and parentheses. No variables or functions.
+        """
+        console = Console()
+        expression = " ".join(expr).strip()
+        if not expression:
+            console.print("[dim]Usage:[/dim] synth-ai calc '2*(3+4)' or: uvx . calc 2 + 2")
+            return
+        try:
+            # Allow underscores in numbers for readability
+            expression = expression.replace("_", "")
+            result = _safe_eval(expression)
+            console.print(f"= [bold]{result}[/bold]")
+        except Exception as e:
+            console.print(f"[red]Error:[/red] {e}")
+

synth_ai/cli/demo.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+CLI: interactive launcher for example demos.
+
+Finds all `run_demo.sh` scripts under `examples/` and lets the user pick one
+to run. Intended to be used as: `uvx synth-ai demo` or `synth-ai demo`.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import List
+
+import click
+
+
+def _find_demo_scripts(root: Path) -> List[Path]:
+    if not root.exists():
+        return []
+    return sorted([p for p in root.rglob("run_demo.sh") if p.is_file()])
+
+
+def register(cli):
+    @cli.command()
+    @click.option("--list", "list_only", is_flag=True, help="List available demos and exit")
+    @click.option("-f", "filter_term", default="", help="Filter demos by substring")
+    def demo(list_only: bool, filter_term: str):
+        """Launch an interactive demo from examples/"""
+        repo_root = Path(os.getcwd())
+        examples_dir = repo_root / "examples"
+        demos = _find_demo_scripts(examples_dir)
+        if filter_term:
+            demos = [p for p in demos if filter_term.lower() in str(p).lower()]
+
+        if not demos:
+            click.echo("No run_demo.sh scripts found under examples/.")
+            return
+
+        if list_only:
+            click.echo("Available demos:")
+            for p in demos:
+                click.echo(f" - {p.relative_to(repo_root)}")
+            return
+
+        click.echo("Available demos:")
+        for idx, p in enumerate(demos, start=1):
+            click.echo(f" {idx}. {p.relative_to(repo_root)}")
+        click.echo("")
+
+        def _validate_choice(val: str) -> int:
+            try:
+                i = int(val)
+            except Exception:
+                raise click.BadParameter("Enter a number from the list")
+            if i < 1 or i > len(demos):
+                raise click.BadParameter(f"Choose a number between 1 and {len(demos)}")
+            return i
+
+        choice = click.prompt("Select a demo to run", value_proc=_validate_choice)
+        script = demos[choice - 1]
+
+        click.echo("")
+        click.echo(f"🚀 Running {script.relative_to(repo_root)}\n")
+
+        # Run via bash to avoid relying on executable bit; inherit environment
+        try:
+            subprocess.run(["bash", str(script)], check=True)
+        except subprocess.CalledProcessError as e:
+            click.echo(f"❌ Demo exited with non-zero status: {e.returncode}")
+        except KeyboardInterrupt:
+            click.echo("\n🛑 Demo interrupted by user")
+

synth_ai/{cli.py → cli/legacy_root_backup.py}

@@ -9,7 +9,6 @@ import subprocess
 import signal
 import time
 import shutil
-import asyncio
 from pathlib import Path
 from typing import Optional
 import logging
@@ -228,13 +227,33 @@ def unregister_env(name: str, service_url: str):
         click.echo(f"❌ Error: {e}")
 
 
+@cli.command()
+@click.option("--url", default="sqlite+aiosqlite:///./synth_ai.db/dbs/default/data", help="Database URL")
+def view(url: str):
+    """Launch the interactive TUI dashboard."""
+    try:
+        from .tui.dashboard import SynthDashboard
+        app = SynthDashboard(db_url=url)
+        app.run()
+    except ImportError:
+        click.echo("❌ Textual not installed. Install with: pip install textual", err=True)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        click.echo("\n👋 Dashboard closed", err=True)
+
+# Note: subcommands (watch, experiments, experiment, usage, traces, status, recent, calc)
+# are registered from the package module synth_ai.cli at import time.
+
+
 @cli.command()
 @click.option("--db-file", default="synth_ai.db", help="Database file path")
 @click.option("--sqld-port", default=8080, type=int, help="Port for sqld HTTP interface")
 @click.option("--env-port", default=8901, type=int, help="Port for environment service")
 @click.option("--no-sqld", is_flag=True, help="Skip starting sqld daemon")
 @click.option("--no-env", is_flag=True, help="Skip starting environment service")
-def serve(db_file: str, sqld_port: int, env_port: int, no_sqld: bool, no_env: bool):
+@click.option("--reload/--no-reload", default=False, help="Enable auto-reload (default: off). Or set SYNTH_RELOAD=1")
+@click.option("--force", is_flag=True, help="Kill any process already bound to --env-port without prompting")
+def serve(db_file: str, sqld_port: int, env_port: int, no_sqld: bool, no_env: bool, reload: bool, force: bool):
     """Start Synth AI services (sqld daemon and environment service)."""
 
     # Configure logging
@@ -330,18 +349,38 @@ def serve(db_file: str, sqld_port: int, env_port: int, no_sqld: bool, no_env: bo
             # Running from source
             env_module = "synth_ai.environments.service.app:app"
 
-        # Check if port is already in use
+        # Ensure env_port is free; offer to kill existing listeners
         try:
             import socket
 
             with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-                result = s.connect_ex(("127.0.0.1", env_port))
-                if result == 0:
-                    click.echo(f"⚠️  Port {env_port} is already in use!")
-                    click.echo("   Another instance of the environment service may be running.")
-                    click.echo("")
-        except:
-            pass
+                in_use = s.connect_ex(("127.0.0.1", env_port)) == 0
+        except Exception:
+            in_use = False
+
+        if in_use:
+            # Try to find PIDs using lsof (macOS/Linux)
+            pids: list[str] = []
+            try:
+                out = subprocess.run(["lsof", "-ti", f":{env_port}"], capture_output=True, text=True)
+                if out.returncode == 0 and out.stdout.strip():
+                    pids = [p for p in out.stdout.strip().splitlines() if p]
+            except FileNotFoundError:
+                pids = []
+
+            if force:
+                if pids:
+                    subprocess.run(["kill", "-9", *pids], check=False)
+                    time.sleep(0.5)
+            else:
+                pid_info = f" PIDs: {', '.join(pids)}" if pids else ""
+                if click.confirm(f"⚠️  Port {env_port} is in use.{pid_info} Kill and continue?", default=True):
+                    if pids:
+                        subprocess.run(["kill", "-9", *pids], check=False)
+                        time.sleep(0.5)
+                else:
+                    click.echo("❌ Aborting. Re-run with --force to auto-kill or choose a different --env-port.")
+                    sys.exit(1)
 
         # Set environment variables
         env = os.environ.copy()
@@ -358,7 +397,12 @@ def serve(db_file: str, sqld_port: int, env_port: int, no_sqld: bool, no_env: bo
         click.echo("💡 Tips:")
         click.echo("   - Check sqld.log if database issues occur")
         click.echo("   - Use Ctrl+C to stop all services")
-        click.echo("   - Service will auto-reload on code changes")
+        # Determine reload behavior: CLI flag overrides env var, default is off
+        reload_enabled = reload or (os.getenv("SYNTH_RELOAD", "0") == "1")
+        if reload_enabled:
+            click.echo("   - Auto-reload ENABLED (code changes restart service)")
+        else:
+            click.echo("   - Auto-reload DISABLED (stable in-memory sessions)")
         click.echo("")
 
         # Start uvicorn
@@ -373,12 +417,13 @@ def serve(db_file: str, sqld_port: int, env_port: int, no_sqld: bool, no_env: bo
             str(env_port),
             "--log-level",
             "info",
-            "--reload",
         ]
 
-        # If running from source, add reload directory
-        if os.path.exists("synth_ai"):
-            uvicorn_cmd.extend(["--reload-dir", "synth_ai"])
+        if reload_enabled:
+            uvicorn_cmd.append("--reload")
+            # If running from source, add reload directory
+            if os.path.exists("synth_ai"):
+                uvicorn_cmd.extend(["--reload-dir", "synth_ai"])
 
         proc = subprocess.Popen(uvicorn_cmd, env=env)
         processes.append(proc)

synth_ai/cli/man.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+CLI: human-friendly manual for Synth AI commands and options.
+"""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich import box
+
+
+def _commands_table() -> Table:
+    t = Table(title="Commands", box=box.SIMPLE, header_style="bold")
+    t.add_column("Command")
+    t.add_column("Summary")
+    t.add_row(
+        "balance",
+        "Show remaining credit balance (USD) and a compact spend summary for last 24h and 7d.\n"
+        "Options: --base-url, --api-key, --usage",
+    )
+    t.add_row(
+        "traces",
+        "List local trace DBs, trace counts, experiments, and per-system counts.\n"
+        "Options: --root",
+    )
+    t.add_row(
+        "experiments",
+        "Snapshot table of experiments from the local traces DB.\n"
+        "Options: --url, --limit",
+    )
+    t.add_row(
+        "experiment <id>",
+        "Details and sessions for an experiment (accepts partial ID).\n"
+        "Options: --url",
+    )
+    t.add_row(
+        "usage",
+        "Model usage statistics (tokens, cost).\n"
+        "Options: --url, --model",
+    )
+    t.add_row(
+        "status",
+        "DB stats, systems, and environment service health.\n"
+        "Options: --url, --service-url",
+    )
+    t.add_row(
+        "calc '<expr>'",
+        "Evaluate a simple arithmetic expression (e.g., 2*(3+4)).",
+    )
+    t.add_row(
+        "env list | env register | env unregister",
+        "Manage environment registry via the service.\n"
+        "Options vary; see examples.",
+    )
+    return t
+
+
+def _env_table() -> Table:
+    t = Table(title="Environment Variables", box=box.SIMPLE, header_style="bold")
+    t.add_column("Variable")
+    t.add_column("Used By")
+    t.add_column("Purpose")
+    t.add_row("SYNTH_BACKEND_BASE_URL", "balance", "Backend base URL (preferred) e.g. http://localhost:8000/api/v1")
+    t.add_row("BACKEND_BASE_URL", "balance", "Fallback backend base URL")
+    t.add_row("LOCAL_BACKEND_URL", "balance", "Another fallback backend base URL")
+    t.add_row("SYNTH_BASE_URL", "balance", "Generic base URL (may point to Modal, guarded)")
+    t.add_row("SYNTH_BACKEND_API_KEY", "balance", "Backend API key (preferred)")
+    t.add_row("SYNTH_API_KEY", "balance, env*", "API key used if backend-specific key not set")
+    t.add_row("DEFAULT_DEV_API_KEY", "balance", "Dev fallback key for local testing")
+    t.add_row("SYNTH_TRACES_ROOT", "traces", "Root directory of local trace DBs (default ./synth_ai.db/dbs)")
+    return t
+
+
+def _examples_table() -> Table:
+    t = Table(title="Examples", box=box.SIMPLE, header_style="bold")
+    t.add_column("Command")
+    t.add_column("Example")
+    t.add_row("Balance (local backend)", "uvx . balance")
+    t.add_row("Balance with URL+key", "uvx . balance --base-url http://localhost:8000 --api-key $SYNTH_API_KEY")
+    t.add_row("Traces (default root)", "uvx . traces")
+    t.add_row("Traces (custom root)", "uvx . traces --root /path/to/dbs")
+    t.add_row("Experiments", "uvx . experiments --limit 20")
+    t.add_row("Experiment detail", "uvx . experiment abcd1234")
+    t.add_row("Usage by model", "uvx . usage --model gpt-4o-mini")
+    t.add_row("Status", "uvx . status")
+    t.add_row("Calc", "uvx . calc '2*(3+4)'")
+    t.add_row("Env list", "uvx . env list --service-url http://localhost:8901")
+    return t
+
+
+def register(cli):
+    @cli.command(name="man")
+    def man():
+        """Show Synth AI CLI manual with commands, options, env vars, and examples."""
+        console = Console()
+        console.print(Panel("Synth AI CLI Manual", border_style="cyan"))
+        console.print(_commands_table())
+        console.print(_env_table())
+        console.print(_examples_table())
+