Metadata-Version: 2.4
Name: dosync
Version: 0.4.1
Summary: The semantic layer between AI agents and physical devices
Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
License-Expression: Apache-2.0
Project-URL: Homepage, https://dosync.dev
Project-URL: Repository, https://github.com/giulianireg-spec/dosync-protocol
Project-URL: Specification, https://github.com/giulianireg-spec/dosync-protocol/blob/main/spec/DoSync-SPEC-v0.1.md
Project-URL: Issues, https://github.com/giulianireg-spec/dosync-protocol/issues
Keywords: iot,ai-agents,protocol,semantic,orchestration,audit,governance,mcp,home-automation,robotics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1.0,>=0.115.0
Requires-Dist: uvicorn<1.0,>=0.23.0
Requires-Dist: pydantic<3.0,>=2.7.0
Requires-Dist: jsonschema<5.0,>=4.18
Provides-Extra: wiz
Requires-Dist: pywizlight>=0.5.0; extra == "wiz"
Provides-Extra: mqtt
Requires-Dist: paho-mqtt>=2.0.0; extra == "mqtt"
Provides-Extra: ha
Requires-Dist: aiohttp>=3.8.0; extra == "ha"
Provides-Extra: ble
Requires-Dist: bleak>=0.21; extra == "ble"
Provides-Extra: sms
Requires-Dist: twilio>=8.0.0; extra == "sms"
Provides-Extra: mavlink
Requires-Dist: pymavlink>=2.4.0; extra == "mavlink"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: pywizlight>=0.5.0; extra == "all"
Requires-Dist: paho-mqtt>=2.0.0; extra == "all"
Requires-Dist: aiohttp>=3.8.0; extra == "all"
Requires-Dist: bleak>=0.21; extra == "all"
Requires-Dist: twilio>=8.0.0; extra == "all"
Requires-Dist: pymavlink>=2.4.0; extra == "all"
Requires-Dist: mcp>=1.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

# DoSync Protocol

> The semantic layer between AI agents and physical devices.

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Protocol](https://img.shields.io/badge/protocol-v0.4-green.svg)](spec/DoSync-SPEC-v0.1.md)
[![PyPI](https://img.shields.io/pypi/v/dosync.svg)](https://pypi.org/project/dosync/)
[![Python](https://img.shields.io/pypi/pyversions/dosync.svg)](https://pypi.org/project/dosync/)
[![CI](https://github.com/giulianireg-spec/dosync-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/giulianireg-spec/dosync-protocol/actions/workflows/ci.yml)
[![Certification](https://img.shields.io/badge/certification-Conformance%2052%2F52-orange.svg)](dosync/certify.py)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](dosync/mcp_server.py)

---

## The problem

Today's IoT protocols speak the language of commands. AI speaks the language of goals.

```python
# Existing protocols
lock.unlock()
light.set_brightness(100)
thermostat.set_temperature(21)

# What an AI actually expresses
"there is an emergency at home"
"nobody is home — save energy"
"good morning"
```

Someone has to translate. Today, that translation is custom code written per-device, per-platform, per-scenario. It breaks when you add a new device. It completely fails in emergencies where milliseconds matter.

**DoSync is the bridge.**

---

## What it does

DoSync is an open protocol (Apache 2.0) that lets AI systems interact with physical devices using **semantic intent** — expressing *what they want to achieve*, not *how to achieve it*.

When the hub receives `"ensure_safety / emergency"`, every registered device figures out its own role automatically based on its declared capabilities — no hardcoded rules, no manual configuration.

---

## Scope and safety boundaries

DoSync coordinates **non-safety-critical systems** — lighting, access, climate, notifications, logging — and produces a tamper-evident record of every action. It is infrastructure for coordination and auditability, not a certified safety system.

DoSync is **not** certified to IEC 61508 / IEC 62304 / ISO 13849 and must not be the sole or primary mechanism for:

- Primary control of medical devices or life-support systems
- Fire suppression, gas detection, or emergency shutdown of SIL-rated machinery
- Any function where a failure could cause injury or loss of life

In regulated or industrial environments, DoSync **complements** the certified safety systems already in place — coordinating the peripherals around them and recording what happened — but never replaces them. The certified safety system remains in charge of safety.

See [Protocol Specification §12.3](spec/DoSync-SPEC-v0.1.md) for the full operational boundaries.

---

## Is DoSync for you?

DoSync earns its place in specific situations — and honestly gets in the way in others. A quick filter:

**It probably fits if you:**
- Are building an **AI agent that acts on physical devices** and need an auditable record of what it did, when, and why.
- Coordinate **heterogeneous devices** (different brands / transports) and want one semantic layer — express a goal, devices resolve it — with a tamper-evident audit trail.
- Work in **robotics or physical automation** and want a policy + safety layer (emergency preemption, confirmation policies) *between* the AI and the actuators.
- Keep hand-writing per-device command sequences and wish you could just say *"secure the space."*

**It's probably not for you if you:**
- Want home automation (schedules, motion → light). [Home Assistant](https://www.home-assistant.io/) and its automations — and its MCP server — already do that better; DoSync would be overhead.
- Have a single device or one brand's ecosystem — you don't need a coordination layer.
- Don't need auditability or a policy layer.

**If the first list is you:** the fastest way in is the **[20-minute device tutorial](TUTORIAL.md)** — build a device that senses, expresses a goal, and acts, with the full audit trail. Or open an [issue](https://github.com/giulianireg-spec/dosync-protocol/issues) describing what you're trying to coordinate and we'll tell you honestly whether DoSync fits.

---

## Demo

[![DoSync Demo](https://img.shields.io/badge/▶_Watch_Demo-YouTube-red?style=for-the-badge)](https://youtu.be/2czAqoIrd08)

**What you'll see:** Claude AI triggers a physical emergency protocol in real time — 10 Philips WiZ bulbs at full brightness, SMS notification sent, audit log updated. No commands. No rules. No cloud.

---

## How it works

```
User / AI says:  "there is an emergency at home"
                          │
                    DoSync Hub v0.3.0
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   💡 All lights      📱 SMS sent     🚨 Alarm
   at maximum       to family        activated
   (10 WiZ bulbs)   immediately
          │               │               │
          └───────────────┴───────────────┘
                          │
                  Audit log updated
              (SHA-256 tamper-evident)
```

The **Capability-based Resolver** matches the intent against every device's **Capability Manifest** — what it can sense, what it can do, whether it's emergency-capable. No rules to write. Add a new device and it participates automatically.

Benchmark (Raspberry Pi 5, Python 3.11.2):

| Devices | Mean | p99 | Within 500ms limit |
|---|---|---|---|
| 38 (production) | 0.076ms | 0.097ms | ✓ |
| 1000 | 1.336ms | 5.690ms | ✓ |
| 5000 | 9.163ms | 24.541ms | ✓ (20× margin) |

---

## Protocol architecture

| Layer | Name | Role |
|---|---|---|
| 5 | **Intent** | AI expresses semantic goals |
| 4 | **Semantic** | Resolver maps intent → device actions |
| 3 | **Registry** | Devices self-declare capabilities on join |
| 2 | **Secure channel** | mTLS, local PKI — no internet required |
| 1 | **Transport (HAL)** | Reference: WiFi/HTTP-WS · MQTT. Via bridge: Zigbee · Z-Wave · Thread · Matter (Home Assistant). Native BLE/radio bindings: roadmap |

---

## Quick start

### Install and run — five minutes, no hardware

```bash
pip install dosync
dosync-hub
```

That is a working hub on `http://127.0.0.1:47200`. It starts with a simulated
executor, so you can drive the whole protocol — register devices, fire intents,
read the audit chain — before you own a single smart device.

Register something and give it a goal:

```bash
# 1. A device declares what it CAN DO (not what commands it takes)
curl -X POST http://127.0.0.1:47200/v1/devices/register \
  -H 'Content-Type: application/json' -d '{
    "device_id": "siren-hall", "device_name": "Hall Siren",
    "manufacturer": "acme", "model": "S1", "firmware": "1.0",
    "category": "actuator", "tags": ["alarm", "emergency"],
    "emergency_capable": true, "cert_tier": "basic",
    "sensors": [], "actuators": [{"id": "alarm", "type": "alarm",
                                  "description": "audible alarm"}]}'

# 2. An AI expresses a GOAL — not a command, and it names no device
curl -X POST http://127.0.0.1:47200/v1/intent/async \
  -H 'Content-Type: application/json' \
  -d '{"intent": "ensure_safety", "urgency": "emergency", "context": {}}'

# 3. Ask WHY those devices were chosen
curl http://127.0.0.1:47200/v1/intents/ensure_safety/explain

# 4. Read the tamper-evident record of what happened
curl http://127.0.0.1:47200/v1/audit?limit=10
```

Step 3 is the one worth pausing on: the hub tells you which devices it
evaluated, which it included, and the score breakdown behind each decision.
Step 4 is the other: every action leaves a SHA-256-chained entry, so what the
system did is provable after the fact rather than merely logged.

Install only the adapters you need:

```bash
pip install 'dosync[wiz]'      # Philips WiZ bulbs
pip install 'dosync[ha]'       # Home Assistant bridge
pip install 'dosync[mqtt]'     # MQTT devices
pip install 'dosync[all]'      # everything
```

### Docker

```bash
docker run -p 47200:47200 dosync/hub        # published image
# or, from a clone:
docker compose up
```

### From source (development)

```bash
git clone https://github.com/giulianireg-spec/dosync-protocol
cd dosync-protocol
python3 -m venv venv && source venv/bin/activate
pip install -e '.[dev]'
pytest                                  # 667 tests
dosync-hub --reload
```

---

## What's built today

| Component | Status |
|---|---|
| REST API (12+ endpoints) | ✅ |
| WebSocket real-time events | ✅ |
| Web dashboard | ✅ |
| API key authentication + SHA-256 audit log | ✅ |
| Capability-based resolver | ✅ |
| Certification CLI — Standard 33/33 · Emergency 44/44 (signed reports) | ✅ |
| Philips WiZ adapter (UDP local) | ✅ |
| Home Assistant bridge (10 domains) | ✅ |
| Native MCP server (Claude, ChatGPT, any LLM) | ✅ |
| GPIO adapter — Raspberry Pi 5 (PIR + DHT22) | ✅ |
| SMS notifications via Twilio | ✅ code (requires an active Twilio plan) |
| MQTT transport adapter (Mosquitto) | ✅ |
| Shelly adapter (HTTP local, Gen1 + Gen2) | ✅ code, not hardware-tested |
| Matter adapter (via HA bridge / python-matter-server) | ✅ code, not hardware-tested |
| External Resolver Protocol (HTTP wire format) | ✅ |
| SQLite persistence (survives restarts) | ✅ |
| CI pipeline (GitHub Actions) | ✅ |
| Multi-hub assisted failover (Phase A — operator-in-the-loop) | ✅ |
| Long-running operations + telemetry reconciliation (state machine) | ✅ |
| Drone / MAVLink adapter — full AI→intent→mission loop in ArduPilot SITL | ✅ software (physical flight pending) |

---

## MQTT transport

DoSync supports MQTT as a Layer 1 transport for devices that can't use HTTP. Requires Mosquitto and proper authentication. See [config/mosquitto-secure.conf](config/mosquitto-secure.conf) for secure setup.

```bash
# Enable MQTT in the hub service
Environment="DOSYNC_MQTT_BROKER=localhost"
Environment="DOSYNC_MQTT_USER=dosync-hub"
Environment="DOSYNC_MQTT_PASSWORD=<password>"
Environment="DOSYNC_MQTT_SECRET=<registration-secret>"
```

---

## Certification

Self-certifiable with the CLI:

```bash
python3 certify.py --host <hub-ip> --port 47200 --tier standard
# Output: dosync-cert-standard-*.json
```

| Tier | Tests | What it validates |
|---|---|---|
| **Basic** | 10 | Connectivity, auth, device manifest |
| **Standard** | 33 | Protocol conformance, events, health, version headers |
| **Emergency** | 44 | Everything in Standard + emergency override, policy engine, audit log integrity |

---

## Implementations

| Language | Location | Author | Certification |
|---|---|---|---|
| Python (reference) | `server.py` | this project | Standard 33/33 · Emergency 44/44 ✅ |
| Node.js (companion) | [giulianireg-spec/dosync-node](https://github.com/giulianireg-spec/dosync-node) | this project | 33/33 Standard ✅ |

The Node.js implementation is a **companion** port that validates the protocol
is implementable in a second language against the same certification suite —
both share the same author. A genuinely **independent** implementation
(different author or organization) is a tracked milestone for v1.0: a protocol
needs multiple independent implementations to become a standard. See the
[roadmap](ROADMAP.md).

---

## Works with Home Assistant — a layer on top, not a replacement

Home Assistant already solved the hardest problem: talking to thousands of devices, and since 2025 it ships an MCP server so an AI can control them directly. DoSync doesn't reinvent that — it reads devices from HA through a bridge already in the repo and adds **one thing**: it turns a semantic goal (`ensure_safety`, `away_mode`) into a coordinated, **auditable** set of actions across *any* source (HA, WiZ, GPIO, MQTT, BLE).

The honest version: for everyday automation ("porch light when I get home") you **don't need DoSync** — HA's automations and its MCP cover that completely. DoSync earns its place only when **coordination and traceability matter at once** — e.g. a fall-response that unlocks the door, lights the house, and messages family, with a tamper-evident record of exactly what fired and when. Full reasoning: [Home Assistant Already Talks to Your Devices. So What Would DoSync Add?](https://dev.to/giulianiregspec/home-assistant-already-talks-to-your-devices-so-what-would-dosync-add-1iei)

---

## Beyond the home

Nothing in DoSync assumes a house — the same 5-layer stack coordinates physical systems anywhere an AI needs to act: retail cold-chain, hotels, factory peripherals (alongside certified safety systems, never replacing them).

The proof: we took it to the hardest device, an **autonomous drone**. From a single plain-language sentence, an AI model (Claude Haiku, via DoSync's MCP server) fired an `inspect_area` intent and the drone flew the full mission in ArduPilot SITL — every step confirmed by real telemetry. When the AI guessed coordinates 11,000 km away, the supervisor didn't fake success: it waited for a confirmed arrival, none came, and it aborted with a clear diagnosis. **The AI can be wrong; the protocol doesn't have to be.** [Full build log](https://dev.to/giulianiregspec/i-gave-an-ai-one-sentence-a-drone-flew-the-mission-and-when-the-ai-guessed-wrong-the-system-2h3m) · *(validated in SITL; physical-hardware flight is the next step, not a claim made today.)*

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, including the CI pipeline that runs on every push.

---

## Specification

- [spec/DoSync-SPEC-v0.1.md](spec/DoSync-SPEC-v0.1.md) — full protocol specification
- [spec/RESOLVER-SPEC-v0.3.md](spec/RESOLVER-SPEC-v0.3.md) — resolver interface + external resolver protocol
- [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md) — architectural decisions and rationale
- [COMPATIBILITY.md](COMPATIBILITY.md) — backward compatibility guarantees

---

## License

Apache 2.0 — free to implement, free to extend, no royalties.

---

*DoSync Protocol v0.3.0 · © 2026 Rodrigo Giuliani · rgiuliani@dosync.dev*
