analogcli 0.1.4__py3-none-any.whl

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

@@ -0,0 +1,238 @@
+"""``analogcli task search`` — cross-user task search, report table + CSV export."""
+
+import json
+from datetime import datetime, timedelta, timezone
+
+import click
+
+from ...context import get_client
+from ...utils import (
+    OutputMode,
+    handle_api_error,
+    pick_output_mode,
+    print_search_table,
+    write_task_csv,
+)
+
+# Column sets for the report table and CSV export.
+THIN_COLUMNS = ["id", "user_id", "type", "state", "created_at", "error"]
+RICH_COLUMNS = THIN_COLUMNS + [
+    "device_name",
+    "backend",
+    "sample_rate",
+    "op_time",
+    "k0",
+    "has_result",
+    "has_log",
+]
+
+# Per-request page size when gathering all matches across pages.
+PAGE_SIZE = 1000
+
+
+@click.command()
+@click.option("--user-id", "user_id", multiple=True,
+              help="Filter by owning api_key (honoured only for system keys). Repeatable.")
+@click.option("--me", is_flag=True, default=False,
+              help="Shortcut for --user-id $ANALOGCLOUD_API_KEY (your own jobs). "
+                   "Combines with any --user-id values given.")
+@click.option("--device", "device_name", multiple=True,
+              help="Filter by device name (matches run jobs). Repeatable.")
+@click.option("--device-class", "device_class", multiple=True,
+              help="Filter by device class: LUCIDAC, REDAC or SIMULATOR. Repeatable.")
+@click.option("--type", "task_type", multiple=True,
+              help="Filter by task type: compile or run. Repeatable.")
+@click.option("--state", multiple=True,
+              help="Filter by latest state, e.g. QUEUED, INPROGRESS, SUCCEEDED. Repeatable.")
+@click.option("--from", "from_", default=None,
+              help="Window start as an ISO 8601 datetime, e.g. 2026-05-01T00:00:00 "
+                   "(default: 24h before --to). Mutually exclusive with --last-*.")
+@click.option("--to", "to", default=None,
+              help="Window end as an ISO 8601 datetime, e.g. 2026-05-08T00:00:00 "
+                   "(default: now). Window capped at 90 days. Mutually exclusive with --last-*.")
+@click.option("--last-h", "last_h", default=None, type=int,
+              help="Show the last N hours (window = now-Nh .. now). "
+                   "Excludes --from/--to and the other --last-* options.")
+@click.option("--last-d", "last_d", default=None, type=int,
+              help="Show the last N days. Excludes --from/--to and the other --last-* options.")
+@click.option("--last-m", "last_m", default=None, type=int,
+              help="Show the last N minutes. Excludes --from/--to and the other --last-* options.")
+@click.option("--limit", default=None, type=int,
+              help="Cap the total number of jobs returned (default: all matches).")
+@click.option("--recursive", is_flag=True, default=False,
+              help="Enrich each job with full detail (device/backend/...) via per-job lookups.")
+@click.option("--csv", "csv_path", default=None, type=click.Path(dir_okay=False, writable=True),
+              help="Also write the result set to this path as CSV.")
+@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_search(
+    ctx: click.Context,
+    user_id: tuple[str, ...],
+    me: bool,
+    device_name: tuple[str, ...],
+    device_class: tuple[str, ...],
+    task_type: tuple[str, ...],
+    state: tuple[str, ...],
+    from_: str | None,
+    to: str | None,
+    last_h: int | None,
+    last_d: int | None,
+    last_m: int | None,
+    limit: int | None,
+    recursive: bool,
+    csv_path: str | None,
+    ids_only: bool,
+    format_: str | None,
+) -> None:
+    """Search tasks and render a report table, optionally exporting CSV.
+
+    System keys search across all users (and may filter by ``--user-id``);
+    non-system keys are scoped to their own tasks. All matches are gathered
+    across pages up to ``--limit``.
+
+    \b
+    Time window — pick ONE style:
+      * --from / --to with ISO 8601 datetimes (e.g. 2026-05-01T00:00:00).
+        A bare datetime is read as UTC; a value with an offset is converted.
+      * --last-h / --last-d / --last-m for a window ending "now". These are
+        mutually exclusive with --from/--to and with each other.
+
+    \b
+    Examples:
+      # explicit ISO 8601 window (one week)
+      analogcli task search --from 2026-05-01T00:00:00 --to 2026-05-08T00:00:00
+      # from a fixed start up to the current moment; generate the ISO
+      # timestamp for "now" with the Linux `date` command:
+      analogcli task search --from 2026-05-01T00:00:00 --to "$(date -u +%Y-%m-%dT%H:%M:%S)"
+      # the last 6 hours / 7 days / 90 minutes
+      analogcli task search --last-h 6
+      analogcli task search --last-d 7
+      analogcli task search --last-m 90
+      # multiple owners (system key) — repeat the flag
+      analogcli task search --user-id alice-key --user-id bob-key
+      # just your own jobs (handy for a system key, which sees everyone by default)
+      analogcli task search --me
+    """
+    # Resolve the time window: --last-* is a convenience over --from/--to and
+    # may not be mixed with them or with each other.
+    last_opts = {"--last-h": last_h, "--last-d": last_d, "--last-m": last_m}
+    given_last = {name: val for name, val in last_opts.items() if val is not None}
+    if len(given_last) > 1:
+        raise click.UsageError(
+            "Only one of --last-h / --last-d / --last-m may be used at a time."
+        )
+    if given_last and (from_ is not None or to is not None):
+        raise click.UsageError(
+            "--last-h / --last-d / --last-m cannot be combined with --from / --to."
+        )
+    if given_last:
+        deltas = {
+            "--last-h": timedelta(hours=last_h or 0),
+            "--last-d": timedelta(days=last_d or 0),
+            "--last-m": timedelta(minutes=last_m or 0),
+        }
+        (name,) = given_last
+        if given_last[name] < 0:
+            raise click.UsageError(f"{name} must not be negative.")
+        now = datetime.now(timezone.utc)
+        to = now.isoformat()
+        from_ = (now - deltas[name]).isoformat()
+
+    _to_list = lambda t: list(t) if t else None  # noqa: E731
+
+    uid_filter = _to_list(user_id)
+    dev_filter = _to_list(device_name)
+    cls_filter = _to_list(device_class)
+    type_filter = _to_list(task_type)
+    state_filter = _to_list(state)
+
+    columns = RICH_COLUMNS if recursive else THIN_COLUMNS
+
+    collected = []
+    offset = 0
+
+    with get_client(ctx) as client:
+        # --me folds the caller's own api_key into the user_id filter (deduped,
+        # order-preserving). For a non-system key the server force-scopes to
+        # the caller anyway, so this is a no-op there; it matters for a system
+        # key that would otherwise see every user's jobs.
+        if me:
+            uid_filter = list(dict.fromkeys((uid_filter or []) + [client.api_key]))
+
+        # Pagination loop — gather all matching pages up to limit.
+        while True:
+            remaining = None if limit is None else limit - len(collected)
+            if remaining is not None and remaining <= 0:
+                break
+            req_limit = PAGE_SIZE if remaining is None else min(PAGE_SIZE, remaining)
+            resp = client.search_tasks(
+                user_id=uid_filter,
+                device_name=dev_filter,
+                device_class=cls_filter,
+                type=type_filter,
+                state=state_filter,
+                from_=from_,
+                to=to,
+                limit=req_limit,
+                offset=offset,
+            )
+            collected.extend(resp.items)
+            if resp.next_offset is None:
+                break
+            offset = resp.next_offset
+
+        if limit is not None:
+            collected = collected[:limit]
+
+        # Optionally enrich each item with per-job detail.
+        details = {}
+        if recursive:
+            for item in collected:
+                details[item.id] = client.get_task_detail(str(item.id))
+
+    # Build flat row dicts.
+    def _attr_val(obj, name: str) -> str:
+        """Return a string rendering of *name* on *obj*; None or missing → ''."""
+        val = getattr(obj, name, None)
+        if val is None:
+            return ""
+        if hasattr(val, "value"):
+            return str(val.value)
+        return str(val)
+
+    rows = []
+    for item in collected:
+        row = {
+            "id": str(item.id),
+            "user_id": item.user_id,
+            "type": item.type.value,
+            "state": item.state.value,
+            "created_at": item.created_at.isoformat(),
+            "error": item.error or "",
+        }
+        if recursive:
+            detail = details.get(item.id)
+            for col in ["device_name", "backend", "sample_rate", "op_time", "k0", "has_result", "has_log"]:
+                row[col] = _attr_val(detail, col) if detail is not None else ""
+        rows.append(row)
+
+    # --ids-only overrides --format.
+    if ids_only:
+        for item in collected:
+            click.echo(str(item.id))
+        if csv_path is not None:
+            write_task_csv(rows, csv_path, columns)
+        return
+
+    mode = pick_output_mode(ctx, format_, follow=False)
+    if mode == OutputMode.JSON:
+        click.echo(json.dumps(rows, indent=2, default=str))
+    else:
+        print_search_table(rows, columns)
+
+    if csv_path is not None:
+        write_task_csv(rows, csv_path, columns)

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

@@ -0,0 +1,54 @@
+"""``analogcli task status`` — current state of a single task."""
+
+import click
+from rich.table import Table
+
+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_status(ctx: click.Context, task_id: str, format_: str | None) -> None:
+    """Show the current state and state history of a single task."""
+    with get_client(ctx) as client:
+        status_obj = client.get_task_status(task_id)
+
+    mode = pick_output_mode(ctx, format_, follow=False)
+    if mode == OutputMode.JSON:
+        dump_task_json(status_obj)
+        return
+
+    state_val = status_obj.state
+    state_str = state_val.value if hasattr(state_val, "value") else str(state_val)
+    console.print(f"[cyan]ID:[/cyan] {status_obj.id}")
+    console.print(f"[cyan]State:[/cyan] {state_str}")
+    if status_obj.error:
+        console.print(f"[red]Error:[/red] {status_obj.error}")
+
+    table = Table(title="State history")
+    table.add_column("Timestamp", style="white")
+    table.add_column("State", style="green")
+    for entry in status_obj.state_history:
+        entry_state = entry.state
+        entry_state_str = (
+            entry_state.value if hasattr(entry_state, "value") else str(entry_state)
+        )
+        table.add_row(format_timestamp(entry.timestamp), entry_state_str)
+    console.print(table)

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

@@ -0,0 +1,67 @@
+"""``analogcli task wait`` — poll a task until terminal; exit code encodes the state."""
+
+import sys
+import time
+
+import click
+
+from ...context import get_client
+from ...utils import handle_api_error
+
+__all__ = ["task_wait", "get_client", "time", "_now"]
+
+
+def _now() -> float:
+    """Return a monotonic timestamp in seconds for elapsed-time computation.
+
+    Wrapped in a helper so tests can patch a single, named symbol on this
+    module rather than monkey-patching ``time.monotonic`` globally.
+    """
+    return time.monotonic()
+
+
+@click.command()
+@click.argument("task_id")
+@click.option(
+    "--poll-interval",
+    "poll_interval",
+    type=float,
+    default=1.0,
+    show_default=True,
+    help="Seconds between status polls.",
+)
+@click.option(
+    "--timeout",
+    "timeout",
+    type=float,
+    default=None,
+    help="Abort polling after this many seconds and exit 124.",
+)
+@click.pass_context
+@handle_api_error
+def task_wait(
+    ctx: click.Context,
+    task_id: str,
+    poll_interval: float,
+    timeout: float | None,
+) -> None:
+    """Wait until *task_id* reaches a terminal state.
+
+    Stdout stays empty; the terminal state is carried by the exit code:
+    0 = SUCCEEDED, 1 = FAILED, 2 = CANCELLED, 124 = timeout.
+    """
+    start = _now()
+    with get_client(ctx) as client:
+        while True:
+            status = client.get_task_status(task_id)
+            raw_state = getattr(status.state, "value", status.state)
+            state = str(raw_state).lower()
+            if state == "succeeded":
+                sys.exit(0)
+            if state == "failed":
+                sys.exit(1)
+            if state == "cancelled":
+                sys.exit(2)
+            if timeout is not None and (_now() - start) >= timeout:
+                sys.exit(124)
+            time.sleep(poll_interval)

anabrid/cloud/cli/context.py

@@ -0,0 +1,18 @@
+import os
+import click
+from .client import AnalogCloudClient
+
+
+def get_client(ctx: click.Context) -> AnalogCloudClient:
+    """Create and return an Analog Cloud client with context configuration."""
+    config = ctx.obj["client_config"]
+
+    # Read API key from environment
+    api_key = os.environ.get("ANALOGCLOUD_API_KEY")
+    if not api_key:
+        raise click.ClickException(
+            "ANALOGCLOUD_API_KEY environment variable is not set. "
+            "Please set it to your Analog Cloud API key."
+        )
+
+    return AnalogCloudClient(**config, api_key=api_key)

anabrid/cloud/cli/entity_tree.py

@@ -0,0 +1,110 @@
+"""Entity-blob -> pybrid ``Computer`` construction and ASCII-tree rendering.
+
+The helpers in this module let the CLI render a device's entity tree without
+a live hardware connection. The entity blob is the raw ``pb.Module`` bytes
+returned by the server's ``/api/v1/devices/{name}/entity`` endpoint.
+
+Pybrid is imported lazily inside each function so callers that do not need
+tree rendering (e.g. ``analogcli info --short``) don't pay the pybrid import
+cost.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pybrid.redac.computer import REDAC as Computer
+
+
+_SUPPORTED_DEVICE_TYPES = frozenset({"LUCIDAC", "REDAC"})
+
+
+def build_computer_from_entity(entity_bytes: bytes, device_type: str) -> "Computer":
+    """Deserialize an entity blob into a populated pybrid ``Computer``.
+
+    The server stores the entity as a ``pb.File`` envelope wrapping the
+    raw ``pb.Module`` (see ``devices._fetch_entity``); this helper parses
+    the envelope, takes ``.module``, instantiates a ``LUCIDACController``
+    or ``REDACController`` based on *device_type*, walks the module's
+    entity-specification items through a ``LUCIDACDeserializer``, and
+    attaches the resulting carriers to the controller's ``.computer``.
+    No network or hardware access is performed.
+
+    Args:
+        entity_bytes: Raw serialized ``pb.File`` bytes (as returned by
+            the server's device-entity endpoint).
+        device_type: ``"LUCIDAC"`` or ``"REDAC"`` - drives the
+            controller-class selection.
+
+    Returns:
+        A pybrid ``Computer`` (``LUCIDAC`` or ``REDAC`` subclass) with
+        carriers populated from the entity blob.
+
+    Raises:
+        ValueError: If *device_type* is not a recognised physical-device
+            type (e.g. ``"SIMULATOR"``) or if *entity_bytes* cannot be
+            parsed as a ``pb.File``.
+    """
+    if device_type not in _SUPPORTED_DEVICE_TYPES:
+        raise ValueError(
+            f"Unsupported device_type {device_type!r}; "
+            f"expected one of {sorted(_SUPPORTED_DEVICE_TYPES)}"
+        )
+
+    import pybrid.base.proto.main_pb2 as pb
+    from pybrid.lucidac.controller import Controller as LUCIDACController
+    from pybrid.lucidac.protocol.serializer import LUCIDACDeserializer
+    from pybrid.redac.controller import Controller as REDACController
+    from pybrid.redac.device import Device
+    from pybrid.redac.entities import Path
+
+    file_msg = pb.File()
+    try:
+        file_msg.ParseFromString(entity_bytes)
+    except Exception as exc:
+        raise ValueError(f"entity_bytes is not a valid pb.File: {exc}") from exc
+    module = file_msg.module
+
+    controller_cls = LUCIDACController if device_type == "LUCIDAC" else REDACController
+    controller = controller_cls()
+
+    deserializer = LUCIDACDeserializer()
+    for item in module.items:
+        if not item.HasField("entity_specification"):
+            continue
+        entity = item.entity_specification.entity
+        try:
+            root_path = Path.parse(entity.id.strip("/"))
+        except Exception:
+            root_path = Path.make()
+
+        result = deserializer.deserialize_specification(entity, root_path)
+        carriers = result.carriers if isinstance(result, Device) else [result]
+        for carrier in carriers:
+            controller.computer.add_carrier(carrier)
+
+    return controller.computer
+
+
+def render_entity_tree(entity_bytes: bytes, device_type: str) -> str:
+    """Return the pybrid ``TreeDisplay`` rendering of an entity blob.
+
+    Equivalent to building a ``Computer`` via :func:`build_computer_from_entity`
+    and running ``TreeDisplay.render(computer)``. The return value is the
+    same ASCII tree that ``pybrid display`` prints against a live device.
+
+    Args:
+        entity_bytes: Raw serialized ``pb.Module`` bytes.
+        device_type: ``"LUCIDAC"`` or ``"REDAC"``.
+
+    Returns:
+        A non-empty ASCII tree string.
+
+    Raises:
+        ValueError: Propagated from :func:`build_computer_from_entity`.
+    """
+    from pybrid.redac.display import TreeDisplay
+
+    computer = build_computer_from_entity(entity_bytes, device_type)
+    return TreeDisplay.render(computer)

anabrid/cloud/cli/main.py

@@ -0,0 +1,52 @@
+"""CLI entry point — registers all sub-commands."""
+
+import click
+
+from .commands import compile, info, run, status
+from .commands.task import task
+
+
+@click.group()
+@click.option(
+    "-u",
+    "--base-url",
+    default="https://redac.anabrid.com",
+    help="Hostname of the Analog Cloud API server",
+    show_default=True,
+)
+@click.option(
+    "--timeout",
+    default=30.0,
+    type=float,
+    help="Request timeout in seconds",
+    show_default=True,
+)
+@click.pass_context
+def cli(ctx: click.Context, base_url: str, timeout: float):
+    """Analog Cloud CLI - Command-line interface for the Analog Cloud system.
+
+    This CLI provides access to Analog Cloud's analog computing devices through
+    a REST API interface. You can submit tasks, monitor their progress,
+    and retrieve results.
+
+    Common workflow:
+    1. Check system status: analogcli status
+    2. Compile an ODE: analogcli compile my_ode.txt device.entity
+    3. Run on a device: analogcli run compiled.apb --device lucidac-01
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["client_config"] = {
+        "base_url": base_url,
+        "timeout": timeout,
+    }
+
+
+cli.add_command(status.status)
+cli.add_command(info.info)
+cli.add_command(run.run)
+cli.add_command(compile.compile)
+cli.add_command(task)
+
+
+if __name__ == "__main__":
+    cli()