hivemind-sdk 0.1.0__tar.gz

hivemind_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: hivemind-sdk
+Version: 0.1.0
+Summary: Client SDK for HiveMind: persistent shared memory and a working-context compiler for agent systems.
+Author-email: "Militant.AI" <support@militant.ai>
+License: Proprietary
+Project-URL: Homepage, https://hivemind.militant.ai
+Project-URL: Documentation, https://hivemind.militant.ai/docs
+Keywords: ai,agents,memory,llm,context,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# HiveMind Python SDK
+
+Persistent memory and a working-context compiler for your agent, in three
+lines inside your own loop. Your model, your key — HiveMind never calls an
+LLM.
+
+```bash
+pip install hivemind-sdk
+```
+
+Python ≥ 3.10, zero dependencies. The import name is `hivemind`.
+Docs: https://hivemind.militant.ai/docs
+
+```python
+from hivemind import HiveMind
+
+mind = HiveMind(base_url="...", api_key="...", tenant_id="...")
+session = mind.session(budget_total=8192)
+
+result = session.turn(user_input)       # store -> recall -> compile
+reply = call_your_llm(result.messages)  # your model, your key
+session.record(reply)                   # completes the exchange
+```
+
+## What one `turn()` does
+
+1. Stores the user message (receipted).
+2. Semantically recalls relevant memories and past conversation.
+3. Compiles local history + recalled records + active holds + your
+   operator briefing into a token-budgeted bundle.
+
+`result.messages` is the **entire** prompt payload — send it as-is, splice
+nothing in. `result.bundle["decisions"]` explains every admission under
+the budget; `result.receipt` is the audit record. Empty recall on a young
+tenant is normal, not an error.
+
+`session.record(reply)` stores your model's reply as the other half of the
+exchange, so the next turn — and every future session — remembers it.
+
+## Beyond the loop
+
+- `mind.remember(content, metadata)` — deliberately store a durable
+  lesson, decision, fact, or outcome.
+- `mind.recall(query)` / `mind.recall_filtered(query, metadata)` —
+  explicit recall, `[]` when nothing matches.
+- `session.hold_set(key, content)` / `hold_clear(key)` — pin operational
+  state ("stop-order", "API is down") into every compile until cleared.
+- `mind.receipts(session_id=...)` — the audit trail: what ran, what it
+  consumed, what it produced, with lineage.
+- `mind.delete_by_metadata(metadata)` — destructive, audited deletion.
+- `mind.client` — the raw HTTP client for anything not wrapped.
+
+## Configuration
+
+Constructor arguments override environment:
+
+| Env var | Meaning |
+|---|---|
+| `HIVEMIND_BASE_URL` | Service root (hosted or local — same API) |
+| `HIVEMIND_API_KEY` | Sent as `Authorization: Bearer <key>` |
+| `HIVEMIND_TENANT_ID` | Your tenant (`X-Tenant-ID`) |
+| `HIVEMIND_TIMEOUT` | Request timeout, seconds (default 30) |
+| `HIVEMIND_BUDGET_TOTAL` | Default compile token budget (default 4096) |
+
+## Examples
+
+- [`examples/quickstart.py`](examples/quickstart.py) — the full loop with
+  no LLM key needed.
+- [`examples/chat_loop.py`](examples/chat_loop.py) — a real chat with any
+  OpenAI-compatible model.
+
+## Development note (this repo)
+
+The import name `hivemind` collides with the service package at the repo
+root, so run SDK tests as their own invocation:
+
+```bash
+python -m pytest sdk/python/tests
+```

hivemind_sdk-0.1.0/README.md

@@ -0,0 +1,79 @@
+# HiveMind Python SDK
+
+Persistent memory and a working-context compiler for your agent, in three
+lines inside your own loop. Your model, your key — HiveMind never calls an
+LLM.
+
+```bash
+pip install hivemind-sdk
+```
+
+Python ≥ 3.10, zero dependencies. The import name is `hivemind`.
+Docs: https://hivemind.militant.ai/docs
+
+```python
+from hivemind import HiveMind
+
+mind = HiveMind(base_url="...", api_key="...", tenant_id="...")
+session = mind.session(budget_total=8192)
+
+result = session.turn(user_input)       # store -> recall -> compile
+reply = call_your_llm(result.messages)  # your model, your key
+session.record(reply)                   # completes the exchange
+```
+
+## What one `turn()` does
+
+1. Stores the user message (receipted).
+2. Semantically recalls relevant memories and past conversation.
+3. Compiles local history + recalled records + active holds + your
+   operator briefing into a token-budgeted bundle.
+
+`result.messages` is the **entire** prompt payload — send it as-is, splice
+nothing in. `result.bundle["decisions"]` explains every admission under
+the budget; `result.receipt` is the audit record. Empty recall on a young
+tenant is normal, not an error.
+
+`session.record(reply)` stores your model's reply as the other half of the
+exchange, so the next turn — and every future session — remembers it.
+
+## Beyond the loop
+
+- `mind.remember(content, metadata)` — deliberately store a durable
+  lesson, decision, fact, or outcome.
+- `mind.recall(query)` / `mind.recall_filtered(query, metadata)` —
+  explicit recall, `[]` when nothing matches.
+- `session.hold_set(key, content)` / `hold_clear(key)` — pin operational
+  state ("stop-order", "API is down") into every compile until cleared.
+- `mind.receipts(session_id=...)` — the audit trail: what ran, what it
+  consumed, what it produced, with lineage.
+- `mind.delete_by_metadata(metadata)` — destructive, audited deletion.
+- `mind.client` — the raw HTTP client for anything not wrapped.
+
+## Configuration
+
+Constructor arguments override environment:
+
+| Env var | Meaning |
+|---|---|
+| `HIVEMIND_BASE_URL` | Service root (hosted or local — same API) |
+| `HIVEMIND_API_KEY` | Sent as `Authorization: Bearer <key>` |
+| `HIVEMIND_TENANT_ID` | Your tenant (`X-Tenant-ID`) |
+| `HIVEMIND_TIMEOUT` | Request timeout, seconds (default 30) |
+| `HIVEMIND_BUDGET_TOTAL` | Default compile token budget (default 4096) |
+
+## Examples
+
+- [`examples/quickstart.py`](examples/quickstart.py) — the full loop with
+  no LLM key needed.
+- [`examples/chat_loop.py`](examples/chat_loop.py) — a real chat with any
+  OpenAI-compatible model.
+
+## Development note (this repo)
+
+The import name `hivemind` collides with the service package at the repo
+root, so run SDK tests as their own invocation:
+
+```bash
+python -m pytest sdk/python/tests
+```

hivemind_sdk-0.1.0/hivemind/__init__.py

@@ -0,0 +1,4 @@
+from hivemind.client import HivemindClient, HivemindClientError
+from hivemind.session import HiveMind, Session, TurnResult
+
+__all__ = ["HiveMind", "Session", "TurnResult", "HivemindClient", "HivemindClientError"]

hivemind_sdk-0.1.0/hivemind/client.py

@@ -0,0 +1,256 @@
+"""Zero-dependency HTTP client for the HiveMind service API.
+
+Uses only the standard library. This is the transport layer the Python
+SDK builds on.
+
+Configuration (constructor arguments override environment):
+
+- ``HIVEMIND_BASE_URL``  — service root, default ``http://localhost:8000``
+- ``HIVEMIND_API_KEY``   — optional; sent as ``Authorization: Bearer <key>``
+- ``HIVEMIND_TENANT_ID`` — optional; sent as ``X-Tenant-ID`` (required unless
+  the service resolves tenancy from auth or runs with a local tenant)
+- ``HIVEMIND_TIMEOUT``   — request timeout in seconds, default ``30``
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+API_PREFIX = "/hivemind/v1"
+
+# Transport signature: (request, timeout_seconds) -> (status_code, body_bytes)
+Transport = Callable[[urllib.request.Request, float], Tuple[int, bytes]]
+
+
+class HivemindClientError(RuntimeError):
+    """Raised when the HiveMind service returns an error response."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None, detail: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.detail = detail
+
+
+def _default_transport(request: urllib.request.Request, timeout: float) -> Tuple[int, bytes]:
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 (caller controls URL)
+            return int(response.status), response.read()
+    except urllib.error.HTTPError as exc:
+        return int(exc.code), exc.read()
+
+
+class HivemindClient:
+    """Thin, synchronous client over the HiveMind HTTP contract."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        *,
+        api_key: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        project: Optional[str] = None,
+        timeout: Optional[float] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self.base_url = (base_url or os.getenv("HIVEMIND_BASE_URL") or "http://localhost:8000").rstrip("/")
+        self.api_key = api_key if api_key is not None else os.getenv("HIVEMIND_API_KEY")
+        self.tenant_id = tenant_id if tenant_id is not None else os.getenv("HIVEMIND_TENANT_ID")
+        # Which project this client operates in; absent, the hive's default
+        # project serves. One hive can bind different projects to different
+        # storage (managed and BYO side by side).
+        self.project = project if project is not None else os.getenv("HIVEMIND_PROJECT")
+        self.timeout = float(timeout if timeout is not None else os.getenv("HIVEMIND_TIMEOUT") or 30)
+        self._transport = transport or _default_transport
+
+    # ── memory ────────────────────────────────────────────────────────────
+
+    def create_memory(self, content: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self._post("/create_memory", {"content": content, "metadata": metadata or {}})
+
+    def recall_memory(self, query: str, top_k: int = 5) -> Dict[str, Any]:
+        return self._post("/recall_memory", {"query": query, "top_k": int(top_k)})
+
+    def recall_with_metadata(
+        self, query: str, metadata: Dict[str, Any], top_k: int = 10
+    ) -> Dict[str, Any]:
+        return self._post(
+            "/recall_with_metadata",
+            {"query": query, "metadata": dict(metadata or {}), "top_k": int(top_k)},
+        )
+
+    def delete_by_metadata(self, metadata: Dict[str, Any]) -> Dict[str, Any]:
+        return self._post("/delete_by_metadata", {"metadata": dict(metadata or {})})
+
+    # ── conversation ──────────────────────────────────────────────────────
+
+    def store_conversation(
+        self,
+        content: str,
+        session_id: str,
+        turn_number: int,
+        role: str,
+        exchange_pair_id: str,
+        additional_metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        return self._post(
+            "/conversation/store",
+            {
+                "content": content,
+                "session_id": session_id,
+                "turn_number": int(turn_number),
+                "role": role,
+                "exchange_pair_id": exchange_pair_id,
+                "additional_metadata": additional_metadata,
+            },
+        )
+
+    def recall_conversation(
+        self, query: str, session_id: Optional[str] = None, top_k: int = 10
+    ) -> Dict[str, Any]:
+        return self._post(
+            "/conversation/recall",
+            {"query": query, "session_id": session_id, "top_k": int(top_k)},
+        )
+
+    # ── context ───────────────────────────────────────────────────────────
+
+    def compile_context(
+        self,
+        session_id: str,
+        messages: Sequence[Dict[str, Any]],
+        turn_number: int,
+        budget_total: int,
+        *,
+        user_input: Optional[str] = None,
+        operator_briefing: Optional[str] = None,
+        holds: Optional[List[Dict[str, Any]]] = None,
+        artifacts_context: Optional[str] = None,
+        recalled_conversation: Optional[List[Dict[str, Any]]] = None,
+        recalled_memories: Optional[List[Dict[str, Any]]] = None,
+        policy: Optional[Dict[str, Any]] = None,
+        config: Optional[Dict[str, Any]] = None,
+        event_id: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        timestamp: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "session_id": session_id,
+            "messages": list(messages),
+            "turn_number": int(turn_number),
+            "budget_total": int(budget_total),
+            "user_input": user_input,
+            "operator_briefing": operator_briefing,
+            "holds": holds,
+            "artifacts_context": artifacts_context,
+            "recalled_conversation": recalled_conversation,
+            "recalled_memories": recalled_memories,
+            "policy": policy,
+            "config": config,
+            "event_id": event_id,
+            "trace_id": trace_id,
+            "timestamp": timestamp,
+        }
+        return self._post("/context/compile", payload)
+
+    # ── receipts ──────────────────────────────────────────────────────────
+
+    def list_receipts(
+        self,
+        limit: int = 50,
+        session_id: Optional[str] = None,
+        operation: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params: Dict[str, Any] = {"limit": int(limit)}
+        if session_id:
+            params["session_id"] = session_id
+        if operation:
+            params["operation"] = operation
+        return self._get("/receipts", params)
+
+    # ── export ────────────────────────────────────────────────────────────
+
+    def export(self, page_size: int = 200):
+        """Iterate every record the tenant owns: memories and conversations,
+        then receipts (including legacy). Yields dicts of
+        {id, content, metadata, phase}. Follows pagination to completion."""
+        cursor: Optional[str] = None
+        while True:
+            params: Dict[str, Any] = {"limit": int(page_size)}
+            if cursor:
+                params["cursor"] = cursor
+            envelope = self._get("/export", params)
+            data = envelope.get("data") or {}
+            phase = data.get("phase")
+            for record in data.get("records") or []:
+                yield {**record, "phase": phase}
+            if data.get("done") or not data.get("next_cursor"):
+                return
+            cursor = data["next_cursor"]
+
+    def export_to_file(self, path: str, page_size: int = 200) -> int:
+        """Write the full export to a JSONL file. Returns the record count."""
+        count = 0
+        with open(path, "w", encoding="utf-8") as handle:
+            for record in self.export(page_size=page_size):
+                handle.write(json.dumps(record, ensure_ascii=False, default=str) + "\n")
+                count += 1
+        return count
+
+    # ── transport plumbing ────────────────────────────────────────────────
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.tenant_id:
+            headers["X-Tenant-ID"] = str(self.tenant_id)
+        if self.project:
+            headers["X-Hivemind-Project"] = str(self.project)
+        return headers
+
+    def _post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        body = json.dumps(payload, ensure_ascii=True).encode("utf-8")
+        request = urllib.request.Request(  # noqa: S310
+            f"{self.base_url}{API_PREFIX}{path}",
+            data=body,
+            headers=self._headers(),
+            method="POST",
+        )
+        return self._execute(request)
+
+    def _get(self, path: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        query = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+        url = f"{self.base_url}{API_PREFIX}{path}"
+        if query:
+            url = f"{url}?{query}"
+        request = urllib.request.Request(url, headers=self._headers(), method="GET")  # noqa: S310
+        return self._execute(request)
+
+    def _execute(self, request: urllib.request.Request) -> Dict[str, Any]:
+        try:
+            status, raw = self._transport(request, self.timeout)
+        except urllib.error.URLError as exc:
+            raise HivemindClientError(
+                f"HiveMind service unreachable at {self.base_url}: {exc.reason}"
+            ) from exc
+
+        try:
+            parsed = json.loads(raw.decode("utf-8")) if raw else {}
+        except Exception as exc:
+            raise HivemindClientError(
+                f"HiveMind returned non-JSON response (HTTP {status}).", status=status
+            ) from exc
+
+        if status >= 400 or (isinstance(parsed, dict) and parsed.get("ok") is False):
+            detail = parsed.get("detail") if isinstance(parsed, dict) else parsed
+            raise HivemindClientError(
+                f"HiveMind request failed (HTTP {status}): {json.dumps(detail, default=str)[:500]}",
+                status=status,
+                detail=detail,
+            )
+        return parsed if isinstance(parsed, dict) else {"ok": True, "data": parsed}

hivemind_sdk-0.1.0/hivemind/session.py

@@ -0,0 +1,340 @@
+"""Turn-loop session layer for the HiveMind SDK.
+
+The integration contract, inside the customer's own agent loop:
+
+    from hivemind import HiveMind
+
+    mind = HiveMind(base_url="...", api_key="...", tenant_id="...")
+    session = mind.session(budget_total=8192)
+
+    result = session.turn(user_input)       # store -> recall -> compile
+    reply = call_your_llm(result.messages)  # your model, your key
+    session.record(reply)                   # completes the exchange
+
+``result.messages`` is the ENTIRE prompt payload: send it to your model
+as-is and do not splice anything else in. Every step is receipted
+server-side; ``result.receipt`` is the audit record for the compile and
+``result.bundle["decisions"]`` explains every admission under the token
+budget.
+
+One ``turn()`` call performs, in order:
+
+1. stores the user message as the user half of a conversation exchange
+2. semantically recalls relevant memories and past conversation
+3. compiles local history + recalled records + active holds + operator
+   briefing into a budgeted working-context bundle
+
+``record(reply)`` stores the assistant half of the exchange and keeps the
+local history that feeds the next compile.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+from hivemind.client import HivemindClient, HivemindClientError
+
+DEFAULT_BUDGET_TOTAL = 4096
+DEFAULT_RECALL_TOP_K = 5
+DEFAULT_LOCAL_HISTORY = 40
+
+
+def _records(envelope: Dict[str, Any]) -> List[Dict[str, Any]]:
+    data = envelope.get("data") or {}
+    for key in ("memories", "exchanges", "results"):
+        value = data.get(key)
+        if isinstance(value, list):
+            return value
+    return []
+
+
+@dataclass
+class TurnResult:
+    """What one turn() call returns.
+
+    ``messages`` is the compiled prompt payload — the only field to send
+    to the model. Everything else is audit and diagnostics.
+    """
+
+    messages: List[Dict[str, Any]]
+    bundle: Dict[str, Any]
+    receipt: Dict[str, Any]
+    session_id: str
+    turn_number: int
+    exchange_pair_id: str
+    recalled_memories: int
+    recalled_conversation: int
+    warnings: List[str] = field(default_factory=list)
+
+    @property
+    def token_count(self) -> Optional[int]:
+        return self.bundle.get("token_count")
+
+    @property
+    def budget_total(self) -> Optional[int]:
+        return self.bundle.get("budget_total")
+
+    @property
+    def decisions(self) -> List[Dict[str, Any]]:
+        return list(self.bundle.get("decisions") or [])
+
+    @property
+    def receipt_id(self) -> Optional[str]:
+        return self.receipt.get("receipt_id") or self.receipt.get("id")
+
+
+class Session:
+    """One conversation with memory maintained for you.
+
+    Not thread-safe; use one Session per concurrent conversation.
+    """
+
+    def __init__(
+        self,
+        client: HivemindClient,
+        *,
+        session_id: Optional[str] = None,
+        budget_total: int = DEFAULT_BUDGET_TOTAL,
+        operator_briefing: Optional[str] = None,
+        recall_top_k: int = DEFAULT_RECALL_TOP_K,
+        local_history_limit: int = DEFAULT_LOCAL_HISTORY,
+    ) -> None:
+        self._client = client
+        self.session_id = (session_id or "").strip() or f"sdk-{uuid.uuid4().hex[:12]}"
+        self.budget_total = int(budget_total)
+        self.operator_briefing = operator_briefing
+        self.recall_top_k = int(recall_top_k)
+        self.local_history_limit = int(local_history_limit)
+
+        self._turn = 0
+        self._history: List[Dict[str, str]] = []
+        self._open_exchange: Optional[Dict[str, Any]] = None
+        self._holds: Dict[str, Dict[str, Any]] = {}
+
+    # ── the loop ──────────────────────────────────────────────────────────
+
+    def turn(
+        self,
+        user_input: str,
+        *,
+        budget_total: Optional[int] = None,
+        operator_briefing: Optional[str] = None,
+        artifacts_context: Optional[str] = None,
+        policy: Optional[Dict[str, Any]] = None,
+    ) -> TurnResult:
+        """Run store -> recall -> compile for one turn.
+
+        Returns a TurnResult whose ``messages`` are the entire prompt for
+        your model call. Recall failures degrade to empty recall (noted in
+        ``warnings``); a compile failure raises HivemindClientError.
+        """
+        warnings: List[str] = []
+        self._turn += 1
+        turn_number = self._turn
+        exchange_id = f"xp-{uuid.uuid4().hex[:8]}"
+
+        # 1. Capture the user half of this exchange.
+        try:
+            self._client.store_conversation(
+                user_input, self.session_id, turn_number, "user", exchange_id
+            )
+            self._open_exchange = {"exchange_id": exchange_id, "turn": turn_number}
+        except HivemindClientError as exc:
+            warnings.append(f"user input not stored: {exc}")
+
+        # 2. Recall both lanes. 404 means "nothing stored yet", not failure.
+        recalled_memories = self._safe_recall(
+            lambda: self._client.recall_memory(user_input, self.recall_top_k),
+            warnings,
+            "memory recall",
+        )
+        recalled_conversation = self._safe_recall(
+            lambda: self._client.recall_conversation(user_input, None, self.recall_top_k),
+            warnings,
+            "conversation recall",
+        )
+
+        # 3. Compile local history + recall + holds under the budget.
+        current = {"role": "user", "content": user_input}
+        envelope = self._client.compile_context(
+            self.session_id,
+            [*self._history, current],
+            turn_number,
+            int(budget_total or self.budget_total),
+            user_input=user_input,
+            operator_briefing=operator_briefing or self.operator_briefing,
+            holds=self.holds() or None,
+            artifacts_context=artifacts_context,
+            recalled_conversation=recalled_conversation or None,
+            recalled_memories=recalled_memories or None,
+            policy=policy,
+        )
+        data = envelope.get("data") or {}
+        bundle = data.get("bundle") or {}
+
+        self._append_history(current)
+        return TurnResult(
+            messages=list(bundle.get("messages") or []),
+            bundle=bundle,
+            receipt=data.get("receipt") or {},
+            session_id=self.session_id,
+            turn_number=turn_number,
+            exchange_pair_id=exchange_id,
+            recalled_memories=len(recalled_memories),
+            recalled_conversation=len(recalled_conversation),
+            warnings=warnings,
+        )
+
+    def record(self, assistant_reply: str) -> Dict[str, Any]:
+        """Store the assistant half of the current exchange.
+
+        Call once per turn, after your model call. Uses the exchange the
+        last turn() opened; if none is open, stores under a fresh exchange
+        at the current turn.
+        """
+        open_exchange = self._open_exchange
+        self._open_exchange = None
+        turn_number = open_exchange["turn"] if open_exchange else max(1, self._turn)
+        exchange_id = (
+            open_exchange["exchange_id"] if open_exchange else f"xp-{uuid.uuid4().hex[:8]}"
+        )
+        result = self._client.store_conversation(
+            assistant_reply, self.session_id, turn_number, "assistant", exchange_id
+        )
+        self._append_history({"role": "assistant", "content": assistant_reply})
+        return result
+
+    # ── holds (pins injected into every compile) ─────────────────────────
+
+    def hold_set(self, key: str, content: str, title: Optional[str] = None) -> None:
+        key = str(key).strip()
+        if not key:
+            raise ValueError("hold key must be non-empty")
+        self._holds[key] = {
+            "id": key,
+            "title": (title or key).strip(),
+            "content": content,
+            "held_since": max(1, self._turn),
+        }
+
+    def hold_clear(self, key: str) -> bool:
+        return self._holds.pop(str(key).strip(), None) is not None
+
+    def holds(self) -> List[Dict[str, Any]]:
+        return [dict(value) for value in self._holds.values()]
+
+    # ── plumbing ──────────────────────────────────────────────────────────
+
+    def _append_history(self, message: Dict[str, str]) -> None:
+        self._history.append(message)
+        if len(self._history) > self.local_history_limit:
+            del self._history[: len(self._history) - self.local_history_limit]
+
+    @staticmethod
+    def _safe_recall(
+        call: Callable[[], Dict[str, Any]],
+        warnings: List[str],
+        label: str,
+    ) -> List[Dict[str, Any]]:
+        try:
+            return _records(call())
+        except HivemindClientError as exc:
+            if exc.status == 404:
+                return []
+            warnings.append(f"{label} failed: {exc}")
+            return []
+
+
+class HiveMind:
+    """Entry point. Holds credentials; makes sessions and deliberate calls.
+
+    Constructor arguments override environment (HIVEMIND_BASE_URL,
+    HIVEMIND_API_KEY, HIVEMIND_TENANT_ID, HIVEMIND_TIMEOUT). The same code
+    works against the hosted service and a local one — only base_url
+    changes.
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        *,
+        api_key: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        timeout: Optional[float] = None,
+        client: Optional[HivemindClient] = None,
+    ) -> None:
+        self._client = client or HivemindClient(
+            base_url, api_key=api_key, tenant_id=tenant_id, timeout=timeout
+        )
+
+    def session(
+        self,
+        session_id: Optional[str] = None,
+        *,
+        budget_total: Optional[int] = None,
+        operator_briefing: Optional[str] = None,
+        recall_top_k: int = DEFAULT_RECALL_TOP_K,
+    ) -> Session:
+        env_budget = os.getenv("HIVEMIND_BUDGET_TOTAL")
+        resolved_budget = (
+            int(budget_total)
+            if budget_total is not None
+            else int(env_budget) if env_budget else DEFAULT_BUDGET_TOTAL
+        )
+        return Session(
+            self._client,
+            session_id=session_id,
+            budget_total=resolved_budget,
+            operator_briefing=operator_briefing,
+            recall_top_k=recall_top_k,
+        )
+
+    # ── deliberate memory (outside the turn loop) ─────────────────────────
+
+    def remember(self, content: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Store a durable memory: a decision, lesson, fact, or outcome."""
+        return self._client.create_memory(content, metadata)
+
+    def recall(self, query: str, top_k: int = DEFAULT_RECALL_TOP_K) -> List[Dict[str, Any]]:
+        """Semantic recall. Returns [] when nothing matches."""
+        try:
+            return _records(self._client.recall_memory(query, top_k))
+        except HivemindClientError as exc:
+            if exc.status == 404:
+                return []
+            raise
+
+    def recall_filtered(
+        self, query: str, metadata: Dict[str, Any], top_k: int = 10
+    ) -> List[Dict[str, Any]]:
+        """Recall constrained to exact metadata matches. Returns [] when empty."""
+        try:
+            return _records(self._client.recall_with_metadata(query, metadata, top_k))
+        except HivemindClientError as exc:
+            if exc.status == 404:
+                return []
+            raise
+
+    def receipts(
+        self,
+        limit: int = 50,
+        session_id: Optional[str] = None,
+        operation: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """The audit trail: what ran, what it consumed, what it produced."""
+        envelope = self._client.list_receipts(limit, session_id, operation)
+        data = envelope.get("data") or {}
+        receipts = data.get("receipts") or data.get("results") or []
+        return list(receipts) if isinstance(receipts, list) else []
+
+    def delete_by_metadata(self, metadata: Dict[str, Any]) -> Dict[str, Any]:
+        """DESTRUCTIVE, audited: soft-delete memories matching all keys."""
+        return self._client.delete_by_metadata(metadata)
+
+    @property
+    def client(self) -> HivemindClient:
+        """The raw HTTP client, for anything the SDK doesn't wrap."""
+        return self._client

hivemind_sdk-0.1.0/hivemind_sdk.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: hivemind-sdk
+Version: 0.1.0
+Summary: Client SDK for HiveMind: persistent shared memory and a working-context compiler for agent systems.
+Author-email: "Militant.AI" <support@militant.ai>
+License: Proprietary
+Project-URL: Homepage, https://hivemind.militant.ai
+Project-URL: Documentation, https://hivemind.militant.ai/docs
+Keywords: ai,agents,memory,llm,context,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# HiveMind Python SDK
+
+Persistent memory and a working-context compiler for your agent, in three
+lines inside your own loop. Your model, your key — HiveMind never calls an
+LLM.
+
+```bash
+pip install hivemind-sdk
+```
+
+Python ≥ 3.10, zero dependencies. The import name is `hivemind`.
+Docs: https://hivemind.militant.ai/docs
+
+```python
+from hivemind import HiveMind
+
+mind = HiveMind(base_url="...", api_key="...", tenant_id="...")
+session = mind.session(budget_total=8192)
+
+result = session.turn(user_input)       # store -> recall -> compile
+reply = call_your_llm(result.messages)  # your model, your key
+session.record(reply)                   # completes the exchange
+```
+
+## What one `turn()` does
+
+1. Stores the user message (receipted).
+2. Semantically recalls relevant memories and past conversation.
+3. Compiles local history + recalled records + active holds + your
+   operator briefing into a token-budgeted bundle.
+
+`result.messages` is the **entire** prompt payload — send it as-is, splice
+nothing in. `result.bundle["decisions"]` explains every admission under
+the budget; `result.receipt` is the audit record. Empty recall on a young
+tenant is normal, not an error.
+
+`session.record(reply)` stores your model's reply as the other half of the
+exchange, so the next turn — and every future session — remembers it.
+
+## Beyond the loop
+
+- `mind.remember(content, metadata)` — deliberately store a durable
+  lesson, decision, fact, or outcome.
+- `mind.recall(query)` / `mind.recall_filtered(query, metadata)` —
+  explicit recall, `[]` when nothing matches.
+- `session.hold_set(key, content)` / `hold_clear(key)` — pin operational
+  state ("stop-order", "API is down") into every compile until cleared.
+- `mind.receipts(session_id=...)` — the audit trail: what ran, what it
+  consumed, what it produced, with lineage.
+- `mind.delete_by_metadata(metadata)` — destructive, audited deletion.
+- `mind.client` — the raw HTTP client for anything not wrapped.
+
+## Configuration
+
+Constructor arguments override environment:
+
+| Env var | Meaning |
+|---|---|
+| `HIVEMIND_BASE_URL` | Service root (hosted or local — same API) |
+| `HIVEMIND_API_KEY` | Sent as `Authorization: Bearer <key>` |
+| `HIVEMIND_TENANT_ID` | Your tenant (`X-Tenant-ID`) |
+| `HIVEMIND_TIMEOUT` | Request timeout, seconds (default 30) |
+| `HIVEMIND_BUDGET_TOTAL` | Default compile token budget (default 4096) |
+
+## Examples
+
+- [`examples/quickstart.py`](examples/quickstart.py) — the full loop with
+  no LLM key needed.
+- [`examples/chat_loop.py`](examples/chat_loop.py) — a real chat with any
+  OpenAI-compatible model.
+
+## Development note (this repo)
+
+The import name `hivemind` collides with the service package at the repo
+root, so run SDK tests as their own invocation:
+
+```bash
+python -m pytest sdk/python/tests
+```

hivemind_sdk-0.1.0/hivemind_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+hivemind/__init__.py
+hivemind/client.py
+hivemind/session.py
+hivemind_sdk.egg-info/PKG-INFO
+hivemind_sdk.egg-info/SOURCES.txt
+hivemind_sdk.egg-info/dependency_links.txt
+hivemind_sdk.egg-info/top_level.txt
+tests/test_session.py

hivemind_sdk-0.1.0/hivemind_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hivemind_sdk-0.1.0/hivemind_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+hivemind

hivemind_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name: "hivemind" on PyPI belongs to an unrelated distributed
+# deep-learning library, so the package installs as hivemind-sdk. The
+# import name stays `hivemind` (which also means our SDK and that library
+# cannot coexist in one environment — acceptable, non-overlapping audience).
+name = "hivemind-sdk"
+version = "0.1.0"
+description = "Client SDK for HiveMind: persistent shared memory and a working-context compiler for agent systems."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Militant.AI", email = "support@militant.ai" }]
+keywords = ["ai", "agents", "memory", "llm", "context", "rag"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# No runtime dependencies: the client is pure standard library.
+dependencies = []
+
+[project.urls]
+Homepage = "https://hivemind.militant.ai"
+Documentation = "https://hivemind.militant.ai/docs"
+
+[tool.setuptools]
+packages = ["hivemind"]

hivemind_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hivemind_sdk-0.1.0/tests/test_session.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import pytest
+
+from hivemind.client import HivemindClientError
+from hivemind.session import DEFAULT_BUDGET_TOTAL, HiveMind, Session
+
+
+class FakeClient:
+    def __init__(self) -> None:
+        self.stores: List[Dict[str, Any]] = []
+        self.compiles: List[Dict[str, Any]] = []
+        self.memory_error: Optional[Exception] = None
+        self.conversation_error: Optional[Exception] = None
+        self.compile_error: Optional[Exception] = None
+
+    def store_conversation(
+        self,
+        content: str,
+        session_id: str,
+        turn_number: int,
+        role: str,
+        exchange_pair_id: str,
+        additional_metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        self.stores.append(
+            {
+                "content": content,
+                "session_id": session_id,
+                "turn_number": turn_number,
+                "role": role,
+                "exchange_pair_id": exchange_pair_id,
+            }
+        )
+        return {"ok": True, "data": {"id": f"conv-{len(self.stores)}", "receipt_id": "r"}}
+
+    def recall_memory(self, query: str, top_k: int = 5) -> Dict[str, Any]:
+        if self.memory_error is not None:
+            raise self.memory_error
+        return {"ok": True, "data": {"memories": [{"id": "m1", "content": "a lesson"}]}}
+
+    def recall_conversation(
+        self, query: str, session_id: Optional[str] = None, top_k: int = 10
+    ) -> Dict[str, Any]:
+        if self.conversation_error is not None:
+            raise self.conversation_error
+        return {"ok": True, "data": {"exchanges": [{"id": "c1", "content": "earlier"}]}}
+
+    def compile_context(
+        self,
+        session_id: str,
+        messages,
+        turn_number: int,
+        budget_total: int,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        if self.compile_error is not None:
+            raise self.compile_error
+        self.compiles.append(
+            {
+                "session_id": session_id,
+                "messages": list(messages),
+                "turn_number": turn_number,
+                "budget_total": budget_total,
+                "holds": kwargs.get("holds"),
+                "recalled_memories": kwargs.get("recalled_memories"),
+                "recalled_conversation": kwargs.get("recalled_conversation"),
+                "operator_briefing": kwargs.get("operator_briefing"),
+            }
+        )
+        return {
+            "ok": True,
+            "data": {
+                "bundle": {
+                    "messages": [{"role": "system", "content": "compiled"}],
+                    "token_count": 42,
+                    "budget_total": budget_total,
+                    "decisions": [{"action": "included"}],
+                },
+                "receipt": {"receipt_id": "rcpt-compile"},
+            },
+        }
+
+
+@pytest.fixture()
+def fake() -> FakeClient:
+    return FakeClient()
+
+
+@pytest.fixture()
+def session(fake: FakeClient) -> Session:
+    return Session(fake, session_id="s1")
+
+
+def test_turn_stores_recalls_and_compiles(fake: FakeClient, session: Session) -> None:
+    result = session.turn("what do we know?")
+
+    assert fake.stores[0]["role"] == "user"
+    assert fake.stores[0]["turn_number"] == 1
+    compile_call = fake.compiles[0]
+    assert compile_call["messages"] == [{"role": "user", "content": "what do we know?"}]
+    assert compile_call["recalled_memories"] == [{"id": "m1", "content": "a lesson"}]
+    assert compile_call["recalled_conversation"] == [{"id": "c1", "content": "earlier"}]
+    assert compile_call["budget_total"] == DEFAULT_BUDGET_TOTAL
+
+    assert result.messages == [{"role": "system", "content": "compiled"}]
+    assert result.token_count == 42
+    assert result.receipt_id == "rcpt-compile"
+    assert result.turn_number == 1
+    assert result.recalled_memories == 1
+    assert result.warnings == []
+
+
+def test_record_completes_the_exchange_and_feeds_next_compile(
+    fake: FakeClient, session: Session
+) -> None:
+    first = session.turn("hello")
+    session.record("hi, I remember you")
+    session.turn("second question")
+
+    roles = [(s["role"], s["turn_number"], s["exchange_pair_id"]) for s in fake.stores]
+    assert roles[0] == ("user", 1, first.exchange_pair_id)
+    assert roles[1] == ("assistant", 1, first.exchange_pair_id)
+    assert roles[2][0] == "user" and roles[2][1] == 2
+
+    # Local history flows into the next compile.
+    assert fake.compiles[1]["messages"] == [
+        {"role": "user", "content": "hello"},
+        {"role": "assistant", "content": "hi, I remember you"},
+        {"role": "user", "content": "second question"},
+    ]
+
+
+def test_holds_are_injected_until_cleared(fake: FakeClient, session: Session) -> None:
+    session.hold_set("stop-order", "Do not deploy until QA signs off.")
+    session.turn("status?")
+    assert fake.compiles[0]["holds"][0]["id"] == "stop-order"
+
+    assert session.hold_clear("stop-order") is True
+    session.turn("and now?")
+    assert fake.compiles[1]["holds"] is None
+
+
+def test_empty_recall_is_not_an_error(fake: FakeClient, session: Session) -> None:
+    fake.memory_error = HivemindClientError("nothing", status=404)
+    fake.conversation_error = HivemindClientError("nothing", status=404)
+
+    result = session.turn("first ever message")
+
+    assert result.warnings == []
+    assert result.recalled_memories == 0
+    assert fake.compiles[0]["recalled_memories"] is None
+
+
+def test_recall_outage_degrades_with_warning(fake: FakeClient, session: Session) -> None:
+    fake.memory_error = HivemindClientError("boom", status=500)
+
+    result = session.turn("hello")
+
+    assert len(result.warnings) == 1
+    assert "memory recall failed" in result.warnings[0]
+    assert fake.compiles  # compile still ran
+
+
+def test_compile_failure_raises(fake: FakeClient, session: Session) -> None:
+    fake.compile_error = HivemindClientError("compiler down", status=500)
+    with pytest.raises(HivemindClientError):
+        session.turn("hello")
+
+
+def test_hivemind_entrypoint_builds_sessions_and_passthroughs(fake: FakeClient) -> None:
+    mind = HiveMind(client=fake)
+    session = mind.session("named-session", budget_total=1024)
+
+    assert session.session_id == "named-session"
+    assert session.budget_total == 1024
+
+    generated = mind.session()
+    assert generated.session_id.startswith("sdk-")