# gokzz-glitch/chakramodel architecture

> Architecture diagram of the GitHub repository gokzz-glitch/chakramodel, 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/gokzz-glitch/chakramodel
- Repository: https://github.com/gokzz-glitch/chakramodel

## Overview

ChakraModel is a research framework for colonoscopy polyp segmentation, with video analysis as its user-facing workflow: upload a video, run inference and tracking, optionally stabilize detections, then present annotated video and clinical reporting. Its broader product includes model training, transformer segmentation, uncertainty calibration, temporal/foundation-model experiments, and evaluation. Edges are limited to relationships shown in excerpts, the source index, or README; several documented subsystems are represented without speculative implementation links.

Main entry points: [`src/vst_fp/pipeline.py`](https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/pipeline.py) (VST-FP pipeline), [`src/infer_stream.py`](https://github.com/gokzz-glitch/chakramodel/blob/main/src/infer_stream.py) (Stream inference), [`evaluate_all.py`](https://github.com/gokzz-glitch/chakramodel/blob/main/evaluate_all.py) (Model evaluation), [`src/eval_pipeline.py`](https://github.com/gokzz-glitch/chakramodel/blob/main/src/eval_pipeline.py) (Detection evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_video["Video analysis"]
  node_dashboard["Analysis dashboard<br/>[app.py]"]
  node_stream["Stream inference<br/>[infer_stream.py]"]
  node_clinical["Clinical report<br/>[clinical_report.py]"]
  node_legacy_app["YOLO video app<br/>[app.py]"]
end

subgraph group_models["Segmentation models"]
  node_pranet["PraNet segmenter"]
  node_paris["Paris classifier"]
  node_transformer["Transformer segmenter"]
  node_vst_pipeline["VST-FP pipeline<br/>[pipeline.py]"]
  node_temporal_proposer["Temporal proposer"]
  node_sam2["SAM2 integration"]
end

subgraph group_safety["Safety and verification"]
  node_legacy_persist["Persistence filter"]
  node_conformal["Conformal calibration"]
  node_topology["Topological loss<br/>[topo_loss.py]"]
  node_topological_verifier["Topology verifier"]
  node_evidential["Evidential decisions"]
  node_persistence["Temporal persistence<br/>[persistence.py]"]
end

subgraph group_research["Training and evaluation"]
  node_combo_training["Combo training<br/>[run_all_combos.py]"]
  node_transformer_training["Transformer training"]
  node_evaluation["Model evaluation<br/>[evaluate_all.py]"]
  node_eval_pipeline["Detection evaluation<br/>[eval_pipeline.py]"]
  node_seg_metrics["Segmentation metrics<br/>[seg_metrics.py]"]
  node_ars["ARS metric<br/>[ars.py]"]
  node_tcs["TCS metric<br/>[tcs.py]"]
end

subgraph group_showcase["Web showcase"]
  node_frontend["Interactive showcase<br/>[App.jsx]"]
end

node_clinician(("Video user"))

node_clinician -->|"uploads video"| node_dashboard
node_dashboard -->|"runs analysis"| node_stream
node_stream -->|"refines masks"| node_pranet
node_stream -->|"classifies polyps"| node_paris
node_stream -->|"generates report"| node_clinical
node_clinician -->|"submits video"| node_legacy_app
node_legacy_app -->|"filters detections"| node_legacy_persist
node_combo_training -.->|"adds topology loss"| node_topology
node_transformer_training -->|"trains"| node_transformer
node_transformer_training -->|"measures scores"| node_seg_metrics
node_conformal -->|"calibrates model"| node_pranet
node_vst_pipeline -->|"generates prompts"| node_temporal_proposer
node_vst_pipeline -->|"segments video"| node_sam2
node_vst_pipeline -->|"verifies masks"| node_topological_verifier
node_vst_pipeline -->|"estimates uncertainty"| node_evidential
node_eval_pipeline -->|"computes metric"| node_ars
node_eval_pipeline -->|"computes metric"| node_tcs
node_eval_pipeline -->|"uses temporal state"| node_persistence
node_evaluation -->|"evaluates models"| node_seg_metrics
node_evaluation -->|"evaluates model"| node_pranet
node_evaluation -->|"evaluates model"| node_transformer

click node_dashboard "https://github.com/gokzz-glitch/chakramodel/blob/main/src/app.py"
click node_stream "https://github.com/gokzz-glitch/chakramodel/blob/main/src/infer_stream.py"
click node_pranet "https://github.com/gokzz-glitch/chakramodel/blob/main/src/pranet_segmenter.py"
click node_paris "https://github.com/gokzz-glitch/chakramodel/blob/main/src/paris_classifier.py"
click node_clinical "https://github.com/gokzz-glitch/chakramodel/blob/main/src/clinical_report.py"
click node_legacy_app "https://github.com/gokzz-glitch/chakramodel/blob/main/app.py"
click node_legacy_persist "https://github.com/gokzz-glitch/chakramodel/blob/main/temporal_persistence.py"
click node_combo_training "https://github.com/gokzz-glitch/chakramodel/blob/main/src/run_all_combos.py"
click node_transformer "https://github.com/gokzz-glitch/chakramodel/blob/main/src/chakra_transformer/transformer_segmenter.py"
click node_transformer_training "https://github.com/gokzz-glitch/chakramodel/blob/main/src/chakra_transformer/train_transformer.py"
click node_conformal "https://github.com/gokzz-glitch/chakramodel/blob/main/src/conformal_calibration.py"
click node_topology "https://github.com/gokzz-glitch/chakramodel/blob/main/src/topo_loss.py"
click node_vst_pipeline "https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/pipeline.py"
click node_temporal_proposer "https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/temporal_proposer.py"
click node_sam2 "https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/sam2_integration.py"
click node_topological_verifier "https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/topological_verifier.py"
click node_evidential "https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/evidential_layer.py"
click node_persistence "https://github.com/gokzz-glitch/chakramodel/blob/main/src/temporal/persistence.py"
click node_evaluation "https://github.com/gokzz-glitch/chakramodel/blob/main/evaluate_all.py"
click node_eval_pipeline "https://github.com/gokzz-glitch/chakramodel/blob/main/src/eval_pipeline.py"
click node_seg_metrics "https://github.com/gokzz-glitch/chakramodel/blob/main/src/metrics/seg_metrics.py"
click node_ars "https://github.com/gokzz-glitch/chakramodel/blob/main/src/metrics/ars.py"
click node_tcs "https://github.com/gokzz-glitch/chakramodel/blob/main/src/metrics/tcs.py"
click node_frontend "https://github.com/gokzz-glitch/chakramodel/blob/main/frontend/src/App.jsx"

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_dashboard,node_stream,node_clinical,node_legacy_app,node_clinician toneBlue
class node_pranet,node_paris,node_transformer,node_vst_pipeline,node_temporal_proposer,node_sam2 toneAmber
class node_legacy_persist,node_conformal,node_topology,node_topological_verifier,node_evidential,node_persistence toneMint
class node_combo_training,node_transformer_training,node_evaluation,node_eval_pipeline,node_seg_metrics,node_ars,node_tcs toneRose
class node_frontend toneIndigo
```

## Components

### Video analysis

- [Analysis dashboard](https://github.com/gokzz-glitch/chakramodel/blob/main/src/app.py): `src/app.py`
- [Stream inference](https://github.com/gokzz-glitch/chakramodel/blob/main/src/infer_stream.py): `src/infer_stream.py`
- [Clinical report](https://github.com/gokzz-glitch/chakramodel/blob/main/src/clinical_report.py): `src/clinical_report.py`
- [YOLO video app](https://github.com/gokzz-glitch/chakramodel/blob/main/app.py): `app.py`

### Segmentation models

- [PraNet segmenter](https://github.com/gokzz-glitch/chakramodel/blob/main/src/pranet_segmenter.py): `src/pranet_segmenter.py`
- [Paris classifier](https://github.com/gokzz-glitch/chakramodel/blob/main/src/paris_classifier.py): `src/paris_classifier.py`
- [Transformer segmenter](https://github.com/gokzz-glitch/chakramodel/blob/main/src/chakra_transformer/transformer_segmenter.py): `src/chakra_transformer/transformer_segmenter.py`
- [VST-FP pipeline](https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/pipeline.py): `src/vst_fp/pipeline.py`
- [Temporal proposer](https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/temporal_proposer.py): `src/vst_fp/temporal_proposer.py`
- [SAM2 integration](https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/sam2_integration.py): `src/vst_fp/sam2_integration.py`

### Safety and verification

- [Persistence filter](https://github.com/gokzz-glitch/chakramodel/blob/main/temporal_persistence.py): `temporal_persistence.py`
- [Conformal calibration](https://github.com/gokzz-glitch/chakramodel/blob/main/src/conformal_calibration.py): `src/conformal_calibration.py`
- [Topological loss](https://github.com/gokzz-glitch/chakramodel/blob/main/src/topo_loss.py): `src/topo_loss.py`
- [Topology verifier](https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/topological_verifier.py): `src/vst_fp/topological_verifier.py`
- [Evidential decisions](https://github.com/gokzz-glitch/chakramodel/blob/main/src/vst_fp/evidential_layer.py): `src/vst_fp/evidential_layer.py`
- [Temporal persistence](https://github.com/gokzz-glitch/chakramodel/blob/main/src/temporal/persistence.py): `src/temporal/persistence.py`

### Training and evaluation

- [Combo training](https://github.com/gokzz-glitch/chakramodel/blob/main/src/run_all_combos.py): `src/run_all_combos.py`
- [Transformer training](https://github.com/gokzz-glitch/chakramodel/blob/main/src/chakra_transformer/train_transformer.py): `src/chakra_transformer/train_transformer.py`
- [Model evaluation](https://github.com/gokzz-glitch/chakramodel/blob/main/evaluate_all.py): `evaluate_all.py`
- [Detection evaluation](https://github.com/gokzz-glitch/chakramodel/blob/main/src/eval_pipeline.py): `src/eval_pipeline.py`
- [Segmentation metrics](https://github.com/gokzz-glitch/chakramodel/blob/main/src/metrics/seg_metrics.py): `src/metrics/seg_metrics.py`
- [ARS metric](https://github.com/gokzz-glitch/chakramodel/blob/main/src/metrics/ars.py): `src/metrics/ars.py`
- [TCS metric](https://github.com/gokzz-glitch/chakramodel/blob/main/src/metrics/tcs.py): `src/metrics/tcs.py`

### Web showcase

- [Interactive showcase](https://github.com/gokzz-glitch/chakramodel/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Other components

- **Video user**

## Connections

- Video user → Analysis dashboard: uploads video (evidence: `src/app.py`)
- Analysis dashboard → Stream inference: runs analysis (evidence: `src/app.py`)
- Stream inference → PraNet segmenter: refines masks (evidence: `src/infer_stream.py`)
- Stream inference → Paris classifier: classifies polyps (evidence: `src/infer_stream.py`)
- Stream inference → Clinical report: generates report (evidence: `src/infer_stream.py`)
- Video user → YOLO video app: submits video (evidence: `app.py`)
- YOLO video app → Persistence filter: filters detections (evidence: `app.py`)
- Combo training → Topological loss: adds topology loss (evidence: `README.md`)
- Transformer training → Transformer segmenter: trains (evidence: `src/chakra_transformer/train_transformer.py`)
- Transformer training → Segmentation metrics: measures scores (evidence: `src/chakra_transformer/train_transformer.py`)
- Conformal calibration → PraNet segmenter: calibrates model (evidence: `src/conformal_calibration.py`)
- VST-FP pipeline → Temporal proposer: generates prompts (evidence: `src/vst_fp/pipeline.py`)
- VST-FP pipeline → SAM2 integration: segments video (evidence: `src/vst_fp/pipeline.py`)
- VST-FP pipeline → Topology verifier: verifies masks (evidence: `src/vst_fp/pipeline.py`)
- VST-FP pipeline → Evidential decisions: estimates uncertainty (evidence: `src/vst_fp/pipeline.py`)
- Detection evaluation → ARS metric: computes metric (evidence: `src/eval_pipeline.py`)
- Detection evaluation → TCS metric: computes metric (evidence: `src/eval_pipeline.py`)
- Detection evaluation → Temporal persistence: uses temporal state (evidence: `src/eval_pipeline.py`)
- Model evaluation → Segmentation metrics: evaluates models (evidence: `evaluate_all.py`)
- Model evaluation → PraNet segmenter: evaluates model (evidence: `evaluate_all.py`)
- Model evaluation → Transformer segmenter: evaluates model (evidence: `evaluate_all.py`)
