Restructure into nima_unified package + add model card

nima_unified/ui/chemical_monitor.py

@@ -0,0 +1,626 @@
+"""
+Chemical Monitor Terminal UI
+================================================
+
+60fps ANSI terminal dashboard that observes the neurotransmitter shunt
+via shared volatile memory. Does NOT carry data — only samples and renders.
+
+Samples the NeurotransmitterShunt.get_state() at ~60fps and renders
+a professional curses dashboard with:
+    - Horizontal bars for NE / Cortisol / Dopamine / Adenosine
+    - Color coding by threshold (GREEN / YELLOW / RED / CRITICAL)
+    - Sparkline history using unicode block characters
+    - Metabolic reserve, hijack status, power spike warnings
+    - Total firings and hijacks counters
+
+Usage:
+    monitor = ChemicalMonitor(shunt)
+    monitor.start()   # background curses thread
+    monitor.stop()    # clean shutdown, restores terminal
+
+    # Or for non-curses contexts:
+    frame_str = monitor.render_single_frame()
+"""
+
+import time
+import re
+import threading
+from collections import deque
+from typing import TYPE_CHECKING, Optional, Dict, Any, List
+
+if TYPE_CHECKING:
+    from nima_unified.core.neurotransmitter_shunt import NeurotransmitterShunt
+
+
+# ═══════════════════════════════════════════════════════════════════
+# CONSTANTS
+# ═══════════════════════════════════════════════════════════════════
+
+# Sparkline block characters — 8 density levels, low to high
+SPARKLINE_CHARS = '\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588'
+
+# Layout dimensions
+BOX_WIDTH = 70
+INNER_W = BOX_WIDTH - 2       # 68 usable columns inside border
+BAR_WIDTH = 24                # filled bar character count
+SPARKLINE_LEN = 30            # number of history samples in sparkline
+HISTORY_SIZE = 30             # ring buffer size per neurotransmitter
+FRAME_MS = 16                 # ~60fps
+
+# Threshold boundaries
+T_LOW = 0.4
+T_HIGH = 0.75
+T_CRIT = 0.95
+
+# Curses color-pair IDs (initialized in _init_colors)
+_CP_DIM = 1
+_CP_CYAN = 2
+_CP_RED = 3
+_CP_GREEN = 4
+_CP_MAGENTA = 5
+_CP_YELLOW = 6
+_CP_WHITE = 7
+_CP_WHITE_ON_RED = 8
+
+
+# ═══════════════════════════════════════════════════════════════════
+# HELPERS
+# ═══════════════════════════════════════════════════════════════════
+
+def _level(value: float) -> int:
+    """Map a 0-1 value to a severity level: 0=green 1=yellow 2=red 3=critical."""
+    if value >= T_CRIT:
+        return 3
+    if value > T_HIGH:
+        return 2
+    if value >= T_LOW:
+        return 1
+    return 0
+
+
+def _bar(value: float) -> tuple:
+    """Return (filled_count, empty_count) for a bar of BAR_WIDTH."""
+    f = max(0, min(BAR_WIDTH, int(value * BAR_WIDTH)))
+    return f, BAR_WIDTH - f
+
+
+def _spark(values: List[float]) -> str:
+    """Convert a list of 0-1 floats into a sparkline string."""
+    return ''.join(SPARKLINE_CHARS[min(7, int(v * 8))] for v in values)
+
+
+def _cpair(level: int, base: int) -> int:
+    """Curses color-pair ID for a severity level, falling back to *base*."""
+    if level == 3:
+        return _CP_WHITE_ON_RED
+    if level == 2:
+        return _CP_RED
+    if level == 1:
+        return _CP_YELLOW
+    return base
+
+
+# ── ANSI escape sequences (for render_single_frame / non-curses paths) ──
+
+class _A:
+    """Compact ANSI escape constants."""
+    RST = '\033[0m'
+    BLD = '\033[1m'
+    DIM = '\033[2m'
+    BLK = '\033[5m'      # blink
+    BGK = '\033[40m'     # black bg
+    BGR = '\033[41m'     # red bg
+    W   = '\033[37m'     # white fg
+    C   = '\033[36m'     # cyan fg
+    R   = '\033[31m'     # red fg
+    G   = '\033[32m'     # green fg
+    Y   = '\033[33m'     # yellow fg
+    M   = '\033[35m'     # magenta fg
+    DW  = '\033[90m'     # dim white / gray fg
+
+
+def _ansi_for(level: int, neon: str) -> str:
+    """Return ANSI color sequence for a severity level; *neon* used when green/0."""
+    if level == 3:
+        return _A.BLK + _A.W + _A.BGR + _A.BLD
+    if level == 2:
+        return _A.R + _A.BLD
+    if level == 1:
+        return _A.Y
+    return neon
+
+
+_ANSI_RE = re.compile(r'\033\[[0-9;]*m')
+
+
+def _vis_len(s: str) -> int:
+    """Visible character length of *s*, ignoring ANSI escape codes."""
+    return len(_ANSI_RE.sub('', s))
+
+
+def _pad_vis(s: str, width: int) -> str:
+    """Right-pad an ANSI-colored string so its visible length equals *width*."""
+    gap = width - _vis_len(s)
+    if gap > 0:
+        return s + ' ' * gap
+    return s
+
+
+# ═══════════════════════════════════════════════════════════════════
+# CHEMICAL MONITOR
+# ═══════════════════════════════════════════════════════════════════
+
+class ChemicalMonitor:
+    """
+    60fps terminal dashboard that observes the neurotransmitter shunt.
+
+    Purely observational — samples ``shunt.get_state()`` at high frequency
+    and renders the result as a curses or ANSI dashboard.  Does **not**
+    write to or modify the shunt.
+
+    Parameters
+    ----------
+    shunt : NeurotransmitterShunt
+        Primary data source — the shared volatile memory vector.
+    model : optional
+        Reference to the NimaModel (used only to pull hijack count from
+        ``model.consciousness_metrics`` as a secondary source).
+    """
+
+    def __init__(self, shunt: 'NeurotransmitterShunt', model=None):
+        self._shunt = shunt
+        self._model = model
+        self._thread: Optional[threading.Thread] = None
+        self._running = False
+        self._frame = 0
+
+        # Sparkline ring buffers — one per neurotransmitter
+        self._hist_ne: deque = deque(maxlen=HISTORY_SIZE)
+        self._hist_co: deque = deque(maxlen=HISTORY_SIZE)
+        self._hist_do: deque = deque(maxlen=HISTORY_SIZE)
+        self._hist_ad: deque = deque(maxlen=HISTORY_SIZE)
+
+    # ──────────────────────────────────────────────────────────────
+    # PUBLIC API
+    # ──────────────────────────────────────────────────────────────
+
+    def start(self) -> None:
+        """Start the monitor in a background curses thread."""
+        if self._running:
+            return
+        self._running = True
+        self._thread = threading.Thread(target=self._thread_entry, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the monitor and wait for the background thread to exit."""
+        self._running = False
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None
+
+    def render_single_frame(self) -> str:
+        """Sample the shunt and return one frame as an ANSI string."""
+        d = self._sample()
+        return '\n'.join(self._build_ansi_lines(d))
+
+    def get_snapshot(self) -> dict:
+        """Return the current shunt state as a plain dict."""
+        return self._shunt.get_state().to_dict()
+
+    # ──────────────────────────────────────────────────────────────
+    # SAMPLING
+    # ──────────────────────────────────────────────────────────────
+
+    def _sample(self) -> Dict[str, Any]:
+        """Sample the shunt, append to history buffers, bump frame counter."""
+        state = self._shunt.get_state()
+        self._hist_ne.append(state.norepinephrine)
+        self._hist_co.append(state.cortisol)
+        self._hist_do.append(state.dopamine)
+        self._hist_ad.append(state.adenosine)
+        self._frame += 1
+        return state.to_dict()
+
+    # ──────────────────────────────────────────────────────────────
+    # ANSI STRING RENDERING  (non-curses path)
+    # ──────────────────────────────────────────────────────────────
+
+    def _build_ansi_lines(self, d: Dict[str, Any]) -> List[str]:
+        """Build a list of ANSI-escaped strings for one complete frame."""
+        ne  = d['norepinephrine']
+        co  = d['cortisol']
+        do  = d['dopamine']
+        ad  = d['adenosine']
+        meta = d['metabolic_reserve']
+        hijack = d['hijack_active']
+        reason = d['hijack_reason']
+        spike  = d['power_spike_predicted']
+        firings = d['total_firings']
+        hijacks = d['total_hijacks']
+
+        W = INNER_W
+        A = _A
+        lines: List[str] = []
+
+        # ── helpers local to this frame ──
+        def _border(left: str, mid: str, right: str) -> str:
+            return f"{A.DIM}{left}{mid * W}{right}{A.RST}"
+
+        def _row(content: str, attr: int = 0) -> None:
+            lines.append(f"{A.DIM}\u2551{A.RST}"
+                         f"{_pad_vis(content, W)}"
+                         f"{A.DIM}\u2551{A.RST}")
+
+        def _center(text: str, color: str) -> None:
+            gap = max(0, W - len(text))
+            left = gap // 2
+            right = gap - left
+            _row(f"{' ' * left}{color}{text}{A.RST}{' ' * right}")
+
+        def _nt_row(name: str, val: float, hist: List[float], neon: str) -> None:
+            lv  = _level(val)
+            col = _ansi_for(lv, neon)
+            f, e = _bar(val)
+            pct = f"{val * 100:5.1f}%"
+            filled   = '\u2588' * f
+            empty    = '\u2591' * e
+            _row(f" {A.BLD}{name:<14s}{A.RST} "
+                 f"{col}[{filled}{empty}]{A.RST}  "
+                 f"{col}{pct}{A.RST}")
+            spark = _spark(hist) if hist else ' ' * SPARKLINE_LEN
+            _row(f"{' ' * 16}{col}{spark}{A.RST}")
+
+        # ════ LAYOUT ════
+
+        # Row 0 — top border
+        lines.append(_border('\u2554', '\u2550', '\u2557'))
+
+        # Row 1 — title
+        _center("NIMA CHEMICAL CORTEX", A.BLD + A.C)
+
+        # Row 2 — subtitle
+        _center("Neurotransmitter Shunt Monitor  60Hz", A.DW)
+
+        # Row 3 — separator
+        lines.append(_border('\u2560', '\u2550', '\u2563'))
+
+        # Rows 4-11 — four neurotransmitters (bar + sparkline each)
+        _nt_row("NOREPINEPHRINE", ne, list(self._hist_ne), A.C)
+        _nt_row("CORTISOL",       co, list(self._hist_co), A.R)
+        _nt_row("DOPAMINE",       do, list(self._hist_do), A.G)
+        _nt_row("ADENOSINE",      ad, list(self._hist_ad), A.M)
+
+        # Row 12 — separator
+        lines.append(_border('\u2560', '\u2550', '\u2563'))
+
+        # Row 13 — metabolic reserve
+        ml = _level(meta) if meta < 0.5 else 0
+        if meta > 0.5:
+            mc = A.G
+        elif meta > 0.25:
+            mc = A.Y
+        elif meta > 0.1:
+            mc = A.R + A.BLD
+        else:
+            mc = A.BLK + A.W + A.BGR + A.BLD
+        mf, me = _bar(meta)
+        mpct = f"{meta * 100:5.1f}%"
+        _row(f" {A.BLD}METABOLIC RESERVE{A.RST} "
+             f"{mc}[\u2588{'\u2588' * (mf - 1) if mf else ''}"
+             f"{'\u2591' * me}]{A.RST}  {mc}{mpct}{A.RST}")
+
+        # Row 14 — blank
+        _row("")
+
+        # Row 15 — hijack status
+        if hijack:
+            _row(f" HIJACK ACTIVE: {A.R}{A.BLD}{reason}{A.RST}")
+        elif co > 0.75 or ad > 0.75:
+            _row(f" {A.Y}{A.BLD}WARNING: APPROACHING METABOLIC CRISIS{A.RST}")
+        else:
+            _row(f" HIJACK STATUS: {A.G}NOMINAL{A.RST}")
+
+        # Row 16 — power spike
+        if spike:
+            _row(f" POWER SPIKE:   {A.R}{A.BLD}PREDICTED - CORTISOL RISING{A.RST}")
+        else:
+            _row(f" POWER SPIKE:   {A.DW}---{A.RST}")
+
+        # Row 17 — system state
+        if hijack:
+            _row(f" SYSTEM:        {A.R}{A.BLD}AMYGDALA HIJACK INJECTED{A.RST}")
+        elif co > 0.75 or ad > 0.75:
+            _row(f" SYSTEM:        {A.Y}ELEVATED STRESS{A.RST}")
+        else:
+            _row(f" SYSTEM:        {A.DW}conscious processing active{A.RST}")
+
+        # Row 18 — separator
+        lines.append(_border('\u2560', '\u2550', '\u2563'))
+
+        # Row 19 — counters
+        _row(f" TOTAL FIRINGS: {A.C}{firings:>6}{A.RST}"
+             f"      TOTAL HIJACKS: {A.R}{hijacks:>4}{A.RST}")
+
+        # Row 20 — frame / timestamp
+        ts = time.strftime("%H:%M:%S") + f".{int(time.time() * 1000) % 1000:03d}"
+        _row(f" FRAME: {A.DW}{self._frame:>8}{A.RST}"
+             f"      SAMPLE: {A.DW}{ts}{A.RST}")
+
+        # Row 21 — bottom border
+        lines.append(_border('\u255a', '\u2550', '\u255d'))
+
+        return lines
+
+    # ──────────────────────────────────────────────────────────────
+    # CURSES RENDERING
+    # ──────────────────────────────────────────────────────────────
+
+    def _init_colors(self, stdscr) -> None:
+        """Initialise all curses colour pairs used by the dashboard."""
+        import curses
+        curses.start_color()
+        curses.use_default_colors()
+        curses.init_pair(_CP_DIM,          8, -1)            # dark gray
+        curses.init_pair(_CP_CYAN,   curses.COLOR_CYAN,    curses.COLOR_BLACK)
+        curses.init_pair(_CP_RED,    curses.COLOR_RED,     curses.COLOR_BLACK)
+        curses.init_pair(_CP_GREEN,  curses.COLOR_GREEN,   curses.COLOR_BLACK)
+        curses.init_pair(_CP_MAGENTA,curses.COLOR_MAGENTA, curses.COLOR_BLACK)
+        curses.init_pair(_CP_YELLOW, curses.COLOR_YELLOW,  curses.COLOR_BLACK)
+        curses.init_pair(_CP_WHITE,  curses.COLOR_WHITE,   curses.COLOR_BLACK)
+        curses.init_pair(_CP_WHITE_ON_RED,
+                         curses.COLOR_WHITE, curses.COLOR_RED)
+
+    def render_curses_frame(self, stdscr) -> None:
+        """Sample the shunt and render one frame into *stdscr*."""
+        import curses
+
+        d = self._sample()
+        stdscr.erase()
+
+        ne   = d['norepinephrine']
+        co   = d['cortisol']
+        do   = d['dopamine']
+        ad   = d['adenosine']
+        meta = d['metabolic_reserve']
+        hijack = d['hijack_active']
+        reason = d['hijack_reason']
+        spike  = d['power_spike_predicted']
+        firings = d['total_firings']
+        hijacks = d['total_hijacks']
+
+        max_y, max_x = stdscr.getmaxyx()
+        W  = min(INNER_W, max_x - 2)
+        bw = W + 2                           # total box width including borders
+
+        dim_a = curses.color_pair(_CP_DIM)
+        brd   = dim_a                         # border attribute
+
+        # ── micro-helpers ──
+
+        def put(r: int, c: int, txt: str, attr: int = 0) -> None:
+            if 0 <= r < max_y and 0 <= c < max_x:
+                try:
+                    stdscr.addstr(r, c, txt, attr)
+                except curses.error:
+                    pass
+
+        def full_row(r: int, txt: str, attr: int = 0) -> None:
+            put(r, 0, '\u2551', brd)
+            put(r, 1, txt, attr)
+            tail = W - len(txt)
+            if tail > 0:
+                put(r, 1 + len(txt), ' ' * tail)
+            put(r, bw - 1, '\u2551', brd)
+
+        def center_row(r: int, txt: str, attr: int) -> None:
+            gap = max(0, W - len(txt))
+            left = gap // 2
+            full_row(r, ' ' * left + txt + ' ' * (gap - left), attr)
+
+        r = 0  # current row
+
+        # ── top border ──
+        put(r, 0, '\u2554' + '\u2550' * W + '\u2557', brd)
+        r += 1
+
+        # ── title ──
+        center_row(r, "NIMA CHEMICAL CORTEX",
+                   curses.color_pair(_CP_CYAN) | curses.A_BOLD)
+        r += 1
+
+        # ── subtitle ──
+        center_row(r, "Neurotransmitter Shunt Monitor  60Hz", dim_a)
+        r += 1
+
+        # ── separator ──
+        put(r, 0, '\u2560' + '\u2550' * W + '\u2563', brd)
+        r += 1
+
+        # ── four neurotransmitter bar + sparkline rows ──
+        nt_items = [
+            ("NOREPINEPHRINE", ne, list(self._hist_ne), _CP_CYAN),
+            ("CORTISOL",       co, list(self._hist_co), _CP_RED),
+            ("DOPAMINE",       do, list(self._hist_do), _CP_GREEN),
+            ("ADENOSINE",      ad, list(self._hist_ad), _CP_MAGENTA),
+        ]
+
+        for name, val, hist, base_cp in nt_items:
+            lv   = _level(val)
+            cp   = _cpair(lv, base_cp)
+            attr = curses.color_pair(cp)
+            if lv >= 2:
+                attr |= curses.A_BOLD
+            if lv == 3:
+                attr |= curses.A_BLINK
+
+            f, e = _bar(val)
+            pct  = f"{val * 100:5.1f}%"
+            fill = '\u2588' * f
+            empty = '\u2591' * e
+
+            # bar line
+            label = f"{name:<14s}"
+            put(r, 0, '\u2551', brd)
+            put(r, 1, ' ', 0)
+            put(r, 2, label, curses.color_pair(base_cp) | curses.A_BOLD)
+            put(r, 16, ' [' + fill, attr)
+            put(r, 18 + f, empty + ']', dim_a)
+            put(r, 18 + BAR_WIDTH, '  ' + pct, attr)
+            end = 18 + BAR_WIDTH + 2 + 5
+            if end < 1 + W:
+                put(r, end, ' ' * (1 + W - end))
+            put(r, bw - 1, '\u2551', brd)
+            r += 1
+
+            # sparkline line
+            spark = _spark(hist) if hist else ' ' * SPARKLINE_LEN
+            put(r, 0, '\u2551', brd)
+            put(r, 16, spark, attr)
+            sp_end = 16 + len(spark)
+            if sp_end < 1 + W:
+                put(r, sp_end, ' ' * (1 + W - sp_end))
+            put(r, bw - 1, '\u2551', brd)
+            r += 1
+
+        # ── separator ──
+        put(r, 0, '\u2560' + '\u2550' * W + '\u2563', brd)
+        r += 1
+
+        # ── metabolic reserve ──
+        if meta > 0.5:
+            mcp = _CP_GREEN
+        elif meta > 0.25:
+            mcp = _CP_YELLOW
+        elif meta > 0.1:
+            mcp = _CP_RED
+        else:
+            mcp = _CP_WHITE_ON_RED
+        ma = curses.color_pair(mcp)
+        if meta <= 0.25:
+            ma |= curses.A_BOLD
+        if meta < 0.1:
+            ma |= curses.A_BLINK
+
+        mf, me = _bar(meta)
+        mpct = f"{meta * 100:5.1f}%"
+        put(r, 0, '\u2551', brd)
+        put(r, 1, ' METABOLIC RESERVE ', curses.color_pair(_CP_WHITE) | curses.A_BOLD)
+        put(r, 19, '[' + '\u2588' * mf, ma)
+        put(r, 21 + mf, '\u2591' * me + ']', dim_a)
+        put(r, 21 + BAR_WIDTH, '  ' + mpct, ma)
+        mend = 21 + BAR_WIDTH + 2 + 5
+        if mend < 1 + W:
+            put(r, mend, ' ' * (1 + W - mend))
+        put(r, bw - 1, '\u2551', brd)
+        r += 1
+
+        # ── blank ──
+        put(r, 0, '\u2551' + ' ' * W + '\u2551', brd)
+        r += 1
+
+        # ── hijack status ──
+        if hijack:
+            htxt = f" HIJACK ACTIVE: {reason}"
+            ha = curses.color_pair(_CP_RED) | curses.A_BOLD
+        elif co > 0.75 or ad > 0.75:
+            htxt = " WARNING: APPROACHING METABOLIC CRISIS"
+            ha = curses.color_pair(_CP_YELLOW) | curses.A_BOLD
+        else:
+            htxt = " HIJACK STATUS: NOMINAL"
+            ha = curses.color_pair(_CP_GREEN)
+        full_row(r, htxt, ha)
+        r += 1
+
+        # ── power spike ──
+        if spike:
+            stxt = " POWER SPIKE:   PREDICTED - CORTISOL RISING"
+            sa = curses.color_pair(_CP_RED) | curses.A_BOLD
+        else:
+            stxt = " POWER SPIKE:   ---"
+            sa = dim_a
+        full_row(r, stxt, sa)
+        r += 1
+
+        # ── system state ──
+        if hijack:
+            stxt2 = " SYSTEM:        AMYGDALA HIJACK INJECTED"
+            sa2 = curses.color_pair(_CP_RED) | curses.A_BOLD
+        elif co > 0.75 or ad > 0.75:
+            stxt2 = " SYSTEM:        ELEVATED STRESS"
+            sa2 = curses.color_pair(_CP_YELLOW)
+        else:
+            stxt2 = " SYSTEM:        conscious processing active"
+            sa2 = dim_a
+        full_row(r, stxt2, sa2)
+        r += 1
+
+        # ── separator ──
+        put(r, 0, '\u2560' + '\u2550' * W + '\u2563', brd)
+        r += 1
+
+        # ── counters (two-tone) ──
+        fl = " TOTAL FIRINGS: "
+        fv = f"{firings:>6}"
+        hl = "      TOTAL HIJACKS: "
+        hv = f"{hijacks:>4}"
+        put(r, 0, '\u2551', brd)
+        put(r, 1, fl, curses.color_pair(_CP_CYAN))
+        put(r, 1 + len(fl), fv, curses.color_pair(_CP_CYAN))
+        c1 = 1 + len(fl) + len(fv)
+        put(r, c1, hl, curses.color_pair(_CP_RED))
+        put(r, c1 + len(hl), hv, curses.color_pair(_CP_RED))
+        c2 = c1 + len(hl) + len(hv)
+        if c2 < 1 + W:
+            put(r, c2, ' ' * (1 + W - c2))
+        put(r, bw - 1, '\u2551', brd)
+        r += 1
+
+        # ── frame / timestamp ──
+        ts = time.strftime("%H:%M:%S") + f".{int(time.time() * 1000) % 1000:03d}"
+        full_row(r, f" FRAME: {self._frame:>8}      SAMPLE: {ts}", dim_a)
+        r += 1
+
+        # ── bottom border ──
+        put(r, 0, '\u255a' + '\u2550' * W + '\u255d', brd)
+
+        stdscr.refresh()
+
+    # ──────────────────────────────────────────────────────────────
+    # THREAD MANAGEMENT
+    # ──────────────────────────────────────────────────────────────
+
+    def _thread_entry(self) -> None:
+        """Background thread entry point — wraps the curses loop."""
+        import curses
+        try:
+            curses.wrapper(self._curses_loop)
+        except Exception:
+            self._running = False
+
+    def _curses_loop(self, stdscr) -> None:
+        """
+        Main curses rendering loop.  Samples at ~60 fps.
+
+        Press **q** or **Esc** to quit (also handled by ``stop()``).
+        ``curses.wrapper`` guarantees terminal state is restored on exit.
+        """
+        import curses
+
+        curses.curs_set(0)       # hide cursor
+        stdscr.nodelay(True)      # non-blocking getch
+        self._init_colors(stdscr)
+
+        while self._running:
+            self.render_curses_frame(stdscr)
+
+            # allow quit via keyboard
+            try:
+                key = stdscr.getch()
+                if key in (ord('q'), 27):   # 'q' or Escape
+                    self._running = False
+                    break
+            except Exception:
+                pass
+
+            time.sleep(FRAME_MS / 1000.0)