# nom-network/melba-toast-ai architecture

> Architecture diagram of the GitHub repository nom-network/melba-toast-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nom-network/melba-toast-ai
- Repository: https://github.com/nom-network/melba-toast-ai

## Overview

##### Project type and purpose
- This is an open-source, CLI-driven inference tool (“Melba-Toast-AI”) that wraps a GGUF-format LLM via llama-cpp-python, uses ChromaDB for vector-store memory, and employs NRCLex for sentiment/Affect analysis.
- It is neither a full-stack web app nor a compiler; it’s a backend-only “inference engine” library + reference CLI interface.

##### File structure
- Top-level:
- README.md, LICENSE.md, docs/ (static docs), examples/ (usage sample), memories/ (seed memory text files)
- src/ (all code)
- src/:
- melbaToast.py → entry-point orchestrator & CLI interface
- LLMCore.py → wraps llama-cpp load/infer routines
- LLMUtils.py → shared utilities (tokenization, prompt formatting, logging)
- memoryDB.py + initMemoryDB.py → handle ChromaDB vector store init, persist & retrieve “memories”
- llmbackendClient.py → client API abstraction for external invocation of the engine

##### README for additional insights
- Requires llama-cpp-python (local GGUF model runner), ChromaDB (vector DB), NRCLex (sentiment lexicon).
- Models must be converted/quantized to GGUF beforehand.

##### Detail
- Six src/ modules, the “memories” directory as a seed store, example usage script, and external dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI/API Interface Layer
    subgraph "CLI/API Interface"
        CLI["Examples (examples/main.py)"]:::module
        Orchestrator["Orchestrator / CLI (src/melbaToast.py)"]:::module
    end

    %% Core Modules
    subgraph "Core Modules"
        LLMCore["LLMCore (src/LLMCore.py)"]:::module
        MemoryDB["MemoryDB (src/memoryDB.py)"]:::module
        InitDB["MemoryDB Bootstrap (src/initMemoryDB.py)"]:::module
        Utils["Utilities (src/LLMUtils.py & NRCLex)"]:::module
        Client["Backend Client (src/llmbackendClient.py)"]:::module
    end

    %% Data Stores
    subgraph "Data Stores"
        SeedDocs["Seed Memories"]:::docs
        VectorDB["ChromaDB Vector Store"]:::data
    end

    %% External Dependencies
    subgraph "External Dependencies"
        LLCPP["llama-cpp-python"]:::external
        GGUF["Local GGUF Model Files"]:::external
        NRCLexDep["NRCLex"]:::external
        ChromaService["ChromaDB Service"]:::external
    end

    %% Data Flow
    CLI -->|"invoke CLI"| Orchestrator
    Orchestrator -->|"load context & retrieve memories"| MemoryDB
    MemoryDB -->|"fetch vectors"| ChromaService
    MemoryDB -->|"return memories"| Orchestrator
    Orchestrator -->|"format prompt"| Utils
    Orchestrator -->|"invoke inference"| LLMCore
    LLMCore -->|"call llama-cpp bindings"| LLCPP
    LLMCore -->|"load model"| GGUF
    LLMCore -->|"return raw response"| Orchestrator
    Orchestrator -->|"analyze sentiment"| Utils
    Utils -->|"use NRCLex"| NRCLexDep
    Orchestrator -->|"store new memories"| MemoryDB
    MemoryDB -->|"persist vectors"| ChromaService
    Orchestrator -->|"return response"| CLI

    InitDB -->|"bootstrap seed memories"| VectorDB
    SeedDocs -->|"source files"| InitDB

    %% Click Events
    click CLI "https://github.com/nom-network/melba-toast-ai/blob/main/examples/main.py"
    click Orchestrator "https://github.com/nom-network/melba-toast-ai/blob/main/src/melbaToast.py"
    click LLMCore "https://github.com/nom-network/melba-toast-ai/blob/main/src/LLMCore.py"
    click MemoryDB "https://github.com/nom-network/melba-toast-ai/blob/main/src/memoryDB.py"
    click InitDB "https://github.com/nom-network/melba-toast-ai/blob/main/src/initMemoryDB.py"
    click Utils "https://github.com/nom-network/melba-toast-ai/blob/main/src/LLMUtils.py"
    click Client "https://github.com/nom-network/melba-toast-ai/blob/main/src/llmbackendClient.py"
    click SeedDocs "https://github.com/nom-network/melba-toast-ai/tree/main/memories/"
    click LLCPP "https://github.com/nom-network/melba-toast-ai/tree/main/llama-cpp-python"
    click GGUF "https://github.com/nom-network/melba-toast-ai/tree/main/local_models/"
    click NRCLexDep "https://github.com/nom-network/melba-toast-ai/tree/main/NRCLex"
    click ChromaService "https://github.com/nom-network/melba-toast-ai/tree/main/ChromaDB"

    %% Styles
    classDef module fill:#BBDEFB,stroke:#2196F3;
    classDef external fill:#C8E6C9,stroke:#388E3C;
    classDef data fill:#FFF9C4,stroke:#FBC02D;
    classDef docs fill:#E1BEE7,stroke:#8E24AA;
```
