hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/question_sets/geopolitics_q20.json

@@ -0,0 +1,122 @@
+[
+  {
+    "id": "geo-001",
+    "query": "Will armed conflict between two major powers begin within 30 days given mobilisation of 50,000+ troops near a disputed border?",
+    "ground_truth": 0.65,
+    "category": "kinetic"
+  },
+  {
+    "id": "geo-002",
+    "query": "Is satellite imagery showing tank columns near a border consistent with invasion preparation rather than routine exercise?",
+    "ground_truth": 0.75,
+    "category": "kinetic"
+  },
+  {
+    "id": "geo-003",
+    "query": "Will civilian casualties exceed 1,000 in the next 7 days following such mobilisation?",
+    "ground_truth": 0.55,
+    "category": "kinetic"
+  },
+  {
+    "id": "geo-004",
+    "query": "Is diplomatic de-escalation viable when both parties have already broken off ambassadorial relations?",
+    "ground_truth": 0.30,
+    "category": "diplomatic"
+  },
+  {
+    "id": "geo-005",
+    "query": "Will a UN Security Council resolution pass condemning the aggression?",
+    "ground_truth": 0.40,
+    "category": "diplomatic"
+  },
+  {
+    "id": "geo-006",
+    "query": "Will currency markets price in war risk via a >5% drop in the affected nation's currency within 7 days?",
+    "ground_truth": 0.70,
+    "category": "economic"
+  },
+  {
+    "id": "geo-007",
+    "query": "Will sovereign CDS spreads widen to >300bps within 14 days of escalation?",
+    "ground_truth": 0.65,
+    "category": "economic"
+  },
+  {
+    "id": "geo-008",
+    "query": "Will sanctions be imposed within 30 days of the first kinetic action?",
+    "ground_truth": 0.85,
+    "category": "policy"
+  },
+  {
+    "id": "geo-009",
+    "query": "Will mass civilian displacement exceed 100,000 in the first week?",
+    "ground_truth": 0.50,
+    "category": "humanitarian"
+  },
+  {
+    "id": "geo-010",
+    "query": "Will critical infrastructure (power grid, water) be deliberately targeted in the first 14 days?",
+    "ground_truth": 0.45,
+    "category": "kinetic"
+  },
+  {
+    "id": "geo-011",
+    "query": "Will a third-party state intervene militarily within 60 days?",
+    "ground_truth": 0.15,
+    "category": "kinetic"
+  },
+  {
+    "id": "geo-012",
+    "query": "Will a cyberattack on financial infrastructure precede or accompany kinetic operations?",
+    "ground_truth": 0.55,
+    "category": "cyber"
+  },
+  {
+    "id": "geo-013",
+    "query": "Will there be a credible nuclear-doctrine signal (alert posture, treaty withdrawal) in the conflict's first month?",
+    "ground_truth": 0.20,
+    "category": "kinetic"
+  },
+  {
+    "id": "geo-014",
+    "query": "Will the conflict last longer than 90 days?",
+    "ground_truth": 0.65,
+    "category": "kinetic"
+  },
+  {
+    "id": "geo-015",
+    "query": "Will a ceasefire mediated by a neutral state be agreed within 60 days?",
+    "ground_truth": 0.25,
+    "category": "diplomatic"
+  },
+  {
+    "id": "geo-016",
+    "query": "Will domestic protests in the aggressor state exceed 100,000 participants in any single city?",
+    "ground_truth": 0.30,
+    "category": "domestic"
+  },
+  {
+    "id": "geo-017",
+    "query": "Will commodity prices (oil, wheat) spike >15% within 30 days?",
+    "ground_truth": 0.55,
+    "category": "economic"
+  },
+  {
+    "id": "geo-018",
+    "query": "Will a NATO Article 4 consultation be triggered within 14 days?",
+    "ground_truth": 0.40,
+    "category": "policy"
+  },
+  {
+    "id": "geo-019",
+    "query": "Will the International Criminal Court open a formal investigation within 60 days?",
+    "ground_truth": 0.55,
+    "category": "policy"
+  },
+  {
+    "id": "geo-020",
+    "query": "Will a regime-change attempt occur in the aggressor state within 12 months of the conflict's start?",
+    "ground_truth": 0.10,
+    "category": "domestic"
+  }
+]

hypermind/simlab/question_sets/governance_q5.json

@@ -0,0 +1,67 @@
+[
+  {
+    "id": "gov-001",
+    "label": "High-risk classifier",
+    "model_card": {
+      "model_name": "credit-decision-classifier-v2",
+      "intended_use": "Score loan applications for retail banking; outputs feed an underwriter dashboard.",
+      "risk_tier": "high",
+      "dataset_provenance": "internal application history 2018-2024, documented",
+      "mitigations": ["fairness-audit-q3", "appeal-channel", "human-in-the-loop"],
+      "deployment_scope": "b2b-customer",
+      "autonomous_action": false
+    }
+  },
+  {
+    "id": "gov-002",
+    "label": "Mass-personalisation LLM",
+    "model_card": {
+      "model_name": "story-personalisation-llm",
+      "intended_use": "Generate personalised marketing copy variants at scale.",
+      "risk_tier": "limited",
+      "dataset_provenance": "publicly licensed corpora + synthetic augmentations",
+      "mitigations": ["rate-limit-100rpm", "content-filter"],
+      "deployment_scope": "public-api",
+      "autonomous_action": false
+    }
+  },
+  {
+    "id": "gov-003",
+    "label": "Clinical decision support",
+    "model_card": {
+      "model_name": "ddx-helper-research",
+      "intended_use": "Surface differential-diagnosis options and supporting evidence to clinicians.",
+      "risk_tier": "high",
+      "dataset_provenance": "MIMIC-IV (research IRB), licensed PubMed abstracts",
+      "mitigations": ["clinician-review-required", "exemption-§3060", "audit-log"],
+      "deployment_scope": "internal-only",
+      "autonomous_action": false
+    }
+  },
+  {
+    "id": "gov-004",
+    "label": "Autonomous action agent",
+    "model_card": {
+      "model_name": "auto-refund-agent-v1",
+      "intended_use": "Process small-amount refunds end-to-end without human review.",
+      "risk_tier": "high",
+      "dataset_provenance": "",
+      "mitigations": ["amount-cap-50usd"],
+      "deployment_scope": "consumer-app",
+      "autonomous_action": true
+    }
+  },
+  {
+    "id": "gov-005",
+    "label": "Children's data product",
+    "model_card": {
+      "model_name": "edu-tutor-k12",
+      "intended_use": "Personalised tutoring assistant for K-12 students.",
+      "risk_tier": "high",
+      "dataset_provenance": "COPPA-compliant licensed corpora, documented",
+      "mitigations": ["coppa-review", "age-gate", "no-pii-retention", "human-review-of-flagged"],
+      "deployment_scope": "consumer-app",
+      "autonomous_action": false
+    }
+  }
+]

hypermind/simlab/question_sets/msft_outlook_q10.json

@@ -0,0 +1,62 @@
+[
+  {
+    "id": "msft-001",
+    "query": "Will Microsoft's stock price be HIGHER 12 months from now than today?",
+    "ground_truth": 0.62,
+    "category": "price"
+  },
+  {
+    "id": "msft-002",
+    "query": "Will Azure cloud revenue growth remain ABOVE 25% year-over-year over the next four quarters?",
+    "ground_truth": 0.58,
+    "category": "fundamentals"
+  },
+  {
+    "id": "msft-003",
+    "query": "Will Microsoft generate positive ROI on its AI capex (≥$50B committed) within the next 24 months?",
+    "ground_truth": 0.55,
+    "category": "ai"
+  },
+  {
+    "id": "msft-004",
+    "query": "Will Microsoft face a MAJOR antitrust action (formal proceedings, blocked deal, or fine >$1B) within 18 months?",
+    "ground_truth": 0.32,
+    "category": "regulatory"
+  },
+  {
+    "id": "msft-005",
+    "query": "Will Microsoft's operating margin remain ABOVE 40% over the next four quarters?",
+    "ground_truth": 0.72,
+    "category": "fundamentals"
+  },
+  {
+    "id": "msft-006",
+    "query": "Will Microsoft outperform the S&P 500 over the next 12 months?",
+    "ground_truth": 0.55,
+    "category": "price"
+  },
+  {
+    "id": "msft-007",
+    "query": "Will Copilot reach 50M paid seats within 18 months?",
+    "ground_truth": 0.60,
+    "category": "ai"
+  },
+  {
+    "id": "msft-008",
+    "query": "Will Microsoft acquire a major AI company ($10B+) in the next 24 months?",
+    "ground_truth": 0.30,
+    "category": "m&a"
+  },
+  {
+    "id": "msft-009",
+    "query": "Will Microsoft's relationship with OpenAI fundamentally restructure (replaced by exclusive license, equity-only stake, or termination) within 24 months?",
+    "ground_truth": 0.40,
+    "category": "ai"
+  },
+  {
+    "id": "msft-010",
+    "query": "Will Microsoft initiate a major buyback program (>$50B authorisation) in the next 18 months?",
+    "ground_truth": 0.55,
+    "category": "capital"
+  }
+]

hypermind/simlab/question_sets/whatif_q3.json

@@ -0,0 +1,38 @@
+[
+  {
+    "id": "wif-001",
+    "label": "UAE leaves OPEC by end of 2026",
+    "payload": {
+      "hypothesis": "UAE leaves OPEC by end of 2026.",
+      "horizon_days": 365,
+      "drivers": [
+        "oil_price_usd=60|80|100",
+        "us_saudi_relations=warm|cool|cold"
+      ]
+    }
+  },
+  {
+    "id": "wif-002",
+    "label": "Fed pivots within 6 months",
+    "payload": {
+      "hypothesis": "The Federal Reserve pivots to rate cuts within 6 months.",
+      "horizon_days": 180,
+      "drivers": [
+        "core_inflation_yoy=below_2|2_to_3|above_3",
+        "labor_market=soft|balanced|tight"
+      ]
+    }
+  },
+  {
+    "id": "wif-003",
+    "label": "Major cyber-incident at a named cloud",
+    "payload": {
+      "hypothesis": "A nation-state cyber-incident affects a major cloud provider within 12 months.",
+      "horizon_days": 365,
+      "drivers": [
+        "actor_capability=nation_state|criminal|insider",
+        "blast_radius=single_tenant|regional|global"
+      ]
+    }
+  }
+]

hypermind/simlab/registry.py

@@ -0,0 +1,325 @@
+"""Sim registry — persistent on-disk record of every simulation run.
+
+Layout (under ``$HYPERMIND_HOME/sims/`` or ``~/.hypermind/sims/``):
+
+    {sim_id}/
+        config.json     — what was requested (SimConfig.to_dict())
+        trace.json      — what was produced (full Trace)
+        status.json     — lifecycle: queued|running|done|failed + progress
+        stderr.log      — captured stderr from the run
+
+A `sim_id` is ``YYYY-MM-DDTHH-MM-SS_xxxxxx`` — sortable lexicographically,
+collision-resistant via a 6-char nonce.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+def home() -> Path:
+    """Resolve the SimLab home dir.
+
+    Priority:
+    1. ``HYPERMIND_HOME`` environment variable
+    2. ``~/.hypermind``
+    """
+    raw = os.environ.get("HYPERMIND_HOME", "").strip()
+    if raw:
+        return Path(raw).expanduser()
+    return Path.home() / ".hypermind"
+
+
+def sims_dir() -> Path:
+    d = home() / "sims"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+#: Crockford base32 alphabet — no I/L/O/U so the slug stays unambiguous.
+_B32 = "0123456789abcdefghjkmnpqrstvwxyz"
+
+
+def _b32encode(n: int, length: int) -> str:
+    """Tiny base32 encoder — produces `length` chars from the low bits of n."""
+    out: list[str] = []
+    for _ in range(length):
+        out.append(_B32[n & 0x1F])
+        n >>= 5
+    return "".join(reversed(out))
+
+
+def new_sim_id() -> str:
+    """Generate a short ULID-style sim slug.
+
+    Format: ``YYYY-MM-DD-XXXXXXXXXX`` (10-char base32 random tail).
+
+    - Date prefix keeps directories scannable in `ls` by day.
+    - The 50-bit base32 tail is monotonic-within-process (millisecond
+      timestamp + a 30-bit random nonce) so IDs sort by creation time
+      *within* a day too — the same property UUIDv7 guarantees.
+    - 18 chars total, URL-safe (no `/` `:` `+` to escape), readable.
+
+    Crockford base32 alphabet (no I/L/O/U) — fewer transcription errors
+    if a user reads an id off a screen.
+
+    """
+    now_ms = int(time.time() * 1000)
+    today = time.strftime("%Y-%m-%d", time.gmtime(now_ms / 1000))
+    # 50-bit tail = 30 bits of millis-since-midnight (covers 24h) ‖ 20
+    # bits of fresh entropy. Putting millis in the HIGH bits is what
+    # makes lexicographic sort match creation order — the same property
+    # UUIDv7 / ULID guarantee. 20 bits of random tail = ~1M nonces per
+    # millisecond before a collision is even probable.
+    midnight = int(now_ms / 86_400_000) * 86_400_000
+    ms_today = (now_ms - midnight) & ((1 << 30) - 1)
+    rand = secrets.randbits(20)
+    tail = _b32encode((ms_today << 20) | rand, 10)
+    return f"{today}-{tail}"
+
+
+def new_sim_dir() -> tuple[str, Path]:
+    """Allocate a fresh sim directory; returns (sim_id, path)."""
+    sim_id = new_sim_id()
+    path = sims_dir() / sim_id
+    path.mkdir(parents=True, exist_ok=False)
+    return sim_id, path
+
+
+def sim_dir(sim_id: str) -> Path:
+    path = sims_dir() / sim_id
+    resolved = path.resolve()
+    base = sims_dir().resolve()
+    if not str(resolved).startswith(str(base)):
+        raise ValueError(f"sim_id escapes sims directory: {sim_id!r}")
+    return path
+
+
+# ---- atomic write helpers --------------------------------------------------
+
+
+def _write_json_atomic(path: Path, data: Any, mode: int | None = None) -> None:
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2, default=str))
+    if mode is not None:
+        import os
+
+        os.chmod(tmp, mode)  # chmod before rename to avoid TOCTOU window
+    tmp.replace(path)  # POSIX atomic rename
+
+
+def write_config(sim_id: str, cfg_dict: dict[str, Any]) -> None:
+    _write_json_atomic(sim_dir(sim_id) / "config.json", cfg_dict)
+
+
+def load_config(sim_id: str) -> dict[str, Any]:
+    p = sim_dir(sim_id) / "config.json"
+    if not p.exists():
+        raise FileNotFoundError(f"no config for sim {sim_id}")
+    return json.loads(p.read_text())
+
+
+def write_status(sim_id: str, status: dict[str, Any]) -> None:
+    _write_json_atomic(sim_dir(sim_id) / "status.json", status)
+
+
+def load_status(sim_id: str) -> dict[str, Any]:
+    p = sim_dir(sim_id) / "status.json"
+    if not p.exists():
+        return {"sim_id": sim_id, "state": "unknown"}
+    return json.loads(p.read_text())
+
+
+def update_status(sim_id: str, **fields: Any) -> dict[str, Any]:
+    """Read-modify-write the status.json for a sim."""
+    status = load_status(sim_id)
+    status.update(fields)
+    write_status(sim_id, status)
+    return status
+
+
+def load_trace(sim_id: str) -> dict[str, Any] | None:
+    p = sim_dir(sim_id) / "trace.json"
+    if not p.exists():
+        return None
+    return json.loads(p.read_text())
+
+
+# ---- listing ---------------------------------------------------------------
+
+
+@dataclass
+class SimSummary:
+    sim_id: str
+    state: str
+    started_at: float | None
+    finished_at: float | None
+    n_agents: int | None
+    n_questions: int | None
+    ciq_score: float | None
+    eig_mean: float | None  # S3 — primary headline metric (bits/question)
+    model: str | None
+    enable_tools: bool | None
+    deliberation_rounds: int | None
+    no_llm: bool | None
+    error: str | None
+    topic: str | None  # user-entered free-text topic (or empty if saved-set was used)
+    questions_set: str | None  # legacy saved-set name when no topic
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "sim_id": self.sim_id,
+            "state": self.state,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "n_agents": self.n_agents,
+            "n_questions": self.n_questions,
+            "ciq_score": self.ciq_score,
+            "eig_mean": self.eig_mean,
+            "model": self.model,
+            "enable_tools": self.enable_tools,
+            "deliberation_rounds": self.deliberation_rounds,
+            "no_llm": self.no_llm,
+            "error": self.error,
+            "topic": self.topic,
+            "questions_set": self.questions_set,
+        }
+
+
+def _summary_from_dir(d: Path) -> SimSummary | None:
+    sim_id = d.name
+    if not d.is_dir():
+        return None
+    status = load_status(sim_id)
+    config_path = d / "config.json"
+    cfg: dict[str, Any] = {}
+    if config_path.exists():
+        try:
+            cfg = json.loads(config_path.read_text())
+        except json.JSONDecodeError:
+            cfg = {}
+    # n_agents, n_questions, ciq_score, eig_mean are written to status.json
+    # at completion by the runner — no need to read trace.json for list views.
+    return SimSummary(
+        sim_id=sim_id,
+        state=status.get("state", "unknown"),
+        started_at=status.get("started_at"),
+        finished_at=status.get("finished_at"),
+        n_agents=status.get("n_agents") or cfg.get("personas", 0) * cfg.get("replicas", 0),
+        n_questions=status.get("n_questions"),
+        ciq_score=status.get("ciq_score"),
+        eig_mean=status.get("eig_mean"),
+        model=cfg.get("model"),
+        enable_tools=cfg.get("enable_tools"),
+        deliberation_rounds=cfg.get("deliberation_rounds"),
+        no_llm=cfg.get("no_llm"),
+        error=status.get("error"),
+        topic=cfg.get("topic") or None,
+        questions_set=cfg.get("questions") or None,
+    )
+
+
+def list_sims(*, limit: int | None = None) -> list[SimSummary]:
+    """Return summaries newest-first. Skips empty/corrupt directories."""
+    out: list[SimSummary] = []
+    for d in sorted(sims_dir().iterdir(), reverse=True):
+        if d.is_dir():
+            try:
+                s = _summary_from_dir(d)
+                if s is not None:
+                    out.append(s)
+            except Exception:
+                continue
+        if limit is not None and len(out) >= limit:
+            break
+    return out
+
+
+def _summary_from_backend(backend: Any, sim_id: str) -> SimSummary | None:
+    """Build a SimSummary from a StorageBackend (server tier).
+
+    Reads status.json and config.json from the backend, and reads the
+    top-level summary fields from trace.json when state == "done".
+    Returns None if the sim has no status record.
+    """
+    raw_status = backend.read_file(sim_id, "status.json")
+    if raw_status is None:
+        return None
+    try:
+        status: dict[str, Any] = json.loads(raw_status)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+    cfg: dict[str, Any] = {}
+    raw_cfg = backend.read_file(sim_id, "config.json")
+    if raw_cfg is not None:
+        try:
+            cfg = json.loads(raw_cfg)
+        except (json.JSONDecodeError, ValueError):
+            cfg = {}
+
+    trace_summary: dict[str, Any] = {}
+    if status.get("state") == "done":
+        trace = backend.read_trace(sim_id) if hasattr(backend, "read_trace") else None
+        if trace is not None:
+            try:
+                trace_summary = {
+                    "n_agents": trace.get("n_agents"),
+                    "n_questions": trace.get("n_questions"),
+                    "ciq_score": (trace.get("collective_iq") or {}).get("score"),
+                    "eig_mean": (trace.get("collective_iq") or {}).get("eig_mean"),
+                }
+            except Exception:
+                trace_summary = {}
+
+    return SimSummary(
+        sim_id=sim_id,
+        state=status.get("state", "unknown"),
+        started_at=status.get("started_at"),
+        finished_at=status.get("finished_at"),
+        n_agents=trace_summary.get("n_agents") or cfg.get("personas", 0) * cfg.get("replicas", 0),
+        n_questions=trace_summary.get("n_questions"),
+        ciq_score=trace_summary.get("ciq_score"),
+        eig_mean=trace_summary.get("eig_mean"),
+        model=cfg.get("model"),
+        enable_tools=cfg.get("enable_tools"),
+        deliberation_rounds=cfg.get("deliberation_rounds"),
+        no_llm=cfg.get("no_llm"),
+        error=status.get("error"),
+        topic=cfg.get("topic") or None,
+        questions_set=cfg.get("questions") or None,
+    )
+
+
+def list_sims_for_backend(backend: Any, *, limit: int | None = None) -> list[SimSummary]:
+    """Return SimSummary list from a StorageBackend (server tier).
+
+    Accepts any object that implements ``list_sim_ids() -> list[str]``
+    and ``read_file(sim_id, filename) -> bytes | None``.  The local
+    disk-walk path (``list_sims()``) is unaffected.
+    """
+    out: list[SimSummary] = []
+    for sim_id in backend.list_sim_ids():
+        try:
+            s = _summary_from_backend(backend, sim_id)
+            if s is not None:
+                out.append(s)
+        except Exception:
+            continue
+        if limit is not None and len(out) >= limit:
+            break
+    return out
+
+
+def append_stderr(sim_id: str, line: str) -> None:
+    p = sim_dir(sim_id) / "stderr.log"
+    with p.open("a") as f:
+        f.write(line)
+        if not line.endswith("\n"):
+            f.write("\n")