SAM Architecture

graph TB
    subgraph "User Interface Layer"
        UI[SwiftUI User Interface<br/>ChatWidget, Preferences, Help]
    end

    subgraph "Conversation Management"
        CM[ConversationManager<br/>Lifecycle, Persistence, State]
        Topics[Shared Topics<br/>Cross-Conversation Memory]
    end

    subgraph "Voice Framework"
        VoiceMgr[VoiceManager<br/>TTS, Wake Word, Speech Input]
        AudioMgr[AudioDeviceManager<br/>Device Selection]
    end

    subgraph "API Framework"
        EO[EndpointManager<br/>RESTful API Server]
        AO[AgentOrchestrator<br/>Request Processing]
    end

    subgraph "Provider Layer"
        OpenAI[OpenAI Provider<br/>GPT-4, GPT-3.5]
        Copilot[GitHub Copilot<br/>GPT-4, o1]
        Anthropic[Anthropic<br/>Claude 3.5]
        Gemini[Google Gemini]
        Local[Local Models<br/>MLX, GGUF]
        ALICE[ALICE Provider<br/>Remote Stable Diffusion]
    end

    subgraph "MCP Tool Execution"
        Think[think]
        FileOps[file_operations]
        Terminal[terminal_operations]
        Memory[memory_operations]
        Web[web_operations]
        Docs[document_operations]
        Build[build_and_version_control]
        Subagent[run_subagent]
    end

    subgraph "Memory & Intelligence"
        VectorRAG[Vector RAG<br/>Semantic Search]
        YaRN[YaRN Context Processor<br/>Dynamic Scaling]
        MemDB[(SQLite Memory<br/>Conversation/Topic Scoped)]
    end

    UI -->|User Input| CM
    UI -->|Voice Input| VoiceMgr
    VoiceMgr -->|Transcribed Text| CM
    AO -->|Stream Response| VoiceMgr
    VoiceMgr -->|Use Settings| AudioMgr
    CM -->|Manage State| Topics
    CM -->|Process| AO
    AO -->|Select Provider| OpenAI
    AO -->|Select Provider| Copilot
    AO -->|Select Provider| Anthropic
    AO -->|Select Provider| Gemini
    AO -->|Select Provider| Local
    OpenAI -->|Request Tools| Think
    OpenAI -->|Request Tools| FileOps
    OpenAI -->|Request Tools| Terminal
    OpenAI -->|Request Tools| Memory
    OpenAI -->|Request Tools| Web
    OpenAI -->|Request Tools| Docs
    OpenAI -->|Request Tools| Build
    OpenAI -->|Request Tools| Subagent
    Memory -->|Store/Retrieve| VectorRAG
    VectorRAG -->|Persist| MemDB
    AO -->|Context Processing| YaRN
    YaRN -->|Enhanced Context| VectorRAG
    Topics -->|Shared Memory| MemDB
    Subagent -->|Create New| AO
    AO -->|Stream Response| CM
    CM -->|Display| UI
    EO -->|HTTP API| AO

@Published public var conversations: [ConversationModel]
@Published public var activeConversation: ConversationModel?
public let memoryManager = MemoryManager()
public let vectorRAGService: VectorRAGService
public let yarnContextProcessor: YaRNContextProcessor

~/Library/Application Support/SAM/conversations/
├── {UUID}/
│   ├── conversation.json    # Single conversation data
│   ├── tasks.json           # Agent todo list
│   └── .vectorrag/          # Conversation-scoped RAG
├── active-conversation.json
└── backups/

classDiagram
    class MessageBus {
        +messages: [EnhancedMessage]
        -messageCache: [UUID: Int]
        +addUserMessage() UUID
        +addAssistantMessage() UUID
        +updateStreamingMessage(id, content)
        +completeStreamingMessage(id)
        -scheduleSave()
        -notifyConversationOfChanges()
    }

    class ConversationModel {
        +messages: [EnhancedMessage]
        +messageBus: MessageBus?
        +syncMessagesFromMessageBus()
    }

    class ChatWidget {
        +observes messages
        +displays real-time updates
    }

    MessageBus --> ConversationModel : syncs to
    ConversationModel --> ChatWidget : observes

1. Receive user message
2. Add to context
3. Call LLM with available tools
4. Parse tool calls
5. Execute tools
6. Inject results
7. Continue until completion or iteration limit

func storeMemory(content: String, conversationId: UUID, ...)
func retrieveRelevantMemories(for query: String, ...)
func searchAllConversations(query: String, ...)

Document Input
    ↓
DocumentChunker (semantic chunking)
    ↓
EmbeddingGenerator (512-d vectors via Apple NaturalLanguage)
    ↓
MemoryManager (SQLite storage with vectors)
    ↓
Semantic Search (cosine similarity)
    ↓
Ranked Results

func chunkDocument(_ document: RAGDocument) -> [DocumentChunk]
func generateEmbedding(for text: String) -> [Double]
func semanticSearch(query: String, threshold: Double) -> [Result]

public static let `default` = YaRNConfig(
    baseContextLength: 8192,
    extendedContextLength: 32768,
    scalingFactor: 4.0,
    attentionFactor: 0.1,
    compressionThreshold: 0.8
)

public static let mega = YaRNConfig(
    baseContextLength: 65536,
    extendedContextLength: 134217728, // 128M
    scalingFactor: 2048.0,
    attentionFactor: 0.001,
    compressionThreshold: 0.95
)

1. Analyze message importance
2. Identify preservation candidates
3. Apply semantic clustering
4. Calculate compression targets
5. Generate compressed context
6. Archive rolled-off messages to ContextArchiveManager
7. Cache result

Active Context (Fits model window)
    ↓ YaRN Compression
Rolled-Off Messages
    ↓
ContextArchiveManager (SQLite)
    ↓
recall_history Tool (MCP)
    ↓
Agent retrieves archived context on demand

Topic Storage (SQLite shared-data.db)
    ↓
Topic Metadata (id, name, description)
    ↓
Workspace Directory (~/SAM/{topic-name}/)
    ↓
Effective Scope Resolution
    ↓
Memory/File/Terminal Operations

let effectiveScopeId = if sharedTopicEnabled {
    topic.id
} else {
    conversation.id
}

public protocol MCPTool {
    var name: String { get }
    var description: String { get }
    var parameters: [String: MCPToolParameter] { get }

    func execute(parameters: [String: Any], context: MCPExecutionContext) async -> MCPToolResult
}

public protocol ConsolidatedMCP: MCPTool {
    var supportedOperations: [String] { get }
    func route(operation: String, params: [String: Any], context: MCPExecutionContext) async -> MCPToolResult
}

sequenceDiagram
    participant User
    participant ChatWidget
    participant ConversationManager
    participant AgentOrchestrator
    participant LLM as AI Provider
    participant MCPManager
    participant Tool as MCP Tool
    participant System

    User->>ChatWidget: Send message
    ChatWidget->>ConversationManager: Process message
    ConversationManager->>AgentOrchestrator: Orchestrate request
    AgentOrchestrator->>LLM: Send with tool schemas

    loop Tool Execution Loop
        LLM->>MCPManager: Request tool call
        MCPManager->>Tool: Route to specific tool
        Tool->>System: Execute operation
        System->>Tool: Return result
        Tool->>MCPManager: MCPToolResult
        MCPManager->>LLM: Inject result into context

        alt More iterations needed
            LLM->>MCPManager: Request another tool
        else Task complete
            LLM->>AgentOrchestrator: Final response
        end
    end

    AgentOrchestrator->>ConversationManager: Stream response
    ConversationManager->>ChatWidget: Update UI
    ChatWidget->>User: Display response

POST /api/chat/completions
POST /api/chat/autonomous
GET  /api/models
GET  /v1/conversations
POST /v1/conversations
GET  /v1/conversations/{id}

func streamResponse() -> AsyncThrowingStream<ChatResponseChunk, Error> {
    AsyncThrowingStream { continuation in
        // Stream chunks as they arrive
        continuation.yield(chunk)
        continuation.finish()
    }
}

graph TB
    Client[API Client<br/>HTTP POST]
    Router[EndpointManager<br/>Route Handler]
    Validate[Request Validation<br/>Check conversationId]
    Check{Has conversationId?}
    LoadConv[Load Existing<br/>Conversation + Memory]
    NewConv[Create New<br/>Conversation]
    Orchestrator[AgentOrchestrator<br/>Process Request]
    Tools[Tool Execution Loop<br/>MCP Tools]
    StreamCheck{Streaming?}
    SSE[Server-Sent Events<br/>data: &#123;...&#125;]
    JSON[JSON Response<br/>&#123;...&#125;]

    Client -->|POST /api/chat/completions| Router
    Router --> Validate
    Validate --> Check
    Check -->|Yes| LoadConv
    Check -->|No| NewConv
    LoadConv -->|With context| Orchestrator
    NewConv -->|No context| Orchestrator
    Orchestrator -->|Execute| Tools
    Tools -->|Results| Orchestrator
    Orchestrator --> StreamCheck
    StreamCheck -->|stream=true| SSE
    StreamCheck -->|stream=false| JSON
    SSE -->|Stream chunks| Client
    JSON -->|Complete response| Client

User Input
    ↓
ChatWidget (UI)
    ↓
ConversationManager.addMessage()
    ↓
Persistence (debounced)
    ↓
EndpointManager.processMessage()
    ↓
AgentOrchestrator.executeAutonomousWorkflow()
    ↓
LLM API Call (streaming)
    ↓
Tool Execution (if needed)
    ↓
Response Assembly
    ↓
UI Update

Content to Store
    ↓
MemoryManager.storeMemory()
    ↓
EmbeddingGenerator.generate()
    ↓
SQLite INSERT with vector
    ↓
Tags + Metadata
    ↓
Success

Search Query
    ↓
EmbeddingGenerator.generate()
    ↓
SQLite Vector Search (cosine similarity)
    ↓
Filter by threshold
    ↓
Rank by similarity
    ↓
Return top N results

File Drop/Selection
    ↓
DocumentImportSystem
    ↓
Format Detection (PDF, DOCX, etc.)
    ↓
Text Extraction
    ↓
Page-Aware Chunking
    ↓
VectorRAGService.ingestDocument()
    ↓
EmbeddingGenerator (per chunk)
    ↓
MemoryManager.storeMemory()
    ↓
Indexed and searchable

graph TB
    subgraph "Swift Layer"
        UI[TrainingPreferencesPane<br/>User Interface]
        Service[MLXTrainingService<br/>Training Orchestration]
        Exporter[TrainingDataExporter<br/>Data Preparation]
        AdapterMgr[AdapterManager<br/>Storage & I/O]
    end

    subgraph "Python Layer"
        Script[train_lora.py<br/>MLX Training Script]
        MLX[mlx-lm Library<br/>LoRA Implementation]
    end

    subgraph "Data Processing"
        ChatTemplate[ChatTemplateEngine<br/>Format Conversion]
        PIIDetector[PIIDetector<br/>Privacy Protection]
        DocChunker[DocumentChunker<br/>Content Splitting]
    end

    subgraph "Storage"
        JSONL[(Training Data<br/>JSONL Format)]
        Adapters[(Adapter Files<br/>SafeTensors)]
    end

    subgraph "Provider Integration"
        EndpointMgr[EndpointManager<br/>Adapter Registration]
        MLXProvider[MLXProvider<br/>LoRA Inference]
    end

    UI --> Service
    UI --> Exporter
    Service --> Script
    Script --> MLX
    Exporter --> ChatTemplate
    Exporter --> PIIDetector
    Exporter --> DocChunker
    Exporter --> JSONL
    Script --> Adapters
    AdapterMgr --> Adapters
    EndpointMgr --> AdapterMgr
    MLXProvider --> Adapters

    style UI fill:#00d4ff,color:#000
    style Service fill:#141822,color:#fff
    style Script fill:#00ff88,color:#000
    style MLX fill:#00ff88,color:#000

// MLXTrainingService.swift
public func startTraining(
    dataPath: String,
    modelPath: String,
    adapterName: String,
    rank: Int,
    learningRate: Double,
    epochs: Int,
    batchSize: Int
) async throws

# scripts/train_lora.py

import mlx.core as mx
from mlx_lm import load, lora

# Load base model
model, tokenizer = load(model_path)

# Configure LoRA
lora_config = {
    "rank": rank,
    "alpha": alpha,
    "dropout": 0.0,
    "target_modules": ["q_proj", "k_proj", "v_proj", "o_proj"]
}

# Train
model = lora.train(
    model=model,
    tokenizer=tokenizer,
    data=training_data,
    config=lora_config,
    learning_rate=learning_rate,
    num_epochs=num_epochs,
    batch_size=batch_size
)

# Save adapter
adapter_path = output_dir / "adapters.safetensors"
mx.savez(adapter_path, **lora_params)

for epoch in range(num_epochs):
    for batch in data_loader:
        # Forward pass
        logits = model(batch["input_ids"])

        # Compute loss
        loss = cross_entropy(logits, batch["labels"])

        # Backward pass (gradient computation)
        loss.backward()

        # Update LoRA weights only
        optimizer.step()

        # Report progress
        print(json.dumps({
            "epoch": epoch,
            "step": step,
            "loss": float(loss)
        }))

// AdapterManager.swift (Actor-based)
public func saveAdapter(_ adapter: LoRAAdapter) async throws {
    let adapterDir = adaptersDirectory
        .appendingPathComponent(adapter.id)

    // Create directory structure
    try FileManager.default.createDirectory(at: adapterDir)

    // Save metadata
    let metadata = AdapterMetadata(
        name: adapter.name,
        baseModel: adapter.baseModelName,
        trainingDataset: adapter.trainingDataset,
        createdAt: Date(),
        finalLoss: adapter.finalLoss,
        rank: adapter.rank,
        learningRate: adapter.learningRate,
        epochs: adapter.epochs,
        trainingSteps: adapter.trainingSteps
    )

    let metadataPath = adapterDir.appendingPathComponent("metadata.json")
    try JSONEncoder().encode(metadata).write(to: metadataPath)

    // Adapter weights saved by Python script:
    // - adapters.safetensors (LoRA weights)
    // - adapter_config.json (MLX configuration)
}

~/Library/Application Support/SAM/adapters/
├── {adapter-uuid-1}/
│   ├── adapters.safetensors      # LoRA weights (20-50MB typical)
│   ├── adapter_config.json        # MLX LoRA config
│   └── metadata.json              # Training metadata
├── {adapter-uuid-2}/
│   └── ...

// EndpointManager.swift
private func scanForAdapters() {
    let adapters = adapterManager.loadAllAdapters()

    for adapter in adapters {
        // Create LoRA provider for this adapter
        let provider = MLXProvider(
            modelPath: adapter.baseModelPath,
            adapterPath: adapter.adapterPath,
            modelName: "lora/\(adapter.name)"
        )

        // Register with model manager
        modelManager.registerProvider(provider)
    }
}

// MLXProvider.swift
public func loadModel() async throws {
    // Load base model
    let baseModel = try await MLX.load(modelPath: basePath)

    // Load LoRA adapter if specified
    if let adapterPath = adapterPath {
        let adapter = try await MLX.loadLoRA(path: adapterPath)

        // Apply LoRA to base model
        model = baseModel.applyLoRA(adapter)
    } else {
        model = baseModel
    }
}

// AppleMLXAdapter.swift
private func applyLoRAWeights(
    baseModel: MLXModel,
    adapterPath: String
) throws -> MLXModel {
    // Load adapter weights
    let weights = loadSafetensors(path: adapterPath)

    // For each attention layer
    for layer in baseModel.layers {
        if let loraA = weights["layer.\(layer.id).q_proj.lora_a"],
           let loraB = weights["layer.\(layer.id).q_proj.lora_b"] {
            // W' = W + (B × A) × scale
            let delta = loraB.matmul(loraA).multiply(scale)
            layer.q_proj.weight = layer.q_proj.weight.add(delta)
        }
        // Repeat for k_proj, v_proj, o_proj
    }

    return baseModel
}

// TrainingDataModels.swift

public struct TrainingExample: Codable, Sendable {
    public let userMessage: String
    public let assistantMessage: String
    public let systemPrompt: String?
}

public struct JSONLEntry: Codable, Sendable {
    public struct Message: Codable {
        public let role: String  // "system", "user", "assistant"
        public let content: String
    }

    public let messages: [Message]
}

public struct ExportOptions: Sendable {
    public enum ChunkingStrategy: String, CaseIterable, Sendable {
        case semantic = "Semantic (Paragraphs)"
        case fixedSize = "Fixed Size"
        case pageAware = "Page Aware (PDFs)"
    }

    public let chunkingStrategy: ChunkingStrategy
    public let maxChunkTokens: Int
    public let enablePIIDetection: Bool
    public let template: ChatTemplate
}

public struct ExportStatistics: Sendable {
    public let totalExamples: Int
    public let totalTokens: Int
    public let averageTokensPerExample: Int
    public let piiEntitiesRedacted: [PIIEntity: Int]
    public let outputFileSize: Int
}

public init(
    endpointManager: EndpointManager,
    conversationService: SharedConversationService,
    conversationManager: ConversationManager,
    maxIterations: Int = 300
) {
    self.endpointManager = endpointManager
    self.conversationService = conversationService
    self.conversationManager = conversationManager
    self.maxIterations = maxIterations
}

public protocol AIProviderProtocol: AnyObject {
    func processStreamingChatCompletion(...) async throws -> AsyncThrowingStream<...>
}

@MainActor
public class ConversationManager: ObservableObject {
    @Published public var conversations: [ConversationModel]
    @Published public var activeConversation: ConversationModel?
}

public func executeAutonomousWorkflow(...) async throws -> String {
    let response = try await provider.processChatCompletion(...)
    return response
}