antioch-py 3.0.3__tar.gz

antioch_py-3.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Antioch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

antioch_py-3.0.3/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.pypi.md
+include LICENSE
+

antioch_py-3.0.3/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: antioch-py
+Version: 3.0.3
+Summary: Antioch Python Module SDK
+Author-email: Antioch Robotics <support@antioch.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://antioch.com
+Keywords: robotics,simulation,middleware,sdk,modules
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: docker>=7.0.0
+Requires-Dist: eclipse-zenoh>=1.5.0
+Requires-Dist: foxglove-sdk>=0.14.1
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: msgpack==1.1.1
+Requires-Dist: msgpack>=1.1.1
+Requires-Dist: numpy==1.26.0
+Requires-Dist: ormsgpack>=1.6.0
+Requires-Dist: pydantic>=2.11.6
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: scipy==1.15.3
+Requires-Dist: sortedcontainers-stubs>=2.4.3
+Requires-Dist: sortedcontainers>=2.4.0
+Dynamic: license-file
+
+# antioch-py
+
+Python SDK for the [Antioch](https://antioch.com) autonomy simulation platform.
+
+## Overview
+
+The antioch-py package provides two components:
+
+### Module SDK (`antioch.module`)
+
+The Module SDK is a framework for building Antioch modules in Python. Modules are containerized components that run alongside your simulation, processing sensor data and producing outputs. Each module runs in its own Docker container and communicates with the simulation through the Antioch runtime. Install the SDK in your module's Dockerfile to read sensors, run inference, and publish results.
+
+```python
+from antioch.module import Execution, Module
+
+def process_radar(execution: Execution) -> None:
+    scan = execution.read_radar("sensor")
+    if scan is not None and len(scan.detections) > 0:
+        execution.output("detections").set(scan)
+
+if __name__ == "__main__":
+    module = Module()
+    module.register("radar_node", process_radar)
+    module.spin()
+```
+
+### Session SDK (`antioch.session`)
+
+The Session SDK is a client library for orchestrating Antioch simulations. Use it from Python scripts or Jupyter notebooks to programmatically build scenes, load assets, spawn robots, control simulation playback, and record data. The Session SDK connects to your Antioch deployment and provides a high-level API for automation and experimentation.
+
+```python
+from antioch.session import Scene, Session, Task, TaskOutcome
+
+session = Session()
+scene = Scene()
+
+# Load environment and robot
+scene.add_asset(path="/World/environment", name="warehouse", version="1.0.0")
+ark = scene.add_ark(name="my_robot", version="0.1.0")
+
+# Run simulation
+task = Task()
+task.start(mcap_path="/tmp/recording.mcap")
+
+scene.step(1_000_000)  # step 1 second
+
+task.finish(outcome=TaskOutcome.SUCCESS)
+```
+
+## Installation
+
+To install in your Python environment:
+
+```bash
+pip install antioch-py
+```
+
+To install in your Python-based Docker image (e.g. for an Antioch module):
+
+```dockerfile
+FROM python:3.12-slim
+
+RUN pip install antioch-py
+
+COPY . /app
+WORKDIR /app
+
+CMD ["python", "module.py"]
+```
+
+## Documentation
+
+Visit [antioch.com](https://antioch.com) for full documentation.
+
+## License
+
+MIT

antioch_py-3.0.3/README.md

@@ -0,0 +1,105 @@
+# antioch-py
+
+The Antioch Python Module SDK for building deterministic robotic modules.
+
+## Overview
+
+`antioch-py` provides the Python client library for implementing Antioch modules - the core computational units that run inside Arks. Modules contain nodes that execute callbacks on a deterministic schedule, communicating via tokens.
+
+## Installation
+
+```bash
+pip install antioch-py
+```
+
+## Quick Start
+
+```python
+from antioch import Module, Execution
+
+def my_callback(execution: Execution) -> None:
+    """Process inputs and produce outputs."""
+    # Read input data
+    input_data = execution.input("sensor_data")
+    
+    # Process data
+    result = process(input_data)
+    
+    # Write output
+    execution.output("processed", result)
+
+# Create and run module
+module = Module()
+module.register("my_node", my_callback)
+module.spin()
+```
+
+## Key Concepts
+
+### Module
+
+The `Module` class is the main entry point for implementing Antioch modules. It handles:
+- Configuration loading from environment (container mode) or explicit parameters (local mode)
+- Node registration and lifecycle management
+- Startup handshake and synchronization
+
+### Node
+
+Nodes are the computational units within a module. Each node:
+- Runs in its own thread
+- Executes on a deterministic schedule
+- Receives input tokens and produces output tokens
+
+### Execution
+
+The `Execution` object is passed to node callbacks and provides:
+- Access to input data via `input(name)`
+- Output publishing via `output(name, data)`
+- Hardware read/write for simulation mode
+- Logging via `execution.logger`
+
+## Modes of Operation
+
+### Container Mode (Default)
+
+When running inside an Ark pod, the module automatically loads configuration from environment variables:
+- `_MODULE_NAME`: Module name
+- `_ARK`: Ark configuration JSON
+- `_ENVIRONMENT`: Execution environment (sim/real)
+- `_DEBUG`: Debug mode flag
+
+### Local Mode
+
+For testing and development, provide configuration explicitly:
+
+```python
+from antioch import Module, Environment
+
+module = Module(
+    module_name="my_module",
+    ark=my_ark_config,
+    environment=Environment.SIM,
+    debug=True,
+)
+```
+
+## API Reference
+
+### Module
+
+- `Module(module_name=None, ark=None, environment=Environment.REAL, debug=False)`: Create a module
+- `register(name, callback)`: Register a node callback
+- `spin()`: Start the module and wait for shutdown
+- `join(timeout=None)`: Wait for all nodes to finish
+
+### Execution
+
+- `input(name) -> list[Token]`: Get input tokens for an input
+- `output(name, data)`: Set output data for an output
+- `hardware_read(name) -> bytes`: Read hardware data (sim mode)
+- `hardware_write(name, data)`: Write hardware data (sim mode)
+- `logger`: Logger for telemetry and debugging
+
+## License
+
+MIT

antioch_py-3.0.3/README.pypi.md

@@ -0,0 +1,77 @@
+# antioch-py
+
+Python SDK for the [Antioch](https://antioch.com) autonomy simulation platform.
+
+## Overview
+
+The antioch-py package provides two components:
+
+### Module SDK (`antioch.module`)
+
+The Module SDK is a framework for building Antioch modules in Python. Modules are containerized components that run alongside your simulation, processing sensor data and producing outputs. Each module runs in its own Docker container and communicates with the simulation through the Antioch runtime. Install the SDK in your module's Dockerfile to read sensors, run inference, and publish results.
+
+```python
+from antioch.module import Execution, Module
+
+def process_radar(execution: Execution) -> None:
+    scan = execution.read_radar("sensor")
+    if scan is not None and len(scan.detections) > 0:
+        execution.output("detections").set(scan)
+
+if __name__ == "__main__":
+    module = Module()
+    module.register("radar_node", process_radar)
+    module.spin()
+```
+
+### Session SDK (`antioch.session`)
+
+The Session SDK is a client library for orchestrating Antioch simulations. Use it from Python scripts or Jupyter notebooks to programmatically build scenes, load assets, spawn robots, control simulation playback, and record data. The Session SDK connects to your Antioch deployment and provides a high-level API for automation and experimentation.
+
+```python
+from antioch.session import Scene, Session, Task, TaskOutcome
+
+session = Session()
+scene = Scene()
+
+# Load environment and robot
+scene.add_asset(path="/World/environment", name="warehouse", version="1.0.0")
+ark = scene.add_ark(name="my_robot", version="0.1.0")
+
+# Run simulation
+task = Task()
+task.start(mcap_path="/tmp/recording.mcap")
+
+scene.step(1_000_000)  # step 1 second
+
+task.finish(outcome=TaskOutcome.SUCCESS)
+```
+
+## Installation
+
+To install in your Python environment:
+
+```bash
+pip install antioch-py
+```
+
+To install in your Python-based Docker image (e.g. for an Antioch module):
+
+```dockerfile
+FROM python:3.12-slim
+
+RUN pip install antioch-py
+
+COPY . /app
+WORKDIR /app
+
+CMD ["python", "module.py"]
+```
+
+## Documentation
+
+Visit [antioch.com](https://antioch.com) for full documentation.
+
+## License
+
+MIT

antioch_py-3.0.3/antioch/__init__.py

@@ -0,0 +1,101 @@
+from antioch.clock import Clock
+from antioch.execution import Execution
+from antioch.input import NodeInputBuffer
+from antioch.module import Module
+from antioch.node import Node
+from common.ark import Environment
+from common.ark.token import Token, TokenType
+from common.message import (
+    Array,
+    Bool,
+    CameraInfo,
+    CircleAnnotation,
+    Color,
+    DeserializationError,
+    Float,
+    FrameTransform,
+    FrameTransforms,
+    Image,
+    ImageAnnotations,
+    ImageEncoding,
+    Int,
+    JointState,
+    JointStates,
+    JointTarget,
+    JointTargets,
+    Log,
+    LogLevel,
+    Message,
+    MessageError,
+    MismatchError,
+    Point2,
+    Point3,
+    PointCloud,
+    PointsAnnotation,
+    PointsAnnotationType,
+    Pose,
+    Quaternion,
+    RadarScan,
+    SerializationError,
+    String,
+    TextAnnotation,
+    Vector2,
+    Vector3,
+)
+
+__all__ = [
+    # Core
+    "Clock",
+    "Environment",
+    "Execution",
+    "Module",
+    "Node",
+    "NodeInputBuffer",
+    "Token",
+    "TokenType",
+    # Base types
+    "Message",
+    "MessageError",
+    "DeserializationError",
+    "SerializationError",
+    "MismatchError",
+    # Primitive types
+    "Array",
+    "Bool",
+    "Float",
+    "Int",
+    "String",
+    # Geometry types
+    "Point2",
+    "Point3",
+    "Vector2",
+    "Vector3",
+    "Pose",
+    "Quaternion",
+    # Color
+    "Color",
+    # Camera types
+    "CameraInfo",
+    "Image",
+    "ImageEncoding",
+    # Joint types
+    "JointState",
+    "JointStates",
+    "JointTarget",
+    "JointTargets",
+    # Sensor types
+    "RadarScan",
+    "PointCloud",
+    # Logging
+    "Log",
+    "LogLevel",
+    # Annotations
+    "CircleAnnotation",
+    "ImageAnnotations",
+    "PointsAnnotation",
+    "PointsAnnotationType",
+    "TextAnnotation",
+    # Frame transforms
+    "FrameTransform",
+    "FrameTransforms",
+]

antioch_py-3.0.3/antioch/clock.py

@@ -0,0 +1,62 @@
+import time
+from threading import Event
+
+from common.utils.time import now_us
+
+
+class Clock:
+    """
+    Real-time clock for LET-to-wall-time mapping (real mode only).
+
+    Maps logical execution time to wall-clock time using a fixed start time.
+    Provides precise timing for real-mode execution to avoid clock drift.
+    """
+
+    def __init__(self, start_timestamp_us: int, event: Event | None = None):
+        """
+        Create a new real-time clock.
+
+        :param start_timestamp_us: Wall-clock time (microseconds since epoch) corresponding to LET=0.
+        :param event: Optional event to check for shutdown requests during waits.
+        """
+
+        self._start_timestamp_us = start_timestamp_us
+        self._event = event
+
+    @property
+    def let_us(self) -> int:
+        """
+        Get the current logical time in microseconds.
+
+        :return: Current logical time.
+        """
+
+        return now_us() - self._start_timestamp_us
+
+    def wait_until(self, let_us: int) -> bool:
+        """
+        Sleep until reaching target LET.
+
+        Checks shutdown event every 100ms. Uses hybrid sleep approach:
+        - For waits > 10ms: Sleep in chunks (max 100ms) for shutdown responsiveness
+        - For waits < 10ms: Sleep in 100μs increments for precision
+
+        :param let_us: Target logical execution time in microseconds.
+        :return: True if wait completed normally, False if interrupted by event.
+        """
+
+        target_timestamp_us = self._start_timestamp_us + let_us
+        while True:
+            # Check if we should exit
+            current = now_us()
+            if current >= target_timestamp_us:
+                return True
+
+            # Check event if provided
+            if self._event and self._event.is_set():
+                return False
+
+            # Sleep for chunk
+            remaining_us = target_timestamp_us - current
+            sleep_us = min(remaining_us, 100_000) if remaining_us > 10_000 else min(remaining_us, 100)
+            time.sleep(sleep_us / 1_000_000)