How rag-fish/noesisnoema works
Project Type & Purpose
• This is a cross-platform, on-device private RAG (Retrieval-Augmented Generation) system written in Swift. It ships as a macOS app, an iOS app, and a small CLI harness. Core functionality: import RAGpacks (text chunks + embeddings), run a multi-stage retrieval pipeline with online/offline reranking and Thompson sampling via ParamBandit, invoke llama.cpp through a thin Swift shim for local LLM inference, clean and normalize output, and present results in a modern UI.
Top-Level Structure
• Frameworks/xcframeworks – prebuilt llama.cpp binaries for macOS and iOS
• NoesisNoema (macOS app target)
• NoesisNoemaMobile (iOS app target)
• LlamaBridgeTest (CLI test runner)
• ModelRegistry – command-line and programmatic model discovery & specs
• Shared – core business logic (AnswerGenerator, RAG pipeline, Llama shim, services, utilities)
• Tests – UI snapshot tests, ModelRegistry unit tests, utility tests
• Scripts & docs – build helpers, architecture notes, cleanup, refactoring plans
Main Components & Their Relationships
A. UI Layer
• macOS App (Two-pane SwiftUI)
• iOS App (Single-pane SwiftUI with overlays)
• CLI (LlamaBridgeTest)
→ All three invoke the same core logic in Shared.
B. Application Core (Shared)
• AnswerGenerator – orchestrates retrieval + inference
• RAG pipeline (Shared/RAG)
– LocalRetriever & BanditRetriever (uses ParamBandit to choose topK, mmrLambda, minScore)
– QueryIterator for multi-stage reranking (MMR)
– VectorStore holds embeddings in memory
• InferenceEngine (Shared/Llama)
– LibLlama.swift & LlamaInferenceEngine.swift bridge into llama.cpp xcframework
– Runtime guards + SystemLog for load checks & diagnostics
• Output Cleaning
– Streaming filter for <think> tags + control tokens
– Final normalizer for uniform answer formatting
• Services
– RewardBus (pub/sub for user feedback thumbs up/down)
– ParamBandit (Thompson Sampling to tune retrieval params per query)
– GoogleDriveService (optional remote pack import)
– FileResource / DocumentManager / ChunkExporter for pack I/O
• ModelRegistry (shared code under ModelRegistry/Core & IO)
– Registers available GGUF models, hardware profiles, persistence via JSON reader/writer
C. Data & Persistence
• RAGpacks (zip files with chunks.json, embeddings.csv, optional metadata.json)
• In-memory VectorStore + optional disk‐based persistence
• AppSettings / RegistryPersistence via JSON files
• Models loaded from app bundle or user‐supplied paths
D. External Dependencies
• llama_macos.xcframework / llama_ios.xcframework (C++ inference library)
• System file system for RAGpacks & models
• SwiftUI / Combine / Foundation
Architectural Patterns & Principles
• Layered Architecture: UI ↔ Core Logic ↔ Services ↔ External Frameworks
• Pub/Sub for Feedback (RewardBus) decouples UI from ParamBandit & retrieval pipeline
• Strategy / Dependency Injection for retrieval parameters (ParamBandit arms)
• Separation of concerns: ModelRegistry core vs. CLI vs. UI
• Reuse of Shared code across macOS, iOS, and CLI targets