# pedroarruda07/functiongemma_fine-tune architecture

> Architecture diagram of the GitHub repository pedroarruda07/functiongemma_fine-tune, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pedroarruda07/functiongemma_fine-tune
- Repository: https://github.com/pedroarruda07/functiongemma_fine-tune

## Overview

This repo is not a “service” or “app” in the classic sense; it’s an **ML fine-tuning + evaluation + conversion pipeline** packaged as **two Jupyter notebooks** (Colab + Kaggle variants). The system you’re diagramming is the **end-to-end lifecycle**:

**FunctionGemma 270M (base)** → **prepare Mobile Actions dataset** → **fine-tune with LoRA / optional QLoRA using TRL+PEFT** → **evaluate (tool accuracy / exact match)** → **export artifacts** (checkpoints + `.litertlm`) → **deploy/run in Edge Gallery / edge devices**.

So the “architecture” is primarily a **workflow architecture** with key components (data, training runtime, libraries, model registry, conversion target, consumer runtime).

##### File tree analysis (what exists / what’s missing)
Top-level:
- `notebooks/`
- `colab-finetune_functiongemma_270m_for_mobile_actions_with_LoRA.ipynb`
- `kaggle-finetune_functiongemma_270m_for_mobile_actions_with_LoRA.ipynb`
These are the **source of truth** for the pipeline logic (setup → data → train → eval → export).
- `results/`
- `scored_df_20251228_base.json`
- `scored_df_20251228_trained_full_finetuned.json`
- `scored_df_20251228_trained_lora.json`
These are **evaluation outputs** (evidence artifacts), useful for showing “metrics generation” in the flow.
- `assets/`
- demo gif for Edge Gallery usage (deployment consumer).

##### README-derived architecture signals (explicit components)
- **Base model**: FunctionGemma 270M (instruction-tuned)
- **Dataset**: Mobile Actions dataset
- **Fine-tuning method**: LoRA (optional QLoRA)
- **Frameworks**: Hugging Face **TRL** + **PEFT**
- **Optimizer**: `paged_adamw_32bit` (especially relevant when QLoRA is enabled)
- **Training env**: Colab or Kaggle with **single NVIDIA T4**
- **Outputs**:
- trained checkpoint (LoRA adapters / merged model depending on notebook)
- evaluation JSON in `/results`
- `.litertlm` export for edge deployment
- **External distribution**: Hugging Face model repo hosting `.litertlm`
- **Deployment consumer**: Edge Gallery (Mobile Actions section) / supported edge devices

##### Notebook Orchestrator
- “Colab Notebook” and “Kaggle Notebook” as two entrypoints (same logical pipeline, different secrets/paths)

**Runtime / Compute**
##### Execution Environment
- Colab or Kaggle runtime
- GPU: NVIDIA T4

**Data Plane**
##### Mobile Actions Dataset Source
- wherever it’s pulled from in the notebook (show as external “Dataset provider”)

##### Base Model Source
- “FunctionGemma 270M” from model provider (likely Hugging Face / Google release; represent as external registry)
##### Fine-tuning Engine
- TRL Trainer (conceptually) + PEFT LoRA injection
##### Quantization Branch (optional)
- QLoRA path (bitsandbytes/4-bit quant) as a conditional subcomponent
##### Optimizer
- `paged_adamw_32bit` (connect to training loop)

**Evaluation**
##### Evaluation / Scoring
- computes: Correct Tool Accuracy, Exact Match Rate
##### Results Artifacts
- writes JSON to `results/*.json`

**Packaging / Export**
##### Checkpoint Saving
- LoRA adapter weights / final weights
##### Conversion to `.litertlm`

**Distribution / Deployment**
##### Model Hosting
- Hugging Face repo (external)
##### Edge Consumer
- Edge Gallery / edge device runtime loading `.litertlm`

##### Architectural patterns / principles actually used here
This repo is best described as:
- **Notebook-driven ML pipeline** (single orchestrator script, multiple stages)
- **Artifact-oriented workflow**: dataset → checkpoints → metrics JSON → export format
- **Parameter-efficient fine-tuning** (LoRA/QLoRA) rather than full model updates
- **Environment-specific entrypoints**: Colab vs Kaggle notebooks (same architecture, different integration details)

##### Technologies
- **Hugging Face TRL** (training loop)
- **PEFT** (LoRA injection)
- **LoRA / QLoRA** (parameter-efficient tuning strategy)
- **Paged AdamW 32-bit** (optimizer)
- **FunctionGemma 270M** (base)
- **`.litertlm`** (edge packaging target)
- **Colab/Kaggle + T4** (compute constraints that justify LoRA/QLoRA)

##### Labels
- Use explicit artifact names:
- “Base Model Weights (FunctionGemma 270M)”
- “LoRA Adapter Weights”
- “Evaluation JSON (`results/scored_df_*.json`)”
- “`.litertlm` package”

##### Boundaries (important)
- “This repository” (notebooks + results)
- “External providers” (dataset, base model registry, Hugging Face hosting, Edge Gallery)

##### A “best possible” component breakdown for this repo (what to literally put on the canvas)

- **User/Engineer**
- **Notebook (Colab)** / **Notebook (Kaggle)**
- **Runtime: Colab/Kaggle VM + NVIDIA T4**
- **Env setup (pip installs / auth / secrets)**
- **Dataset download**
- **Dataset preprocessing + prompt formatting**
- **Tokenizer**
- **Base model download (FunctionGemma 270M)**
- **LoRA config (r=16, alpha=32, dropout=0.1, target Linear modules...)**
- **(Optional) QLoRA quantization**
- **Training loop (TRL)**
- **PEFT adapter injection**
- **Optimizer: paged_adamw_32bit**
- **Checkpoint output**
- **Evaluation**
- **Metrics computation**
- **Results JSON in `/results`**
- **Convert to `.litertlm`**
- **Hugging Face model repo**
- **Edge Gallery / edge device runtime**

That level of decomposition matches the README and avoids inventing absent code structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Actors / Systems
  %% =========================
  User["User / ML Engineer"]:::actor

  subgraph "External Providers & Consumers"
    DatasetProvider["Mobile Actions Dataset Provider"]:::external
    BaseModelRegistry["Base Model Registry\n(FunctionGemma 270M weights + tokenizer)"]:::external
    HFHosting["Hugging Face Model Repo Hosting\n(artifacts + .litertlm)"]:::external
    EdgeGallery["Edge Gallery / Edge Device Runtime\n(Mobile Actions consumer)"]:::external
  end

  %% =========================
  %% Repository Boundary
  %% =========================
  subgraph "This Repository (Notebook-driven ML pipeline)"
    Readme["README\n(architecture + usage)"]:::doc

    subgraph "Notebooks (Entrypoints / Orchestrator)"
      ColabNB["Colab Notebook\nfinetune FunctionGemma 270M + Mobile Actions + LoRA"]:::notebook
      KaggleNB["Kaggle Notebook\nfinetune FunctionGemma 270M + Mobile Actions + LoRA"]:::notebook
    end

    subgraph "Execution Environment (Runtime / Compute)"
      Runtime["Colab / Kaggle Runtime VM"]:::runtime
      GPU["NVIDIA T4 GPU"]:::runtime
      EnvSetup["Environment Setup\n(pip installs, auth/secrets)"]:::stage
    end

    subgraph "Pipeline Stages (Workflow)"
      DataDownload["Dataset Download / Load"]:::stage
      DataPrep["Dataset Prep + Prompt Formatting\n(train/val split, tokenization inputs)"]:::stage
      Tokenizer["Tokenizer (FunctionGemma)"]:::stage

      ModelDownload["Base Model Download\n(FunctionGemma 270M)"]:::stage
      LoRAConfig["LoRA Configuration\n(r, alpha, dropout, target modules)"]:::stage

      subgraph "Fine-tuning Engine (TRL + PEFT)"
        PEFT["PEFT Adapter Injection\n(LoRA)"]:::stage
        TRLTrainer["Training Loop\n(Hugging Face TRL Trainer)"]:::stage
        Optimizer["Optimizer\n(paged_adamw_32bit)"]:::stage
        QLoRA["QLoRA Quantization (Optional)\n(4-bit via bitsandbytes)"]:::optional
      end

      CheckpointSave["Checkpoint Saving\n(LoRA adapters and/or merged weights)"]:::stage

      Eval["Evaluation / Scoring\n(Tool Accuracy, Exact Match)"]:::stage
      Metrics["Metrics Computation\n(aggregate scoring)"]:::stage

      Convert["Export / Conversion\n(to .litertlm)"]:::stage
    end

    subgraph "Artifacts in Repo"
      ResultsDir["results/ (evaluation outputs)"]:::artifact
      BaseJSON["scored_df_20251228_base.json"]:::artifact
      TrainedFullJSON["scored_df_20251228_trained_full_finetuned.json"]:::artifact
      TrainedLoRAJSON["scored_df_20251228_trained_lora.json"]:::artifact

      AssetsDir["assets/ (Edge Gallery demo evidence)"]:::artifact
      CheckpointArtifact["Trained Checkpoints\n(LoRA adapter weights / merged model)"]:::artifact
      LiteRTLM[".litertlm package"]:::artifact
    end
  end

  %% =========================
  %% Relationships / Flow (vertical)
  %% =========================
  User -->|"reads|runs"| Readme
  User -->|"executes"| ColabNB
  User -->|"executes"| KaggleNB

  ColabNB -->|"runs_on"| Runtime
  KaggleNB -->|"runs_on"| Runtime
  Runtime -->|"uses"| GPU
  ColabNB -->|"initializes"| EnvSetup
  KaggleNB -->|"initializes"| EnvSetup

  EnvSetup -->|"enables_access"| DatasetProvider
  EnvSetup -->|"enables_access"| BaseModelRegistry

  ColabNB -->|"orchestrates"| DataDownload
  KaggleNB -->|"orchestrates"| DataDownload
  DataDownload -->|"pulls_raw_data"| DatasetProvider
  DataDownload -->|"feeds"| DataPrep
  DataPrep -->|"uses"| Tokenizer

  ColabNB -->|"orchestrates"| ModelDownload
  KaggleNB -->|"orchestrates"| ModelDownload
  ModelDownload -->|"pulls_weights+tokenizer"| BaseModelRegistry

  ModelDownload -->|"provides_base"| PEFT
  DataPrep -->|"provides_batches"| TRLTrainer
  LoRAConfig -->|"configures"| PEFT
  PEFT -->|"wraps_model"| TRLTrainer
  Optimizer -->|"updates_params"| TRLTrainer

  QLoRA -.->|"optional_quant_path"| TRLTrainer

  TRLTrainer -->|"produces"| CheckpointSave
  CheckpointSave -->|"writes"| CheckpointArtifact

  %% Evaluation (base and trained)
  ModelDownload -->|"base_eval_input"| Eval
  CheckpointArtifact -->|"trained_eval_input"| Eval
  Eval -->|"computes"| Metrics
  Metrics -->|"writes_JSON"| ResultsDir

  ResultsDir -->|"contains"| BaseJSON
  ResultsDir -->|"contains"| TrainedFullJSON
  ResultsDir -->|"contains"| TrainedLoRAJSON

  %% Export / Distribution / Deployment
  CheckpointArtifact -->|"convert"| Convert
  Convert -->|"emits"| LiteRTLM
  LiteRTLM -->|"upload"| HFHosting
  HFHosting -->|"download/run"| EdgeGallery
  AssetsDir -->|"demonstrates"| EdgeGallery

  %% Iteration loop
  ResultsDir -.->|"iterate_hparams"| ColabNB
  ResultsDir -.->|"iterate_hparams"| KaggleNB

  %% =========================
  %% Click Events (mapped paths)
  %% =========================
  click ColabNB "https://github.com/pedroarruda07/functiongemma_fine-tune/blob/main/notebooks/colab-finetune_functiongemma_270m_for_mobile_actions_with_LoRA.ipynb"
  click KaggleNB "https://github.com/pedroarruda07/functiongemma_fine-tune/blob/main/notebooks/kaggle-finetune_functiongemma_270m_for_mobile_actions_with_LoRA.ipynb"
  click Readme "https://github.com/pedroarruda07/functiongemma_fine-tune/blob/main/README.md"
  click ResultsDir "https://github.com/pedroarruda07/functiongemma_fine-tune/tree/main/results/"
  click BaseJSON "https://github.com/pedroarruda07/functiongemma_fine-tune/blob/main/results/scored_df_20251228_base.json"
  click TrainedFullJSON "https://github.com/pedroarruda07/functiongemma_fine-tune/blob/main/results/scored_df_20251228_trained_full_finetuned.json"
  click TrainedLoRAJSON "https://github.com/pedroarruda07/functiongemma_fine-tune/blob/main/results/scored_df_20251228_trained_lora.json"
  click AssetsDir "https://github.com/pedroarruda07/functiongemma_fine-tune/tree/main/assets/"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#1f3a93,stroke:#0b1f4a,color:#ffffff,stroke-width:1px
  classDef notebook fill:#2e86de,stroke:#1b4f72,color:#ffffff,stroke-width:1px
  classDef runtime fill:#5dade2,stroke:#1b4f72,color:#0b1f4a,stroke-width:1px
  classDef stage fill:#2ecc71,stroke:#1e8449,color:#0b2e13,stroke-width:1px
  classDef optional fill:#a3e4d7,stroke:#117864,color:#0b2e13,stroke-width:1px,stroke-dasharray: 5 3
  classDef artifact fill:#e5e7e9,stroke:#7b7d7d,color:#1c2833,stroke-width:1px
  classDef external fill:#f5b041,stroke:#9c640c,color:#1c2833,stroke-width:1px
  classDef doc fill:#d6eaf8,stroke:#1b4f72,color:#1b2631,stroke-width:1px
```
