analogcli 0.1.4__py3-none-any.whl

anabrid/cloud/cli/client.py

@@ -0,0 +1,385 @@
+"""HTTP client for the Analog Cloud v1 API."""
+
+import base64
+import json
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+import httpx
+
+from anabrid.cloud.models.api.v1 import (
+    CompileTaskDetailResponse,
+    DeviceResponse,
+    RunTaskDetailResponse,
+    SystemStatusResponse,
+    TaskCreatedResponse,
+    TaskLogResponse,
+    TaskSearchResponse,
+    TaskStatusResponse,
+    TaskSummaryResponse,
+    UserInfoResponse,
+)
+from anabrid.cloud.models.enums import DeviceTypeEnum, TaskStateEnum
+
+
+class AnalogCloudAPIError(Exception):
+    """Raised when the Analog Cloud API returns an error or the request fails."""
+
+
+class StateConflictError(AnalogCloudAPIError):
+    """HTTP 409 — the requested operation is incompatible with the task's
+    current state.
+
+    Raised when the server refuses an action because the target task is
+    not in a state from which the action is allowed. The CLI maps this
+    to exit code 4 so shell scripts can distinguish "you asked for
+    something the task can no longer do" from a generic transport
+    failure (exit 3).
+
+    Current 409 sites on the server:
+
+    - ``POST /tasks/{id}/cancel`` — the task is not ``QUEUED``. Cancel
+      only withdraws queued work; once the worker has picked the task up
+      (``INPROGRESS``) or it has reached a terminal state
+      (``SUCCEEDED``/``FAILED``/``CANCELLED``), the cancel request is
+      refused.
+    - ``DELETE /tasks/{id}`` — the task is ``INPROGRESS`` and its latest
+      ``INPROGRESS`` transition is less than 2 minutes old. The grace
+      window protects an in-flight worker run from having its row
+      yanked out from under it.
+    """
+
+
+TERMINAL_TASK_STATES: frozenset = frozenset(
+    {TaskStateEnum.SUCCEEDED, TaskStateEnum.FAILED, TaskStateEnum.CANCELLED}
+)
+
+
+class AnalogCloudClient:
+    """Synchronous HTTP client for the Analog Cloud v1 API."""
+
+    def __init__(
+        self,
+        base_url: str = "https://redac.anabrid.com",
+        timeout: float = 30.0,
+        api_key: str = None,
+    ):
+        """Initialise client.
+
+        Parameters
+        ----------
+        base_url:
+            Base URL of the Analog Cloud server.
+        timeout:
+            Per-request timeout in seconds.
+        api_key:
+            Bearer token.  Required; raises ``ValueError`` when absent.
+        """
+        if not api_key:
+            raise ValueError(
+                "API key is required. "
+                "Please set the ANALOGCLOUD_API_KEY environment variable."
+            )
+
+        self.base_url = base_url
+        self.timeout = timeout
+        self.api_key = api_key
+        self.client = httpx.Client(
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+    def __enter__(self) -> "AnalogCloudClient":
+        """Support use as a context manager."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Close the underlying HTTP client on context-manager exit."""
+        self.client.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self.client.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _make_request(self, method: str, endpoint: str, **kwargs) -> httpx.Response:
+        """Execute an HTTP request and raise ``AnalogCloudAPIError`` on failure."""
+        url = f"{self.base_url}{endpoint}"
+        try:
+            response = self.client.request(method, url, **kwargs)
+            response.raise_for_status()
+            return response
+        except httpx.HTTPStatusError as exc:
+            try:
+                detail = exc.response.json().get("detail", str(exc))
+            except Exception:
+                detail = str(exc)
+            if exc.response.status_code == 409:
+                raise StateConflictError(f"API Error: {detail}") from exc
+            raise AnalogCloudAPIError(f"API Error: {detail}") from exc
+        except httpx.RequestError as exc:
+            raise AnalogCloudAPIError(f"Connection Error: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # System
+    # ------------------------------------------------------------------
+
+    def get_system_status(self) -> SystemStatusResponse:
+        """Return current system status (version, domain, uptime)."""
+        response = self._make_request("GET", "/api/v1/system/status")
+        return SystemStatusResponse(**response.json())
+
+    # ------------------------------------------------------------------
+    # Users
+    # ------------------------------------------------------------------
+
+    def get_user_info(self) -> UserInfoResponse:
+        """Return profile and rate-limit quota for the authenticated user."""
+        response = self._make_request("GET", "/api/v1/users/me")
+        return UserInfoResponse(**response.json())
+
+    # ------------------------------------------------------------------
+    # Devices
+    # ------------------------------------------------------------------
+
+    def get_devices(self) -> list[DeviceResponse]:
+        """Return all registered devices with their current queue lengths."""
+        response = self._make_request("GET", "/api/v1/devices")
+        return [DeviceResponse(**d) for d in response.json()]
+
+    def get_device_entity(self, device_name: str) -> bytes:
+        """Return the raw protobuf entity blob for *device_name*.
+
+        Raises ``AnalogCloudAPIError`` when the device is unknown or has no entity.
+        """
+        response = self._make_request("GET", f"/api/v1/devices/{device_name}/entity")
+        return response.content
+
+    # ------------------------------------------------------------------
+    # Tasks — submission
+    # ------------------------------------------------------------------
+
+    def submit_compile_task(
+        self,
+        ode_source: str,
+        backend: DeviceTypeEnum,
+        module: bytes,
+        *,
+        k0: int | None = None,
+    ) -> UUID:
+        """Submit a compile task and return its UUID.
+
+        Parameters
+        ----------
+        ode_source:
+            Raw ODE source text (analang format).
+        backend:
+            Target device type (must not be SIMULATOR).
+        module:
+            Protobuf entity blob for the target device.  Base64-encoded on
+            the wire.
+        k0:
+            Optional time-scale factor override.
+        """
+        payload = {
+            "ode_source": ode_source,
+            "backend": backend.value,
+            "module": base64.b64encode(module).decode("ascii"),
+            "k0": k0,
+        }
+        response = self._make_request("POST", "/api/v1/tasks/compile", json=payload)
+        return TaskCreatedResponse(**response.json()).id
+
+    def submit_run_task(
+        self,
+        device_name: str,
+        module: bytes,
+        *,
+        sample_rate: int = 10000,
+        op_time: float = 0.1,
+    ) -> UUID:
+        """Submit a run task and return its UUID.
+
+        Parameters
+        ----------
+        device_name:
+            Name of the registered device to run on.
+        module:
+            Compiled protobuf configuration blob.  Base64-encoded on the wire.
+        sample_rate:
+            ADC samples drawn per second.
+        op_time:
+            Wall-clock integration time in seconds.
+        """
+        payload = {
+            "device_name": device_name,
+            "module": base64.b64encode(module).decode("ascii"),
+            "sample_rate": sample_rate,
+            "op_time": op_time,
+        }
+        response = self._make_request("POST", "/api/v1/tasks/run", json=payload)
+        return TaskCreatedResponse(**response.json()).id
+
+    # ------------------------------------------------------------------
+    # Tasks — polling and status
+    # ------------------------------------------------------------------
+
+    def list_tasks(
+        self,
+        state: str | None = None,
+        type: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> list[TaskSummaryResponse]:
+        """List tasks visible to the current API key.
+
+        Query parameters with ``None`` values are omitted from the request.
+        """
+        params: dict[str, Any] = {}
+        if state is not None:
+            params["state"] = state
+        if type is not None:
+            params["type"] = type
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        response = self._make_request("GET", "/api/v1/tasks", params=params)
+        return [TaskSummaryResponse(**item) for item in response.json()]
+
+    def search_tasks(
+        self,
+        *,
+        user_id: list[str] | None = None,
+        device_name: list[str] | None = None,
+        device_class: list[str] | None = None,
+        type: list[str] | None = None,
+        state: list[str] | None = None,
+        from_: str | None = None,
+        to: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> TaskSearchResponse:
+        """Search tasks via ``POST /api/v1/tasks/search`` and return one page.
+
+        List-valued filters left ``None`` are omitted from the body; ``from_``
+        is sent under the reserved-word alias ``from``. The caller's privilege
+        (system vs. non-system) is resolved server-side; this method forwards a
+        single page and the pagination loop lives in the command layer.
+        """
+        body: dict = {"limit": limit, "offset": offset}
+        if user_id is not None:
+            body["user_id"] = user_id
+        if device_name is not None:
+            body["device_name"] = device_name
+        if device_class is not None:
+            body["device_class"] = device_class
+        if type is not None:
+            body["type"] = type
+        if state is not None:
+            body["state"] = state
+        if from_ is not None:
+            body["from"] = from_
+        if to is not None:
+            body["to"] = to
+        response = self._make_request("POST", "/api/v1/tasks/search", json=body)
+        return TaskSearchResponse(**response.json())
+
+    def get_task_status(self, task_id: str | UUID) -> TaskStatusResponse:
+        """Return the current state and full state history for *task_id*."""
+        response = self._make_request("GET", f"/api/v1/tasks/{task_id}/status")
+        return TaskStatusResponse(**response.json())
+
+    def get_task_log(self, task_id: str | UUID) -> TaskLogResponse:
+        """Return the log lines for *task_id*."""
+        response = self._make_request("GET", f"/api/v1/tasks/{task_id}/log")
+        return TaskLogResponse(**response.json())
+
+    def get_task_detail(
+        self, task_id: str | UUID
+    ) -> CompileTaskDetailResponse | RunTaskDetailResponse:
+        """Return the full task detail, discriminated by ``type`` field.
+
+        Raises ``AnalogCloudAPIError`` when the ``type`` field is not recognised.
+        """
+        response = self._make_request("GET", f"/api/v1/tasks/{task_id}")
+        data = response.json()
+        task_type = data.get("type")
+        if task_type == "compile":
+            return CompileTaskDetailResponse(**data)
+        if task_type == "run":
+            return RunTaskDetailResponse(**data)
+        raise AnalogCloudAPIError(f"unexpected task type: {task_type!r}")
+
+    def get_task_result(self, task_id: str | UUID) -> bytes | Any:
+        """Return the task result.
+
+        Compile tasks return raw ``bytes`` (protobuf blob).
+        Run tasks return the JSON-deserialised Python value.
+
+        Raises ``AnalogCloudAPIError`` for unrecognised content types or malformed
+        JSON bodies.
+        """
+        response = self._make_request("GET", f"/api/v1/tasks/{task_id}/result")
+        content_type = response.headers.get("content-type", "")
+        if content_type.startswith("application/octet-stream"):
+            return response.content
+        if content_type.startswith("application/json"):
+            try:
+                return response.json()
+            except ValueError as exc:
+                raise AnalogCloudAPIError(f"invalid JSON in result body: {exc}") from exc
+        raise AnalogCloudAPIError(f"unexpected result content-type: {content_type!r}")
+
+    def cancel_task(self, task_id: str | UUID) -> TaskStatusResponse:
+        """Request cancellation of a queued task.
+
+        Returns the updated ``TaskStatusResponse``.
+        """
+        response = self._make_request("POST", f"/api/v1/tasks/{task_id}/cancel")
+        return TaskStatusResponse(**response.json())
+
+    def delete_task(self, task_id: str | UUID) -> None:
+        """Permanently delete a task and its blobs.
+
+        Expects HTTP 204; raises ``AnalogCloudAPIError`` on failure.
+        """
+        self._make_request("DELETE", f"/api/v1/tasks/{task_id}")
+
+    def wait_for_task_completion(
+        self, task_id: str | UUID, poll_interval: float = 1.0
+    ) -> TaskStatusResponse:
+        """Poll *task_id* until it reaches a terminal state and return it.
+
+        Terminal states: SUCCEEDED, FAILED, CANCELLED.
+        """
+        import time
+
+        while True:
+            status = self.get_task_status(task_id)
+            if status.state in TERMINAL_TASK_STATES:
+                return status
+            time.sleep(poll_interval)
+
+
+def load_json_file(file_path: str) -> dict:
+    """Load and parse a JSON file.
+
+    Raises ``FileNotFoundError`` when the path does not exist,
+    ``ValueError`` when the content is not valid JSON.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    try:
+        with open(path, "r") as f:
+            return json.load(f)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in file {file_path}: {exc}") from exc
+    except Exception as exc:
+        raise RuntimeError(f"Error reading file {file_path}: {exc}") from exc

anabrid/cloud/cli/commands/compile.py

@@ -0,0 +1,164 @@
+"""CLI command for compiling ODE sources to device configurations."""
+
+from pathlib import Path
+
+import click
+from ..context import get_client
+from ..utils import (
+    handle_api_error,
+    load_binary_file,
+    wait_for_task_with_progress,
+    display_task_logs,
+    console,
+)
+from anabrid.cloud.models.enums import DeviceTypeEnum, TaskStateEnum
+
+
+@click.command()
+@click.argument("ode_file", type=click.Path(exists=True))
+@click.argument("module_file", type=click.Path(exists=True), required=False)
+@click.option(
+    "--device",
+    "device_name",
+    default=None,
+    help=(
+        "Device name to compile for. When given, the CLI fetches the device's "
+        "entity blob and derives the backend automatically; MODULE_FILE and "
+        "--backend must be omitted."
+    ),
+)
+@click.option(
+    "--backend",
+    type=click.Choice(
+        [t.value for t in DeviceTypeEnum if t != DeviceTypeEnum.SIMULATOR]
+    ),
+    default=None,
+    help=(
+        f"Target device type for compilation "
+        f"(default: {DeviceTypeEnum.LUCIDAC.value} when MODULE_FILE is given)."
+    ),
+)
+@click.option(
+    "--k0",
+    default=None,
+    type=int,
+    help="Time-scale factor override",
+)
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    help="Save compiled module bytes 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 compile(
+    ctx: click.Context,
+    ode_file: str,
+    module_file: str | None,
+    device_name: str | None,
+    backend: str | None,
+    k0: int | None,
+    output: str | None,
+    follow: bool,
+):
+    """Compile an ODE source file to a device configuration module.
+
+    ODE_FILE is a text file containing the ODE in analang format.
+
+    There are two ways to select the target:
+
+    \b
+    1. Explicit: pass MODULE_FILE (obtained via
+       ``analogcli info <device> --save-entity``) and optionally --backend.
+    2. By device: pass --device <name> to let the CLI fetch the entity blob
+       and pick the backend automatically.
+
+    The compiled module bytes are printed to stdout or saved with --output.
+
+    Examples:
+
+    \b
+        analogcli compile my_ode.txt device.entity --backend LUCIDAC
+        analogcli compile my_ode.txt --device lucidac-01
+    """
+    if device_name and module_file:
+        raise click.UsageError(
+            "MODULE_FILE and --device are mutually exclusive; pass exactly one."
+        )
+    if device_name and backend:
+        raise click.UsageError(
+            "--backend is derived from --device; do not pass both."
+        )
+    if not device_name and not module_file:
+        raise click.UsageError(
+            "Either MODULE_FILE or --device must be provided."
+        )
+
+    ode_source = Path(ode_file).read_text()
+
+    with get_client(ctx) as client:
+        if device_name:
+            devices = client.get_devices()
+            device = next((d for d in devices if d.name == device_name), None)
+            if device is None:
+                console.print(f"[red]Device '{device_name}' not found[/red]")
+                raise click.Abort()
+            if device.type == DeviceTypeEnum.SIMULATOR:
+                console.print(
+                    f"[red]Device '{device_name}' is a SIMULATOR; "
+                    "compile requires a hardware backend.[/red]"
+                )
+                raise click.Abort()
+            backend_enum = device.type
+            module_bytes = client.get_device_entity(device_name)
+        else:
+            backend_enum = DeviceTypeEnum(backend or DeviceTypeEnum.LUCIDAC.value)
+            module_bytes = load_binary_file(module_file)
+
+        if follow:
+            console.print("[blue]Submitting compile task...[/blue]")
+        task_id = client.submit_compile_task(
+            ode_source=ode_source,
+            backend=backend_enum,
+            module=module_bytes,
+            k0=k0,
+        )
+
+        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, "Compiling ODE")
+
+        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]Compilation completed successfully![/bold green]"
+            )
+
+            result_bytes = client.get_task_result(task_id)
+
+            if output:
+                with open(output, "wb") as f:
+                    f.write(result_bytes)
+                console.print(f"[green]Compiled module saved to {output}[/green]")
+            else:
+                console.print(
+                    f"[green]Compiled module: {len(result_bytes)} bytes "
+                    "(use --output to save)[/green]"
+                )
+        else:
+            error = final_status.error or "(no detail)"
+            console.print(f"\n[bold red]Compilation failed: {error}[/bold red]")

anabrid/cloud/cli/commands/info.py

@@ -0,0 +1,97 @@
+"""CLI command for displaying device information."""
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from ..context import get_client
+from ..utils import handle_api_error
+
+console = Console()
+
+# Device type whose entity is ``null`` per spec: skip entity fetch and tree.
+_SIMULATOR_TYPE = "SIMULATOR"
+
+
+@click.command()
+@click.argument("device_name")
+@click.option(
+    "--short",
+    is_flag=True,
+    default=False,
+    help="Suppress the entity tree and print only the summary table.",
+)
+@click.option(
+    "--save-entity",
+    default=None,
+    metavar="PATH",
+    help="Save the raw entity blob to PATH.",
+)
+@click.pass_context
+@handle_api_error
+def info(ctx: click.Context, device_name: str, short: bool, save_entity: str | None):
+    """Show information about a registered device.
+
+    DEVICE_NAME is the name of the device as registered in the hub.
+
+    By default, the summary table is followed by the pybrid entity tree.
+    Pass ``--short`` to suppress the tree. SIMULATOR devices always show
+    only the table (their entity is null).
+
+    With ``--save-entity PATH``, the raw protobuf entity bytes are written
+    to PATH.
+    """
+    with get_client(ctx) as client:
+        devices = client.get_devices()
+        device = next((d for d in devices if d.name == device_name), None)
+
+        if device is None:
+            console.print(f"[red]Device '{device_name}' not found[/red]")
+            raise click.Abort()
+
+        info_table = Table(
+            title=f"Device Information: {device_name}", show_header=False
+        )
+        info_table.add_column("Property", style="cyan")
+        info_table.add_column("Value", style="white")
+
+        info_table.add_row("Name", device.name)
+        info_table.add_row("Type", device.type.value)
+
+        availability_text = (
+            "[green]Available[/green]" if device.available else "[red]Unavailable[/red]"
+        )
+        info_table.add_row("Status", availability_text)
+        info_table.add_row("Queue Length", str(device.queue_length))
+
+        console.print(info_table)
+
+        device_type = device.type.value
+        is_simulator = device_type == _SIMULATOR_TYPE
+
+        # SIMULATOR entity is null: skip both the entity fetch and the tree.
+        if is_simulator:
+            return
+
+        # Only fetch the entity blob when something actually needs it.
+        need_entity = bool(save_entity) or not short
+        if not need_entity:
+            return
+
+        try:
+            entity_bytes = client.get_device_entity(device_name)
+
+            if save_entity:
+                with open(save_entity, "wb") as f:
+                    f.write(entity_bytes)
+                console.print(f"[green]Entity saved to {save_entity}[/green]")
+
+            if not short:
+                from ..entity_tree import render_entity_tree
+
+                tree = render_entity_tree(entity_bytes, device_type)
+                console.print()
+                console.print(tree)
+
+        except Exception as exc:
+            console.print(f"[yellow]Entity configuration not available: {exc}[/yellow]")