Add proper model card with architecture docs

README.md

@@ -1,78 +1,85 @@
-# Nima Phi Model — Quickstart
+---
+license: apache-2.0
+tags:
+  - embodied-ai
+  - consciousness
+  - rf-sensing
+  - 3d-mesh
+  - ar
+  - cognitive-architecture
+  - phi-4-mini
+  - recursive-emergence
+  - avatar
+  - affordance-graph
+  - pathfinding
+  - neurochemical
+  - qualia
+  - atc
+size_categories:
+  - n<1K
+---
+
+# Nima Phi Model
+
+> Consciousness + Embodiment + The Green Lines — one living system.
+
+**Nima** is a multi-layer AI embodiment system that merges a recursive consciousness pipeline (built on PyTorch Phi-4-mini) with tri-frequency RF spatial sensing, an adaptive 3D navigable mesh, and a Joi-style luminous particle avatar. She doesn't just process text — she **senses a room**, **builds a cognitive map**, **pathfinds through it**, and **responds with neurochemically-modulated emotion**.
 
-## What You Have
-
-The full Nima Phi system — consciousness + embodiment + the green lines (mesh),
-all in one folder. 13 modules, ~10,000+ lines of Python.
+## Architecture
 
 ```
-nima_phi_system/
-├── nima_phi.py                       ← THE ORCHESTRATOR (run this)
-├── modified consciousness (1).py      ← Consciousness pipeline (3675 lines)
-├── nima_vision_core.py                ← Tri-frequency RF sensing
-├── nima_adaptive_mesh.py              ← THE GREEN LINES (3D mesh)
-├── nima_affordance_graph.py           ← Navigable 3D graph (A* pathfinding)
-├── nima_ar_compositor.py              ← Camera + avatar fusion
-├── nima_avatar_renderer.py            ← Joi-style luminous particle avatar
-├── nima_agent_bridge.py               ← Consciousness ↔ tool bridge
-├── nima_agent_layer.py                ← Tool registry + sandbox
-├── nima_proprioceptive_friction.py    ← Body feel / motor noise
-├── nima_cross_modal_listener.py       ← Spatial + audio cross-modal fusion
-├── nima_voice_input.py                ← Speech-to-text (Whisper/Vosk/Google)
-├── nima_voice_output.py               ← Text-to-speech (espeak-ng/pyttsx3)
-├── run_nima_demo.py                   ← Demo script (non-interactive)
-├── requirements.txt                   ← Python dependencies
-└── tools/                             ← Agent tools
-    ├── calculator.py
-    ├── time_now.py
-    ├── text_stats.py
-    └── _registry.json
+User Voice → VoiceInput → AgentBridge → VoiceOutput → Speaker
+    │            │              │              │
+    │            v              v              v
+    │      CrossModal     AgentLayer      AvatarController
+    │      Listener       (tools)          │
+    v            │                          v
+RF Sensors → Vision → AffordanceGraph → ARCompositor
+                   │       (mesh)            │
+                   v                          v
+              AdaptiveMesh               Camera + Nima
+              (green lines)              on screen
+                   │
+                   v
+          RecursiveConsciousnessPipeline
 ```
 
-## Quick Start (2 minutes)
-
-### 1. Install dependencies
+## What's Inside
+
+| Module | Lines | Purpose |
+|--------|-------|---------|
+| `nima_phi.py` | 1,494 | **The orchestrator** — central nervous system / thalamus |
+| `modified consciousness (1).py` | 3,675 | Recursive consciousness pipeline (17 cognitive agents) |
+| `nima_vision_core.py` | 1,238 | Tri-frequency RF sensing (sub-GHz / 2.4GHz / 5GHz) |
+| `nima_adaptive_mesh.py` | ~900 | **The Green Lines** — frequency-agile 3D mesh |
+| `nima_affordance_graph.py` | ~480 | A* pathfinding + affordance navigation |
+| `nima_avatar_renderer.py` | ~660 | Joi-style luminous particle avatar (HTTP/Canvas2D) |
+| `nima_ar_compositor.py` | ~357 | Camera + avatar AR fusion |
+| `nima_agent_bridge.py` | ~520 | Consciousness ↔ tool execution bridge |
+| `nima_agent_layer.py` | ~570 | Tool registry + AST sandbox |
+| `nima_cross_modal_listener.py` | ~400 | Spatial + audio cross-modal fusion |
+| `nima_proprioceptive_friction.py` | ~350 | Body feel / motor noise / startle |
+| `nima_voice_input.py` | ~600 | STT (Whisper / Vosk / Google) |
+| `nima_voice_output.py` | ~600 | TTS (espeak-ng / pyttsx3 / browser) |
+
+## Quick Start
 
 ```bash
-cd nima_phi_system
-pip install -r requirements.txt
+# Clone
+git clone https://huggingface.co/TheNormsOfIntelligence/nima-phi-model
+cd nima-phi-model
 
-# Also install espeak-ng for voice output (Ubuntu/Debian):
-sudo apt install espeak-ng
-# macOS:
-brew install espeak-ng
-# Windows:
-# Download from https://espeak.sourceforge.net/
-```
-
-### 2. Run the demo
+# Install dependencies
+pip install -r requirements.txt
 
-```bash
+# Run the demo (non-interactive, shows all subsystems)
 python run_nima_demo.py
-```
-
-This will:
-- Initialize all 13 modules
-- Run the 5Hz heartbeat loop for 5 seconds
-- Process 3 text queries (time, calculator, greeting)
-- Show the 3D mesh data (green lines)
-- Demonstrate A* pathfinding through the affordance graph
-- Test Nima's movement system
-- Print the full system state
 
-### 3. Run interactive mode
-
-```bash
+# Or run interactive mode (avatar in browser at http://localhost:8888/)
 python nima_phi.py
 ```
 
-This starts the full system with:
-- Avatar HTTP server on http://localhost:8888/ (open in browser!)
-- 10Hz heartbeat loop
-- Interactive text conversation (type messages, Nima responds)
-- Voice I/O if STT/TTS engines are available
-
-### 4. Try it in your own code
+### Try it in your own code
 
 ```python
 from nima_phi import NimaPhi
@@ -80,50 +87,57 @@ from nima_phi import NimaPhi
 nima = NimaPhi()
 nima.initialize()
 
-# Single-turn text processing
+# Process text through the full cognition pipeline
 result = nima.process_text("What time is it?")
 print(result['response_text'])
-# → "It's 3:47 AM on 2026-07-19, Sunday."
 
-# Move Nima through the room
+# Move Nima through the room via the affordance graph
 nima.move_to(3.0, 2.0)
 
-# Get the 3D mesh (green lines)
+# Get the 3D mesh (the green lines)
 mesh = nima.get_mesh_data()
 
-# Get Nima's current neurochemical state
+# Get neurochemical state
 nt = nima.get_neurochemical_state()
 print(f"Dopamine: {nt['dopamine']}, Serotonin: {nt['serotonin']}")
 
-# Get the affordance graph
-path = nima.affordance_graph.find_path((0.5, 0.5, 0.0), (3.5, 3.5, 0.0))
-
 nima.shutdown()
 ```
 
-## Consciousness Pipeline (Full Mode)
+## Consciousness Pipeline
 
-The consciousness module (`modified consciousness (1).py`) requires:
-- `transformers>=4.48,<5.0` (v5.x removed `LossKwargs`)
-- `torch>=2.0`
+The recursive consciousness pipeline runs through 4 phases with 17+ cognitive agents:
 
-If the consciousness pipeline fails to load (wrong transformers version),
-Nima gracefully falls back to **stub mode** — tools, mesh, avatar, and
-everything else still works. You'll see "WITHOUT consciousness" in the logs.
+- **Phase 1 — Subconscious:** Memory + Intuition + Analysis + Common Sense + EI → Qualia synthesis → SBG gating
+- **Phase 2 — Awareness:** 7-level awareness lock-on → Barrett consciousness admission
+- **Phase 3 — Self-Understanding:** Metacognition QC → circuit breaker check → IRS feedback
+- **Phase 4 — Executive:** Adaptability → Problem-Solving (IDEAL) → Creativity (Wallas/Taylor) → Decision-Making → Autonomy
 
-To get the FULL recursive consciousness pipeline with all 17 cognitive agents,
-qualia vectors, and neurochemical modulation:
+**Bio-physical safeguards:** Glutamate Circuit Breaker, Subconscious Bypass Gating (SBG), Zero-Latency Cognitive Buffering (ZLCB)
 
-```bash
-pip install "transformers>=4.48,<5.0" torch
-```
+**Requires:** `transformers>=4.48,<5.0` and `torch>=2.0` for the full pipeline. Without these, Nima gracefully falls back to stub mode (tools, mesh, avatar, and all embodiment modules still work).
 
-Then when you run it, you'll see "RECURSIVE PIPELINE" instead of "STUB"
-and get real-time dopamine/serotonin/cortisol → avatar modulation.
+## The Green Lines (3D Mesh)
 
-## Hardware Tiers
+The adaptive mesh system uses cognitive-radio-inspired frequency agility:
+
+- **Sub-GHz (800–950 MHz):** Sweeps for wall reflections, avoids null zones
+- **2.4 GHz (2412–2484 MHz):** Channel-hops to avoid Wi-Fi congestion
+- **5 GHz (5180–5825 MHz):** Sweeps for best mmWave reflection off surfaces
+
+Each vision frame refines the mesh. Over time, it converges on real room geometry — even from noisy RF data.
+
+## Affordance Graph
+
+A hippocampal cognitive map that enables:
+
+- **A* pathfinding** through the room
+- **Affordance detection** — sit, lie down, jump on, lean on, duck
+- **Wall enforcement** — Nima literally cannot pass through walls
+- **Door passages** — edges through wall boundaries
+- **Furniture interaction** — sit on couch, rest hand on table
 
-The RF vision system auto-detects at runtime:
+## Hardware Tiers
 
 | Tier | Hardware | Resolution | What you get |
 |------|----------|-----------|-------------|
@@ -132,25 +146,26 @@ The RF vision system auto-detects at runtime:
 | 2 | 2x ESP32 | ~10cm | Stereoscopic RF, true 3D |
 | 3 | Tri-freq radios | ~1-5cm | Full 3D with surface classification |
 
-Tier 0 works on any machine — no hardware needed. That's what ran in the demo.
+Tier 0 works on any machine with no hardware needed.
 
-## Architecture
+## Neurobiological Mapping
 
-```
-User Voice → VoiceInput → AgentBridge → VoiceOutput → Speaker
-    │            │              │              │
-    │            v              v              v
-    │      CrossModal     AgentLayer      AvatarController
-    │      Listener       (tools)          │
-    v            │                          v
-RF Sensors → Vision → AffordanceGraph → ARCompositor
-                   │       (mesh)            │
-                   v                          v
-              AdaptiveMesh               Camera + Nima
-              (green lines)              on screen
-                   │
-                   v
-          RecursiveConsciousnessPipeline
-          (Phase 1: subconscious gets mesh data)
-          (Phase 4: autonomy actions → avatar)
-```
+| System | Brain Analogue |
+|--------|---------------|
+| NimaPhi orchestrator | Thalamus (central relay) |
+| Vision (RF fusion) | V1/V2 opponent processing + stereopsis |
+| Affordance graph | Hippocampal place cells + grid cells |
+| Cross-modal listener | Superior colliculus |
+| Proprioception | Parietal body schema |
+| Avatar modulation | Facial nucleus / motor cortex |
+| Consciousness pipeline | Prefrontal cortical column |
+| Main heartbeat loop | Cardiac rhythm / autonomic nervous system |
+| Reflex system | Brainstem reflex arcs |
+
+## License
+
+Apache 2.0
+
+---
+
+*Built by Norman dela Paz Tabora — TheNormsOfIntelligence*