# vedevpatel/kinema architecture

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

- Interactive diagram: https://gitdiagram.com/vedevpatel/kinema
- Repository: https://github.com/vedevpatel/kinema

## Overview

Kinema audits LeRobot robot-learning datasets before training, loading local, zipped, or Hub data and returning check findings, a health score, and reports. The main workflow is user → CLI → dataset loading → registered quality checks → report rendering. Checks cover data integrity, motion and calibration, metadata and video, duplicates and outliers, and deployment readiness; RLDS reading and MCP access are additional capabilities. Edges reflect README statements or source-index references; for unsampled modules, connections are omitted or marked unverified rather than inferred as certain.

Main entry points: [`src/kinema/checks/base.py`](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/base.py) (Check framework), [`src/kinema/mcp_server.py`](https://github.com/vedevpatel/kinema/blob/main/src/kinema/mcp_server.py) (MCP server), [`src/kinema/cli.py`](https://github.com/vedevpatel/kinema/blob/main/src/kinema/cli.py) (CLI), [`src/kinema/dataset.py`](https://github.com/vedevpatel/kinema/blob/main/src/kinema/dataset.py) (LeRobot loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

subgraph group_loading["Dataset loading"]
  node_dataset["LeRobot loader<br/>[dataset.py]"]
  node_rlds["RLDS reader<br/>[rlds.py]"]
end

subgraph group_checks["Quality checks"]
  node_framework["Check framework<br/>[base.py]"]
  node_actions["Action checks<br/>[actions.py]"]
  node_calibration["Calibration checks<br/>[calibration.py]"]
  node_idle["Idle and actuator<br/>[idle.py]"]
  node_duplicates["Duplicate checks<br/>[duplicates.py]"]
  node_metadata["Metadata checks<br/>[metadata.py]"]
  node_timestamps["Timestamp checks<br/>[timestamps.py]"]
  node_statsdrift["Stats drift<br/>[stats_drift.py]"]
  node_statsprov["Stats provenance"]
  node_outliers["Outlier checks<br/>[outliers.py]"]
  node_visual["Visual quality<br/>[visual.py]"]
  node_deployment["Deployment readiness<br/>[deployment.py]"]
  node_rldschecks["RLDS checks<br/>[rlds_checks.py]"]
  node_stats["Stats helpers<br/>[stats.py]"]
end

subgraph group_outputs["Results and integrations"]
  node_diagnose["Dataset diagnosis<br/>[diagnose.py]"]
  node_report["Report model<br/>[report.py]"]
  node_probes["Dataset probes<br/>[probes.py]"]
  node_similar["Similarity search<br/>[similar.py]"]
  node_history["Audit history<br/>[history.py]"]
end

node_user(("Dataset auditor"))
node_hub{{"Hugging Face Hub"}}
node_gcs{{"Google Cloud Storage"}}

node_user -->|"runs audit"| node_cli
node_cli -->|"loads dataset"| node_dataset
node_cli -->|"selects checks"| node_framework
node_cli -->|"renders results"| node_report
node_cli -->|"starts server"| node_mcp
node_dataset -->|"fetches dataset"| node_hub
node_dataset -->|"uses helpers"| node_stats
node_framework -->|"registers checks"| node_actions
node_framework -->|"registers checks"| node_calibration
node_framework -->|"registers checks"| node_idle
node_framework -->|"registers checks"| node_duplicates
node_framework -->|"registers checks"| node_metadata
node_framework -->|"registers checks"| node_timestamps
node_framework -->|"registers checks"| node_statsdrift
node_framework -->|"registers checks"| node_statsprov
node_framework -->|"registers checks"| node_outliers
node_framework -->|"registers checks"| node_visual
node_framework -->|"registers checks"| node_deployment
node_framework -->|"registers checks"| node_rldschecks
node_framework -->|"checks dataset"| node_dataset
node_statsdrift -->|"compares stats"| node_stats
node_calibration -->|"uses helpers"| node_stats
node_idle -->|"uses helpers"| node_stats
node_rlds -->|"reads shards"| node_gcs
node_rldschecks -->|"checks data"| node_rlds
node_diagnose -->|"loads dataset"| node_dataset
node_diagnose -->|"runs checks"| node_framework
node_diagnose -->|"builds report"| node_report
node_mcp -->|"dispatches diagnosis"| node_diagnose
node_mcp -->|"uses reports"| node_report
node_mcp -->|"uses similarity"| node_similar
node_mcp -.->|"uses probes"| node_probes
node_mcp -.->|"uses history"| node_history

click node_cli "https://github.com/vedevpatel/kinema/blob/main/src/kinema/cli.py"
click node_mcp "https://github.com/vedevpatel/kinema/blob/main/src/kinema/mcp_server.py"
click node_dataset "https://github.com/vedevpatel/kinema/blob/main/src/kinema/dataset.py"
click node_rlds "https://github.com/vedevpatel/kinema/blob/main/src/kinema/rlds.py"
click node_framework "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/base.py"
click node_actions "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/actions.py"
click node_calibration "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/calibration.py"
click node_idle "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/idle.py"
click node_duplicates "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/duplicates.py"
click node_metadata "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/metadata.py"
click node_timestamps "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/timestamps.py"
click node_statsdrift "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/stats_drift.py"
click node_statsprov "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/stats_provenance.py"
click node_outliers "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/outliers.py"
click node_visual "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/visual.py"
click node_deployment "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/deployment.py"
click node_rldschecks "https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/rlds_checks.py"
click node_stats "https://github.com/vedevpatel/kinema/blob/main/src/kinema/stats.py"
click node_diagnose "https://github.com/vedevpatel/kinema/blob/main/src/kinema/diagnose.py"
click node_report "https://github.com/vedevpatel/kinema/blob/main/src/kinema/report.py"
click node_probes "https://github.com/vedevpatel/kinema/blob/main/src/kinema/probes.py"
click node_similar "https://github.com/vedevpatel/kinema/blob/main/src/kinema/similar.py"
click node_history "https://github.com/vedevpatel/kinema/blob/main/src/kinema/history.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_mcp toneBlue
class node_dataset,node_rlds,node_gcs toneAmber
class node_framework,node_actions,node_calibration,node_idle,node_duplicates,node_metadata,node_timestamps,node_statsdrift,node_statsprov,node_outliers,node_visual,node_deployment,node_rldschecks,node_stats toneMint
class node_diagnose,node_report,node_probes,node_similar,node_history toneRose
class node_user,node_hub toneIndigo
```

## Components

### User entry

- [CLI](https://github.com/vedevpatel/kinema/blob/main/src/kinema/cli.py): `src/kinema/cli.py`
- [MCP server](https://github.com/vedevpatel/kinema/blob/main/src/kinema/mcp_server.py): `src/kinema/mcp_server.py`

### Dataset loading

- [LeRobot loader](https://github.com/vedevpatel/kinema/blob/main/src/kinema/dataset.py): `src/kinema/dataset.py`
- [RLDS reader](https://github.com/vedevpatel/kinema/blob/main/src/kinema/rlds.py): `src/kinema/rlds.py`

### Quality checks

- [Check framework](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/base.py): `src/kinema/checks/base.py`
- [Action checks](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/actions.py): `src/kinema/checks/actions.py`
- [Calibration checks](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/calibration.py): `src/kinema/checks/calibration.py`
- [Idle and actuator](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/idle.py): `src/kinema/checks/idle.py`
- [Duplicate checks](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/duplicates.py): `src/kinema/checks/duplicates.py`
- [Metadata checks](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/metadata.py): `src/kinema/checks/metadata.py`
- [Timestamp checks](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/timestamps.py): `src/kinema/checks/timestamps.py`
- [Stats drift](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/stats_drift.py): `src/kinema/checks/stats_drift.py`
- [Stats provenance](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/stats_provenance.py): `src/kinema/checks/stats_provenance.py`
- [Outlier checks](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/outliers.py): `src/kinema/checks/outliers.py`
- [Visual quality](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/visual.py): `src/kinema/checks/visual.py`
- [Deployment readiness](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/deployment.py): `src/kinema/checks/deployment.py`
- [RLDS checks](https://github.com/vedevpatel/kinema/blob/main/src/kinema/checks/rlds_checks.py): `src/kinema/checks/rlds_checks.py`
- [Stats helpers](https://github.com/vedevpatel/kinema/blob/main/src/kinema/stats.py): `src/kinema/stats.py`

### Results and integrations

- [Dataset diagnosis](https://github.com/vedevpatel/kinema/blob/main/src/kinema/diagnose.py): `src/kinema/diagnose.py`
- [Report model](https://github.com/vedevpatel/kinema/blob/main/src/kinema/report.py): `src/kinema/report.py`
- [Dataset probes](https://github.com/vedevpatel/kinema/blob/main/src/kinema/probes.py): `src/kinema/probes.py`
- [Similarity search](https://github.com/vedevpatel/kinema/blob/main/src/kinema/similar.py): `src/kinema/similar.py`
- [Audit history](https://github.com/vedevpatel/kinema/blob/main/src/kinema/history.py): `src/kinema/history.py`

### Other components

- **Dataset auditor**
- **Hugging Face Hub**
- **Google Cloud Storage**

## Connections

- Dataset auditor → CLI: runs audit (evidence: `README.md`)
- CLI → LeRobot loader: loads dataset (evidence: `src/kinema/cli.py`)
- CLI → Check framework: selects checks (evidence: `src/kinema/cli.py`)
- CLI → Report model: renders results (evidence: `src/kinema/cli.py`)
- CLI → MCP server: starts server (evidence: `src/kinema/cli.py`)
- LeRobot loader → Hugging Face Hub: fetches dataset (evidence: `README.md`)
- LeRobot loader → Stats helpers: uses helpers (evidence: `src/kinema/dataset.py`)
- Check framework → Action checks: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Calibration checks: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Idle and actuator: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Duplicate checks: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Metadata checks: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Timestamp checks: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Stats drift: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Stats provenance: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Outlier checks: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Visual quality: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → Deployment readiness: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → RLDS checks: registers checks (evidence: `src/kinema/checks/base.py`)
- Check framework → LeRobot loader: checks dataset (evidence: `src/kinema/checks/base.py`)
- Stats drift → Stats helpers: compares stats (evidence: `src/kinema/checks/stats_drift.py`)
- Calibration checks → Stats helpers: uses helpers (evidence: `src/kinema/checks/calibration.py`)
- Idle and actuator → Stats helpers: uses helpers (evidence: `src/kinema/checks/idle.py`)
- RLDS reader → Google Cloud Storage: reads shards (evidence: `src/kinema/rlds.py`)
- RLDS checks → RLDS reader: checks data (evidence: `src/kinema/checks/rlds_checks.py`)
- Dataset diagnosis → LeRobot loader: loads dataset (evidence: `src/kinema/diagnose.py`)
- Dataset diagnosis → Check framework: runs checks (evidence: `src/kinema/diagnose.py`)
- Dataset diagnosis → Report model: builds report (evidence: `src/kinema/diagnose.py`)
- MCP server → Dataset diagnosis: dispatches diagnosis (evidence: `src/kinema/mcp_server.py`)
- MCP server → Report model: uses reports (evidence: `src/kinema/mcp_server.py`)
- MCP server → Similarity search: uses similarity (evidence: `src/kinema/mcp_server.py`)
- MCP server → Dataset probes: uses probes
- MCP server → Audit history: uses history
