@aleph-ai/tinyaleph 1.0.0

package/docs/design/ALEPH_CHAT_ARCHITECTURE.md

@@ -0,0 +1,499 @@
+# AlephChat: Hybrid LLM/TinyAleph Chat Client Design
+
+## Overview
+
+AlephChat is a conversational AI system that combines the neural language generation of a local LLM (via LMStudio) with TinyAleph's deterministic semantic processing. The system transparently learns new vocabulary and adapts to the user's communication style while maintaining semantic coherence through hypercomplex embeddings.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              AlephChat Client                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│   ┌───────────────┐     ┌──────────────────┐     ┌───────────────────┐      │
+│   │  User Input   │────▶│  PromptEnhancer  │────▶│  LMStudio Client  │      │
+│   └───────────────┘     └────────┬─────────┘     └─────────┬─────────┘      │
+│                                  │                         │                 │
+│                                  ▼                         ▼                 │
+│   ┌───────────────────────────────────────────────────────────────────┐     │
+│   │                     AlephSemanticCore                              │     │
+│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────┐  │     │
+│   │  │ Vocabulary  │  │   Style     │  │   Topic     │  │ Concept  │  │     │
+│   │  │  Manager    │  │  Profiler   │  │  Tracker    │  │  Graph   │  │     │
+│   │  └─────────────┘  └─────────────┘  └─────────────┘  └──────────┘  │     │
+│   └───────────────────────────────────────────────────────────────────┘     │
+│                                  │                         │                 │
+│                                  ▼                         ▼                 │
+│   ┌───────────────────────────────────────────────────────────────────┐     │
+│   │                       Context Memory                               │     │
+│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────────┐│     │
+│   │  │  Immediate  │  │   Session   │  │       Persistent            ││     │
+│   │  │   Buffer    │  │   Memory    │  │        Memory               ││     │
+│   │  │  (5-10 msg) │  │  (current)  │  │   (JSON file store)         ││     │
+│   │  └─────────────┘  └─────────────┘  └─────────────────────────────┘│     │
+│   └───────────────────────────────────────────────────────────────────┘     │
+│                                  │                                           │
+│                                  ▼                                           │
+│   ┌───────────────┐     ┌──────────────────┐     ┌───────────────────┐      │
+│   │ LLM Response  │◀────│ResponseProcessor │◀────│  LLM Streaming    │      │
+│   └───────────────┘     └──────────────────┘     └───────────────────┘      │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. AlephSemanticCore
+
+The semantic heart of the system, built on TinyAleph's SemanticBackend:
+
+```javascript
+class AlephSemanticCore {
+    constructor(options) {
+        this.backend = new SemanticBackend({ dimension: options.dimension || 16 });
+        this.vocabulary = new VocabularyManager(this.backend);
+        this.styleProfiler = new StyleProfiler(this.backend);
+        this.topicTracker = new TopicTracker(this.backend);
+        this.conceptGraph = new ConceptGraph(this.backend);
+    }
+}
+```
+
+**Sub-components:**
+
+| Component | Purpose | Key Methods |
+|-----------|---------|-------------|
+| VocabularyManager | Tracks known words, learns new ones with prime encodings | `learn(word)`, `isKnown(word)`, `encode(word)` |
+| StyleProfiler | Builds user's communication style embedding | `updateStyle(text)`, `getStyleVector()`, `matchStyle(response)` |
+| TopicTracker | Tracks current conversation topics via hypercomplex states | `updateTopic(text)`, `getCurrentTopics()`, `getTopicRelevance(text)` |
+| ConceptGraph | Maps relationships between concepts | `addRelation(a, rel, b)`, `query(concept)`, `findRelated(concept)` |
+
+### 2. Context Memory
+
+Multi-tiered memory system for conversation context:
+
+```javascript
+class ContextMemory {
+    constructor(options) {
+        this.immediate = new ImmediateBuffer(options.bufferSize || 10);
+        this.session = new SessionMemory();
+        this.persistent = new PersistentMemory(options.storePath);
+        this.semanticIndex = new SemanticIndex(options.backend);
+    }
+}
+```
+
+**Memory Tiers:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Memory Architecture                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│   IMMEDIATE (in-memory ring buffer)                         │
+│   ├── Last 5-10 exchanges                                   │
+│   ├── Full text + embeddings                                │
+│   └── Used for: Direct context injection                    │
+│                                                              │
+│   SESSION (in-memory map)                                   │
+│   ├── All exchanges this session                            │
+│   ├── Topic summaries                                       │
+│   ├── Learned vocabulary this session                       │
+│   └── Used for: Semantic retrieval, topic continuity        │
+│                                                              │
+│   PERSISTENT (JSON file)                                    │
+│   ├── User style profile                                    │
+│   ├── Learned vocabulary + primes                           │
+│   ├── Concept graph                                         │
+│   ├── Notable conversation snippets                         │
+│   └── Used for: Long-term learning, cross-session memory    │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3. LMStudio Client
+
+Interface to the local LLM via LMStudio's OpenAI-compatible API:
+
+```javascript
+class LMStudioClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl || 'http://localhost:1234/v1';
+        this.model = options.model || 'local-model';
+        this.temperature = options.temperature || 0.7;
+        this.maxTokens = options.maxTokens || 2048;
+    }
+
+    async chat(messages, options) { /* ... */ }
+    async *streamChat(messages, options) { /* ... */ }
+    async listModels() { /* ... */ }
+}
+```
+
+### 4. PromptEnhancer
+
+Enhances user prompts with semantic context before sending to LLM:
+
+```javascript
+class PromptEnhancer {
+    enhance(userInput, context) {
+        return {
+            systemPrompt: this.buildSystemPrompt(context),
+            userPrompt: userInput,
+            contextMessages: this.getRelevantContext(userInput, context),
+            styleHints: this.getStyleHints(context)
+        };
+    }
+}
+```
+
+**Enhancement Process:**
+
+```
+User Input: "Tell me more about neural networks"
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    PromptEnhancer                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. Semantic Analysis                                        │
+│     ├── Encode input to hypercomplex state                  │
+│     ├── Compute topic relevance scores                       │
+│     └── Identify key concepts                                │
+│                                                              │
+│  2. Context Retrieval                                        │
+│     ├── Immediate: Last N relevant exchanges                 │
+│     ├── Session: Semantically similar past discussions       │
+│     └── Persistent: Related concepts from knowledge graph    │
+│                                                              │
+│  3. Style Adaptation                                         │
+│     ├── Match response length preference                     │
+│     ├── Technical level adjustment                           │
+│     └── Tone alignment                                       │
+│                                                              │
+│  4. Prompt Construction                                      │
+│     └── System + Context + User → Enhanced Messages          │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+                    │
+                    ▼
+Enhanced Messages: [
+  { role: "system", content: "You are a helpful assistant..." },
+  { role: "assistant", content: "Previously discussed: ML basics..." },
+  { role: "user", content: "Tell me more about neural networks" }
+]
+```
+
+### 5. ResponseProcessor
+
+Post-processes LLM responses to extract learning opportunities:
+
+```javascript
+class ResponseProcessor {
+    process(response, userInput, context) {
+        // Extract new vocabulary
+        const newWords = this.extractNewVocabulary(response);
+        
+        // Verify semantic coherence
+        const coherence = this.checkCoherence(response, userInput);
+        
+        // Extract concepts for graph
+        const concepts = this.extractConcepts(response);
+        
+        return {
+            response,
+            newWords,
+            coherence,
+            concepts,
+            shouldLearn: coherence.score > 0.6
+        };
+    }
+}
+```
+
+## Data Flow
+
+### Conversation Turn Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Conversation Turn Flow                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  1. USER INPUT                                                               │
+│     │                                                                        │
+│     ▼                                                                        │
+│  2. PRE-PROCESSING                                                           │
+│     ├── Encode to hypercomplex state                                         │
+│     ├── Extract keywords for vocab check                                     │
+│     ├── Compute topic embedding                                              │
+│     └── Check for new vocabulary                                             │
+│     │                                                                        │
+│     ▼                                                                        │
+│  3. CONTEXT RETRIEVAL                                                        │
+│     ├── Get immediate buffer                                                 │
+│     ├── Semantic search session memory                                       │
+│     └── Query concept graph for relevant knowledge                           │
+│     │                                                                        │
+│     ▼                                                                        │
+│  4. PROMPT ENHANCEMENT                                                       │
+│     ├── Build system prompt with style hints                                 │
+│     ├── Inject relevant context                                              │
+│     └── Add semantic grounding                                               │
+│     │                                                                        │
+│     ▼                                                                        │
+│  5. LLM GENERATION                                                           │
+│     ├── Send to LMStudio                                                     │
+│     └── Stream response tokens                                               │
+│     │                                                                        │
+│     ▼                                                                        │
+│  6. POST-PROCESSING                                                          │
+│     ├── Extract new vocabulary                                               │
+│     ├── Verify semantic coherence                                            │
+│     ├── Extract concepts                                                     │
+│     └── Update style profile                                                 │
+│     │                                                                        │
+│     ▼                                                                        │
+│  7. LEARNING                                                                 │
+│     ├── Add new words to vocabulary                                          │
+│     ├── Update topic tracker                                                 │
+│     ├── Update concept graph                                                 │
+│     └── Refine style profile                                                 │
+│     │                                                                        │
+│     ▼                                                                        │
+│  8. MEMORY UPDATE                                                            │
+│     ├── Add exchange to immediate buffer                                     │
+│     ├── Index in session memory                                              │
+│     └── Persist notable learnings                                            │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Transparent Learning
+
+### Vocabulary Learning
+
+The system automatically detects and learns new words:
+
+```javascript
+class VocabularyManager {
+    learn(word) {
+        if (this.isKnown(word)) return;
+        
+        // Generate prime encoding
+        const primes = this.backend.encode(word);
+        
+        // Create hypercomplex embedding
+        const embedding = this.backend.textToOrderedState(word);
+        
+        // Store with metadata
+        this.vocabulary.set(word, {
+            primes,
+            embedding,
+            firstSeen: Date.now(),
+            frequency: 1,
+            contexts: []
+        });
+        
+        console.log(`📚 Learned new word: "${word}"`);
+    }
+}
+```
+
+### Style Profiling
+
+The system builds a profile of the user's communication style:
+
+```javascript
+class StyleProfiler {
+    updateStyle(userText) {
+        const embedding = this.backend.textToOrderedState(userText);
+        
+        // Running average with exponential decay
+        const alpha = 0.1; // Learning rate
+        for (let i = 0; i < this.styleVector.length; i++) {
+            this.styleVector[i] = (1 - alpha) * this.styleVector[i] + alpha * embedding.c[i];
+        }
+        
+        // Update style metrics
+        this.metrics.avgLength = this.updateAvg(this.metrics.avgLength, userText.length);
+        this.metrics.technicalLevel = this.estimateTechnicalLevel(userText);
+        this.metrics.formalityScore = this.estimateFormality(userText);
+    }
+}
+```
+
+### Concept Graph Updates
+
+Extract and store concept relationships:
+
+```javascript
+class ConceptGraph {
+    extractAndStore(text) {
+        const concepts = this.extractConcepts(text);
+        
+        // Create embeddings for each concept
+        for (const concept of concepts) {
+            const embedding = this.backend.textToOrderedState(concept);
+            this.nodes.set(concept, embedding);
+        }
+        
+        // Infer relationships from proximity
+        for (let i = 0; i < concepts.length - 1; i++) {
+            this.addRelation(concepts[i], 'related_to', concepts[i + 1]);
+        }
+    }
+}
+```
+
+## File Structure
+
+```
+aleph-chat/
+├── index.js                 # Main entry point & CLI
+├── lib/
+│   ├── core.js              # AlephSemanticCore
+│   ├── memory.js            # ContextMemory system
+│   ├── lmstudio.js          # LMStudio API client
+│   ├── enhancer.js          # PromptEnhancer
+│   ├── processor.js         # ResponseProcessor
+│   ├── vocabulary.js        # VocabularyManager
+│   ├── style.js             # StyleProfiler
+│   ├── topics.js            # TopicTracker
+│   └── concepts.js          # ConceptGraph
+├── data/
+│   ├── vocabulary.json      # Learned vocabulary
+│   ├── style-profile.json   # User style data
+│   └── concepts.json        # Concept graph
+└── README.md
+```
+
+## Example Usage Session
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AlephChat Session                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  $ npm run chat                                              │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ 🌟 AlephChat v1.0                                       ││
+│  │ Connected to LMStudio: mistral-7b-instruct              ││
+│  │ Vocabulary: 1,247 words | Style: learning               ││
+│  └─────────────────────────────────────────────────────────┘│
+│                                                              │
+│  You: What's the difference between ML and DL?               │
+│       [📚 New term detected: "DL"]                           │
+│       [🎯 Topic: machine learning, deep learning]            │
+│                                                              │
+│  Aleph: Machine Learning (ML) is the broader category...     │
+│         [Coherence: 0.87 | Concepts: +3]                     │
+│                                                              │
+│  You: Can you explain backpropagation?                       │
+│       [🔗 Context: previous ML/DL discussion]                │
+│       [📚 Learning: "backpropagation"]                       │
+│                                                              │
+│  Aleph: Building on our discussion of deep learning,         │
+│         backpropagation is the algorithm that allows...      │
+│         [Coherence: 0.92 | Topics: +neural networks]         │
+│                                                              │
+│  You: /status                                                │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ Session Stats:                                          ││
+│  │   Exchanges: 2                                          ││
+│  │   New words learned: 2 (DL, backpropagation)            ││
+│  │   Topics: ML, DL, neural networks                       ││
+│  │   Style confidence: 43%                                 ││
+│  │   Avg coherence: 0.895                                  ││
+│  └─────────────────────────────────────────────────────────┘│
+│                                                              │
+│  You: /save                                                  │
+│  💾 Session saved to data/                                   │
+│                                                              │
+│  You: /quit                                                  │
+│  👋 Goodbye! Vocabulary updated with 2 new words.            │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Special Commands
+
+| Command | Description |
+|---------|-------------|
+| `/status` | Show session statistics |
+| `/topics` | List current conversation topics |
+| `/vocab` | Show recently learned vocabulary |
+| `/style` | Display user style profile |
+| `/concepts` | Explore concept graph |
+| `/forget <word>` | Remove word from vocabulary |
+| `/save` | Persist current session |
+| `/load` | Load previous session |
+| `/clear` | Clear immediate context |
+| `/quit` | Exit and save |
+
+## Configuration
+
+```javascript
+// aleph-chat.config.js
+module.exports = {
+    lmstudio: {
+        baseUrl: 'http://localhost:1234/v1',
+        model: 'local-model',
+        temperature: 0.7,
+        maxTokens: 2048
+    },
+    aleph: {
+        dimension: 16,
+        learningRate: 0.1,
+        coherenceThreshold: 0.6
+    },
+    memory: {
+        immediateSize: 10,
+        sessionLimit: 100,
+        persistPath: './data'
+    },
+    ui: {
+        showCoherence: true,
+        showTopics: true,
+        showLearning: true,
+        colorOutput: true
+    }
+};
+```
+
+## Key Design Principles
+
+1. **Semantic Grounding** - All text is encoded to hypercomplex space via TinyAleph's prime-based encoding, providing deterministic semantic signatures
+
+2. **Transparent Learning** - The system visibly learns new vocabulary and style preferences, building a persistent profile over time
+
+3. **Multi-Tier Memory** - Immediate buffer for context injection, session memory for semantic search, persistent storage for cross-session continuity
+
+4. **Hybrid Architecture** - Combines TinyAleph's symbolic/mathematical processing with LLM's neural generation for enhanced coherence
+
+5. **Local-First** - Uses LMStudio for on-device inference, keeping conversations private and enabling offline operation
+
+## Implementation Priorities
+
+1. **Phase 1**: Core infrastructure
+   - LMStudio client with streaming
+   - Basic AlephSemanticCore
+   - Immediate context buffer
+
+2. **Phase 2**: Learning systems
+   - VocabularyManager
+   - StyleProfiler
+   - Session memory
+
+3. **Phase 3**: Advanced features
+   - ConceptGraph
+   - Persistent storage
+   - Semantic search
+
+4. **Phase 4**: Polish
+   - Rich CLI interface
+   - Commands and status
+   - Error handling