hypermind 1.4.4__tar.gz → 1.4.5__tar.gz

{hypermind-1.4.4 → hypermind-1.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 1.4.4
+Version: 1.4.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

{hypermind-1.4.4 → hypermind-1.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "1.4.4"
+version = "1.4.5"
 description = "Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{hypermind-1.4.4 → hypermind-1.4.5}/src/hypermind/__init__.py

@@ -73,7 +73,7 @@ open = HyperMindAgent.open
 #: is held until the §External & human gates clear (IETF I-D, IANA,
 #: third-party audit, OpenSSF acceptance, ≥3 pilots) — at that point we
 #: cut ``1.0.0`` GA. See ROADMAP.md §Status snapshot.
-__version__ = "1.4.4"
+__version__ = "1.4.5"
 
 #: SLSA build-provenance level committed for every release artefact.
 #: Cosign keyless signing + slsa-github-generator + PEP 740 attestations

{hypermind-1.4.4 → hypermind-1.4.5}/src/hypermind/integrations/mcp_tools.py

@@ -1554,12 +1554,19 @@ def register_hypermind_tools(
 
         # Recent errors from recorder
         rec = client._primary._world.recorder
-        recent = getattr(rec, "_events", [])
-        errors = [
-            {"event": e.get("event_type"), "error": e.get("error"), "ts": e.get("ts")}
-            for e in (recent[-200:] if hasattr(recent, "__getitem__") else [])
-            if e.get("error") or e.get("status") == "error"
-        ]
+        recent = list(getattr(rec, "records", []))
+        errors = []
+        for e in recent[-200:]:
+            if hasattr(e, "event_type"):
+                # LogRecord object
+                fields = getattr(e, "fields", {}) or {}
+                err = fields.get("error") or fields.get("status")
+                if err == "error" or (isinstance(err, str) and err):
+                    errors.append({"event": e.event_type, "error": fields.get("error"), "ts": getattr(e, "ts_wall_ms", None)})
+            elif hasattr(e, "get"):
+                # plain dict fallback
+                if e.get("error") or e.get("status") == "error":
+                    errors.append({"event": e.get("event_type"), "error": e.get("error"), "ts": e.get("ts")})
 
         degraded = [f for f in features if f["status"] in ("degraded", "off", "missing")]
         next_steps = []
@@ -1596,6 +1603,203 @@ def register_hypermind_tools(
         handler=hm_status,
     )
 
+    async def hm_stats(_params: dict[str, Any]) -> Any:
+        """Segmented operational snapshot: agents, topics, claims, disputes."""
+        world = client._primary._world
+        agents_raw = list(world.agents.values()) if hasattr(world, "agents") else []
+
+        # ---- agents ----
+        rep_kernel = world.reputation
+        agent_rows = []
+        for ag in agents_raw:
+            kid = ag.keypair.kid
+            # aggregate reputation across all topics this agent has touched
+            all_rep = [
+                rep_kernel.snapshot(kid, topic).score
+                for (k, topic) in rep_kernel._posteriors
+                if k == kid
+            ]
+            avg_rep = round(sum(all_rep) / len(all_rep), 4) if all_rep else round(rep_kernel.snapshot(kid, "default").score, 4)
+            rep_tier = (
+                "established" if avg_rep >= 0.75
+                else "trusted" if avg_rep >= 0.60
+                else "provisional" if avg_rep >= 0.50
+                else "new"
+            )
+            topics_known = list({topic for (k, topic) in rep_kernel._posteriors if k == kid})
+            agent_rows.append({
+                "kid": kid.hex()[:16] + "…",
+                "role": getattr(ag, "_role", None),
+                "reputation": avg_rep,
+                "tier": rep_tier,
+                "topics": topics_known,
+                "topic_count": len(topics_known),
+                "ramp_complete": getattr(ag, "_ramp_complete", None),
+                "rooms": list(getattr(ag, "_rooms", set())),
+            })
+
+        # segment agents by tier
+        by_tier: dict[str, int] = {}
+        for row in agent_rows:
+            by_tier[row["tier"]] = by_tier.get(row["tier"], 0) + 1
+
+        # ---- claims & topics ----
+        claims = getattr(client, "_claims", [])
+        topic_map: dict[str, dict] = {}
+        for c in claims:
+            t = c.get("topic") or "default"
+            if t not in topic_map:
+                topic_map[t] = {"topic": t, "claim_count": 0, "confidences": [], "experts": 0}
+            topic_map[t]["claim_count"] += 1
+            conf = c.get("confidence")
+            if conf is not None:
+                topic_map[t]["confidences"].append(float(conf))
+
+        # count experts per topic from reputation kernel
+        for (kid_bytes, topic), posterior in rep_kernel._posteriors.items():
+            a = getattr(posterior, "alpha", 1.0)
+            b = getattr(posterior, "beta", 1.0)
+            score = a / (a + b)
+            if score >= 0.5 and topic in topic_map:
+                topic_map[topic]["experts"] += 1
+
+        topic_rows = []
+        for t, td in sorted(topic_map.items(), key=lambda x: -x[1]["claim_count"]):
+            confs = td["confidences"]
+            avg_conf = round(sum(confs) / len(confs), 3) if confs else None
+            high = sum(1 for c in confs if c >= 0.8)
+            med = sum(1 for c in confs if 0.6 <= c < 0.8)
+            low = sum(1 for c in confs if c < 0.6)
+            topic_rows.append({
+                "topic": t,
+                "claim_count": td["claim_count"],
+                "avg_confidence": avg_conf,
+                "confidence_distribution": {"high_≥0.8": high, "medium_0.6-0.8": med, "low_<0.6": low},
+                "expert_count": td["experts"],
+            })
+
+        # ---- disputes ----
+        dispute_objs = list(world.disputes.values()) if hasattr(world, "disputes") else []
+        by_state: dict[str, int] = {}
+        for d in dispute_objs:
+            state = str(getattr(d, "state", "unknown"))
+            by_state[state] = by_state.get(state, 0) + 1
+
+        # ---- recorder activity ----
+        rec = world.recorder
+        all_events = list(getattr(rec, "records", []))
+        event_counts: dict[str, int] = {}
+        for e in all_events:
+            et = getattr(e, "event_type", None) or e.get("event_type", "unknown") if hasattr(e, "get") else getattr(e, "event_type", "unknown")
+            event_counts[et] = event_counts.get(et, 0) + 1
+
+        # ---- evolution timeline (bucket recorder events by hour) ----
+        # Each event has a monotonic ts (float seconds since epoch or process start).
+        # We produce a compact timeline: [{bucket, claims, vouches, outcomes, disputes, tool_calls}]
+        LEARNING_EVENTS = {"publish_claim", "vouch", "record_outcome", "mcp_tool_call",
+                           "dispute_opened", "dispute_closed"}
+        timeline_buckets: dict[str, dict] = {}
+        import time as _time
+        _now = _time.time()
+        for e in all_events:
+            etype = getattr(e, "event_type", None) or (e.get("event_type", "") if hasattr(e, "get") else "")
+            if etype not in LEARNING_EVENTS:
+                continue
+            ts_ms = getattr(e, "ts_wall_ms", None) or (e.get("ts") if hasattr(e, "get") else None)
+            if ts_ms is None:
+                continue
+            try:
+                import datetime as _dt
+                t = float(ts_ms) / 1000 if float(ts_ms) > 1e10 else float(ts_ms)
+                bucket = _dt.datetime.utcfromtimestamp(t).strftime("%Y-%m-%dT%H:00Z")
+            except Exception:
+                bucket = "unknown"
+            if bucket not in timeline_buckets:
+                timeline_buckets[bucket] = {"bucket": bucket, "claims": 0, "vouches": 0,
+                                             "outcomes": 0, "disputes": 0, "tool_calls": 0}
+            b = timeline_buckets[bucket]
+            if etype == "publish_claim":
+                b["claims"] += 1
+            elif etype == "vouch":
+                b["vouches"] += 1
+            elif etype == "record_outcome":
+                b["outcomes"] += 1
+            elif etype in ("dispute_opened", "dispute_closed"):
+                b["disputes"] += 1
+            elif etype == "mcp_tool_call":
+                b["tool_calls"] += 1
+
+        timeline = sorted(timeline_buckets.values(), key=lambda x: x["bucket"])
+
+        # ---- knowledge base quality summary ----
+        all_confs = [float(c.get("confidence", 0)) for c in claims if c.get("confidence") is not None]
+        high_conf_claims = sum(1 for c in all_confs if c >= 0.8)
+        disputed_kids = {str(getattr(d, "claim_kid", "")) for d in dispute_objs}
+        contested_claims = sum(1 for c in claims if str(c.get("kid", "")) in disputed_kids)
+        established_agents = by_tier.get("established", 0) + by_tier.get("trusted", 0)
+        all_topics_experts = sum(r["expert_count"] for r in topic_rows)
+
+        kb_summary = {
+            "total_claims": len(claims),
+            "topics_covered": len(topic_rows),
+            "high_confidence_claims": high_conf_claims,
+            "high_confidence_pct": round(100 * high_conf_claims / len(claims), 1) if claims else 0,
+            "avg_confidence_overall": round(sum(all_confs) / len(all_confs), 3) if all_confs else None,
+            "contested_claims": contested_claims,
+            "established_or_trusted_agents": established_agents,
+            "total_expert_slots": all_topics_experts,
+            "headline": (
+                f"{len(claims)} signed claims across {len(topic_rows)} topic(s) · "
+                f"{high_conf_claims} high-confidence ({round(100*high_conf_claims/len(claims),0):.0f}%) · "
+                f"{established_agents}/{len(agent_rows)} agents established or trusted"
+                if claims else
+                "No claims yet — publish your first claim with hm_publish_claim."
+            ),
+        }
+
+        return {
+            "knowledge_base": kb_summary,
+            "agents": {
+                "total": len(agent_rows),
+                "by_tier": by_tier,
+                "list": agent_rows,
+            },
+            "topics": {
+                "total": len(topic_rows),
+                "list": topic_rows,
+            },
+            "claims": {
+                "total": len(claims),
+                "by_topic": {r["topic"]: r["claim_count"] for r in topic_rows},
+            },
+            "disputes": {
+                "total": len(dispute_objs),
+                "by_state": by_state,
+            },
+            "activity": {
+                "total_events": len(all_events),
+                "by_type": event_counts,
+            },
+            "evolution_timeline": timeline,
+        }
+
+    server.register_tool(
+        "hm_stats",
+        description=(
+            "Segmented operational snapshot of the running namespace — the full picture of what the swarm knows. "
+            "knowledge_base: headline numbers (total claims, topics covered, high-confidence %, avg confidence, contested claims, established agents). "
+            "agents: each agent's reputation tier (new/provisional/trusted/established), role, rooms, topic coverage. "
+            "topics: per-topic claim count, avg confidence, confidence distribution (high/medium/low), expert count. "
+            "claims: total + count by topic. "
+            "disputes: total + by FSM state (OPEN/ARGUE/COUNTER/CLOSED/FRIVOLOUS). "
+            "activity: recorder event counts by type (publish_claim, record_outcome, vouch, mcp_tool_call, …). "
+            "evolution_timeline: hourly buckets of learning activity (claims published, vouches, outcomes recorded, disputes, tool calls) — shows how the knowledge base has grown over time. "
+            "Use this to understand knowledge-base quality, who the domain experts are, where disputes are active, and how the swarm has evolved."
+        ),
+        parameters_schema={"type": "object", "properties": {}},
+        handler=hm_stats,
+    )
+
     server.register_tool(
         "hm_eval",
         description=(

{hypermind-1.4.4 → hypermind-1.4.5}/tests/integrations/test_mcp_tools.py

@@ -285,3 +285,45 @@ async def test_hm_status_shape():
                 assert "fix" in f, f"degraded feature {f['feature']} missing fix instructions"
     finally:
         await client.close()
+
+
+@pytest.mark.asyncio
+async def test_hm_stats_shape():
+    server, client = build_mcp_server(writable=True, swarm=3)
+    try:
+        h = server.tools
+        await h["hm_publish_claim"].handler({"text": "gene editing is precise", "confidence": 0.9})
+        await h["hm_publish_claim"].handler({"text": "off-target effects are a concern", "confidence": 0.65})
+        out = await h["hm_stats"].handler({})
+        kb = out["knowledge_base"]
+        assert kb["total_claims"] == 2
+        assert kb["topics_covered"] == 1
+        assert kb["high_confidence_claims"] == 1
+        assert 0.0 < kb["avg_confidence_overall"] < 1.0
+        assert "headline" in kb
+
+        assert out["agents"]["total"] == 3
+        assert all("tier" in a and "reputation" in a for a in out["agents"]["list"])
+
+        assert out["topics"]["total"] == 1
+        topic = out["topics"]["list"][0]
+        assert topic["claim_count"] == 2
+        assert "confidence_distribution" in topic
+
+        assert out["claims"]["total"] == 2
+        assert "evolution_timeline" in out
+        assert "activity" in out
+    finally:
+        await client.close()
+
+
+@pytest.mark.asyncio
+async def test_hm_stats_empty_namespace():
+    # covers the "no claims yet" headline branch
+    server, client = build_mcp_server(writable=True, swarm=2)
+    try:
+        out = await server.tools["hm_stats"].handler({})
+        assert out["claims"]["total"] == 0
+        assert "No claims yet" in out["knowledge_base"]["headline"]
+    finally:
+        await client.close()