enigmind-agent 0.1.0__tar.gz

enigmind_agent-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: enigmind-agent
+Version: 0.1.0
+Summary: Enigmind Agent Python SDK for secure IoT connectivity.
+Author: Enigmind
+License: Proprietary
+Project-URL: Homepage, https://enigmind.ai
+Keywords: iot,mqtt,telemetry,enigmind
+Classifier: Development Status :: 3 - Alpha
+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: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: paho-mqtt<3,>=2.1.0
+Requires-Dist: platformdirs>=4.5.1
+Requires-Dist: typer[standard]>=0.21.1
+Provides-Extra: health
+Requires-Dist: psutil>=7.2.2; extra == "health"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+
+# Enigmind Agent Python SDK
+
+A lightweight Python SDK for secure IoT device connectivity.
+
+## Quick Start
+
+```python
+from enigmind_agent import Agent, AgentConfig
+
+config = AgentConfig(
+    broker_url="mqtts://broker.enigmind.ai:8883",
+    device_id="device-123",
+    api_key="YOUR_API_KEY",
+)
+
+agent = Agent(config)
+agent.start()
+agent.send_telemetry({"temp": 22.4, "vibration": 0.12})
+```
+
+## Device Claim Flow (Zero-Touch Setup)
+
+If the agent starts without credentials (`device_id` + `api_key`/`password`), it automatically enters the claim flow:
+
+1. Generates a stable hardware fingerprint and a human-readable claim token.
+2. Calls the claim API (`/api/claims/initiate`).
+3. Polls `/api/claims/{token}/status` until approved.
+4. Stores the returned credentials locally and connects to MQTT.
+
+The claim token is printed at startup when using the CLI, and is also stored locally for retrieval.
+By default the state file is saved under your user data directory as `enigmind_agent/state.json`.
+If you embed the SDK directly, enable Python logging at INFO level to see claim output.
+
+### CLI Example
+
+```bash
+ENIGMIND_CLAIM_BASE_URL=https://api.enigmind.ai enigmind-cli run
+```
+
+Check claim status and token:
+
+```bash
+enigmind-cli claim status
+```
+
+### JSON Config Example
+
+```json
+{
+  "broker_url": "mqtts://broker.enigmind.ai:8883",
+  "claim": {
+    "base_url": "https://api.enigmind.ai",
+    "poll_interval_s": 5,
+    "timeout_s": 300
+  }
+}
+```
+
+## Installation & Setup
+
+```powershell
+py -3.12 -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install -U pip
+pip install -e .[dev]
+```
+
+Optional Health plugin:
+
+```powershell
+pip install -e .[health]
+```
+
+## CLI
+
+```bash
+enigmind-cli send --data '{"temp": 22.4}' --config ./enigmind.json
+```
+
+## Releasing
+
+Releases are published to PyPI automatically via GitHub Actions when you create a GitHub Release.
+
+1. Bump `version` in `pyproject.toml`.
+2. Commit and push to `main`.
+3. Go to **GitHub → Releases → Draft a new release**.
+4. Create a new tag (e.g. `v0.1.0`), add release notes, and click **Publish release**.
+5. The `release.yml` workflow will build and publish the package to PyPI.
+
+## Plugins
+
+- Health plugin: CPU/memory/disk metrics (requires optional dependency `psutil`).
+- Geo plugin: local geofencing hooks (no extra dependencies).

enigmind_agent-0.1.0/README.md

@@ -0,0 +1,93 @@
+# Enigmind Agent Python SDK
+
+A lightweight Python SDK for secure IoT device connectivity.
+
+## Quick Start
+
+```python
+from enigmind_agent import Agent, AgentConfig
+
+config = AgentConfig(
+    broker_url="mqtts://broker.enigmind.ai:8883",
+    device_id="device-123",
+    api_key="YOUR_API_KEY",
+)
+
+agent = Agent(config)
+agent.start()
+agent.send_telemetry({"temp": 22.4, "vibration": 0.12})
+```
+
+## Device Claim Flow (Zero-Touch Setup)
+
+If the agent starts without credentials (`device_id` + `api_key`/`password`), it automatically enters the claim flow:
+
+1. Generates a stable hardware fingerprint and a human-readable claim token.
+2. Calls the claim API (`/api/claims/initiate`).
+3. Polls `/api/claims/{token}/status` until approved.
+4. Stores the returned credentials locally and connects to MQTT.
+
+The claim token is printed at startup when using the CLI, and is also stored locally for retrieval.
+By default the state file is saved under your user data directory as `enigmind_agent/state.json`.
+If you embed the SDK directly, enable Python logging at INFO level to see claim output.
+
+### CLI Example
+
+```bash
+ENIGMIND_CLAIM_BASE_URL=https://api.enigmind.ai enigmind-cli run
+```
+
+Check claim status and token:
+
+```bash
+enigmind-cli claim status
+```
+
+### JSON Config Example
+
+```json
+{
+  "broker_url": "mqtts://broker.enigmind.ai:8883",
+  "claim": {
+    "base_url": "https://api.enigmind.ai",
+    "poll_interval_s": 5,
+    "timeout_s": 300
+  }
+}
+```
+
+## Installation & Setup
+
+```powershell
+py -3.12 -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install -U pip
+pip install -e .[dev]
+```
+
+Optional Health plugin:
+
+```powershell
+pip install -e .[health]
+```
+
+## CLI
+
+```bash
+enigmind-cli send --data '{"temp": 22.4}' --config ./enigmind.json
+```
+
+## Releasing
+
+Releases are published to PyPI automatically via GitHub Actions when you create a GitHub Release.
+
+1. Bump `version` in `pyproject.toml`.
+2. Commit and push to `main`.
+3. Go to **GitHub → Releases → Draft a new release**.
+4. Create a new tag (e.g. `v0.1.0`), add release notes, and click **Publish release**.
+5. The `release.yml` workflow will build and publish the package to PyPI.
+
+## Plugins
+
+- Health plugin: CPU/memory/disk metrics (requires optional dependency `psutil`).
+- Geo plugin: local geofencing hooks (no extra dependencies).

enigmind_agent-0.1.0/enigmind_agent/__init__.py

@@ -0,0 +1,16 @@
+from .agent import Agent
+from .claim import ClaimSettings, claim_device, generate_claim_token, hardware_fingerprint
+from .config import AgentConfig, ClaimConfig, TLSConfig
+from .version import __version__
+
+__all__ = [
+    "Agent",
+    "AgentConfig",
+    "ClaimConfig",
+    "ClaimSettings",
+    "TLSConfig",
+    "__version__",
+    "claim_device",
+    "generate_claim_token",
+    "hardware_fingerprint",
+]

enigmind_agent-0.1.0/enigmind_agent/agent.py

@@ -0,0 +1,162 @@
+import threading
+import time
+from typing import Any, Callable, Dict, Iterable, Optional
+
+from .buffer import SQLiteTelemetryBuffer
+from .claim import ClaimError, ClaimSettings, claim_device
+from .config import AgentConfig
+from .delta import DeltaFilter
+from .mqtt import MQTTClient
+from .rpc import RpcRouter
+from .plugins.base import Plugin
+
+
+class Agent:
+    def __init__(self, config: AgentConfig) -> None:
+        self.config = config.normalized()
+        self._buffer = SQLiteTelemetryBuffer(self.config.buffer_path)
+        self._delta = DeltaFilter()
+        self._rpc = RpcRouter()
+        self._plugins: Iterable[Plugin] = []
+        self._mqtt = MQTTClient(self.config, on_message=self._on_message, on_connect=self._on_connect)
+        self._heartbeat_thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+
+    def register_plugin(self, plugin: Plugin) -> None:
+        self._plugins = [*self._plugins, plugin]
+
+    def register_rpc_handler(self, method: str, handler: Callable[[Any], Any]) -> None:
+        self._rpc.register(method, handler)
+
+    def start(self) -> None:
+        self._start_time = time.time()
+        for plugin in self._plugins:
+            plugin.on_start(self)
+        self._ensure_claimed()
+        self._mqtt.connect()
+        self._mqtt.subscribe(self.config.rpc_request_topic)
+        self._stop_event.clear()
+        self._heartbeat_thread = threading.Thread(target=self._heartbeat_loop, daemon=True)
+        self._heartbeat_thread.start()
+
+    def stop(self) -> None:
+        self._stop_event.set()
+        if self._heartbeat_thread:
+            self._heartbeat_thread.join(timeout=2)
+        for plugin in self._plugins:
+            plugin.on_stop(self)
+        self._mqtt.disconnect()
+
+    def send_telemetry(self, payload: Dict[str, Any], qos: int = 0, retain: bool = False, force: bool = False) -> None:
+        if not force and self.config.delta_sync:
+            payload, changed = self._delta.diff(payload)
+            if not changed:
+                return
+        topic = self.config.telemetry_topic
+        if not self._mqtt.connected:
+            self._buffer.enqueue(topic, payload, qos=qos, retain=retain)
+            return
+        ok = self._mqtt.publish(topic, payload, qos=qos, retain=retain)
+        if not ok:
+            self._buffer.enqueue(topic, payload, qos=qos, retain=retain)
+
+    def flush_buffer(self, batch_size: int = 100) -> None:
+        if not self._mqtt.connected:
+            return
+        messages = self._buffer.dequeue_batch(limit=batch_size)
+        if not messages:
+            return
+        failed_ids = []
+        for message in messages:
+            ok = self._mqtt.publish(message.topic, message.payload, qos=message.qos, retain=message.retain)
+            if not ok:
+                failed_ids.append(message.id)
+        success_ids = [msg.id for msg in messages if msg.id not in failed_ids]
+        self._buffer.delete(success_ids)
+
+    def buffer_count(self) -> int:
+        return self._buffer.count()
+
+    def _heartbeat_loop(self) -> None:
+        last_flush = 0.0
+        while not self._stop_event.is_set():
+            now = time.time()
+            payload = {
+                "type": "heartbeat",
+                "ts": int(now * 1000),
+                "uptime_s": int(now - (self._start_time if hasattr(self, "_start_time") else now)),
+            }
+            for plugin in self._plugins:
+                metrics = plugin.collect_telemetry()
+                if metrics:
+                    payload.update(metrics)
+            self.send_telemetry(payload, force=True)
+            if now - last_flush > 10:
+                self.flush_buffer()
+                last_flush = now
+            self._stop_event.wait(self.config.heartbeat_interval_s)
+
+    def _on_message(self, topic: str, payload: bytes) -> None:
+        prefix = self.config.rpc_request_topic.rstrip("+")
+        if topic.startswith(prefix):
+            request_id = topic.split("/")[-1]
+            response = self._rpc.handle(payload)
+            if response is None:
+                return
+            response_topic = self.config.rpc_response_topic.format(request_id=request_id)
+            self._mqtt.publish(response_topic, response, qos=0)
+
+    def _on_connect(self) -> None:
+        self.flush_buffer()
+
+    def _ensure_claimed(self) -> None:
+        if self.config.has_credentials():
+            return
+        claim_cfg = self.config.claim
+        if not claim_cfg.base_url:
+            raise RuntimeError("Missing credentials and claim.base_url is not configured")
+        settings = ClaimSettings(
+            base_url=claim_cfg.base_url,
+            initiate_path=claim_cfg.initiate_path,
+            status_path=claim_cfg.status_path,
+            poll_interval_s=claim_cfg.poll_interval_s,
+            timeout_s=claim_cfg.timeout_s,
+            request_timeout_s=claim_cfg.request_timeout_s,
+            max_retries=claim_cfg.max_retries,
+            backoff_s=claim_cfg.backoff_s,
+            state_path=claim_cfg.state_path,
+        )
+        try:
+            credentials = claim_device(settings)
+        except ClaimError as exc:
+            raise RuntimeError(f"Device claim failed: {exc}") from exc
+        self._apply_claimed_credentials(credentials)
+        self.config.normalized()
+        self._mqtt = MQTTClient(self.config, on_message=self._on_message, on_connect=self._on_connect)
+
+    def _apply_claimed_credentials(self, credentials: Dict[str, Any]) -> None:
+        mapping = (
+            "broker_url",
+            "device_id",
+            "api_key",
+            "username",
+            "password",
+            "client_id",
+            "telemetry_topic",
+            "heartbeat_topic",
+            "rpc_request_topic",
+            "rpc_response_topic",
+            "keepalive",
+        )
+        for key in mapping:
+            if key not in credentials:
+                continue
+            value = credentials.get(key)
+            if value is None:
+                continue
+            if key == "keepalive":
+                try:
+                    value = int(value)
+                except (TypeError, ValueError):
+                    continue
+            setattr(self.config, key, value)

enigmind_agent-0.1.0/enigmind_agent/buffer.py

@@ -0,0 +1,80 @@
+import json
+import os
+import sqlite3
+import threading
+from dataclasses import dataclass
+from typing import Iterable, List, Optional
+
+
+@dataclass
+class BufferedMessage:
+    id: int
+    topic: str
+    payload: dict
+    qos: int
+    retain: bool
+
+
+class SQLiteTelemetryBuffer:
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self._lock = threading.Lock()
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        self._init_db()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.path)
+        conn.execute("PRAGMA journal_mode=WAL;")
+        conn.execute("PRAGMA synchronous=NORMAL;")
+        return conn
+
+    def _init_db(self) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS telemetry_queue (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    topic TEXT NOT NULL,
+                    payload TEXT NOT NULL,
+                    qos INTEGER NOT NULL,
+                    retain INTEGER NOT NULL
+                )
+                """
+            )
+
+    def enqueue(self, topic: str, payload: dict, qos: int = 0, retain: bool = False) -> None:
+        with self._lock, self._connect() as conn:
+            conn.execute(
+                "INSERT INTO telemetry_queue (topic, payload, qos, retain) VALUES (?, ?, ?, ?)",
+                (topic, json.dumps(payload, separators=(",", ":")), qos, int(retain)),
+            )
+
+    def dequeue_batch(self, limit: int = 100) -> List[BufferedMessage]:
+        with self._lock, self._connect() as conn:
+            rows = conn.execute(
+                "SELECT id, topic, payload, qos, retain FROM telemetry_queue ORDER BY id ASC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [
+            BufferedMessage(
+                id=row[0],
+                topic=row[1],
+                payload=json.loads(row[2]),
+                qos=int(row[3]),
+                retain=bool(row[4]),
+            )
+            for row in rows
+        ]
+
+    def delete(self, ids: Iterable[int]) -> None:
+        ids = list(ids)
+        if not ids:
+            return
+        placeholders = ",".join("?" for _ in ids)
+        with self._lock, self._connect() as conn:
+            conn.execute(f"DELETE FROM telemetry_queue WHERE id IN ({placeholders})", ids)
+
+    def count(self) -> int:
+        with self._lock, self._connect() as conn:
+            row = conn.execute("SELECT COUNT(*) FROM telemetry_queue").fetchone()
+        return int(row[0]) if row else 0