# danny024/financellm architecture

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

- Interactive diagram: https://gitdiagram.com/danny024/financellm
- Repository: https://github.com/danny024/financellm

## Overview

##### Project Type and Purpose
- FinanceLLM is a retrieval-augmented generation (RAG) system for financial question-answering.
- It ingests structured financial data (`data/train.json`), builds a FAISS vector store, retrieves relevant document chunks, and uses a local LLM (via Ollama) to generate step-by-step answers.
- A Streamlit app (`app.py`) serves as the user interface; a Jupyter notebook (`notebook.ipynb`) supports development and analysis; evaluation modules produce retrieval and answer quality metrics.

##### File Structure Analysis
Top-level:
- app.py – Streamlit front-end
- Dockerfile, entry.sh – containerization
- data/ – raw JSON and generated Markdown
- vector_db/ – persistent FAISS indices and metadata
- modules/ – core logic:
– data_processor.py (JSON→Markdown, chunking)
– rag_pipeline.py (embedding, retrieval, LLM chain)
– evaluator.py (computes correctness, precision, recall, hit rate, NDCG)
- requirements.txt, env – dependencies and environment
- notebook.ipynb – interactive pipeline exploration

##### Key README Insights
- Technologies: Python 3.12, LangChain, FAISS, Ollama (deepseek-r1:1.5b, nomic-embed-text), Streamlit, Docker
- External services: Local Ollama server, optional S3/AWS for data storage, optional OpenAI API

##### Main Components and Interactions
a. Components
1. User Interface (Streamlit app)
2. Data Processor (modules/data_processor.py)
3. Vector Store (FAISS indices in vector_db/)
4. RAG Pipeline (modules/rag_pipeline.py + Ollama LLM)
5. Evaluation Engine (modules/evaluator.py)
6. Storage: JSON source, Markdown chunks, CSV metrics
7. External Services: Ollama server, (optional) AWS S3, (optional) OpenAI API

b. Data Flow and Relationships
1. User uploads `train.json` → Data Processor converts to Markdown → splits into chunks
2. Chunks → Embedding via nomic-embed-text → indexed into FAISS (vector_db/)
3. User query → RAG Pipeline:
- Retrieve top-k vectors from FAISS
- Pass retrieved context + prompt to Ollama LLM
- Receive generated answer → display in UI
4. Batch evaluation: Query set from JSON → RAG Pipeline → Evaluator computes metrics → writes CSV files
5. Notebook path: same modules used interactively

c. Architectural Patterns and Principles
- Modular separation: UI, processing, retrieval, generation, evaluation
- Pipeline design: Clear stages (ingest → index → retrieve → generate → evaluate)
- Persistence layer: FAISS indices serve as the document store
- Containerization: Dockerfile and entry script for reproducible environments
- Extensibility: modules/ namespace allows swapping embedding or LLM backends

d. Key Technologies and Frameworks
- Streamlit (UI)
- LangChain (chain orchestration)
- FAISS (vector store)
- Ollama (local LLM inference)
- Python modules for data processing and evaluation

##### Detailed Capture of Essential Elements
- Sequence:
1. Data ingestion & chunking
2. Embedding & indexing
3. Retrieval & generation
4. Evaluation & metrics persistence
5. UI interactions (upload, query, view metrics)
- Environment setup: Docker container boundary, `.env` config for credentials
- Metrics flows (evaluation_results.csv → aggregation → mean_retrieval_metrics.csv)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container"
        direction TB
        UI["Streamlit UI\n(app.py)"]:::ui
        subgraph "Backend Modules"
            direction TB
            DP["Data Processor\n(data_processor.py)"]:::compute
            RP["RAG Pipeline\n(rag_pipeline.py)"]:::compute
            EV["Evaluation Engine\n(evaluator.py)"]:::compute
        end
        subgraph "Storage"
            direction TB
            JSON[(Raw JSON\ntrain.json)]:::storage
            MD[(Markdown Chunks\ntrain_output.md)]:::storage
            CSV1[(mean_retrieval_metrics.csv)]:::storage
            CSV2[(retrieval_metrics_summary.csv)]:::storage
            subgraph "FAISS Vector Store"
                direction TB
                VS1[(index.faiss\nindex.pkl)]:::storage
                VS2[(index.faiss\nindex.pkl)]:::storage
            end
        end
        UI -->|uploads JSON| DP
        DP -->|generates MD| MD
        DP -->|splits into chunks & embeds| RP
        RP -->|indexes vectors| VS1
        RP -->|indexes vectors| VS2
        UI -->|user query| RP
        RP -->|retrieves top-k| VS1
        RP -->|retrieves top-k| VS2
        RP -->|sends prompt| Ollama
        Ollama -->|response| RP
        RP -->|answer| UI
        RP -->|batch queries| EV
        EV -->|writes metrics| CSV1
        EV -->|writes metrics| CSV2
    end
    subgraph "Interactive Notebook"
        direction TB
        NB["Jupyter Notebook\n(notebook.ipynb)"]:::ui
        NB --> DP
        NB --> RP
        NB --> EV
    end
    subgraph "External Services"
        direction TB
        Ollama["Ollama LLM Server"]:::external
        AWS["AWS S3 / OpenAI API"]:::external
    end
    DP --> AWS
    RP --> AWS

    click UI "https://github.com/danny024/financellm/blob/main/app.py"
    click DP "https://github.com/danny024/financellm/blob/main/modules/data_processor.py"
    click RP "https://github.com/danny024/financellm/blob/main/modules/rag_pipeline.py"
    click EV "https://github.com/danny024/financellm/blob/main/modules/evaluator.py"
    click JSON "https://github.com/danny024/financellm/blob/main/data/train.json"
    click MD "https://github.com/danny024/financellm/blob/main/data/train_output.md"
    click CSV1 "https://github.com/danny024/financellm/blob/main/modules/mean_retrieval_metrics.csv"
    click CSV2 "https://github.com/danny024/financellm/blob/main/modules/retrieval_metrics_summary.csv"
    click NB "https://github.com/danny024/financellm/blob/main/notebook.ipynb"
    click VS1 "https://github.com/danny024/financellm/blob/main/vector_db/train.faiss/index.faiss"
    click VS2 "https://github.com/danny024/financellm/blob/main/vector_db/train/index.faiss"

    classDef compute fill:#add8e6,stroke:#333,stroke-width:1px
    classDef storage fill:#90ee90,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#f9f185,stroke:#333,stroke-width:1px
    classDef ui fill:#dda0dd,stroke:#333,stroke-width:1px,columnWidth:150px
```
