puda-comms 0.0.2__py3-none-any.whl

puda_comms/models.py

@@ -0,0 +1,88 @@
+"""
+Models for Puda Comms.
+"""
+
+from enum import Enum
+from typing import Optional, Dict, Any
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+
+
+class CommandResponseStatus(str, Enum):
+    """Status of a command response."""
+    SUCCESS = 'success'
+    ERROR = 'error'
+
+
+class CommandResponseCode(str, Enum):
+    """Error codes for command responses."""
+    COMMAND_CANCELLED = 'COMMAND_CANCELLED'
+    JSON_DECODE_ERROR = 'JSON_DECODE_ERROR'
+    EXECUTION_ERROR = 'EXECUTION_ERROR'
+    EXECUTION_LOCKED = 'EXECUTION_LOCKED'
+    UNKNOWN_COMMAND = 'UNKNOWN_COMMAND'
+    PAUSE_ERROR = 'PAUSE_ERROR'
+    RESUME_ERROR = 'RESUME_ERROR'
+    NO_EXECUTION = 'NO_EXECUTION'
+    RUN_ID_MISMATCH = 'RUN_ID_MISMATCH'
+    CANCEL_ERROR = 'CANCEL_ERROR'
+    MACHINE_PAUSED = 'MACHINE_PAUSED'
+
+
+class MessageType(str, Enum):
+    """Type of NATS message."""
+    COMMAND = 'command'
+    RESPONSE = 'response'
+    LOG = 'log'
+    ALERT = 'alert'
+    MEDIA = 'media'
+
+
+class ImmediateCommand(str, Enum):
+    """Command names for immediate commands."""
+    PAUSE = 'pause'
+    RESUME = 'resume'
+    CANCEL = 'cancel'
+
+
+def _get_current_timestamp() -> str:
+    """Get current timestamp in ISO 8601 UTC format."""
+    return datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+
+
+class CommandRequest(BaseModel):
+    """Command request data for NATS messages."""
+    name: str = Field(description="The command name (string) to send to the machine.")
+    params: Dict[str, Any] = Field(default_factory=dict, description="The parameters to send to the machine.")
+    step_number: int = Field(description="Execution step number (integer). Used to track the progress of a command.")
+    version: str = Field(default="1.0", description="Command version.")
+
+
+class CommandResponse(BaseModel):
+    """Result data in a command response."""
+    status: CommandResponseStatus = Field(description="Status of the command response.")
+    completed_at: str = Field(default_factory=_get_current_timestamp, description="ISO format timestamp (auto-set on creation)")
+    code: Optional[CommandResponseCode] = Field(default=None, description="Error code")
+    message: Optional[str] = Field(default=None, description="Error message (human-readable description)")
+    data: Optional[Dict[str, Any]] = Field(default=None, description="Optional output data from the command handler")
+
+class MessageHeader(BaseModel):
+    """Header for NATS messages."""
+    message_type: MessageType = Field(description="Type of message")
+    version: str = Field(default="1.0", description="Message version")
+    timestamp: str = Field(default_factory=_get_current_timestamp, description="ISO format timestamp (auto-set on creation)")
+    machine_id: str = Field(description="Machine ID")
+    run_id: Optional[str] = Field(default=None, description="Unique identifier (uuid) for the run/workflow")
+
+class NATSMessage(BaseModel):
+    """
+    Complete NATS message structure.
+    
+    Structure:
+    - header: MessageHeader with message_type, version, timestamp, machine_id, run_id
+    - command: Optional CommandRequest (for command messages)
+    - response: Optional CommandResponse data (for response messages)
+    """
+    header: MessageHeader = Field(description="Header of the NATS message.")
+    command: Optional[CommandRequest] = Field(default=None, description="Command request (for command messages)")
+    response: Optional[CommandResponse] = Field(default=None, description="Command response (for response messages)")

puda_comms-0.0.2.dist-info/METADATA

@@ -0,0 +1,310 @@
+Metadata-Version: 2.3
+Name: puda-comms
+Version: 0.0.2
+Summary: Communication library for the PUDA platform.
+Author: zhao
+Author-email: zhao <20024592+agentzhao@users.noreply.github.com>
+Requires-Dist: nats-py>=2.12.0
+Requires-Dist: puda-drivers
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Puda Comms
+
+A Python module for communication between machines and command services via NATS messaging. Provides client-side services for sending commands, machine-side clients for receiving commands, and data models for structured message exchange.
+
+## Overview
+
+The `puda_comms` module enables asynchronous, reliable communication between command services and machines using NATS (NATS JetStream for guaranteed delivery). It handles:
+
+- **Command execution**: Send commands to machines and receive responses
+- **Message routing**: Queue commands (sequential execution) and immediate commands (control operations)
+- **State management**: Thread-safe execution state tracking for cancellation and locking
+- **Connection management**: Automatic NATS connection handling with async context managers
+
+## Components
+
+The module consists of four main components:
+
+### 1. Models (`models.py`)
+
+Data models for structured message exchange. All models use Pydantic for validation and serialization.
+
+#### Enums
+
+##### `CommandResponseStatus`
+Status of a command response:
+- `SUCCESS`: Command executed successfully
+- `ERROR`: Command execution failed
+
+##### `CommandResponseCode`
+Error codes for command responses:
+- `COMMAND_CANCELLED`: Command was cancelled before completion
+- `JSON_DECODE_ERROR`: Failed to decode JSON payload
+- `EXECUTION_ERROR`: General execution error
+- `EXECUTION_LOCKED`: Execution is locked (another command is running)
+- `UNKNOWN_COMMAND`: Command name not recognized
+- `PAUSE_ERROR`: Error occurred while pausing execution
+- `RESUME_ERROR`: Error occurred while resuming execution
+- `NO_EXECUTION`: No execution found
+- `RUN_ID_MISMATCH`: Run ID doesn't match current execution
+- `CANCEL_ERROR`: Error occurred while cancelling execution
+- `MACHINE_PAUSED`: Machine is currently paused
+
+##### `MessageType`
+Type of NATS message:
+- `COMMAND`: Command message sent to machine
+- `RESPONSE`: Response message from machine
+- `LOG`: Log message
+- `ALERT`: Alert message
+- `MEDIA`: Media message
+
+##### `ImmediateCommand`
+Command names for immediate/control commands:
+- `PAUSE`: Pause the current execution
+- `RESUME`: Resume a paused execution
+- `CANCEL`: Cancel the current execution
+
+#### Data Models
+
+##### `CommandRequest`
+Represents a command to be sent to a machine.
+
+**Fields:**
+- `name` (str): The command name to execute
+- `params` (Dict[str, Any]): Command parameters (default: empty dict)
+- `step_number` (int): Execution step number for tracking progress
+- `version` (str): Command version (default: "1.0")
+
+**Example:**
+```python
+command = CommandRequest(
+    name="attach_tip",
+    params={"slot": "A3", "well": "G8"},
+    step_number=2,
+    version="1.0"
+)
+```
+
+##### `CommandResponse`
+Represents the result of a command execution.
+
+**Fields:**
+- `status` (CommandResponseStatus): Status of the command response (SUCCESS or ERROR)
+- `completed_at` (str): ISO 8601 UTC timestamp (auto-generated)
+- `code` (Optional[str]): Error code if status is ERROR
+- `message` (Optional[str]): Human-readable error message
+
+**Example:**
+```python
+response = CommandResponse(
+    status=CommandResponseStatus.SUCCESS,
+    completed_at="2026-01-20T02:00:46Z"
+)
+```
+
+**Error Example:**
+```python
+error_response = CommandResponse(
+    status=CommandResponseStatus.ERROR,
+    code="EXECUTION_ERROR",
+    message="Failed to attach tip: slot A3 not found",
+    completed_at="2026-01-20T02:00:46Z"
+)
+```
+
+##### `MessageHeader`
+Header metadata for NATS messages.
+
+**Fields:**
+- `message_type` (MessageType): Type of message (COMMAND, RESPONSE, LOG, etc.)
+- `version` (str): Message version (default: "1.0")
+- `timestamp` (str): ISO 8601 UTC timestamp (auto-generated)
+- `machine_id` (str): Identifier for the target machine
+- `run_id` (Optional[str]): Unique identifier (UUID) for the run/workflow
+
+**Example:**
+```python
+header = MessageHeader(
+    message_type=MessageType.RESPONSE,
+    version="1.0",
+    timestamp="2026-01-20T02:00:46Z",
+    machine_id="first",
+    run_id="092073e6-13d0-4756-8d99-eff1612a5a72"
+)
+```
+
+##### `NATSMessage`
+Complete NATS message structure combining header with optional command or response data.
+
+**Fields:**
+- `header` (MessageHeader): Message header (required)
+- `command` (Optional[CommandRequest]): Command request (for command messages)
+- `response` (Optional[CommandResponse]): Command response (for response messages)
+
+**Structure:**
+- For command messages: include `header` with `message_type=COMMAND` and `command` field
+- For response messages: include `header` with `message_type=RESPONSE` and `response` field
+
+**Complete Message Example:**
+```json
+{
+  "header": {
+    "message_type": "response",
+    "version": "1.0",
+    "timestamp": "2026-01-20T02:00:46Z",
+    "machine_id": "first",
+    "run_id": "092073e6-13d0-4756-8d99-eff1612a5a72"
+  },
+  "command": {
+    "name": "attach_tip",
+    "params": {
+      "slot": "A3",
+      "well": "G8"
+    },
+    "step_number": 2,
+    "version": "1.0"
+  },
+  "response": {
+    "status": "success",
+    "completed_at": "2026-01-20T02:00:46Z",
+    "code": null,
+    "message": null
+  }
+}
+```
+
+### 2. CommandService (`command_service.py`)
+
+Client-side service for sending commands to machines via NATS. Handles:
+- Connecting to NATS servers
+- Sending commands to machines (queue or immediate)
+- Waiting for and handling responses
+- Managing command lifecycle (run_id, step_number, etc.)
+- Automatic connection cleanup via async context manager
+
+See [Sending Commands](#sending-commands) section for usage examples.
+
+### 3. MachineClient (`machine_client.py`)
+
+Basic default NATS client for generic machines. Handles commands, telemetry, and events following the `puda.{machine_id}.{category}.{sub_category}` pattern. Provides:
+- Subscribing to command streams (queue and immediate) via JetStream with exactly-once delivery
+- Processing incoming commands and sending command responses
+- Publishing telemetry (core NATS, no JetStream)
+- Publishing events (core NATS, fire-and-forget)
+- Connection management and reconnection handling
+
+**Note:** This is a generic client. Machine-specific methods should be implemented in the machine-edge client.
+
+### 4. ExecutionState (`execution_state.py`)
+
+Thread-safe state management for command execution. Provides:
+- Execution lock to prevent concurrent commands
+- Current task tracking for cancellation
+- Run ID matching for cancel operations
+- Thread-safe access to execution state
+
+## Sending Commands
+
+The `CommandService` provides a high-level interface for sending commands to machines via NATS. See [`tests/commands.py`](tests/commands.py) and [`tests/batch_commands.py`](tests/batch_commands.py) for complete examples.
+
+### Recommended Usage: Async Context Manager
+
+The recommended way to use `CommandService` is with an async context manager, which automatically handles connection and disconnection. See [`tests/commands.py`](tests/commands.py) for complete examples.
+
+### Command Types
+
+#### Queue Commands
+
+Queue commands are regular commands that are executed in sequence. Use `send_queue_command()` for machine-specific operations.
+
+**Note:** Available commands depend on the machine you are controlling. Different machines support different command sets. See [`puda_drivers`](../drivers/README.md) for information about available commands for each machine type (e.g., `first` machine supports commands like `load_deck`, `attach_tip`, `aspirate_from`, `dispense_to`, `drop_tip`, etc.).
+
+Both `send_queue_command()`, `send_queue_commands()`, and `send_immediate_command()` accept an optional `timeout` parameter (default: 120 seconds):
+
+```python
+# Single command
+reply = await service.send_queue_command(
+    request=request,
+    machine_id="first",
+    run_id=run_id,
+    timeout=60  # Wait up to 60 seconds
+)
+
+# Multiple commands (timeout applies to each command)
+reply = await service.send_queue_commands(
+    requests=commands,
+    machine_id="first",
+    run_id=run_id,
+    timeout=60  # Wait up to 60 seconds per command
+)
+```
+
+**Examples:**
+
+See [`tests/commands.py`](tests/commands.py) for complete examples.
+
+#### Immediate Commands
+
+Immediate commands are control commands that interrupt or modify execution. Use `send_immediate_command()` for:
+- `pause`: Pause the current execution
+- `resume`: Resume a paused execution
+- `cancel`: Cancel the current execution
+
+**Examples:**
+
+See [`tests/commands.py`](tests/commands.py) for complete examples.
+
+
+
+### Sending Command Sequences
+
+You can send multiple commands in sequence using `send_queue_commands()`, which sends commands one by one and waits for each response before sending the next. If any command fails or times out, it stops immediately and returns the error response.
+
+**Loading Commands from JSON (Recommended for LLM-generated commands):**
+
+When generating commands from an LLM or loading from external sources, you can store commands in a JSON file and load them. See [`tests/batch_commands.py`](tests/batch_commands.py) for a complete example.
+
+### Error Handling
+
+Always check the response status and handle errors appropriately:
+
+```python
+reply: NATSMessage = await service.send_queue_command(
+    request=request,
+    machine_id="first",
+    run_id=run_id
+)
+
+if reply is None:
+    # Command timed out or failed to send
+    logger.error("Command failed or timed out")
+elif reply.response is not None and reply.response.status == CommandResponseStatus.SUCCESS:
+    # Command succeeded
+    logger.info("Command completed successfully")
+else:
+    # Command failed with error
+    logger.error("Command failed with code: %s, message: %s", 
+                reply.response.code if reply.response else None,
+                reply.response.message if reply.response else None)
+```
+
+### Configuration
+
+The `CommandService` reads NATS server URLs from the `NATS_SERVERS` environment variable, or defaults to:
+```
+nats://192.168.50.201:4222,nats://192.168.50.201:4223,nats://192.168.50.201:4224
+```
+
+You can also specify servers explicitly:
+```python
+service = CommandService(servers=["nats://localhost:4222"])
+```
+## Validation
+
+All models use Pydantic for validation, ensuring:
+- Type checking for all fields
+- Required fields are present
+- Default values are applied correctly
+- JSON serialization/deserialization works correctly

puda_comms-0.0.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+puda_comms/__init__.py,sha256=lntvVFJJez_rv5lZy5mYj4_43B9Y3NRNzxWfBuSAQ1M,194
+puda_comms/command_service.py,sha256=B4fKiQNF0slvGS1fXVoh5UZax_-xk4IS-KT96teSRfg,23272
+puda_comms/execution_state.py,sha256=aTaejCnJgg1y_FP-ymIC1GQzqC81FIWo0RZ18XzAQnA,2881
+puda_comms/machine_client.py,sha256=F2i0BYBuOLjKAnfZAblNrb3Lzs0yhEO1d4XA-k_dkIU,33039
+puda_comms/models.py,sha256=cVH5uKzyLmjzPeBcm3RIJMTkoynmxqe_P26GtZwlIN8,3500
+puda_comms-0.0.2.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
+puda_comms-0.0.2.dist-info/METADATA,sha256=jHHcSSmdWOykobTsieX2bqDeRtqSaqdUd-xZeeWxJZ8,10585
+puda_comms-0.0.2.dist-info/RECORD,,

puda_comms-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.18
+Root-Is-Purelib: true
+Tag: py3-none-any