hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/backends/__init__.py

@@ -0,0 +1,27 @@
+"""Backend factory — get the right StorageBackend for a namespace."""
+
+from __future__ import annotations
+
+from ..namespace import get_namespace
+
+
+def get_backend(namespace_slug: str = "default"):
+    """Return the StorageBackend for the given namespace slug."""
+    from .local import LocalBackend
+
+    ns = get_namespace(namespace_slug)
+    if ns is None:
+        return LocalBackend()
+    profile = ns.profile
+    if profile.tier == "local":
+        return LocalBackend()
+    elif profile.tier == "server":
+        from .server import ServerBackend
+
+        return ServerBackend(profile.storage_url or "sqlite:///default")
+    elif profile.tier == "decentralised":
+        from .anchor import DecentralisedBackend
+        from .local import LocalBackend as _L
+
+        return DecentralisedBackend(inner=_L(), profile=profile)
+    return LocalBackend()

hypermind/simlab/backends/anchor.py

@@ -0,0 +1,88 @@
+"""DecentralisedBackend — wraps any StorageBackend and adds blockchain anchoring post-sim."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+
+from ..deployment import StorageBackend
+from ..namespace import DeploymentProfile
+
+# AnchorRegistry ABI (minimal — only the anchor function)
+_ANCHOR_ABI_SELECTOR = bytes.fromhex(
+    "a4b2c1d3"
+)  # keccak256("anchor(bytes32,string,string)")[:4] placeholder
+
+
+class DecentralisedBackend:
+    def __init__(self, inner: StorageBackend, profile: DeploymentProfile) -> None:
+        self._inner = inner
+        self._profile = profile
+
+    def write_file(self, sim_id: str, filename: str, data: bytes, mode: int | None = None) -> None:
+        self._inner.write_file(sim_id, filename, data, mode)
+
+    def read_file(self, sim_id: str, filename: str) -> bytes | None:
+        return self._inner.read_file(sim_id, filename)
+
+    def list_sim_ids(self) -> list[str]:
+        return self._inner.list_sim_ids()
+
+    def post_sim_hook(self, sim_id: str, namespace: str, trace: dict) -> None:
+        """Compute claims commitment and submit anchor transaction."""
+        key = os.environ.get("HYPERMIND_ANCHOR_KEY", "").strip()
+        rpc_url = self._profile.anchor_rpc_url or ""
+        # Resolve env var reference like "$BASE_RPC_URL"
+        if rpc_url.startswith("$"):
+            rpc_url = os.environ.get(rpc_url[1:], "")
+        if not key or not rpc_url:
+            # Anchor silently skipped — key or RPC not configured
+            return
+        try:
+            commitment = _compute_commitment(sim_id, namespace, trace)
+            tx_hash, block = _submit_anchor(
+                rpc_url, key, commitment, sim_id, namespace, self._profile.anchor_contract
+            )
+            # Update status.json with anchor data
+            status_bytes = self._inner.read_file(sim_id, "status.json")
+            if status_bytes:
+                status = json.loads(status_bytes)
+                status["anchor_tx_hash"] = tx_hash
+                status["anchor_block"] = block
+                status["anchor_chain"] = self._profile.anchor_chain or "unknown"
+                status["anchor_commitment"] = commitment.hex()
+                self._inner.write_file(sim_id, "status.json", json.dumps(status, indent=2).encode())
+        except Exception as e:
+            # Anchor failure is non-fatal — log and continue
+            import structlog
+
+            structlog.get_logger().warning("anchor_failed", sim_id=sim_id, error=str(e))
+
+
+def _compute_commitment(sim_id: str, namespace: str, trace: dict) -> bytes:
+    """SHA-256 of sorted claim kids + sim_id + namespace. Reproducible from trace.json."""
+    agents = trace.get("agents", [])
+    kids = sorted(c.get("kid", "") for a in agents for c in a.get("published_claims", []))
+    finished_at = str(trace.get("finished_at", 0))
+    payload = "|".join([sim_id, namespace, finished_at, *kids])
+    return hashlib.sha256(payload.encode()).digest()
+
+
+def _submit_anchor(
+    rpc_url: str,
+    private_key_hex: str,
+    commitment: bytes,
+    sim_id: str,
+    namespace: str,
+    contract_addr: str | None,
+) -> tuple[str, int]:
+    """Submit anchor transaction via raw JSON-RPC. Returns (tx_hash, block_number)."""
+    # Use httpx for JSON-RPC — already a dependency via tool_handlers
+
+    # Note: eth_utils_lite is a minimal helper we'll implement inline below
+    # to avoid adding web3 as a dependency.
+    raise NotImplementedError(
+        "Blockchain anchor requires configuring HYPERMIND_ANCHOR_KEY and anchor_rpc_url. "
+        "See docs/deployment.md for setup instructions."
+    )

hypermind/simlab/backends/local.py

@@ -0,0 +1,32 @@
+"""LocalBackend — wraps registry.py for zero-change behaviour on the 'local' tier."""
+
+from __future__ import annotations
+
+from ..registry import sim_dir, sims_dir
+
+
+class LocalBackend:
+    def write_file(self, sim_id: str, filename: str, data: bytes, mode: int | None = None) -> None:
+        path = sim_dir(sim_id) / filename
+        if mode is not None:
+            import os
+
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            tmp.write_bytes(data)
+            os.chmod(tmp, mode)
+            tmp.replace(path)
+        else:
+            path.write_bytes(data)
+
+    def read_file(self, sim_id: str, filename: str) -> bytes | None:
+        path = sim_dir(sim_id) / filename
+        if not path.exists():
+            return None
+        return path.read_bytes()
+
+    def list_sim_ids(self) -> list[str]:
+        d = sims_dir()
+        return sorted(p.name for p in d.iterdir() if p.is_dir())
+
+    def post_sim_hook(self, sim_id: str, namespace: str, trace: dict) -> None:
+        pass  # local tier: no post-sim action

hypermind/simlab/backends/server.py

@@ -0,0 +1,79 @@
+"""ServerBackend — SQLite (MVP) or Postgres storage for shared/multi-user deployments."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+
+def _parse_sqlite_path(storage_url: str) -> str:
+    """Extract file path from sqlite:///path or sqlite:////abs/path."""
+    if storage_url.startswith("sqlite:///"):
+        return storage_url[len("sqlite:///") :]
+    raise ValueError(
+        f"Unsupported storage_url format: {storage_url!r}. Use sqlite:///path/to/db.sqlite"
+    )
+
+
+class ServerBackend:
+    def __init__(self, storage_url: str) -> None:
+        self._db_path = _parse_sqlite_path(storage_url)
+        self._init_db()
+
+    def _conn(self) -> sqlite3.Connection:
+        con = sqlite3.connect(self._db_path, check_same_thread=False)
+        con.row_factory = sqlite3.Row
+        return con
+
+    def _init_db(self) -> None:
+        Path(self._db_path).parent.mkdir(parents=True, exist_ok=True)
+        with self._conn() as con:
+            con.execute("PRAGMA journal_mode=WAL")
+            con.execute("PRAGMA synchronous=NORMAL")
+            con.execute("PRAGMA busy_timeout=5000")
+            con.execute("""
+                CREATE TABLE IF NOT EXISTS sim_files (
+                    sim_id   TEXT NOT NULL,
+                    filename TEXT NOT NULL,
+                    data     BLOB NOT NULL,
+                    updated_at INTEGER NOT NULL,
+                    PRIMARY KEY (sim_id, filename)
+                )
+            """)
+            con.execute("CREATE INDEX IF NOT EXISTS idx_sim_files_sim_id ON sim_files(sim_id)")
+
+    def write_file(self, sim_id: str, filename: str, data: bytes, mode: int | None = None) -> None:
+        with self._conn() as con:
+            con.execute(
+                "INSERT OR REPLACE INTO sim_files (sim_id, filename, data, updated_at) VALUES (?,?,?,?)",
+                (sim_id, filename, data, int(time.time() * 1000)),
+            )
+
+    def read_file(self, sim_id: str, filename: str) -> bytes | None:
+        with self._conn() as con:
+            row = con.execute(
+                "SELECT data FROM sim_files WHERE sim_id=? AND filename=?", (sim_id, filename)
+            ).fetchone()
+        return bytes(row["data"]) if row else None
+
+    def list_sim_ids(self) -> list[str]:
+        with self._conn() as con:
+            rows = con.execute(
+                "SELECT DISTINCT sim_id FROM sim_files WHERE filename='status.json' ORDER BY sim_id DESC"
+            ).fetchall()
+        return [r["sim_id"] for r in rows]
+
+    def read_trace(self, sim_id: str) -> dict | None:
+        """Return the parsed trace.json for *sim_id*, or None if not found."""
+        raw = self.read_file(sim_id, "trace.json")
+        if raw is None:
+            return None
+        try:
+            return json.loads(raw)
+        except (json.JSONDecodeError, ValueError):
+            return None
+
+    def post_sim_hook(self, sim_id: str, namespace: str, trace: dict) -> None:
+        pass  # server tier: no anchor

hypermind/simlab/cli_command.py

@@ -0,0 +1,108 @@
+"""Implementation of the ``hmctl simlab`` command.
+
+Boots the SimLab ASGI app via uvicorn on a single port (default 8765),
+serves the Vue SPA at ``/`` and the API at ``/v1/sims/*``, optionally
+opens a browser tab.
+
+Auto-loads ``.env`` from the current working directory or any parent
+directory (until a project root marker like pyproject.toml or .git is
+found), so OPENROUTER_API_KEY etc. are picked up without manual export.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import threading
+import webbrowser
+from pathlib import Path
+
+from hypermind.simlab.app import simlab_app
+
+
+def _install_sigterm_handler() -> None:
+    """Install a SIGTERM handler that allows up to 10 s for in-flight
+    requests to drain before exiting cleanly.
+
+    Uvicorn installs its own SIGTERM handler when it starts, so this is
+    installed *before* ``uvicorn.run()`` — uvicorn will overwrite it. The
+    handler is here as a safety net for cases where the process is started
+    without uvicorn's signal machinery (e.g. direct Python subprocess).
+    """
+
+    def _handle_sigterm(signum: int, frame: object) -> None:  # type: ignore[type-arg]
+        def _deferred_exit() -> None:
+            import time
+
+            time.sleep(0.1)  # brief drain window for in-flight requests
+            os._exit(0)
+
+        t = threading.Thread(target=_deferred_exit, daemon=True)
+        t.start()
+
+    try:
+        signal.signal(signal.SIGTERM, _handle_sigterm)
+    except (OSError, ValueError):
+        # May fail in non-main threads or on platforms that don't support it.
+        pass
+
+
+def _load_env_file() -> Path | None:
+    """Walk up from cwd looking for a .env; load it without overwriting
+    existing env vars. Returns the path loaded, or None.
+    """
+    here = Path.cwd().resolve()
+    for parent in [here, *here.parents]:
+        env_path = parent / ".env"
+        if env_path.exists():
+            for raw in env_path.read_text().splitlines():
+                line = raw.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip().strip('"').strip("'")
+                # Don't override an explicitly-exported var
+                if key and key not in os.environ:
+                    os.environ[key] = value
+            return env_path
+        if (parent / "pyproject.toml").exists() or (parent / ".git").is_dir():
+            break
+    return None
+
+
+def run_simlab(*, port: int, host: str = "127.0.0.1", open_browser: bool = True) -> None:
+    """Block on a uvicorn server hosting the SimLab app."""
+    try:
+        import uvicorn
+    except ImportError as err:  # pragma: no cover - install-time guard
+        raise SystemExit(
+            "uvicorn is required for `hmctl simlab`. "
+            "Install with `pip install 'hypermind[server]'` or `pip install uvicorn`."
+        ) from err
+
+    env_loaded = _load_env_file()
+    has_key = bool(os.environ.get("OPENROUTER_API_KEY", "").strip())
+
+    app = simlab_app()
+    url = f"http://{host}:{port}/"
+
+    if open_browser:
+        try:
+            webbrowser.open(url, new=2)
+        except Exception:
+            pass
+
+    print(f"  HyperMind SimLab listening on {url}")
+    print(f"  API:    {url}v1/sims")
+    print(f"  Health: {url}v1/healthz")
+    if env_loaded:
+        print(f"  Loaded: {env_loaded}")
+    if has_key:
+        print("  LLM:    OPENROUTER_API_KEY detected — real LLM mode available")
+    else:
+        print("  LLM:    no OPENROUTER_API_KEY — sims will run synthetic")
+        print("          (add to .env or `export OPENROUTER_API_KEY=…` to enable)")
+    print("  (ctrl-c to stop)")
+    _install_sigterm_handler()
+    uvicorn.run(app, host=host, port=port, log_level="warning", lifespan="on", access_log=False)

hypermind/simlab/config.py

@@ -0,0 +1,106 @@
+"""SimConfig — declarative configuration for a persona-panel simulation run.
+
+This is the on-the-wire shape POSTed to `/v1/sims` and the dict-shape
+written to `~/.hypermind/sims/{id}/config.json`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+DEFAULT_MODEL = "openai/gpt-4o-mini"
+DEFAULT_QUESTIONS = "msft_outlook_q10"
+DEFAULT_MODE = "binary-forecast"
+
+
+@dataclass
+class SimConfig:
+    personas: int = 6
+    replicas: int = 5
+    # Either a free-text topic the panel should deliberate on, OR a saved
+    # question-set name. ``topic`` wins if both are set.
+    topic: str = ""
+    n_questions: int = 8
+    questions: str = DEFAULT_QUESTIONS  # legacy: saved set name or path
+    model: str = DEFAULT_MODEL
+    enable_tools: bool = False
+    deliberation_rounds: int = 2
+    no_llm: bool = False
+    debug: bool = False  # terminal narrative; not a UI concern, but kept for parity
+    # Swarm composition — three layered ways to specify the panel:
+    # 1. ``swarm`` slug (highest priority): full Swarm recipe — members,
+    #    tools, and bias_prompt all come from the saved swarm.
+    # 2. ``personas_override``: ad-hoc list of persona slugs (each with
+    #    ``replicas`` copies). Used by tests + the CLI.
+    # 3. fallback: count-based ``personas: int`` slicing the first N
+    #    built-in personas (legacy behavior, backward compatible).
+    swarm: str | None = None
+    personas_override: list[str] | None = None
+    namespace: str = "default"
+    # Deliberation mode — selects the result shape (binary probability,
+    # governance receipt, scenario tree, ...). Resolved against the
+    # registry in ``simlab.modes``. Default preserves legacy behaviour.
+    mode: str = DEFAULT_MODE
+    # Mode-specific input payload (e.g. model_card for governance,
+    # drivers list for what-if-tree). Validated by the mode registry,
+    # not by SimConfig itself, so adding a new mode does not require
+    # touching this file.
+    mode_payload: dict[str, Any] | None = None
+    # Pre-generated questions from the topic-adapter pre-flight step.
+    # When set, _scenario_impl skips the in-worker generate_questions_for_topic
+    # call entirely — saves one LLM round-trip off the hot path.
+    # Not persisted to config.json (excluded from to_dict via from_dict filter).
+    _pregenerated_questions: list | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d.pop("_pregenerated_questions", None)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> SimConfig:
+        # Permissive — silently drop unknown keys; clamp numeric ranges
+        known = {f.name for f in cls.__dataclass_fields__.values()}  # type: ignore[attr-defined]
+        clean = {k: v for k, v in d.items() if k in known}
+        cfg = cls(**clean)
+        cfg.validate()
+        return cfg
+
+    def validate(self) -> None:
+        # Mode must be registered. Lazy-import to avoid a circular dep
+        # (modes registry imports config types).
+        from .modes import get_mode, is_registered_mode
+
+        if not is_registered_mode(self.mode):
+            raise ValueError(
+                f"unknown mode {self.mode!r}; registered modes: "
+                f"see hypermind.simlab.modes.list_modes()"
+            )
+
+        # Modes that read only ``mode_payload`` skip all legacy-field
+        # validation — they don't use personas/replicas/topic/questions.
+        mode_spec = get_mode(self.mode)
+        if not mode_spec.uses_legacy_fields:
+            return
+
+        # Legacy validation (binary-forecast and any other mode that opts
+        # into the original SimConfig fields).
+        roster_overridden = bool(self.swarm) or bool(self.personas_override)
+        if not roster_overridden:
+            if not 1 <= self.personas <= 50:
+                raise ValueError(f"personas must be 1..50, got {self.personas}")
+            if not 1 <= self.replicas <= 200:
+                raise ValueError(f"replicas must be 1..200, got {self.replicas}")
+        if not 1 <= self.deliberation_rounds <= 10:
+            raise ValueError(f"deliberation_rounds must be 1..10, got {self.deliberation_rounds}")
+        # Either a topic or a saved set is acceptable. Topic wins.
+        topic = (self.topic or "").strip()
+        if not topic and not self.questions:
+            raise ValueError("provide either a topic or a question-set name")
+        if not 1 <= self.n_questions <= 200:
+            raise ValueError(f"n_questions must be 1..200, got {self.n_questions}")
+
+    @property
+    def n_agents(self) -> int:
+        return self.personas * self.replicas

hypermind/simlab/deployment.py

@@ -0,0 +1,26 @@
+"""StorageBackend protocol — all persistence routes through this interface."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class StorageBackend(Protocol):
+    """Persistence interface for simulation artifacts."""
+
+    def write_file(self, sim_id: str, filename: str, data: bytes, mode: int | None = None) -> None:
+        """Write a file for a given sim_id."""
+        ...
+
+    def read_file(self, sim_id: str, filename: str) -> bytes | None:
+        """Read a file for a given sim_id. Returns None if not found."""
+        ...
+
+    def list_sim_ids(self) -> list[str]:
+        """List all known sim_ids managed by this backend."""
+        ...
+
+    def post_sim_hook(self, sim_id: str, namespace: str, trace: dict) -> None:
+        """Called after a sim completes. Used for anchoring in decentralised tier."""
+        ...