Merge pull request #5 from hanamorix/week-4-dream

feat: Week 4 — dream engine + LLM bridge (Claude CLI default)

Author: hanamorix

brain/bridge/__init__.py

@@ -0,0 +1,21 @@
+"""LLM provider abstraction for companion-emergence engines.
+
+Exports LLMProvider ABC + three concrete providers + factory.
+See docs/superpowers/specs/2026-04-23-week-4-dream-engine-design.md.
+"""
+
+from brain.bridge.provider import (
+    ClaudeCliProvider,
+    FakeProvider,
+    LLMProvider,
+    OllamaProvider,
+    get_provider,
+)
+
+__all__ = [
+    "ClaudeCliProvider",
+    "FakeProvider",
+    "LLMProvider",
+    "OllamaProvider",
+    "get_provider",
+]

brain/bridge/provider.py

@@ -0,0 +1,118 @@
+"""LLM provider abstraction — ABC + concrete providers + factory."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from abc import ABC, abstractmethod
+
+_DEFAULT_TIMEOUT_SECONDS = 300
+
+
+class LLMProvider(ABC):
+    """Abstract LLM provider. Subclasses implement `generate` and `name`."""
+
+    @abstractmethod
+    def generate(self, prompt: str, *, system: str | None = None) -> str:
+        """Return the LLM's completion for the given prompt."""
+
+    @abstractmethod
+    def name(self) -> str:
+        """Return a short provider name (e.g. 'fake', 'claude-cli:sonnet')."""
+
+
+class FakeProvider(LLMProvider):
+    """Deterministic hash-based echo provider for tests — zero network calls."""
+
+    def generate(self, prompt: str, *, system: str | None = None) -> str:
+        seed_input = (system or "").encode("utf-8") + b"||" + prompt.encode("utf-8")
+        h = hashlib.sha256(seed_input).hexdigest()[:16]
+        return f"DREAM: test dream {h} — an associative thread"
+
+    def name(self) -> str:
+        return "fake"
+
+
+class ClaudeCliProvider(LLMProvider):
+    """Shells out to `claude -p <prompt> --output-format json`.
+
+    Uses Hana's Claude Code subscription — no per-token API billing.
+    Per the feedback memory: this is the default Claude path for
+    companion-emergence and Hana's other projects.
+    """
+
+    def __init__(
+        self,
+        model: str = "sonnet",
+        timeout_seconds: int = _DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        self._model = model
+        self._timeout = timeout_seconds
+
+    def generate(self, prompt: str, *, system: str | None = None) -> str:
+        cmd = ["claude", "-p", prompt, "--output-format", "json", "--model", self._model]
+        if system is not None:
+            cmd.extend(["--system-prompt", system])
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=self._timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise TimeoutError(
+                f"ClaudeCliProvider: subprocess timed out after {self._timeout}s"
+            ) from exc
+
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"ClaudeCliProvider failed (exit {result.returncode}): {result.stderr.strip()}"
+            )
+
+        try:
+            payload = json.loads(result.stdout)
+            return str(payload["result"])
+        except (json.JSONDecodeError, KeyError, TypeError) as exc:
+            raise RuntimeError(
+                f"ClaudeCliProvider: unexpected output format: {result.stdout[:200]!r}"
+            ) from exc
+
+    def name(self) -> str:
+        return f"claude-cli:{self._model}"
+
+
+class OllamaProvider(LLMProvider):
+    """Placeholder for local Ollama integration.
+
+    Stub until Hana's local Ollama stack is back up. Fill in by:
+    1. Replacing raise with an httpx POST to {host}/api/generate
+    2. Parsing the streamed/non-streamed response
+    3. Adding the httpx dep to pyproject
+    """
+
+    def __init__(self, model: str = "nell-dpo", host: str = "http://localhost:11434") -> None:
+        self._model = model
+        self._host = host
+
+    def generate(self, prompt: str, *, system: str | None = None) -> str:
+        raise NotImplementedError(
+            "OllamaProvider is a stub; fill in when the local Ollama stack is available."
+        )
+
+    def name(self) -> str:
+        return f"ollama:{self._model}"
+
+
+def get_provider(name: str) -> LLMProvider:
+    """Resolve a provider identifier to an instance. Raises ValueError on unknown."""
+    if name == "fake":
+        return FakeProvider()
+    if name == "claude-cli":
+        return ClaudeCliProvider()
+    if name == "ollama":
+        return OllamaProvider()
+    raise ValueError(f"Unknown provider: {name!r}")

brain/cli.py

@@ -12,13 +12,17 @@
 from collections.abc import Callable
 
 from brain import __version__
+from brain.bridge.provider import get_provider
+from brain.engines.dream import DreamEngine
+from brain.memory.hebbian import HebbianMatrix
+from brain.memory.store import MemoryStore
 from brain.migrator.cli import build_parser as _build_migrate_parser
+from brain.paths import get_persona_dir
 
 # Subcommands the framework plans to ship. Each is a stub in Week 1;
 # filled in across Weeks 2-8 as respective modules come online.
 _STUB_COMMANDS: tuple[str, ...] = (
     "supervisor",
-    "dream",
     "heartbeat",
     "reflex",
     "status",
@@ -47,6 +51,52 @@ def _handler(args: argparse.Namespace) -> int:
     return _handler
 
 
+def _dream_handler(args: argparse.Namespace) -> int:
+    """Dispatch `nell dream` to the DreamEngine."""
+    persona_dir = get_persona_dir(args.persona)
+    if not persona_dir.exists():
+        raise FileNotFoundError(
+            f"No persona directory at {persona_dir} — "
+            f"run `nell migrate --install-as {args.persona}` first."
+        )
+    # Nested try/finally so a HebbianMatrix open failure still closes the
+    # already-open MemoryStore connection. Inline contextmanager would be
+    # prettier but stores don't implement __enter__/__exit__ yet.
+    store = MemoryStore(db_path=persona_dir / "memories.db")
+    try:
+        hebbian = HebbianMatrix(db_path=persona_dir / "hebbian.db")
+        try:
+            provider = get_provider(args.provider)
+            engine = DreamEngine(
+                store=store,
+                hebbian=hebbian,
+                embeddings=None,
+                provider=provider,
+                log_path=persona_dir / "dreams.log.jsonl",
+            )
+            result = engine.run_cycle(
+                seed_id=args.seed,
+                lookback_hours=args.lookback,
+                depth=args.depth,
+                decay_per_hop=args.decay,
+                neighbour_limit=args.limit,
+                dry_run=args.dry_run,
+            )
+        finally:
+            hebbian.close()
+    finally:
+        store.close()
+
+    if args.dry_run:
+        print("Dry run — no writes.")
+        print(f"Seed: {result.seed.id}  ({result.seed.content[:80]})")
+        print(f"Neighbours: {len(result.neighbours)}")
+        print(f"Prompt preview:\n{result.prompt[:400]}")
+    else:
+        print(result.dream_text or "")
+    return 0
+
+
 def _build_parser() -> argparse.ArgumentParser:
     """Construct the top-level argparse parser with all stub subcommands."""
     parser = argparse.ArgumentParser(
@@ -69,6 +119,32 @@ def _build_parser() -> argparse.ArgumentParser:
 
     _build_migrate_parser(subparsers)
 
+    dream_sub = subparsers.add_parser(
+        "dream",
+        help="Run one dream cycle against a persona's memory store.",
+    )
+    dream_sub.add_argument("--persona", default="nell", help="Persona name (default: nell).")
+    dream_sub.add_argument(
+        "--seed", default=None, help="Explicit seed memory id (default: auto-select)."
+    )
+    dream_sub.add_argument(
+        "--provider",
+        default="claude-cli",
+        help="LLM provider: claude-cli (default), fake, ollama.",
+    )
+    dream_sub.add_argument("--dry-run", action="store_true", help="Skip LLM call and store writes.")
+    dream_sub.add_argument(
+        "--lookback", type=int, default=24, help="Hours of history to consider (default: 24)."
+    )
+    dream_sub.add_argument(
+        "--depth", type=int, default=2, help="Spreading-activation depth (default: 2)."
+    )
+    dream_sub.add_argument("--decay", type=float, default=0.5, help="Per-hop decay (default: 0.5).")
+    dream_sub.add_argument(
+        "--limit", type=int, default=8, help="Max neighbours in prompt (default: 8)."
+    )
+    dream_sub.set_defaults(func=_dream_handler)
+
     return parser
 
 

brain/engines/__init__.py

@@ -0,0 +1,10 @@
+"""Cognitive engines for companion-emergence.
+
+Dreams consolidate associative patterns; heartbeat/reflex/research
+follow in later weeks. See:
+docs/superpowers/specs/2026-04-23-week-4-dream-engine-design.md
+"""
+
+from brain.engines.dream import DreamEngine, DreamResult, NoSeedAvailable
+
+__all__ = ["DreamEngine", "DreamResult", "NoSeedAvailable"]