# fabienfrfr/kairos architecture

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

- Interactive diagram: https://gitdiagram.com/fabienfrfr/kairos
- Repository: https://github.com/fabienfrfr/kairos

## Overview

KairosFM is an experimental multimodal foundation model and low-compute training stack. Its documented workflow builds or loads multimodal examples, encodes modalities with a shared byte-level tokenizer, packs training data, trains a hybrid diffusion model, then generates continuations or publishes a trained model. The graph preserves the model’s attention, routing, and residual architecture alongside dataset construction, training, and generation. Evidence is limited to the README and excerpts/SOURCE INDEX references; unsampled pipeline internals and notebook stages are not expanded into speculative links.

Main entry points: [`kairos/pipeline.py`](https://github.com/fabienfrfr/kairos/blob/main/kairos/pipeline.py) (Training pipeline), [`kairos/modeling.py`](https://github.com/fabienfrfr/kairos/blob/main/kairos/modeling.py) (Kairos model), [`notebook/kairos_pretraining.py`](https://github.com/fabienfrfr/kairos/blob/main/notebook/kairos_pretraining.py) (Pretraining workflow), [`kairos/generation.py`](https://github.com/fabienfrfr/kairos/blob/main/kairos/generation.py) (Diffusion generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_multimodal_data["Multimodal corpus builder"]
  node_tokenizer["Multimodal tokenizer<br/>[tokenizer.py]"]
  node_dataset["Dataset packing<br/>[dataset.py]"]
end

subgraph group_runtime["Model runtime"]
  node_model["Kairos model<br/>[modeling.py]"]
  node_attention["SWA and DeltaNet<br/>[attentions.py]"]
  node_generation["Diffusion generation<br/>[generation.py]"]
end

subgraph group_learning["Training and evaluation"]
  node_pipeline["Training pipeline<br/>[pipeline.py]"]
  node_trainer["Diffusion trainer<br/>[trainer.py]"]
  node_utilities["Compute diagnostics<br/>[utils.py]"]
  node_notebook["Pretraining workflow"]
end

subgraph group_delivery["Inference and publishing"]
  node_hub["Hugging Face Hub"]
  node_generated["Generated tokens"]
  node_trained["Trained model"]
end

node_user(("Researcher"))

node_user -->|"builds corpus"| node_multimodal_data
node_multimodal_data -->|"pushes dataset"| node_hub
node_user -->|"runs training"| node_notebook
node_notebook -->|"invokes builder"| node_multimodal_data
node_notebook -->|"loads datasets"| node_hub
node_notebook -->|"configures workflow"| node_pipeline
node_pipeline -->|"initializes"| node_tokenizer
node_pipeline -->|"uses datasets"| node_dataset
node_pipeline -->|"configures model"| node_model
node_pipeline -->|"creates trainer"| node_trainer
node_trainer -->|"trains model"| node_model
node_model -->|"uses attention"| node_attention
node_model -->|"inherits generation"| node_generation
node_pipeline -->|"uses diagnostics"| node_utilities
node_pipeline -->|"saves checkpoints"| node_trained
node_user -->|"requests generation"| node_pipeline
node_pipeline -->|"delegates generation"| node_generation
node_generation -->|"runs forward pass"| node_model
node_generation -->|"returns sequences"| node_generated
node_user -->|"publishes model"| node_pipeline
node_pipeline -->|"pushes model"| node_hub

click node_multimodal_data "https://github.com/fabienfrfr/kairos/blob/main/scripts/pretrain/build_keep_it_simple_multimodal.py"
click node_tokenizer "https://github.com/fabienfrfr/kairos/blob/main/kairos/tokenizer.py"
click node_dataset "https://github.com/fabienfrfr/kairos/blob/main/kairos/dataset.py"
click node_pipeline "https://github.com/fabienfrfr/kairos/blob/main/kairos/pipeline.py"
click node_trainer "https://github.com/fabienfrfr/kairos/blob/main/kairos/trainer.py"
click node_model "https://github.com/fabienfrfr/kairos/blob/main/kairos/modeling.py"
click node_attention "https://github.com/fabienfrfr/kairos/blob/main/kairos/attentions.py"
click node_generation "https://github.com/fabienfrfr/kairos/blob/main/kairos/generation.py"
click node_utilities "https://github.com/fabienfrfr/kairos/blob/main/kairos/utils.py"
click node_notebook "https://github.com/fabienfrfr/kairos/blob/main/notebook/kairos_pretraining.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_multimodal_data,node_tokenizer,node_dataset toneBlue
class node_model,node_attention,node_generation toneAmber
class node_pipeline,node_trainer,node_utilities,node_notebook toneMint
class node_hub,node_generated,node_trained toneRose
class node_user toneIndigo
```

## Components

### Data preparation

- [Multimodal corpus builder](https://github.com/fabienfrfr/kairos/blob/main/scripts/pretrain/build_keep_it_simple_multimodal.py): `scripts/pretrain/build_keep_it_simple_multimodal.py`
- [Multimodal tokenizer](https://github.com/fabienfrfr/kairos/blob/main/kairos/tokenizer.py): `kairos/tokenizer.py`
- [Dataset packing](https://github.com/fabienfrfr/kairos/blob/main/kairos/dataset.py): `kairos/dataset.py`

### Model runtime

- [Kairos model](https://github.com/fabienfrfr/kairos/blob/main/kairos/modeling.py): `kairos/modeling.py`
- [SWA and DeltaNet](https://github.com/fabienfrfr/kairos/blob/main/kairos/attentions.py): `kairos/attentions.py`
- [Diffusion generation](https://github.com/fabienfrfr/kairos/blob/main/kairos/generation.py): `kairos/generation.py`

### Training and evaluation

- [Training pipeline](https://github.com/fabienfrfr/kairos/blob/main/kairos/pipeline.py): `kairos/pipeline.py`
- [Diffusion trainer](https://github.com/fabienfrfr/kairos/blob/main/kairos/trainer.py): `kairos/trainer.py`
- [Compute diagnostics](https://github.com/fabienfrfr/kairos/blob/main/kairos/utils.py): `kairos/utils.py`
- [Pretraining workflow](https://github.com/fabienfrfr/kairos/blob/main/notebook/kairos_pretraining.py): `notebook/kairos_pretraining.py`

### Inference and publishing

- **Hugging Face Hub**
- **Generated tokens**
- **Trained model**

### Other components

- **Researcher**

## Connections

- Researcher → Multimodal corpus builder: builds corpus (evidence: `README.md`)
- Multimodal corpus builder → Hugging Face Hub: pushes dataset (evidence: `README.md`)
- Researcher → Pretraining workflow: runs training (evidence: `README.md`)
- Pretraining workflow → Multimodal corpus builder: invokes builder (evidence: `notebook/kairos_pretraining.py`)
- Pretraining workflow → Hugging Face Hub: loads datasets (evidence: `README.md`)
- Pretraining workflow → Training pipeline: configures workflow (evidence: `notebook/kairos_pretraining.py`)
- Training pipeline → Multimodal tokenizer: initializes (evidence: `kairos/pipeline.py`)
- Training pipeline → Dataset packing: uses datasets (evidence: `kairos/pipeline.py`)
- Training pipeline → Kairos model: configures model (evidence: `README.md`)
- Training pipeline → Diffusion trainer: creates trainer (evidence: `kairos/pipeline.py`)
- Diffusion trainer → Kairos model: trains model (evidence: `kairos/trainer.py`)
- Kairos model → SWA and DeltaNet: uses attention (evidence: `kairos/modeling.py`)
- Kairos model → Diffusion generation: inherits generation (evidence: `kairos/modeling.py`)
- Training pipeline → Compute diagnostics: uses diagnostics (evidence: `kairos/pipeline.py`)
- Training pipeline → Trained model: saves checkpoints (evidence: `README.md`)
- Researcher → Training pipeline: requests generation (evidence: `kairos/pipeline.py`)
- Training pipeline → Diffusion generation: delegates generation (evidence: `kairos/pipeline.py`)
- Diffusion generation → Kairos model: runs forward pass (evidence: `kairos/generation.py`)
- Diffusion generation → Generated tokens: returns sequences (evidence: `kairos/generation.py`)
- Researcher → Training pipeline: publishes model (evidence: `README.md`)
- Training pipeline → Hugging Face Hub: pushes model (evidence: `README.md`)
