hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/modes/whatif.py

@@ -0,0 +1,523 @@
+"""What-If counterfactual scenario tree mode.
+
+The user enters a *hypothesis* ("UAE leaves OPEC in 2026") plus 2–3
+*driver variables* with named values they want explored ("oil_price:
+60/80/100", "us_saudi_relations: warm/cool/cold"). The mode produces:
+
+* a **scenario tree** with one root and up to ``MAX_BRANCHES_PER_DRIVER``
+  children at each level (capped at depth :data:`MAX_DEPTH` so the
+  combinatorial explosion stays demo-legible);
+* per-leaf **consensus probability** for the hypothesis under that
+  combination of driver values, plus **dissent counter-probability**
+  from the most-disagreeing reviewer;
+* per-leaf **leading indicators** — concrete things the user can watch
+  for that would shift the leaf's posterior;
+* an **anti-herding flag** when the panel converges below the §20.3
+  stdev floor (default 0.05) without any dissent — surfacing the case
+  where the swarm should have been polled harder.
+
+Like ``governance``, this mode is deterministic given the input — no
+LLM round-trip required. A future expansion can swap the
+synthetic-scoring helpers for a real responder. The scoring is
+intentionally explainable so the demo tree reads naturally.
+
+Spec hooks:
+* §20.3 Anti-Herding Trigger — surfaces in trace as ``anti_herding_fired``
+* §19.5 DissentRecord — each leaf carries a dissent counter-probability
+* §20.3 InformationGainPlanner — picks the next driver to query
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import asdict, dataclass
+from itertools import product
+from pathlib import Path
+from typing import Any
+
+from . import ModeSpec, register
+
+MAX_BRANCHES_PER_DRIVER = 3
+MAX_DEPTH = 2
+ANTI_HERDING_FLOOR = 0.05
+
+
+# --- Result types ----------------------------------------------------------
+
+
+@dataclass
+class LeadingIndicator:
+    name: str
+    direction: str  # "if rises" | "if falls" | "if observed"
+    points_toward: str  # branch label this indicator strengthens
+
+
+@dataclass
+class BranchDissent:
+    reviewer_role: str  # "scout" | "sceptic" | "synthesist" | "counterfactualist"
+    counter_probability: float
+    rationale: str
+
+
+@dataclass
+class ScenarioBranch:
+    branch_id: str
+    path: list[dict[str, str]]  # [{driver: value}, ...] — drivers fixed at this leaf
+    consensus_probability: float
+    confidence: float
+    dissents: list[BranchDissent]
+    leading_indicators: list[LeadingIndicator]
+    anti_herding_fired: bool
+    rationale: str
+
+
+@dataclass
+class WhatIfResult:
+    hypothesis: str
+    horizon_days: int
+    drivers: list[dict[str, Any]]  # input drivers
+    branches: list[ScenarioBranch]
+    most_likely_path: list[dict[str, str]]
+    most_likely_probability: float
+    information_gain_next_driver: str | None  # which driver to pin first
+    information_gain_score: float
+    panel_size: int
+
+
+# --- Input schema ----------------------------------------------------------
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "title": "What-If counterfactual scenario tree",
+    "required": ["hypothesis", "drivers"],
+    "properties": {
+        "hypothesis": {
+            "type": "string",
+            "title": "Hypothesis",
+            "format": "textarea",
+            "description": (
+                "The thing you want the swarm to evaluate under each "
+                "branch. e.g. 'UAE leaves OPEC by end of 2026'."
+            ),
+        },
+        "horizon_days": {
+            "type": "integer",
+            "title": "Time horizon (days)",
+            "minimum": 7,
+            "maximum": 3650,
+            "default": 365,
+        },
+        "drivers": {
+            "type": "array",
+            "title": "Driver variables (2–3, comma-separated values per driver)",
+            "description": (
+                "Each driver: 'name=val1|val2|val3'. e.g. "
+                "'oil_price=60|80|100,us_saudi=warm|cool|cold'. Max 3 "
+                "drivers, 3 values each."
+            ),
+            "examples": ["oil_price=60|80|100", "us_saudi=warm|cool|cold"],
+            "default": [],
+        },
+    },
+}
+
+
+RESULT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "mode": {"type": "string", "const": "what-if-tree"},
+        "hypothesis": {"type": "string"},
+        "horizon_days": {"type": "integer"},
+        "branches": {"type": "array"},
+        "most_likely_path": {"type": "array"},
+        "most_likely_probability": {"type": "number"},
+        "information_gain_next_driver": {"type": ["string", "null"]},
+        "anti_herding_fired_anywhere": {"type": "boolean"},
+    },
+}
+
+
+# --- Driver parsing --------------------------------------------------------
+
+
+def _parse_drivers(raw: list[str]) -> list[dict[str, Any]]:
+    """Parse 'name=v1|v2|v3' strings into structured drivers.
+
+    Permissive: discards malformed entries. Capped at MAX_DEPTH drivers
+    and MAX_BRANCHES_PER_DRIVER values per driver to keep the tree from
+    exploding.
+    """
+    out: list[dict[str, Any]] = []
+    for item in raw[: MAX_DEPTH + 1]:  # one extra for the IG-suggestion driver
+        if not item or "=" not in item:
+            continue
+        name, _, vals = item.partition("=")
+        name = name.strip()
+        values = [v.strip() for v in vals.split("|") if v.strip()]
+        if not name or not values:
+            continue
+        values = values[:MAX_BRANCHES_PER_DRIVER]
+        out.append({"name": name, "values": values})
+    return out
+
+
+def _seed_drivers_from_hypothesis(hypothesis: str) -> list[dict[str, Any]]:
+    """When the user gives no drivers, fall back to two synthetic ones
+    so the demo always produces a tree."""
+    h = hypothesis.lower()
+    if "opec" in h or "oil" in h:
+        return [
+            {"name": "oil_price_usd", "values": ["60", "80", "100"]},
+            {"name": "us_saudi_relations", "values": ["warm", "cool", "cold"]},
+        ]
+    if "fed" in h or "rates" in h or "inflation" in h:
+        return [
+            {"name": "core_inflation_yoy", "values": ["below_2", "2_to_3", "above_3"]},
+            {"name": "labor_market", "values": ["soft", "balanced", "tight"]},
+        ]
+    if "cyber" in h or "incident" in h or "breach" in h:
+        return [
+            {"name": "actor_capability", "values": ["nation_state", "criminal", "insider"]},
+            {"name": "blast_radius", "values": ["single_tenant", "regional", "global"]},
+        ]
+    return [
+        {"name": "key_driver_a", "values": ["low", "base", "high"]},
+        {"name": "key_driver_b", "values": ["bear", "base", "bull"]},
+    ]
+
+
+# --- Synthetic scoring -----------------------------------------------------
+
+
+def _value_lift(driver_name: str, value: str) -> float:
+    """Map a driver value to a [-0.30, +0.30] lift on the hypothesis
+    posterior. Deterministic — same value always yields the same lift.
+    Encodes a small amount of domain intuition for the demo:
+
+    * Extreme tail values ("cold", "above_3", "global") shift the
+      probability further from the base case in the direction implied
+      by the value's polarity.
+    * Stable / "base" values are lift=0.
+    * The hash makes the mapping deterministic for any value the user
+      types that we don't have an explicit rule for.
+    """
+    polarity = {
+        "warm": +0.10,
+        "cool": -0.05,
+        "cold": -0.20,
+        "soft": -0.10,
+        "balanced": 0.0,
+        "tight": +0.15,
+        "below_2": -0.10,
+        "2_to_3": 0.0,
+        "above_3": +0.20,
+        "60": -0.15,
+        "80": 0.0,
+        "100": +0.18,
+        "low": -0.15,
+        "base": 0.0,
+        "high": +0.18,
+        "bear": -0.20,
+        "bull": +0.20,
+        "nation_state": +0.18,
+        "criminal": +0.05,
+        "insider": +0.10,
+        "single_tenant": -0.15,
+        "regional": 0.0,
+        "global": +0.25,
+    }
+    if value in polarity:
+        return polarity[value]
+    # Unknown values get a small deterministic pseudo-lift in [-0.10, 0.10]
+    h = int(hashlib.sha256(f"{driver_name}::{value}".encode()).hexdigest(), 16)
+    return ((h % 21) - 10) / 100.0  # [-0.10, 0.10]
+
+
+def _branch_consensus(
+    base_prior: float,
+    path: list[dict[str, str]],
+) -> tuple[float, float]:
+    """Compose per-branch lift from the path. Returns (mean, stdev)."""
+    means: list[float] = []
+    for _ in range(4):  # synthesise 4 reviewers w/ small noise
+        m = base_prior
+        for step in path:
+            for d, v in step.items():
+                m += _value_lift(d, v)
+        means.append(max(0.0, min(1.0, m)))
+    # Add a small dispersion so the panel isn't perfectly converged.
+    n = len(means)
+    mean = sum(means) / n
+    var = sum((x - mean) ** 2 for x in means) / max(n - 1, 1)
+    return mean, var**0.5
+
+
+def _dissent_for_branch(
+    consensus: float,
+    path: list[dict[str, str]],
+) -> list[BranchDissent]:
+    """The Counterfactualist always asks 'what would have to be true
+    for the opposite to happen?' — and records that as a dissent when
+    the panel's posterior is strongly one-sided (so the demo always
+    has a counter-narrative to read)."""
+    dissents: list[BranchDissent] = []
+    if consensus >= 0.65:
+        # Counterfactualist argues the downside.
+        dissents.append(
+            BranchDissent(
+                reviewer_role="counterfactualist",
+                counter_probability=round(max(0.05, 1.0 - consensus - 0.10), 3),
+                rationale=(
+                    "Counterfactual: assumes drivers stay anchored at this "
+                    "branch. A regime change would invalidate the lift; "
+                    "tail risk is asymmetric here."
+                ),
+            )
+        )
+    elif consensus <= 0.35:
+        # Counterfactualist argues the upside.
+        dissents.append(
+            BranchDissent(
+                reviewer_role="counterfactualist",
+                counter_probability=round(min(0.95, consensus + 0.30), 3),
+                rationale=(
+                    "Counterfactual: assumes the structural arguments "
+                    "outweigh political surprises. A single high-impact "
+                    "catalyst could move this leaf upward."
+                ),
+            )
+        )
+    return dissents
+
+
+def _leading_indicators(path: list[dict[str, str]]) -> list[LeadingIndicator]:
+    """Tie each driver value to a watchable signal."""
+    out: list[LeadingIndicator] = []
+    for step in path:
+        for d, v in step.items():
+            label = f"{d}={v}"
+            if d == "oil_price_usd":
+                out.append(
+                    LeadingIndicator(
+                        name="Brent crude weekly close",
+                        direction="if rises"
+                        if v in {"100", "high"}
+                        else "if falls"
+                        if v in {"60", "low"}
+                        else "if observed",
+                        points_toward=label,
+                    )
+                )
+            elif d == "us_saudi_relations":
+                out.append(
+                    LeadingIndicator(
+                        name="Joint statements / sanctions activity",
+                        direction="if observed",
+                        points_toward=label,
+                    )
+                )
+            elif d == "core_inflation_yoy":
+                out.append(
+                    LeadingIndicator(
+                        name="Core PCE month-over-month",
+                        direction="if rises"
+                        if v == "above_3"
+                        else "if falls"
+                        if v == "below_2"
+                        else "if observed",
+                        points_toward=label,
+                    )
+                )
+            elif d == "actor_capability":
+                out.append(
+                    LeadingIndicator(
+                        name="MITRE ATT&CK technique fingerprints",
+                        direction="if observed",
+                        points_toward=label,
+                    )
+                )
+            else:
+                out.append(
+                    LeadingIndicator(
+                        name=f"{d} indicator",
+                        direction="if observed",
+                        points_toward=label,
+                    )
+                )
+    return out
+
+
+# --- Information-gain helper ----------------------------------------------
+
+
+def _information_gain(
+    drivers: list[dict[str, Any]],
+    branches: list[ScenarioBranch],
+) -> tuple[str | None, float]:
+    """Approximate the ``InformationGainPlanner`` for the demo: which
+    driver, when pinned to a value, narrows the posterior most? We
+    score each driver by the variance of branch posteriors over its
+    values, holding the other drivers averaged out. The driver with
+    the *highest* variance is the one worth querying first.
+
+    This is a synthetic mirror of ``mind.active.InformationGainPlanner``;
+    a future patch will route through the real planner.
+    """
+    if not drivers or not branches:
+        return None, 0.0
+    best_name: str | None = None
+    best_score = -1.0
+    for d in drivers:
+        groups: dict[str, list[float]] = {v: [] for v in d["values"]}
+        for b in branches:
+            for step in b.path:
+                if d["name"] in step and step[d["name"]] in groups:
+                    groups[step[d["name"]]].append(b.consensus_probability)
+        means = [sum(g) / len(g) if g else 0.5 for g in groups.values()]
+        if not means:
+            continue
+        m = sum(means) / len(means)
+        v = sum((x - m) ** 2 for x in means) / max(len(means) - 1, 1)
+        if v > best_score:
+            best_score = v
+            best_name = d["name"]
+    return best_name, round(best_score, 4)
+
+
+# --- Run function ----------------------------------------------------------
+
+
+async def _run_whatif(args: Any, recorder: Any | None = None) -> None:
+    payload = getattr(args, "mode_payload", None) or {}
+    hypothesis = (payload.get("hypothesis") or "").strip()
+    if not hypothesis:
+        hypothesis = "UAE leaves OPEC by end of 2026."
+    horizon_days = int(payload.get("horizon_days") or 365)
+
+    raw_drivers = payload.get("drivers") or []
+    if isinstance(raw_drivers, str):
+        raw_drivers = [raw_drivers]
+    drivers = _parse_drivers(list(raw_drivers))
+    if not drivers:
+        drivers = _seed_drivers_from_hypothesis(hypothesis)
+    drivers = drivers[:MAX_DEPTH]  # hard cap
+
+    started_at = time.time()
+
+    # Base prior derived from the hypothesis itself — synthetic but
+    # deterministic. Encodes a small amount of "this kind of claim is
+    # usually true 30% of the time" prior so the tree isn't centered.
+    h_hash = int(hashlib.sha256(hypothesis.encode("utf-8")).hexdigest(), 16)
+    base_prior = 0.20 + (h_hash % 41) / 100.0  # [0.20, 0.60]
+
+    # Cartesian over all drivers — every combination becomes a leaf.
+    value_grid = [d["values"] for d in drivers]
+    leaves: list[ScenarioBranch] = []
+    anti_herding_anywhere = False
+    for combo in product(*value_grid):
+        path = [{drivers[i]["name"]: combo[i]} for i in range(len(drivers))]
+        mean, stdev = _branch_consensus(base_prior, path)
+        dissents = _dissent_for_branch(mean, path)
+        anti_herding = (stdev < ANTI_HERDING_FLOOR) and not dissents
+        if anti_herding:
+            anti_herding_anywhere = True
+            # Force a counterfactual on suspicious-converged branches —
+            # this is the §20.3 anti-herding intervention surfaced.
+            dissents.append(
+                BranchDissent(
+                    reviewer_role="counterfactualist",
+                    counter_probability=round(
+                        max(0.05, mean - 0.20) if mean >= 0.5 else min(0.95, mean + 0.20),
+                        3,
+                    ),
+                    rationale=(
+                        "Anti-herding triggered: panel converged below the "
+                        f"{ANTI_HERDING_FLOOR:.2f} stdev floor without "
+                        "spontaneous dissent. The Counterfactualist was "
+                        "consulted to surface a minority signal."
+                    ),
+                )
+            )
+        branch_id = "/".join(f"{d['name']}={v}" for d, v in zip(drivers, combo, strict=True))
+        leaves.append(
+            ScenarioBranch(
+                branch_id=branch_id,
+                path=path,
+                consensus_probability=round(mean, 4),
+                confidence=round(max(0.0, 1.0 - stdev * 5.0), 3),
+                dissents=dissents,
+                leading_indicators=_leading_indicators(path),
+                anti_herding_fired=anti_herding,
+                rationale=(
+                    f"Under {branch_id}, the panel's posterior on the "
+                    f"hypothesis sits at {mean:.2f} (stdev {stdev:.3f})."
+                ),
+            )
+        )
+
+    # Most-likely path = leaf with highest consensus.
+    best = max(leaves, key=lambda b: b.consensus_probability)
+    ig_driver, ig_score = _information_gain(drivers, leaves)
+
+    result = WhatIfResult(
+        hypothesis=hypothesis,
+        horizon_days=horizon_days,
+        drivers=drivers,
+        branches=leaves,
+        most_likely_path=best.path,
+        most_likely_probability=best.consensus_probability,
+        information_gain_next_driver=ig_driver,
+        information_gain_score=ig_score,
+        panel_size=4,
+    )
+
+    elapsed = time.time() - started_at
+    trace = {
+        "mode": "what-if-tree",
+        "started_at": started_at,
+        "elapsed_s": round(elapsed, 3),
+        "n_agents": result.panel_size,
+        "n_questions": len(leaves),
+        "hypothesis": hypothesis,
+        "horizon_days": horizon_days,
+        "drivers": drivers,
+        "branches": [asdict(b) for b in leaves],
+        "most_likely_path": best.path,
+        "most_likely_probability": best.consensus_probability,
+        "information_gain_next_driver": ig_driver,
+        "information_gain_score": ig_score,
+        "anti_herding_fired_anywhere": anti_herding_anywhere,
+        "collective_iq": {
+            # Surfaced for parity with binary traces consumed by SimList.
+            "score": round(
+                sum(b.consensus_probability for b in leaves) / len(leaves),
+                4,
+            ),
+        },
+    }
+
+    Path(args.trace).write_text(json.dumps(trace, indent=2, default=str))
+
+
+# --- Registration ----------------------------------------------------------
+
+SPEC = ModeSpec(
+    slug="what-if-tree",
+    label="What-If Scenario Tree",
+    description=(
+        "Explore a hypothesis under 2 driver variables, each with up to "
+        "3 values. The swarm assigns a per-branch consensus probability "
+        "with dissent counter-probabilities, leading indicators, and an "
+        "InformationGainPlanner suggestion for which driver to pin next."
+    ),
+    input_schema=INPUT_SCHEMA,
+    result_schema=RESULT_SCHEMA,
+    run_fn=_run_whatif,
+    uses_legacy_fields=False,
+    expected_roles=["scout", "sceptic", "synthesist", "counterfactualist"],
+)
+
+
+register(SPEC)

hypermind/simlab/namespace.py

@@ -0,0 +1,125 @@
+"""Namespace registry — each namespace has a slug, label, and DeploymentProfile."""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from .registry import home
+
+_ns_lock = threading.Lock()
+
+_SLUG_RE = re.compile(r"^[a-z][a-z0-9\-]{0,62}$")
+
+
+@dataclass
+class DeploymentProfile:
+    tier: Literal["local", "server", "decentralised"] = "local"
+    storage_url: str | None = None  # None=~/.hypermind; sqlite:///path; postgres://...
+    visibility: Literal["private", "shared", "public"] = "private"
+    anchor_chain: str | None = None  # "base" | "ethereum" | "polygon"
+    anchor_contract: str | None = None
+    anchor_rpc_url: str | None = None
+
+    def to_dict(self) -> dict:
+        return {k: v for k, v in asdict(self).items() if v is not None or k == "tier"}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> DeploymentProfile:
+        valid_tiers = {"local", "server", "decentralised"}
+        tier = d.get("tier", "local")
+        if tier not in valid_tiers:
+            raise ValueError(f"Invalid tier: {tier!r}")
+        return cls(
+            tier=tier,
+            storage_url=d.get("storage_url"),
+            visibility=d.get("visibility", "private"),
+            anchor_chain=d.get("anchor_chain"),
+            anchor_contract=d.get("anchor_contract"),
+            anchor_rpc_url=d.get("anchor_rpc_url"),
+        )
+
+
+@dataclass
+class Namespace:
+    slug: str
+    label: str
+    profile: DeploymentProfile = field(default_factory=DeploymentProfile)
+    created_at_ms: int | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "slug": self.slug,
+            "label": self.label,
+            "profile": self.profile.to_dict(),
+            "created_at_ms": self.created_at_ms,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Namespace:
+        return cls(
+            slug=d["slug"],
+            label=d.get("label", d["slug"]),
+            profile=DeploymentProfile.from_dict(d.get("profile", {})),
+            created_at_ms=d.get("created_at_ms"),
+        )
+
+
+def _namespaces_dir() -> Path:
+    d = home() / "namespaces"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _ns_path(slug: str) -> Path:
+    return _namespaces_dir() / f"{slug}.json"
+
+
+def list_namespaces() -> list[Namespace]:
+    ns = []
+    for p in sorted(_namespaces_dir().glob("*.json")):
+        try:
+            ns.append(Namespace.from_dict(json.loads(p.read_text())))
+        except Exception:
+            pass
+    if not ns:
+        # Auto-create default namespace on first call
+        default = Namespace(
+            slug="default", label="Default", profile=DeploymentProfile(tier="local")
+        )
+        save_namespace(default)
+        ns = [default]
+    return ns
+
+
+def get_namespace(slug: str) -> Namespace | None:
+    p = _ns_path(slug)
+    if not p.exists():
+        return None
+    return Namespace.from_dict(json.loads(p.read_text()))
+
+
+def save_namespace(ns: Namespace) -> None:
+    import time
+
+    with _ns_lock:
+        if ns.created_at_ms is None:
+            ns.created_at_ms = int(time.time() * 1000)
+        _ns_path(ns.slug).write_text(json.dumps(ns.to_dict(), indent=2))
+
+
+def validate_slug(slug: str) -> None:
+    if not _SLUG_RE.match(slug):
+        raise ValueError(f"Invalid namespace slug {slug!r} — must match [a-z][a-z0-9-]{{0,62}}")
+
+
+def ensure_default() -> None:
+    """Call at server startup to guarantee 'default' namespace exists."""
+    if not _ns_path("default").exists():
+        save_namespace(
+            Namespace(slug="default", label="Default", profile=DeploymentProfile(tier="local"))
+        )