Initial README with project documentation

README.md

@@ -1,12 +1,78 @@
 ---
-title: Limbic Reasoning Agent
-emoji: 📉
-colorFrom: indigo
-colorTo: pink
+title: "🧠 Limbic-Modulated Reasoning Agent"
+emoji: 🧠
+colorFrom: purple
+colorTo: blue
 sdk: gradio
-sdk_version: 6.13.0
+sdk_version: "5.33.0"
 app_file: app.py
 pinned: false
+license: mit
+short_description: "LLM with real-time neuro-behavioral state modulation"
+tags:
+  - psychology
+  - neuroscience
+  - reasoning
+  - limbic-system
+  - emotion
+  - agents
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧠 Limbic-Modulated Reasoning Agent
+
+An LLM whose **reasoning behavior adapts in real-time** based on a simulated neuro-behavioral state engine.
+
+## How It Works
+
+```
+User Message → Limbic Engine → Modulate LLM Parameters → Generate Response
+                  │                    │
+                  ├─ Arousal/Valence   ├─ Temperature (fear↓ seeking↑)
+                  ├─ 4 Affective       ├─ Top-p (fear=tight, seek=wide)
+                  │  Engines           ├─ Behavioral Directive
+                  ├─ Hormones          ├─ Active Instincts
+                  └─ Psychological     └─ Self-Debug Protocol
+                     Lattice
+```
+
+### Core Formulas (from [LIMBIC-system-PACKGE](https://github.com/Xover-Official/LIMBIC-system-PACKGE))
+
+| Formula | Source | Effect |
+|---------|--------|--------|
+| `temp = 1.0 - fear×0.9 + seeking×2.0` | `amygdala.py` | Fear → deterministic, Seeking → creative |
+| `hormone[t+1] = h[t] + (baseline - h[t]) × 0.05` | `endocrine.py` | Hormones decay toward homeostasis |
+| `fear_mod = 1.0 + cortisol - oxytocin×0.5` | `fear.py` | Cortisol amplifies fear, oxytocin dampens |
+| `shadow += 0.1 × suppressed_count` | `lattice.py` | Suppressed drives build up, may "outburst" |
+
+### Agentic Patterns (from [everything-claude-code](https://github.com/affaan-m/everything-claude-code))
+
+- **4-Tier Memory**: Session → Observations → Instincts → State Store
+- **Learned Instincts**: Behavioral patterns activated by limbic state
+- **4-Phase Self-Debug**: Capture → Diagnose → Fix → Report
+
+## Architecture
+
+| Module | Lines | Purpose |
+|--------|-------|---------|
+| `limbic_engine.py` | 480 | Full limbic state machine with 14 formulas |
+| `memory.py` | 332 | 4-tier memory + instincts + self-debugger |
+| `training_plan.py` | 468 | GRPO training recipe + dataset generation |
+| `app.py` | 436 | ZeroGPU Gradio interface |
+
+## Try It
+
+Type messages with different emotional tones and watch the Limbic Dashboard react:
+
+- 😰 **Fear**: "I'm terrified of losing my job" → Low temperature, structured response
+- 🔍 **Seeking**: "Tell me something fascinating about the brain" → High temperature, creative response
+- 💙 **Care**: "How can I help my friend with depression?" → Empathetic, supportive response
+- 😢 **Panic**: "My best friend is moving away forever" → Warm, validating response
+
+## Training Plan
+
+3-stage pipeline to fine-tune a base model:
+1. **SFT Warm-Up**: 5K synthetic conversations (limbic state → response style)
+2. **GRPO Loop Learning**: 2K psychology prompts × 4 reward functions
+3. **Active Learning**: Uncertain predictions → human labels → retrain
+
+See `training_plan.py` for the complete recipe and runnable script.