Metadata-Version: 2.4
Name: loop-sdk
Version: 0.6.0
Summary: Python SDK for implementing Loop Robot Control Platform Nodes.
Project-URL: Documentation, https://github.com/configinc/loop-sdk/blob/main/docs/architecture.md
Project-URL: Examples, https://github.com/configinc/loop-sdk/tree/main/examples
Project-URL: Source, https://github.com/configinc/loop-sdk
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: loop-node[numpy]<0.4.0,>=0.3.0
Requires-Dist: pydantic>=2.12.0

# loop-sdk

Connect your robots, cameras, sensors, policies, and teleoperation code to Loop.
Your Python application exposes a Node; Loop connects it to a Cell for control
and recording.

## How Loop uses your Node

Your application owns the device or model code and its execution loop. Loop's
Orchestrator applies Config and manages the Node's lifecycle. The Node exchanges
application data directly with other Nodes through Ports.

<img src="docs/assets/sdk-overview.svg" alt="Your application contains a Node built with loop-sdk. Loop Orchestrator manages its Config, bindings, and lifecycle; application data travels directly between its Ports and other Cell Nodes." width="800">

## Install

Install SDK 0.6.0 for Loop v2 in an isolated environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install loop-sdk==0.6.0
python -c 'from loop_sdk import CameraNode, SensorNode, RobotNode'
```

Installation brings in `loop-node[numpy]>=0.3.0,<0.4.0`, including NumPy; no
separate NumPy extra is needed on `loop-sdk`. Release wheels support
**CPython 3.10–3.14 on Linux x86_64 and ARM64 (aarch64), with glibc 2.28+**.
You also need a running Loop instance using `loop-node` 0.3.x (control protocol
version 2) to activate Nodes. Update Loop and external Nodes together.

## Port transport

Ports default to `auto`: image contracts use shared memory when all connected
peers pass the SHM probe, and otherwise use ordinary Zenoh transmission.
Contracts without images use ordinary transmission by default. Custom Port
declarations can require `zenoh_network` or `zenoh_shared_memory`; request and
reply policies are independent. The selected mode stays fixed until bindings
are released, and Cell Config no longer stores transport choices.

Application payloads and the publish/poll/request APIs remain unchanged. See
[transport policies](docs/node_api.md#transportmode) for options and
[Port declarations](docs/node_api.md#port-declaration-methods) for usage.

## Run your first Node

Start with the simulated [sensor example](https://github.com/configinc/loop-sdk/blob/main/examples/sensor_node.py).
It needs no hardware.

1. Save the file as `sensor_node.py`. It connects to `tcp/127.0.0.1:7448`;
   change `loop_endpoint` in the file if Loop runs on another host.
2. Run your Node:

   ```bash
   python sensor_node.py
   ```

3. In Loop, add `force_sensor` to a Cell as an external `loop.sensor@1` Node.
   Config `{}` uses the defaults. Connect its `sensor_observation` output to
   Main Controller Node, then click **Start Nodes**.

The terminal prints `Start: sample_hz=50.0`, and the Node begins publishing
`{"force": 1.25}` approximately 50 times per second. Launching the script
connects the Node; **Loop configures it, validates connections, then starts publication**. Stop Nodes pauses it;
Ctrl+C exits the example.

## Node classes and examples

| What your application does | Example |
|---|---|
| Read sensor values | [SensorNode](https://github.com/configinc/loop-sdk/blob/main/examples/sensor_node.py) |
| Provide camera frames | [CameraNode](https://github.com/configinc/loop-sdk/blob/main/examples/camera_node.py) |
| Publish robot state and apply incoming actions | [RobotNode](https://github.com/configinc/loop-sdk/blob/main/examples/robot_node.py) |
| Run an existing robot control loop and record its observation/action pairs | [RobotStepNode](https://github.com/configinc/loop-sdk/blob/main/examples/robot_step_node.py) |
| Generate actions with a model | [PolicyNode](https://github.com/configinc/loop-sdk/blob/main/examples/policy_node.py) |
| Generate actions through teleoperation | [TeleopNode](https://github.com/configinc/loop-sdk/blob/main/examples/teleop_node.py) |

Replace each example's simulated or file-backed data with your device or model.
See the [example setup guide](https://github.com/configinc/loop-sdk/blob/main/examples/README.md)
for Node IDs, Config, and compatible examples.

## Documentation

| Guide | Use it to |
|---|---|
| [Architecture and lifecycle](https://github.com/configinc/loop-sdk/blob/main/docs/architecture.md) | Understand Nodes, Ports, the Orchestrator, and Configure/Start/Stop |
| [Recording flow and data](https://github.com/configinc/loop-sdk/blob/main/docs/recording_flow.md) | Follow observations and actions into a recorded episode |
| [Node API reference](https://github.com/configinc/loop-sdk/blob/main/docs/node_api.md) | Look up classes, methods, contracts, and value types |

For SDK development, see [CONTRIBUTING.md](CONTRIBUTING.md).
