dosync 0.6.2__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.6.2
+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>=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>=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
           │               │               │
           └───────────────┴───────────────┘
                           │
@@ -788,6 +791,167 @@ test, so it is named rather than recommended.
 
 ---
 
+## Connecting an agent
+
+This page has said "MCP" a dozen times — a badge at the top, a section on why
+MCP is the channel rather than the rival, a drone that flew a mission through
+it — and never once explained how to connect an agent. This is that.
+
+DoSync ships an MCP server. It is not a separate product: it exposes the hub's
+intents and devices as tools, and every call it makes lands in the same policy
+engine and the same audit chain as a call from `curl`. An agent that reaches a
+device through it is governed exactly like anything else.
+
+### What DoSync provides
+
+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.27.0,<2.0"      # or: pipx inject dosync "mcp>=1.27.0,<2.0"
+python -m dosync.mcp_server
+```
+
+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 |
+|---|---|
+| `DOSYNC_HUB_URL` | Where the hub is. Default `http://localhost:47200` |
+| `DOSYNC_TOKEN` | The hub's bearer token |
+| `DOSYNC_CA_CERT` | CA certificate, when the hub runs over TLS |
+
+That is the whole of DoSync's side. Everything below is about getting a client
+to launch that command — which is the client's business, not the protocol's.
+
+### What the client provides
+
+MCP clients are configured with a JSON file naming a command to run and the
+environment to run it in. The shape is standard:
+
+```json
+{
+  "mcpServers": {
+    "dosync": {
+      "command": "/absolute/path/to/python",
+      "args": ["-m", "dosync.mcp_server"],
+      "env": {
+        "DOSYNC_HUB_URL": "http://localhost:47200",
+        "DOSYNC_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+**That file holds a credential.** It grants whatever the token grants. This
+project shipped a live token in a public repository for three months, so the
+warning is not rhetorical: keep it out of version control and off shared
+drives.
+
+Use an absolute path to the interpreter that has DoSync installed. A client
+launches the command with its own environment, not yours, so `python` may not
+resolve to what you expect. With `pipx`, the interpreter is inside its venv —
+on Linux and macOS `~/.local/share/pipx/venvs/dosync/bin/python`, on Windows
+`%LOCALAPPDATA%\pipx\pipx\venvs\dosync\Scripts\python.exe`.
+
+Where the file goes and how it reloads is documented by your client, not here.
+
+### Two things Windows does to this file
+
+Neither belongs to any particular client, and both fail without a useful error,
+so they are worth knowing before you spend an afternoon on them.
+
+**A packaged application does not see the path you wrote to.** Applications
+installed from the Microsoft Store run with a virtualised filesystem: when they
+read `%APPDATA%\Something`, Windows redirects them to
+`%LOCALAPPDATA%\Packages\<package-id>\LocalCache\Roaming\Something`. A file
+written to the literal path is invisible to the application, and nothing
+reports this — the client simply behaves as though no configuration exists. If
+your client offers a button that opens its configuration folder, use it and
+write there.
+
+**PowerShell 5.1 writes a byte-order mark.** `Set-Content -Encoding UTF8` puts
+three bytes at the start of the file that JSON parsers reject, and the error
+names an invisible character: `Unexpected token ''`. Write it without one:
+
+```powershell
+[System.IO.File]::WriteAllText($path, $json, [System.Text.UTF8Encoding]::new($false))
+```
+
+Check the first byte is `123` (`{`) and not `239`:
+
+```powershell
+[System.IO.File]::ReadAllBytes($path)[0]
+```
+
+### What it looks like when it works
+
+*Verified 29 August 2026: Windows 11 ARM64, Python 3.14, DoSync 0.6.2 installed
+with `pipx`, MCP SDK 1.29.1, Claude Desktop from the Microsoft Store. Named
+because a result you cannot reproduce is not evidence — not as a
+recommendation. Any client that speaks MCP works; the details above are what
+that combination required, and clients change theirs without notice.*
+
+Asked in plain language which devices were registered, the agent listed six —
+three WiZ bulbs with their actions, and three adopted devices with none. What
+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
+flow in [`/v1/devices/{id}/describe`](#keeping-the-hub-running), reached from
+the other end.
+
+---
+
 ## What's built today
 
 | Component | Status |
@@ -797,11 +961,11 @@ test, so it is named rather than recommended.
 | 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 |
@@ -850,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.2 → 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
           │               │               │
           └───────────────┴───────────────┘
                           │
@@ -726,6 +725,167 @@ test, so it is named rather than recommended.
 
 ---
 
+## Connecting an agent
+
+This page has said "MCP" a dozen times — a badge at the top, a section on why
+MCP is the channel rather than the rival, a drone that flew a mission through
+it — and never once explained how to connect an agent. This is that.
+
+DoSync ships an MCP server. It is not a separate product: it exposes the hub's
+intents and devices as tools, and every call it makes lands in the same policy
+engine and the same audit chain as a call from `curl`. An agent that reaches a
+device through it is governed exactly like anything else.
+
+### What DoSync provides
+
+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.27.0,<2.0"      # or: pipx inject dosync "mcp>=1.27.0,<2.0"
+python -m dosync.mcp_server
+```
+
+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 |
+|---|---|
+| `DOSYNC_HUB_URL` | Where the hub is. Default `http://localhost:47200` |
+| `DOSYNC_TOKEN` | The hub's bearer token |
+| `DOSYNC_CA_CERT` | CA certificate, when the hub runs over TLS |
+
+That is the whole of DoSync's side. Everything below is about getting a client
+to launch that command — which is the client's business, not the protocol's.
+
+### What the client provides
+
+MCP clients are configured with a JSON file naming a command to run and the
+environment to run it in. The shape is standard:
+
+```json
+{
+  "mcpServers": {
+    "dosync": {
+      "command": "/absolute/path/to/python",
+      "args": ["-m", "dosync.mcp_server"],
+      "env": {
+        "DOSYNC_HUB_URL": "http://localhost:47200",
+        "DOSYNC_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+**That file holds a credential.** It grants whatever the token grants. This
+project shipped a live token in a public repository for three months, so the
+warning is not rhetorical: keep it out of version control and off shared
+drives.
+
+Use an absolute path to the interpreter that has DoSync installed. A client
+launches the command with its own environment, not yours, so `python` may not
+resolve to what you expect. With `pipx`, the interpreter is inside its venv —
+on Linux and macOS `~/.local/share/pipx/venvs/dosync/bin/python`, on Windows
+`%LOCALAPPDATA%\pipx\pipx\venvs\dosync\Scripts\python.exe`.
+
+Where the file goes and how it reloads is documented by your client, not here.
+
+### Two things Windows does to this file
+
+Neither belongs to any particular client, and both fail without a useful error,
+so they are worth knowing before you spend an afternoon on them.
+
+**A packaged application does not see the path you wrote to.** Applications
+installed from the Microsoft Store run with a virtualised filesystem: when they
+read `%APPDATA%\Something`, Windows redirects them to
+`%LOCALAPPDATA%\Packages\<package-id>\LocalCache\Roaming\Something`. A file
+written to the literal path is invisible to the application, and nothing
+reports this — the client simply behaves as though no configuration exists. If
+your client offers a button that opens its configuration folder, use it and
+write there.
+
+**PowerShell 5.1 writes a byte-order mark.** `Set-Content -Encoding UTF8` puts
+three bytes at the start of the file that JSON parsers reject, and the error
+names an invisible character: `Unexpected token ''`. Write it without one:
+
+```powershell
+[System.IO.File]::WriteAllText($path, $json, [System.Text.UTF8Encoding]::new($false))
+```
+
+Check the first byte is `123` (`{`) and not `239`:
+
+```powershell
+[System.IO.File]::ReadAllBytes($path)[0]
+```
+
+### What it looks like when it works
+
+*Verified 29 August 2026: Windows 11 ARM64, Python 3.14, DoSync 0.6.2 installed
+with `pipx`, MCP SDK 1.29.1, Claude Desktop from the Microsoft Store. Named
+because a result you cannot reproduce is not evidence — not as a
+recommendation. Any client that speaks MCP works; the details above are what
+that combination required, and clients change theirs without notice.*
+
+Asked in plain language which devices were registered, the agent listed six —
+three WiZ bulbs with their actions, and three adopted devices with none. What
+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
+flow in [`/v1/devices/{id}/describe`](#keeping-the-hub-running), reached from
+the other end.
+
+---
+
 ## What's built today
 
 | Component | Status |
@@ -735,11 +895,11 @@ test, so it is named rather than recommended.
 | 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 |
@@ -788,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.2 → 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.2"
-__protocol_version__ = "0.4"
+__version__ = "0.7.0"
+__protocol_version__ = "0.5"

{dosync-0.6.2 → 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.2 → dosync-0.7.0}/dosync/adapters/__init__.py

@@ -6,7 +6,7 @@ Translation layer between the DoSync protocol and real physical devices.
 Modelo:
     DoSync Hub → AdapterExecutor → [WiZAdapter | GPIOAdapter | ShellyAdapter | ...]
 
-Para agregar un nuevo dispositivo:
+To add a new device type:
     1. Crear adapters/mi_marca.py implementando DoSyncAdapter
     2. Register the device with adapter="my_brand" in its CapabilityManifest
     3. The hub treats it like any other device — no core changes needed
@@ -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.).
 
-    Para implementar un adapter nuevo:
+    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