# google-deepmind/gemma architecture

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

- Interactive diagram: https://gitdiagram.com/google-deepmind/gemma
- Repository: https://github.com/google-deepmind/gemma

## Overview

Gemma is a JAX library for running and fine-tuning open-weight Gemma models. The primary workflow loads checkpoint parameters, constructs a model and sampler, then tokenizes a prompt (optionally with images) and generates a response; the README documents multi-turn, multimodal chat. Separate capabilities include model-family implementations, data and fine-tuning utilities, and a diffusion-based training/sampling stack. The diffusion adapter’s Sudoku and PubMedQA data and evaluation stages are represented from the tree and index; their internal wiring is not inferred where excerpts do not show it.

Main entry points: [`gemma/gm/text/_sampler.py`](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/text/_sampler.py) (Text sampler), [`gemma/diffusion/hackable_diffusion_adapter/hd/sft_model.py`](https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/hd/sft_model.py) (Diffusion fine-tuning), [`gemma/gm/__init__.py`](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/__init__.py) (Gemma API), [`gemma/gm/ckpts/_checkpoint.py`](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/ckpts/_checkpoint.py) (Checkpoint loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API and inference"]
  node_gm_api["Gemma API<br/>[__init__.py]"]
  node_checkpoints["Checkpoint loading<br/>[_checkpoint.py]"]
  node_tokenizer["Text tokenizer<br/>[_tokenizer.py]"]
  node_sampler["Text sampler<br/>[_sampler.py]"]
  node_sampler_loop["Generation loop<br/>[_sampler_loop.py]"]
end

subgraph group_models["Models and modalities"]
  node_model_family["Gemma model families<br/>[_gemma4.py]"]
  node_transformer["Transformer modules<br/>[_modules.py]"]
  node_rope["Positional embeddings"]
  node_vision["Vision processing<br/>[_preprocessing.py]"]
  node_audio["Audio model<br/>[_model.py]"]
end

subgraph group_tuning["Data and fine-tuning"]
  node_data_tasks["Task data<br/>[_tasks.py]"]
  node_data_functional["Data transforms<br/>[_functional.py]"]
  node_losses["Preference losses<br/>[_dpo.py]"]
  node_peft_lora["LoRA adaptation<br/>[_lora.py]"]
  node_peft_quant["Quantization<br/>[_quantization.py]"]
end

subgraph group_diffusion["Diffusion workflows"]
  node_diffusion_sampler["Diffusion sampler<br/>[_sampler.py]"]
  node_diffusion_transformer["Diffusion transformer<br/>[_transformer.py]"]
  node_adapter_data["Adapter datasets<br/>[data.py]"]
  node_adapter_network["Gemma diffusion network"]
  node_ar_state["Autoregressive state"]
  node_sft_model["Diffusion fine-tuning<br/>[sft_model.py]"]
  node_adapter_eval["Task evaluation<br/>[ar_eval.py]"]
end

subgraph group_extensions["Tools and research"]
  node_tools["Tool orchestration<br/>[_manager.py]"]
  node_t5["T5 Gemma research<br/>[t5gemma.py]"]
end

node_user(("Application user"))

node_user -->|"uses"| node_gm_api
node_gm_api -->|"exposes"| node_checkpoints
node_gm_api -->|"exposes"| node_sampler
node_user -->|"loads parameters"| node_checkpoints
node_user -->|"submits prompt"| node_sampler
node_checkpoints -->|"supplies parameters"| node_sampler
node_model_family -->|"configures model"| node_sampler
node_sampler -->|"tokenizes input"| node_tokenizer
node_sampler -->|"runs generation"| node_sampler_loop
node_sampler -->|"accepts images"| node_vision
node_transformer -->|"uses embeddings"| node_rope
node_data_tasks -->|"uses transforms"| node_data_functional
node_data_tasks -->|"uses tokenizer"| node_tokenizer
node_user -->|"fine-tunes with"| node_peft_lora
node_user -.->|"uses quantization"| node_peft_quant
node_adapter_network -->|"uses model"| node_diffusion_transformer
node_ar_state -->|"calls encoder"| node_adapter_network
node_sft_model -->|"uses state handler"| node_ar_state
node_sft_model -->|"uses network"| node_adapter_network
node_sft_model -->|"uses evaluator"| node_adapter_eval
node_t5 -->|"uses modules"| node_transformer
node_tools -.->|"serves tool calls"| node_user

click node_gm_api "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/__init__.py"
click node_checkpoints "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/ckpts/_checkpoint.py"
click node_tokenizer "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/text/_tokenizer.py"
click node_sampler "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/text/_sampler.py"
click node_sampler_loop "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/text/_sampler_loop.py"
click node_model_family "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/nn/gemma4/_gemma4.py"
click node_transformer "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/nn/gemma4/_modules.py"
click node_rope "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/math/_positional_embeddings.py"
click node_vision "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/nn/gemma4/vision/_preprocessing.py"
click node_audio "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/nn/gemma4/audio/_model.py"
click node_data_tasks "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/data/_tasks.py"
click node_data_functional "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/data/_functional.py"
click node_losses "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/losses/_dpo.py"
click node_peft_lora "https://github.com/google-deepmind/gemma/blob/main/gemma/peft/_lora.py"
click node_peft_quant "https://github.com/google-deepmind/gemma/blob/main/gemma/peft/_quantization.py"
click node_diffusion_sampler "https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/_sampler.py"
click node_diffusion_transformer "https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/_transformer.py"
click node_adapter_data "https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/data/data.py"
click node_adapter_network "https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/hd/hd_gemma_network.py"
click node_ar_state "https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/hd/hd_gemma_ar_state_handler.py"
click node_sft_model "https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/hd/sft_model.py"
click node_adapter_eval "https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/eval/ar_eval.py"
click node_tools "https://github.com/google-deepmind/gemma/blob/main/gemma/gm/tools/_manager.py"
click node_t5 "https://github.com/google-deepmind/gemma/blob/main/gemma/research/t5gemma/t5gemma.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gm_api,node_checkpoints,node_tokenizer,node_sampler,node_sampler_loop,node_user toneBlue
class node_model_family,node_transformer,node_rope,node_vision,node_audio toneAmber
class node_data_tasks,node_data_functional,node_losses,node_peft_lora,node_peft_quant toneMint
class node_diffusion_sampler,node_diffusion_transformer,node_adapter_data,node_adapter_network,node_ar_state,node_sft_model,node_adapter_eval toneRose
class node_tools,node_t5 toneIndigo
```

## Components

### Public API and inference

- [Gemma API](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/__init__.py): `gemma/gm/__init__.py`
- [Checkpoint loading](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/ckpts/_checkpoint.py): `gemma/gm/ckpts/_checkpoint.py`
- [Text tokenizer](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/text/_tokenizer.py): `gemma/gm/text/_tokenizer.py`
- [Text sampler](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/text/_sampler.py): `gemma/gm/text/_sampler.py`
- [Generation loop](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/text/_sampler_loop.py): `gemma/gm/text/_sampler_loop.py`

### Models and modalities

- [Gemma model families](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/nn/gemma4/_gemma4.py): `gemma/gm/nn/gemma4/_gemma4.py`
- [Transformer modules](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/nn/gemma4/_modules.py): `gemma/gm/nn/gemma4/_modules.py`
- [Positional embeddings](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/math/_positional_embeddings.py): `gemma/gm/math/_positional_embeddings.py`
- [Vision processing](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/nn/gemma4/vision/_preprocessing.py): `gemma/gm/nn/gemma4/vision/_preprocessing.py`
- [Audio model](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/nn/gemma4/audio/_model.py): `gemma/gm/nn/gemma4/audio/_model.py`

### Data and fine-tuning

- [Task data](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/data/_tasks.py): `gemma/gm/data/_tasks.py`
- [Data transforms](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/data/_functional.py): `gemma/gm/data/_functional.py`
- [Preference losses](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/losses/_dpo.py): `gemma/gm/losses/_dpo.py`
- [LoRA adaptation](https://github.com/google-deepmind/gemma/blob/main/gemma/peft/_lora.py): `gemma/peft/_lora.py`
- [Quantization](https://github.com/google-deepmind/gemma/blob/main/gemma/peft/_quantization.py): `gemma/peft/_quantization.py`

### Diffusion workflows

- [Diffusion sampler](https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/_sampler.py): `gemma/diffusion/_sampler.py`
- [Diffusion transformer](https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/_transformer.py): `gemma/diffusion/_transformer.py`
- [Adapter datasets](https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/data/data.py): `gemma/diffusion/hackable_diffusion_adapter/data/data.py`
- [Gemma diffusion network](https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/hd/hd_gemma_network.py): `gemma/diffusion/hackable_diffusion_adapter/hd/hd_gemma_network.py`
- [Autoregressive state](https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/hd/hd_gemma_ar_state_handler.py): `gemma/diffusion/hackable_diffusion_adapter/hd/hd_gemma_ar_state_handler.py`
- [Diffusion fine-tuning](https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/hd/sft_model.py): `gemma/diffusion/hackable_diffusion_adapter/hd/sft_model.py`
- [Task evaluation](https://github.com/google-deepmind/gemma/blob/main/gemma/diffusion/hackable_diffusion_adapter/eval/ar_eval.py): `gemma/diffusion/hackable_diffusion_adapter/eval/ar_eval.py`

### Tools and research

- [Tool orchestration](https://github.com/google-deepmind/gemma/blob/main/gemma/gm/tools/_manager.py): `gemma/gm/tools/_manager.py`
- [T5 Gemma research](https://github.com/google-deepmind/gemma/blob/main/gemma/research/t5gemma/t5gemma.py): `gemma/research/t5gemma/t5gemma.py`

### Other components

- **Application user**

## Connections

- Application user → Gemma API: uses
- Gemma API → Checkpoint loading: exposes (evidence: `gemma/gm/__init__.py`)
- Gemma API → Text sampler: exposes (evidence: `gemma/gm/__init__.py`)
- Application user → Checkpoint loading: loads parameters
- Application user → Text sampler: submits prompt
- Checkpoint loading → Text sampler: supplies parameters
- Gemma model families → Text sampler: configures model
- Text sampler → Text tokenizer: tokenizes input (evidence: `gemma/gm/text/_sampler.py`)
- Text sampler → Generation loop: runs generation (evidence: `gemma/gm/text/_sampler.py`)
- Text sampler → Vision processing: accepts images
- Transformer modules → Positional embeddings: uses embeddings (evidence: `gemma/gm/nn/gemma4/_modules.py`)
- Task data → Data transforms: uses transforms (evidence: `gemma/gm/data/_tasks.py`)
- Task data → Text tokenizer: uses tokenizer (evidence: `gemma/gm/data/_tasks.py`)
- Application user → LoRA adaptation: fine-tunes with
- Application user → Quantization: uses quantization
- Gemma diffusion network → Diffusion transformer: uses model (evidence: `gemma/diffusion/hackable_diffusion_adapter/hd/hd_gemma_network.py`)
- Autoregressive state → Gemma diffusion network: calls encoder (evidence: `gemma/diffusion/hackable_diffusion_adapter/hd/hd_gemma_ar_state_handler.py`)
- Diffusion fine-tuning → Autoregressive state: uses state handler (evidence: `gemma/diffusion/hackable_diffusion_adapter/hd/sft_model.py`)
- Diffusion fine-tuning → Gemma diffusion network: uses network (evidence: `gemma/diffusion/hackable_diffusion_adapter/hd/sft_model.py`)
- Diffusion fine-tuning → Task evaluation: uses evaluator (evidence: `gemma/diffusion/hackable_diffusion_adapter/hd/sft_model.py`)
- T5 Gemma research → Transformer modules: uses modules (evidence: `gemma/research/t5gemma/t5gemma.py`)
- Tool orchestration → Application user: serves tool calls
