hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/topic_adapter.py

@@ -0,0 +1,338 @@
+"""Topic-adaptive configuration inference.
+
+Given only a topic string, infers the right simulation parameters:
+    n_questions, personas, replicas, deliberation_rounds, persona_mix
+
+The adapter classifies the topic into one of several *complexity profiles*
+and adjusts all parameters accordingly.  LLM mode asks the model to reason
+about the topic before returning a structured config — the same model that
+will be used for the simulation itself, so the choice is coherent.
+
+Profiles (heuristic fast-path, no LLM required):
+    QUICK       — narrow, operational, single-asset questions
+                  (stock price, product launch, binary event)
+                  → 4 questions, 3 personas × 1 replica, 1 round
+    STANDARD    — domain analysis, policy, market dynamics
+                  → 6 questions, 4 personas × 2 replicas, 2 rounds
+    DEEP        — multi-factor, geopolitical, science/technology roadmaps
+                  → 8 questions, 5 personas × 2 replicas, 3 rounds
+    STRATEGIC   — long-horizon, cross-domain, portfolio/investment decisions
+                  → 10 questions, 6 personas × 2 replicas, 3 rounds
+
+When OPENROUTER_API_KEY is present, the adapter also asks the LLM to
+suggest the profile and to propose relevant persona archetypes from the
+available roster.  The LLM answer is parsed and validated; any malformed
+response falls back to the heuristic.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Profile definitions
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TopicProfile:
+    """Inferred simulation parameters for a topic."""
+    profile_name: str
+    n_questions: int
+    personas: int
+    replicas: int
+    deliberation_rounds: int
+    rationale: str = ""
+    suggested_personas: list[str] = field(default_factory=list)
+
+
+_PROFILES: dict[str, TopicProfile] = {
+    "quick": TopicProfile(
+        profile_name="quick",
+        n_questions=4,
+        personas=3,
+        replicas=1,
+        deliberation_rounds=1,
+        rationale="Narrow, time-sensitive question — minimal swarm for speed.",
+    ),
+    "standard": TopicProfile(
+        profile_name="standard",
+        n_questions=6,
+        personas=4,
+        replicas=2,
+        deliberation_rounds=2,
+        rationale="Domain analysis — moderate panel size with one deliberation pass.",
+    ),
+    "deep": TopicProfile(
+        profile_name="deep",
+        n_questions=8,
+        personas=5,
+        replicas=2,
+        deliberation_rounds=3,
+        rationale="Multi-factor topic — larger panel with extra deliberation rounds for convergence.",
+    ),
+    "strategic": TopicProfile(
+        profile_name="strategic",
+        n_questions=10,
+        personas=6,
+        replicas=2,
+        deliberation_rounds=3,
+        rationale="Long-horizon strategic question — full swarm with deep deliberation.",
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Heuristic classifier
+# ---------------------------------------------------------------------------
+
+
+_QUICK_SIGNALS = frozenset({
+    "today", "tonight", "tomorrow", "this week", "this month",
+    "price", "stock", "earnings", "ipo", "launch", "release",
+    "win", "lose", "beat", "miss", "crash", "spike",
+    "will it", "is it", "should i",
+})
+
+_STRATEGIC_SIGNALS = frozenset({
+    "geopolit", "sovereign", "decade", "2030", "2035", "2040", "2050",
+    "long-term", "long term", "strategic", "nation", "global",
+    "civilisati", "civilization", "regime", "alliance",
+    "portfolio", "multi-asset", "sector rotation", "structural",
+})
+
+_DEEP_SIGNALS = frozenset({
+    "regul", "policy", "legislation", "infrastructure", "platform",
+    "ecosystem", "supply chain", "adopt", "transition", "compet",
+    "market structure", "industri", "technolog", "innovat",
+    "research", "science", "climate", "energy", "defence", "security",
+    "economic", "fiscal", "monetary", "trade war", "tariff",
+})
+
+
+def _heuristic_profile(topic: str) -> str:
+    t = topic.lower()
+    words = set(re.findall(r"[a-z]+", t))
+
+    # Check strategic first (long-horizon beats everything)
+    for sig in _STRATEGIC_SIGNALS:
+        if sig in t:
+            return "strategic"
+
+    # Deep: multi-factor domain analysis
+    deep_hits = sum(1 for sig in _DEEP_SIGNALS if sig in t)
+    if deep_hits >= 2:
+        return "deep"
+
+    # Quick: operational, time-sensitive, personal
+    quick_hits = sum(1 for sig in _QUICK_SIGNALS if sig in words or sig in t)
+    if quick_hits >= 2:
+        return "quick"
+
+    # Length heuristic: longer, richer topics warrant deeper analysis
+    word_count = len(topic.split())
+    if word_count <= 6:
+        return "quick"
+    elif word_count <= 12:
+        return "standard"
+    else:
+        return "deep"
+
+
+# ---------------------------------------------------------------------------
+# LLM classifier (async, non-blocking)
+# ---------------------------------------------------------------------------
+
+
+_SYSTEM_PROMPT = """\
+You are a research-design expert. Given a topic for a multi-agent forecasting simulation,
+output ONLY a JSON object with these fields:
+
+{
+  "profile": "quick" | "standard" | "deep" | "strategic",
+  "rationale": "one sentence explaining the choice",
+  "suggested_personas": ["slug1", "slug2", "slug3"]
+}
+
+Profile guide:
+  quick     — narrow, time-sensitive, single-asset (≤4 questions make sense)
+  standard  — domain analysis, market dynamics, policy (6 questions)
+  deep      — multi-factor, technology roadmaps, sector analysis (8 questions)
+  strategic — long-horizon, geopolitical, cross-domain portfolio (10 questions)
+
+For suggested_personas, pick 3–5 slugs from this roster that best cover the topic:
+analyst, economist, technologist, risk-manager, geopolitical-analyst,
+lawyer, scientist, ethicist, entrepreneur, investor, sceptic,
+policy-expert, security-analyst, healthcare-expert, energy-expert
+
+Output ONLY valid JSON. No markdown, no preamble.
+"""
+
+
+async def _llm_profile(topic: str, model: str, api_key: str) -> dict[str, Any] | None:
+    try:
+        import httpx
+
+        async with httpx.AsyncClient(timeout=12.0) as client:
+            resp = await client.post(
+                "https://openrouter.ai/api/v1/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                    "HTTP-Referer": "https://hypermind.ai",
+                },
+                json={
+                    "model": model,
+                    "messages": [
+                        {"role": "system", "content": _SYSTEM_PROMPT},
+                        {"role": "user", "content": f"Topic: {topic}"},
+                    ],
+                    "temperature": 0.2,
+                    "max_tokens": 200,
+                },
+            )
+            resp.raise_for_status()
+            content = resp.json()["choices"][0]["message"]["content"].strip()
+            # Strip markdown fences if present
+            content = re.sub(r"^```json?\s*", "", content)
+            content = re.sub(r"\s*```$", "", content)
+            parsed = json.loads(content)
+            if parsed.get("profile") in _PROFILES:
+                return parsed
+    except Exception:
+        pass
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def _profile_cache_path(topic: str, model: str) -> Path:
+    key = hashlib.sha256(f"{topic}|{model}".encode()).hexdigest()[:16]
+    cache_dir = Path.home() / ".hypermind" / "profile_cache"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir / f"{key}.json"
+
+
+def _load_cached_profile(topic: str, model: str) -> TopicProfile | None:
+    path = _profile_cache_path(topic, model)
+    if path.exists():
+        try:
+            d = json.loads(path.read_text())
+            return TopicProfile(**d)
+        except Exception:
+            pass
+    return None
+
+
+def _save_cached_profile(topic: str, model: str, profile: TopicProfile) -> None:
+    try:
+        d = {
+            "profile_name": profile.profile_name,
+            "n_questions": profile.n_questions,
+            "personas": profile.personas,
+            "replicas": profile.replicas,
+            "deliberation_rounds": profile.deliberation_rounds,
+            "rationale": profile.rationale,
+            "suggested_personas": profile.suggested_personas,
+        }
+        _profile_cache_path(topic, model).write_text(json.dumps(d, indent=2))
+    except Exception:
+        pass
+
+
+async def infer_topic_profile(
+    topic: str,
+    *,
+    model: str | None = None,
+    no_llm: bool = False,
+) -> TopicProfile:
+    """Return a TopicProfile inferred from *topic*.
+
+    Fast-path: heuristic classifier (no LLM, no network).
+    If OPENROUTER_API_KEY and model are available, asks the LLM to refine
+    the profile and suggest personas.  Falls back to heuristic on any error.
+    """
+    topic = (topic or "").strip()
+    if not topic:
+        return _PROFILES["standard"]
+
+    heuristic_key = _heuristic_profile(topic)
+    heuristic = _PROFILES[heuristic_key]
+
+    api_key = os.environ.get("OPENROUTER_API_KEY", "").strip()
+    if no_llm or not api_key or not model:
+        return heuristic
+
+    # Cache hit — same topic+model already classified
+    cached = _load_cached_profile(topic, model)
+    if cached is not None:
+        return cached
+
+    llm_result = await _llm_profile(topic, model, api_key)
+    if llm_result is None:
+        return heuristic
+
+    profile_key = llm_result.get("profile", heuristic_key)
+    base = _PROFILES.get(profile_key, heuristic)
+
+    result = TopicProfile(
+        profile_name=base.profile_name,
+        n_questions=base.n_questions,
+        personas=base.personas,
+        replicas=base.replicas,
+        deliberation_rounds=base.deliberation_rounds,
+        rationale=llm_result.get("rationale", base.rationale),
+        suggested_personas=llm_result.get("suggested_personas", []),
+    )
+    _save_cached_profile(topic, model, result)
+    return result
+
+
+def apply_profile_to_config(config_dict: dict[str, Any], profile: TopicProfile) -> dict[str, Any]:
+    """Apply an inferred profile to a raw config dict.
+
+    Only overwrites fields that were left at their sentinel defaults
+    (i.e. the caller didn't explicitly supply them).
+    """
+    out = dict(config_dict)
+    sentinel = _SENTINELS
+
+    if out.get("n_questions") in (None, sentinel["n_questions"]):
+        out["n_questions"] = profile.n_questions
+    if out.get("personas") in (None, sentinel["personas"]):
+        out["personas"] = profile.personas
+    if out.get("replicas") in (None, sentinel["replicas"]):
+        out["replicas"] = profile.replicas
+    if out.get("deliberation_rounds") in (None, sentinel["deliberation_rounds"]):
+        out["deliberation_rounds"] = profile.deliberation_rounds
+
+    # Inject suggested persona override if provided and caller didn't already set one
+    if profile.suggested_personas and not out.get("personas_override") and not out.get("swarm"):
+        from .personas import get_persona
+        valid = [s for s in profile.suggested_personas if get_persona(s) is not None]
+        if len(valid) >= 2:
+            out["personas_override"] = valid
+
+    out["_profile"] = profile.profile_name
+    out["_profile_rationale"] = profile.rationale
+    return out
+
+
+# Sentinel values — these are the SimConfig dataclass defaults.
+# Any field still at its default is considered "not explicitly set by caller".
+_SENTINELS: dict[str, Any] = {
+    "n_questions": 8,
+    "personas": 6,
+    "replicas": 5,
+    "deliberation_rounds": 2,
+}

hypermind/simlab/topic_questions.py

@@ -0,0 +1,259 @@
+"""Topic-driven question generation.
+
+Given a free-text topic ("Microsoft Azure outlook 2026") and a count,
+emit a list of binary-forecast questions in the same shape as the
+bundled question_sets/*.json files:
+
+    {"id": "...", "query": "Will ...?", "ground_truth": 0.5, "category": "..."}
+
+Modes
+-----
+- LLM mode (preferred): asks the configured model to draft N specific,
+  binary, falsifiable questions on the topic. Ground truth is set to
+  0.5 for each (we don't know the answer; the panel forecasts and the
+  oracle resolves later from peer consensus).
+- Synthetic mode: deterministic template generator. Used when
+  ``no_llm=True`` or when the LLM call fails. Slugs the topic and emits
+  N questions across a fixed set of forecast frames (growth, risk,
+  adoption, competition, regulation, sentiment).
+
+The output is the **same dict shape** the existing scenario already
+consumes via ``_load_questions``, so the persona panel doesn't need any
+changes to handle generated questions.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+SYNTHETIC_FRAMES = [
+    ("growth", "Will {topic} see meaningful growth over the next 12 months?"),
+    ("risk", "Is there a major risk that {topic} fails or stalls in the next 12 months?"),
+    ("adoption", "Will adoption of {topic} significantly increase in the next year?"),
+    ("competition", "Will {topic} retain its competitive position over the next year?"),
+    ("regulation", "Will regulators take meaningful action on {topic} in the next 18 months?"),
+    ("sentiment", "Will public/market sentiment toward {topic} improve in the next 6 months?"),
+    ("cost", "Will the cost (financial or operational) of {topic} change materially this year?"),
+    ("technology", "Will the underlying technology behind {topic} see a major shift in 12 months?"),
+    ("opportunity", "Does {topic} represent a compelling opportunity vs alternatives?"),
+    ("longterm", "Will {topic} still be relevant 3 years from now?"),
+]
+
+
+@dataclass
+class GeneratedQuestion:
+    id: str
+    query: str
+    ground_truth: float
+    category: str
+
+
+def _slug(s: str) -> str:
+    out = re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-")
+    return out[:48] or "topic"
+
+
+def _normalize_topic_for_template(topic: str) -> str:
+    """Strip leading 'Will/Does/Is/Can' and trailing '?' so the topic
+    plugs into our forecast frames as a noun phrase, not a sentence.
+    """
+    t = topic.strip().rstrip("?").strip()
+    for prefix in ("Will ", "Does ", "Is ", "Can ", "Should ", "Are ", "Has "):
+        if t.lower().startswith(prefix.lower()):
+            t = t[len(prefix) :].strip()
+            break
+    # Lowercase the first letter unless it's a proper noun (heuristic: keep if
+    # next chars are also upper, e.g. "AI", "EU", or it's a single word).
+    if t and t[0].isupper() and len(t) > 1 and not t[1].isupper():
+        t = t[0].lower() + t[1:]
+    return t
+
+
+def _synthetic_questions(topic: str, n: int) -> list[dict]:
+    """Deterministic fallback.
+
+    If the topic itself ends with '?', use it as Q1 verbatim and generate
+    n−1 derived sub-questions framed around the cleaned subject. Otherwise
+    cycle through frames with the topic as a noun phrase.
+    """
+    slug = _slug(topic)
+    is_direct_question = topic.strip().endswith("?")
+    subject = _normalize_topic_for_template(topic)
+
+    out: list[dict] = []
+    if is_direct_question:
+        out.append(
+            {
+                "id": f"{slug}-001",
+                "query": topic.strip(),
+                "ground_truth": 0.5,
+                "category": "primary",
+            }
+        )
+        offset = 1
+    else:
+        offset = 0
+
+    for i in range(offset, n):
+        frame_id, template = SYNTHETIC_FRAMES[(i - offset) % len(SYNTHETIC_FRAMES)]
+        out.append(
+            {
+                "id": f"{slug}-{i + 1:03d}",
+                "query": template.format(topic=subject),
+                "ground_truth": 0.5,
+                "category": frame_id,
+            }
+        )
+    return out
+
+
+_SYSTEM_PROMPT = (
+    "You are a forecasting analyst. Given a TOPIC, draft exactly N binary "
+    "(yes/no) forecast questions about it. Each question must be:\n"
+    "  - specific (named entity or measurable claim)\n"
+    "  - falsifiable within 6–24 months\n"
+    "  - answerable as a probability (0..1)\n"
+    "  - non-redundant with the others\n"
+    "Cover diverse angles: growth, risk, adoption, competition, regulation, "
+    "sentiment, technology, cost, geopolitics. Reply ONLY with a JSON array "
+    "of N objects, each: "
+    '{"query": "Will ...?", "category": "<one-word>"}. No prose, no markdown.'
+)
+
+
+async def _llm_questions(
+    topic: str, n: int, *, model: str, api_key: str, timeout_s: float = 30.0
+) -> list[dict]:
+    """Ask OpenRouter to draft N forecast questions.
+
+    Async — uses httpx.AsyncClient so the event loop stays responsive
+    while we wait on OpenRouter. Raises on any failure; the caller
+    should fall back to synthetic.
+    """
+    user = f"TOPIC: {topic}\nN: {n}"
+    body = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": _SYSTEM_PROMPT},
+            {"role": "user", "content": user},
+        ],
+        "temperature": 0.4,
+        "response_format": {"type": "json_object"},
+    }
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "HTTP-Referer": "https://github.com/ZySec-AI/hypermind",
+        "X-Title": "HyperMind SimLab",
+        "Content-Type": "application/json",
+    }
+    async with httpx.AsyncClient(timeout=timeout_s) as client:
+        r = await client.post(
+            "https://openrouter.ai/api/v1/chat/completions",
+            json=body,
+            headers=headers,
+        )
+    r.raise_for_status()
+    payload = r.json()
+    text = payload["choices"][0]["message"]["content"]
+    parsed = json.loads(text)
+    # Some models wrap a top-level key; try common shapes.
+    if isinstance(parsed, dict):
+        for key in ("questions", "items", "data"):
+            if key in parsed and isinstance(parsed[key], list):
+                parsed = parsed[key]
+                break
+    if not isinstance(parsed, list):
+        raise ValueError(f"LLM returned non-list shape: {type(parsed).__name__}")
+    slug = _slug(topic)
+    out: list[dict] = []
+    for i, item in enumerate(parsed[:n]):
+        if not isinstance(item, dict) or "query" not in item:
+            continue
+        out.append(
+            {
+                "id": f"{slug}-{i + 1:03d}",
+                "query": str(item["query"]).strip(),
+                "ground_truth": 0.5,
+                "category": str(item.get("category", "general")).lower(),
+            }
+        )
+    if not out:
+        raise ValueError("LLM returned no usable questions")
+    # Top up with synthetic if the model returned fewer than asked
+    if len(out) < n:
+        out.extend(_synthetic_questions(topic, n - len(out)))
+    return out
+
+
+def _question_cache_path(topic: str, n: int, model: str) -> Path:
+    key = hashlib.sha256(f"{topic}|{n}|{model}".encode()).hexdigest()[:16]
+    cache_dir = Path.home() / ".hypermind" / "question_cache"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir / f"{key}.json"
+
+
+def _load_cached_questions(topic: str, n: int, model: str) -> list[dict] | None:
+    path = _question_cache_path(topic, n, model)
+    if path.exists():
+        try:
+            return json.loads(path.read_text())
+        except Exception:
+            pass
+    return None
+
+
+def _save_cached_questions(topic: str, n: int, model: str, questions: list[dict]) -> None:
+    try:
+        _question_cache_path(topic, n, model).write_text(json.dumps(questions, indent=2))
+    except Exception:
+        pass
+
+
+async def generate_questions_for_topic(
+    topic: str,
+    n: int,
+    *,
+    model: str | None = None,
+    no_llm: bool = False,
+) -> list[dict]:
+    """Public entry point.
+
+    Async because the LLM path uses httpx.AsyncClient so the event
+    loop stays responsive (otherwise the worker blocks all HTTP traffic
+    in the SimLab API for the duration of the OpenRouter call).
+
+    Returns a list of question dicts with the same shape as the bundled
+    question_sets JSON files. Falls back to synthetic on any LLM error.
+
+    Results are cached on disk keyed by (topic, n, model) so repeated
+    runs on the same topic skip the LLM question-gen round-trip entirely.
+    """
+    n = max(1, min(50, int(n)))
+    topic = (topic or "").strip()
+    if not topic:
+        raise ValueError("topic is required")
+    api_key = os.environ.get("OPENROUTER_API_KEY", "").strip()
+    if no_llm or not api_key or not model:
+        return _synthetic_questions(topic, n)
+
+    # Cache hit — same topic+n+model already generated
+    cached = _load_cached_questions(topic, n, model)
+    if cached is not None:
+        return cached
+
+    try:
+        questions = await _llm_questions(topic, n, model=model, api_key=api_key)
+        _save_cached_questions(topic, n, model, questions)
+        return questions
+    except Exception:
+        return _synthetic_questions(topic, n)
+
+
+__all__ = ["GeneratedQuestion", "generate_questions_for_topic"]

hypermind/storage/__init__.py

@@ -0,0 +1,69 @@
+"""Persistence layer for HyperMind worlds.
+
+A ``StorageBackend`` is an opt-in companion to ``_NamespaceWorld`` that
+durably records every sealed claim, dispute, reputation snapshot, and
+Merkle leaf. The default sandbox/testbed factories run with no backend
+(in-memory only). Production agents wire one of:
+
+  * :class:`SqliteBackend` — single-file SQLite, zero extra deps.
+
+The backend is a Protocol — operators can substitute Postgres, S3+RDS,
+or a cloud KV without touching the SDK core.
+
+Lifecycle:
+
+  1. ``backend.open()`` — connect / create schema if missing.
+  2. ``backend.append_claim(stmt)`` — called from ``publish_claim``.
+  3. ``backend.append_dispute(disp)`` — called from ``dispute``.
+  4. ``backend.snapshot_reputation(rep)`` — periodic checkpoint.
+  5. ``backend.close()`` — flush + disconnect.
+
+Crash recovery:
+
+  - On ``open()``, the backend re-loads sealed claims, disputes,
+    reputation posteriors, and Merkle leaves into the world.
+  - The Merkle tree is rebuilt by replaying leaves in append order
+    (RFC 6962 deterministic re-derivation).
+
+This first iteration covers single-process durability. Multi-writer /
+HA setups belong on a Postgres backend in v0.6+.
+"""
+
+from __future__ import annotations
+
+import os
+
+from hypermind.storage.backend import StorageBackend
+from hypermind.storage.relata import RelataBackend
+from hypermind.storage.sqlite import SqliteBackend
+
+
+def storage_from_env(*, namespace_id: str = "default") -> StorageBackend | None:
+    """Resolve the production storage backend from the environment.
+
+    RelataDB is the default *the moment it is configured*; SQLite and in-memory
+    stay one env var away. ``sandbox()`` / ``testbed()`` ignore this and remain
+    in-memory (zero-dep, no server) — only ``open(mode="production")`` calls it.
+
+    Precedence:
+
+    - ``HYPERMIND_STORAGE=relata`` (or any ``RELATA_URL`` set) → :class:`RelataBackend`
+    - ``HYPERMIND_STORAGE=sqlite:/path/to.db``                → :class:`SqliteBackend`
+    - unset                                                   → ``None`` (in-memory)
+    """
+    kind = os.getenv("HYPERMIND_STORAGE") or ("relata" if os.getenv("RELATA_URL") else "")
+    if kind == "relata":
+        url = os.getenv("RELATA_URL")
+        if not url:
+            raise RuntimeError("HYPERMIND_STORAGE=relata requires RELATA_URL to be set")
+        return RelataBackend(
+            url,
+            namespace_id=os.getenv("HYPERMIND_NAMESPACE", namespace_id),
+            bearer_token=os.getenv("RELATA_TOKEN"),
+        )
+    if kind.startswith("sqlite:"):
+        return SqliteBackend(kind[len("sqlite:") :])
+    return None
+
+
+__all__ = ["RelataBackend", "SqliteBackend", "StorageBackend", "storage_from_env"]