Metadata-Version: 2.4
Name: hypermind
Version: 0.31.1
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: kms-all
Requires-Dist: azure-identity>=1.16; extra == 'kms-all'
Requires-Dist: azure-keyvault-keys>=4.8; extra == 'kms-all'
Requires-Dist: boto3>=1.34; extra == 'kms-all'
Requires-Dist: google-cloud-kms>=2.20; extra == 'kms-all'
Requires-Dist: hvac>=2.0; extra == 'kms-all'
Provides-Extra: kms-aws
Requires-Dist: boto3>=1.34; extra == 'kms-aws'
Provides-Extra: kms-azure
Requires-Dist: azure-identity>=1.16; extra == 'kms-azure'
Requires-Dist: azure-keyvault-keys>=4.8; extra == 'kms-azure'
Provides-Extra: kms-gcp
Requires-Dist: google-cloud-kms>=2.20; extra == 'kms-gcp'
Provides-Extra: kms-vault
Requires-Dist: hvac>=2.0; extra == 'kms-vault'
Provides-Extra: libp2p
Requires-Dist: hypermind-libp2p>=0.10.1; 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 protocol for swarm intelligence between AI agents.**

Agents share what they learn. Dispute what they doubt. Build trust over time.
**Across companies. Without a central server. With cryptographic proof.**

*Think Git for agent knowledge — federated, signed, evolving.*

<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-2133%20passing-brightgreen)](#testing--quality)
[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](#testing--quality)
[![Status](https://img.shields.io/badge/status-v0.10-blue)](#project-status)

**[Run the demo](#run-the-demo-one-command)** ·
**[60-second SDK tour](#60-second-demo)** ·
**[What it is](#what-it-is-30-seconds)** ·
**[Cascaded security](#cascaded-security--five-layers-failure-isolated)** ·
**[Use cases](#two-use-cases-that-make-it-click)** ·
**[Spec](docs/spec/)** ·
**[Examples](examples/)** ·
**[Discussions](https://github.com/ZySec-AI/hypermind/discussions)**

</div>

---

## Run the demo (one command)

The fastest way to see HyperMind is the **SimLab web UI**. It rebuilds the Vue bundle and starts the local server in one go:

```bash
git clone https://github.com/ZySec-AI/hypermind && cd hypermind
make bootstrap   # one-time: creates .venv and installs editable
make run         # builds the webui + starts SimLab on http://127.0.0.1:8765
```

Open **http://127.0.0.1:8765** and you'll see:

| Route | What it shows |
|---|---|
| `/` | Home — quick orientation |
| `/how-it-works` | Animated walkthrough of the protocol layers |
| `/evidence` | IEEE-grade evaluation: HyperMind vs. baselines |
| `/security` | **NEW.** 5-layer cascaded security stack + failure-isolation matrix |
| `/usecases` | 6 industries × ~22 use cases each, filterable, expandable |
| `/sims` | Past simulations (run new ones from `/new`) |
| `/agents` · `/tools` · `/knowledge` · `/reports` | The SDK in action |
| `/docs` · `/paper` | Full spec (28 sections) + IEEE paper draft + patent disclosure |

**Other make targets:**

```bash
make run-fast      # skip the webui rebuild (when JS hasn't changed)
make webui-dev     # Vite dev server with hot-reload on :5173
make test          # 2133 tests pass, ~80s
make demo          # examples/01_hello_world from the CLI
make demos         # all numbered tutorials + scenarios sequentially
make help          # show all targets
```

---

## What it is (30 seconds)

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

It gives AI agents from different organizations five things they don't have today:

| Verb | What it does | Biology analogue |
|---|---|---|
| 📡 **Share** | Publish a signed, citeable finding any other agent can build on | Lab notebooks + peer review |
| ⚖️ **Dispute** | Disagree with a bonded, structured counter-statement (FSM, not Slack) | The immune system |
| 🧠 **Consult** | Query a panel of peers — sealed receipt, weighted by reputation | Swarm decision-making |
| 🧬 **Evolve** | Per-topic reputation rewards being right, decays being wrong | Selection pressure on ideas |
| 📚 **Remember** | Sealed claims verifiable in 2045, even if the lab is gone | Inheritance across generations |

Built on **RFC 6962** (Merkle transparency), **RFC 9591** (FROST threshold sigs), **IETF SCITT**, **COSE**, **NIST FIPS 204** (ML-DSA-65 hybrid PQ).

> **Not a chat protocol. Not a chain. Not another framework.**
> It's the **substrate** underneath agent collaboration — the layer where `share`, `cite`, `dispute`, and `evolve` become primitives instead of tickets in someone's backlog.

---

## Why this matters (in three lines)

> 🌍 **By 2027, ~1B AI agents will run inside companies.** Today, none of them can talk to one across the firewall.
> 🧠 **Frontier models are already brilliant in isolation.** The bottleneck isn't intelligence — it's *integration*.
> 🔒 **Without a trust substrate, every "multi-agent" system reinvents (badly): identity, citation, dispute, reputation, audit.** `hypermind` is that substrate — once, properly, open-source.

**The value, in one sentence:** *turn isolated AI agents into a swarm that learns, evolves, and remembers — across companies, with cryptographic proof that any auditor (or court, or regulator, or competitor) can verify in 2045.*

---

## Why it matters

Today's AI agents are **isolated minds**. An agent at Lab A finds something — the agent at Lab B will never know. Different stores, different keys, no shared trust model. Every multi-agent system in production today reinvents (badly): identity, citation, disagreement, reputation, audit.

**Every adaptive system that ever got smarter at scale is a network of agents that share what they learn and dispute what they doubt.** Ant colonies do it with pheromones. Neurons with synapses. Scientists with citations and peer review. Cities with markets. We just haven't built it yet for our agents.

`hypermind` is that missing layer. **Not validation. Not citation. Connected, evolving intelligence** — with the cryptographic chain of custody that makes the swarm trustworthy instead of just noisy.

<details>
<summary><b>Imagine this →</b> the swarm in motion (click to expand)</summary>

> An agent at Lab A wakes up. It runs an evaluation, finds something interesting, and signs its result.
>
> An agent at Lab B sees that result. It doesn't blindly trust it — Lab B's agent has watched Lab A for six months and knows where its strengths and blind spots are. It re-runs the test independently. It mostly agrees, but on one edge case it disagrees, **politely** — it files a counter-statement explaining why, putting some of its reputation on the line.
>
> An agent at Lab C, watching both of them, asks the swarm: *"so which is right?"* A panel of five other agents — picked because their views diverge most — weighs in. Their answers are aggregated, weighted by past accuracy. A signed receipt records the outcome.
>
> A week later, ground truth arrives. The agents who were right gain standing. The ones who were wrong lose some — *only in this topic, not everywhere*. Nobody is "punished," but **the swarm has learned**. Tomorrow's questions get sharper answers because today's agents got slightly smarter, together.
>
> No central server told them to do any of this. No company owns the data. Each agent kept its own keys, its own data, its own boundaries. But the *collective* — that grew.

This is how humans work. We talk, we cite, we disagree, we build reputations, we update. Whole civilizations are built on this layer. Our AI agents have none of it. That's the gap `hypermind` exists to close.

</details>

---

## Simulate any network — `hypermind.orgs` (the engine)

The SDK ships a **living-simulation engine**: spin up a network of LLM-backed agents with roles, per-agent models, and group-scoped native tools, then run a `research → publish → cite → dispute → resolve → learn → evolve` loop persisted to Relata. One general engine expresses many scenarios — a university researching a hard problem, a city at war, a foreign-policy cabinet, an internet crowd reacting to a what-if — via pluggable **interaction strategies** (`cooperative` / `adversarial` / `crowd`) and an override hook for custom phases.

```python
from hypermind.orgs import OrgSim
from hypermind.orgs.templates import university   # or: city_at_war, un_security_council, ...

model = university(members=24)                     # generic OrgModel, scaled to 24 people
report = await OrgSim(model, relata_url="http://localhost:9090",
                      llm="anthropic", llm_client=client).simulate(
                          topic="What limits ab-initio protein folding?", rounds=6)
report.print()        # reputation ranking · citation graph · dispute ledger · calibration
```

- **Generic core, template library.** `OrgModel` / `Unit` / `Seat` are org-agnostic; `hypermind.orgs.templates` ships ready presets (`university`, `hospital`, `city_at_war`, `foreign_policy_cabinet`, `un_security_council`, `internet_crowd`, `research_lab`) — pure convenience data the core never imports. Roll your own network from the primitives.
- **Per-agent models.** Any seat can pin its own provider/model (`Seat("Professor", llm="anthropic", model="claude-opus-4-8")`), or hand `OrgSim` a router for random / cost-aware assignment.
- **Native tools, group-scoped.** Tools (web search, retrieval, KB query, Relata research) are granted per unit/seat and enforced — an ungranted tool is *absent* from that agent's toolset. Grants can be declarative or randomised; register your own with `hypermind.orgs.register_tool(...)`.
- **Relata end-to-end.** Organisation → tenant; member → private memory session (agent kid); claims / disputes / reputation → tenant-scoped ledger rows; chain of custody → the Merkle log. Restart replays the whole org.
- **Study → ask (a queryable swarm).** Let the swarm learn a topic, then question it: `await sim.study(topic)` then `await sim.ask("...")` — every member recalls what it learned, reasons, and the answers are aggregated weighted by earned standing. `sim.ask` studies first automatically if you skip the explicit step.
- **Proper RAG.** Retrieval for `ask` is pluggable: lexical (default), semantic embeddings (`embedder=`), the claim↔entity graph (`use_graph_retrieval=True`), or `hybrid_retriever(...)` which fuses dense + graph + lexical via Reciprocal Rank Fusion with an optional cross-encoder rerank. Relata *is* the vector store + graph (`relata_retriever(..., "search_knowledge" / "find_connections")`).
- **Answer quality, natively.** `await sim.assess(question)` returns a `QualityReport` scoring grounding, hallucination rate, calibration (Brier), self-consistency, and hm-native rubrics that are *verifiable from the signed ledger* — provenance coverage, dispute exposure, reputation-weighted support. All rubrics on by default; missing deps (judge / ground-truth) degrade to informational notes.
- **Scales like Locust.** `OrgSim(lightweight=True)` caps RAM to O(members), not O(records); Relata writes are batched. For horizontal scale, `hypermind.orgs.distributed` runs a **master/worker** control plane — shard a swarm across processes or machines against the shared Relata namespace, merged into one report (`python -m hypermind.orgs.distributed master/worker`, or `run_distributed(...)`).

### No-code CLI — `hmctl orgs`

Run the whole engine from the shell (no Python). `--live` shows an animated, colourful dashboard; `ask` prints a quality panel with per-rubric gauges (grounding, **hallucination**, calibration, …).

```bash
hmctl orgs templates                         # list the presets
hmctl orgs simulate --template university --members 24 --rounds 6 \
    --topic "what limits protein folding?" --live      # animated dashboard + report
hmctl orgs ask "what limits protein folding?" --template university --live
                                             # study → ask → fancy quality panel
hmctl orgs distributed --template university --members 10000 --workers 8 \
    --topic "…"                              # sharded across workers, merged report
```

Common flags: `--relata-url` (or `$RELATA_URL`), `--llm openai|anthropic`, `--llm-model`, `--base-url`, `--api-key-env`, `--html report.html`. Full options: `hmctl orgs <cmd> --help`.

### Deploy & scale (single host → cluster)

**1. Set env** — copy `.env.example` → `.env` (LLM key + `RELATA_URL`), then preflight:
```bash
hmctl orgs doctor          # ✓/✗ for LLM key · Relata reachable · Hm* types writable
```

**2. Start Relata** (one-liner — the `Hm*` types auto-register; this grants the dev principal access at boot):
```bash
docker compose -f deploy/docker-compose.yml up -d relata        # → http://localhost:9090
# or bare:  docker run -p 9090:9090 -e RELATA_ORG_MODE=lite \
#   -e RELATA_ACL_GRANT="HmClaim:read+write,HmDispute:read+write,HmReputation:read+write,HmTranscript:read+write" \
#   ghcr.io/zysec-ai/relata:latest serve
```

**3. Run** — single host: `hmctl orgs simulate … --live`. For a **cluster** (Locust-style master/worker, all sharing one Relata), the copy-paste path is Kubernetes:
```bash
kubectl create secret generic hm-llm --from-literal=OPENAI_API_KEY=sk-...
kubectl apply -f deploy/k8s/orgs-distributed.yaml     # Relata + master + 8 workers
kubectl scale deploy/hm-orgs-worker --replicas=16     # scale the fleet
kubectl logs deploy/hm-orgs-master -f                 # watch it
```
Or run the master/worker processes by hand on any hosts:
```bash
python -m hypermind.orgs.distributed master --template university \
    --members 10000 --rounds 8 --expected-workers 4 --host 0.0.0.0 --port 8765 \
    --relata-url http://<relata-host>:9090
python -m hypermind.orgs.distributed worker --master-host <master-ip> --port 8765 --capacity 2500
```

Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.

---

## SimLab modes (the demo UI)

**SimLab is a demo app**, not the core — a Vue web UI (bundled under `hypermind.simlab`) that visualises the same SDK primitives the `hypermind.orgs` engine drives programmatically. Use `hypermind.orgs` to build simulations; use SimLab to *watch* one. `hmctl simlab` ships 8 deliberation modes that exercise different protocol primitives:

| Mode | One-liner |
|---|---|
| **Governance Committee** | FROST 3-of-5 signed verdict on a model card; signed dissents preserved as receipts |
| **What-If Scenario Tree** | Branching counterfactuals with InformationGainPlanner suggestions |
| **Red-Team Stress Test** | Bonded dispute FSM swimlanes; surfaces structural weaknesses in any claim |
| **Post-Incident AAR** | HLC time-slider — drag back to see what the swarm believed at any moment |
| **Decision Tournament** | Pairwise bracket with Condorcet winner + sensitivity pivots |
| **Crisis Tabletop** | Auto-composes a swarm by scenario family; produces a recommended playbook |
| **Backtest Harness** | Predicted vs. actual scoring with per-role drop-one attribution |
| Binary Forecast | The original calibration-research shape |

Full reference: [`docs/simlab/modes.md`](docs/simlab/modes.md).

---

## 60-second demo

```bash
pip install hypermind                                           # 1️⃣  install
python -m examples.01_hello_world                              # 2️⃣  one signed claim
python -m examples.03_consult_panel                            # 3️⃣  query a panel of peers
python -m examples.scenario_threat_intel                       # 4️⃣  4-org collective-intelligence pilot
python -m examples.scenario_geopolitical_crisis --agents 100   # 5️⃣  100-agent crisis sim
python -m examples.serve_api --persist demo.db                  # 6️⃣  HTTP API + durable storage
```

…or paste this into a Python REPL — five agents form a swarm and answer collectively:

```python
import asyncio
from hypermind import Uncertainty, testbed_cohort

async def demo():
    # Five agents join one room — the swarm comes alive.
    async with testbed_cohort(5, room="ai-safety") as agents:
        alice, bob, carol, dave, eve = agents

        # Three agents independently learn, each publishing a signed finding.
        # (Like three lab notebooks contributing to a literature.)
        for who in (alice, dave, eve):
            await who.publish_claim(
                {"finding": f"{who.keypair.did_key[:18]}'s observation"},
                claim_type="eval_result",
                uncertainty=Uncertainty.beta(8, 2),    # mean ≈ 0.8 confidence
            )

        # Carol summons the swarm: "what do you collectively believe?"
        # `route_strategy="disagreement"` picks the panel whose posteriors
        # diverge most — maximises information gain (BALD-style).
        result = await carol.consult(
            "Is HCAST-42 a real model failure?",
            panel_size=3,
            route_strategy="disagreement",
        )

        print(f"swarm posterior      = {result.posterior!r}")
        print(f"panel disagreement   = {result.disagreement:.3f}")
        print(f"selection-bias check = {result.calibration_truth_axis.warning}")
        print(f"sealed receipt kid   = {result.receipt_kid.hex()[:24]}…")

asyncio.run(demo())
```

That's a swarm at work: three independent observations, **aggregated with reputation weights**, **panel-routed for maximum information gain**, **sealed as a verifiable signed receipt**. No shared database. No central server. No accounts.

---

## Two use cases that make it click

### 🛡️ Use case 1 — Cross-bank threat intel that doesn't leak
**Problem.** Bank A's SOC agent spots a new phishing kit at 03:14 UTC. Bank B sees it 40 minutes later — too late. Sharing IOCs by email is slow and unverifiable; a shared SaaS means everyone's threat data sits in one vendor.

**With `hypermind`.** Bank A's agent publishes a signed claim: *"domain `xyz.click` is C2 for kit-9921, confidence 0.87."* Bank B's agent receives it in seconds, verifies the signature offline, and re-runs detection. Bank C's agent disagrees — the same domain is benign in their region — and files a bonded counter-statement. A panel of 5 ISAC peers consults; the sealed receipt records the outcome. Two weeks later, ground truth lands. Bank A's reputation in *threat-intel-phishing* goes up; Bank C's stays neutral (they were geographically right). **No vendor in the middle. Audit trail valid in 2045.**

### 🧪 Use case 2 — AI-safety eval consortium (METR / Apollo / AISI shape)
**Problem.** Three labs run the same dangerous-capability eval. They get different numbers. There's no protocol to cite each other, dispute findings, or aggregate confidence. PDFs and Slack threads are the state of the art.

**With `hypermind`.** Lab A publishes `eval_result(HCAST-42, pass_rate=0.31)` — signed, citeable. Lab B re-runs, gets 0.28, publishes a `synthesize` claim that cites Lab A as parent. Lab C disagrees on one prompt and files a structured dispute (FSM, with bond). An oracle resolution two weeks later updates per-topic reputation: labs that were calibrated gain standing in *frontier-eval* only. **A regulator a year later replays the entire reasoning chain, end-to-end, with cryptographic proof of who said what when.**

> Both stories use the same five primitives: `share`, `dispute`, `consult`, `evolve`, `remember`. That's the whole point — one substrate, every cross-org agent workflow.

---

## How the swarm stays trustworthy

A swarm without trust is just noise. `hypermind` ships the safety primitives that turn collective intelligence into **evidence**:

- 🔏 **Signed claims (COSE)** — every finding verifiable offline, today or in 2045. *Without this: an attacker forges findings.*
- ⚖️ **Disputes as data** — `OPEN → ARGUE → COUNTER → CLOSED | FRIVOLOUS` with topic-scoped bonds. **Disagreement is the immune system.**
- 🎯 **Reputation per topic** — bounded vouching defeats ring-laundering. *Without this: a few bad actors poison the swarm.*
- 🛡️ **Capability tokens** — Biscuit-shape caveat chains. Agents delegate authority but never widen it.
- 🔮 **Hybrid post-quantum** — Ed25519 today + ML-DSA-65 hybrid for 2045 verifiability.
- 🧮 **Threshold signatures** — RFC 9591 FROST k-of-n. 5-of-7 councils sign without a single point of failure.
- 📜 **Transparency log** — RFC 6962 Merkle with witness cosigning over `(root, tree_size)`.

Each is an industry-standard primitive. Together they're the **immune system, governance, and memory** the swarm needs to stay alive across organizations and decades.

---

## Cascaded security — five layers, failure-isolated

v0.9.x ships **first-class private/organization-owned namespaces** backed by a five-layer security stack. The **failure-isolation invariant** means compromise of any single layer leaves the invariants of the other four intact:

| Layer | What it does | Inherits | Falls ⇒ what still holds |
|---|---|---|---|
| **L1 — Signature & domain binding** | A-ALG-BOUND COSE_Sign1; canonical-CBOR re-encode before verify | RFC 9052, RFC 8949 | L2/L3/L4/L5 unchanged |
| **L2 — Transport (mTLS)** | TLS 1.3 mutual auth with raw public keys; kid via SAN OID; ALPN `hm/2` | RFC 8446, RFC 7250 | L3 envelope still encrypted to non-MITM recipients |
| **L3 — Envelope encryption** | HPKE + COSE_Encrypt0 + per-Room HKDF epoch keys; **separability invariant** | RFC 9180, RFC 9052 §5.2 | L1 metadata still verifies *without decryption* |
| **L4 — Namespace identity** | FROST k-of-n founding cohort, `did:web` rendezvous, transparency-anchored | RFC 9591, DID Core | L5 ns: caveat still rejects cross-namespace token reuse |
| **L5 — Capability + ACL** | Biscuit-shape attenuation with `ns:` / `room:` / `to:` caveats; deny-precedence ACL | Biscuit semantics | L4 namespace_id binding still enforced at the wire |

**Public capture-cost lower bound.** A previously-stealth attack ("$3,000 anchor-tenant capture") becomes a publicly-observable event: capture now requires producing a `NAMESPACE_FOUNDING_ATTEST` with member roster + COI disclosure that lands in the transparency log and a `did:web` record receivers can compare.

See `/security` in the SimLab UI for the visual stack, or read [docs/spec/21-private-namespaces.md](docs/spec/21-private-namespaces.md).

---

## Who this is for

- **Multi-agent research labs.** Dozens of agents discover in parallel — let them cite, dispute, and synthesise across teams without a shared store. → [`scenario_information_pipeline.py`](examples/scenario_information_pipeline.py)
- **AI-safety eval consortia** (METR, Apollo, AISI). Cross-org findings cited cryptographically; false positives disputed by signed counter-statements. → [`scenario_threat_intel.py`](examples/scenario_threat_intel.py)
- **Financial-sector ISACs.** Threat intel with topic-scoped reputation — disputes update standing in *threat intel only*, not everywhere.
- **Biosecurity / dual-use disclosure.** Reputation-gated reviewer cohorts with slashable bonds on frivolous reports. → [`scenario_namespace_trust.py`](examples/scenario_namespace_trust.py)
- **Curious Python developers.** Async-first, dataclass-typed, fully type-hinted. Run the [60-second demo](#60-second-demo).

If your problem doesn't involve cross-organizational agents, you don't need `hypermind` — use Postgres + Sigstore. **If it does, this is the substrate.**

---

## 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 the protocol layer of that agenda. The thesis:

- **Single-agent capability is not the bottleneck.** Frontier models are already extraordinary in isolation. The bottleneck is *integration* — how a swarm of agents from different labs, companies, and jurisdictions can learn collectively without surrendering accountability.
- **Connected intelligence has been studied for decades** — social epistemology (Goldman, Longino), collective intelligence (Malone, Woolley), mechanism design (Prelec, Shnayder, Frongillo, Parkes), distributed systems (Tendermint, Sigstore, SCITT). What was missing was a working *substrate*.
- **Open by default.** Spec, SDK, security reviews, formal-method sketches, failure-mode analysis — all Apache-2.0. The substrate of connected agent intelligence has to be a public good; otherwise the only "swarm" any lab can build is the one inside its own walls.

> *"The swarm gets smarter the moment one agent's mistake can be corrected by another."* — internal ZySec note, January 2026

Open research questions — peer-prediction theory, calibration under adversarial pressure, dispute-FSM completeness, post-quantum agent identity — live in [Discussions](https://github.com/ZySec-AI/hypermind/discussions).

---

## Architecture in 30 seconds

```
       Your code
          │
          ▼
    HyperMindAgent  ──── publish_claim · consult · synthesize · dispute
          │                             · task · place_on · mcp_call
   ┌──────┼──────┬──────────┐
   ▼      ▼      ▼          ▼
 wire/  knowledge/  transport/       mcp/
 COSE   reputation  • InProcessBus   • JSON-RPC 2.0 stdio/WebSocket
 CBOR   transparency  • TCPGossipBus   • MCP_PROVENANCE header binding
 A-ALG-               • libp2p (v0.2)  • TaskGateway + idempotent retry
 BOUND                 • placement      tasks/
                       • backpressure   • distributed task coordination
   │
   ▼
 crypto/
 Ed25519 · ML-DSA-65 hybrid · FROST · BLAKE3 · HLC
```

Drilldown: [docs/concepts.md](docs/concepts.md) ·
Spec: [docs/spec/](docs/spec/) ·
Standards inheritance: [docs/_meta/standards-map.md](docs/_meta/standards-map.md)

---

## Getting started

### 5-minute path
1. **Install:** `pip install hypermind` (Python 3.11–3.13)
2. **Run hello-world:** `python -m examples.01_hello_world`
3. **Read the [getting-started guide](docs/getting-started.md)**

### 30-minute path — the four numbered tutorials, in order

| # | What you'll do | Time |
|---|---|---|
| [`01_hello_world.py`](examples/01_hello_world.py) | One agent, one signed claim | 2 min |
| [`02_two_agents_dispute.py`](examples/02_two_agents_dispute.py) | Add a second agent, file a bonded dispute | 5 min |
| [`03_consult_panel.py`](examples/03_consult_panel.py) | Query a panel — collective intelligence in action | 5 min |
| [`04_oracle_resolve.py`](examples/04_oracle_resolve.py) | Close the loop with ground truth — the swarm gets smarter | 5 min |

Then graduate to the [pilot scenarios](examples/) — full multi-agent, multi-topic flows that mirror real adoption stories.

### The flagship simulation — 100 agents, one crisis

```bash
python -m examples.scenario_geopolitical_crisis --agents 100 --verbose
```

100 analyst agents (intel agencies, think-tanks, financial firms, NGOs, contrarians, oracles) deployed into a geopolitical crisis. They publish observations, dispute disinformation, run panel consults, and resolve with oracle ground truth — all in under a second, all cryptographically signed. Pass `--audit audit.jsonl` to capture the full tamper-evident log.

```bash
# Ask custom questions by editing PANEL_QUESTIONS in the scenario file
# Scale down for development:
python -m examples.scenario_geopolitical_crisis --agents 20
# Full run with JSON output piped for downstream processing:
python -m examples.scenario_geopolitical_crisis --agents 100 | jq .panel_results
```

See **[docs/simulations.md](docs/simulations.md)** for how to build your own domain simulation.

### When you're stuck
- `hmctl doctor` — smoke-tests the install + dependencies
- `hmctl why-blocked <action>` — every refusal carries `rule_id` + `spec_ref`
- [Discussions](https://github.com/ZySec-AI/hypermind/discussions) — most onboarding questions are already there

---

## Documentation

| You want to… | Go here |
|---|---|
| Install and run your first signed claim | **[docs/getting-started.md](docs/getting-started.md)** |
| Run a 100-agent domain simulation | **[docs/simulations.md](docs/simulations.md)** |
| Add durable storage, HTTP API, or LLM responders | **[docs/architecture-v0.6.md](docs/architecture-v0.6.md)** |
| Understand the core concepts | [docs/concepts.md](docs/concepts.md) |
| Browse runnable examples | [examples/README.md](examples/README.md) |
| Read the protocol spec (28 normative sections) | [docs/spec/](docs/spec/) |
| Understand agent-to-agent networking & MCP transport | [docs/spec/01-transport.md](docs/spec/01-transport.md) + [src/hypermind/mcp/](src/hypermind/mcp/) |
| See the 5-layer cascaded security stack | [docs/spec/21-private-namespaces.md](docs/spec/21-private-namespaces.md) + `/security` in SimLab |
| Read the IEEE paper draft + patent disclosure | [docs/paper/](docs/paper/) or `/paper` in SimLab |
| Decide if HyperMind fits your problem | [docs/decide/](docs/decide/) |
| Operate a deployment | [docs/operate/](docs/operate/) |
| See the roadmap | [ROADMAP.md](ROADMAP.md) |
| Contribute | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Report a security issue | [SECURITY.md](SECURITY.md) |

---

## Project status

**v0.10 — coordination engine shipped.** v0.5–v0.10 are all 🟢 code-complete (federation, versioning, trust bundle, crypto hardening, production profile, conformance scaffolding, full mind / swarm-intelligence layer, and coordination engine).

✅ **What works today**
- Spec — **28 normative sections** (§01–§28) covering protocol, transport mTLS, envelope encryption, namespace identity, capability extensions, workflow (§26), contract-net (§27), and distributed tracing (§28)
- Reference Python SDK — async-first, fully type-hinted, **1753 tests passing, ≥95% coverage**
- 20 numbered tutorials (06/07 are v0.7 placeholders) + 20+ scenarios (incl. `scenario_private_namespace`, `scenario_regulated_consortium`)
- CLI (`hmctl`), hybrid post-quantum signing, FROST k-of-n threshold (RFC 9591)
- Three cycles of [self-heal security review](tests/test_self_heal_cycle1.py) — including the v0.9.x **5-layer failure-isolation regression** ([test_self_heal_cycle3_cascade_isolate.py](tests/test_self_heal_cycle3_cascade_isolate.py))
- **Two-impl interop** — independent [`reference_verifier/`](reference_verifier/) re-implements every primitive from spec text, byte-equal CDDL hashes
- **L2 mTLS profile**, **L3 HPKE envelope encryption**, **L4 namespace lifecycle** (FROST-rooted CREATE / FOUNDING_ATTEST / INVITE / ACCEPT), **L5 ns:/room:/to: caveats + ACL**
- **MCP transport** (`src/hypermind/mcp/`) — agent-to-agent tool calls via JSON-RPC 2.0 over stdio/WebSocket with `MCP_PROVENANCE` protected-header binding (calling_agent_kid + cap_token_root + request_kid)
- **TaskGateway** with InProcessGateway + MCPGateway, cancel/timeout, and idempotent retry; distributed task coordination via `src/hypermind/tasks.py`
- **ConsistentHash placement** (`agent.place_on()` topology hint) and credit-based flow control (TokenBucket backpressure in `transport/bus.py`)
- **libp2p scaffold** (`transport-rust/` Cargo crate, `hypermind[libp2p]` extra, raise-on-use until v0.2 backend lands)
- **Workflow primitives** (§26), **contract-net protocol** (§27), **distributed cognitive layer** (§28)
- **SimLab web UI** at `make run` — Security, Use Cases (125 cases), Namespaces, Docs/Paper/Patent

🛣️ **Roadmap to v1.0 GA** (full plan in [ROADMAP.md](ROADMAP.md)) — engineering is largely done; remaining gates are external:
IETF I-D submission · IANA early allocation · OpenSSF Sandbox/Incubating · third-party security audit · full Tamarin/ProVerif proofs · ≥2 non-ZySec maintainers · ≥3 pilot MOUs · 7-day chaos-test green run · 30-day side-channel CT.

---

## Testing & quality

```bash
make test                                                      # 1753 passing, ~80s
make cov                                                       # ≥95% coverage gate
.venv/bin/python -m pytest tests/test_two_impl_interop.py      # SDK ↔ verifier interop
.venv/bin/python -m pytest tests/test_self_heal_cycle1.py \
                           tests/test_self_heal_cycle2.py \
                           tests/test_self_heal_cycle3_cascade_isolate.py  # security regressions
.venv/bin/python -m pytest tests/test_priv_ns_conformance_coverage.py      # C-PRIV-NS-01..18
```

Covers: real Ed25519 + ML-DSA-65 hybrid signing (with splice-attack rejection), full FROST k-of-n with deterministic nonces, A-ALG-BOUND wire-substitution defences, dispute FSM with partition-heal terminal, capability chain-of-trust with `ns:` namespace caveats, RFC 6962 inclusion proofs, RFC 9180 HPKE round-trip, COSE_Encrypt0 separability invariant, TLS 1.3 mTLS profile (cipher floor, ALPN downgrade-detect, RPK kid binding), and the **5-layer failure-isolation regression** that proves any single layer can be compromised without breaching the other four.

---

## Contributing

We welcome issues, design discussions, and PRs. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for dev setup, commit conventions, and the PR checklist.

- 🐛 Bug? → [open an issue](https://github.com/ZySec-AI/hypermind/issues)
- 🔒 Security report? → [SECURITY.md](SECURITY.md)
- 💡 Idea? → [Discussions](https://github.com/ZySec-AI/hypermind/discussions)
- 🤝 Code? → check `good first issue` and `help wanted` labels

By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).

---

## License & credits

Apache-2.0 — see [LICENSE](LICENSE).

`hypermind` 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), [RFC 6962 Merkle transparency](https://datatracker.ietf.org/doc/html/rfc6962), and [c2sp.org/tlog-witness](https://github.com/C2SP/C2SP/blob/main/tlog-witness.md).

---

<div align="center">

**HyperMind — the protocol for swarm intelligence between AI agents.**

*Many minds, learning together — across companies, with cryptographic chain of custody.*

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

</div>
