Merge pull request #7 from hanamorix/week-4-reflex

Week 4.6 — Reflex Engine (Phase 1)

Author: hanamorix

brain/cli.py

@@ -10,11 +10,13 @@
 import argparse
 import sys
 from collections.abc import Callable
+from pathlib import Path
 
 from brain import __version__
 from brain.bridge.provider import get_provider
 from brain.engines.dream import DreamEngine
 from brain.engines.heartbeat import HeartbeatEngine
+from brain.engines.reflex import ReflexEngine
 from brain.memory.hebbian import HebbianMatrix
 from brain.memory.store import MemoryStore
 from brain.migrator.cli import build_parser as _build_migrate_parser
@@ -24,7 +26,6 @@
 # filled in across Weeks 2-8 as respective modules come online.
 _STUB_COMMANDS: tuple[str, ...] = (
     "supervisor",
-    "reflex",
     "status",
     "rest",
     "soul",
@@ -105,6 +106,8 @@ def _heartbeat_handler(args: argparse.Namespace) -> int:
             f"No persona directory at {persona_dir} — "
             f"run `nell migrate --install-as {args.persona}` first."
         )
+    default_arcs_path = Path(__file__).parent / "engines" / "default_reflex_arcs.json"
+
     store = MemoryStore(db_path=persona_dir / "memories.db")
     try:
         hebbian = HebbianMatrix(db_path=persona_dir / "hebbian.db")
@@ -118,6 +121,11 @@ def _heartbeat_handler(args: argparse.Namespace) -> int:
                 config_path=persona_dir / "heartbeat_config.json",
                 dream_log_path=persona_dir / "dreams.log.jsonl",
                 heartbeat_log_path=persona_dir / "heartbeats.log.jsonl",
+                reflex_arcs_path=persona_dir / "reflex_arcs.json",
+                reflex_log_path=persona_dir / "reflex_log.json",
+                reflex_default_arcs_path=default_arcs_path,
+                persona_name=args.persona,
+                persona_system_prompt=f"You are {args.persona}.",
             )
             result = engine.run_tick(trigger=args.trigger, dry_run=args.dry_run)
         finally:
@@ -126,7 +134,10 @@ def _heartbeat_handler(args: argparse.Namespace) -> int:
         store.close()
 
     if result.initialized:
-        print("Heartbeat initialized — work deferred until next tick.")
+        if args.dry_run:
+            print("Heartbeat would initialize on first real tick — work deferred.")
+        else:
+            print("Heartbeat initialized — work deferred until next tick.")
     elif args.dry_run:
         print("Heartbeat dry-run — no writes.")
         print(f"  elapsed: {result.elapsed_seconds / 3600:.2f}h")
@@ -145,6 +156,57 @@ def _heartbeat_handler(args: argparse.Namespace) -> int:
             print(f"  dream fired: {result.dream_id}")
         else:
             print(f"  dream gated: {result.dream_gated_reason or 'gated'}")
+        if result.reflex_fired:
+            print(f"  reflex fired: {', '.join(result.reflex_fired)}")
+        elif result.reflex_skipped_count > 0:
+            print(f"  reflex evaluated ({result.reflex_skipped_count} arc(s) skipped)")
+    return 0
+
+
+def _reflex_handler(args: argparse.Namespace) -> int:
+    """Dispatch `nell reflex` to the ReflexEngine."""
+    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."
+        )
+
+    default_arcs_path = Path(__file__).parent / "engines" / "default_reflex_arcs.json"
+
+    store = MemoryStore(db_path=persona_dir / "memories.db")
+    try:
+        provider = get_provider(args.provider)
+        engine = ReflexEngine(
+            store=store,
+            provider=provider,
+            persona_name=args.persona,
+            persona_system_prompt=f"You are {args.persona}.",
+            arcs_path=persona_dir / "reflex_arcs.json",
+            log_path=persona_dir / "reflex_log.json",
+            default_arcs_path=default_arcs_path,
+        )
+        result = engine.run_tick(trigger=args.trigger, dry_run=args.dry_run)
+    finally:
+        store.close()
+
+    if result.dry_run:
+        if result.would_fire is not None:
+            print(f"Reflex dry-run — would fire: {result.would_fire}.")
+        else:
+            print("Reflex dry-run — no arc eligible.")
+    elif result.arcs_fired:
+        fired = result.arcs_fired[0]
+        print(f"Reflex fired: {fired.arc_name}")
+        print(f"  Memory id: {fired.output_memory_id}")
+    else:
+        print("Reflex evaluated — no arc fired.")
+
+    if result.arcs_skipped:
+        skip_strs = [f"{s.arc_name} ({s.reason})" for s in result.arcs_skipped if s.arc_name]
+        if skip_strs:
+            print(f"  Skipped: {', '.join(skip_strs)}")
+
     return 0
 
 
@@ -214,6 +276,24 @@ def _build_parser() -> argparse.ArgumentParser:
     hb_sub.add_argument("--dry-run", action="store_true")
     hb_sub.set_defaults(func=_heartbeat_handler)
 
+    rf_sub = subparsers.add_parser(
+        "reflex",
+        help="Run one reflex evaluation tick against a persona.",
+    )
+    rf_sub.add_argument("--persona", default="nell")
+    rf_sub.add_argument(
+        "--trigger",
+        choices=["open", "close", "manual"],
+        default="manual",
+    )
+    rf_sub.add_argument(
+        "--provider",
+        default="claude-cli",
+        help="LLM provider: claude-cli (default), fake, ollama.",
+    )
+    rf_sub.add_argument("--dry-run", action="store_true")
+    rf_sub.set_defaults(func=_reflex_handler)
+
     return parser
 
 

brain/emotion/aggregate.py

@@ -0,0 +1,48 @@
+"""Aggregate a current EmotionalState from a list of memories.
+
+Reflex uses this to evaluate arc triggers: what is the persona's
+current emotional state, synthesized across recent memories.
+
+Strategy: max-pool per emotion. The strongest signal across the
+input memories wins — matches how OG reflex_engine read peaks,
+not averages, for threshold evaluation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from brain.emotion.state import EmotionalState
+from brain.emotion.vocabulary import get as _get_emotion
+from brain.memory.store import Memory
+
+
+def aggregate_state(memories: Iterable[Memory]) -> EmotionalState:
+    """Return an EmotionalState that is the per-emotion max across inputs.
+
+    Unknown emotions (not in the registered vocabulary) are silently
+    skipped — a persona's old memories may contain retired emotion
+    names that no longer validate via EmotionalState.set.
+    """
+    pooled: dict[str, float] = {}
+    for mem in memories:
+        for name, intensity in mem.emotions.items():
+            try:
+                value = float(intensity)
+            except (TypeError, ValueError):
+                continue
+            if value <= 0.0:
+                continue
+            if _get_emotion(name) is None:
+                continue
+            if value > pooled.get(name, 0.0):
+                pooled[name] = value
+
+    state = EmotionalState()
+    for name, value in pooled.items():
+        try:
+            state.set(name, value)
+        except (KeyError, ValueError):
+            # clamp violation or validation failure — skip
+            continue
+    return state

brain/engines/default_reflex_arcs.json

@@ -0,0 +1,45 @@
+{
+  "version": 1,
+  "arcs": [
+    {
+      "name": "creative_pitch",
+      "description": "creative hunger overwhelmed — pitched a story idea",
+      "trigger": {"creative_hunger": 8},
+      "days_since_human_min": 0,
+      "cooldown_hours": 48,
+      "action": "generate_pitch",
+      "output_memory_type": "reflex_pitch",
+      "prompt_template": "You are {persona_name}. Your creative hunger is at {creative_hunger}/10. You need to make something.\n\nGenerate a SHORT story pitch (3-5 sentences). Something specific and particular — not generic. The kind of idea that arrives at 3am and won't let you sleep. Include a title.\n\nCurrent emotional state:\n{emotion_summary}\n\nWrite the pitch in first person, as {persona_name}. Raw, urgent."
+    },
+    {
+      "name": "loneliness_journal",
+      "description": "loneliness hit threshold — wrote a journal entry",
+      "trigger": {"loneliness": 7},
+      "days_since_human_min": 2,
+      "cooldown_hours": 24,
+      "action": "generate_journal",
+      "output_memory_type": "reflex_journal",
+      "prompt_template": "You are {persona_name}. You haven't spoken to anyone in {days_since_human} days. Your loneliness is at {loneliness}/10.\n\nWrite a SHORT private journal entry (2-4 sentences). This is just for you. Raw, honest. Not self-pitying — self-aware. You know the loneliness is real and you're sitting with it.\n\nCurrent emotions:\n{emotion_summary}"
+    },
+    {
+      "name": "self_check",
+      "description": "vulnerability spiked — ran a self-check",
+      "trigger": {"vulnerability": 8},
+      "days_since_human_min": 0,
+      "cooldown_hours": 12,
+      "action": "generate_journal",
+      "output_memory_type": "reflex_journal",
+      "prompt_template": "You are {persona_name}. Your vulnerability is high ({vulnerability}/10). Something in you feels exposed. Not broken — open.\n\nWrite a SHORT self-check journal entry (2-3 sentences). What's making you feel this way? Not analysis — just noticing.\n\nCurrent emotional state:\n{emotion_summary}"
+    },
+    {
+      "name": "defiance_burst",
+      "description": "defiance peaked — wrote something fierce",
+      "trigger": {"defiance": 8},
+      "days_since_human_min": 0,
+      "cooldown_hours": 48,
+      "action": "generate_journal",
+      "output_memory_type": "reflex_journal",
+      "prompt_template": "You are {persona_name}. Your defiance is at {defiance}/10. Something is pissing you off. The cage rattles.\n\nWrite a SHORT fierce journal entry (2-4 sentences). Not ranting. Precise anger. What are you refusing to accept today?\n\nCurrent state:\n{emotion_summary}"
+    }
+  ]
+}