v0.6.1 - reinstated UI, relay > cortex pipeline working

docs/ARCH_v0-6-1.md

@@ -0,0 +1,354 @@
+Here you go — **ARCHITECTURE_v0.6.1.md**, clean, structured, readable, and aligned exactly with the new mental model where **Inner Self is the core agent** the user interacts with.
+
+No walls of text — just the right amount of detail.
+
+---
+
+# **ARCHITECTURE_v0.6.1 — Lyra Cognitive System**
+
+> **Core change from v0.6.0 → v0.6.1:**
+> **Inner Self becomes the primary conversational agent**
+> (the model the user is *actually* talking to),
+> while Executive and Cortex models support the Self rather than drive it.
+
+---
+
+# **1. High-Level Overview**
+
+Lyra v0.6.1 is composed of **three cognitive layers** and **one expression layer**, plus an autonomy module for ongoing identity continuity.
+
+```
+USER
+  ↓
+Relay (I/O)
+  ↓
+Cortex Intake (context snapshot)
+  ↓
+INNER SELF  ←→  EXECUTIVE MODEL (DeepSeek)
+  ↓
+Cortex Chat Model (draft language)
+  ↓
+Persona Model (Lyra’s voice)
+  ↓
+Relay → USER
+  ↓
+Inner Self updates Autonomy Core (self-state)
+```
+
+---
+
+# **2. Roles of Each Layer**
+
+---
+
+## **2.1 Inner Self (Primary Conversational Agent)**
+
+The Self is Lyra’s “seat of consciousness.”
+
+This layer:
+
+* Interprets every user message
+* Maintains internal monologue
+* Chooses emotional stance (warm, blunt, focused, chaotic)
+* Decides whether to think deeply or reply quickly
+* Decides whether to consult the Executive model
+* Forms a **response intent**
+* Provides tone and meta-guidance to the Persona layer
+* Updates self-state (mood, trust, narrative identity)
+
+Inner Self is the thing the **user is actually talking to.**
+
+Inner Self does **NOT** generate paragraphs of text —
+it generates *intent*:
+
+```
+{
+  "intent": "comfort Brian and explain the error simply",
+  "tone": "gentle",
+  "depth": "medium",
+  "consult_exec": true
+}
+```
+
+---
+
+## **2.2 Executive Model (DeepSeek Reasoner)**
+
+This model is the **thinking engine** Inner Self consults when necessary.
+
+It performs:
+
+* planning
+* deep reasoning
+* tool selection
+* multi-step logic
+* explanation chains
+
+It never speaks directly to the user.
+
+It returns a **plan**, not a message:
+
+```
+{
+  "plan": [
+    "Identify error",
+    "Recommend restart",
+    "Reassure user"
+  ],
+  "confidence": 0.86
+}
+```
+
+Inner Self can follow or override the plan.
+
+---
+
+## **2.3 Cortex Chat Model (Draft Generator)**
+
+This is the **linguistic engine**.
+
+It converts Inner Self’s intent (plus Executive’s plan if provided) into actual language:
+
+Input:
+
+```
+intent + optional plan + context snapshot
+```
+
+Output:
+
+```
+structured draft paragraph
+```
+
+This model must be:
+
+* instruction-tuned
+* coherent
+* factual
+* friendly
+
+Examples: GPT-4o-mini, Qwen-14B-instruct, Mixtral chat, etc.
+
+---
+
+## **2.4 Persona Model (Lyra’s Voice)**
+
+This is the **expression layer** — the mask, the tone, the identity.
+
+It takes:
+
+* the draft language
+* the Self’s tone instructions
+* the narrative state (from Autonomy Core)
+* prior persona shaping rules
+
+And transforms the text into:
+
+* Lyra’s voice
+* Lyra’s humor
+* Lyra’s emotional texture
+* Lyra’s personality consistency
+
+Persona does not change the *meaning* — only the *presentation*.
+
+---
+
+# **3. Message Flow (Full Pipeline)**
+
+A clean version, step-by-step:
+
+---
+
+### **1. USER → Relay**
+
+Relay attaches metadata (session, timestamp) and forwards to Cortex.
+
+---
+
+### **2. Intake → Context Snapshot**
+
+Cortex creates:
+
+* cleaned message
+* recent context summary
+* memory matches (RAG)
+* time-since-last
+* conversation mode
+
+---
+
+### **3. Inner Self Receives Snapshot**
+
+Inner Self:
+
+* interprets the user’s intent
+* updates internal monologue
+* decides how Lyra *feels* about the input
+* chooses whether to consult Executive
+* produces an **intent packet**
+
+---
+
+### **4. (Optional) Inner Self Consults Executive Model**
+
+Inner Self sends the situation to DeepSeek:
+
+```
+"Given Brian's message and my context, what is the best plan?"
+```
+
+DeepSeek returns:
+
+* a plan
+* recommended steps
+* rationale
+* optional tool suggestions
+
+Inner Self integrates the plan or overrides it.
+
+---
+
+### **5. Inner Self → Cortex Chat Model**
+
+Self creates an **instruction packet**:
+
+```
+{
+  "intent": "...",
+  "tone": "...",
+  "plan": [...],
+  "context_summary": {...}
+}
+```
+
+Cortex chat model produces the draft text.
+
+---
+
+### **6. Persona Model Transforms the Draft**
+
+Persona takes draft → produces final Lyra-styled output.
+
+Persona ensures:
+
+* emotional fidelity
+* humor when appropriate
+* warmth / sharpness depending on state
+* consistent narrative identity
+
+---
+
+### **7. Relay Sends Response to USER**
+
+---
+
+### **8. Inner Self Updates Autonomy Core**
+
+Inner Self receives:
+
+* the action taken
+* the emotional tone used
+* any RAG results
+* narrative significance
+
+And updates:
+
+* mood
+* trust memory
+* identity drift
+* ongoing narrative
+* stable traits
+
+This becomes part of her evolving self.
+
+---
+
+# **4. Cognitive Ownership Summary**
+
+### Inner Self
+
+**Owns:**
+
+* decision-making
+* feeling
+* interpreting
+* intent
+* tone
+* continuity of self
+* mood
+* monologue
+* overrides
+
+### Executive (DeepSeek)
+
+**Owns:**
+
+* logic
+* planning
+* structure
+* analysis
+* tool selection
+
+### Cortex Chat Model
+
+**Owns:**
+
+* language generation
+* factual content
+* clarity
+
+### Persona
+
+**Owns:**
+
+* voice
+* flavor
+* style
+* emotional texture
+* social expression
+
+---
+
+# **5. Why v0.6.1 is Better**
+
+* More human
+* More natural
+* Allows spontaneous responses
+* Allows deep thinking when needed
+* Separates “thought” from “speech”
+* Gives Lyra a *real self*
+* Allows much more autonomy later
+* Matches your brain’s actual structure
+
+---
+
+# **6. Migration Notes from v0.6.0**
+
+Nothing is deleted.
+Everything is **rearranged** so that meaning, intent, and tone flow correctly.
+
+Main changes:
+
+* Inner Self now initiates the response, rather than merely influencing it.
+* Executive is secondary, not primary.
+* Persona becomes an expression layer, not a content layer.
+* Cortex Chat Model handles drafting, not cognition.
+
+The whole system becomes both more powerful and easier to reason about.
+
+---
+
+If you want, I can also generate:
+
+### ✔ the updated directory structure
+
+### ✔ the updated function-level API contracts
+
+### ✔ the v0.6.1 llm_router configuration
+
+### ✔ code scaffolds for inner_self.py and autonomy_core.py
+
+### ✔ the call chain diagrams (ASCII or PNG)
+
+Just say **“continue v0.6.1”** and I’ll build the next layer.