analogcli 0.1.4__py3-none-any.whl

anabrid/cloud/cli/commands/run.py

@@ -0,0 +1,116 @@
+"""CLI command for executing a compiled module on a physical device."""
+
+import click
+import json
+from ..context import get_client
+from ..utils import (
+    handle_api_error,
+    load_binary_file,
+    wait_for_task_with_progress,
+    display_task_logs,
+    display_task_output,
+    console,
+)
+from anabrid.cloud.models.enums import TaskStateEnum
+
+
+@click.command()
+@click.argument("module_file", type=click.Path(exists=True))
+@click.option(
+    "--sample-rate",
+    default=10000,
+    type=int,
+    show_default=True,
+    help="ADC samples drawn per second",
+)
+@click.option(
+    "--op-time",
+    default=0.1,
+    type=float,
+    show_default=True,
+    help="Wall-clock integration time in seconds",
+)
+@click.option(
+    "--device",
+    help="Device name to run on.  If omitted, the first available LUCIDAC is used.",
+)
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    help="Save run result JSON to this file path",
+)
+@click.option(
+    "--follow/--no-follow",
+    default=True,
+    show_default=True,
+    help="Wait for the task to finish; with --no-follow only the UUID is printed.",
+)
+@click.pass_context
+@handle_api_error
+def run(
+    ctx: click.Context,
+    module_file: str,
+    sample_rate: int,
+    op_time: float,
+    device: str | None,
+    output: str | None,
+    follow: bool,
+):
+    """Execute a compiled module on a physical LUCIDAC device.
+
+    MODULE_FILE should be a compiled protobuf configuration blob (.apb).
+
+    Example:
+        analogcli run compiled.apb --sample-rate 20000 --op-time 0.5 --device lucidac-01
+    """
+    module_bytes = load_binary_file(module_file)
+
+    with get_client(ctx) as client:
+        if not device:
+            devices = client.get_devices()
+            lucidacs = [
+                d for d in devices if "lucidac" in d.name.lower() and d.available
+            ]
+            if not lucidacs:
+                console.print("[red]No available LUCIDAC device found[/red]")
+                return
+            device = lucidacs[0].name
+            if follow:
+                console.print(f"[yellow]Using device: {device}[/yellow]")
+
+        if follow:
+            console.print(f"[blue]Submitting run task to device {device}...[/blue]")
+        task_id = client.submit_run_task(
+            device_name=device,
+            module=module_bytes,
+            sample_rate=sample_rate,
+            op_time=op_time,
+        )
+
+        if not follow:
+            click.echo(task_id)
+            click.echo(f"Task submitted: {task_id}", err=True)
+            return
+
+        console.print(f"[green]Task submitted with ID: {task_id}[/green]")
+
+        final_status = wait_for_task_with_progress(client, task_id, "Running on device")
+
+        log_response = client.get_task_log(task_id)
+        display_task_logs(log_response.lines)
+
+        if final_status.state == TaskStateEnum.SUCCEEDED:
+            console.print("\n[bold green]Task completed successfully![/bold green]")
+
+            result = client.get_task_result(task_id)
+            console.print()
+            display_task_output(result)
+
+            if output:
+                with open(output, "w") as f:
+                    json.dump(result, f, indent=2)
+                console.print(f"[green]Result saved to {output}[/green]")
+        else:
+            error = final_status.error or "(no detail)"
+            console.print(f"\n[bold red]Task failed: {error}[/bold red]")

anabrid/cloud/cli/commands/status.py

@@ -0,0 +1,20 @@
+"""CLI command for displaying system and device status."""
+
+import click
+from ..context import get_client
+from ..utils import handle_api_error, display_system_info
+
+
+@click.command()
+@click.pass_context
+@handle_api_error
+def status(ctx: click.Context):
+    """Display system status and all connected devices.
+
+    Shows the hub domain, version, uptime, and a table of available
+    and unavailable devices with their current queue lengths.
+    """
+    with get_client(ctx) as client:
+        system_info = client.get_system_status()
+        devices = client.get_devices()
+        display_system_info(system_info, devices)

anabrid/cloud/cli/commands/task/__init__.py

@@ -0,0 +1,29 @@
+"""Task management commands registered under ``analogcli task``."""
+
+import click
+
+from .delete import task_delete
+from .info import task_info
+from .list import task_list
+from .logs import task_logs
+from .result import task_result
+from .revoke import task_revoke
+from .search import task_search
+from .status import task_status
+from .wait import task_wait
+
+
+@click.group(name="task")
+def task() -> None:
+    """Operations on tasks (list / search / info / status / logs / result / wait / revoke / delete)."""
+
+
+task.add_command(task_list, name="list")
+task.add_command(task_search, name="search")
+task.add_command(task_info, name="info")
+task.add_command(task_status, name="status")
+task.add_command(task_logs, name="logs")
+task.add_command(task_result, name="result")
+task.add_command(task_wait, name="wait")
+task.add_command(task_revoke, name="revoke")
+task.add_command(task_delete, name="delete")

anabrid/cloud/cli/commands/task/delete.py

@@ -0,0 +1,22 @@
+"""``analogcli task delete`` — permanently delete a task and its blobs."""
+
+import click
+
+from ...context import get_client
+from ...utils import handle_api_error
+
+__all__ = ["task_delete", "get_client"]
+
+
+@click.command()
+@click.argument("task_id")
+@click.pass_context
+@handle_api_error
+def task_delete(ctx: click.Context, task_id: str) -> None:
+    """Permanently delete *task_id* and its associated blobs.
+
+    Stdout stays empty on success; a 409 state conflict is mapped to
+    exit code 4 by the ``handle_api_error`` decorator.
+    """
+    with get_client(ctx) as client:
+        client.delete_task(task_id)

anabrid/cloud/cli/commands/task/info.py

@@ -0,0 +1,66 @@
+"""``analogcli task info`` — detailed task view."""
+
+import click
+from rich.panel import Panel
+
+from ...context import get_client
+from ...utils import (
+    OutputMode,
+    console,
+    dump_task_json,
+    format_timestamp,
+    handle_api_error,
+    pick_output_mode,
+)
+
+
+@click.command()
+@click.argument("task_id")
+@click.option(
+    "--format",
+    "format_",
+    type=click.Choice(["text", "json"]),
+    default=None,
+    help="Force the output format; defaults to auto-detect from TTY.",
+)
+@click.pass_context
+@handle_api_error
+def task_info(ctx: click.Context, task_id: str, format_: str | None) -> None:
+    """Show detailed information for a single task."""
+    with get_client(ctx) as client:
+        detail = client.get_task_detail(task_id)
+
+    mode = pick_output_mode(ctx, format_, follow=False)
+    if mode == OutputMode.JSON:
+        dump_task_json(detail)
+        return
+
+    type_val = detail.type
+    type_str = type_val.value if hasattr(type_val, "value") else str(type_val)
+    state_val = detail.state
+    state_str = state_val.value if hasattr(state_val, "value") else str(state_val)
+    created_str = format_timestamp(detail.created_at)
+
+    lines = [
+        f"[cyan]ID:[/cyan] {detail.id}",
+        f"[cyan]Type:[/cyan] {type_str}",
+        f"[cyan]State:[/cyan] {state_str}",
+        f"[cyan]Created:[/cyan] {created_str}",
+    ]
+    if getattr(detail, "error", None):
+        lines.append(f"[red]Error:[/red] {detail.error}")
+    if hasattr(detail, "backend"):
+        backend = detail.backend
+        backend_str = backend.value if hasattr(backend, "value") else str(backend)
+        lines.append(f"[cyan]Backend:[/cyan] {backend_str}")
+        lines.append(f"[cyan]k0:[/cyan] {detail.k0}")
+    if hasattr(detail, "device_name"):
+        lines.append(f"[cyan]Device:[/cyan] {detail.device_name}")
+        lines.append(f"[cyan]Sample rate:[/cyan] {detail.sample_rate}")
+        lines.append(f"[cyan]Op time:[/cyan] {detail.op_time}")
+    if hasattr(detail, "has_result"):
+        lines.append(f"[cyan]Has result:[/cyan] {detail.has_result}")
+    if hasattr(detail, "has_log"):
+        lines.append(f"[cyan]Has log:[/cyan] {detail.has_log}")
+
+    console.print(Panel("\n".join(lines), title=f"Task {detail.id}"))

anabrid/cloud/cli/commands/task/list.py

@@ -0,0 +1,82 @@
+"""``analogcli task list`` — paginated, filterable task listing."""
+
+import click
+
+from ...context import get_client
+from ...utils import (
+    OutputMode,
+    dump_task_json,
+    handle_api_error,
+    pick_output_mode,
+    print_task_table,
+)
+
+
+@click.command()
+@click.option(
+    "--state",
+    default=None,
+    help="Filter tasks by state (e.g. QUEUED, INPROGRESS, SUCCEEDED).",
+)
+@click.option(
+    "--type",
+    "task_type",
+    default=None,
+    help="Filter tasks by type (e.g. compile, run).",
+)
+@click.option(
+    "--limit",
+    default=None,
+    type=int,
+    help="Maximum number of tasks to return.",
+)
+@click.option(
+    "--offset",
+    default=None,
+    type=int,
+    help="Number of tasks to skip before the page.",
+)
+@click.option(
+    "--ids-only",
+    is_flag=True,
+    default=False,
+    help="Emit one UUID per line on stdout (overrides --format).",
+)
+@click.option(
+    "--format",
+    "format_",
+    type=click.Choice(["text", "json"]),
+    default=None,
+    help="Force the output format; defaults to auto-detect from TTY.",
+)
+@click.pass_context
+@handle_api_error
+def task_list(
+    ctx: click.Context,
+    state: str | None,
+    task_type: str | None,
+    limit: int | None,
+    offset: int | None,
+    ids_only: bool,
+    format_: str | None,
+) -> None:
+    """List tasks visible to the current API key."""
+    with get_client(ctx) as client:
+        tasks = client.list_tasks(
+            state=state,
+            type=task_type,
+            limit=limit,
+            offset=offset,
+        )
+
+    if ids_only:
+        for task in tasks:
+            task_id = task.id if hasattr(task, "id") else task["id"]
+            click.echo(str(task_id))
+        return
+
+    mode = pick_output_mode(ctx, format_, follow=False)
+    if mode == OutputMode.JSON:
+        dump_task_json(tasks)
+    else:
+        print_task_table(tasks)

anabrid/cloud/cli/commands/task/logs.py

@@ -0,0 +1,120 @@
+"""``analogcli task logs`` — fetch (and optionally follow) a task's log output."""
+
+import time
+
+import click
+from rich.panel import Panel
+
+from ...context import get_client
+from ...utils import (
+    OutputMode,
+    console,
+    dump_task_json,
+    handle_api_error,
+    pick_output_mode,
+    print_task_logs_plain,
+)
+
+__all__ = ["task_logs", "get_client", "time", "POLL_INTERVAL"]
+
+
+POLL_INTERVAL: float = 1.0
+"""Seconds between polls in ``--follow`` mode. Patched to 0 in tests."""
+
+
+_TERMINAL_STATE_VALUES = frozenset({"succeeded", "failed", "cancelled"})
+"""Lowercase wire-level values considered terminal for follow-mode polling."""
+
+
+def _state_value(state: object) -> str:
+    """Return the lowercase string value of a state enum or raw string."""
+    raw = getattr(state, "value", state)
+    return str(raw).lower()
+
+
+def _pick_logs_output_mode(
+    ctx: click.Context | None, format_: str | None
+) -> OutputMode:
+    """Pick the output mode for ``task logs`` snapshot output.
+
+    Logs are text-native: the natural downstream consumer of piped log
+    output is ``grep``, not ``jq``. That makes the JSON-by-default
+    behaviour of the shared ``pick_output_mode`` (designed for
+    structured commands like ``task list``) the wrong choice here. This
+    helper overrides the auto-detect branch to default to TEXT off-TTY
+    while still honouring an explicit ``--format`` verbatim, so the
+    user can opt into JSON when they want it.
+    """
+    if format_ is not None:
+        return pick_output_mode(ctx, format_, follow=False)
+    if _stdout_is_tty():
+        return OutputMode.RICH
+    return OutputMode.TEXT
+
+
+def _stdout_is_tty() -> bool:
+    """Return True if ``sys.stdout`` reports being attached to a TTY."""
+    import sys
+
+    isatty = getattr(sys.stdout, "isatty", None)
+    if isatty is None:
+        return False
+    try:
+        return bool(isatty())
+    except Exception:
+        return False
+
+
+@click.command()
+@click.argument("task_id")
+@click.option(
+    "--follow",
+    is_flag=True,
+    default=False,
+    help="Continuously poll for new log lines until the task reaches a terminal state.",
+)
+@click.option(
+    "--format",
+    "format_",
+    type=click.Choice(["text", "json"]),
+    default=None,
+    help="Force the output format; defaults to auto-detect from TTY.",
+)
+@click.pass_context
+@handle_api_error
+def task_logs(
+    ctx: click.Context, task_id: str, follow: bool, format_: str | None
+) -> None:
+    """Show the log output for *task_id*.
+
+    Snapshot mode (default): fetch once and render to stdout. On a TTY the
+    log lines appear in a Rich panel; off a TTY the raw newline-joined
+    lines are printed so ``grep`` works.
+
+    With ``--follow``: poll periodically and emit only newly appended lines
+    until the task reaches a terminal state.
+    """
+    with get_client(ctx) as client:
+        if not follow:
+            log = client.get_task_log(task_id)
+            lines = log.lines
+            mode = _pick_logs_output_mode(ctx, format_)
+            if mode == OutputMode.JSON:
+                dump_task_json(log)
+            elif mode == OutputMode.TEXT:
+                print_task_logs_plain(lines)
+            else:
+                console.print(Panel("\n".join(lines), title="Task logs"))
+            return
+
+        printed = 0
+        while True:
+            status = client.get_task_status(task_id)
+            log = client.get_task_log(task_id)
+            lines = log.lines
+            for line in lines[printed:]:
+                click.echo(line)
+            printed = len(lines)
+            if _state_value(status.state) in _TERMINAL_STATE_VALUES:
+                break
+            time.sleep(POLL_INTERVAL)

anabrid/cloud/cli/commands/task/result.py

@@ -0,0 +1,64 @@
+"""``analogcli task result`` — fetch a task's result payload (compile bytes or run JSON)."""
+
+import json
+import sys
+
+import click
+
+from ...context import get_client
+from ...utils import handle_api_error
+
+__all__ = ["task_result", "get_client"]
+
+
+def _to_jsonable(payload: object) -> object:
+    """Return a JSON-serialisable representation of *payload*.
+
+    Pydantic models are dumped via ``model_dump(mode="json")``; everything
+    else is returned unchanged so ``json.dumps(..., default=str)`` can
+    handle leaf types.
+    """
+    if hasattr(payload, "model_dump"):
+        return payload.model_dump(mode="json")
+    return payload
+
+
+@click.command()
+@click.argument("task_id")
+@click.option(
+    "-o",
+    "--output",
+    "output",
+    type=click.Path(dir_okay=False, writable=True),
+    default=None,
+    help="Write the result to FILE instead of stdout.",
+)
+@click.pass_context
+@handle_api_error
+def task_result(ctx: click.Context, task_id: str, output: str | None) -> None:
+    """Fetch the result payload for *task_id*.
+
+    Compile tasks return a binary protobuf blob; run tasks return a JSON
+    document. The discrimination is driven by the wire-level content-type
+    returned from ``client.get_task_result``.
+
+    When ``-o FILE`` is given the payload is written to that path; otherwise
+    it is written to stdout (binary for compile, JSON for run).
+    """
+    with get_client(ctx) as client:
+        payload = client.get_task_result(task_id)
+
+        if isinstance(payload, bytes):
+            if output is not None:
+                with open(output, "wb") as f:
+                    f.write(payload)
+            else:
+                sys.stdout.buffer.write(payload)
+            return
+
+        jsonable = _to_jsonable(payload)
+        if output is not None:
+            with open(output, "w") as f:
+                json.dump(jsonable, f, indent=2, default=str)
+        else:
+            click.echo(json.dumps(jsonable, indent=2, default=str))

anabrid/cloud/cli/commands/task/revoke.py

@@ -0,0 +1,23 @@
+"""``analogcli task revoke`` — request cancellation of a queued/running task."""
+
+import click
+
+from ...context import get_client
+from ...utils import handle_api_error
+
+__all__ = ["task_revoke", "get_client"]
+
+
+@click.command()
+@click.argument("task_id")
+@click.pass_context
+@handle_api_error
+def task_revoke(ctx: click.Context, task_id: str) -> None:
+    """Request cancellation of *task_id*.
+
+    Wire-level endpoint is unchanged (``POST /tasks/{id}/cancel``).
+    Stdout stays empty on success; a 409 state conflict is mapped to
+    exit code 4 by the ``handle_api_error`` decorator.
+    """
+    with get_client(ctx) as client:
+        client.cancel_task(task_id)