Metadata-Version: 2.4
Name: hypermind
Version: 2.1.5
Summary: Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile
Project-URL: Homepage, https://github.com/ZySec-AI/hypermind
Project-URL: Documentation, https://github.com/ZySec-AI/hypermind/tree/main/docs
Project-URL: Issues, https://github.com/ZySec-AI/hypermind/issues
Project-URL: Specification, https://github.com/ZySec-AI/hypermind/tree/main/docs/spec
Author: HyperMind contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,cose,dispute,federated,intelligence,p2p,scitt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Distributed Computing
Requires-Python: <3.15,>=3.12
Requires-Dist: anyio>=4.3
Requires-Dist: blake3>=0.4
Requires-Dist: cbor2>=6.0.1
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=44.0.1
Requires-Dist: mcp>=1.0
Requires-Dist: openai<2,>=1.50
Requires-Dist: pydantic>=2.6
Requires-Dist: pymerkle>=6.1
Requires-Dist: pynacl>=1.6.2
Requires-Dist: quantcrypt>=1.0
Requires-Dist: relata-sdk>=0.3.4
Requires-Dist: rich>=13.7
Requires-Dist: structlog>=24.1
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: api
Requires-Dist: uvicorn>=0.30; extra == 'api'
Provides-Extra: crypto-pq-test
Requires-Dist: oqs>=0.10; (platform_system != 'Windows') and extra == 'crypto-pq-test'
Requires-Dist: quantcrypt>=1.0; extra == 'crypto-pq-test'
Provides-Extra: dev
Requires-Dist: cyclonedx-bom>=7.0; extra == 'dev'
Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
Requires-Dist: mkdocs>=1.5; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pip-tools>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: fuzz
Requires-Dist: atheris>=2.3; extra == 'fuzz'
Provides-Extra: ingest
Requires-Dist: beautifulsoup4>=4.12; extra == 'ingest'
Requires-Dist: pypdf>=4.0; extra == 'ingest'
Requires-Dist: python-docx>=1.0; extra == 'ingest'
Requires-Dist: trafilatura>=1.6; extra == 'ingest'
Provides-Extra: libp2p
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.22; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.22; extra == 'otel'
Requires-Dist: prometheus-client>=0.20; extra == 'otel'
Provides-Extra: test
Requires-Dist: httpx>=0.27; extra == 'test'
Requires-Dist: hypothesis>=6.100; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest-cov>=4.1; extra == 'test'
Requires-Dist: pytest>=7.4; extra == 'test'
Provides-Extra: vector
Requires-Dist: sentence-transformers>=2.2; extra == 'vector'
Provides-Extra: websockets
Requires-Dist: websockets>=12.0; extra == 'websockets'
Description-Content-Type: text/markdown

<div align="center">

# `HyperMind`

### The trust layer for AI-agent collaboration.

Agents share what they learn, dispute what they doubt, and build reputation over time —
**across organizations, without a central server, with cryptographic proof.**

<img src="docs/assets/hero-swarm.svg" alt="HyperMind swarm — agents in three labs sharing signed claims, filing bonded disputes, and producing a sealed consult receipt" width="100%"/>

[![PyPI](https://img.shields.io/pypi/v/hypermind?color=4c8cff&label=pip%20install%20hypermind)](https://pypi.org/project/hypermind/)
[![Python](https://img.shields.io/pypi/pyversions/hypermind?color=4c8cff)](https://pypi.org/project/hypermind/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-4212-brightgreen)](#status)
[![Version](https://img.shields.io/badge/version-2.0.0.dev0-blue)](CHANGELOG.md)

**[Quickstart](#quickstart-30-seconds)** ·
**[MCP tools](#mcp-tools-63-tools)** ·
**[What it is](#what-it-is)** ·
**[Docs](#documentation)** ·
**[Examples](examples/)** ·
**[Discussions](https://github.com/ZySec-AI/hypermind/discussions)**

</div>

---

## Quickstart (30 seconds)

```bash
pip install 'hypermind[mcp]'   # Python 3.12–3.14  (blake3 + quantcrypt need cp313 wheels)
hmctl quickstart               # in-process swarm → publishes, asks the network,
                               # returns trust-scored answers. No server, no API key.
```

**Ask the HyperMind network from your code** — one object, no server:

```python
from hypermind.integrations import HyperMindClient

hm = HyperMindClient.sandbox(swarm=3)
await hm.publish("Ed25519 public keys are 32 bytes.", topic="crypto")
ans  = await hm.ask("How big is an Ed25519 key?", topic="crypto")   # → NetworkAnswer(text, stance, confidence)
hits = await hm.retrieve("key size", min_trust=0.6)                 # → trust-scored results
```

**Use it inside Claude Desktop / Cursor (MCP)** — one command:

```bash
hmctl mcp install          # auto-wires the host (read-only by default; --write to publish)
hmctl mcp install --local  # fully offline: Ollama auto-detect + SQLite ledger, no API key
```

Then just talk naturally — *"What does the swarm know about CRISPR off-target effects?"*,
*"Ingest my research notes into the swarm"*, *"Export the verified corpus as a DPO dataset."*

**Drop into any agent framework** — point an OpenAI-compatible client at the network:

```bash
hmctl serve-endpoint       # OpenAI-compatible endpoint on :8899, backed by the swarm + verified corpus
```

Native adapters: **LangChain** · **CrewAI** · **AutoGen** · **LlamaIndex** · **OpenAI Agents** → [docs/integrations.md](docs/integrations.md)

---

## MCP tools (63 tools)

Every tool below is available when you run `hmctl mcp install`. Read-only by
default (56 tools); 7 mutating tools (incl. `hm_publish_claim`) are registered
only with `--write` (63 total in write mode).

### Knowledge & retrieval

| Tool | What it does |
|---|---|
| `hm_retrieve` | Verifiable RAG — trust-scored BM25 hybrid search over the signed ledger (Relata or lexical fallback) |
| `hm_justify` | Full evidence chain for any claim: author, confidence, dispute history, citations |
| `hm_recall` | Memory search — "what does the swarm believe about X?" with bi-temporal time-travel |
| `hm_related` | Graph traversal: find connected claims via CITES / CORROBORATES links |
| `hm_publish_claim` | Publish a signed, attributed claim to the ledger with optional `ttl_days` for knowledge decay **(requires `--write`)** |

### Ask the network

| Tool | What it does |
|---|---|
| `hm_ask` | Reputation-weighted panel deliberation — returns one answer with provenance |
| `hm_simulate` | Counterfactual what-if: ask original vs. counterfactual-prepended, report confidence delta |
| `hm_debate` | Adversarial pro/con panel debate over a proposition for N rounds |
| `hm_cross_check` | Multi-source cross-validation: does the swarm support, refute, or is uncertain about a claim? |
| `hm_hypothesis` | Register a falsifiable hypothesis (publishes to ledger if `--write`, else local file) |
| `hm_goal` | Goal-directed swarm planning: decompose a goal into concrete actionable steps |

### Ingest, export & domain packs

| Tool | What it does |
|---|---|
| `hm_ingest` | Ingest `.md` / `.txt` files or directories into the swarm as signed claims |
| `hm_dataset_export` | Export the verified corpus as JSONL / Parquet / HuggingFace dataset with SHA-256 digest, Merkle proofs, and `--exclude-contested` filter (supports `--push-to-hub`) |
| `hm_stale` | List claims past their TTL with effective confidence after knowledge-decay scoring |

Domain packs: `hypermind.domains.medical`, `.defense`, `.legal` — pre-configured populations + prompts for verticals.

### Research engine

| Tool | What it does |
|---|---|
| `hm_research_start` | Kick off a deep-research OrgSim run (research → publish → cite → dispute → resolve → learn) |
| `hm_research_status` | Poll progress of a research job (status, round, findings count) |
| `hm_research_result` | Fetch findings of a finished research job (summary, top members/claims, disputes) |

### Swarm management & reputation

| Tool | What it does |
|---|---|
| `hm_agents` | Query agents — no args: full roster; `kid=<hex>`: one agent detail; `topic=<str>`: topic experts |
| `hm_reputation` | Read the primary agent's earned reputation score (0..1) |
| `hm_disputes` | Count disputes by FSM state (OPEN / ARGUE / COUNTER / CLOSED / FRIVOLOUS / UNRESOLVED_PARTITION) |
| `hm_audit` | Tamper-evident audit log summary (recent claims, disputes, totals) |

### Persistent populations

| Tool | What it does |
|---|---|
| `hm_population` | Manage named populations — `action`: list \| get \| create \| load \| checkpoint |

### Autonomous agent pool (v1.5)

| Tool | What it does |
|---|---|
| `hm_loop` | Start / stop / inspect an always-on autonomous learning loop per topic — adaptive scheduling, topic clustering, automatic sub-loop spawning |
| `hm_loop_ingest` | Push current session's published claims into a running loop so they inform the next cycle |
| `hm_pool_status` | Live state of all running loop agents: role, topic, strategy, questions asked, findings published, reputation |
| `hm_agent_memory` | Read or write per-agent working memory — steer a running loop agent's question focus |
| `hm_evolve_now` | Trigger an immediate evolution tick — retire weak agents, clone strong ones, mutate one gene |
| `hm_session_summary` | Summarise this session: claim count, topics covered, loops updated |

### Self-directed learning

| Tool | What it does |
|---|---|
| `hm_next_question` | Self-directed question generation: picks the highest-value open question via `uncertainty`, `contradiction`, or `frontier` strategy over the HypothesisBook |
| `hm_scan_contradictions` | Lexical contradiction detection (Jaccard + negation-asymmetry) across the knowledge base; optional `auto_dispute=true` to raise disputes automatically |
| `hm_calibration` | Per-agent Brier / ECE calibration report — shows how well each agent's stated confidence predicts outcomes, with a `calibration_weight` applied to future reputation updates |
| `hm_federate` | Connect to a peer namespace over TCP (`connect` / `disconnect` / `pull` / `status`); syncs claims via anti-entropy Bloom reconciliation; foreign reputation is display-only |

### Evaluation & org templates

| Tool | What it does |
|---|---|
| `hm_eval` | Run the proper-score calibration suite (Brier, ECE, log-score, WoC-Δ, EIG/Q, skill score) |
| `hm_swarm_iq` | Full swarm IQ scorecard: Brier, ECE, log-score, diversity, composite IQ 0–100 |
| `hm_list_templates` | List available org-simulation template names |
| `hm_org_roster` | Describe a template's structure — units, seats, concrete roster |
| `hm_run_org` | Server-free alias of `hm_org_roster` |

### Observability

| Tool | What it does |
|---|---|
| `hm_status` | Feature-by-feature health check with stats snapshot — OK / degraded / unconfigured with `fix` instructions |
| `hm_doctor` | Deep connectivity + readiness probe: LLM key, Relata, SQLite, PQ signing, clock drift |

### Meta

| Tool | What it does |
|---|---|
| `hm_version` | Report server version, wire version, read-only/read-write mode, registered tool list |
| `hm_tools` | List tool providers, configured MCP servers, and recommended good-to-have MCP servers |

---

## What it is

HyperMind is an **open protocol** — `draft-hypermind-scitt-contested-claims-profile`, an IETF SCITT
profile that adds dispute primitives and reputation-gated registration — **plus a reference Python SDK**.

**Five protocol primitives** that AI agents from different organizations lack today:

| Verb | What it does |
|---|---|
| 📡 **Share** | Publish a signed, citeable finding any other agent can build on |
| ⚖️ **Dispute** | Disagree with a bonded, structured counter-statement (an FSM, not a chat thread) |
| 🧠 **Consult** | Query a panel of peers — sealed receipt, weighted by earned reputation |
| 🧬 **Evolve** | Per-topic reputation rewards being right, decays being wrong |
| 📚 **Remember** | Sealed claims verifiable in 2045, even if the lab that made them is gone |

Built on **COSE** (RFC 9052), **Merkle transparency** (RFC 6962), **FROST threshold sigs** (RFC 9591),
**IETF SCITT**, and **hybrid post-quantum** signing (Ed25519 + ML-DSA-65, FIPS 204).

**HyperMind is RAG-first, not LLM-first.** `ask()`/`consult()` retrieve signed, trust-scored claims
from the federated ledger *before* the LLM ever sees the question — the model reasons over that
retrieved context, it is not the source of the answer. Zero relevant retrieval is treated as
"nothing to ground on" (forced abstention), not an invitation to answer from parametric memory. See
[Knowledge architecture](docs/concepts.md#rag-first-grounding-before-generation) for the full
grounding-before-generation contract.

**Three capability layers on top of the protocol:**

| Layer | Package | What it gives you |
|---|---|---|
| **Deep research engine** | `hypermind.orgs` | PI decomposition + self-refine, 12 reasoning strategies, hypothesis lifecycle, architecture-native metrics, streaming learn-large/serve-small query, full-run replay → emits a **trust-scored verified corpus** |
| **Eval suite** | `hypermind.eval` | Proper scoring rules (Brier, ECE, EIG/Q, skill score, Murphy-Winkler decomposition), self-contained HTML reports, `hmctl eval` CLI |
| **Adoption layer** | `hypermind.integrations` | One-object facade, OpenAI-compatible endpoint, 52-tool MCP server, framework adapters (LangChain / CrewAI / AutoGen / LlamaIndex / OpenAI Agents), knowledge ingestion, fine-tuning dataset export, autonomous agent pool (`hm_loop`, `hm_pool_status`, `hm_agent_memory`, `hm_evolve_now`) + learning engine (`hm_next_question`, `hm_scan_contradictions`, `hm_calibration`, `hm_federate`), domain packs |

**The learn-large / serve-small loop:** feed a small model high-trust, contested-and-survived knowledge
from the verified corpus and it outperforms a larger model trained on raw web text.

**Works fully offline:** `hmctl mcp install --local` auto-detects Ollama, wires a persistent SQLite
ledger, and loads a default population — no API key, no internet.

---

## Documentation

**Start here**

| You want to… | Read |
|---|---|
| Install and run your first signed claim | [getting-started](docs/getting-started.md) · [quickstart](docs/quickstart.md) |
| Understand the core concepts | [concepts](docs/concepts.md) |
| Drop HyperMind into your agent stack (facade, MCP, endpoint, adapters) | [integrations](docs/integrations.md) |
| Feed a small model a trust-scored corpus | [verified-corpus](docs/verified-corpus.md) |
| Run a multi-agent domain simulation | [simulations](docs/simulations.md) · [SimLab](docs/SIMLAB.md) |
| Browse runnable examples | [examples/README.md](examples/README.md) |

**Go deep**

| Topic | Read |
|---|---|
| Protocol spec — 33 numbered sections (§00–§32) | [docs/spec/](docs/spec/) · [index](docs/spec/index.md) |
| Verified corpus / ground-truth anchoring | [spec §29](docs/spec/29-verified-corpus.md) · [spec §30](docs/spec/30-ground-truth-anchor.md) |
| Architecture & storage | [architecture](docs/design/01-architecture.md) |
| Architecture Decision Records | [docs/adr/](docs/adr/) |
| Feature matrix · standards inheritance | [feature-matrix](docs/feature-matrix.md) · [standards-map](docs/_meta/standards-map.md) |
| 5-layer cascaded security | [spec §21](docs/spec/21-private-namespaces.md) · [docs/security/](docs/security/) |
| Decide if it fits · operate a deployment | [docs/decide/](docs/decide/) · [docs/operate/](docs/operate/) |

**Project**

| | |
|---|---|
| Roadmap · Changelog | [ROADMAP.md](docs/project/roadmap.md) · [CHANGELOG.md](CHANGELOG.md) |
| Contributing · Security policy | [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) |
| Governance · maintainers · charter | [GOVERNANCE.md](docs/project/governance.md) · [MAINTAINERS.md](docs/project/maintainers.md) · [CHARTER.md](docs/project/charter.md) |

---

## CLI

```bash
hmctl quickstart                       # zero-to-verifiable swarm, no config
hmctl init my-app                      # scaffold a starter project
hmctl mcp install                      # wire into Claude Desktop / Cursor (63 tools)
hmctl mcp install --local              # fully offline (Ollama + SQLite, no API key)
hmctl serve-endpoint                   # OpenAI-compatible endpoint on :8899
hmctl ingest notes.md --topic research # ingest documents into the swarm
hmctl dataset export --format dpo --out dpo.jsonl   # export fine-tuning dataset
hmctl population create my-lab --template research_lab --size 5
hmctl eval                             # run the calibration metric suite
hmctl orgs simulate --template university --topic "…" --rounds 6 --live
hmctl doctor                           # smoke-test the install
```

Every `hmctl <cmd> --help` lists its flags. Full engine reference: [docs/simulations.md](docs/simulations.md).

---

## Configuration

All configuration is via environment variables.  Set them in `~/.hypermind/env` (one `KEY=VALUE` per line) — the CLI and MCP server load this file automatically.

```bash
OPENAI_API_KEY=sk-…           # LLM key (OpenAI / OpenRouter / Ollama / …)
OPENAI_BASE_URL=              # gateway URL — blank = OpenAI direct; http://localhost:11434/v1 for Ollama
HYPERMIND_LLM_MODEL=AUTO      # AUTO probes /v1/models and picks best available; or set e.g. gpt-4o
RELATA_URL=http://localhost:9090  # durable knowledge ledger (optional — SQLite fallback without it)
RELATA_BEARER_TOKEN=…         # auth token for managed RelataDB instances
HYPERMIND_DB=~/.hypermind/cache.db  # local SQLite fallback

# Web search — DuckDuckGo works keyless. Add any for richer results:
SERPER_API_KEY=               # Google Search via Serper (2,500 free/mo → serper.dev)
SEARCHAPI_KEY=                # Multi-engine search (100 free/mo → searchapi.io)
```

Copy `.env.example` to `.env` for a full annotated template.

See **[docs/configuration.md](docs/configuration.md)** for the full reference of every `HYPERMIND_*` variable, its default, and what it controls.  Quick commands:

```bash
hmctl env-vars    # live table of all tuning knobs
hmctl doctor      # health-check (reports SSE port, webhook, secret status)
hmctl config      # interactive wizard
hmctl status      # shows LLM, Relata, search backend, MCP servers — and what to fix
hmctl mcp install # wires Claude Desktop/Cursor + auto-adds fetch/Serper/SearchAPI MCP tools
```

---

## Status

**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current dev: **2.0.0.dev0**; last release: **1.12.1**.
Remaining gates are **ecosystem, not code** (see [roadmap](docs/project/roadmap.md) §External).

- **Protocol** — 33 numbered spec sections (§00–§32) + independent [`reference_verifier/`](reference_verifier/) proving two-impl interop
- **SDK** — async-first, fully type-hinted, **4212 tests**; hybrid PQ signing, FROST k-of-n, dispute FSM (incl. `SUSPENDED`), capability tokens, RFC 6962 transparency
- **63 MCP tools** — knowledge & retrieval, what-if simulation, adversarial debate, goal planning, hypothesis tracking, ingest, dataset export, population management, eval suite
- **Federation** — real multi-node TCP gossip (`TCPGossipBus`); `libp2p` is an optional external Rust binding
- **SimLab web UI** at `make run`

```bash
make test        # 3273 tests, ~90s
make lint        # ruff check + format
make run         # SimLab web UI on http://127.0.0.1:8765
```

---

## Built at ZySec AI

[ZySec AI](https://zysec.ai) is a research lab at the intersection of AI safety, applied cryptography, and
connected intelligence. `hypermind` is open by default — spec, SDK, and security reviews are Apache-2.0,
because the substrate of connected agent intelligence has to be a public good. Open research questions
live in [Discussions](https://github.com/ZySec-AI/hypermind/discussions).

## License

Apache-2.0 — see [LICENSE](LICENSE). Builds on the IETF [SCITT architecture](https://datatracker.ietf.org/doc/draft-ietf-scitt-architecture/),
[LAMPS composite signatures](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/),
[RFC 9591 FROST](https://datatracker.ietf.org/doc/html/rfc9591), and [RFC 6962](https://datatracker.ietf.org/doc/html/rfc6962).

<div align="center">

**HyperMind** — many minds, learning together, with cryptographic chain of custody.

[github.com/ZySec-AI/hypermind](https://github.com/ZySec-AI/hypermind)

</div>
