artificialbrains-sdk 0.1.0__py3-none-any.whl

ab_sdk/__init__.py

@@ -0,0 +1,63 @@
+"""
+Top-level package for ArtificialBrains Python SDK.
+
+This package provides a client and helper classes to interact with the
+ArtificialBrains server over HTTP and realtime (Socket.IO/WebSocket-style)
+events. The SDK wraps the low-level REST + realtime protocols so developers
+can focus on:
+- providing sensor inputs (camera, depth, etc.)
+- turning brain outputs (spikes) into actuator commands
+- defining reward / feedback (optional)
+
+High-level imports (recommended):
+
+    from ab_sdk import ABClient, RunSession, InputStreamer, RobotLoop
+
+Decoding output spikes (robot-agnostic):
+
+    from ab_sdk.plugins.decoder import MappingEntry, decode_stream_rows
+
+Optional convenience helper (if your robot uses dq/dg style):
+
+    from ab_sdk.plugins.decoder import deltas_to_dq_dg
+
+Reward / deviation plugins (optional defaults):
+
+    from ab_sdk.plugins.deviation import DefaultDeviation
+    from ab_sdk.plugins.reward import DefaultReward
+"""
+
+from .client import ABClient  # noqa: F401
+from .run_session import RunSession  # noqa: F401
+from .input_streamer import InputStreamer  # noqa: F401
+from .robot_loop import RobotLoop  # noqa: F401
+
+# plugins (robot-agnostic decoding)
+from .plugins.decoder import (  # noqa: F401
+    MappingEntry,
+    decode_stream_rows,
+    deltas_to_dq_dg,
+)
+
+# contract + policy scaffolding
+from .contract_scaffold import sync_policies_from_contract  # noqa: F401
+
+# optional defaults (policies)
+from .plugins.deviation import DefaultDeviation  # noqa: F401
+from .plugins.reward import DefaultReward  # noqa: F401
+
+__all__ = [
+    "ABClient",
+    "RunSession",
+    "InputStreamer",
+    "RobotLoop",
+    # decoder plugin
+    "MappingEntry",
+    "decode_stream_rows",
+    "deltas_to_dq_dg",
+    # scaffolding
+    "sync_policies_from_contract",
+    # policies
+    "DefaultDeviation",
+    "DefaultReward",
+]

ab_sdk/client.py

@@ -0,0 +1,270 @@
+"""HTTP and realtime client for ArtificialBrains.
+
+This module defines the :class:`ABClient` class which wraps the REST
+endpoints exposed by the Artificial Brains server and manages the
+underlying realtime (Socket.IO) connection.  It is responsible for
+starting and stopping runs, querying the current input state and
+creating :class:`~ab_sdk.run_session.RunSession` instances which
+encapsulate per‑run state and socket clients.  You should not need to
+deal with low level HTTP or Socket.IO interactions outside of this
+class.
+
+Usage example::
+
+    from ab_sdk import ABClient
+
+    client = ABClient("https://brains.example.com/api", api_key="your_key")
+    run = client.start("my_project")
+    # ... attach sensors, run loop ...
+    client.stop("my_project")
+
+The `start` method returns a :class:`~ab_sdk.run_session.RunSession` object
+containing the run contract (IO manifest, constants) and a Socket.IO
+client already joined to the run room.  See the documentation on
+`RunSession` for details.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+import socketio
+
+from .run_session import RunSession
+from . import endpoints
+from .contract_scaffold import sync_policies_from_contract
+
+logger = logging.getLogger(__name__)
+
+
+class ABClient:
+    """Client for interacting with the Artificial Brains backend.
+
+    Auth:
+      - This SDK always sends your machine API key on *every* HTTP request using:
+          * `x-api-key: <key>`  (preferred by the server)
+        and also:
+          * `Authorization: Bearer <key>` (accepted by the server as a fallback)
+
+    Base URL:
+      - Provide either:
+          * https://artificialbrains.app/api
+          * http://localhost:3000/api
+        If you pass a host without `/api`, the client will append `/api` automatically.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: Optional[str] = None,
+        timeout: float = 10.0,
+        socket_namespace: str = "/ab",
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url must be provided")
+
+        base = base_url.rstrip("/")
+        # Accept either host root or /api, but store a base_url that ends with /api.
+        if not base.endswith("/api"):
+            base = base + "/api"
+
+        self.base_url = base
+        self.api_key = api_key or None
+        self.timeout = timeout
+        self.socket_namespace = socket_namespace
+
+        headers: Dict[str, str] = {}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        # httpx base_url joins *relative* paths; leading '/' would reset the path.
+        self._http = httpx.Client(base_url=self.base_url, headers=headers, timeout=timeout)
+        logger.debug("ABClient initialized with base_url=%s", self.base_url)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Internal helper for sending HTTP requests."""
+        url = path.lstrip("/")  # preserve /api prefix in base_url
+        try:
+            response = self._http.request(method, url, **kwargs)
+            response.raise_for_status()
+            return response
+        except httpx.HTTPStatusError as exc:
+            logger.error("HTTP error: %s", exc)
+            raise
+        except httpx.RequestError as exc:
+            logger.error("Request failed: %s", exc)
+            raise
+
+    def start(self, project_id: str, **kwargs: Any) -> RunSession:
+        """Start a new run and connect to realtime."""
+        if not project_id:
+            raise ValueError("project_id must be provided")
+
+        path = endpoints.START_RUN.format(project_id=project_id)
+        logger.info("Starting run for project %s", project_id)
+        response = self._request("POST", path, json=kwargs or {})
+        contract = response.json()
+
+        run_id = contract.get("runId")
+        if not run_id:
+            raise ValueError("start response missing 'runId'")
+
+        # Determine Socket.IO connection details
+        rt_info = contract.get("realtime", {}) or {}
+        ns = rt_info.get("namespace", self.socket_namespace)
+        url = rt_info.get("url")
+
+        if not url:
+            # derive host root from base_url (/api stripped)
+            url = self.base_url[:-4] if self.base_url.endswith("/api") else self.base_url
+
+        socket = socketio.Client(reconnection=True, logger=False, engineio_logger=False)
+
+        connect_headers: Dict[str, str] = {}
+        auth_payload: Optional[Dict[str, Any]] = None
+        if self.api_key:
+            connect_headers["x-api-key"] = self.api_key
+            connect_headers["Authorization"] = f"Bearer {self.api_key}"
+            # Some server middleware reads handshake.auth
+            auth_payload = {"token": self.api_key, "apiKey": self.api_key}
+
+        logger.info("Connecting to realtime at %s namespace %s", url, ns)
+         # Helpful visibility: log namespace connect/disconnect
+        @socket.on("connect", namespace=ns)
+        def _on_connect():
+            logger.info("Realtime connected to namespace %s (namespaces=%s)", ns, list(getattr(socket, "namespaces", {}).keys()))
+
+        @socket.on("disconnect", namespace=ns)
+        def _on_disconnect():
+            logger.warning("Realtime disconnected from namespace %s", ns)
+
+        # Robust connect strategy:
+        #  1) Try websocket-only (does NOT require `requests`)
+        #  2) Fallback to default transports (polling+websocket) if needed
+        # Provide a clear error message if dependencies are missing.
+        try:
+            socket.connect(
+                url,
+                headers=connect_headers,
+                auth=auth_payload,
+                namespaces=[ns],
+                transports=["websocket"],
+                wait=True,
+                wait_timeout=self.timeout,
+            )
+        except Exception as e1:
+            # If websocket-client is missing, python-socketio will fail here.
+            # If polling is needed and `requests` is missing, it will fail on fallback.
+            try:
+                socket.connect(
+                    url,
+                    headers=connect_headers,
+                    auth=auth_payload,
+                    namespaces=[ns],
+                    wait=True,
+                    wait_timeout=self.timeout,
+                )
+            except Exception as e2:
+                msg = (
+                    "Realtime connection failed.\n\n"
+                    "Tried websocket-only then default transports.\n\n"
+                    "Common fixes:\n"
+                    "  - pip install websocket-client\n"
+                    "  - pip install requests\n\n"
+                    f"websocket error: {e1}\n"
+                    f"fallback error: {e2}"
+                )
+                raise socketio.exceptions.ConnectionError(msg)
+            
+
+        # HARD ASSERT: the namespace must actually be connected, or emits will fail with:
+        # "/ab is not a connected namespace."
+        namespaces = getattr(socket, "namespaces", {}) or {}
+        if ns not in namespaces:
+            try:
+                socket.disconnect()
+            except Exception:
+                pass
+            raise socketio.exceptions.ConnectionError(
+                f"Socket connected but namespace '{ns}' is NOT connected. Connected namespaces: {list(namespaces.keys())}"
+            )
+        
+        # Join run
+        socket.emit(endpoints.RUN_JOIN_EVENT, {"runId": run_id}, namespace=ns)
+
+        return RunSession(
+            client=self,
+            project_id=project_id,
+            run_id=run_id,
+            contract=contract,
+            socket=socket,
+            namespace=ns,
+        )
+
+    def stop(self, project_id: str, run_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Stops a run on the server.
+
+        NOTE: Your server's stop endpoint expects a body with { runId }.
+        If run_id is not provided, server may not stop anything.
+        """
+        if not project_id:
+            raise ValueError("project_id must be provided")
+
+        path = endpoints.STOP_RUN.format(project_id=project_id)
+        payload: Dict[str, Any] = {}
+        if run_id:
+            payload["runId"] = run_id
+
+        logger.info("Stopping run for project %s runId=%s", project_id, run_id)
+        response = self._request("POST", path, json=payload)
+        return response.json()
+
+    def get_io_state(self, project_id: str) -> Dict[str, Any]:
+        if not project_id:
+            raise ValueError("project_id must be provided")
+        path = endpoints.IO_STATE.format(project_id=project_id)
+        logger.debug("Fetching IO state for project %s", project_id)
+        response = self._request("GET", path)
+        return response.json()
+    
+    def get_contract(self, project_id: str) -> Dict[str, Any]:
+        """
+        Fetch the IO/constants contract without starting a run.
+
+        Requires your server to implement:
+          GET /api/robot/:project_id/contract
+        returning:
+          { ok: true, projectId, constants: {...}, io: {...} }
+        """
+        if not project_id:
+            raise ValueError("project_id must be provided")
+        path = endpoints.CONTRACT.format(project_id=project_id)
+        logger.debug("Fetching contract for project %s", project_id)
+        response = self._request("GET", path)
+        return response.json()
+
+    def sync_policies(self, project_id: str, *, policies_dir: str = "policies") -> Dict[str, Any]:
+        """
+        One command devs can run whenever they want:
+          - overwrites machine-owned contract files
+          - never overwrites user-owned policy files
+        """
+        contract = self.get_contract(project_id)
+        res = sync_policies_from_contract(contract, policies_dir=policies_dir)
+        return {
+            "ok": True,
+            "policiesDir": res.policies_dir,
+            "sha256": res.sha256,
+            "createdRewardPolicy": res.created_reward_policy,
+            "createdDeviationPolicy": res.created_deviation_policy,
+        }
+
+
+    def close(self) -> None:
+        self._http.close()

ab_sdk/contract_scaffold.py

@@ -0,0 +1,315 @@
+# ab_sdk/contract_scaffold.py
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+MACHINE_OWNED_JSON = "_contract.json"
+MACHINE_OWNED_PY = "_contract.py"
+MACHINE_OWNED_SHA = "_contract.sha256"
+
+USER_REWARD_POLICY = "reward_policy.py"
+USER_DEVIATION_POLICY = "error_deviation_policy.py"
+
+
+def _stable_contract_view(contract: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Strip run-specific fields and keep only what a dev needs to write policies.
+    This is what we hash + persist.
+    """
+    io = (contract or {}).get("io") or {}
+    consts = (contract or {}).get("constants") or {}
+
+    # Keep only the things that define the "policy contract"
+    view = {
+        "constants": {
+            "gamma": int(consts.get("gamma", 64)),
+            "outputWindowN": int(consts.get("outputWindowN", 32)),
+            "feedbackN": int(consts.get("feedbackN", 128)),
+            "feedbackT": int(consts.get("feedbackT", consts.get("FEEDBACK_WINDOW_T", 128))),
+        },
+        "io": {
+            "inputs": list(io.get("inputs") or []),
+            "outputs": list(io.get("outputs") or []),
+            "feedback": list(io.get("feedback") or []),
+            "stdp3": {"layers": list(((io.get("stdp3") or {}).get("layers")) or [])},
+        },
+    }
+    return view
+
+
+def _json_bytes(obj: Any) -> bytes:
+    # stable, deterministic serialization
+    s = json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return s.encode("utf-8")
+
+
+def _sha256_hex(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+def _ensure_dir(path: str) -> None:
+    os.makedirs(path, exist_ok=True)
+
+
+def _write_text(path: str, text: str) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(text)
+
+
+def _write_bytes(path: str, b: bytes) -> None:
+    with open(path, "wb") as f:
+        f.write(b)
+
+
+def _exists(path: str) -> bool:
+    try:
+        return os.path.exists(path)
+    except Exception:
+        return False
+
+
+def _render_contract_py(view: Dict[str, Any], sha256_hex: str) -> str:
+    consts = (view.get("constants") or {})
+    io = (view.get("io") or {})
+    inputs = io.get("inputs") or []
+    outputs = io.get("outputs") or []
+    feedback = io.get("feedback") or []
+    stdp_layers = ((io.get("stdp3") or {}).get("layers")) or []
+
+    input_ids = [str(x.get("id")) for x in inputs if isinstance(x, dict) and x.get("id")]
+    output_ids = [str(x.get("id")) for x in outputs if isinstance(x, dict) and x.get("id")]
+    feedback_ids = [str(x.get("id")) for x in feedback if isinstance(x, dict) and x.get("id")]
+
+    # Keep a tiny amount of metadata that’s helpful for policy authors
+    feedback_meta = []
+    for fb in feedback:
+        if not isinstance(fb, dict):
+            continue
+        feedback_meta.append(
+            {
+                "id": str(fb.get("id")),
+                "n": int(fb.get("n", consts.get("feedbackN", 128))),
+                "fromOutput": fb.get("fromOutput"),
+                "outputKind": fb.get("outputKind"),
+            }
+        )
+
+    return f'''"""
+AUTO-GENERATED FILE. DO NOT EDIT.
+
+This file is machine-owned and overwritten whenever you "sync contract".
+It is meant to give developers the IDs they need for:
+- per-layer STDP3 reward (by stdp layer id)
+- per-feedback deviation (by feedback input id)
+
+If this changes, your graph/IO changed. Compare sha256 or diff _contract.json.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Dict, List, Optional, TypedDict
+
+
+CONTRACT_SHA256 = "{sha256_hex}"
+
+# Constants (as reported by server)
+GAMMA: int = {int(consts.get("gamma", 64))}
+OUTPUT_WINDOW_N: int = {int(consts.get("outputWindowN", 32))}
+FEEDBACK_N: int = {int(consts.get("feedbackN", 128))}
+FEEDBACK_T: int = {int(consts.get("feedbackT", 128))}
+
+# IDs you typically need in policies
+INPUT_IDS: List[str] = {input_ids!r}
+OUTPUT_IDS: List[str] = {output_ids!r}
+FEEDBACK_IDS: List[str] = {feedback_ids!r}
+
+# Per-layer reward keys (STDP3)
+STDP3_LAYERS: List[str] = {list(map(str, stdp_layers))!r}
+
+
+class FeedbackInfo(TypedDict, total=False):
+    id: str
+    n: int
+    fromOutput: Optional[str]
+    outputKind: Optional[str]
+
+
+FEEDBACK_INFO: List[FeedbackInfo] = {feedback_meta!r}
+'''
+
+
+def _render_default_reward_policy() -> str:
+    return '''"""
+User-owned policy file (created once; never overwritten).
+
+Implement:
+  compute_reward(summary, stdp_layers) -> (global_reward, by_layer)
+
+- global_reward: float in [0,1] (or whatever your server expects)
+- by_layer: dict mapping STDP3 layer-id -> reward float (same range)
+
+You can import ids from:
+  from policies._contract import STDP3_LAYERS
+
+Note: Keep this deterministic. No RNG here unless you *explicitly* want it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional, Tuple, List
+
+
+@dataclass
+class CycleSummary:
+    # Example fields – you can change these to match your controller summary.
+    startDist: Optional[float] = None
+    endDist: Optional[float] = None
+    success: bool = False
+
+
+def compute_reward(
+    summary: Optional[CycleSummary],
+    *,
+    stdp_layers: List[str],
+) -> Tuple[float, Dict[str, float]]:
+    """
+    Return (global_reward, by_layer).
+
+    Default behavior:
+      - If success: reward = 1.0
+      - Else if distance improved: reward = 0.6
+      - Else: reward = 0.4
+
+    Change freely.
+    """
+    if summary is None:
+        r = 0.5
+    else:
+        if summary.success:
+            r = 1.0
+        elif (summary.startDist is not None and summary.endDist is not None and summary.endDist < summary.startDist):
+            r = 0.6
+        else:
+            r = 0.4
+
+    by_layer = {layer_id: float(r) for layer_id in (stdp_layers or [])}
+    return float(r), by_layer
+'''
+
+
+def _render_default_deviation_policy() -> str:
+    return '''"""
+User-owned policy file (created once; never overwritten).
+
+Goal:
+  For EACH feedback input id (fb.id), produce deviation_f32:
+    dev: list[float] length T, values typically in [-1,1]
+  The server will convert dev into a feedback raster using baseline + your corrections.
+
+You can import ids from:
+  from policies._contract import FEEDBACK_IDS, FEEDBACK_INFO
+
+You decide the meaning of dev[t] (closer/farther, torque error, etc).
+Keep deterministic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+
+@dataclass
+class DeviationContext:
+    """
+    Put whatever you want here: distances by timestep, joint errors, etc.
+    The controller can pass this in when a feedback need arrives.
+    """
+    # Example:
+    dist_by_t: Optional[Dict[int, float]] = None
+
+
+def compute_deviation(
+    feedback_id: str,
+    *,
+    T: int,
+    ctx: Optional[DeviationContext] = None,
+) -> List[float]:
+    """
+    Return dev[t] length T.
+
+    Default is all zeros (no correction).
+    Customize per feedback_id if you want different deviation semantics per channel.
+    """
+    _ = feedback_id
+    _ = ctx
+    return [0.0] * int(T)
+'''
+
+
+@dataclass
+class ScaffoldResult:
+    policies_dir: str
+    wrote_contract: bool
+    created_reward_policy: bool
+    created_deviation_policy: bool
+    sha256: str
+
+
+def sync_policies_from_contract(
+    contract: Dict[str, Any],
+    *,
+    policies_dir: str = "policies",
+) -> ScaffoldResult:
+    """
+    - Always overwrites:
+        policies/_contract.json
+        policies/_contract.py
+        policies/_contract.sha256
+    - Creates once (never overwrites):
+        policies/reward_policy.py
+        policies/error_deviation_policy.py
+    """
+    _ensure_dir(policies_dir)
+
+    view = _stable_contract_view(contract)
+    jb = _json_bytes(view)
+    sha = _sha256_hex(jb)
+
+    # Machine-owned outputs (always overwritten)
+    contract_json_path = os.path.join(policies_dir, MACHINE_OWNED_JSON)
+    contract_py_path = os.path.join(policies_dir, MACHINE_OWNED_PY)
+    contract_sha_path = os.path.join(policies_dir, MACHINE_OWNED_SHA)
+
+    _write_text(contract_json_path, json.dumps(view, indent=2, ensure_ascii=False) + "\n")
+    _write_text(contract_py_path, _render_contract_py(view, sha))
+    _write_text(contract_sha_path, sha + "\n")
+
+    # User-owned policies (create once)
+    reward_path = os.path.join(policies_dir, USER_REWARD_POLICY)
+    dev_path = os.path.join(policies_dir, USER_DEVIATION_POLICY)
+
+    created_reward = False
+    created_dev = False
+
+    if not _exists(reward_path):
+        _write_text(reward_path, _render_default_reward_policy())
+        created_reward = True
+
+    if not _exists(dev_path):
+        _write_text(dev_path, _render_default_deviation_policy())
+        created_dev = True
+
+    return ScaffoldResult(
+        policies_dir=policies_dir,
+        wrote_contract=True,
+        created_reward_policy=created_reward,
+        created_deviation_policy=created_dev,
+        sha256=sha,
+    )

ab_sdk/endpoints.py

@@ -0,0 +1,48 @@
+"""API endpoint definitions.
+
+This module defines the HTTP endpoint paths used by the SDK relative
+to the base URL provided when instantiating :class:`~ab_sdk.client.ABClient`.
+Keeping these values in one place makes it easy to audit and update
+the API surface when the server changes.
+
+Note that all paths are joined to the base URL (for example
+``https://artificialbrains.app/api``) so you should not include
+``/api`` at the beginning when constructing the `ABClient`.
+"""
+
+START_RUN = "/robot/{project_id}/start"
+"""POST start a new run.  Replace ``{project_id}`` with the target project identifier."""
+
+STOP_RUN = "/robot/{project_id}/stop"
+"""POST stop the current run for the project.  Safe to call even if no run is active."""
+
+IO_STATE = "/robot/{project_id}/io/state"
+"""GET fetch the current IO state (needed inputs, cycle, etc.) for resynchronization."""
+
+# The following endpoints are used implicitly via Socket.IO events.  They are
+# documented here for completeness; your backend should implement the
+# corresponding handlers on its realtime gateway.
+
+RUN_JOIN_EVENT = "run:join"
+"""Client emits this event to join the room for a given run ID."""
+
+IO_NEED_EVENT = "io:need"
+"""Server emits this event to inform the client which inputs are needed for the next cycle."""
+
+IO_CHUNK_EVENT = "io:chunk"
+"""Client emits this event to send raw input data (image/audio/lidar/etc.) or feedback rasters."""
+
+ROBOT_STATE_EVENT = "robot:state"
+"""Client emits this event periodically with the robot's current joint positions, velocities and gripper state."""
+
+ROBOT_CMD_EVENT = "robot:cmd"
+"""Server may emit this legacy event with direct joint commands.  Newer versions omit this in favour of decoding on the client."""
+
+CYCLE_UPDATE_EVENT = "cycle:update"
+"""Server emits this event after each cycle with the latest telemetry (spike activity, error, etc.)."""
+
+LEARN_REWARD_EVENT = "learn:reward"
+"""Client emits this event with global and per‑layer reward values for STDP3 learning."""
+
+CONTRACT = "/robot/{project_id}/contract"
+"""GET fetch the IO/constants contract without starting a run."""