# mantistobogg/gemma-sprint-project architecture

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

- Interactive diagram: https://gitdiagram.com/mantistobogg/gemma-sprint-project
- Repository: https://github.com/mantistobogg/gemma-sprint-project

## Overview

##### Project Type and Purpose
- This is a Python-based, containerized machine-learning pipeline (no user interface) that orchestrates multiple NLP models to analyze user comments (sentiment and sarcasm) and generate context-aware, domain-enriched responses for enterprise consulting use-cases.

##### File Structure
- Top-level:
- Dockerfile + requirements.txt → containerized deployment of the entire pipeline.
- datasets/ → raw input CSV/JSON datasets (UScomments_final_cleaned.csv, IT_glossory_final_v4.csv, Sarcasm_Headlines_Dataset.json).
- src/ → main application entrypoint (gemma_v5.py) and helper modules (sentiment_model.py).
- tokenizer/ → custom tokenization logic (tokenzier_v1.py).
- gptj_integration/ & minilm_integration/ → scripts to load and train GPT-J and MiniLM models, plus persisted artifacts (term_embeddings.pt).
- Patterns → Single “orchestrator” script calls four model modules (DistilBERT, sarcasm detector, MiniLM, GPT-J/GEMMA-2B-IT) in sequence or in parallel.

##### README for Insights
- Confirms multi-LLM stack (DistilBERT for sentiment, sarcasm detection model, MiniLM for IT terms, GPT-J & GEMMA-2B-IT for response generation).
- Highlights containerization (Docker + Colima), Apple-Silicon PyTorch/MPS optimizations, logging, checkpointing.

##### Main Components & Relationships
a. Data Ingestion & Preprocessing
- Input datasets → cleaning & tokenization (tokenizer/tokenzier_v1.py).
b. Model Inference Modules
1) Sentiment Classifier (DistilBERT via src/sentiment_model.py)
2) Sarcasm Detector (Hugging Face model, integrated similarly)
3) IT-Term Embedder (MiniLM via minilm_integration/)
4) Generative LLMs (GPT-J & GEMMA-2B-IT via gptj_integration/)
c. Orchestration Layer
- gemma_v5.py stitches together inputs/outputs, handles routing logic (e.g., negative/sarcastic → urgent response).
d. Persistence & Observability
- Checkpoints/ logs directories (per README, though not shown in file tree) capture training/inference state.
e. Containerization & Deployment
- Dockerfile builds image hosting the orchestrator and all model dependencies, exposes API or CLI at port 8080.

##### Architectural Patterns & Design Principles
- Modular, pipeline-based design: each model is a separate component with a clear interface.
- Separation of concerns: tokenizer, model loaders, inference logic, and orchestration in distinct directories.
- Containerized reproducibility: ensures consistent environments across development and production.
- Hardware‐specific optimizations (MPS backend for Mac ARM64).

##### Detail & Coverage
- Every directory/module as an individual node if it plays a distinct role.
- Don’t omit the Dockerfile: it’s the boundary for production deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        USComments["UScomments CSV"]:::datastore
        ITGlossary["IT Glossary CSV"]:::datastore
        SarcasmDS["Sarcasm Headlines JSON"]:::datastore
    end

    %% Preprocessing
    subgraph "Preprocessing"
        Tokenizer["Tokenizer"]:::compute
    end

    %% Inference Services
    subgraph "Inference Services"
        Sentiment["DistilBERT Sentiment Model"]:::compute
        Sarcasm["Sarcasm Detector"]:::compute
        MiniLMLoader["Load MiniLM"]:::compute
        TermEmbed["Generate Term Embeddings"]:::compute
    end

    %% Generation Service
    subgraph "Generation Service"
        GPTJLoad["Load GPT-J"]:::compute
        GPTJTrain["Train GPT-J V2"]:::compute
    end

    %% Orchestration
    Orchestrator["Orchestrator (gemma_v5.py)"]:::orchestrator

    %% Persistence
    subgraph "Persistence"
        Checkpoints["Logs/Checkpoints"]:::datastore
    end

    %% Deployment
    Docker["Docker Container"]:::infra

    %% Data Flow
    USComments -->|ingest| Tokenizer
    ITGlossary -->|ingest| Tokenizer
    SarcasmDS -->|ingest| Tokenizer

    Tokenizer --> Sentiment
    Tokenizer --> Sarcasm
    Tokenizer --> MiniLMLoader

    MiniLMLoader --> TermEmbed

    Sentiment -->|results| Orchestrator
    Sarcasm -->|results| Orchestrator
    TermEmbed -->|embeddings| Orchestrator

    Orchestrator --> GPTJLoad
    GPTJLoad --> GPTJTrain
    GPTJTrain -->|response| Orchestrator

    %% Persistence connections
    Sentiment -->|log/checkpoint| Checkpoints
    Sarcasm -->|log/checkpoint| Checkpoints
    MiniLMLoader -->|log/checkpoint| Checkpoints
    TermEmbed -->|log/checkpoint| Checkpoints
    GPTJLoad -->|log/checkpoint| Checkpoints
    GPTJTrain -->|log/checkpoint| Checkpoints
    Orchestrator -->|log| Checkpoints

    %% Deployment connections
    Docker -->|hosts| Orchestrator
    Docker -->|hosts| GPTJLoad
    Docker -->|hosts| GPTJTrain

    %% Click Events
    click Tokenizer "https://github.com/mantistobogg/gemma-sprint-project/blob/main/tokenizer/tokenzier_v1.py"
    click USComments "https://github.com/mantistobogg/gemma-sprint-project/blob/main/datasets/UScomments_final_cleaned.csv.zip"
    click ITGlossary "https://github.com/mantistobogg/gemma-sprint-project/blob/main/datasets/IT_glossory_final_v4.csv"
    click SarcasmDS "https://github.com/mantistobogg/gemma-sprint-project/blob/main/datasets/Sarcasm_Headlines_Dataset.json"
    click Sentiment "https://github.com/mantistobogg/gemma-sprint-project/blob/main/src/sentiment_model.py"
    click MiniLMLoader "https://github.com/mantistobogg/gemma-sprint-project/blob/main/minilm_integration/load_minilm.py"
    click TermEmbed "https://github.com/mantistobogg/gemma-sprint-project/blob/main/minilm_integration/generate_term_embeddings.py"
    click GPTJLoad "https://github.com/mantistobogg/gemma-sprint-project/blob/main/gptj_integration/load_gptj.py"
    click GPTJTrain "https://github.com/mantistobogg/gemma-sprint-project/blob/main/gptj_integration/train_gptj_v2.py"
    click Orchestrator "https://github.com/mantistobogg/gemma-sprint-project/blob/main/src/gemma_v5.py"
    click Docker "https://github.com/mantistobogg/gemma-sprint-project/tree/main/Dockerfile"
    click Docker "https://github.com/mantistobogg/gemma-sprint-project/blob/main/requirements.txt"

    %% Styles
    classDef datastore fill:#B0E0E6,stroke:#333,stroke-width:1px
    classDef compute fill:#98FB98,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
