Metadata-Version: 2.4
Name: spatialai
Version: 0.1.0
Summary: SpatialAI SDK — Python API for VisionLibra ToF depth sensors and cameras (simulator included, DM0301/VL53L4CD I2C support)
Author-email: VisionLibra <sales@visionlibra.com>
License: MIT
Project-URL: Homepage, https://visionlibra.adamaohappy.workers.dev
Project-URL: Documentation, https://visionlibra.adamaohappy.workers.dev/developer.html
Keywords: tof,time-of-flight,depth,sensor,lidar,vl53l4cd,spatial,visionlibra
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dm0301
Requires-Dist: adafruit-circuitpython-vl53l4cd>=1.1; extra == "dm0301"
Requires-Dist: adafruit-blinka>=8.0; extra == "dm0301"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# SpatialAI SDK

Python SDK for [VisionLibra](https://visionlibra.adamaohappy.workers.dev) ToF depth
sensors and cameras.

> Physical AI starts with Spatial Intelligence + AI Agents.

```bash
pip install spatialai
```

Five lines to spatial intelligence:

```python
from spatialai import Camera

cam = Camera()
result = cam.detect_people()
print(result)
# {'people': 1, 'nearest_m': 1.42, 'positions': [...], 'source': 'simulator'}
```

## Status — v0.1 (alpha)

| Feature | Status |
|---|---|
| Simulator (all four products, no hardware needed) | ✅ works everywhere |
| Spatial Mini / DM0301 over I²C (VL53L4CD-compatible) | ✅ Raspberry Pi & Linux SBCs, via `pip install spatialai[dm0301]` |
| Spatial Home / Vision / Robot real backends | 🚧 in development — simulator only for now |
| Model marketplace, agents, fleet | 🚧 in development |

## Simulator — works on any machine

Every device can run in simulator mode, which generates realistic distance and
people-detection streams. It is the default whenever no hardware is detected,
so the quickstart above always runs.

```python
from spatialai import Camera

cam = Camera("spatial-vision", simulate=True)
for frame in cam.stream(hz=10, duration=3):
    print(f"people={frame.people} nearest={frame.nearest_m:.2f}m")
```

Try it from the terminal:

```bash
spatialai demo                  # live simulated distance readout
spatialai demo --device spatial-vision
spatialai scan                  # look for real hardware on I2C
```

## Real hardware — Spatial Mini (DM0301)

The DM0301 1D ToF sensor is pin-to-pin compatible with the ST VL53L4CD, so the
SDK drives it through the proven Adafruit driver stack.

Wiring (Raspberry Pi): VIN→3V3, GND→GND, SDA→GPIO2, SCL→GPIO3 (I²C address `0x29`).

```bash
sudo raspi-config          # enable I2C
pip install "spatialai[dm0301]"
```

```python
from spatialai import Sensor

lock = Sensor("spatial-mini")      # auto-detects the sensor on I2C
print(lock.distance_m())           # 0.734

for reading in lock.stream(hz=20):
    if reading.distance_m < 0.5:
        print("presence!", reading)
```

`Camera("spatial-mini").detect_people()` also works on real hardware: it maps
near-field presence onto the people-detection schema (0 or 1 person).

## API overview

- `Camera(device_id=None, simulate=None)` — unified entry point.
  `.detect_people()`, `.stream(hz, duration)`, `.distance_m()`, `.info()`
- `Sensor(device_id)` — alias of `Camera` tuned for 1D sensors.
- `spatialai.devices()` — catalog of supported products.
- Exceptions: `DeviceNotFound`, `HardwareNotSupportedYet`.

## Roadmap

Depth-frame backends for Spatial Home (DMOS5030A serial), Spatial Vision
(DMOM2508CL) and Spatial Robot (DMAS2M001), on-device people tracking models,
and the agent/fleet APIs. Follow along at
[visionlibra.adamaohappy.workers.dev/developer.html](https://visionlibra.adamaohappy.workers.dev/developer.html).

## License

MIT
