hypermind 2.0.2__tar.gz → 2.1.2__tar.gz

{hypermind-2.0.2 → hypermind-2.1.2}/CHANGELOG.md

@@ -14,6 +14,31 @@ changes only on major-version bumps.
 
 ## [Unreleased]
 
+## [2.1.2] — 2026-07-27
+
+### Added
+- **`hmctl serve-endpoint` LLM responder auto-wiring**: auto-detects `OPENAI_API_KEY` / `OPENAI_BASE_URL` / `HYPERMIND_LLM_MODEL` from env and wires `OpenAIResponder` at startup — all three models (`hm-network`, `hm-corpus`, `hm-moa`) now generate real LLM rationale when a key is present. Falls back to reputation-only with a warning when no key is set.
+- **`--system-prompt` flag on `serve-endpoint`**: default scopes every panel member to swarm-verified knowledge and prefixes answers with `"HyperMind says — "`. Override with `--system-prompt "..."` per invocation.
+- **`"HyperMind says — "` response prefix**: all `/v1/chat/completions` responses (streaming and non-streaming) are now prefixed, making it clear answers come from the HyperMind swarm.
+
+### Fixed
+- Docker `CMD`: `hmctl mcp serve` now explicitly passes `--write --log-level info` — connections and tool calls are visible in `docker logs` output.
+
+## [2.1.1] — 2026-07-27
+
+### Added
+- **Web search result capture** (#973): agents now fetch every search result URL (previously capped at 3), convert HTML to clean markdown via `trafilatura` (strips nav/ads/footers), and store in Relata `/memory/remember` under `{agent_id}/web-search/{url_hash}` with full metadata. Each page is linked to its originating claim via `associate("source_for")`. Future rounds can recall full page content via `/memory/recall` instead of snippets only. `trafilatura>=1.6` added to the `[ingest]` optional extra; falls back to bs4 then skips gracefully.
+- **`hmctl status` endpoint panel**: a dedicated always-visible panel shows HyperMind's OpenAI-compatible endpoint URL, connection snippet, all models with descriptions, and all routes — turns green when live.
+- **`GET /v1/models` spec compliance**: response now includes `created` (Unix timestamp) alongside `id`, `object`, `owned_by`, and `description` — fully OpenAI-spec-compliant.
+
+### Fixed
+- Docker: `hmctl mcp serve` env file no longer overrides compose-set env vars (e.g. `RELATA_URL`) — process env takes priority over `/data/env` file values.
+
+## [2.1.0] — 2026-07-27
+
+### Added
+- **Mixture-of-Agents (MoA) OpenAI-compatible endpoint** (EPIC #949): `learn(topic)` runs one research cycle with a large model and persists what was learned to `KernelStore`; from then on `model="hm-moa"` on the existing OpenAI-compatible endpoint answers questions by having a small/cheap model panel **propose** independent draft answers, then verify or consolidate them — verified by sandboxed execution for code (`CodeExecutionAnchor`, #959), reputation/calibration-weighted synthesis otherwise (#951) — instead of passing through one panelist's raw text. Query digestion condenses multi-turn chat into a standalone, topic-routed, bounded-decomposed query before serving (#963); a verifiability-class router (V/C/S/G, #958) picks the right verdict mechanism per question and discloses trust/expertise tiers; a readiness gate fails closed with a stable `rule_id` and self-queues a research goal on cold topics instead of answering weakly (#956); bounded critique/revise refinement (#960) and real per-proposer SSE streaming (#952) round out the serving path. Self-improvement closes several loops: population evolution now reaches `select_experts()` (#961), `tool_outcomes` feedback is read as well as written (#964), the pipeline's own orchestration parameters (panel size, aggregation weighting) evolve under the same regression-gated pattern as personas (#966), and research decomposition uses best-first/beam search over independent candidate plans instead of single-thread refinement (#967). A mandatory adversarial Sceptic pass gates confidence-only hypothesis confirmation absent an external ground-truth anchor (#968), and lightweight integrity monitors flag — and seal as tamper-evident, signed records — gaming of the system's own verification (#969). A benchmark harness (#955) and signed, independently-replayable evaluation bundles (#965) substantiate the "beats a frontier model at a fraction of cost" claim, with sample efficiency (calls/tokens-to-confidence) tracked as its own objective alongside quality and `$`-cost (#970). `hmctl moa {learn,status,ask,serve,benchmark,replay-bundle}` plus `examples/30_moa_endpoint.py` (CI-safe, no API key required) cover the CLI and drop-in-adoption surface (#957, #971) — the real, unmodified `openai` Python SDK works against `hm-moa` via a `base_url` change alone, including standard-shaped error handling for structured refusals.
+
 ### Added
 - **L1–L5 Autonomous Intelligence Stack** (EPIC #932): the full five-level autonomy ladder. **L1** — a `GroundingGapTracker` (#891) turns recurring zero-grounding topics in `OrgSim._think()` into self-generated research goals merged into `run_forever()`'s EIG-ranked candidate list. **L2** — `ReputationKernel.eigentrust()` (#892, #902) computes transitive trust over the vouch graph (EigenTrust power iteration), blended into `select_experts()`'s ranking and exposed via `hm_agents`. **L3** — `KernelStore` schema v6 adds a `lattice_root` (#894, #903): an RFC 6962 Merkle root over confirmed knowledge, independently verifiable via `KernelStore.verify_lattice()` without the local HMAC secret. **L4** — a deterministic evolve-tick → clone → outperform test plus `apply_calibration_feedback()` (#895, #904) wiring Brier/ECE calibration into `KernelStore.policy_params` via an opt-in `hm_calibration` `apply_feedback` param. **L5** — `propose_policy_change()`/`check_quorum()`/`apply_ratified_proposal()` (#896, #905): policy changes are published as signed claims and must survive the existing, unmodified dispute FSM before taking effect — a single dispute blocks ratification unilaterally. See `docs/concepts.md` §13 for the full write-up. Two smaller gaps closed alongside: versioned skill evolution with bounded history (#900) and a confirmation-rate quality gate on skill synthesis (#850), closing EPIC #934.
 - **Rust port** — a new `rust/` Cargo workspace (`hypermind-proto` protocol-primitives library + `hmctl` daemon-client CLI) covering the wire format (COSE_Sign1, A-ALG-BOUND), Ed25519 + ML-DSA-65 hybrid PQ signing, RFC 9591 FROST threshold Schnorr, the reputation kernel, the dispute FSM, Bloom-filter anti-entropy, and a TCP gossip transport interoperable with the Python `TCPGossipBus`. Proven via genuine cross-language interop tests (real subprocesses, real sockets) and conformance vectors shared with the Python SDK. See `rust/README.md` for scope and what deliberately stays Python-only (#924–#931).

{hypermind-2.0.2 → hypermind-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 2.0.2
+Version: 2.1.2
 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
@@ -55,6 +55,7 @@ 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'

{hypermind-2.0.2 → hypermind-2.1.2}/deploy/Dockerfile

@@ -60,4 +60,4 @@ EXPOSE 8484 8766
 #   OPENAI_BASE_URL=http://...     # local model (Ollama etc.)
 #   HYPERMIND_LLM_MODEL=gpt-4o
 #   RELATA_URL=http://relata:9090  # optional durable ledger
-CMD ["hmctl", "mcp", "serve"]
+CMD ["hmctl", "mcp", "serve", "--write", "--log-level", "info"]

{hypermind-2.0.2 → hypermind-2.1.2}/deploy/Dockerfile.mcp

@@ -16,4 +16,4 @@ VOLUME ["/config"]
 # TCP MCP (multi-user JSON-RPC), SSE dashboard
 EXPOSE 8484 8766
 
-CMD ["hmctl", "mcp", "serve", "--config", "/config/mcp.toml"]
+CMD ["hmctl", "mcp", "serve", "--config", "/config/mcp.toml", "--write", "--log-level", "info"]

hypermind-2.1.2/examples/30_moa_endpoint.py

@@ -0,0 +1,175 @@
+"""Example 30 — MoA endpoint: learn once, serve consolidated swarm answers.
+
+THE STORY
+─────────
+You've read about HyperMind's Mixture-of-Agents pipeline: agents learn a
+topic once with a big model, then a small/cheap model panel serves
+consolidated, provenance-tagged answers at a fraction of the cost of one
+frontier-model call per question. This example runs that whole loop —
+learn → mount the endpoint → ask — using the REAL `openai` Python SDK
+client, unmodified, pointed at `model="hm-moa"` via `base_url` alone
+(#971's drop-in-adoption bar).
+
+WHAT THIS EXAMPLE SHOWS
+────────────────────────
+  1. learn("Python") — one research cycle, persisted to KernelStore
+  2. Mounting the OpenAI-compatible endpoint with model="hm-moa"
+  3. Pointing the unmodified `openai` SDK client at it (base_url swap only)
+  4. Reading the consolidated answer AND its provenance — but the
+     provenance is optional: `resp.choices[0].message.content` alone is a
+     complete, usable answer even if you never look at `resp.model_extra`.
+
+PREREQUISITES
+  None for the default run — with no ANTHROPIC_API_KEY/OPENAI_API_KEY set,
+  this uses a deterministic synthetic client (same convention as
+  simlab's no_llm=), so it's CI-runnable with no network access. Set
+  ANTHROPIC_API_KEY or OPENAI_API_KEY to see it run against a real model.
+
+Two-command equivalent from a shell, no code:
+    hmctl moa learn "Python"
+    hmctl moa serve
+"""
+
+# Run: python -m examples.30_moa_endpoint
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+
+class _Chunk:
+    def __init__(self, content: str) -> None:
+        self.choices = [type("C", (), {"delta": type("D", (), {"content": content})()})()]
+
+
+class _NonStreamResponse:
+    def __init__(self, content: str) -> None:
+        message = type("M", (), {"content": content})()
+        self.choices = [type("C", (), {"message": message})()]
+
+
+class _SyntheticClient:
+    """Deterministic offline stand-in for a real LLM client — used when no
+    API key is configured, so this example runs in CI without network
+    access (mirrors `simlab`'s `no_llm=` convention rather than skipping
+    the example outright)."""
+
+    def __init__(self, text: str) -> None:
+        self._text = text
+
+    @property
+    def chat(self):
+        return self
+
+    @property
+    def completions(self):
+        return self
+
+    async def create(self, *, model, messages, stream: bool = False, **kw):
+        if stream:
+            words = self._text.split()
+
+            async def gen():
+                for w in words:
+                    yield _Chunk(w + " ")
+
+            return gen()
+        return _NonStreamResponse(self._text)
+
+
+def _pick_llm_client() -> tuple[str | None, object]:
+    """Real provider client when a key is configured, synthetic otherwise."""
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        import anthropic
+
+        return "anthropic", anthropic.AsyncAnthropic()
+    if os.environ.get("OPENAI_API_KEY"):
+        import openai as openai_sdk
+
+        return "openai", openai_sdk.AsyncOpenAI()
+    print("  (no ANTHROPIC_API_KEY/OPENAI_API_KEY set — using a synthetic offline client)")
+    return None, _SyntheticClient(
+        "Python decorators wrap a function to extend its behavior without "
+        "modifying its source, using the @ syntax placed above a def."
+    )
+
+
+async def _learn_or_seed_offline(llm_name: str | None, client: object) -> None:
+    """learn("Python") for real when an API key is configured. Offline, we
+    seed the same KernelStore records `learn()` would have produced instead
+    of faking OrgSim.study()'s multi-round Anthropic/OpenAI response
+    contract — the MoA test suite makes the identical call: don't fake
+    study()'s LLM interaction, seed the KernelStore state it would leave
+    behind (see tests/moa/conftest.py's own documented reasoning).
+    """
+    if llm_name is not None:
+        from hypermind.moa import learn
+
+        report = await learn("Python", llm=llm_name, llm_client=client, rounds=1)
+        print(f"  facts learned:        {report.n_facts_learned}")
+        print(f"  hypotheses confirmed: {report.n_hypotheses_confirmed}")
+        print(f"  personas ready:       {len(report.personas_ready)}\n")
+        return
+
+    from hypermind.knowledge.kernel_store import KernelStore, PersonaKernelState
+    from hypermind.moa.digest import record_topic_learned
+    from hypermind.moa.model import DEFAULT_PERSONAS, persona_slug
+
+    facts = [
+        "Python decorators wrap a function to extend its behavior without modifying its source",
+        "Decorators use the @ syntax placed directly above a function definition",
+    ]
+    for seat, fact in zip(DEFAULT_PERSONAS, facts):
+        KernelStore.save(
+            PersonaKernelState(
+                persona=persona_slug(seat), learned_facts={"python": [{"fact": fact}]}
+            )
+        )
+    record_topic_learned("python")
+    print(f"  (offline: seeded {len(facts)} facts directly — same end state as learn())\n")
+
+
+async def main() -> None:
+    print("MoA endpoint — learn once, serve consolidated swarm answers.\n")
+
+    llm_name, client = _pick_llm_client()
+
+    print('Step 1 — learn("Python"): one research cycle, persisted to KernelStore.')
+    await _learn_or_seed_offline(llm_name, client)
+
+    print('Step 2 — mount the OpenAI-compatible endpoint (model="hm-moa").')
+    from hypermind.integrations.openai_endpoint import create_app
+
+    app = create_app(moa_client=client)
+
+    print("Step 3 — point the unmodified `openai` Python SDK at it (base_url swap only).")
+    import httpx
+    import openai
+
+    transport = httpx.ASGITransport(app=app)
+    http_client = httpx.AsyncClient(transport=transport, base_url="http://hm-moa.local/v1")
+    sdk_client = openai.AsyncOpenAI(api_key="unused", http_client=http_client)
+
+    resp = await sdk_client.chat.completions.create(
+        model="hm-moa",
+        messages=[{"role": "user", "content": "How do Python decorators work?"}],
+    )
+    print(f"\n  Answer: {resp.choices[0].message.content}\n")
+
+    print("Step 4 — the provenance is additive, not required reading (#971):")
+    ext = (resp.model_extra or {}).get("hypermind", {})
+    print(f"    confidence   = {ext.get('confidence')}")
+    print(f"    disagreement = {ext.get('disagreement')}")
+    print(f"    contributors = {len(ext.get('contributors', []))}")
+
+    print("\n✓ MoA endpoint example complete.")
+    print()
+    print("WHAT'S NEXT")
+    print("───────────")
+    print('  • hmctl moa learn "<topic>" && hmctl moa serve  — the same loop, two shell commands')
+    print("  • examples/05_consult_to_synthesis.py           — the consult-based (non-MoA) path")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{hypermind-2.0.2 → hypermind-2.1.2}/examples/README.md

@@ -76,12 +76,13 @@ Read in order. Each builds on the previous one's mental model.
 | 20 | [`20_conformance_check.py`](20_conformance_check.py) | Run 5 attack scenarios from spec §14 (`alg=none`, replay, capability widening, Sybil panel dedup, dispute bond theft). Exits non-zero on any failure. |
 | 21 | [`21_revocation.py`](21_revocation.py) | Mint a `CapToken`, delegate to a second agent, revoke the original key via `RevocationList.issue()`, confirm the delegation is now rejected. |
 
-### 28–29 — Storage and simulation quick-starts
+### 28–30 — Storage, simulation, and MoA quick-starts
 
 | # | File | What it adds |
 |---|---|---|
 | 28 | [`28_relata_connection.py`](28_relata_connection.py) | Connect to a real Relata persistence backend: set `RELATA_URL` + `RELATA_BEARER_TOKEN`, publish a claim, retrieve it back. Falls back to sandbox mode if no env vars set. |
 | 29 | [`29_quick_research_sim.py`](29_quick_research_sim.py) | Zero-dependency research sim in sandbox mode: 3-agent publish → consult → dispute → reputation cycle, completes in under 2 minutes. |
+| 30 | [`30_moa_endpoint.py`](30_moa_endpoint.py) | Mixture-of-Agents: `learn("Python")` once, mount `model="hm-moa"` on the OpenAI-compatible endpoint, ask it with the unmodified `openai` SDK client (`base_url` swap only), read the consolidated answer plus its optional provenance. CI-safe synthetic fallback with no API key; set `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` for a real model. |
 
 ---
 

{hypermind-2.0.2 → hypermind-2.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "2.0.2"
+version = "2.1.2"
 description = "Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile"
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
@@ -83,6 +83,8 @@ ingest = [
     "pypdf>=4.0",
     "python-docx>=1.0",
     "beautifulsoup4>=4.12",
+    # #973: web page fetch + markdown conversion for search result capture.
+    "trafilatura>=1.6",
 ]
 vector = [
     # #854: local (in-process, no external embedding service) semantic