# telotubbies/auto_label architecture

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

- Interactive diagram: https://gitdiagram.com/telotubbies/auto_label
- Repository: https://github.com/telotubbies/auto_label

## Overview

This repository is an offline PPE dataset-generation and model-training pipeline. The principal workflow runs from raw images through SAM labeling, manual verification, dataset preparation, YOLO training, evaluation, and deployment export. The README documents orchestration and subsystem responsibilities; the source excerpts sampled here are partial, so links between stages follow explicit README descriptions rather than inferred implementation details.

Main entry points: [`sam3_auto_label/src/batch_segment.py`](https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/batch_segment.py) (SAM Batch Runner), [`pipeline_cli.py`](https://github.com/telotubbies/auto_label/blob/main/pipeline_cli.py) (Pipeline CLI), [`yolo26_ppe/scripts/pipeline/03_evaluate_models.py`](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/03_evaluate_models.py) (Evaluation), [`yolo26_ppe/scripts/pipeline/01_prepare_dataset.py`](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/01_prepare_dataset.py) (Dataset Preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow Orchestration"]
  node_cli["Pipeline CLI<br/>[pipeline_cli.py]"]
end

subgraph group_labeling["SAM Auto-Labeling"]
  node_sam_batch["SAM Batch Runner<br/>[batch_segment.py]"]
  node_config["Typed Configuration<br/>[config.py]"]
  node_sam_inference["SAM Inference<br/>[inference.py]"]
  node_sam_model["SAM Model<br/>[model_builder.py]"]
  node_annotation_exports["Annotation Exports<br/>[exporters.py]"]
  node_experiment_db[("Experiment History<br/>[tracker.py]")]
  node_checkpoint["Resume Checkpoint<br/>[batch_segment.py]"]
end

subgraph group_dataset["Dataset Preparation"]
  node_dataset_prep["Dataset Preparation"]
  node_dataset["Versioned Dataset"]
end

subgraph group_model["YOLO Model Lifecycle"]
  node_training["YOLO Training<br/>[02_train_models.py]"]
  node_models["Production Models"]
end

subgraph group_analysis["Evaluation and Outputs"]
  node_evaluation["Evaluation"]
  node_failure_analysis["Failure Analysis"]
  node_robustness["Blur Robustness"]
  node_robustness_analysis["Robustness Analysis"]
  node_onnx["ONNX Export"]
  node_prediction["Raw Image Prediction"]
  node_report["Engineering Report"]
end

node_operator(("Operator"))
node_raw["Raw Images"]
node_review(("Manual Verification"))

node_operator -->|"starts workflow"| node_cli
node_cli -->|"dispatches SAM"| node_sam_batch
node_cli -->|"dispatches preparation"| node_dataset_prep
node_cli -->|"dispatches training"| node_training
node_cli -->|"dispatches evaluation"| node_evaluation
node_cli -->|"dispatches export"| node_onnx
node_cli -->|"dispatches prediction"| node_prediction
node_raw -->|"supplies images"| node_sam_batch
node_sam_batch -->|"reads settings"| node_config
node_sam_batch -->|"runs inference"| node_sam_inference
node_sam_inference -->|"uses model"| node_sam_model
node_sam_batch -->|"serializes annotations"| node_annotation_exports
node_sam_batch -->|"records runs"| node_experiment_db
node_sam_batch -->|"writes resume state"| node_checkpoint
node_checkpoint -->|"resumes batch"| node_sam_batch
node_annotation_exports -->|"provides annotations"| node_review
node_review -->|"supplies verified labels"| node_dataset_prep
node_dataset_prep -->|"creates dataset"| node_dataset
node_dataset -->|"trains on"| node_training
node_training -->|"produces weights"| node_models
node_models -->|"evaluates"| node_evaluation
node_evaluation -->|"provides results"| node_failure_analysis
node_models -->|"exports models"| node_onnx
node_onnx -->|"provides export results"| node_report
node_evaluation -->|"provides metrics"| node_report
node_dataset -->|"tests robustness"| node_robustness
node_robustness -->|"provides results"| node_robustness_analysis
node_models -->|"runs inference"| node_prediction

click node_cli "https://github.com/telotubbies/auto_label/blob/main/pipeline_cli.py"
click node_sam_batch "https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/batch_segment.py"
click node_config "https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/config.py"
click node_sam_inference "https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/inference.py"
click node_sam_model "https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/sam3/sam3/model_builder.py"
click node_annotation_exports "https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/exporters.py"
click node_experiment_db "https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/tracker.py"
click node_checkpoint "https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/batch_segment.py"
click node_dataset_prep "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/01_prepare_dataset.py"
click node_training "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/02_train_models.py"
click node_evaluation "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/03_evaluate_models.py"
click node_failure_analysis "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/05_generate_failure_montage.py"
click node_robustness "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/06_run_blur_robustness.py"
click node_robustness_analysis "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/07_analyze_blur_robustness.py"
click node_onnx "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/04_export_and_evaluate_onnx.py"
click node_prediction "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/09_predict_raw_images.py"
click node_report "https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/08_generate_report_figures.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 toneBlue
class node_sam_batch,node_config,node_sam_inference,node_sam_model,node_annotation_exports,node_experiment_db,node_checkpoint toneAmber
class node_dataset_prep,node_dataset toneMint
class node_training,node_models toneRose
class node_evaluation,node_failure_analysis,node_robustness,node_robustness_analysis,node_onnx,node_prediction,node_report,node_operator,node_raw,node_review toneIndigo
```

## Components

### Workflow Orchestration

- [Pipeline CLI](https://github.com/telotubbies/auto_label/blob/main/pipeline_cli.py): `pipeline_cli.py`

### SAM Auto-Labeling

- [SAM Batch Runner](https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/batch_segment.py): `sam3_auto_label/src/batch_segment.py`
- [Typed Configuration](https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/config.py): `sam3_auto_label/src/config.py`
- [SAM Inference](https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/inference.py): `sam3_auto_label/src/inference.py`
- [SAM Model](https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/sam3/sam3/model_builder.py): `sam3_auto_label/sam3/sam3/model_builder.py`
- [Annotation Exports](https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/exporters.py): `sam3_auto_label/src/exporters.py`
- [Experiment History](https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/tracker.py): `sam3_auto_label/src/tracker.py`
- [Resume Checkpoint](https://github.com/telotubbies/auto_label/blob/main/sam3_auto_label/src/batch_segment.py): `sam3_auto_label/src/batch_segment.py`

### Dataset Preparation

- [Dataset Preparation](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/01_prepare_dataset.py): `yolo26_ppe/scripts/pipeline/01_prepare_dataset.py`
- **Versioned Dataset**

### YOLO Model Lifecycle

- [YOLO Training](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/02_train_models.py): `yolo26_ppe/scripts/pipeline/02_train_models.py`
- **Production Models**

### Evaluation and Outputs

- [Evaluation](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/03_evaluate_models.py): `yolo26_ppe/scripts/pipeline/03_evaluate_models.py`
- [Failure Analysis](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/05_generate_failure_montage.py): `yolo26_ppe/scripts/pipeline/05_generate_failure_montage.py`
- [Blur Robustness](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/06_run_blur_robustness.py): `yolo26_ppe/scripts/pipeline/06_run_blur_robustness.py`
- [Robustness Analysis](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/07_analyze_blur_robustness.py): `yolo26_ppe/scripts/pipeline/07_analyze_blur_robustness.py`
- [ONNX Export](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/04_export_and_evaluate_onnx.py): `yolo26_ppe/scripts/pipeline/04_export_and_evaluate_onnx.py`
- [Raw Image Prediction](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/09_predict_raw_images.py): `yolo26_ppe/scripts/pipeline/09_predict_raw_images.py`
- [Engineering Report](https://github.com/telotubbies/auto_label/blob/main/yolo26_ppe/scripts/pipeline/08_generate_report_figures.py): `yolo26_ppe/scripts/pipeline/08_generate_report_figures.py`

### Other components

- **Operator**
- **Raw Images**
- **Manual Verification**

## Connections

- Operator → Pipeline CLI: starts workflow
- Pipeline CLI → SAM Batch Runner: dispatches SAM
- Pipeline CLI → Dataset Preparation: dispatches preparation
- Pipeline CLI → YOLO Training: dispatches training
- Pipeline CLI → Evaluation: dispatches evaluation
- Pipeline CLI → ONNX Export: dispatches export
- Pipeline CLI → Raw Image Prediction: dispatches prediction
- Raw Images → SAM Batch Runner: supplies images
- SAM Batch Runner → Typed Configuration: reads settings
- SAM Batch Runner → SAM Inference: runs inference
- SAM Inference → SAM Model: uses model
- SAM Batch Runner → Annotation Exports: serializes annotations
- SAM Batch Runner → Experiment History: records runs
- SAM Batch Runner → Resume Checkpoint: writes resume state
- Resume Checkpoint → SAM Batch Runner: resumes batch
- Annotation Exports → Manual Verification: provides annotations
- Manual Verification → Dataset Preparation: supplies verified labels
- Dataset Preparation → Versioned Dataset: creates dataset
- Versioned Dataset → YOLO Training: trains on
- YOLO Training → Production Models: produces weights
- Production Models → Evaluation: evaluates
- Evaluation → Failure Analysis: provides results
- Production Models → ONNX Export: exports models
- ONNX Export → Engineering Report: provides export results
- Evaluation → Engineering Report: provides metrics
- Versioned Dataset → Blur Robustness: tests robustness
- Blur Robustness → Robustness Analysis: provides results
- Production Models → Raw Image Prediction: runs inference