enigmind-agent 0.1.0__py3-none-any.whl

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/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/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

enigmind_agent/claim.py

@@ -0,0 +1,247 @@
+import hashlib
+import json
+import logging
+import os
+import secrets
+import time
+import uuid
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from .storage import StateStore
+from .version import __version__
+
+
+CLAIM_TOKEN_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+logger = logging.getLogger("enigmind_agent.claim")
+
+
+class ClaimError(RuntimeError):
+    pass
+
+
+class ClaimTimeout(ClaimError):
+    pass
+
+
+class ClaimHttpError(ClaimError):
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+@dataclass
+class ClaimSettings:
+    base_url: str
+    initiate_path: str = "/api/claims/initiate"
+    status_path: str = "/api/claims/{token}/status"
+    poll_interval_s: float = 5.0
+    timeout_s: float = 300.0
+    request_timeout_s: float = 5.0
+    max_retries: int = 3
+    backoff_s: float = 1.0
+    state_path: Optional[str] = None
+
+
+def generate_claim_token(length: int = 8, alphabet: str = CLAIM_TOKEN_ALPHABET) -> str:
+    if length < 6 or length > 8:
+        raise ValueError("claim token length must be between 6 and 8 characters")
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
+def hardware_fingerprint() -> str:
+    override = os.getenv("ENIGMIND_HARDWARE_ID")
+    if override:
+        return override.strip()
+    machine_id = _read_machine_id()
+    if machine_id:
+        raw = f"machine:{machine_id}"
+    else:
+        raw = f"mac:{uuid.getnode()}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _read_machine_id() -> Optional[str]:
+    paths = ("/etc/machine-id", "/var/lib/dbus/machine-id")
+    for path in paths:
+        try:
+            with open(path, "r", encoding="utf-8") as handle:
+                value = handle.read().strip()
+            if value:
+                return value
+        except OSError:
+            continue
+    return None
+
+
+def claim_device(
+    settings: ClaimSettings,
+    hardware_id: Optional[str] = None,
+    token_length: int = 8,
+    store: Optional[StateStore] = None,
+) -> Dict[str, Any]:
+    store = store or StateStore(settings.state_path)
+    state = store.load()
+    if state.credentials:
+        return state.credentials
+
+    had_token = bool(state.claim_token)
+    state.hardware_id = state.hardware_id or hardware_id or hardware_fingerprint()
+    state.claim_token = state.claim_token or generate_claim_token(token_length)
+    store.save(state)
+
+    logger.info("Device claim token: %s", state.claim_token)
+    logger.info("Waiting for claim approval...")
+
+    client = ClaimClient(settings)
+    if had_token:
+        try:
+            client.initiate(state.hardware_id, state.claim_token)
+        except ClaimHttpError as exc:
+            if exc.status_code in {400, 409}:
+                logger.info("Claim token already initiated; resuming status polling")
+            else:
+                raise
+    else:
+        client.initiate(state.hardware_id, state.claim_token)
+    payload = client.poll_status(state.claim_token)
+    credentials = _extract_credentials(payload)
+    if not credentials:
+        raise ClaimError("Claim completed without returning credentials")
+
+    state.credentials = credentials
+    store.save(state)
+    return credentials
+
+
+class ClaimClient:
+    def __init__(self, settings: ClaimSettings) -> None:
+        self.settings = settings
+
+    def initiate(self, hardware_id: str, claim_token: str) -> Dict[str, Any]:
+        payload = {
+            "hardware_id": hardware_id,
+            "claim_token": claim_token,
+        }
+        url = _join_url(self.settings.base_url, self.settings.initiate_path)
+        return _request_with_retries(
+            "POST",
+            url,
+            payload,
+            self.settings,
+        )
+
+    def poll_status(self, claim_token: str) -> Dict[str, Any]:
+        url = _join_url(
+            self.settings.base_url,
+            self.settings.status_path.format(token=claim_token),
+        )
+        deadline = time.time() + max(self.settings.timeout_s, 0)
+        interval = max(self.settings.poll_interval_s, 0.1)
+
+        while time.time() <= deadline:
+            payload = _request_with_retries("GET", url, None, self.settings)
+            status = str(payload.get("status", "pending")).lower()
+            if status == "claimed":
+                logger.info("Claim approved for token %s", claim_token)
+                return payload
+            if status in {"expired", "rejected", "failed"}:
+                raise ClaimError(f"Claim {status} for token {claim_token}")
+            time.sleep(interval)
+
+        raise ClaimTimeout("Timed out waiting for claim acceptance")
+
+    def get_status(self, claim_token: str) -> Dict[str, Any]:
+        url = _join_url(
+            self.settings.base_url,
+            self.settings.status_path.format(token=claim_token),
+        )
+        return _request_with_retries("GET", url, None, self.settings)
+
+
+def _extract_credentials(payload: Dict[str, Any]) -> Dict[str, Any]:
+    if isinstance(payload.get("credentials"), dict):
+        return payload["credentials"]
+    keys = (
+        "broker_url",
+        "device_id",
+        "api_key",
+        "username",
+        "password",
+        "client_id",
+        "telemetry_topic",
+        "heartbeat_topic",
+        "rpc_request_topic",
+        "rpc_response_topic",
+        "keepalive",
+    )
+    credentials = {key: payload.get(key) for key in keys if payload.get(key) is not None}
+    return credentials
+
+
+def _request_with_retries(
+    method: str,
+    url: str,
+    payload: Optional[Dict[str, Any]],
+    settings: ClaimSettings,
+) -> Dict[str, Any]:
+    attempt = 0
+    while True:
+        try:
+            return _request_json(method, url, payload, settings.request_timeout_s)
+        except urllib.error.HTTPError as exc:
+            if _is_retryable_http_error(exc) and attempt < settings.max_retries:
+                _sleep_backoff(attempt, settings.backoff_s)
+                attempt += 1
+                continue
+            raise ClaimHttpError(
+                exc.code, f"Claim request failed with HTTP {exc.code}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            if attempt < settings.max_retries:
+                _sleep_backoff(attempt, settings.backoff_s)
+                attempt += 1
+                continue
+            raise ClaimError("Claim request failed due to network error") from exc
+
+
+def _request_json(
+    method: str,
+    url: str,
+    payload: Optional[Dict[str, Any]],
+    timeout_s: float,
+) -> Dict[str, Any]:
+    data = None
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": f"enigmind-agent/{__version__}",
+    }
+    if payload is not None:
+        data = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+
+    request = urllib.request.Request(url, data=data, method=method.upper())
+    for key, value in headers.items():
+        request.add_header(key, value)
+
+    with urllib.request.urlopen(request, timeout=timeout_s) as response:
+        body = response.read()
+        if not body:
+            return {}
+        return json.loads(body.decode("utf-8"))
+
+
+def _is_retryable_http_error(error: urllib.error.HTTPError) -> bool:
+    return error.code in {408, 425, 429} or 500 <= error.code <= 599
+
+
+def _sleep_backoff(attempt: int, backoff_s: float) -> None:
+    delay = backoff_s * (2**attempt)
+    if delay > 0:
+        time.sleep(delay)
+
+
+def _join_url(base_url: str, path: str) -> str:
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"

enigmind_agent/cli.py

@@ -0,0 +1,128 @@
+import json
+import logging
+import time
+from typing import Optional
+
+import typer
+from rich import print as rprint
+
+from .agent import Agent
+from .claim import ClaimClient, ClaimError, ClaimSettings
+from .config import AgentConfig
+from .plugins.health import HealthPlugin
+from .storage import StateStore
+
+app = typer.Typer(help="Enigmind Agent CLI")
+claim_app = typer.Typer(help="Device claim helpers")
+
+
+@app.callback()
+def main(verbose: bool = typer.Option(False, "--verbose", help="Enable debug logging")) -> None:
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(level=level, format="%(message)s")
+
+
+def _load_config(path: Optional[str]) -> AgentConfig:
+    if path:
+        return AgentConfig.from_file(path)
+    return AgentConfig.from_env()
+
+
+@app.command("send")
+def send_command(
+    data: str = typer.Option(..., "--data", help="Telemetry JSON payload"),
+    config: Optional[str] = typer.Option(None, "--config", help="Path to config JSON"),
+) -> None:
+    payload = json.loads(data)
+    agent = Agent(_load_config(config))
+    agent.start()
+    agent.send_telemetry(payload, force=True)
+    time.sleep(0.5)
+    agent.stop()
+    rprint("[green]Sent telemetry[/green]")
+
+
+@app.command("status")
+def status_command(
+    config: Optional[str] = typer.Option(None, "--config", help="Path to config JSON"),
+    health: bool = typer.Option(False, "--health", help="Include health metrics"),
+) -> None:
+    cfg = _load_config(config)
+    agent = Agent(cfg)
+    rprint({
+        "broker": cfg.broker_url,
+        "client_id": cfg.client_id,
+        "telemetry_topic": cfg.telemetry_topic,
+        "buffered": agent.buffer_count(),
+    })
+    if health:
+        plugin = HealthPlugin()
+        rprint(plugin.collect_telemetry())
+
+
+@app.command("run")
+def run_command(
+    config: Optional[str] = typer.Option(None, "--config", help="Path to config JSON"),
+) -> None:
+    cfg = _load_config(config)
+    agent = Agent(cfg)
+    try:
+        agent.start()
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        agent.stop()
+
+
+@claim_app.command("status")
+def claim_status_command(
+    config: Optional[str] = typer.Option(None, "--config", help="Path to config JSON"),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="Override claim base URL"),
+) -> None:
+    cfg = _load_config(config)
+    claim_cfg = cfg.claim
+    base_url = base_url or claim_cfg.base_url
+    store = StateStore(claim_cfg.state_path)
+    state = store.load()
+    if not state.claim_token:
+        rprint("[yellow]No claim token found locally.[/yellow]")
+        return
+
+    output = {
+        "token": state.claim_token,
+        "hardware_id": state.hardware_id,
+        "credentials": "stored" if state.credentials else "missing",
+    }
+
+    if not base_url:
+        output["status"] = "unknown (missing claim base URL)"
+        rprint(output)
+        return
+
+    settings = ClaimSettings(
+        base_url=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,
+    )
+    client = ClaimClient(settings)
+    try:
+        status_payload = client.get_status(state.claim_token)
+        output["status"] = status_payload.get("status", "unknown")
+    except ClaimError as exc:
+        output["status_error"] = str(exc)
+    rprint(output)
+
+
+app.add_typer(claim_app, name="claim")
+
+
+if __name__ == "__main__":
+    app()

enigmind_agent/config.py

@@ -0,0 +1,158 @@
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+from urllib.parse import urlparse
+
+from platformdirs import user_data_dir
+
+
+@dataclass
+class TLSConfig:
+    ca_cert: Optional[str] = None
+    client_cert: Optional[str] = None
+    client_key: Optional[str] = None
+    insecure: bool = False
+
+
+@dataclass
+class ClaimConfig:
+    base_url: Optional[str] = None
+    initiate_path: str = "/api/claims/initiate"
+    status_path: str = "/api/claims/{token}/status"
+    poll_interval_s: int = 5
+    timeout_s: int = 300
+    request_timeout_s: int = 5
+    max_retries: int = 3
+    backoff_s: float = 1.0
+    state_path: Optional[str] = None
+
+
+@dataclass
+class AgentConfig:
+    broker_url: str
+    device_id: Optional[str] = None
+    api_key: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+    client_id: Optional[str] = None
+    keepalive: int = 60
+    telemetry_topic: str = "v1/devices/me/telemetry"
+    heartbeat_topic: str = "v1/devices/me/telemetry"
+    rpc_request_topic: str = "v1/devices/me/rpc/request/+"
+    rpc_response_topic: str = "v1/devices/me/rpc/response/{request_id}"
+    heartbeat_interval_s: int = 60
+    buffer_path: Optional[str] = None
+    delta_sync: bool = True
+    tls: TLSConfig = field(default_factory=TLSConfig)
+    claim: ClaimConfig = field(default_factory=ClaimConfig)
+
+    def normalized(self) -> "AgentConfig":
+        if not self.client_id:
+            self.client_id = self.device_id or "enigmind-agent"
+        if not self.username and self.device_id:
+            self.username = self.device_id
+        if not self.password and self.api_key:
+            self.password = self.api_key
+        if not self.buffer_path:
+            data_dir = user_data_dir("enigmind_agent")
+            self.buffer_path = os.path.join(data_dir, "buffer.db")
+        return self
+
+    def broker_host_port(self) -> Dict[str, Any]:
+        parsed = urlparse(self.broker_url)
+        host = parsed.hostname or self.broker_url
+        port = parsed.port
+        use_tls = parsed.scheme in ("mqtts", "ssl", "tls")
+        if not port:
+            port = 8883 if use_tls else 1883
+        return {"host": host, "port": port, "use_tls": use_tls}
+
+    def has_credentials(self) -> bool:
+        return bool(self.device_id and (self.api_key or self.password))
+
+    @staticmethod
+    def from_env(prefix: str = "ENIGMIND_") -> "AgentConfig":
+        def env(key: str, default: Optional[str] = None) -> Optional[str]:
+            return os.getenv(prefix + key, default)
+
+        cfg = AgentConfig(
+            broker_url=env("BROKER_URL", "mqtt://localhost:1883"),
+            device_id=env("DEVICE_ID"),
+            api_key=env("API_KEY"),
+            username=env("USERNAME"),
+            password=env("PASSWORD"),
+            client_id=env("CLIENT_ID"),
+            telemetry_topic=env("TELEMETRY_TOPIC", "v1/devices/me/telemetry"),
+            heartbeat_topic=env("HEARTBEAT_TOPIC", "v1/devices/me/telemetry"),
+            rpc_request_topic=env("RPC_REQUEST_TOPIC", "v1/devices/me/rpc/request/+"),
+            rpc_response_topic=env("RPC_RESPONSE_TOPIC", "v1/devices/me/rpc/response/{request_id}"),
+        )
+        cfg.heartbeat_interval_s = int(env("HEARTBEAT_INTERVAL_S", "60"))
+        cfg.keepalive = int(env("KEEPALIVE", "60"))
+        cfg.delta_sync = env("DELTA_SYNC", "true").lower() == "true"
+        cfg.buffer_path = env("BUFFER_PATH")
+        cfg.tls = TLSConfig(
+            ca_cert=env("TLS_CA_CERT"),
+            client_cert=env("TLS_CLIENT_CERT"),
+            client_key=env("TLS_CLIENT_KEY"),
+            insecure=env("TLS_INSECURE", "false").lower() == "true",
+        )
+        cfg.claim = ClaimConfig(
+            base_url=env("CLAIM_BASE_URL"),
+            initiate_path=env("CLAIM_INITIATE_PATH", "/api/claims/initiate"),
+            status_path=env("CLAIM_STATUS_PATH", "/api/claims/{token}/status"),
+            poll_interval_s=int(env("CLAIM_POLL_INTERVAL_S", "5")),
+            timeout_s=int(env("CLAIM_TIMEOUT_S", "300")),
+            request_timeout_s=int(env("CLAIM_REQUEST_TIMEOUT_S", "5")),
+            max_retries=int(env("CLAIM_MAX_RETRIES", "3")),
+            backoff_s=float(env("CLAIM_BACKOFF_S", "1.0")),
+            state_path=env("CLAIM_STATE_PATH"),
+        )
+        return cfg.normalized()
+
+    @staticmethod
+    def from_file(path: str) -> "AgentConfig":
+        with open(path, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+        delta_sync = data.get("delta_sync", True)
+        if isinstance(delta_sync, str):
+            delta_sync = delta_sync.lower() == "true"
+        tls_insecure = data.get("tls", {}).get("insecure", False)
+        if isinstance(tls_insecure, str):
+            tls_insecure = tls_insecure.lower() == "true"
+        claim = data.get("claim", {})
+        cfg = AgentConfig(
+            broker_url=data["broker_url"],
+            device_id=data.get("device_id"),
+            api_key=data.get("api_key"),
+            username=data.get("username"),
+            password=data.get("password"),
+            client_id=data.get("client_id"),
+            keepalive=int(data.get("keepalive", 60)),
+            telemetry_topic=data.get("telemetry_topic", "v1/devices/me/telemetry"),
+            heartbeat_topic=data.get("heartbeat_topic", "v1/devices/me/telemetry"),
+            rpc_request_topic=data.get("rpc_request_topic", "v1/devices/me/rpc/request/+"),
+            rpc_response_topic=data.get("rpc_response_topic", "v1/devices/me/rpc/response/{request_id}"),
+            heartbeat_interval_s=int(data.get("heartbeat_interval_s", 60)),
+            buffer_path=data.get("buffer_path"),
+            delta_sync=bool(delta_sync),
+            tls=TLSConfig(
+                ca_cert=data.get("tls", {}).get("ca_cert"),
+                client_cert=data.get("tls", {}).get("client_cert"),
+                client_key=data.get("tls", {}).get("client_key"),
+                insecure=bool(tls_insecure),
+            ),
+            claim=ClaimConfig(
+                base_url=claim.get("base_url"),
+                initiate_path=claim.get("initiate_path", "/api/claims/initiate"),
+                status_path=claim.get("status_path", "/api/claims/{token}/status"),
+                poll_interval_s=int(claim.get("poll_interval_s", 5)),
+                timeout_s=int(claim.get("timeout_s", 300)),
+                request_timeout_s=int(claim.get("request_timeout_s", 5)),
+                max_retries=int(claim.get("max_retries", 3)),
+                backoff_s=float(claim.get("backoff_s", 1.0)),
+                state_path=claim.get("state_path"),
+            ),
+        )
+        return cfg.normalized()

enigmind_agent/delta.py

@@ -0,0 +1,18 @@
+from typing import Dict, Tuple
+
+
+class DeltaFilter:
+    def __init__(self) -> None:
+        self._last: Dict[str, object] = {}
+
+    def diff(self, payload: Dict[str, object]) -> Tuple[Dict[str, object], bool]:
+        changed: Dict[str, object] = {}
+        for key, value in payload.items():
+            if key not in self._last or self._last[key] != value:
+                changed[key] = value
+        if changed:
+            self._last.update(changed)
+        return changed, bool(changed)
+
+    def reset(self) -> None:
+        self._last.clear()

enigmind_agent/mqtt.py

@@ -0,0 +1,92 @@
+import json
+import ssl
+import threading
+from typing import Any, Callable, Optional
+
+import paho.mqtt.client as mqtt
+
+from .config import AgentConfig
+
+
+MessageHandler = Callable[[str, bytes], None]
+ConnectHandler = Callable[[], None]
+
+
+class MQTTClient:
+    def __init__(
+        self,
+        config: AgentConfig,
+        on_message: Optional[MessageHandler] = None,
+        on_connect: Optional[ConnectHandler] = None,
+    ) -> None:
+        self.config = config
+        self.on_message = on_message
+        self.on_connect = on_connect
+        self._client = mqtt.Client(
+            client_id=self.config.client_id,
+            protocol=mqtt.MQTTv5,
+        )
+        self._connected = threading.Event()
+        self._setup_client()
+
+    @property
+    def connected(self) -> bool:
+        return self._connected.is_set()
+
+    def _setup_client(self) -> None:
+        if self.config.username or self.config.password:
+            self._client.username_pw_set(self.config.username, self.config.password)
+
+        self._client.on_connect = self._handle_connect
+        self._client.on_disconnect = self._handle_disconnect
+        self._client.on_message = self._handle_message
+
+        if self.config.tls:
+            self._configure_tls()
+
+    def _configure_tls(self) -> None:
+        use_tls = self.config.broker_host_port().get("use_tls", False)
+        if not use_tls and not (self.config.tls.ca_cert or self.config.tls.client_cert):
+            return
+        self._client.tls_set(
+            ca_certs=self.config.tls.ca_cert,
+            certfile=self.config.tls.client_cert,
+            keyfile=self.config.tls.client_key,
+            cert_reqs=ssl.CERT_REQUIRED if not self.config.tls.insecure else ssl.CERT_NONE,
+            tls_version=ssl.PROTOCOL_TLS_CLIENT,
+        )
+        if self.config.tls.insecure:
+            self._client.tls_insecure_set(True)
+
+    def connect(self) -> None:
+        broker = self.config.broker_host_port()
+        self._client.connect(broker["host"], broker["port"], keepalive=self.config.keepalive)
+        self._client.loop_start()
+
+    def disconnect(self) -> None:
+        self._client.loop_stop()
+        self._client.disconnect()
+        self._connected.clear()
+
+    def subscribe(self, topic: str, qos: int = 0) -> None:
+        self._client.subscribe(topic, qos=qos)
+
+    def publish(self, topic: str, payload: dict, qos: int = 0, retain: bool = False) -> bool:
+        data = json.dumps(payload, separators=(",", ":"))
+        result = self._client.publish(topic, data, qos=qos, retain=retain)
+        return result.rc == mqtt.MQTT_ERR_SUCCESS
+
+    def _handle_connect(self, client: mqtt.Client, userdata: Any, flags: dict, reason_code: int, properties: Any = None) -> None:
+        if reason_code == 0:
+            self._connected.set()
+            if self.on_connect:
+                self.on_connect()
+        else:
+            self._connected.clear()
+
+    def _handle_disconnect(self, client: mqtt.Client, userdata: Any, reason_code: int, properties: Any = None) -> None:
+        self._connected.clear()
+
+    def _handle_message(self, client: mqtt.Client, userdata: Any, msg: mqtt.MQTTMessage) -> None:
+        if self.on_message:
+            self.on_message(msg.topic, msg.payload)

enigmind_agent/plugins/__init__.py

@@ -0,0 +1,5 @@
+from .base import Plugin
+from .geo import GeoPlugin
+from .health import HealthPlugin
+
+__all__ = ["Plugin", "GeoPlugin", "HealthPlugin"]

enigmind_agent/plugins/base.py

@@ -0,0 +1,14 @@
+from typing import Dict
+
+
+class Plugin:
+    name = "base"
+
+    def on_start(self, agent: "Agent") -> None:
+        return None
+
+    def on_stop(self, agent: "Agent") -> None:
+        return None
+
+    def collect_telemetry(self) -> Dict[str, object]:
+        return {}

enigmind_agent/plugins/geo.py

@@ -0,0 +1,78 @@
+import math
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Optional, Tuple
+
+from .base import Plugin
+
+
+GeoEventHandler = Callable[[str, str, Dict[str, float]], None]
+
+
+@dataclass
+class CircleFence:
+    center_lat: float
+    center_lon: float
+    radius_m: float
+
+
+@dataclass
+class PolygonFence:
+    points: List[Tuple[float, float]]
+
+
+class GeoPlugin(Plugin):
+    name = "geo"
+
+    def __init__(self, on_event: Optional[GeoEventHandler] = None) -> None:
+        self._circles: Dict[str, CircleFence] = {}
+        self._polygons: Dict[str, PolygonFence] = {}
+        self._state: Dict[str, bool] = {}
+        self._on_event = on_event
+
+    def add_circle(self, geofence_id: str, center_lat: float, center_lon: float, radius_m: float) -> None:
+        self._circles[geofence_id] = CircleFence(center_lat, center_lon, radius_m)
+
+    def add_polygon(self, geofence_id: str, points: List[Tuple[float, float]]) -> None:
+        self._polygons[geofence_id] = PolygonFence(points)
+
+    def process_position(self, lat: float, lon: float) -> None:
+        for geofence_id, fence in self._circles.items():
+            inside = _haversine_m(lat, lon, fence.center_lat, fence.center_lon) <= fence.radius_m
+            self._emit_if_changed(geofence_id, inside, lat, lon)
+        for geofence_id, fence in self._polygons.items():
+            inside = _point_in_polygon(lat, lon, fence.points)
+            self._emit_if_changed(geofence_id, inside, lat, lon)
+
+    def _emit_if_changed(self, geofence_id: str, inside: bool, lat: float, lon: float) -> None:
+        prev = self._state.get(geofence_id)
+        if prev is None or prev != inside:
+            self._state[geofence_id] = inside
+            if self._on_event:
+                event = "enter" if inside else "exit"
+                self._on_event(geofence_id, event, {"lat": lat, "lon": lon})
+
+
+def _haversine_m(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    r = 6371000.0
+    phi1 = math.radians(lat1)
+    phi2 = math.radians(lat2)
+    dphi = math.radians(lat2 - lat1)
+    dlambda = math.radians(lon2 - lon1)
+
+    a = math.sin(dphi / 2) ** 2 + math.cos(phi1) * math.cos(phi2) * math.sin(dlambda / 2) ** 2
+    return 2 * r * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+
+
+def _point_in_polygon(lat: float, lon: float, points: List[Tuple[float, float]]) -> bool:
+    inside = False
+    j = len(points) - 1
+    for i in range(len(points)):
+        yi, xi = points[i]
+        yj, xj = points[j]
+        intersects = ((xi > lon) != (xj > lon)) and (
+            lat < (yj - yi) * (lon - xi) / (xj - xi + 1e-12) + yi
+        )
+        if intersects:
+            inside = not inside
+        j = i
+    return inside

enigmind_agent/plugins/health.py

@@ -0,0 +1,24 @@
+from typing import Dict
+
+from .base import Plugin
+
+
+class HealthPlugin(Plugin):
+    name = "health"
+
+    def __init__(self) -> None:
+        try:
+            import psutil  # noqa: F401
+        except Exception as exc:  # pragma: no cover
+            raise RuntimeError("psutil is required for HealthPlugin. Install with enigmind-agent[health].") from exc
+
+    def collect_telemetry(self) -> Dict[str, object]:
+        import psutil
+
+        mem = psutil.virtual_memory()
+        disk = psutil.disk_usage("/")
+        return {
+            "cpu_percent": psutil.cpu_percent(interval=None),
+            "mem_percent": mem.percent,
+            "disk_percent": disk.percent,
+        }

enigmind_agent/rpc.py

@@ -0,0 +1,34 @@
+import json
+from typing import Any, Callable, Dict, Optional
+
+
+RpcHandler = Callable[[Any], Any]
+
+
+class RpcRouter:
+    def __init__(self) -> None:
+        self._handlers: Dict[str, RpcHandler] = {}
+
+    def register(self, method: str, handler: RpcHandler) -> None:
+        self._handlers[method] = handler
+
+    def handle(self, payload: bytes) -> Optional[Dict[str, Any]]:
+        try:
+            message = json.loads(payload.decode("utf-8"))
+        except json.JSONDecodeError:
+            return {"error": "invalid_json"}
+
+        method = message.get("method")
+        if not method:
+            return {"error": "missing_method"}
+
+        handler = self._handlers.get(method)
+        if not handler:
+            return {"error": "unknown_method", "method": method}
+
+        params = message.get("params")
+        try:
+            result = handler(params)
+            return {"result": result}
+        except Exception as exc:
+            return {"error": "handler_error", "message": str(exc)}

enigmind_agent/storage.py

@@ -0,0 +1,62 @@
+import json
+import os
+import threading
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from platformdirs import user_data_dir
+
+
+def default_state_path() -> str:
+    data_dir = user_data_dir("enigmind_agent")
+    return os.path.join(data_dir, "state.json")
+
+
+@dataclass
+class ClaimState:
+    hardware_id: Optional[str] = None
+    claim_token: Optional[str] = None
+    credentials: Optional[Dict[str, Any]] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ClaimState":
+        return cls(
+            hardware_id=data.get("hardware_id"),
+            claim_token=data.get("claim_token"),
+            credentials=data.get("credentials"),
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "hardware_id": self.hardware_id,
+            "claim_token": self.claim_token,
+            "credentials": self.credentials,
+        }
+
+
+class StateStore:
+    def __init__(self, path: Optional[str] = None) -> None:
+        self.path = path or default_state_path()
+        self._lock = threading.Lock()
+
+    def load(self) -> ClaimState:
+        if not os.path.exists(self.path):
+            return ClaimState()
+        with self._lock, open(self.path, "r", encoding="utf-8") as handle:
+            try:
+                data = json.load(handle)
+            except json.JSONDecodeError:
+                return ClaimState()
+        if not isinstance(data, dict):
+            return ClaimState()
+        return ClaimState.from_dict(data)
+
+    def save(self, state: ClaimState) -> None:
+        directory = os.path.dirname(self.path)
+        if directory:
+            os.makedirs(directory, exist_ok=True)
+        payload = state.to_dict()
+        temp_path = f"{self.path}.tmp"
+        with self._lock, open(temp_path, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, indent=2, sort_keys=True)
+        os.replace(temp_path, self.path)

enigmind_agent/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

enigmind_agent-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+enigmind_agent/__init__.py,sha256=0BIr0ON2rTWjEKov5BgNgvgKN6v1lJRGCsvQXI6AnOU,404
+enigmind_agent/agent.py,sha256=iDxgYD7L_c9qzs8mMgbjs7Vr4qKddyAPXtrxa3uLtuo,6213
+enigmind_agent/buffer.py,sha256=Is70Sh_RvaNScF46xGn7jDI7tyQptz65jhxmA4HR8d4,2584
+enigmind_agent/claim.py,sha256=HFIxkE94sljKENVWQlYnciyQWNoHTwiWMvICN5dRg1M,7603
+enigmind_agent/cli.py,sha256=CkaDn5ssIRc99X_3NT0vmzgdYPKf6ms_ikrb7Z-fSYI,3698
+enigmind_agent/config.py,sha256=oMHPiK8P5bXWZCh0FMNrFXVRV_ogMSQTXlBjmiQN_mc,6674
+enigmind_agent/delta.py,sha256=LOU-RIkf2re1jtkFFK5phMaXWnk_9rjd5kzu_H1EGAY,550
+enigmind_agent/mqtt.py,sha256=WDqKVVQ7IsnckWMpP4Vp6NU6XeoUf14DqTG3LGVGH1g,3236
+enigmind_agent/rpc.py,sha256=CuBqMSV8BEgz7hPdBzo3kvAtnoj-EuGWVQrEAaLT_U0,1000
+enigmind_agent/storage.py,sha256=uCNd4yR-ohRPJZZ46UB00wQef49NxkDaz2-qIyjRvaw,1919
+enigmind_agent/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+enigmind_agent/plugins/__init__.py,sha256=zXAv_aXezPQ3wV-nuK4KSqmO4pzN3xlsD1yN5m4XKag,136
+enigmind_agent/plugins/base.py,sha256=VmvGC5wTpqW9NTxJQ507xRni6gaDiFuAvd52dIyFxY0,268
+enigmind_agent/plugins/geo.py,sha256=ppXxZYBJExaANOHK0ZaMvondZ7KM8U_pC3TJ7VdlXc0,2697
+enigmind_agent/plugins/health.py,sha256=1ha3uCJVbHszpw64ypP9k6U5eax1L2eI2zn9WX2zrBM,681
+enigmind_agent-0.1.0.dist-info/METADATA,sha256=KDkv2SoMQnL58Da43sWqoRdMYZScjF_fh2tyYqdoM6g,3304
+enigmind_agent-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+enigmind_agent-0.1.0.dist-info/entry_points.txt,sha256=HHLuxFnnWhnsdPagMMmGzrKK4ufOm-EfzwspTYTkox0,56
+enigmind_agent-0.1.0.dist-info/top_level.txt,sha256=SKGLe5AlvutKnHqVBsil43qx9YLn73I1Hw-RDBJy_Kw,15
+enigmind_agent-0.1.0.dist-info/RECORD,,

enigmind_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

enigmind_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+enigmind-cli = enigmind_agent.cli:app

enigmind_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+enigmind_agent