Metadata-Version: 2.4
Name: hypermind
Version: 1.6.9
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 :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
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.14,>=3.11
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: pydantic>=2.6
Requires-Dist: pymerkle>=6.1
Requires-Dist: pynacl>=1.6.2
Requires-Dist: quantcrypt>=1.0
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: libp2p
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: migrate
Requires-Dist: libcst>=1.1; extra == 'migrate'
Provides-Extra: openai
Requires-Dist: openai<2,>=1.50; extra == 'openai'
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: relata
Requires-Dist: relata-sdk>=0.2; extra == 'relata'
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'
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-2772-brightgreen)](#status)
[![Version](https://img.shields.io/badge/version-1.6.0-blue)](CHANGELOG.md)

**[Quickstart](#quickstart-30-seconds)** ·
**[MCP tools](#mcp-tools-52-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      # Python 3.11–3.13
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 (52 tools)

Every tool below is available when you run `hmctl mcp install`. Read-only by default;
`hm_publish_claim` requires `--write` (53 tools 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).

**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 — 30 numbered sections (§01–§30, §21 split) | [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](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md) |
| Contributing · Security policy | [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) |
| Governance · maintainers · charter | [GOVERNANCE.md](GOVERNANCE.md) · [MAINTAINERS.md](MAINTAINERS.md) · [CHARTER.md](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 (52 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 / …)
HYPERMIND_LLM_MODEL=gpt-4o   # model name (required for OpenRouter)
RELATA_URL=http://localhost:5432  # durable knowledge ledger
RELATA_BEARER_TOKEN=…        # auth token for managed RelataDB instances
HYPERMIND_DB=~/.hypermind/cache.db  # local SQLite fallback
```

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 which features are active
```

---

## Status

**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **1.6.0**.
Remaining gates are **ecosystem, not code** (see [ROADMAP.md](ROADMAP.md) §External).

- **Protocol** — 30 numbered spec sections (§01–§30, §21 split) + independent [`reference_verifier/`](reference_verifier/) proving two-impl interop
- **SDK** — async-first, fully type-hinted, **2772 tests**; hybrid PQ signing, FROST k-of-n, dispute FSM (incl. `SUSPENDED`), capability tokens, RFC 6962 transparency
- **52 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        # 2772 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>
