# rag-fish/noesisnoema architecture

> Architecture diagram of the GitHub repository rag-fish/noesisnoema, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rag-fish/noesisnoema
- Repository: https://github.com/rag-fish/noesisnoema

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        MacApp["macOS App"]:::ui
        iOSApp["iOS App"]:::ui
        CLI["CLI (LlamaBridgeTest)"]:::ui
    end

    %% Core Logic
    subgraph "Core Logic"
        AnswerGen["AnswerGenerator"]:::core

        subgraph "RAG Pipeline"
            VectorStore["VectorStore"]:::datastore
            LocalRet["LocalRetriever"]:::core
            BanditRet["BanditRetriever"]:::core
            QueryIter["QueryIterator"]:::core
            MMR["MMR"]:::core
            OnlineSGD["OnlineSGDReranker"]:::core
            DeepSearch["DeepSearch"]:::core
            ParamBanditCore["ParamBandit"]:::service
        end

        subgraph "InferenceEngine"
            LibLlama["LibLlama.swift"]:::core
            LlamaInf["LlamaInferenceEngine"]:::core
            RuntimeCheck["LlamaRuntimeCheck"]:::core
            SystemLog["SystemLog"]:::core
        end

        Preprocessor["Output Cleaning & Normalizer"]:::core
    end

    %% Services
    subgraph "Services"
        RewardBus["RewardBus"]:::service
        GoogleDrive["GoogleDriveService"]:::service
        FileResource["FileResource"]:::service
        DocManager["DocumentManager"]:::service
        ChunkExporter["ChunkExporter"]:::service
    end

    %% ModelRegistry
    subgraph "ModelRegistry"
        ModelCore["Core Specs & Registry"]:::datastore
        ModelIO["IO & JSON Persistence"]:::datastore
        ModelCLI["ModelCLI"]:::datastore
    end

    %% Settings & Persistence
    subgraph "Settings & Persistence"
        AppSettings["AppSettings & Settings"]:::datastore
        RegistryPersistence["RegistryPersistence"]:::datastore
    end

    %% External Frameworks & OS
    subgraph "External Frameworks & OS"
        LlamaIOS["llama_ios.xcframework"]:::ext
        LlamaMac["llama_macos.xcframework"]:::ext
        FileSystem["File System"]:::ext
        SwiftUI["SwiftUI / Combine / Foundation"]:::ext
    end

    %% Connections
    MacApp -->|"user query"| AnswerGen
    iOSApp -->|"user query"| AnswerGen
    CLI -->|"invoke core"| AnswerGen

    AnswerGen -->|"invoke pipeline"| LocalRet
    AnswerGen -->|"invoke pipeline"| BanditRet
    VectorStore -->|embeddings| LocalRet
    VectorStore -->|embeddings| BanditRet
    LocalRet -->|"retrieved chunks"| QueryIter
    BanditRet -->|"retrieved chunks"| QueryIter
    QueryIter -->|"reranked chunks"| AnswerGen

    AnswerGen -->|"prompt + chunks"| LlamaInf
    LibLlama --> LlamaInf
    LlamaMac --> LibLlama
    LlamaIOS --> LibLlama
    LlamaInf -->|"raw output"| Preprocessor
    Preprocessor -->|"cleaned answer"| AnswerGen

    AnswerGen -->|"answer"| MacApp
    AnswerGen -->|"answer"| iOSApp

    MacApp --> RewardBus
    iOSApp --> RewardBus
    CLI --> RewardBus
    RewardBus -.->|"feedback"| ParamBanditCore
    ParamBanditCore -.->|"tuned params"| BanditRet
    ParamBanditCore -.->|"tuned params"| LocalRet

    FileSystem --> FileResource
    FileSystem --> DocManager
    FileSystem --> ChunkExporter
    FileSystem --> ModelIO
    GoogleDrive --> DocManager

    ModelCore --> LlamaInf
    ModelIO --> ModelCore
    ModelCLI --> ModelCore

    AppSettings --> AnswerGen
    RegistryPersistence --> ModelCore

    SwiftUI --> MacApp
    SwiftUI --> iOSApp

    %% Click Events
    click MacApp "https://github.com/rag-fish/noesisnoema/tree/main/NoesisNoema/"
    click iOSApp "https://github.com/rag-fish/noesisnoema/tree/main/NoesisNoemaMobile/"
    click CLI "https://github.com/rag-fish/noesisnoema/tree/main/LlamaBridgeTest/"
    click AnswerGen "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/AnswerGenerator.swift"
    click LocalRet "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/RAG/LocalRetriever.swift"
    click BanditRet "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/RAG/BanditRetriever.swift"
    click QueryIter "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/RAG/QueryIterator.swift"
    click VectorStore "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/RAG/VectorStore.swift"
    click ParamBanditCore "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/RAG/ParamBandit.swift"
    click MMR "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/RAG/MMR.swift"
    click OnlineSGD "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/RAG/OnlineSGDReranker.swift"
    click DeepSearch "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/RAG/DeepSearch.swift"
    click LibLlama "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/Llama/LibLlama.swift"
    click LlamaInf "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/Llama/LlamaInferenceEngine.swift"
    click RuntimeCheck "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/Llama/LlamaRuntimeCheck.swift"
    click SystemLog "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/Utils/SystemLog.swift"
    click Preprocessor "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/Preprocessor.swift"
    click RewardBus "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/Feedback/RewardBus.swift"
    click GoogleDrive "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/GoogleDriveService.swift"
    click FileResource "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/FileResource.swift"
    click DocManager "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/DocumentManager.swift"
    click ChunkExporter "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/ChunkExporter.swift"
    click ModelCore "https://github.com/rag-fish/noesisnoema/tree/main/NoesisNoema/ModelRegistry/Core/"
    click ModelIO "https://github.com/rag-fish/noesisnoema/tree/main/NoesisNoema/ModelRegistry/IO/"
    click ModelCLI "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/ModelRegistry/CLI/ModelCLI.swift"
    click AppSettings "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/Shared/AppSettings.swift"
    click RegistryPersistence "https://github.com/rag-fish/noesisnoema/blob/main/NoesisNoema/ModelRegistry/IO/RegistryPersistence.swift"
    click LlamaIOS "https://github.com/rag-fish/noesisnoema/tree/main/Frameworks/xcframeworks/llama_ios.xcframework/"
    click LlamaMac "https://github.com/rag-fish/noesisnoema/tree/main/Frameworks/xcframeworks/llama_macos.xcframework/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef core fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef service fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef datastore fill:#ffe5b4,stroke:#333,stroke-width:1px;
    classDef ext fill:#e2e3e5,stroke:#333,stroke-width:1px;
```
