dosync 0.6.3__tar.gz → 0.7.0__tar.gz

{dosync-0.6.3 → dosync-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.6.3
+Version: 0.7.0
 Summary: The semantic layer between AI agents and physical devices
 Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
 License-Expression: Apache-2.0
@@ -8,7 +8,7 @@ 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
+Keywords: iot,ai-agents,protocol,semantic,orchestration,audit,governance,mcp,robotics,cyber-physical
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
@@ -17,7 +17,11 @@ 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
 Classifier: Topic :: Home Automation
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Hardware
 Classifier: Topic :: System :: Distributed Computing
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.10
@@ -45,7 +49,7 @@ 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<2.0,>=1.0.0; extra == "mcp"
+Requires-Dist: mcp<2.0,>=1.27.0; extra == "mcp"
 Provides-Extra: all
 Requires-Dist: pywizlight>=0.5.0; extra == "all"
 Requires-Dist: paho-mqtt>=2.0.0; extra == "all"
@@ -53,7 +57,7 @@ Requires-Dist: aiohttp>=3.9.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<2.0,>=1.0.0; extra == "all"
+Requires-Dist: mcp<2.0,>=1.27.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
@@ -65,7 +69,7 @@ Dynamic: license-file
 > Governance and accountability for AI that acts on 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)
+[![Protocol](https://img.shields.io/badge/protocol-v0.5-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)
@@ -209,15 +213,14 @@ DoSync earns its place in specific situations — and honestly gets in the way i
 ## How it works
 
 ```
-User / AI says:  "there is an emergency at home"
+User / AI says:  "there is a fire in building B"
                           │
                        DoSync Hub
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
-   💡 All lights      📱 SMS sent     🚨 Alarm
-   at maximum       to family        activated
-   (10 WiZ bulbs)   immediately
+   💡 Every light     📱 On-call staff  🚨 Alarm
+   at maximum         notified          activated
           │               │               │
           └───────────────┴───────────────┘
                           │
@@ -805,18 +808,50 @@ The server is a module rather than a command, and it needs the MCP SDK, which
 the hub does not install:
 
 ```bash
-pip install "mcp>=1.0.0,<2.0"       # or: pipx inject dosync "mcp>=1.0.0,<2.0"
+pip install "mcp>=1.27.0,<2.0"      # or: pipx inject dosync "mcp>=1.27.0,<2.0"
 python -m dosync.mcp_server
 ```
 
-The upper bound is not caution. The 2.x SDK changed how tools are registered
-and this server is written against 1.x; without the cap, a fresh install gets
-2.x and the server exits at import. It says so plainly if that happens.
+Both bounds are measured. The upper one: the 2.x SDK changed how tools are
+registered and this server is written against 1.x; without the cap, a fresh
+install gets 2.x and the server exits at import. It says so plainly if that
+happens. The lower one: the HTTP transport needs 1.27.0, and 1.27.0 in turn needs
+pydantic 2.11 and jsonschema 4.20 — so installing the MCP server raises those
+two floors above the hub's own. CI runs the whole suite on exactly those minimums.
 
 It speaks over stdin/stdout, so a successful start prints nothing and waits.
 Typing into that terminal will produce JSON parse errors — that is the protocol
 rejecting your keystrokes, not a fault.
 
+**When the agent is not on this machine**, stdio cannot help: it assumes the
+client can start the server as a subprocess, which means they share a filesystem.
+A hub in a container, on a Pi across the room, or under a supervisor is not that.
+Serve it over the network instead:
+
+```bash
+DOSYNC_MCP_TRANSPORT=http DOSYNC_TOKEN=<token> python -m dosync.mcp_server
+```
+
+It listens on `127.0.0.1:47210` by default; `DOSYNC_MCP_HOST` and
+`DOSYNC_MCP_PORT` change that. Clients connect to `/mcp`, and `/health` answers
+unauthenticated so a supervisor can check the process without holding a
+credential.
+
+**It will not start over HTTP without `DOSYNC_TOKEN`, deliberately.** Over stdio
+the operating system is the boundary — whoever can start the process is already
+on the machine. A port has none, and on a host network it is reachable by every
+device on the LAN. The tools behind it open locks and stop machines.
+
+**The token travels in clear text unless you put TLS in front of it.** That is
+true of the hub's own API too and is documented there, but it matters more here:
+this port executes tools rather than answering questions. On a trusted LAN it is
+a considered trade-off; across anything else, terminate TLS in front of it. Idle
+sessions are dropped after 15 minutes by default (`DOSYNC_MCP_SESSION_TIMEOUT`).
+
+The transport changes nothing else. Both serve the same tools from the same
+server object, and an agent reaching a device this way goes through the hub's
+REST API exactly as `curl` does — same policy engine, same audit chain.
+
 It reads three environment variables:
 
 | Variable | Meaning |
@@ -904,6 +939,11 @@ it said about the second group is the part worth reading:
 > Estos tres últimos están registrados pero sin tags ni acciones definidas — el
 > hub sabe que existen pero no puede actuar sobre ellos todavía.
 
+<sub>Quoted verbatim, in the language the model answered in. Translating it
+would misrepresent what was said, which is the point of quoting it.
+("These last three are registered but with no tags or actions defined — the hub
+knows they exist but cannot act on them yet.")</sub>
+
 It did not invent capabilities for devices that have none. That is not the
 model being careful: the hub reports an undeclared device as undeclared, so
 there was nothing to invent from. Then it offered to describe one — the drafting
@@ -921,11 +961,11 @@ the other end.
 | Web dashboard | ✅ |
 | API key authentication + SHA-256 audit log | ✅ |
 | Capability-based resolver | ✅ |
-| Certification CLI — Standard 33/33 · Emergency 44/44 (signed reports) | ✅ |
+| Certification CLI — Basic 10 · Standard 33 · Emergency 44 · Conformance 65, each run in CI against a live hub (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) | ✅ |
+| GPIO sensors on a Raspberry Pi 5 (PIR + DHT22), via deployment code over the API | ✅ reference deployment (not shipped) |
 | SMS notifications via Twilio | ✅ code (requires an active Twilio plan) |
 | MQTT transport adapter (Mosquitto) | ✅ |
 | Shelly adapter (HTTP local, Gen1 + Gen2) | ✅ code, not hardware-tested |
@@ -974,8 +1014,8 @@ python3 certify.py --host <hub-ip> --port 47200 --tier standard
 
 | 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 | Standard 33/33, against the v0.3 suite — re-validation against the current 56-test suite pending |
+| Python (reference) | `server.py` | this project | Conformance 65/65 ✅ (every tier, in CI) |
+| Node.js (companion) | [giulianireg-spec/dosync-node](https://github.com/giulianireg-spec/dosync-node) | this project | Standard 33/33, against the v0.3 suite — re-validation against the current 65-check suite pending |
 
 The Node.js implementation is a **companion** port that validates the protocol
 is implementable in a second language against the same certification suite —

{dosync-0.6.3 → dosync-0.7.0}/README.md

@@ -3,7 +3,7 @@
 > Governance and accountability for AI that acts on 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)
+[![Protocol](https://img.shields.io/badge/protocol-v0.5-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)
@@ -147,15 +147,14 @@ DoSync earns its place in specific situations — and honestly gets in the way i
 ## How it works
 
 ```
-User / AI says:  "there is an emergency at home"
+User / AI says:  "there is a fire in building B"
                           │
                        DoSync Hub
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
-   💡 All lights      📱 SMS sent     🚨 Alarm
-   at maximum       to family        activated
-   (10 WiZ bulbs)   immediately
+   💡 Every light     📱 On-call staff  🚨 Alarm
+   at maximum         notified          activated
           │               │               │
           └───────────────┴───────────────┘
                           │
@@ -743,18 +742,50 @@ The server is a module rather than a command, and it needs the MCP SDK, which
 the hub does not install:
 
 ```bash
-pip install "mcp>=1.0.0,<2.0"       # or: pipx inject dosync "mcp>=1.0.0,<2.0"
+pip install "mcp>=1.27.0,<2.0"      # or: pipx inject dosync "mcp>=1.27.0,<2.0"
 python -m dosync.mcp_server
 ```
 
-The upper bound is not caution. The 2.x SDK changed how tools are registered
-and this server is written against 1.x; without the cap, a fresh install gets
-2.x and the server exits at import. It says so plainly if that happens.
+Both bounds are measured. The upper one: the 2.x SDK changed how tools are
+registered and this server is written against 1.x; without the cap, a fresh
+install gets 2.x and the server exits at import. It says so plainly if that
+happens. The lower one: the HTTP transport needs 1.27.0, and 1.27.0 in turn needs
+pydantic 2.11 and jsonschema 4.20 — so installing the MCP server raises those
+two floors above the hub's own. CI runs the whole suite on exactly those minimums.
 
 It speaks over stdin/stdout, so a successful start prints nothing and waits.
 Typing into that terminal will produce JSON parse errors — that is the protocol
 rejecting your keystrokes, not a fault.
 
+**When the agent is not on this machine**, stdio cannot help: it assumes the
+client can start the server as a subprocess, which means they share a filesystem.
+A hub in a container, on a Pi across the room, or under a supervisor is not that.
+Serve it over the network instead:
+
+```bash
+DOSYNC_MCP_TRANSPORT=http DOSYNC_TOKEN=<token> python -m dosync.mcp_server
+```
+
+It listens on `127.0.0.1:47210` by default; `DOSYNC_MCP_HOST` and
+`DOSYNC_MCP_PORT` change that. Clients connect to `/mcp`, and `/health` answers
+unauthenticated so a supervisor can check the process without holding a
+credential.
+
+**It will not start over HTTP without `DOSYNC_TOKEN`, deliberately.** Over stdio
+the operating system is the boundary — whoever can start the process is already
+on the machine. A port has none, and on a host network it is reachable by every
+device on the LAN. The tools behind it open locks and stop machines.
+
+**The token travels in clear text unless you put TLS in front of it.** That is
+true of the hub's own API too and is documented there, but it matters more here:
+this port executes tools rather than answering questions. On a trusted LAN it is
+a considered trade-off; across anything else, terminate TLS in front of it. Idle
+sessions are dropped after 15 minutes by default (`DOSYNC_MCP_SESSION_TIMEOUT`).
+
+The transport changes nothing else. Both serve the same tools from the same
+server object, and an agent reaching a device this way goes through the hub's
+REST API exactly as `curl` does — same policy engine, same audit chain.
+
 It reads three environment variables:
 
 | Variable | Meaning |
@@ -842,6 +873,11 @@ it said about the second group is the part worth reading:
 > Estos tres últimos están registrados pero sin tags ni acciones definidas — el
 > hub sabe que existen pero no puede actuar sobre ellos todavía.
 
+<sub>Quoted verbatim, in the language the model answered in. Translating it
+would misrepresent what was said, which is the point of quoting it.
+("These last three are registered but with no tags or actions defined — the hub
+knows they exist but cannot act on them yet.")</sub>
+
 It did not invent capabilities for devices that have none. That is not the
 model being careful: the hub reports an undeclared device as undeclared, so
 there was nothing to invent from. Then it offered to describe one — the drafting
@@ -859,11 +895,11 @@ the other end.
 | Web dashboard | ✅ |
 | API key authentication + SHA-256 audit log | ✅ |
 | Capability-based resolver | ✅ |
-| Certification CLI — Standard 33/33 · Emergency 44/44 (signed reports) | ✅ |
+| Certification CLI — Basic 10 · Standard 33 · Emergency 44 · Conformance 65, each run in CI against a live hub (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) | ✅ |
+| GPIO sensors on a Raspberry Pi 5 (PIR + DHT22), via deployment code over the API | ✅ reference deployment (not shipped) |
 | SMS notifications via Twilio | ✅ code (requires an active Twilio plan) |
 | MQTT transport adapter (Mosquitto) | ✅ |
 | Shelly adapter (HTTP local, Gen1 + Gen2) | ✅ code, not hardware-tested |
@@ -912,8 +948,8 @@ python3 certify.py --host <hub-ip> --port 47200 --tier standard
 
 | 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 | Standard 33/33, against the v0.3 suite — re-validation against the current 56-test suite pending |
+| Python (reference) | `server.py` | this project | Conformance 65/65 ✅ (every tier, in CI) |
+| Node.js (companion) | [giulianireg-spec/dosync-node](https://github.com/giulianireg-spec/dosync-node) | this project | Standard 33/33, against the v0.3 suite — re-validation against the current 65-check suite pending |
 
 The Node.js implementation is a **companion** port that validates the protocol
 is implementable in a second language against the same certification suite —

{dosync-0.6.3 → dosync-0.7.0}/dosync/__init__.py

@@ -13,5 +13,5 @@ The two numbers move independently on purpose:
   __version__           this implementation of the hub  (semver)
   __protocol_version__  the wire contract other implementations must match
 """
-__version__ = "0.6.3"
-__protocol_version__ = "0.4"
+__version__ = "0.7.0"
+__protocol_version__ = "0.5"

{dosync-0.6.3 → dosync-0.7.0}/dosync/adapter_drafting.py

@@ -79,8 +79,13 @@ def _tag_vocabulary(repo_root: Path) -> str:
     the universal intent resolves on `lock`. A model left to guess would
     reproduce that on every device it describes.
     """
-    for candidate in (repo_root / "spec" / "TAG-VOCABULARY.md",
-                      Path(__file__).parent.parent / "spec" / "TAG-VOCABULARY.md"):
+    # The package's own copy first: it is what a `pip install` has. Until 0.7.0
+    # the wheel carried no copy, both paths below were missing in every
+    # installed hub, and the prompt told the model the vocabulary was
+    # unavailable. tests/test_tag_vocabulary.py keeps the copy identical to
+    # spec/TAG-VOCABULARY.md.
+    for candidate in (Path(__file__).parent / "spec" / "TAG-VOCABULARY.md",
+                      repo_root / "spec" / "TAG-VOCABULARY.md"):
         if not candidate.exists():
             continue
         text = candidate.read_text(encoding="utf-8")

{dosync-0.6.3 → dosync-0.7.0}/dosync/adapters/__init__.py

@@ -52,14 +52,14 @@ class DoSyncAdapter(ABC):
     """
     Base interface for physical device adapters.
 
-    Cada adapter traduce acciones DoSync al protocolo nativo
-    del dispositivo (UDP, HTTP, GPIO, BLE, etc.).
+    Each adapter translates DoSync actions into the device's native protocol
+    (UDP, HTTP, BLE, etc.).
 
     To implement a new adapter:
 
         class MyBrandAdapter(DoSyncAdapter):
             async def execute(self, action, urgency):
-                # traducir action.action + action.params al protocolo del dispositivo
+                # translate action.action + action.params into the device's protocol
                 return ActionResult(
                     device_id=action.device_id,
                     action=action.action,
@@ -174,16 +174,16 @@ class DoSyncAdapter(ABC):
         ...
 
 
-# ── AdapterExecutor — el ejecutor central ────────────────────────────────────
+# ── AdapterExecutor — the central executor ────────────────────────────────────
 
 class AdapterExecutor:
     """
-    Ejecutor central que delega acciones al adapter correcto
+    Central executor that delegates each action to the right adapter
     based on the 'adapter' field of the device's CapabilityManifest.
 
     A device with no registered adapter falls back to the SimulatedExecutor.
 
-    Uso:
+    Usage:
         executor = AdapterExecutor(hub)
         executor.register(WiZAdapter())
         executor.register(GPIOAdapter())
@@ -195,9 +195,9 @@ class AdapterExecutor:
     def __init__(self, hub, fallback_to_simulated: bool = True):
         """
         Args:
-            hub: instancia de DoSyncHub
-            fallback_to_simulated: si True, dispositivos sin adapter
-                                   usan SimulatedExecutor en lugar de fallar
+            hub: the DoSyncHub instance
+            fallback_to_simulated: if True, devices with no adapter
+                                   use SimulatedExecutor instead of failing
         """
         self._hub = hub
         self._adapters: dict[str, DoSyncAdapter] = {}
@@ -220,7 +220,7 @@ class AdapterExecutor:
 
 
     def registered_adapters(self) -> list[str]:
-        """Lista de adapters registrados."""
+        """Names of the registered adapters."""
         return list(self._adapters.keys())
 
     async def execute(self, action: DeviceAction, urgency: Urgency) -> ActionResult:
@@ -269,8 +269,8 @@ class AdapterExecutor:
                 result = await self._adapters[adapter_name].execute(action, urgency)
                 if result.success:
                     self._update_resolver_state(action)
-                # Device Health Monitor — record the outcome
-                self._record_health(action, result)
+                # Device health is recorded once, by the wrapper every path
+                # goes through (DoSyncHub.instrumented), not here as well.
                 return result
             except Exception as e:
                 log.error(
@@ -283,7 +283,6 @@ class AdapterExecutor:
                     success=False,
                     error=f"Adapter error: {e}",
                 )
-                self._record_health(action, err_result)
                 return err_result
 
         # Fallback. WARNING, not INFO, and the result says it was simulated:
@@ -307,21 +306,6 @@ class AdapterExecutor:
             error=f"No adapter registered for '{adapter_name}'",
         )
 
-    def _record_health(self, action: DeviceAction, result) -> None:
-        """Record the outcome in the Device Health Monitor."""
-        try:
-            db = getattr(self._hub, 'db', None)
-            if db:
-                db.record_execution(
-                    device_id=action.device_id,
-                    action=action.action,
-                    success=result.success,
-                    error=getattr(result, 'error', None),
-                )
-        except Exception as _e:
-            log.warning('DeviceHealthMonitor: failed to record execution for %s: %s',
-                        action.device_id, _e)
-
     def _update_resolver_state(self, action: DeviceAction) -> None:
         """Tell the StateAwareResolver the new state after a successful action."""
         from ..hub import StateAwareResolver