dosync 0.4.1__py3-none-any.whl

dosync/__init__.py

@@ -0,0 +1,17 @@
+"""DoSync Protocol — the semantic layer between AI agents and physical devices.
+
+Apache 2.0 — github.com/giulianireg-spec/dosync-protocol
+
+This module is the SINGLE SOURCE for both version numbers. Until 2026-07-22
+there were three: this file said 0.1.0/0.1, server.py hardcoded 0.4.0 in four
+places, and pyproject.toml carried its own copy — three declarations nobody
+checked against each other, so `import dosync; dosync.__version__` reported a
+version three releases old. pyproject reads the value from here and the server
+imports it, so they cannot drift again (and a test asserts it).
+
+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.4.1"
+__protocol_version__ = "0.4"

dosync/adapters/__init__.py

@@ -0,0 +1,258 @@
+"""
+DoSync — Adapter Layer
+======================
+Capa de traducción entre el protocolo DoSync y dispositivos físicos reales.
+
+Modelo:
+    DoSync Hub → AdapterExecutor → [WiZAdapter | GPIOAdapter | ShellyAdapter | ...]
+
+Para agregar un nuevo dispositivo:
+    1. Crear adapters/mi_marca.py implementando DoSyncAdapter
+    2. Registrar el dispositivo con adapter="mi_marca" en su CapabilityManifest
+    3. El hub lo maneja igual que cualquier otro dispositivo — sin cambios al núcleo
+
+Publicación de adapters de terceros:
+    pip install dosync-adapter-philipshue
+    pip install dosync-adapter-shelly
+    pip install dosync-adapter-matter
+"""
+
+from __future__ import annotations
+import logging
+from abc import ABC, abstractmethod
+
+from ..models import ActionResult, DeviceAction, Urgency
+
+log = logging.getLogger("dosync.adapters")
+
+
+# ── Interfaz base que todo adapter debe implementar ───────────────────────────
+
+class DoSyncAdapter(ABC):
+    """
+    Interfaz base para adapters de dispositivos físicos.
+
+    Cada adapter traduce acciones DoSync al protocolo nativo
+    del dispositivo (UDP, HTTP, GPIO, BLE, etc.).
+
+    Para implementar un adapter nuevo:
+
+        class MyBrandAdapter(DoSyncAdapter):
+            async def execute(self, action, urgency):
+                # traducir action.action + action.params al protocolo del dispositivo
+                return ActionResult(
+                    device_id=action.device_id,
+                    action=action.action,
+                    success=True,
+                    response={"status": "ok"},
+                )
+
+            async def connect(self, config):
+                # initialize connection with the device
+                pass
+
+            async def disconnect(self):
+                pass
+
+            @property
+            def adapter_name(self):
+                return "mybrand"
+    """
+
+    @abstractmethod
+    async def execute(self, action: DeviceAction, urgency: Urgency) -> ActionResult:
+        """Execute an action on the physical device."""
+        ...
+
+    async def connect(self, config: dict) -> None:
+        """Initialize the connection to the device. Optional."""
+        pass
+
+    async def disconnect(self) -> None:
+        """Close the connection. Optional."""
+        pass
+
+    async def get_state(self, device_id: str) -> dict | None:
+        """
+        Query current device state directly from the physical device.
+
+        Returns a state dict if supported, None if not implemented.
+        The StateAwareResolver background refresher calls this periodically
+        to keep the state cache fresh without blocking intent resolution.
+
+        Example return values:
+            {"on": True, "brightness": 80}       — WiZ bulb
+            {"on": False}                         — Shelly relay
+            {"state": "locked"}                   — door lock
+            None                                  — adapter does not support state query
+        """
+        return None  # default: not supported — override in subclasses
+
+    @property
+    @abstractmethod
+    def adapter_name(self) -> str:
+        """Unique adapter name. Must match the 'adapter' field in the device manifest."""
+        ...
+
+
+# ── AdapterExecutor — el ejecutor central ────────────────────────────────────
+
+class AdapterExecutor:
+    """
+    Ejecutor central que delega acciones al adapter correcto
+    según el campo 'adapter' del CapabilityManifest del dispositivo.
+
+    Si un dispositivo no tiene adapter registrado, cae al SimulatedExecutor.
+
+    Uso:
+        executor = AdapterExecutor(hub)
+        executor.register(WiZAdapter())
+        executor.register(GPIOAdapter())
+
+        # El hub usa este executor en lugar del SimulatedExecutor
+        result = await hub.execute_intent(intent, executor)
+    """
+
+    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
+        """
+        self._hub = hub
+        self._adapters: dict[str, DoSyncAdapter] = {}
+        self._fallback = fallback_to_simulated
+
+        if fallback_to_simulated:
+            from ..executor import SimulatedExecutor
+            self._simulated = SimulatedExecutor()
+        else:
+            self._simulated = None
+
+    def register(self, adapter: DoSyncAdapter) -> None:
+        """Registra un adapter por su nombre."""
+        self._adapters[adapter.adapter_name] = adapter
+        log.info("Adapter registered: %s", adapter.adapter_name)
+
+    def get_adapter(self, adapter_name: str) -> DoSyncAdapter | None:
+        """Returns the adapter instance for a given adapter name, or None if not registered."""
+        return self._adapters.get(adapter_name)
+
+
+    def registered_adapters(self) -> list[str]:
+        """Lista de adapters registrados."""
+        return list(self._adapters.keys())
+
+    async def execute(self, action: DeviceAction, urgency: Urgency) -> ActionResult:
+        """
+        Ejecuta una acción buscando el adapter correcto para el dispositivo.
+        Fallback al SimulatedExecutor si el dispositivo no tiene adapter.
+        """
+        device = self._hub.registry.get(action.device_id)
+
+        if device is None:
+            return ActionResult(
+                device_id=action.device_id,
+                action=action.action,
+                success=False,
+                error=f"Device '{action.device_id}' not found in registry",
+            )
+
+        adapter_name = getattr(device, "adapter", None)
+
+        # State awareness: skip redundant actions
+        from ..hub import StateAwareResolver
+        resolver = getattr(self._hub, 'resolver', None)
+        if isinstance(resolver, StateAwareResolver):
+            dummy_action = action
+            if resolver._is_redundant(dummy_action):
+                log.info("StateAwareResolver: skipped redundant %s on %s",
+                         action.action, action.device_id)
+                # ActionResult already imported at module level (line 25)
+                return ActionResult(
+                    device_id=action.device_id,
+                    action=action.action,
+                    success=True,
+                    response={"status": "skipped_redundant"},
+                )
+
+        if adapter_name and adapter_name in self._adapters:
+            log.info(
+                "Dispatching %s.%s to adapter '%s'",
+                action.device_id, action.action, adapter_name,
+            )
+            try:
+                result = await self._adapters[adapter_name].execute(action, urgency)
+                if result.success:
+                    self._update_resolver_state(action)
+                # Device Health Monitor — registrar resultado
+                self._record_health(action, result)
+                return result
+            except Exception as e:
+                log.error(
+                    "Adapter '%s' failed for %s.%s: %s",
+                    adapter_name, action.device_id, action.action, e,
+                )
+                err_result = ActionResult(
+                    device_id=action.device_id,
+                    action=action.action,
+                    success=False,
+                    error=f"Adapter error: {e}",
+                )
+                self._record_health(action, err_result)
+                return err_result
+
+        # Fallback
+        if self._simulated:
+            log.info(
+                "No adapter for '%s' (device %s) — using SimulatedExecutor",
+                adapter_name or "none", action.device_id,
+            )
+            return await self._simulated.execute(action, urgency)
+
+        return ActionResult(
+            device_id=action.device_id,
+            action=action.action,
+            success=False,
+            error=f"No adapter registered for '{adapter_name}'",
+        )
+
+    def _record_health(self, action: DeviceAction, result) -> None:
+        """Registra el resultado en el 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:
+        """Notifica al StateAwareResolver el nuevo estado tras una accion exitosa."""
+        from ..hub import StateAwareResolver
+        resolver = getattr(self._hub, 'resolver', None)
+        if not isinstance(resolver, StateAwareResolver):
+            return
+        state_update = {}
+        if action.action == 'turn_on':
+            state_update = {'on': True, 'brightness': action.params.get('brightness', 100)}
+        elif action.action == 'turn_off':
+            state_update = {'on': False, 'brightness': 0}
+        elif action.action == 'set_brightness':
+            state_update = {'on': True, 'brightness': action.params.get('brightness', 100)}
+        elif action.action == 'unlock':
+            state_update = {'locked': False}
+        elif action.action == 'lock':
+            state_update = {'locked': True}
+        elif action.action == 'set_temperature':
+            state_update = {'temperature': action.params.get('celsius')}
+        if state_update:
+            resolver.update_state(action.device_id, state_update)
+
+

dosync/adapters/ble.py

@@ -0,0 +1,199 @@
+"""
+DoSync — Universal BLE Adapter
+==============================
+A single adapter that controls ANY Bluetooth Low Energy device, by driving the
+generic GATT primitives (connect, write characteristic) and reading the per-device
+action→characteristic mapping from the device's manifest.
+
+This is the "dumb body, external mind" principle at the transport layer: the BLE
+device does not know DoSync exists. It only exposes its native GATT interface. The
+adapter — running in the hub — speaks that native BLE and lends the device the
+intelligence of being coordinated by an intent.
+
+Why one adapter for all BLE devices:
+    BLE has no universal command. Each device exposes services and characteristics
+    identified by UUIDs, and which characteristic means "turn on" differs per
+    device. So the *code* is generic (GATT writes); the *mapping* lives in each
+    device's manifest under adapter_config. Adding a new BLE device requires a
+    manifest entry, not new code.
+
+Manifest adapter_config schema (per device):
+    {
+        "address": "AA:BB:CC:DD:EE:FF",      # BLE MAC (or platform UUID on macOS)
+        "actions": {
+            "turn_on":  {"char": "0000fff1-0000-1000-8000-00805f9b34fb",
+                          "write": "0F0D0300"},        # hex bytes to write
+            "turn_off": {"char": "0000fff1-0000-1000-8000-00805f9b34fb",
+                          "write": "0F0D0400"}
+        }
+    }
+
+The device's CapabilityManifest declares adapter="ble" and carries this config.
+The hub routes any action on that device here, exactly like wiz/gpio/homeassistant.
+
+Dependencies: bleak (cross-platform BLE; uses BlueZ on the Raspberry Pi).
+"""
+
+from __future__ import annotations
+import logging
+from typing import Optional
+
+from ..models import ActionResult, DeviceAction, Urgency
+from . import DoSyncAdapter
+
+log = logging.getLogger("dosync.adapters.ble")
+
+# bleak is imported lazily so the module imports (and the adapter registers /
+# unit-tests) on a host without a Bluetooth stack.
+try:
+    from bleak import BleakClient
+    _BLEAK_AVAILABLE = True
+except Exception:  # pragma: no cover - depends on host
+    BleakClient = None  # type: ignore
+    _BLEAK_AVAILABLE = False
+
+
+def ble_manifest(
+    device_id: str,
+    device_name: str,
+    address: str,
+    actions: dict,
+    tags: Optional[list] = None,
+    emergency_capable: bool = False,
+):
+    """Helper to build a CapabilityManifest for a generic BLE device.
+
+    `actions` maps a DoSync action name to {"char": <uuid>, "write": <hex>}.
+    The actuator list is derived from the action keys, so the resolver sees
+    exactly the actions this device supports.
+    """
+    from ..models import (
+        ActuatorSpec, CapabilityManifest, CertTier, DeviceCategory,
+    )
+
+    # Derive one actuator per supported action (id == type, like wiz_manifest).
+    actuators = [
+        ActuatorSpec(name, name, f"BLE action {name}")
+        for name in actions.keys()
+    ]
+
+    manifest = CapabilityManifest(
+        device_id=device_id,
+        device_name=device_name,
+        manufacturer="Generic BLE",
+        model="BLE GATT device",
+        firmware="auto",
+        category=DeviceCategory.ACTUATOR,
+        tags=list(set(tags or [])),
+        sensors=[],
+        actuators=actuators,
+        events=[],
+        emergency_capable=emergency_capable,
+        cert_tier=CertTier.BASIC,
+    )
+
+    # Attach adapter config (address + action→characteristic map) to the manifest.
+    manifest.adapter = "ble"
+    manifest.adapter_config = {"address": address, "actions": actions}
+
+    return manifest
+
+
+class BLEAdapter(DoSyncAdapter):
+    """Universal Bluetooth Low Energy adapter.
+
+    One instance handles every device whose manifest declares adapter="ble".
+    The per-device address and action→characteristic map come from the manifest's
+    adapter_config, read from the hub registry (same pattern as WiZAdapter).
+    """
+
+    def __init__(self, hub=None, connect_timeout: float = 10.0):
+        """
+        Args:
+            hub: reference to the DoSyncHub to read adapter_config from the
+                 manifest. Optional — if absent, config must come in action.params.
+            connect_timeout: seconds to wait for a BLE connection.
+        """
+        self._hub = hub
+        self._connect_timeout = connect_timeout
+
+    @property
+    def adapter_name(self) -> str:
+        return "ble"
+
+    def _get_config(self, action: DeviceAction) -> dict:
+        """Resolve adapter_config: action.params override, then manifest."""
+        cfg = action.params.get("adapter_config")
+        if cfg:
+            return cfg
+        if self._hub:
+            device = self._hub.registry.get(action.device_id)
+            if device and device.adapter_config:
+                return device.adapter_config
+        return {}
+
+    async def execute(self, action: DeviceAction, urgency: Urgency) -> ActionResult:
+        """Translate a DoSync action into a GATT characteristic write."""
+        cfg = self._get_config(action)
+        address = cfg.get("address")
+        actions_map = cfg.get("actions", {})
+
+        if not address:
+            return ActionResult(
+                device_id=action.device_id, action=action.action, success=False,
+                error="BLE manifest missing 'address'. Use ble_manifest(address=...).",
+            )
+
+        spec = actions_map.get(action.action)
+        if spec is None:
+            return ActionResult(
+                device_id=action.device_id, action=action.action, success=False,
+                error=f"BLE device has no mapping for action '{action.action}'.",
+            )
+
+        char_uuid = spec.get("char")
+        write_hex = spec.get("write")
+        if not char_uuid or write_hex is None:
+            return ActionResult(
+                device_id=action.device_id, action=action.action, success=False,
+                error=f"BLE action '{action.action}' mapping needs 'char' and 'write'.",
+            )
+
+        try:
+            payload = bytes.fromhex(write_hex)
+        except ValueError:
+            return ActionResult(
+                device_id=action.device_id, action=action.action, success=False,
+                error=f"BLE 'write' value is not valid hex: {write_hex!r}.",
+            )
+
+        if not _BLEAK_AVAILABLE:
+            # Simulated mode — bleak not installed on this host.
+            log.info("[SIMULATED] BLE %s @ %s: write %s to %s",
+                     action.device_id, address, write_hex, char_uuid)
+            return ActionResult(
+                device_id=action.device_id, action=action.action, success=True,
+                response={"status": "simulated", "address": address,
+                          "char": char_uuid, "wrote": write_hex},
+            )
+
+        try:
+            async with BleakClient(address, timeout=self._connect_timeout) as client:
+                await client.write_gatt_char(char_uuid, payload, response=True)
+            log.info("BLE %s @ %s: wrote %s to %s → OK",
+                     action.device_id, address, write_hex, char_uuid)
+            return ActionResult(
+                device_id=action.device_id, action=action.action, success=True,
+                response={"address": address, "char": char_uuid, "wrote": write_hex},
+            )
+        except Exception as e:
+            log.warning("BLE %s @ %s failed: %s", action.action, address, e)
+            return ActionResult(
+                device_id=action.device_id, action=action.action, success=False,
+                error=f"BLE write failed: {e}",
+            )
+
+    async def get_state(self, device_id: str) -> Optional[dict]:
+        """BLE state query is optional and device-specific. Deferred, like other
+        adapters that return None by default."""
+        return None