# pantheon-industries-inc/argus architecture

> Architecture diagram of the GitHub repository pantheon-industries-inc/argus, 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/pantheon-industries-inc/argus
- Repository: https://github.com/pantheon-industries-inc/argus

## Overview

Argus prepares robot and human-ego recordings, runs deterministic quality checks, and uses a vision-language-model harness to produce dense episode annotations. The principal workflow continues through Data Review into a browsable dashboard; model comparison and regression scoring are supporting product branches. The graph follows documented orchestration and source-index references. Some modules were not sampled, so their internal calls are omitted.

Main entry points: [`prepare`](https://github.com/pantheon-industries-inc/argus/tree/main/prepare) (Episode sidecars), [`review/__main__.py`](https://github.com/pantheon-industries-inc/argus/blob/main/review/__main__.py) (Review workflow), [`label/harness.py`](https://github.com/pantheon-industries-inc/argus/blob/main/label/harness.py) (Model harness), [`board/build.py`](https://github.com/pantheon-industries-inc/argus/blob/main/board/build.py) (Board builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data preparation"]
  node_dataset_adapters["Dataset adapters"]
  node_upload_reader["Upload reader<br/>[formats.py]"]
  node_hub_access["Hub access<br/>[hub.py]"]
  node_video_geometry["Video geometry<br/>[display.py]"]
  node_episode_sidecars["Episode sidecars"]
end

subgraph group_quality["Quality checks"]
  node_capture_checks["Capture checks<br/>[capture_qc.py]"]
  node_stream_checks["Stream pairing<br/>[stream_pairing.py]"]
  node_timebase_checks["Timebase checks<br/>[timebase.py]"]
  node_label_checks["Label consistency"]
end

subgraph group_annotation["Episode annotation"]
  node_episode_loader["Episode loading<br/>[episode.py]"]
  node_frame_selection["Frame preparation<br/>[frames.py]"]
  node_annotation_state["Recorded state<br/>[state.py]"]
  node_model_harness["Model harness<br/>[harness.py]"]
end

subgraph group_review_board["Review and dashboard"]
  node_review_runner["Review workflow<br/>[__main__.py]"]
  node_board_builder["Board builder<br/>[build.py]"]
  node_clip_builder["Clip builder<br/>[clips.py]"]
  node_hand_overlay["Hand pose overlay<br/>[core.py]"]
  node_board_server["Dashboard server<br/>[serve.py]"]
end

subgraph group_evaluation["Model evaluation"]
  node_model_comparison["Model comparison<br/>[metrics.py]"]
  node_regression_scoring["Regression scoring<br/>[score.py]"]
end

node_data_user(("Data contributor"))
node_dataset_source[("Dataset sources")]
node_vlm(("Vision-language model"))

node_data_user -->|"submits data"| node_review_runner
node_dataset_source -->|"provides datasets"| node_dataset_adapters
node_dataset_source -->|"provides uploads"| node_upload_reader
node_dataset_adapters -->|"prepares episodes"| node_episode_sidecars
node_upload_reader -->|"writes sidecars"| node_episode_sidecars
node_dataset_adapters -->|"downloads data"| node_hub_access
node_upload_reader -->|"reads geometry"| node_video_geometry
node_review_runner -->|"reads uploads"| node_upload_reader
node_review_runner -->|"runs checks"| node_capture_checks
node_review_runner -->|"measures timebase"| node_timebase_checks
node_review_runner -->|"labels episodes"| node_model_harness
node_review_runner -->|"builds board"| node_board_builder
node_episode_sidecars -->|"checks recordings"| node_capture_checks
node_episode_sidecars -->|"checks streams"| node_stream_checks
node_episode_sidecars -->|"checks timing"| node_timebase_checks
node_episode_sidecars -->|"loads episode"| node_episode_loader
node_episode_loader -->|"prepares frames"| node_frame_selection
node_episode_loader -->|"uses state"| node_annotation_state
node_model_harness -->|"requests episode"| node_episode_loader
node_model_harness -->|"sends request"| node_vlm
node_vlm -->|"returns labels"| node_model_harness
node_board_builder -->|"includes checks"| node_capture_checks
node_board_builder -->|"includes consistency"| node_label_checks
node_board_builder -->|"reads comparisons"| node_model_comparison
node_board_builder -->|"serves board data"| node_board_server
node_episode_sidecars -->|"supplies footage"| node_clip_builder
node_clip_builder -->|"uses geometry"| node_video_geometry
node_board_server -->|"serves clips"| node_clip_builder
node_board_server -->|"shows comparisons"| node_model_comparison
node_board_server -->|"shows quality"| node_capture_checks
node_hand_overlay -->|"uses geometry"| node_video_geometry
node_episode_sidecars -->|"compares runs"| node_model_comparison
node_model_harness -->|"shares harness"| node_model_comparison
node_model_harness -->|"scores runs"| node_regression_scoring
node_label_checks -->|"scores consistency"| node_regression_scoring

click node_dataset_adapters "https://github.com/pantheon-industries-inc/argus/tree/main/prepare"
click node_upload_reader "https://github.com/pantheon-industries-inc/argus/blob/main/prepare/formats.py"
click node_hub_access "https://github.com/pantheon-industries-inc/argus/blob/main/prepare/hub.py"
click node_video_geometry "https://github.com/pantheon-industries-inc/argus/blob/main/prepare/display.py"
click node_episode_sidecars "https://github.com/pantheon-industries-inc/argus/tree/main/prepare"
click node_capture_checks "https://github.com/pantheon-industries-inc/argus/blob/main/checks/capture_qc.py"
click node_stream_checks "https://github.com/pantheon-industries-inc/argus/blob/main/checks/stream_pairing.py"
click node_timebase_checks "https://github.com/pantheon-industries-inc/argus/blob/main/checks/timebase.py"
click node_label_checks "https://github.com/pantheon-industries-inc/argus/blob/main/checks/label_consistency.py"
click node_episode_loader "https://github.com/pantheon-industries-inc/argus/blob/main/label/episode.py"
click node_frame_selection "https://github.com/pantheon-industries-inc/argus/blob/main/label/frames.py"
click node_annotation_state "https://github.com/pantheon-industries-inc/argus/blob/main/label/state.py"
click node_model_harness "https://github.com/pantheon-industries-inc/argus/blob/main/label/harness.py"
click node_review_runner "https://github.com/pantheon-industries-inc/argus/blob/main/review/__main__.py"
click node_board_builder "https://github.com/pantheon-industries-inc/argus/blob/main/board/build.py"
click node_clip_builder "https://github.com/pantheon-industries-inc/argus/blob/main/board/clips.py"
click node_hand_overlay "https://github.com/pantheon-industries-inc/argus/blob/main/board/hand_pose/core.py"
click node_board_server "https://github.com/pantheon-industries-inc/argus/blob/main/board/serve.py"
click node_model_comparison "https://github.com/pantheon-industries-inc/argus/blob/main/compare/metrics.py"
click node_regression_scoring "https://github.com/pantheon-industries-inc/argus/blob/main/gate/score.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_dataset_adapters,node_upload_reader,node_hub_access,node_video_geometry,node_episode_sidecars toneBlue
class node_capture_checks,node_stream_checks,node_timebase_checks,node_label_checks,node_dataset_source toneAmber
class node_episode_loader,node_frame_selection,node_annotation_state,node_model_harness toneMint
class node_review_runner,node_board_builder,node_clip_builder,node_hand_overlay,node_board_server toneRose
class node_model_comparison,node_regression_scoring,node_data_user,node_vlm toneIndigo
```

## Components

### Data preparation

- [Dataset adapters](https://github.com/pantheon-industries-inc/argus/tree/main/prepare): `prepare`
- [Upload reader](https://github.com/pantheon-industries-inc/argus/blob/main/prepare/formats.py): `prepare/formats.py`
- [Hub access](https://github.com/pantheon-industries-inc/argus/blob/main/prepare/hub.py): `prepare/hub.py`
- [Video geometry](https://github.com/pantheon-industries-inc/argus/blob/main/prepare/display.py): `prepare/display.py`
- [Episode sidecars](https://github.com/pantheon-industries-inc/argus/tree/main/prepare): `prepare`

### Quality checks

- [Capture checks](https://github.com/pantheon-industries-inc/argus/blob/main/checks/capture_qc.py): `checks/capture_qc.py`
- [Stream pairing](https://github.com/pantheon-industries-inc/argus/blob/main/checks/stream_pairing.py): `checks/stream_pairing.py`
- [Timebase checks](https://github.com/pantheon-industries-inc/argus/blob/main/checks/timebase.py): `checks/timebase.py`
- [Label consistency](https://github.com/pantheon-industries-inc/argus/blob/main/checks/label_consistency.py): `checks/label_consistency.py`

### Episode annotation

- [Episode loading](https://github.com/pantheon-industries-inc/argus/blob/main/label/episode.py): `label/episode.py`
- [Frame preparation](https://github.com/pantheon-industries-inc/argus/blob/main/label/frames.py): `label/frames.py`
- [Recorded state](https://github.com/pantheon-industries-inc/argus/blob/main/label/state.py): `label/state.py`
- [Model harness](https://github.com/pantheon-industries-inc/argus/blob/main/label/harness.py): `label/harness.py`

### Review and dashboard

- [Review workflow](https://github.com/pantheon-industries-inc/argus/blob/main/review/__main__.py): `review/__main__.py`
- [Board builder](https://github.com/pantheon-industries-inc/argus/blob/main/board/build.py): `board/build.py`
- [Clip builder](https://github.com/pantheon-industries-inc/argus/blob/main/board/clips.py): `board/clips.py`
- [Hand pose overlay](https://github.com/pantheon-industries-inc/argus/blob/main/board/hand_pose/core.py): `board/hand_pose/core.py`
- [Dashboard server](https://github.com/pantheon-industries-inc/argus/blob/main/board/serve.py): `board/serve.py`

### Model evaluation

- [Model comparison](https://github.com/pantheon-industries-inc/argus/blob/main/compare/metrics.py): `compare/metrics.py`
- [Regression scoring](https://github.com/pantheon-industries-inc/argus/blob/main/gate/score.py): `gate/score.py`

### Other components

- **Data contributor**
- **Dataset sources**
- **Vision-language model**

## Connections

- Data contributor → Review workflow: submits data (evidence: `README.md`)
- Dataset sources → Dataset adapters: provides datasets (evidence: `README.md`)
- Dataset sources → Upload reader: provides uploads (evidence: `README.md`)
- Dataset adapters → Episode sidecars: prepares episodes (evidence: `README.md`)
- Upload reader → Episode sidecars: writes sidecars (evidence: `prepare/formats.py`)
- Dataset adapters → Hub access: downloads data (evidence: `prepare/abc130k.py`)
- Upload reader → Video geometry: reads geometry (evidence: `prepare/formats.py`)
- Review workflow → Upload reader: reads uploads (evidence: `review/__main__.py`)
- Review workflow → Capture checks: runs checks (evidence: `README.md`)
- Review workflow → Timebase checks: measures timebase (evidence: `README.md`)
- Review workflow → Model harness: labels episodes (evidence: `README.md`)
- Review workflow → Board builder: builds board (evidence: `README.md`)
- Episode sidecars → Capture checks: checks recordings (evidence: `checks/capture_qc.py`)
- Episode sidecars → Stream pairing: checks streams (evidence: `checks/stream_pairing.py`)
- Episode sidecars → Timebase checks: checks timing (evidence: `checks/timebase.py`)
- Episode sidecars → Episode loading: loads episode (evidence: `label/episode.py`)
- Episode loading → Frame preparation: prepares frames (evidence: `label/episode.py`)
- Episode loading → Recorded state: uses state (evidence: `label/episode.py`)
- Model harness → Episode loading: requests episode (evidence: `label/harness.py`)
- Model harness → Vision-language model: sends request (evidence: `README.md`)
- Vision-language model → Model harness: returns labels (evidence: `README.md`)
- Board builder → Capture checks: includes checks (evidence: `board/build.py`)
- Board builder → Label consistency: includes consistency (evidence: `board/build.py`)
- Board builder → Model comparison: reads comparisons (evidence: `board/build.py`)
- Board builder → Dashboard server: serves board data (evidence: `README.md`)
- Episode sidecars → Clip builder: supplies footage (evidence: `board/clips.py`)
- Clip builder → Video geometry: uses geometry (evidence: `board/clips.py`)
- Dashboard server → Clip builder: serves clips (evidence: `board/serve.py`)
- Dashboard server → Model comparison: shows comparisons (evidence: `board/serve.py`)
- Dashboard server → Capture checks: shows quality (evidence: `board/serve.py`)
- Hand pose overlay → Video geometry: uses geometry (evidence: `board/hand_pose/core.py`)
- Episode sidecars → Model comparison: compares runs (evidence: `compare/metrics.py`)
- Model harness → Model comparison: shares harness (evidence: `compare/metrics.py`)
- Model harness → Regression scoring: scores runs (evidence: `gate/score.py`)
- Label consistency → Regression scoring: scores consistency (evidence: `gate/score.py`)
