spatialai 0.1.0__tar.gz

spatialai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VisionLibra
+
+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.

spatialai-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+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

spatialai-0.1.0/README.md

@@ -0,0 +1,97 @@
+# 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

spatialai-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spatialai"
+version = "0.1.0"
+description = "SpatialAI SDK — Python API for VisionLibra ToF depth sensors and cameras (simulator included, DM0301/VL53L4CD I2C support)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "VisionLibra", email = "sales@visionlibra.com" }]
+keywords = ["tof", "time-of-flight", "depth", "sensor", "lidar", "vl53l4cd", "spatial", "visionlibra"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: System :: Hardware :: Hardware Drivers",
+  "Topic :: Scientific/Engineering :: Image Processing",
+]
+
+[project.urls]
+Homepage = "https://visionlibra.adamaohappy.workers.dev"
+Documentation = "https://visionlibra.adamaohappy.workers.dev/developer.html"
+
+[project.optional-dependencies]
+# Real I2C hardware support for Spatial Mini (DM0301, VL53L4CD-compatible)
+# on Raspberry Pi / Linux SBCs.
+dm0301 = [
+  "adafruit-circuitpython-vl53l4cd>=1.1",
+  "adafruit-blinka>=8.0",
+]
+dev = ["pytest>=7"]
+
+[project.scripts]
+spatialai = "spatialai.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

spatialai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spatialai-0.1.0/src/spatialai/__init__.py

@@ -0,0 +1,33 @@
+"""SpatialAI SDK — Python API for VisionLibra ToF depth sensors and cameras.
+
+Quickstart::
+
+    from spatialai import Camera
+
+    cam = Camera()
+    result = cam.detect_people()
+    print(result)
+
+Runs against real hardware when it is detected (Spatial Mini / DM0301 over
+I2C), and falls back to a realistic simulator everywhere else so the code
+above always works.
+"""
+
+from .camera import Camera, Sensor, Frame, Reading
+from .catalog import DEVICES, devices
+from .exceptions import DeviceNotFound, HardwareNotSupportedYet, SpatialAIError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Camera",
+    "Sensor",
+    "Frame",
+    "Reading",
+    "DEVICES",
+    "devices",
+    "SpatialAIError",
+    "DeviceNotFound",
+    "HardwareNotSupportedYet",
+    "__version__",
+]

spatialai-0.1.0/src/spatialai/camera.py

@@ -0,0 +1,177 @@
+"""Camera / Sensor — the unified SpatialAI device API."""
+
+from __future__ import annotations
+
+import time
+import warnings
+from dataclasses import dataclass, field
+
+from .catalog import DEVICES
+from .exceptions import DeviceNotFound, HardwareNotSupportedYet
+from .simulator import SimulatorBackend
+
+
+@dataclass
+class Reading:
+    """A single 1D distance reading."""
+
+    distance_m: float
+    t: float
+    source: str
+
+    def __repr__(self) -> str:  # keep demos pretty
+        return f"Reading(distance_m={self.distance_m:.3f}, source={self.source!r})"
+
+
+@dataclass
+class Frame:
+    """One people-detection frame."""
+
+    people: int
+    nearest_m: float | None
+    positions: list = field(default_factory=list)
+    t: float = 0.0
+    source: str = "simulator"
+
+
+class Camera:
+    """A VisionLibra depth device.
+
+    Parameters
+    ----------
+    device_id:
+        One of ``spatial-mini``, ``spatial-home``, ``spatial-vision``,
+        ``spatial-robot``. Defaults to auto-detection: the first real device
+        found, else a simulated ``spatial-vision``.
+    simulate:
+        ``True`` forces the simulator, ``False`` requires real hardware
+        (raising :class:`DeviceNotFound` / :class:`HardwareNotSupportedYet`
+        if unavailable). ``None`` (default) tries hardware, then falls back
+        to the simulator with a warning.
+    """
+
+    def __init__(self, device_id: str | None = None, simulate: bool | None = None, seed: int | None = None):
+        if device_id is not None and device_id not in DEVICES:
+            raise DeviceNotFound(
+                f"Unknown device {device_id!r}. Known devices: {', '.join(DEVICES)}"
+            )
+        self.device_id = device_id or self._autodetect_id()
+        self.spec = DEVICES[self.device_id]
+        self._backend = self._open_backend(simulate, seed)
+
+    # -- backend selection ---------------------------------------------------
+
+    @staticmethod
+    def _autodetect_id() -> str:
+        from . import dm0301
+
+        if dm0301.probe():
+            return "spatial-mini"
+        return "spatial-vision"
+
+    def _open_backend(self, simulate: bool | None, seed: int | None):
+        if simulate is True:
+            return SimulatorBackend(self.spec, seed=seed)
+
+        backend_name = self.spec["hardware_backend"]
+        if backend_name == "dm0301":
+            from . import dm0301
+
+            try:
+                return dm0301.DM0301Backend(self.spec)
+            except (ImportError, DeviceNotFound):
+                if simulate is False:
+                    raise
+        elif simulate is False:
+            raise HardwareNotSupportedYet(
+                f"A real-hardware backend for {self.spec['name']} "
+                f"({self.spec['module']}) is not implemented yet — "
+                "the simulator supports it: Camera(..., simulate=True)."
+            )
+
+        if simulate is None:
+            warnings.warn(
+                f"No real {self.spec['name']} hardware found — using the "
+                "simulator. Pass simulate=True to silence this warning.",
+                stacklevel=3,
+            )
+        return SimulatorBackend(self.spec, seed=seed)
+
+    # -- core API --------------------------------------------------------------
+
+    @property
+    def source(self) -> str:
+        """'simulator' or the hardware backend name (e.g. 'dm0301')."""
+        return self._backend.source
+
+    def info(self) -> dict:
+        return {"device": self.device_id, "source": self.source, **self.spec}
+
+    def distance_m(self) -> float:
+        """Distance to the nearest object, in meters."""
+        return self._backend.distance_m()
+
+    def detect_people(self) -> dict:
+        """Detect people in view.
+
+        Returns ``{'people': int, 'nearest_m': float|None, 'positions': [...],
+        'source': str}``.
+        """
+        return self._backend.detect_people()
+
+    def depth_stats(self) -> dict:
+        """Aggregate depth statistics for the current view."""
+        return self._backend.depth_stats()
+
+    def stream(self, hz: float = 10.0, duration: float | None = None):
+        """Yield :class:`Frame` objects at ``hz`` until ``duration`` elapses.
+
+        With no ``duration`` the stream is endless — break out when done.
+        """
+        hz = min(max(hz, 0.1), float(self.spec["max_hz"]))
+        period = 1.0 / hz
+        t0 = time.monotonic()
+        while True:
+            t = time.monotonic() - t0
+            if duration is not None and t >= duration:
+                return
+            d = self._backend.detect_people()
+            yield Frame(
+                people=d["people"],
+                nearest_m=d["nearest_m"],
+                positions=d["positions"],
+                t=round(t, 3),
+                source=d["source"],
+            )
+            time.sleep(period)
+
+    def readings(self, hz: float = 10.0, duration: float | None = None):
+        """Yield :class:`Reading` distance samples (1D convenience stream)."""
+        hz = min(max(hz, 0.1), float(self.spec["max_hz"]))
+        period = 1.0 / hz
+        t0 = time.monotonic()
+        while True:
+            t = time.monotonic() - t0
+            if duration is not None and t >= duration:
+                return
+            yield Reading(distance_m=self.distance_m(), t=round(t, 3), source=self.source)
+            time.sleep(period)
+
+    def close(self) -> None:
+        self._backend.close()
+
+    def __enter__(self) -> "Camera":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Camera({self.device_id!r}, source={self.source!r})"
+
+
+class Sensor(Camera):
+    """Alias of :class:`Camera` for 1D sensors — defaults to Spatial Mini."""
+
+    def __init__(self, device_id: str | None = "spatial-mini", **kwargs):
+        super().__init__(device_id, **kwargs)

spatialai-0.1.0/src/spatialai/catalog.py

@@ -0,0 +1,51 @@
+"""Catalog of VisionLibra devices known to the SDK."""
+
+from __future__ import annotations
+
+DEVICES = {
+    "spatial-mini": {
+        "name": "Spatial Mini",
+        "module": "DM0301",
+        "kind": "1d-tof",
+        "range_m": (0.02, 5.0),
+        "fov_deg": (25.0, 25.0),
+        "max_hz": 50,
+        "resolution": (1, 1),
+        "hardware_backend": "dm0301",  # VL53L4CD-compatible over I2C
+    },
+    "spatial-home": {
+        "name": "Spatial Home",
+        "module": "DMOS5030A/5031A",
+        "kind": "3d-tof-aio",
+        "range_m": (0.2, 2.5),
+        "fov_deg": (60.0, 60.0),
+        "max_hz": 20,
+        "resolution": (100, 100),
+        "hardware_backend": None,  # serial protocol backend planned
+    },
+    "spatial-vision": {
+        "name": "Spatial Vision",
+        "module": "DMOM2508CL",
+        "kind": "3d-tof-camera",
+        "range_m": (0.2, 2.0),
+        "fov_deg": (71.8, 56.6),
+        "max_hz": 30,
+        "resolution": (320, 240),
+        "hardware_backend": None,  # USB/MIPI backend planned
+    },
+    "spatial-robot": {
+        "name": "Spatial Robot",
+        "module": "DMAS2M001",
+        "kind": "dtof-array",
+        "range_m": (0.2, 8.0),
+        "fov_deg": (60.0, 45.0),
+        "max_hz": 10,
+        "resolution": (40, 30),
+        "hardware_backend": None,  # dToF array backend planned
+    },
+}
+
+
+def devices() -> dict:
+    """Return the catalog of supported VisionLibra devices."""
+    return {k: dict(v) for k, v in DEVICES.items()}

spatialai-0.1.0/src/spatialai/cli.py

@@ -0,0 +1,79 @@
+"""spatialai command-line interface: `spatialai demo`, `spatialai scan`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import warnings
+
+from . import __version__
+from .camera import Camera
+from .catalog import DEVICES
+
+
+def _cmd_demo(args: argparse.Namespace) -> int:
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        cam = Camera(args.device, simulate=None if args.hardware else True)
+    print(f"SpatialAI {__version__} — {cam.spec['name']} ({cam.spec['module']}), source: {cam.source}")
+    print("Streaming people detection — Ctrl-C to stop.\n")
+    try:
+        for frame in cam.stream(hz=args.hz, duration=args.duration):
+            bar = "#" * frame.people
+            nearest = f"{frame.nearest_m:.2f} m" if frame.nearest_m is not None else "—"
+            print(f"  t={frame.t:6.2f}s  people={frame.people:<2d} {bar:<4s} nearest={nearest}")
+    except KeyboardInterrupt:
+        pass
+    finally:
+        cam.close()
+    return 0
+
+
+def _cmd_scan(_args: argparse.Namespace) -> int:
+    from . import dm0301
+
+    print(f"SpatialAI {__version__} — scanning for hardware…")
+    found = dm0301.probe()
+    if found:
+        print("  ✓ spatial-mini (DM0301 / VL53L4CD-compatible) at I2C 0x29")
+        return 0
+    print("  no supported hardware found (is I2C enabled? is spatialai[dm0301] installed?)")
+    print("  the simulator is always available:  spatialai demo")
+    return 1
+
+
+def _cmd_devices(_args: argparse.Namespace) -> int:
+    for key, spec in DEVICES.items():
+        lo, hi = spec["range_m"]
+        hw = spec["hardware_backend"] or "simulator only (hw backend planned)"
+        print(f"  {key:<16s} {spec['module']:<16s} {lo}–{hi} m   backend: {hw}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="spatialai", description="SpatialAI SDK CLI")
+    parser.add_argument("--version", action="version", version=f"spatialai {__version__}")
+    sub = parser.add_subparsers(dest="cmd")
+
+    p_demo = sub.add_parser("demo", help="live people-detection demo (simulator by default)")
+    p_demo.add_argument("--device", default="spatial-vision", choices=sorted(DEVICES))
+    p_demo.add_argument("--hz", type=float, default=5.0)
+    p_demo.add_argument("--duration", type=float, default=None)
+    p_demo.add_argument("--hardware", action="store_true", help="prefer real hardware if present")
+    p_demo.set_defaults(func=_cmd_demo)
+
+    p_scan = sub.add_parser("scan", help="look for real VisionLibra hardware")
+    p_scan.set_defaults(func=_cmd_scan)
+
+    p_dev = sub.add_parser("devices", help="list supported devices")
+    p_dev.set_defaults(func=_cmd_devices)
+
+    args = parser.parse_args(argv)
+    if not args.cmd:
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

spatialai-0.1.0/src/spatialai/dm0301.py

@@ -0,0 +1,104 @@
+"""Real-hardware backend for Spatial Mini (DM0301).
+
+The DM0301 is pin-to-pin compatible with the ST VL53L4CD, so this backend
+drives it through the well-tested Adafruit driver stack
+(``adafruit-circuitpython-vl53l4cd`` + Blinka). Install with::
+
+    pip install "spatialai[dm0301]"
+
+Wiring on a Raspberry Pi: VIN->3V3, GND->GND, SDA->GPIO2, SCL->GPIO3.
+Default I2C address: 0x29.
+"""
+
+from __future__ import annotations
+
+from .exceptions import DeviceNotFound
+
+I2C_ADDRESS = 0x29
+
+
+def _import_driver():
+    try:
+        import adafruit_vl53l4cd  # type: ignore
+        import board  # type: ignore
+        import busio  # type: ignore
+    except ImportError as exc:
+        raise ImportError(
+            "Hardware support for Spatial Mini (DM0301) needs the optional "
+            "drivers. Install them with:  pip install 'spatialai[dm0301]'"
+        ) from exc
+    return adafruit_vl53l4cd, board, busio
+
+
+def probe() -> bool:
+    """Return True if a DM0301/VL53L4CD responds on the I2C bus."""
+    try:
+        adafruit_vl53l4cd, board, busio = _import_driver()
+    except ImportError:
+        return False
+    try:
+        i2c = busio.I2C(board.SCL, board.SDA)
+        sensor = adafruit_vl53l4cd.VL53L4CD(i2c, address=I2C_ADDRESS)
+        del sensor
+        return True
+    except Exception:
+        return False
+
+
+class DM0301Backend:
+    """1D ToF ranging via the VL53L4CD-compatible register interface."""
+
+    source = "dm0301"
+
+    def __init__(self, spec: dict):
+        adafruit_vl53l4cd, board, busio = _import_driver()
+        self.spec = spec
+        try:
+            self._i2c = busio.I2C(board.SCL, board.SDA)
+            self._sensor = adafruit_vl53l4cd.VL53L4CD(self._i2c, address=I2C_ADDRESS)
+        except Exception as exc:
+            raise DeviceNotFound(
+                f"No DM0301/VL53L4CD found at I2C address {hex(I2C_ADDRESS)}. "
+                "Check wiring (SDA/SCL/3V3/GND) and that I2C is enabled "
+                "(`sudo raspi-config` on Raspberry Pi)."
+            ) from exc
+        # 20 Hz continuous ranging: 33ms timing budget, no inter-measurement gap.
+        self._sensor.timing_budget = 33
+        self._sensor.inter_measurement = 0
+        self._sensor.start_ranging()
+
+    def close(self) -> None:
+        try:
+            self._sensor.stop_ranging()
+        except Exception:
+            pass
+
+    def distance_m(self) -> float:
+        s = self._sensor
+        while not s.data_ready:
+            pass
+        s.clear_interrupt()
+        return round(s.distance / 100.0, 4)  # driver reports centimeters
+
+    def detect_people(self) -> dict:
+        """Map near-field presence onto the people-detection schema (0/1)."""
+        d = self.distance_m()
+        near, far = self.spec["range_m"]
+        # Heuristic: anything clearly nearer than the ambient background
+        # counts as a presence. 1D sensor => at most one "person".
+        present = d < min(1.2, far * 0.5)
+        return {
+            "people": 1 if present else 0,
+            "nearest_m": d if present else None,
+            "positions": [{"distance_m": d, "x": 0.0}] if present else [],
+            "source": self.source,
+        }
+
+    def depth_stats(self) -> dict:
+        d = self.distance_m()
+        return {
+            "min_m": d,
+            "max_m": d,
+            "resolution": self.spec["resolution"],
+            "fov_deg": self.spec["fov_deg"],
+        }

spatialai-0.1.0/src/spatialai/exceptions.py

@@ -0,0 +1,17 @@
+"""SpatialAI exceptions."""
+
+
+class SpatialAIError(Exception):
+    """Base class for all SpatialAI errors."""
+
+
+class DeviceNotFound(SpatialAIError):
+    """No matching device was found (and simulation was explicitly disabled)."""
+
+
+class HardwareNotSupportedYet(SpatialAIError):
+    """A real-hardware backend for this product is not implemented yet.
+
+    The simulator supports every product; pass ``simulate=True`` (or omit
+    ``simulate``) to use it.
+    """

spatialai-0.1.0/src/spatialai/simulator.py

@@ -0,0 +1,120 @@
+"""Deterministic-feel simulator backends.
+
+Generates plausible distance readings and people-detection frames so the SDK
+works on any machine with no hardware attached. Scenes are lightweight random
+walks: people wander in and out of view, distances drift smoothly.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+
+
+class SimulatedScene:
+    """A tiny world model shared by the simulator backends.
+
+    Tracks up to ``max_people`` people, each with a distance that drifts
+    smoothly between ``near`` and ``far``. People enter and leave the scene
+    with small per-tick probabilities, so streams look alive.
+    """
+
+    def __init__(self, near: float, far: float, max_people: int = 4, seed: int | None = None):
+        self.near = near
+        self.far = far
+        self.max_people = max_people
+        self._rng = random.Random(seed)
+        self._people: list[dict] = []
+        # Start with 0-2 people so first frames vary.
+        for _ in range(self._rng.randint(0, min(2, max_people))):
+            self._spawn()
+
+    def _spawn(self) -> None:
+        span = self.far - self.near
+        self._people.append({
+            "d": self.near + self._rng.uniform(0.25, 0.9) * span,
+            "x": self._rng.uniform(-0.8, 0.8),   # normalized horizontal position
+            "v": self._rng.uniform(-0.12, 0.12), # m per tick drift
+        })
+
+    def tick(self) -> None:
+        rng = self._rng
+        if len(self._people) < self.max_people and rng.random() < 0.06:
+            self._spawn()
+        if self._people and rng.random() < 0.04:
+            self._people.pop(rng.randrange(len(self._people)))
+        span = self.far - self.near
+        for p in self._people:
+            p["v"] += rng.uniform(-0.03, 0.03)
+            p["v"] = max(-0.15, min(0.15, p["v"]))
+            p["d"] += p["v"]
+            p["x"] += rng.uniform(-0.05, 0.05)
+            p["x"] = max(-1.0, min(1.0, p["x"]))
+            if p["d"] < self.near + 0.05 * span or p["d"] > self.far - 0.02 * span:
+                p["v"] = -p["v"]
+                p["d"] = max(self.near + 0.05 * span, min(p["d"], self.far - 0.02 * span))
+
+    # -- queries ------------------------------------------------------------
+
+    def people(self) -> list[dict]:
+        return [
+            {"distance_m": round(p["d"], 3), "x": round(p["x"], 3)}
+            for p in sorted(self._people, key=lambda p: p["d"])
+        ]
+
+    def nearest_m(self) -> float | None:
+        if not self._people:
+            return None
+        return round(min(p["d"] for p in self._people), 3)
+
+    def ambient_m(self) -> float:
+        """Distance to the static background (wall), with mm-level noise."""
+        wall = self.far * 0.92
+        return round(wall + self._rng.gauss(0.0, 0.004), 3)
+
+
+class SimulatorBackend:
+    """Backend driving a :class:`SimulatedScene` for one device."""
+
+    source = "simulator"
+
+    def __init__(self, spec: dict, seed: int | None = None):
+        self.spec = spec
+        near, far = spec["range_m"]
+        max_people = 1 if spec["kind"] == "1d-tof" else 4
+        self.scene = SimulatedScene(near, far, max_people=max_people, seed=seed)
+        self._t0 = time.monotonic()
+
+    def close(self) -> None:  # symmetry with hardware backends
+        pass
+
+    def distance_m(self) -> float:
+        """Nearest object distance (person if present, else background)."""
+        self.scene.tick()
+        nearest = self.scene.nearest_m()
+        if nearest is None:
+            return min(self.scene.ambient_m(), self.spec["range_m"][1])
+        return nearest
+
+    def detect_people(self) -> dict:
+        self.scene.tick()
+        people = self.scene.people()
+        return {
+            "people": len(people),
+            "nearest_m": self.scene.nearest_m(),
+            "positions": people,
+            "source": self.source,
+        }
+
+    def depth_stats(self) -> dict:
+        """Aggregate depth statistics, stand-in for a full depth frame."""
+        self.scene.tick()
+        near, far = self.spec["range_m"]
+        nearest = self.scene.nearest_m()
+        return {
+            "min_m": nearest if nearest is not None else round(far * 0.9, 3),
+            "max_m": round(far * 0.97, 3),
+            "resolution": self.spec["resolution"],
+            "fov_deg": self.spec["fov_deg"],
+        }

spatialai-0.1.0/src/spatialai.egg-info/PKG-INFO

@@ -0,0 +1,122 @@
+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

spatialai-0.1.0/src/spatialai.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/spatialai/__init__.py
+src/spatialai/camera.py
+src/spatialai/catalog.py
+src/spatialai/cli.py
+src/spatialai/dm0301.py
+src/spatialai/exceptions.py
+src/spatialai/simulator.py
+src/spatialai.egg-info/PKG-INFO
+src/spatialai.egg-info/SOURCES.txt
+src/spatialai.egg-info/dependency_links.txt
+src/spatialai.egg-info/entry_points.txt
+src/spatialai.egg-info/requires.txt
+src/spatialai.egg-info/top_level.txt
+tests/test_simulator.py

spatialai-0.1.0/src/spatialai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

spatialai-0.1.0/src/spatialai.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spatialai = spatialai.cli:main

spatialai-0.1.0/src/spatialai.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[dev]
+pytest>=7
+
+[dm0301]
+adafruit-circuitpython-vl53l4cd>=1.1
+adafruit-blinka>=8.0

spatialai-0.1.0/src/spatialai.egg-info/top_level.txt

@@ -0,0 +1 @@
+spatialai

spatialai-0.1.0/tests/test_simulator.py

@@ -0,0 +1,59 @@
+import warnings
+
+import pytest
+
+from spatialai import Camera, Sensor, DeviceNotFound, devices
+
+
+def test_detect_people_schema():
+    cam = Camera("spatial-vision", simulate=True, seed=42)
+    r = cam.detect_people()
+    assert set(r) == {"people", "nearest_m", "positions", "source"}
+    assert r["source"] == "simulator"
+    assert r["people"] == len(r["positions"])
+    if r["people"]:
+        assert r["nearest_m"] == r["positions"][0]["distance_m"]
+
+
+def test_distance_within_device_range():
+    for device_id, spec in devices().items():
+        cam = Camera(device_id, simulate=True, seed=1)
+        lo, hi = spec["range_m"]
+        for _ in range(50):
+            d = cam.distance_m()
+            assert lo <= d <= hi + 1e-6, f"{device_id}: {d} outside [{lo}, {hi}]"
+
+
+def test_stream_respects_duration_and_hz():
+    cam = Camera("spatial-robot", simulate=True, seed=7)
+    frames = list(cam.stream(hz=50, duration=0.5))
+    # capped at the device's 10 Hz -> ~5 frames in 0.5s
+    assert 2 <= len(frames) <= 8
+    assert all(f.source == "simulator" for f in frames)
+
+
+def test_sensor_defaults_to_spatial_mini():
+    s = Sensor(simulate=True, seed=3)
+    assert s.device_id == "spatial-mini"
+    r = s.detect_people()
+    assert r["people"] in (0, 1)  # 1D sensor sees at most one person
+
+
+def test_unknown_device_raises():
+    with pytest.raises(DeviceNotFound):
+        Camera("spatial-nope", simulate=True)
+
+
+def test_autodetect_falls_back_to_simulator_with_warning():
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        cam = Camera()  # no hardware in CI
+        assert cam.source == "simulator"
+        assert any("simulator" in str(x.message) for x in w)
+
+
+def test_context_manager_and_repr():
+    with Camera("spatial-home", simulate=True) as cam:
+        assert "spatial-home" in repr(cam)
+        stats = cam.depth_stats()
+        assert stats["resolution"] == (100, 100)