Metadata-Version: 2.4
Name: cyberwave
Version: 0.6.2
Summary: Python SDK for Cyberwave
License-File: LICENSE
Author: Simone Di Somma
Author-email: sdisomma@cyberwave.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: barcode
Provides-Extra: camera
Provides-Extra: data
Provides-Extra: drivers
Provides-Extra: fuzzy-match
Provides-Extra: image
Provides-Extra: microphone
Provides-Extra: ml
Provides-Extra: ml-all
Provides-Extra: ml-all-audio
Provides-Extra: ml-all-vision
Provides-Extra: ml-audio
Provides-Extra: ml-hailo
Provides-Extra: ml-onnx
Provides-Extra: ml-opencv
Provides-Extra: ml-stt
Provides-Extra: ml-stt-faster
Provides-Extra: ml-tflite
Provides-Extra: ml-wakeword
Provides-Extra: onnx
Provides-Extra: realsense
Provides-Extra: schedule
Provides-Extra: speaker
Provides-Extra: tflite
Provides-Extra: zenoh
Requires-Dist: aiortc (>=1.14.0,<2.0.0) ; extra == "camera" or extra == "microphone" or extra == "speaker" or extra == "realsense"
Requires-Dist: av (>=16.0.1,<17.0.0) ; extra == "camera" or extra == "microphone" or extra == "speaker" or extra == "realsense"
Requires-Dist: croniter (>=6.2.2) ; extra == "schedule"
Requires-Dist: eclipse-zenoh (>=1.0.0) ; extra == "zenoh" or extra == "data"
Requires-Dist: faster-whisper (>=1.1.1) ; extra == "ml-stt-faster" or extra == "ml-all-audio" or extra == "ml-all"
Requires-Dist: numpy (>=1.26.0)
Requires-Dist: onnxruntime (>=1.16.0) ; extra == "ml-onnx" or extra == "ml-wakeword" or extra == "ml-all-vision" or extra == "ml-all-audio" or extra == "ml-all" or extra == "onnx"
Requires-Dist: opencv-python-headless (>=4.8.0,<5.0.0) ; extra == "camera" or extra == "realsense" or extra == "data" or extra == "ml-opencv" or extra == "ml-all-vision" or extra == "ml-all"
Requires-Dist: openwakeword (>=0.6.0) ; extra == "ml-wakeword" or extra == "ml-all-audio" or extra == "ml-all"
Requires-Dist: paho-mqtt (>=2.1.0,<3.0.0)
Requires-Dist: pillow (>=10.0.0) ; extra == "image"
Requires-Dist: pin (>=3.0.0) ; extra == "drivers"
Requires-Dist: pyarrow (>=14.0.0) ; extra == "data"
Requires-Dist: pydantic (>=2,<3)
Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
Requires-Dist: pyudev (>=0.24.3) ; extra == "microphone" or extra == "speaker"
Requires-Dist: pywhispercpp (==1.4.1) ; extra == "ml-stt" or extra == "ml-all-audio" or extra == "ml-all"
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: rapidfuzz (>=3.0.0) ; extra == "fuzzy-match" or extra == "ml-all-audio" or extra == "ml-all"
Requires-Dist: scipy (>=1.10) ; extra == "drivers"
Requires-Dist: silero-vad (>=6.0) ; extra == "ml-audio" or extra == "ml-all-audio" or extra == "ml-all"
Requires-Dist: sounddevice (>=0.5.2) ; extra == "microphone" or extra == "speaker"
Requires-Dist: tflite-runtime (>=2.14.0) ; extra == "ml-tflite" or extra == "ml-all-vision" or extra == "ml-all" or extra == "tflite"
Requires-Dist: torchaudio (>=2.0.0) ; extra == "ml-all-audio" or extra == "ml-all"
Requires-Dist: typing-extensions (>=4.7.1,<5.0.0)
Requires-Dist: ultralytics (>=8.0.0) ; extra == "ml" or extra == "ml-all-vision" or extra == "ml-all"
Requires-Dist: urllib3 (>=2.1.0,<3.0.0)
Requires-Dist: zxing-cpp (==3.0.0) ; extra == "barcode" or extra == "ml-all"
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://cyberwave.com">
    <img src="assets/cyberwave-logo.png" alt="Cyberwave logo" width="320" />
  </a>
</p>

<h1 align="center">Cyberwave Python SDK</h1>

<p align="center">
  <b>Making the physical world programmable.</b><br/>
  Connect, control, and simulate any robot. The same code runs in simulation and on real hardware.
</p>

<p align="center">
  <img src="assets/hero-montage.gif" alt="Cyberwave SDK — deploy any robot as a digital twin, in simulation and on real hardware" width="800" />
</p>

<p align="center">
  <a href="https://github.com/cyberwave-os/cyberwave-python/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-orange.svg" alt="License"></a>
  <a href="https://docs.cyberwave.com"><img src="https://img.shields.io/badge/Documentation-docs.cyberwave.com-orange" alt="Documentation"></a>
  <a href="https://discord.gg/dfGhNrawyF"><img src="https://badgen.net/badge/icon/discord?icon=discord&label&color=orange" alt="Discord"></a>
  <a href="https://pypi.org/project/cyberwave/"><img src="https://img.shields.io/pypi/v/cyberwave.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/cyberwave/"><img src="https://img.shields.io/pypi/pyversions/cyberwave.svg" alt="PyPI Python versions"></a>
  <a href="https://github.com/cyberwave-os/cyberwave-python/actions/workflows/test.yml"><img src="https://github.com/cyberwave-os/cyberwave-python/actions/workflows/test.yml/badge.svg" alt="Build"></a>
</p>

---

Cyberwave is an all-in-one platform for building and deploying intelligent physical AI agents. 
Connect a physical robot or sensor, test it in simulation, and run AI models; all through one Python SDK.
This package is the official client.

## Installation

```bash
pip install cyberwave
```

Optional features install via extras, e.g. `cyberwave[camera]` (video streaming),
`cyberwave[ml]` (vision models), or `cyberwave[zenoh]` (edge data bus). See the
[installation docs](https://docs.cyberwave.com/overview) for the full list.

## Quick Start

Get an API key from your Cyberwave instance (**Profile → API Tokens**) and export it:

```bash
export CYBERWAVE_API_KEY="your_api_key_here"
```

Then create and control your first digital twin:

```python
from cyberwave import Cyberwave

cw = Cyberwave()  # reads CYBERWAVE_API_KEY from the environment

# Create a digital twin from a catalog asset.
# Pin it to a specific twin and environment by passing their IDs (UUID or slug).
# Omit both and Cyberwave creates a "Quickstart Environment" for you automatically.
arm = cw.twin(
    "the-robot-studio/so101",
    twin_id="your-twin-uuid",                 # e.g. "acme/twins/arm-station-1"
    environment_id="your-environment-uuid",   # e.g. "acme/envs/production-floor"
)

# Place it in the scene (editor layout)
arm.edit_position(x=1.0, y=0.0, z=0.5)
arm.edit_rotation(yaw=90)  # degrees

# Move a joint by name
joint_names = arm.joints.list()
if joint_names:
    arm.set_joints({joint_names[0]: -0.2})  # radians
    print(arm.get_joints())

# Drive a locomotion twin in simulation
cw.affect("simulation")          # or cw.affect("live") for the real robot
rover = cw.twin("unitree/go2")
rover.move_forward(0.3)

cw.disconnect()
```

The same script targets real hardware by switching `cw.affect("live")`, no other changes.

## Core Concepts

- **Twins** — virtual representations of robots and sensors. You develop and test against a twin, then deploy to hardware with identical code. Instantiate any catalog asset with `cw.twin("vendor/slug")`.
- **Environments** — scenes your twins live in. Validate quickly in the browser-based Playground, or use MuJoCo for high-fidelity physics and RL.
- **Simulation vs. live** — `cw.affect("simulation")` and `cw.affect("live")` switch where commands and state go. The same code drives both.
- **Edge & cloud** — stream camera/sensor data and run AI models on the edge or in the cloud, without managing the infrastructure in between.

## Demos

Watch the SDK in action with our demos.

<table>
  <tr>
    <td width="50%">
      <a href="https://youtu.be/kUxSxCMCQgc">
        <img src="https://img.youtube.com/vi/kUxSxCMCQgc/hqdefault.jpg" alt="Build a natural language voice agent on SO101" width="100%" />
      </a>
      <br/>
      <b><a href="https://youtu.be/kUxSxCMCQgc">Build a natural language voice agent on SO101</a></b>
    </td>
    <td width="50%">
      <a href="https://youtu.be/ITz9zMf0ObA">
        <img src="https://img.youtube.com/vi/ITz9zMf0ObA/hqdefault.jpg" alt="Controlling a DJI Mini 4 Pro with the Cyberwave Python SDK" width="100%" />
      </a>
      <br/>
      <b><a href="https://youtu.be/ITz9zMf0ObA">Controlling a DJI Mini 4 Pro with the Cyberwave Python SDK</a></b>
    </td>
  </tr>
</table>

## Examples

Runnable scripts live in [examples/](examples) and see the [examples index](examples/README.md) for the full list.

| Example | Shows |
| --- | --- |
| [quickstart.py](examples/quickstart.py) | Create a twin, scene layout, joints, locomotion |
| [joints.py](examples/joints.py) | Read and write joint positions by name |
| [locomotion.py](examples/locomotion.py) | Velocity-style locomotion commands |
| [capture_frame.py](examples/capture_frame.py) | Grab a single camera frame from a twin |
| [camera_stream.py](examples/camera_stream.py) | Stream a camera feed over WebRTC |
| [drone_hovering.py](examples/drone_hovering.py) | Takeoff, hover, and land a flying twin |
| [workflows.py](examples/workflows.py) | List, trigger, and monitor workflows |
| [ai/yolo.ipynb](examples/ai/yolo.ipynb) | Run YOLO vision models (Colab) |

## Documentation

Full guides and the complete API reference are at **[docs.cyberwave.com](https://docs.cyberwave.com)**
([overview](https://docs.cyberwave.com/overview) ·
[API reference](https://docs.cyberwave.com/api-reference/overview)).

## Contributing

Contributions are welcome. Please open an
[issue](https://github.com/cyberwave-os/cyberwave-python/issues) or a pull request.

## Support

- **Documentation**: [docs.cyberwave.com](https://docs.cyberwave.com)
- **Issues**: [GitHub Issues](https://github.com/cyberwave-os/cyberwave-python/issues)
- **Community**: [Discord](https://discord.gg/dfGhNrawyF)

## License

Released under the [MIT License](LICENSE).
