# mchl-labs/stambecco architecture

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

- Interactive diagram: https://gitdiagram.com/mchl-labs/stambecco
- Repository: https://github.com/mchl-labs/stambecco

## Overview

##### Project Type and Purpose
- The README and file structure reveal that this is a research-oriented machine learning project focused on fine-tuning the LLaMA model to create an Italian instruction-following LLM.
- The project reproduces and extends approaches like Stanford Alpaca using LoRA while leveraging GPT-4 generated data for instruction tuning.
- It is designed to be run on Google Colab, with notebooks provided for training, inference (chat demo), and data processing.

##### File Structure
- Top-Level Files: Files like .gitignore, LICENSE, DATA_LICENSE, and README.md indicate standard repository structure.
- Directories:
- assets: Contains media such as the project logo.
- data: Contains the training dataset file (stambecco_data_it.json) that has been translated and adapted for Italian.
- notebooks: This folder holds multiple Jupyter notebooks for distinct tasks:
- Stambecco_chat.ipynb: Likely corresponds to the chat/inference interface (using Gradio).
- Stambecco_train.ipynb: Contains code to fine-tune the model on GPUs (e.g., using RTX 4090 or A100).
- Additional notebooks for data processing, demonstration, and exploratory analysis.

##### Key Components and Their Relationships
- Data Component:
- The "data" directory holds the Italian instruction dataset.
- It may involve preprocessing steps in one or more notebooks.
- Training Module:
- Executed via a Google Colab notebook (Stambecco_train.ipynb).
- Uses PEFT and LoRA to fine-tune the LLaMA 7B/13B models.
- Requires heavy GPU resources (A100/RTX 4090).
- Inference/Demo Module:
- Deployed using the Stambecco_chat.ipynb notebook, which probably integrates a graphical interface (via Gradio).
- Enables real-time interactions with the fine-tuned model.
- External Dependencies:
- Integration with Hugging Face’s model hub (for model cards and storing/fetching LoRA weights).
- External models and libraries like LLaMA, Alpaca, and Hugging Face PEFT library.
- Google Colab serves as the execution environment.
- Optional Assets/Visualization:
- The assets directory (used for the logo and possibly UI images in notebooks).

##### Architectural Patterns and Key Technologies
- The project adopts a modular, notebook-driven pattern that separates concerns (data processing, model fine-tuning, and inference).
- Utilizes low-rank adaptation (LoRA) for parameter-efficient fine-tuning.
- The model fine-tuning pipeline reflects research prototypes built on an experimental platform rather than a full-blown production backend.
- It relies on state-of-the-art ML libraries such as Hugging Face Transformers/PEFT.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Component
    A["Data Preprocessing"]:::data

    %% Notebooks Subgraph
    subgraph "Notebooks (Colab)"
        B["Training Notebook (Colab)"]:::notebook
        C["Inference/Demo (Gradio)"]:::notebook
        D["Data Exploration Notebook"]:::notebook
        E["Demo Exploration Notebook"]:::notebook
        F["Interactive Talk Notebook"]:::notebook
    end

    %% Supporting and External Components
    G["GPU Resources (A100/RTX 4090)"]:::gpu
    H["Fine-tuned Model (LoRA Weights)"]:::model
    I["External Dependencies (Hugging Face)"]:::external
    J["Execution Environment (Google Colab)"]:::env
    K["Assets and Visual Branding"]:::asset

    %% Connections
    A -->|"feeds"| B
    B -->|"uses"| G
    B -->|"produces"| H
    B -->|"updates"| I
    I -->|"stores"| H
    H -->|"serves"| C

    J -->|"runs"| B
    J -->|"runs"| C
    J -->|"runs"| D
    J -->|"runs"| E
    J -->|"runs"| F

    A -->|"feeds"| D
    A -->|"feeds"| E
    C -->|"interfaceswith"| F
    K -->|"providesUIassets"| C

    %% Click Events
    click A "https://github.com/mchl-labs/stambecco/blob/main/data/stambecco_data_it.json"
    click B "https://github.com/mchl-labs/stambecco/blob/main/notebooks/Stambecco_train.ipynb"
    click C "https://github.com/mchl-labs/stambecco/blob/main/notebooks/Stambecco_chat.ipynb"
    click D "https://github.com/mchl-labs/stambecco/blob/main/notebooks/Stambecco_data.ipynb"
    click E "https://github.com/mchl-labs/stambecco/blob/main/notebooks/Stambecco_demo.ipynb"
    click F "https://github.com/mchl-labs/stambecco/blob/main/notebooks/Stambecco_talk.ipynb"
    click K "https://github.com/mchl-labs/stambecco/tree/main/assets"

    %% Styles
    classDef data fill:#ccf,stroke:#333,stroke-width:2px;
    classDef notebook fill:#cfc,stroke:#333,stroke-width:2px;
    classDef gpu fill:#ff9,stroke:#333,stroke-width:2px;
    classDef model fill:#fc9,stroke:#333,stroke-width:2px;
    classDef external fill:#f99,stroke:#333,stroke-width:2px;
    classDef env fill:#9cf,stroke:#333,stroke-width:2px;
    classDef asset fill:#ddd,stroke:#333,stroke-width:2px;
```
