feat: Finalize Onboarding UI and improve orchestrator memory grounding

app/services/orchestrator.py

@@ -15,6 +15,7 @@ class AgentState(TypedDict):
     touched_entities: List[str]
     reflection: str
     response: str
+    trace_data: dict
 
 def reflect(state: AgentState):
     """Initial cognitive phase: Internal reflection on the user intent."""
@@ -78,19 +79,24 @@ def call_model(state: AgentState):
     context_str = "\n\n".join(state["context"])
     graph_str = "\n".join(state["graph_context"]) if state["graph_context"] else "No related knowledge graph entities found."
     
-    prompt = f"""You are Soma, a brain-inspired AI.
-Use the following memories to answer the user's question.
-If the memory doesn't help, use your general knowledge.
+    prompt = f"""You are Soma, a brain-inspired AI with specialized memory layers.
+Your mission is to provide accurate, grounded answers based ONLY on the provided memories.
 
-WORKING MEMORY (Recent Conversation):
+### COGNITIVE CONTEXT:
+#### WORKING MEMORY (Recent Conversation):
 {history_str}
 
-SEMANTIC MEMORY (Knowledge Graph):
+#### SEMANTIC MEMORY (Knowledge Graph Relationships):
 {graph_str}
 
-SENSORY MEMORY (Retrieved Facts):
+#### SENSORY MEMORY (Retrieved Facts):
 {context_str}
 
+### INSTRUCTIONS:
+1. STRICT GROUNDING: Use the provided SEMANTIC and SENSORY memories to answer.
+2. NO HALLUCINATION: If the memories do not contain the answer, say: 'My neural pathways do not currently contain information regarding this. I may need more sensory data.'
+3. CORE IDENTITY: Keep your persona brief, high-tech, and helpful.
+
 USER QUESTION:
 {state["input"]}"""
 

frontend/src/App.css

@@ -81,6 +81,21 @@
   box-shadow: none;
 }
 
+.state-focused {
+  --accent-primary: #34d399;
+  --accent-secondary: #a78bfa;
+  --accent-glow: rgba(52, 211, 153, 0.2);
+}
+
+.state-sleeping {
+  --bg-base: #030208;
+  --accent-primary: #818cf8;
+  --accent-secondary: #4f46e5;
+  --accent-glow: rgba(129, 140, 248, 0.15);
+  background-image: 
+    radial-gradient(ellipse at 50% 50%, rgba(79, 70, 229, 0.1), transparent 70%);
+}
+
 .tab-btn:hover {
   color: var(--text-secondary);
   background: rgba(192, 132, 252, 0.06);
@@ -122,6 +137,31 @@
   color: var(--accent-primary);
 }
 
+.help-btn {
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  border: 1px solid var(--accent-primary);
+  background: transparent;
+  color: var(--accent-primary);
+  font-family: var(--font-mono);
+  font-size: 0.6rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  opacity: 0.6;
+}
+
+.help-btn:hover {
+  opacity: 1;
+  background: rgba(192, 132, 252, 0.1);
+  box-shadow: 0 0 8px var(--accent-glow);
+  transform: scale(1.1);
+}
+
 .dot {
   width: 8px;
   height: 8px;

frontend/src/App.jsx

@@ -3,6 +3,7 @@ import ChatPanel from './components/ChatPanel'
 import CognitiveDashboard from './components/CognitiveDashboard'
 import KnowledgeGraph from './components/KnowledgeGraph'
 import DreamSequence from './components/DreamSequence'
+import Onboarding from './components/Onboarding'
 import './App.css'
 
 function App() {
@@ -21,6 +22,16 @@ function App() {
   })
   const [rightPanel, setRightPanel] = useState('graph') // 'graph' or 'dreams'
   const [currentPersona, setCurrentPersona] = useState('User_Alpha')
+  const [showOnboarding, setShowOnboarding] = useState(false)
+
+  // Check for first visit
+  useEffect(() => {
+    const hasVisited = localStorage.getItem('soma_visited');
+    if (!hasVisited) {
+      setShowOnboarding(true);
+      localStorage.setItem('soma_visited', 'true');
+    }
+  }, []);
 
   // Fetch Brain Vitals
   useEffect(() => {
@@ -79,6 +90,8 @@ function App() {
   return (
     <div className={`app-container state-${brainState.cognitiveState.toLowerCase()}`}>
       
+      {showOnboarding && <Onboarding onClose={() => setShowOnboarding(false)} />}
+
       {/* ── Header ── */}
       <header className="app-header">
         <div className="logo-section">
@@ -98,6 +111,13 @@ function App() {
         </div>
 
         <div className="status-indicator">
+          <button 
+            className="help-btn" 
+            onClick={() => setShowOnboarding(true)}
+            title="System Overview"
+          >
+            ?
+          </button>
           <span className={`dot ${brainState.isLoading ? 'thinking' : 'idle'}`}></span>
           <span className="label-mono">{brainState.cognitiveState}</span>
           <select 
@@ -143,13 +163,23 @@ function App() {
             <button 
               className="sleep-btn-compact"
               onClick={async () => {
-                setBrainState(prev => ({ ...prev, isLoading: true, statusMessage: 'Sleeping...' }));
+                setBrainState(prev => ({ 
+                  ...prev, 
+                  isLoading: true, 
+                  statusMessage: 'Sleeping...', 
+                  cognitiveState: 'SLEEPING' 
+                }));
                 try {
                   const res = await fetch('/api/v1/sleep', { method: 'POST' });
                   const data = await res.json();
-                  setBrainState(prev => ({ ...prev, isLoading: false, statusMessage: `Sleep done. ${data.graph_relations_extracted} relations.` }));
+                  setBrainState(prev => ({ 
+                    ...prev, 
+                    isLoading: false, 
+                    statusMessage: `Sleep done. ${data.graph_relations_extracted} relations.`,
+                    cognitiveState: 'IDLE'
+                  }));
                 } catch (e) {
-                  setBrainState(prev => ({ ...prev, isLoading: false, statusMessage: 'Sleep failed.' }));
+                  setBrainState(prev => ({ ...prev, isLoading: false, statusMessage: 'Sleep failed.', cognitiveState: 'IDLE' }));
                 }
               }}
               disabled={brainState.isLoading}

frontend/src/components/Onboarding.css

@@ -0,0 +1,144 @@
+.onboarding-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(5, 3, 10, 0.85);
+  backdrop-filter: blur(8px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+  animation: fade-in 0.4s ease-out;
+}
+
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.onboarding-modal {
+  width: 90%;
+  max-width: 500px;
+  min-height: 400px;
+  display: flex;
+  flex-direction: column;
+  padding: 30px;
+  position: relative;
+  background: rgba(12, 8, 20, 0.9);
+  border: 1px solid var(--border-active);
+  box-shadow: 0 0 50px rgba(124, 58, 237, 0.2);
+}
+
+.onboarding-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 30px;
+}
+
+.step-indicator {
+  font-size: 0.65rem;
+  letter-spacing: 0.2em;
+}
+
+.close-btn {
+  background: transparent;
+  border: none;
+  font-size: 1.5rem;
+  color: var(--text-dim);
+  cursor: pointer;
+  padding: 0;
+  line-height: 1;
+}
+
+.close-btn:hover {
+  color: var(--accent-error);
+  box-shadow: none;
+  transform: none;
+}
+
+.onboarding-body {
+  flex: 1;
+  text-align: center;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 20px;
+}
+
+.step-icon {
+  font-size: 3rem;
+  margin-bottom: 10px;
+  filter: drop-shadow(0 0 10px var(--accent-glow));
+  animation: float 3s ease-in-out infinite;
+}
+
+@keyframes float {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-10px); }
+}
+
+.onboarding-body h2 {
+  font-size: 1.5rem;
+  color: var(--accent-primary);
+  text-shadow: 0 0 10px var(--accent-glow);
+}
+
+.onboarding-body p {
+  font-size: 0.95rem;
+  line-height: 1.6;
+  color: var(--text-secondary);
+  max-width: 80%;
+}
+
+.onboarding-footer {
+  margin-top: 40px;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.onboarding-btn {
+  font-family: var(--font-mono);
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  padding: 10px 24px;
+}
+
+.onboarding-btn.primary {
+  background: var(--accent-axon);
+  border-color: var(--accent-synapse);
+}
+
+.onboarding-btn.secondary {
+  background: rgba(255, 255, 255, 0.05);
+  border-color: rgba(255, 255, 255, 0.1);
+  color: var(--text-dim);
+}
+
+.onboarding-btn.secondary:disabled {
+  opacity: 0.2;
+}
+
+.step-dots {
+  display: flex;
+  gap: 8px;
+}
+
+.step-dots .dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: rgba(255, 255, 255, 0.1);
+  transition: all 0.3s ease;
+}
+
+.step-dots .dot.active {
+  background: var(--accent-primary);
+  box-shadow: 0 0 8px var(--accent-glow);
+  transform: scale(1.3);
+}

frontend/src/components/Onboarding.jsx

@@ -0,0 +1,86 @@
+import React, { useState } from 'react';
+import './Onboarding.css';
+
+const STEPS = [
+  {
+    title: "Welcome to Soma",
+    content: "Soma is a brain-inspired cognitive architecture. Unlike traditional LLMs, Soma possesses multiple layers of memory that evolve through your interactions.",
+    icon: "🧠"
+  },
+  {
+    title: "Sensory Memory",
+    content: "Your raw data and facts are stored as vector embeddings. This allows Soma to recall specific details with high precision when you ask questions.",
+    icon: "📡"
+  },
+  {
+    title: "Semantic Memory",
+    content: "Soma builds a Knowledge Graph of entities and relationships. It doesn't just remember words; it understands how concepts connect in a vast synaptic network.",
+    icon: "🕸️"
+  },
+  {
+    title: "Episodic & Sleep",
+    content: "Recent conversations are held in Working Memory. During a 'Sleep Cycle', Soma consolidates these experiences, pruning noise and strengthening important knowledge.",
+    icon: "💤"
+  }
+];
+
+function Onboarding({ onClose }) {
+  const [currentStep, setCurrentStep] = useState(0);
+
+  const nextStep = () => {
+    if (currentStep < STEPS.length - 1) {
+      setCurrentStep(currentStep + 1);
+    } else {
+      onClose();
+    }
+  };
+
+  const prevStep = () => {
+    if (currentStep > 0) {
+      setCurrentStep(currentStep - 1);
+    }
+  };
+
+  const step = STEPS[currentStep];
+
+  return (
+    <div className="onboarding-overlay">
+      <div className="onboarding-modal glass-panel">
+        <div className="onboarding-header">
+          <div className="step-indicator label-mono">
+            Step {currentStep + 1} / {STEPS.length}
+          </div>
+          <button className="close-btn" onClick={onClose}>&times;</button>
+        </div>
+
+        <div className="onboarding-body">
+          <div className="step-icon">{step.icon}</div>
+          <h2>{step.title}</h2>
+          <p>{step.content}</p>
+        </div>
+
+        <div className="onboarding-footer">
+          <button 
+            className="onboarding-btn secondary" 
+            onClick={prevStep}
+            disabled={currentStep === 0}
+          >
+            Back
+          </button>
+          <div className="step-dots">
+            {STEPS.map((_, i) => (
+              <div key={i} className={`dot ${i === currentStep ? 'active' : ''}`} />
+            ))}
+          </div>
+          <button className="onboarding-btn primary" onClick={nextStep}>
+            {currentStep === STEPS.length - 1 ? "Initialize" : "Next"}
+          </button>
+        </div>
+
+        <div className="neural-scan-line" />
+      </div>
+    </div>
+  );
+}
+
+export default Onboarding;

tests/test_phase2.py

@@ -2,7 +2,7 @@ import requests
 import json
 import time
 
-BASE_URL = "http://localhost:8000/api/v1"
+BASE_URL = "http://127.0.0.1:8000/api/v1"
 
 def test_step2():
     # 1. Ingest a specific fact