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

synth_ai/cli/commands/status/__init__.py

@@ -0,0 +1,66 @@
+"""Status and listing commands for the Synth CLI."""
+
+from __future__ import annotations
+
+import click
+
+from .config import resolve_backend_config
+from .subcommands.files import files_group
+from .subcommands.jobs import jobs_group
+from .subcommands.models import models_group
+from .subcommands.runs import runs_group
+from .subcommands.session import session_status_cmd
+from .subcommands.summary import summary_command
+
+
+def _attach_group(cli: click.Group, group: click.Group, name: str) -> None:
+    """Attach the provided Click group to the CLI if not already present."""
+    if name in cli.commands:
+        return
+    cli.add_command(group, name=name)
+
+
+def register(cli: click.Group) -> None:
+    """Register all status command groups on the provided CLI root."""
+
+    @click.group(help="Inspect training jobs, models, files, and job runs.")
+    @click.option(
+        "--base-url",
+        envvar="SYNTH_STATUS_BASE_URL",
+        default=None,
+        help="Synth backend base URL (defaults to environment configuration).",
+    )
+    @click.option(
+        "--api-key",
+        envvar="SYNTH_STATUS_API_KEY",
+        default=None,
+        help="API key for authenticated requests (falls back to Synth defaults).",
+    )
+    @click.option(
+        "--timeout",
+        default=30.0,
+        show_default=True,
+        type=float,
+        help="HTTP request timeout in seconds.",
+    )
+    @click.pass_context
+    def status(ctx: click.Context, base_url: str | None, api_key: str | None, timeout: float) -> None:
+        """Populate shared backend configuration for subcommands."""
+        cfg = resolve_backend_config(base_url=base_url, api_key=api_key, timeout=timeout)
+        ctx.ensure_object(dict)
+        ctx.obj["status_backend_config"] = cfg
+
+    status.add_command(jobs_group, name="jobs")
+    status.add_command(models_group, name="models")
+    status.add_command(files_group, name="files")
+    status.add_command(runs_group, name="runs")
+    status.add_command(session_status_cmd, name="session")
+    status.add_command(summary_command, name="summary")
+
+    cli.add_command(status, name="status")
+    _attach_group(cli, jobs_group, "jobs")
+    _attach_group(cli, models_group, "models")
+    _attach_group(cli, files_group, "files")
+    _attach_group(cli, runs_group, "runs")
+    if "status-summary" not in cli.commands:
+        cli.add_command(summary_command, name="status-summary")

synth_ai/cli/commands/status/client.py

@@ -0,0 +1,192 @@
+"""Async HTTP client for Synth status and listing endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .config import BackendConfig
+from .errors import StatusAPIError
+
+
+class StatusAPIClient:
+    """Thin wrapper around httpx.AsyncClient with convenience methods."""
+
+    def __init__(self, config: BackendConfig) -> None:
+        self._config = config
+        timeout = httpx.Timeout(config.timeout)
+        self._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            headers=config.headers,
+            timeout=timeout,
+        )
+
+    async def __aenter__(self) -> StatusAPIClient:
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._client.__aexit__(*args)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    # Jobs -----------------------------------------------------------------
+
+    async def list_jobs(
+        self,
+        *,
+        status: str | None = None,
+        job_type: str | None = None,
+        created_after: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {}
+        if status:
+            params["status"] = status
+        if job_type:
+            params["type"] = job_type
+        if created_after:
+            params["created_after"] = created_after
+        if limit:
+            params["limit"] = limit
+        resp = await self._client.get("/learning/jobs", params=params)
+        return self._json_list(resp, key="jobs")
+
+    async def get_job(self, job_id: str) -> dict[str, Any]:
+        resp = await self._client.get(f"/learning/jobs/{job_id}")
+        return self._json(resp)
+
+    async def get_job_status(self, job_id: str) -> dict[str, Any]:
+        resp = await self._client.get(f"/learning/jobs/{job_id}/status")
+        return self._json(resp)
+
+    async def cancel_job(self, job_id: str) -> dict[str, Any]:
+        resp = await self._client.post(f"/learning/jobs/{job_id}/cancel")
+        return self._json(resp)
+
+    async def get_job_config(self, job_id: str) -> dict[str, Any]:
+        resp = await self._client.get(f"/learning/jobs/{job_id}/config")
+        return self._json(resp)
+
+    async def get_job_metrics(self, job_id: str) -> dict[str, Any]:
+        resp = await self._client.get(f"/learning/jobs/{job_id}/metrics")
+        return self._json(resp)
+
+    async def get_job_timeline(self, job_id: str) -> list[dict[str, Any]]:
+        resp = await self._client.get(f"/learning/jobs/{job_id}/timeline")
+        return self._json_list(resp, key="timeline")
+
+    async def list_job_runs(self, job_id: str) -> list[dict[str, Any]]:
+        resp = await self._client.get(f"/jobs/{job_id}/runs")
+        return self._json_list(resp, key="runs")
+
+    async def get_job_events(
+        self,
+        job_id: str,
+        *,
+        since: str | None = None,
+        limit: int | None = None,
+        after: str | None = None,
+        run_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {}
+        if since:
+            params["since"] = since
+        if limit:
+            params["limit"] = limit
+        if after:
+            params["after"] = after
+        if run_id:
+            params["run"] = run_id
+        resp = await self._client.get(f"/learning/jobs/{job_id}/events", params=params)
+        return self._json_list(resp, key="events")
+
+    # Files ----------------------------------------------------------------
+
+    async def list_files(
+        self,
+        *,
+        purpose: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {}
+        if purpose:
+            params["purpose"] = purpose
+        if limit:
+            params["limit"] = limit
+        resp = await self._client.get("/files", params=params)
+        data = self._json(resp)
+        if isinstance(data, dict):
+            for key in ("files", "data", "items"):
+                if isinstance(data.get(key), list):
+                    return list(data[key])
+        if isinstance(data, list):
+            return list(data)
+        return []
+
+    async def get_file(self, file_id: str) -> dict[str, Any]:
+        resp = await self._client.get(f"/files/{file_id}")
+        return self._json(resp)
+
+    # Models ---------------------------------------------------------------
+
+    async def list_models(
+        self,
+        *,
+        limit: int | None = None,
+        model_type: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {}
+        if limit:
+            params["limit"] = limit
+        endpoint = "/learning/models/rl" if model_type == "rl" else "/learning/models"
+        resp = await self._client.get(endpoint, params=params)
+        return self._json_list(resp, key="models")
+
+    async def get_model(self, model_id: str) -> dict[str, Any]:
+        resp = await self._client.get(f"/learning/models/{model_id}")
+        return self._json(resp)
+
+    # Helpers --------------------------------------------------------------
+
+    def _json(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail = self._extract_detail(exc.response)
+            raise StatusAPIError(detail, exc.response.status_code if exc.response else None) from exc
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise StatusAPIError("Backend response was not valid JSON") from exc
+        if isinstance(data, dict):
+            return data
+        return {"data": data}
+
+    def _json_list(self, response: httpx.Response, *, key: str | None = None) -> list[dict[str, Any]]:
+        payload = self._json(response)
+        if key and isinstance(payload.get(key), list):
+            return list(payload[key])
+        if isinstance(payload.get("data"), list):
+            return list(payload["data"])
+        if isinstance(payload.get("results"), list):
+            return list(payload["results"])
+        if isinstance(payload, list):
+            return list(payload)
+        return []
+
+    @staticmethod
+    def _extract_detail(response: httpx.Response | None) -> str:
+        if response is None:
+            return "Backend request failed"
+        try:
+            data = response.json()
+            if isinstance(data, dict):
+                for key in ("detail", "message", "error"):
+                    if data.get(key):
+                        return str(data[key])
+            return response.text
+        except ValueError:
+            return response.text

synth_ai/cli/commands/status/config.py

@@ -0,0 +1,92 @@
+"""Configuration utilities for the status command suite.
+
+Provides helpers to resolve backend URLs, API keys, and request timeouts
+from CLI options and environment variables.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+
+DEFAULT_TIMEOUT = 30.0
+
+
+def _load_backend_helpers() -> tuple[str, Callable[[], tuple[str, str]] | None]:
+    """Attempt to load shared backend helpers from synth_ai.core.env."""
+    try:
+        module = importlib.import_module("synth_ai.core.env")
+    except Exception:
+        return "https://api.usesynth.ai", None
+
+    default = getattr(module, "PROD_BASE_URL_DEFAULT", "https://api.usesynth.ai")
+    getter = getattr(module, "get_backend_from_env", None)
+    return str(default), getter if callable(getter) else None
+
+
+PROD_BASE_URL_DEFAULT, _GET_BACKEND_FROM_ENV = _load_backend_helpers()
+
+
+def _normalize_base_url(raw: str) -> str:
+    """Ensure the configured base URL includes the /api/v1 prefix."""
+    base = raw.rstrip("/") if raw else ""
+    if not base:
+        return raw
+    if base.endswith("/api") or base.endswith("/api/v1") or "/api/" in base:
+        return base
+    return f"{base}/api/v1"
+
+
+def _default_base_url() -> str:
+    """Compute the default backend base URL using env vars or helper module."""
+    for var in ("SYNTH_BACKEND_BASE_URL", "BACKEND_BASE_URL", "SYNTH_BASE_URL"):
+        val = os.getenv(var)
+        if val:
+            return _normalize_base_url(val)
+    if _GET_BACKEND_FROM_ENV:
+        try:
+            base, _ = _GET_BACKEND_FROM_ENV()
+            return _normalize_base_url(base)
+        except Exception:
+            pass
+    return _normalize_base_url(PROD_BASE_URL_DEFAULT)
+
+
+def _resolve_api_key(cli_key: str | None) -> tuple[str | None, str | None]:
+    """Resolve the API key from CLI input or known environment variables."""
+    if cli_key:
+        return cli_key, "--api-key"
+    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
+
+
+@dataclass()
+class BackendConfig:
+    """Configuration bundle shared across status commands."""
+
+    base_url: str
+    api_key: str | None
+    timeout: float = DEFAULT_TIMEOUT
+
+    @property
+    def headers(self) -> dict[str, str]:
+        if not self.api_key:
+            return {}
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+
+def resolve_backend_config(
+    *,
+    base_url: str | None,
+    api_key: str | None,
+    timeout: float | None = None,
+) -> BackendConfig:
+    """Resolve the backend configuration from CLI options/environment."""
+    resolved_url = _normalize_base_url(base_url) if base_url else _default_base_url()
+    key, _ = _resolve_api_key(api_key)
+    return BackendConfig(base_url=resolved_url, api_key=key, timeout=timeout or DEFAULT_TIMEOUT)

synth_ai/cli/commands/status/errors.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+"""
+Custom error hierarchy for status CLI commands.
+"""
+
+
+
+class StatusAPIError(RuntimeError):
+    """Raised when the backend returns a non-success response."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class StatusCLIError(RuntimeError):
+    """Raised for client-side validation errors."""
+
+    pass

synth_ai/cli/commands/status/formatters.py

@@ -0,0 +1,164 @@
+"""Rich-based formatting helpers for status commands."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from datetime import datetime
+from typing import Any
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+console = Console()
+
+
+def _format_timestamp(value: Any) -> str:
+    if value in (None, "", 0):
+        return ""
+    if isinstance(value, int | float):
+        try:
+            return datetime.fromtimestamp(float(value)).isoformat()
+        except Exception:
+            return str(value)
+    if isinstance(value, str):
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00")).strftime("%Y-%m-%d %H:%M:%S")
+        except Exception:
+            return value
+    return str(value)
+
+
+def print_json(data: Any) -> None:
+    console.print_json(data=data)
+
+
+def jobs_table(jobs: Iterable[dict[str, Any]]) -> Table:
+    table = Table(title="Training Jobs", box=box.SIMPLE, header_style="bold")
+    table.add_column("ID", style="cyan", overflow="fold")
+    table.add_column("Type", style="magenta")
+    table.add_column("Status")
+    table.add_column("Created", style="green")
+    table.add_column("Updated", style="green")
+    table.add_column("Model", style="yellow", overflow="fold")
+    for job in jobs:
+        status = job.get("status", "unknown")
+        status_color = {
+            "running": "green",
+            "queued": "cyan",
+            "succeeded": "bright_green",
+            "failed": "red",
+            "cancelled": "yellow",
+        }.get(status, "white")
+        table.add_row(
+            str(job.get("job_id") or job.get("id", "")),
+            str(job.get("training_type") or job.get("type", "")),
+            f"[{status_color}]{status}[/{status_color}]",
+            _format_timestamp(job.get("created_at")),
+            _format_timestamp(job.get("updated_at")),
+            str(job.get("model_id") or job.get("model", "")),
+        )
+    return table
+
+
+def job_panel(job: dict[str, Any]) -> Panel:
+    lines = [f"[bold cyan]Job[/bold cyan] {job.get('job_id') or job.get('id')}"]
+    if job.get("name"):
+        lines.append(f"Name: {job['name']}")
+    lines.append(f"Type: {job.get('training_type', job.get('type', ''))}")
+    lines.append(f"Status: {job.get('status', 'unknown')}")
+    if job.get("model_id"):
+        lines.append(f"Model: {job['model_id']}")
+    if job.get("base_model"):
+        lines.append(f"Base Model: {job['base_model']}")
+    lines.append(f"Created: {_format_timestamp(job.get('created_at'))}")
+    lines.append(f"Updated: {_format_timestamp(job.get('updated_at'))}")
+    if config := job.get("config"):
+        lines.append("")
+        lines.append(f"[dim]{json.dumps(config, indent=2, sort_keys=True)}[/dim]")
+    return Panel("\n".join(lines), title="Job Details", border_style="cyan")
+
+
+def runs_table(runs: Iterable[dict[str, Any]]) -> Table:
+    table = Table(title="Job Runs", box=box.SIMPLE, header_style="bold")
+    table.add_column("Run #", justify="right")
+    table.add_column("Engine")
+    table.add_column("Status")
+    table.add_column("Created")
+    table.add_column("Started")
+    table.add_column("Ended")
+    table.add_column("Duration", justify="right")
+    for run in runs:
+        table.add_row(
+            str(run.get("run_number") or run.get("id", "")),
+            str(run.get("engine", "")),
+            str(run.get("status", "unknown")),
+            _format_timestamp(run.get("created_at")),
+            _format_timestamp(run.get("started_at")),
+            _format_timestamp(run.get("ended_at")),
+            str(run.get("duration_seconds") or run.get("duration", "")),
+        )
+    return table
+
+
+def events_panel(events: Iterable[dict[str, Any]]) -> Panel:
+    rendered = []
+    for event in events:
+        ts = _format_timestamp(event.get("timestamp") or event.get("created_at"))
+        level = event.get("level") or event.get("severity", "info")
+        message = event.get("message") or event.get("detail") or ""
+        rendered.append(f"[dim]{ts}[/dim] [{level}] {message}")
+    if not rendered:
+        rendered.append("[dim]No events found.[/dim]")
+    return Panel("\n".join(rendered), title="Job Events", border_style="green")
+
+
+def metrics_table(metrics: dict[str, Any]) -> Table:
+    table = Table(title="Job Metrics", box=box.SIMPLE, header_style="bold")
+    table.add_column("Metric")
+    table.add_column("Value", justify="right")
+    for key, value in metrics.items():
+        if isinstance(value, dict):
+            table.add_row(key, Text(json.dumps(value), overflow="fold"))
+        else:
+            table.add_row(key, str(value))
+    return table
+
+
+def files_table(files: Iterable[dict[str, Any]]) -> Table:
+    table = Table(title="Training Files", box=box.SIMPLE, header_style="bold")
+    table.add_column("ID", overflow="fold")
+    table.add_column("Purpose")
+    table.add_column("Size", justify="right")
+    table.add_column("Created")
+    table.add_column("Filename", overflow="fold")
+    for file in files:
+        table.add_row(
+            str(file.get("file_id") or file.get("id", "")),
+            str(file.get("purpose", "")),
+            str(file.get("bytes", "")),
+            _format_timestamp(file.get("created_at")),
+            str(file.get("filename", "")),
+        )
+    return table
+
+
+def models_table(models: Iterable[dict[str, Any]]) -> Table:
+    table = Table(title="Fine-tuned Models", box=box.SIMPLE, header_style="bold")
+    table.add_column("ID", overflow="fold")
+    table.add_column("Base")
+    table.add_column("Created")
+    table.add_column("Owner")
+    table.add_column("Status")
+    for model in models:
+        table.add_row(
+            str(model.get("id", model.get("name", ""))),
+            str(model.get("base_model") or model.get("base", "")),
+            _format_timestamp(model.get("created_at")),
+            str(model.get("owner") or model.get("organization", "")),
+            str(model.get("status", "")),
+        )
+    return table

synth_ai/cli/commands/status/subcommands/__init__.py

@@ -0,0 +1,9 @@
+"""
+Subcommands for the status CLI namespace.
+"""
+
+from .files import files_group  # noqa: F401
+from .jobs import jobs_group  # noqa: F401
+from .models import models_group  # noqa: F401
+from .runs import runs_group  # noqa: F401
+from .summary import summary_command  # noqa: F401

synth_ai/cli/commands/status/subcommands/files.py

@@ -0,0 +1,79 @@
+"""`synth files` command group."""
+
+from __future__ import annotations
+
+import asyncio
+
+import click
+from rich.json import JSON
+
+from ..client import StatusAPIClient
+from ..errors import StatusAPIError
+from ..formatters import console, files_table, print_json
+from ..utils import bail, common_options, resolve_context_config
+
+
+@click.group("files", help="Manage training files.")
+@click.pass_context
+def files_group(ctx: click.Context) -> None:  # pragma: no cover - Click wiring
+    ctx.ensure_object(dict)
+
+
+@files_group.command("list")
+@common_options()
+@click.option("--purpose", type=click.Choice(["fine-tune", "validation"]))
+@click.option("--limit", type=int, default=20, show_default=True)
+@click.option("--json", "output_json", is_flag=True)
+@click.pass_context
+def list_files(
+    ctx: click.Context,
+    base_url: str | None,
+    api_key: str | None,
+    timeout: float,
+    purpose: str | None,
+    limit: int,
+    output_json: bool,
+) -> None:
+    cfg = resolve_context_config(ctx, base_url=base_url, api_key=api_key, timeout=timeout)
+
+    async def _run() -> None:
+        try:
+            async with StatusAPIClient(cfg) as client:
+                files = await client.list_files(purpose=purpose, limit=limit)
+                if output_json:
+                    print_json(files)
+                else:
+                    console.print(files_table(files))
+        except StatusAPIError as exc:
+            bail(f"Backend error: {exc}")
+
+    asyncio.run(_run())
+
+
+@files_group.command("get")
+@common_options()
+@click.argument("file_id")
+@click.option("--json", "output_json", is_flag=True)
+@click.pass_context
+def get_file(
+    ctx: click.Context,
+    base_url: str | None,
+    api_key: str | None,
+    timeout: float,
+    file_id: str,
+    output_json: bool,
+) -> None:
+    cfg = resolve_context_config(ctx, base_url=base_url, api_key=api_key, timeout=timeout)
+
+    async def _run() -> None:
+        try:
+            async with StatusAPIClient(cfg) as client:
+                file_info = await client.get_file(file_id)
+                if output_json:
+                    print_json(file_info)
+                else:
+                    console.print(JSON.from_data(file_info))
+        except StatusAPIError as exc:
+            bail(f"Backend error: {exc}")
+
+    asyncio.run(_run())