analogcli 0.1.4__py3-none-any.whl

anabrid/cloud/cli/utils.py

@@ -0,0 +1,421 @@
+"""Shared utilities and display helpers for CLI commands."""
+
+import csv
+import datetime
+import enum
+import functools
+import locale
+import sys
+import time
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.syntax import Syntax
+from rich.table import Table
+import json
+
+from .client import AnalogCloudClient, AnalogCloudAPIError, TERMINAL_TASK_STATES
+from .client import StateConflictError
+from anabrid.cloud.models.api.v1 import (
+    TaskStatusResponse,
+    DeviceResponse,
+    SystemStatusResponse,
+)
+
+console = Console()
+
+
+try:
+    locale.setlocale(locale.LC_TIME, "")
+except locale.Error:
+    pass
+
+
+def format_timestamp(value: Any) -> str:
+    """Render *value* as a locale-aware date+time string for human display.
+
+    Server timestamps are stored as naive UTC; this helper treats a naive
+    ``datetime`` as UTC, converts it to the user's local time zone, drops
+    the microsecond component (sub-second precision is noise for a human),
+    and renders via ``strftime("%c")`` so the output respects the
+    ``LC_TIME`` environment locale (e.g. ``Fr 08 Mai 2026 17:24:25 CEST``
+    on a German system). Anything that is not a ``datetime`` is returned
+    via ``str(value)`` so callers can pass partial / missing fields
+    straight through.
+    """
+    if not isinstance(value, datetime.datetime):
+        return str(value) if value is not None else ""
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=datetime.timezone.utc)
+    return value.astimezone().replace(microsecond=0).strftime("%c")
+
+
+def format_uptime(seconds: int) -> str:
+    """Render an uptime *seconds* count as a ``?d ?h ?m ?s`` string.
+
+    Units above the largest non-zero one are dropped (``225`` becomes
+    ``3m 45s``, not ``0d 0h 3m 45s``), while interior and trailing zero
+    units are kept once a larger unit is present (``3600`` becomes
+    ``1h 0m 0s``) so the components stay aligned. A zero or negative
+    count - the latter being a nonsensical clock skew - clamps to
+    ``0s`` rather than rendering empty.
+    """
+    seconds = max(int(seconds), 0)
+    days, rem = divmod(seconds, 86_400)
+    hours, rem = divmod(rem, 3_600)
+    minutes, secs = divmod(rem, 60)
+
+    parts = [(days, "d"), (hours, "h"), (minutes, "m"), (secs, "s")]
+    # Drop leading zero units; keep everything from the first non-zero
+    # unit down to seconds. ``next`` defaults to the last index so an
+    # all-zero uptime still renders the trailing ``0s``.
+    first = next(
+        (i for i, (value, _) in enumerate(parts) if value), len(parts) - 1
+    )
+    return " ".join(f"{value}{label}" for value, label in parts[first:])
+
+
+class OutputMode(enum.Enum):
+    """Selects how a CLI command renders its primary output."""
+
+    RICH = "rich"
+    TEXT = "text"
+    JSON = "json"
+
+
+def _stdout_is_tty() -> bool:
+    """Return True if ``sys.stdout`` reports being attached to a TTY."""
+    isatty = getattr(sys.stdout, "isatty", None)
+    if isatty is None:
+        return False
+    try:
+        return bool(isatty())
+    except Exception:
+        return False
+
+
+def pick_output_mode(
+    ctx: click.Context | None,
+    format: str | None,
+    follow: bool,
+) -> OutputMode:
+    """Select the output mode for a CLI command.
+
+    The CLI is used in two distinct contexts: an interactive terminal
+    (humans reading) and a pipeline such as ``analogcli task list | jq``
+    or a CI script (machines parsing). Rich panels and spinners help in
+    the first context and actively break the second — box-drawing
+    characters confuse ``grep``, colour escape sequences confuse
+    ``jq``. This helper centralises that decision so each command stays
+    short: derive ``OutputMode`` once from
+    ``(--format, --follow, sys.stdout.isatty())`` and dispatch to a Rich
+    or plain helper. The helpers themselves do not re-check.
+
+    The precedence captures "explicit user intent beats heuristics, an
+    active TTY means a human is watching, an inherited pipe means a
+    machine is watching":
+
+    - ``format == "json"`` → ``OutputMode.JSON`` (explicit wins)
+    - ``format == "text"`` → ``OutputMode.TEXT`` (explicit wins)
+    - ``format is None`` (auto-detect):
+        - ``follow`` is True → ``OutputMode.RICH`` (the user has opted
+          into an interactive watch loop, so Rich spinners/panels are
+          the right choice)
+        - else if stdout is a TTY → ``OutputMode.TEXT`` (human is
+          watching; structured but plain output)
+        - else → ``OutputMode.JSON`` (output is being piped; emit
+          machine-parsable JSON by default).
+    """
+    if format == "json":
+        return OutputMode.JSON
+    if format == "text":
+        return OutputMode.TEXT
+    if format is not None:
+        raise click.UsageError(
+            f"Unknown --format value: {format!r}. Expected 'text' or 'json'."
+        )
+    if follow:
+        return OutputMode.RICH
+    if _stdout_is_tty():
+        return OutputMode.TEXT
+    return OutputMode.JSON
+
+
+def handle_api_error(func):
+    """Decorator mapping known exceptions to CLI exit codes.
+
+    Mapping:
+    - ``StateConflictError`` → exit 4
+    - ``AnalogCloudAPIError`` → exit 3
+    - ``TimeoutError`` → exit 124
+    - any other exception propagates unchanged
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except StateConflictError as exc:
+            click.echo(f"Error: {exc}", err=True)
+            sys.exit(4)
+        except AnalogCloudAPIError as exc:
+            click.echo(f"Error: {exc}", err=True)
+            sys.exit(3)
+        except TimeoutError as exc:
+            click.echo(f"Error: timed out: {exc}", err=True)
+            sys.exit(124)
+
+    return wrapper
+
+
+def print_task_logs_plain(lines: list[str]) -> None:
+    """Emit task log lines as raw newline-separated text on stdout."""
+    if not lines:
+        return
+    click.echo("\n".join(lines))
+
+
+def print_task_table(tasks: list) -> None:
+    """Render a table of task summaries for TTY consumption."""
+    if not tasks:
+        console.print("(no tasks)")
+        return
+
+    table = Table(title="Tasks")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Type", style="magenta")
+    table.add_column("State", style="green")
+    table.add_column("Created At", style="white")
+
+    def _field(item, name: str) -> Any:
+        if isinstance(item, dict):
+            return item.get(name)
+        return getattr(item, name, None)
+
+    for task in tasks:
+        raw_id = _field(task, "id")
+        id_str = str(raw_id) if raw_id is not None else ""
+        type_val = _field(task, "type")
+        type_str = type_val.value if hasattr(type_val, "value") else str(type_val)
+        state_val = _field(task, "state")
+        state_str = state_val.value if hasattr(state_val, "value") else str(state_val)
+        created_str = format_timestamp(_field(task, "created_at"))
+        table.add_row(id_str, type_str, state_str, created_str)
+
+    console.print(table)
+
+
+def dump_task_json(obj: Any) -> None:
+    """Serialise *obj* to stdout as a single JSON document."""
+
+    def _to_jsonable(value: Any) -> Any:
+        if hasattr(value, "model_dump"):
+            return value.model_dump(mode="json")
+        if isinstance(value, dict):
+            return {key: _to_jsonable(item) for key, item in value.items()}
+        if isinstance(value, list):
+            return [_to_jsonable(item) for item in value]
+        if isinstance(value, datetime.datetime):
+            return value.isoformat()
+        return value
+
+    payload = _to_jsonable(obj)
+    click.echo(json.dumps(payload, indent=2, default=str))
+
+
+def print_search_table(rows: list[dict], columns: list[str]) -> None:
+    """Render search-result *rows* as a Rich table over the given *columns*.
+
+    Each row is a flat ``dict`` keyed by column name; missing keys render as an
+    empty cell. Prints ``(no tasks)`` when *rows* is empty. Used by
+    ``analogcli task search`` to surface the per-job ``user_id`` (and, with
+    ``--recursive``, device metadata) that the plain task table omits.
+
+    A wide console (no fixed column limit) is used so that cell content is not
+    truncated with "…" regardless of how many columns are rendered.
+    """
+    if not rows:
+        console.print("(no tasks)")
+        return
+
+    wide = Console(width=max(200, 20 * len(columns)))
+    table = Table()
+    for col in columns:
+        table.add_column(col)
+
+    for row in rows:
+        table.add_row(*[str(row.get(col, "")) for col in columns])
+
+    wide.print(table)
+
+
+def write_task_csv(rows: list[dict], path: str, columns: list[str]) -> None:
+    """Write search-result *rows* to *path* as CSV with a *columns* header.
+
+    Always emits the header row, so an empty *rows* yields a header-only file.
+    Cells absent from a row are written blank. Column order follows *columns*.
+    """
+    with open(path, "w", newline="") as fh:
+        writer = csv.DictWriter(fh, fieldnames=columns, extrasaction="ignore")
+        writer.writeheader()
+        for row in rows:
+            writer.writerow(row)
+
+
+def format_json_output(data: dict) -> str:
+    """Return *data* as an indented JSON string."""
+    return json.dumps(data, indent=2)
+
+
+def display_system_info(
+    system_info: SystemStatusResponse,
+    devices: list[DeviceResponse],
+) -> None:
+    """Render system status and device tables to the console."""
+    system_table = Table(title="System Status", show_header=False)
+    system_table.add_column("Property", style="cyan")
+    system_table.add_column("Value", style="white")
+
+    system_table.add_row("Domain", system_info.domain)
+    system_table.add_row("Version", system_info.version)
+    system_table.add_row("Uptime", format_uptime(system_info.uptime))
+
+    console.print(system_table)
+    console.print()
+
+    if not devices:
+        console.print("[yellow]No devices connected[/yellow]")
+        return
+
+    available = [d for d in devices if d.available]
+    unavailable = [d for d in devices if not d.available]
+
+    if available:
+        avail_table = Table(title="Available Devices")
+        avail_table.add_column("Name", style="green")
+        avail_table.add_column("Type", style="cyan")
+        avail_table.add_column("Queue", style="yellow")
+
+        for device in available:
+            avail_table.add_row(
+                device.name, device.type.value, str(device.queue_length)
+            )
+
+        console.print(avail_table)
+        console.print()
+
+    if unavailable:
+        unavail_table = Table(title="Unavailable Devices")
+        unavail_table.add_column("Name", style="red")
+        unavail_table.add_column("Type", style="cyan")
+        unavail_table.add_column("Queue", style="yellow")
+
+        for device in unavailable:
+            unavail_table.add_row(
+                device.name, device.type.value, str(device.queue_length)
+            )
+
+        console.print(unavail_table)
+
+
+def display_task_logs(lines: list[str]) -> None:
+    """Render a list of log lines in a bordered panel."""
+    if not lines:
+        console.print("[yellow]No logs available[/yellow]")
+        return
+
+    console.print(Panel("\n".join(lines), title="Task Logs", border_style="blue"))
+
+
+def display_task_output(output_data: Any) -> None:
+    """Render task output as formatted JSON."""
+    if output_data is None:
+        console.print("[yellow]No output data available[/yellow]")
+        return
+
+    json_str = (
+        format_json_output(output_data)
+        if isinstance(output_data, dict)
+        else json.dumps(output_data, indent=2)
+    )
+    syntax = Syntax(json_str, "json", theme="monokai", line_numbers=True)
+    console.print(Panel(syntax, title="Task Output", border_style="green"))
+
+
+def wait_for_task_with_progress(
+    client: AnalogCloudClient,
+    task_id: str,
+    task_description: str = "Running task",
+) -> TaskStatusResponse:
+    """Poll *task_id* with a Rich spinner until it reaches a terminal state."""
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+        transient=True,
+    ) as progress:
+        ptask = progress.add_task(
+            description=f"{task_description} (ID: {str(task_id)[:8]}...)", total=None
+        )
+
+        while True:
+            try:
+                status = client.get_task_status(task_id)
+
+                progress.update(
+                    ptask,
+                    description=f"{task_description} — {status.state.value} (ID: {str(task_id)[:8]}...)",
+                )
+
+                if status.state in TERMINAL_TASK_STATES:
+                    break
+
+                time.sleep(1.0)
+
+            except AnalogCloudAPIError as exc:
+                progress.update(ptask, description=f"Error checking task status: {exc}")
+                raise
+
+    return status
+
+
+def validate_json_file(file_path: str) -> dict:
+    """Load and validate a JSON file, printing user-friendly errors on failure."""
+    try:
+        from .client import load_json_file
+
+        return load_json_file(file_path)
+    except FileNotFoundError:
+        console.print(f"[red]Error: File not found: {file_path}[/red]")
+        raise click.Abort()
+    except ValueError as exc:
+        console.print(f"[red]Error: {exc}[/red]")
+        raise click.Abort()
+    except Exception as exc:
+        console.print(f"[red]Error reading file: {exc}[/red]")
+        raise click.Abort()
+
+
+def load_binary_file(file_path: str) -> bytes:
+    """Read a binary file and return its contents.
+
+    Raises ``click.Abort`` with a user-friendly message on failure.
+    """
+    import os
+
+    if not os.path.exists(file_path):
+        console.print(f"[red]Error: File not found: {file_path}[/red]")
+        raise click.Abort()
+
+    try:
+        with open(file_path, "rb") as f:
+            return f.read()
+    except Exception as exc:
+        console.print(f"[red]Error reading file: {exc}[/red]")
+        raise click.Abort()
+
+

analogcli-0.1.4.dist-info/METADATA

@@ -0,0 +1,276 @@
+Metadata-Version: 2.1
+Name: analogcli
+Version: 0.1.4
+Summary: Command-line interface for the Analog Cloud system
+Author-Email: Anabrid <info@anabrid.com>
+Requires-Python: <4.0,>=3.11
+Requires-Dist: click<9.0.0,>=8.1.7
+Requires-Dist: httpx<1.0.0,>=0.25.0
+Requires-Dist: analogcloud-common==0.1.4
+Requires-Dist: numpy>=2.4
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: rich<14.0.0,>=13.0.0
+Requires-Dist: sympy>=1.14.0
+Description-Content-Type: text/markdown
+
+# Analog Cloud CLI
+
+Command-line interface for the Analog Cloud analog computing system.
+
+## Overview
+
+The Analog Cloud CLI provides a convenient command-line interface to interact with Analog Cloud's analog computing devices through the REST API. You can submit tasks, monitor their progress, and retrieve results directly from your terminal.
+
+## Installation
+
+1. Navigate to the CLI directory:
+   ```bash
+   cd components/cli
+   ```
+
+2. Install using pip:
+   ```bash
+   pip install analogcli
+   ```
+
+3. The CLI tool will be available as `analogcli` command after installation.
+
+## Usage
+
+### Basic Commands
+
+The CLI connects to an Analog Cloud API server. By default, it connects to `localhost:8000`, but you can specify different host and port:
+
+```bash
+# Connect to default server
+analogcli status
+
+# Connect to different server
+analogcli -h 192.168.1.100 -p 8080 status
+```
+
+### Available Commands
+
+#### 1. System Status
+Get system information and connected devices:
+```bash
+analogcli status
+```
+
+#### 2. Run Tasks
+Execute a configuration on physical LUCIDAC device:
+```bash
+# Basic run
+analogcli run config.json
+
+# With custom parameters
+analogcli run config.json --sample-rate 20000 --op-time 0.5 --device device1
+```
+
+Options:
+- `--sample-rate`: Number of samples per second (default: 10000)
+- `--op-time`: Integration time in seconds (default: 0.1)
+- `--device`: Specific device ID (auto-detected if not specified)
+
+#### 3. Simulate Tasks
+Execute a configuration on the built-in simulator:
+```bash
+# Basic simulation
+analogcli simulate config.json
+
+# With simulator options
+analogcli simulate config.json --k0 1000 --with-limits --op-time 1.0
+```
+
+Options:
+- `--sample-rate`: Number of samples per second (default: 10000)
+- `--op-time`: Integration time in seconds (default: 0.1)
+- `--k0`: Acceleration factor (choices: 1, 10, 100, 1000, 10000; default: 10000)
+- `--with-limits`: Enable integrator capacity limits
+- `--device`: Device context (auto-detected if not specified)
+
+#### 4. Compile Tasks
+Compile an ODE specification to device configuration:
+```bash
+# Basic compilation
+analogcli compiler ode.json
+```
+
+#### 5. Async submission with `--follow / --no-follow`
+
+`compile` and `run` are interactive by default (`--follow`): the CLI
+submits the task, polls the server, and prints logs and results in
+place. For pipelines and long-running jobs use `--no-follow`:
+
+```bash
+# Fire and forget — print only the UUID on stdout
+TASK_ID=$(analogcli run config.json --no-follow)
+
+# Use the id with task subcommands later
+analogcli task wait "$TASK_ID"
+analogcli task result "$TASK_ID" -o result.json
+```
+
+In `--no-follow` mode stdout is **strictly** the UUID; the "Task
+submitted" notice goes to stderr so it does not corrupt pipelines.
+
+### Task management — `analogcli task`
+
+The `task` subcommand group inspects, awaits, and withdraws tasks
+asynchronously. Output is TTY-aware: interactive terminals get Rich
+panels and tables, pipes get JSON (or raw text for `task logs`).
+
+```bash
+analogcli task list      [--state S] [--type T] [--limit N] [--offset N]
+                         [--ids-only] [--format text|json]
+analogcli task info      <id> [--format text|json]
+analogcli task status    <id> [--format text|json]
+analogcli task logs      <id> [--follow] [--format text|json]
+analogcli task result    <id> [-o FILE]
+analogcli task wait      <id> [--poll-interval S] [--timeout S]
+analogcli task revoke    <id>
+analogcli task delete    <id>
+```
+
+- `task list` enumerates tasks visible to your API key. Use
+  `--ids-only` to emit one UUID per line for shell loops; use
+  `--format json` for a structured dump.
+- `task info` shows the full detail record (type-specific fields for
+  compile vs run).
+- `task status` shows the current state and the state-transition
+  history.
+- `task logs` prints the captured log output. With `--follow` the
+  command polls every second and emits only newly appended lines until
+  the task reaches a terminal state. Off a TTY the snapshot defaults
+  to raw text so `grep` works.
+- `task result` writes the task's result payload. Compile tasks
+  produce binary device configurations (written to `-o FILE` or to
+  binary stdout); run tasks produce JSON (pretty-printed, written to
+  `-o FILE` or stdout).
+- `task wait` blocks until the task reaches a terminal state and
+  carries the outcome via the exit code — stdout is left empty so the
+  shell can branch on `$?` without parsing output.
+- `task revoke` withdraws a `QUEUED` task. It does *not* abort a task
+  that is already running (the worker keeps it). The wire-level
+  endpoint remains `POST /tasks/{id}/cancel`; the CLI verb is named
+  `revoke` because that better reflects the user-visible semantic.
+- `task delete` removes a task and its blobs. The server refuses
+  `DELETE` on an `INPROGRESS` task whose worker run is less than two
+  minutes old, to protect the worker.
+
+#### Exit-code contract
+
+Shell scripts can rely on the following exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0    | success / `SUCCEEDED` |
+| 1    | task `FAILED` (for `wait`) |
+| 2    | task `CANCELLED` (for `wait`) |
+| 3    | transport / API error (connection refused, 5xx, etc.) |
+| 4    | state conflict — e.g. `revoke` on a non-`QUEUED` task, or `delete` inside the worker grace window (HTTP 409) |
+| 124  | timeout (matches GNU `timeout`); emitted by `task wait --timeout S` |
+
+Example: revoke a queued task only if it is still queued, otherwise
+fall through to waiting on it:
+
+```bash
+if ! analogcli task revoke "$TASK_ID" 2>/dev/null; then
+    case $? in
+        4) analogcli task wait "$TASK_ID" ;;  # already running — wait it out
+        *) exit $? ;;
+    esac
+fi
+```
+
+### File Formats
+
+#### Configuration Files (for run/simulate)
+JSON files containing analog circuit configurations:
+```json
+{
+  "integrators": {
+    "int0": {"initial_value": 1.0}
+  },
+  "constants": {
+    "k1": 2.5
+  },
+  "connections": []
+}
+```
+
+#### ODE Files (for compiler)
+JSON files containing ODE specifications:
+```json
+{
+  "variables": ["x", "y"],
+  "equations": {
+    "x": "-y",
+    "y": "x"
+  },
+  "initial_conditions": {
+    "x": 1.0,
+    "y": 0.0
+  }
+}
+```
+
+### Example Workflow
+
+1. Check system status:
+   ```bash
+   analogcli status
+   ```
+
+2. Compile an ODE to configuration:
+   ```bash
+   analogcli compiler my_ode.json
+   # Save the output to compiled_config.json when prompted
+   ```
+
+3. Run the compiled configuration:
+   ```bash
+   analogcli run compiled_config.json --sample-rate 25000 --op-time 0.2
+   ```
+
+4. Or simulate instead:
+   ```bash
+   analogcli simulate compiled_config.json --k0 1000 --with-limits
+   ```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANALOGCLOUD_API_KEY` | API key for authentication (required) |
+| `ANALOGCLOUD_URL` | Base URL of the Analog Cloud server |
+
+## Development
+
+### Running Tests
+```bash
+uv run pytest
+```
+
+### Code Formatting
+```bash
+uv run black .
+```
+
+## Dependencies
+
+- **click**: Command-line interface framework
+- **httpx**: HTTP client for API communication
+- **pydantic**: Data validation using the shared models
+- **rich**: Rich text and beautiful formatting in the terminal
+- **analogcloud-common**: Shared models and utilities
+
+## Error Handling
+
+The CLI provides user-friendly error messages for common issues:
+- Connection errors to the API server
+- Invalid JSON files
+- Missing files
+- API errors with detailed messages
+
+Progress indicators show task status during execution, and results are displayed in a formatted, readable way.