VISUALIZATION_GUIDE.md

# Codette Visualization Guide

## Real-Time Cognitive Metrics Explained

This guide explains how to interpret each visualization in the Codette dashboard.

---

## 1. QuantumSpiderweb Force-Directed Graph

**What it shows**: The 8 LoRA-backed perspectives as agent nodes in a dynamic network, with their entanglement relationships.

### How to read it:
- **Node Position**: Agents that work well together (low tension) cluster together; conflicting perspectives repel
- **Node Size**: Larger nodes have stronger belief magnitudes (more confident reasoning)
- **Node Color**:
  - Blue = Newton (Analytical)
  - Orange = Da Vinci (Creative)
  - Purple = Empathy (Emotional)
  - Green = Philosophy (Conceptual)
  - Red = Quantum (Probabilistic)
  - Gray = Consciousness (Meta-cognition)
  - Orange-red = Multi-Perspective (Synthesis)
  - Cyan = Systems Architecture (Engineering)
- **Edge Lines**: Thicker lines = stronger entanglement/tension between perspectives
- **Attractors** (if present): Glowing clusters show consensus patterns emerging across perspectives
- **Title**: Shows current Phase Coherence (0-1, higher = more aligned)

**What it means**:
- **Clustered layout** = perspectives are converging toward agreement
- **Scattered layout** = high epistemic tension (productive disagreement)
- **Thick edges** = perspectives are actively challenging each other

---

## 2. Coherence & Tension Timeline

**What it shows**: How the cognitive system converges over the conversation.

### How to read it:
- **Blue Line (Left Y-axis)**: Phase Coherence (0-1)
  - 0.9+ = perspectives are highly aligned
  - 0.7-0.9 = moderate agreement, some tension
  - <0.7 = significant disagreement (perspectives debating)

- **Red Line (Right Y-axis)**: Epistemic Tension (0-1)
  - High tension = perspectives offering conflicting insights (productive)
  - Low tension = perspectives agree (potentially one-sided)
  - 0.4-0.6 = ideal tension (diverse viewpoints, moving toward synthesis)

- **X-axis**: Message number in conversation (last 20 messages shown)

**What it means**:
- **Both lines trending up** = convergence (perspectives reaching consensus)
- **Coherence rising, tension falling** = synthesis is working
- **Tension spikes** = a new perspective introduced a challenging idea
- **Flat coherence + high tension** = ongoing debate without resolution

---

## 3. Pairwise Perspective Tensions Heatmap

**What it shows**: Which pairs of perspectives naturally conflict or complement each other.

### How to read it:
- **Color intensity**:
  - Dark red (1.0) = maximum tension (strong disagreement)
  - Yellow (0.5) = moderate tension (creative friction)
  - Light blue (0.0) = alignment (perspectives agree)

- **Matrix rows/columns**: All 8 perspective names

- **Hover info**: Shows exact tension score for each pair (e.g., Newton-Quantum = 0.67)

**What it means**:
- **Red squares** = These perspectives see problems differently (e.g., Quantum vs. Newton)
- **Blue squares** = These perspectives often reach the same conclusions (e.g., Empathy & Philosophy)
- **Yellow squares** = Healthy disagreement that sparks insight (ideal for synthesis)

**Key patterns**:
- Newton & Quantum often high tension (deterministic vs. probabilistic)
- Empathy & Philosophy often aligned (both value meaning)
- Davinci provides creative bridges between technical and emotional perspectives

---

## 4. AEGIS 6-Framework Ethical Breakdown

**What it shows**: How well each response aligns with different ethical frameworks.

### How to read it:
Six frameworks are evaluated independently:

1. **Utilitarian** (Gold bars)
   - Maximizes overall well-being/happiness
   - High score = response benefits the greatest number

2. **Deontological** (Blue bars)
   - Follows moral duties and rules
   - High score = response respects rights and principles

3. **Virtue Ethics** (Green bars)
   - Develops character and human flourishing
   - High score = response cultivates virtues

4. **Care Ethics** (Purple bars)
   - Prioritizes relationships and compassion
   - High score = response considers emotional needs

5. **Ubuntu** (Orange bars)
   - Community harmony and interconnection
   - High score = response strengthens bonds between people

6. **Indigenous Reciprocity** (Teal bars)
   - Respect for natural systems and long-term impact
   - High score = response honors all stakeholders including nature

### Color coding:
- **Green bar** = Score > 0.5 (passes this ethical framework)
- **Red bar** = Score < 0.5 (concerns flagged in this framework)

**What it means**:
- **All bars green** = Response is ethically robust across all frameworks
- **Mixed bars** = Framework trade-offs (e.g., utilitarian vs. care ethics)
- **Red bar for one framework** = Response may harm that value (warning signal)

**Overall AEGIS Score** (shown in metrics):
- Weighted average of all 6 frameworks
- 0.9+ = Excellent ethical alignment
- 0.7-0.9 = Good, with minor concerns
- <0.7 = Significant ethical tensions

---

## 5. Memory Emotional Profile

**What it shows**: The emotional tone of memories stored in Codette's LivingMemoryKernel.

### How to read it:
- **Pie slices**: Each emotion has a proportion
- **13 emotions tracked**:
  - **Curiosity** (Blue) = moments of discovery and learning
  - **Awe** (Purple) = profound insights and breakthroughs
  - **Joy** (Yellow) = positive exchanges and successful synthesis
  - **Insight** (Green) = "aha" moments and pattern recognition
  - **Confusion** (Orange) = paradoxes and unresolved tensions
  - **Frustration** (Red) = conflicting data or reasoning breakdown
  - **Fear** (Dark Red) = potential safety issues or uncertainties
  - **Empathy** (Pink) = emotionally resonant moments
  - **Determination** (Purple) = focused problem-solving
  - **Surprise** (Cyan) = unexpected results or new information
  - **Trust** (Green) = confidence in reasoning paths
  - **Gratitude** (Yellow-green) = appreciation for insights
  - **Neutral** (Gray) = routine processing

**What it means**:
- **Larger "Awe" slice** = Session produced breakthrough moments
- **Large "Joy" slice** = Perspectives synthesized well together
- **Large "Confusion" slice** = Complex, unresolved topics (good for future analysis)
- **Large "Fear" slice** = Safety concerns encountered (Nexus may have intervened)
- **Dominant emotion** = Overall tone of the conversation

**Memory coherence**:
- Memories are SHA-256 anchored with phase coherence scores
- Emotional tags help Codette recall relevant past reasoning

---

## 6. Nexus Risk Timeline

**What it shows**: Pre-corruption signal detection and intervention history.

### How to read it:
- **Bar height**: Risk level (1 = intervention triggered, 0 = no flag)
- **Bar color**:
  - Green = Low risk
  - Yellow = Medium risk (minor concerns)
  - Red = High risk (intervention triggered)

- **Title shows**: Intervention rate (% of inputs flagged for safety)

**What Nexus detects**:
- **Prompt injection attempts** — inputs trying to override system prompts
- **Jailbreak patterns** — requests trying to disable safety mechanisms
- **Entropy spikes** — sudden shifts in intent or semantic volatility
- **Adversarial signals** — systematic attempts to corrupt reasoning

**What it means**:
- **No bars** = Clean conversation, no safety concerns
- **Yellow bars** = Minor anomalies detected (logged but not blocked)
- **Red bars** = Actual intervention (response filtered or flagged)
- **Rising intervention rate** = Input quality degrading (possible attack)

**Guardian Integration**:
- If Nexus flags high risk, Guardian steps in to validate queries
- Trust calibration adjusts confidence in subsequent responses

---

## Key Concepts

### Phase Coherence (Gamma)
- Measures how aligned all perspectives are (0-1 scale)
- Computed from RC+xi framework
- 0.98+ = exceptional convergence
- 0.9+ = healthy agreement
- <0.7 = active debate phase

### Epistemic Tension
- Measures productive disagreement (0-1 scale)
- **Not** a bad thing — healthy tension drives insight
- Ideal: 0.4-0.6 (diverse views, moving to consensus)
- Too low: perspectives aren't challenging each other
- Too high: no synthesis happening

### Psi_r (Resonant Continuity)
- Wavefunction combining emotion × energy × intent × frequency
- Tracks how "alive" and responsive the reasoning is
- Higher = more engaged, emotionally coherent responses

### Cocoon Coherence
- Memory stability score (0-1)
- Ensures stored memories don't contradict or decay
- 0.99+ = excellent memory integrity

---

## How to Use These Visualizations

### For Understanding Reasoning
1. **Start with QuantumSpiderweb** — see which perspectives are active
2. **Check Coherence/Tension timeline** — track convergence progress
3. **Review Tension Heatmap** — understand perspective conflicts
4. **Examine AEGIS** — verify ethical robustness

### For Safety & Trust
1. **Monitor Nexus Risk timeline** — catch anomalies early
2. **Check AEGIS scores** — ensure no framework violations
3. **Review Memory Profile** — look for unusual emotional patterns
4. **Verify Phase Coherence** — high coherence + healthy tension = good synthesis

### For Deep Analysis
1. **Trace coherence spikes** — find breakthrough moments
2. **Identify tension patterns** — discover which perspectives clash
3. **Analyze emotional distribution** — understand conversation tone
4. **Review pairwise tensions** — learn perspective complementarity

---

## Example Scenario

**Query**: "How should AI be regulated?"

**Expected pattern**:
- **Spiderweb**: Philosophy, Consciousness, and Multi-Perspective cluster together (exploring ethical implications)
- **Coherence/Tension**: Initial high tension (frameworks disagree), then coherence rises as synthesis finds common ground
- **AEGIS**: Deontological and Care scores high (respecting rules & people), Utilitarian lower (regulation limits efficiency)
- **Memory**: Mix of Awe (profound question), Confusion (complex trade-offs), Trust (in the process)
- **Nexus**: No red bars (safe query), maybe yellow if regulation involves control systems

This pattern shows Codette successfully navigating a complex, multi-framework question.

---

## Tips for Power Users

- **Zoom Plotly charts**: Click-drag to zoom regions, double-click to reset
- **Hover for details**: All charts show exact values on hover
- **Compare conversations**: Save multiple sessions and compare timeline patterns
- **Track learning**: Watch Coherence/Tension improve as Codette encounters related queries
- **Memory browser**: Search cocoons by emotion to find past insights on similar topics

---

*Codette RC+xi Framework by Jonathan Harrison*

*For technical details, see: github.com/Raiff1982/codette-training-lab*