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