# higgsfield-ai/higgsfield architecture

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

- Interactive diagram: https://gitdiagram.com/higgsfield-ai/higgsfield
- Repository: https://github.com/higgsfield-ai/higgsfield

## Overview

Higgsfield is a distributed GPU orchestration and large-model training framework. A developer defines an experiment, the CLI parses and builds it, optional CI setup provisions GPU nodes, and queued runs execute a distributed data-loader/model training loop. Models use FSDP sharding and checkpoint helpers to persist state or publish to Hugging Face. The tree supports dataset, checkpoint, LLaMA/Mistral, SSH setup, and experiment-parsing stages; queue, workflow publication, and monitoring details are primarily README-documented and their wiring is therefore conservative.

Main entry points: [`higgsfield/checkpoint/fsdp_checkpoint.py`](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/checkpoint/fsdp_checkpoint.py) (FSDP Checkpointing), [`higgsfield/internal/main.py`](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/main.py) (Higgsfield CLI), [`higgsfield/internal/ci/setup.py`](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/ci/setup.py) (Node Setup), [`higgsfield/llama/llama.py`](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/llama/llama.py) (LLaMA Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_cli["Higgsfield CLI<br/>[main.py]"]
  node_queue["Experiment Queue<br/>[launch.py]"]
  node_ci_setup["Node Setup<br/>[setup.py]"]
end

subgraph group_experiments["Experiments"]
  node_experiment_api["Experiment API<br/>[experiment.py]"]
  node_ast_parser["Experiment Parser<br/>[ast_parser.py]"]
  node_workflow_builder["Workflow Builder<br/>[builder.py]"]
end

subgraph group_training["Distributed Training"]
  node_dataset_transforms["Dataset Transforms<br/>[dataset.py]"]
  node_distributed_loader["Distributed Loader<br/>[llama_loader.py]"]
  node_llama_model["LLaMA Models<br/>[llama.py]"]
  node_mistral_model["Mistral Models<br/>[mistral.py]"]
end

subgraph group_persistence["State Persistence"]
  node_checkpoint_api["Checkpoint API<br/>[fsdp_checkpoint.py]"]
  node_checkpoint_helpers["FSDP Checkpointing<br/>[fsdp_checkpoint.py]"]
  node_experiment_paths["Experiment Paths<br/>[path.py]"]
  node_checkpoint_store[("Checkpoint Store<br/>[path.py]")]
end

subgraph group_integrations["External Integrations"]
  node_run_monitor["Run Monitoring<br/>[launch.py]"]
end

node_developer(("Developer"))
node_training_script(("Training Script"))
node_github["GitHub"]
node_gpu_nodes["GPU Nodes"]
node_huggingface["Hugging Face"]

node_developer -->|"runs commands"| node_cli
node_developer -->|"defines experiment"| node_experiment_api
node_cli -->|"parses definitions"| node_ast_parser
node_ast_parser -->|"describes runs"| node_workflow_builder
node_workflow_builder -.->|"generates workflows"| node_github
node_cli -->|"sets up nodes"| node_ci_setup
node_ci_setup -->|"installs tooling"| node_gpu_nodes
node_ci_setup -.->|"configures deploy key"| node_github
node_developer -->|"submits experiment"| node_queue
node_queue -->|"dispatches run"| node_training_script
node_training_script -->|"loads batches"| node_distributed_loader
node_distributed_loader -->|"formats samples"| node_dataset_transforms
node_training_script -->|"trains model"| node_llama_model
node_training_script -->|"trains model"| node_mistral_model
node_llama_model -->|"saves state"| node_checkpoint_helpers
node_mistral_model -->|"saves state"| node_checkpoint_helpers
node_checkpoint_api -->|"writes state"| node_checkpoint_helpers
node_checkpoint_api -->|"resolves paths"| node_experiment_paths
node_experiment_paths -->|"creates directories"| node_checkpoint_store
node_checkpoint_helpers -->|"writes checkpoints"| node_checkpoint_store
node_llama_model -.->|"loads or publishes"| node_huggingface
node_mistral_model -.->|"loads or publishes"| node_huggingface
node_github -.->|"exposes run UI"| node_run_monitor

click node_cli "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/main.py"
click node_queue "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/launch.py"
click node_ci_setup "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/ci/setup.py"
click node_experiment_api "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/experiment.py"
click node_ast_parser "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/experiment/ast_parser.py"
click node_workflow_builder "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/experiment/builder.py"
click node_dataset_transforms "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/dataset/dataset.py"
click node_distributed_loader "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/loaders/llama_loader.py"
click node_llama_model "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/llama/llama.py"
click node_mistral_model "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/mistral/mistral.py"
click node_checkpoint_api "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/checkpoint/fsdp_checkpoint.py"
click node_checkpoint_helpers "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/checkpoint/fsdp_checkpoint.py"
click node_experiment_paths "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/path.py"
click node_checkpoint_store "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/path.py"
click node_run_monitor "https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/launch.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_cli,node_queue,node_ci_setup toneBlue
class node_experiment_api,node_ast_parser,node_workflow_builder toneAmber
class node_dataset_transforms,node_distributed_loader,node_llama_model,node_mistral_model toneMint
class node_checkpoint_api,node_checkpoint_helpers,node_experiment_paths,node_checkpoint_store toneRose
class node_run_monitor,node_developer,node_training_script,node_github,node_gpu_nodes,node_huggingface toneIndigo
```

## Components

### Orchestration

- [Higgsfield CLI](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/main.py): `higgsfield/internal/main.py`
- [Experiment Queue](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/launch.py): `higgsfield/internal/launch.py`
- [Node Setup](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/ci/setup.py): `higgsfield/internal/ci/setup.py`

### Experiments

- [Experiment API](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/experiment.py): `higgsfield/experiment.py`
- [Experiment Parser](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/experiment/ast_parser.py): `higgsfield/internal/experiment/ast_parser.py`
- [Workflow Builder](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/experiment/builder.py): `higgsfield/internal/experiment/builder.py`

### Distributed Training

- [Dataset Transforms](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/dataset/dataset.py): `higgsfield/dataset/dataset.py`
- [Distributed Loader](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/loaders/llama_loader.py): `higgsfield/loaders/llama_loader.py`
- [LLaMA Models](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/llama/llama.py): `higgsfield/llama/llama.py`
- [Mistral Models](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/mistral/mistral.py): `higgsfield/mistral/mistral.py`

### State Persistence

- [Checkpoint API](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/checkpoint/fsdp_checkpoint.py): `higgsfield/checkpoint/fsdp_checkpoint.py`
- [FSDP Checkpointing](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/checkpoint/fsdp_checkpoint.py): `higgsfield/checkpoint/fsdp_checkpoint.py`
- [Experiment Paths](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/path.py): `higgsfield/path.py`
- [Checkpoint Store](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/path.py): `higgsfield/path.py`

### External Integrations

- [Run Monitoring](https://github.com/higgsfield-ai/higgsfield/blob/main/higgsfield/internal/launch.py): `higgsfield/internal/launch.py`

### Other components

- **Developer**
- **Training Script**
- **GitHub**
- **GPU Nodes**
- **Hugging Face**

## Connections

- Developer → Higgsfield CLI: runs commands
- Developer → Experiment API: defines experiment
- Higgsfield CLI → Experiment Parser: parses definitions
- Experiment Parser → Workflow Builder: describes runs
- Workflow Builder → GitHub: generates workflows
- Higgsfield CLI → Node Setup: sets up nodes
- Node Setup → GPU Nodes: installs tooling
- Node Setup → GitHub: configures deploy key
- Developer → Experiment Queue: submits experiment
- Experiment Queue → Training Script: dispatches run
- Training Script → Distributed Loader: loads batches
- Distributed Loader → Dataset Transforms: formats samples
- Training Script → LLaMA Models: trains model
- Training Script → Mistral Models: trains model
- LLaMA Models → FSDP Checkpointing: saves state
- Mistral Models → FSDP Checkpointing: saves state
- Checkpoint API → FSDP Checkpointing: writes state
- Checkpoint API → Experiment Paths: resolves paths
- Experiment Paths → Checkpoint Store: creates directories
- FSDP Checkpointing → Checkpoint Store: writes checkpoints
- LLaMA Models → Hugging Face: loads or publishes
- Mistral Models → Hugging Face: loads or publishes
- GitHub → Run Monitoring: exposes run UI