# azzh1/purls architecture

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

- Interactive diagram: https://gitdiagram.com/azzh1/purls
- Repository: https://github.com/azzh1/purls

## Overview

PURLS is a research implementation for zero-shot skeleton action recognition, aligning skeleton representations with language-class descriptions. The main workflow in `main.py` loads split labels, prepares seen-class training/validation and unseen-class test data, constructs the model, optionally trains it, then evaluates zero-shot performance. `MInterface` manages training and evaluation steps; `Purls` implements part-aware representations and contrastive learning. The README also describes configurable dataset splits and visual/language embedding choices. Some integrations are dynamically selected or documented without sampled implementation, so uncertain links are omitted or marked unverified.

Main entry points: [`model/purls.py`](https://github.com/azzh1/purls/blob/main/model/purls.py) (PURLS model), [`main.py`](https://github.com/azzh1/purls/blob/main/main.py) (Experiment runner), [`model/model_interface.py`](https://github.com/azzh1/purls/blob/main/model/model_interface.py) (Model interface), [`data/data_interface.py`](https://github.com/azzh1/purls/blob/main/data/data_interface.py) (Data module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Experiment workflow"]
  node_runner["Experiment runner<br/>[main.py]"]
  node_trainer["Train and test<br/>[main.py]"]
end

subgraph group_data["Data and splits"]
  node_labels["Split labels<br/>[utils.py]"]
  node_data_module["Data module<br/>[data_interface.py]"]
  node_ntu120["NTU-120 dataset<br/>[ntu_120.py]"]
  node_ntu60["NTU-60 dataset<br/>[ntu_60.py]"]
  node_data_utils["Skeleton preprocessing<br/>[utils.py]"]
end

subgraph group_model["Representation learning"]
  node_interface["Model interface<br/>[model_interface.py]"]
  node_purls["PURLS model<br/>[purls.py]"]
  node_base["Model base<br/>[base.py]"]
end

subgraph group_helpers["Model components"]
  node_attention["Part attention<br/>[attention.py]"]
  node_contrastive["Contrastive loss<br/>[losses.py]"]
  node_layers["Projection layers<br/>[layers.py]"]
  node_prompt_tools["Prompt tools<br/>[prompt_tools.py]"]
  node_metrics["Prediction metrics<br/>[losses.py]"]
end

node_researcher(("Researcher"))
node_features[("Skeleton features")]
node_clip["CLIP text encoder"]
node_results["Recognition results"]

node_researcher -->|"configures and starts"| node_runner
node_runner -->|"loads split labels"| node_labels
node_runner -->|"constructs and sets up"| node_data_module
node_data_module -.->|"dynamically selects"| node_ntu120
node_data_module -.->|"dynamically selects"| node_ntu60
node_ntu120 -->|"loads feature arrays"| node_features
node_ntu120 -->|"uses splits and interpolation"| node_data_utils
node_runner -->|"fits and tests"| node_trainer
node_trainer -->|"requests data loaders"| node_data_module
node_trainer -->|"trains and evaluates"| node_interface
node_interface -.->|"dynamically instantiates"| node_purls
node_purls -->|"extends"| node_base
node_purls -->|"encodes class text"| node_clip
node_purls -->|"computes part features"| node_attention
node_purls -->|"calculates alignment loss"| node_contrastive
node_layers -->|"uses prompt adapter"| node_prompt_tools
node_interface -->|"passes batches and labels"| node_purls
node_interface -->|"reports test accuracy"| node_results
node_contrastive -.->|"computes predictions and accuracy"| node_metrics

click node_runner "https://github.com/azzh1/purls/blob/main/main.py"
click node_labels "https://github.com/azzh1/purls/blob/main/data/utils.py"
click node_data_module "https://github.com/azzh1/purls/blob/main/data/data_interface.py"
click node_ntu120 "https://github.com/azzh1/purls/blob/main/data/ntu_120.py"
click node_ntu60 "https://github.com/azzh1/purls/blob/main/data/ntu_60.py"
click node_data_utils "https://github.com/azzh1/purls/blob/main/data/utils.py"
click node_trainer "https://github.com/azzh1/purls/blob/main/main.py"
click node_interface "https://github.com/azzh1/purls/blob/main/model/model_interface.py"
click node_purls "https://github.com/azzh1/purls/blob/main/model/purls.py"
click node_base "https://github.com/azzh1/purls/blob/main/model/base.py"
click node_attention "https://github.com/azzh1/purls/blob/main/model/utils/attention.py"
click node_contrastive "https://github.com/azzh1/purls/blob/main/model/utils/losses.py"
click node_layers "https://github.com/azzh1/purls/blob/main/model/utils/layers.py"
click node_prompt_tools "https://github.com/azzh1/purls/blob/main/model/utils/prompt_tools.py"
click node_metrics "https://github.com/azzh1/purls/blob/main/model/utils/losses.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_runner,node_trainer toneBlue
class node_labels,node_data_module,node_ntu120,node_ntu60,node_data_utils,node_features toneAmber
class node_interface,node_purls,node_base toneMint
class node_attention,node_contrastive,node_layers,node_prompt_tools,node_metrics toneRose
class node_researcher,node_clip,node_results toneIndigo
```

## Components

### Experiment workflow

- [Experiment runner](https://github.com/azzh1/purls/blob/main/main.py): `main.py`
- [Train and test](https://github.com/azzh1/purls/blob/main/main.py): `main.py`

### Data and splits

- [Split labels](https://github.com/azzh1/purls/blob/main/data/utils.py): `data/utils.py`
- [Data module](https://github.com/azzh1/purls/blob/main/data/data_interface.py): `data/data_interface.py`
- [NTU-120 dataset](https://github.com/azzh1/purls/blob/main/data/ntu_120.py): `data/ntu_120.py`
- [NTU-60 dataset](https://github.com/azzh1/purls/blob/main/data/ntu_60.py): `data/ntu_60.py`
- [Skeleton preprocessing](https://github.com/azzh1/purls/blob/main/data/utils.py): `data/utils.py`

### Representation learning

- [Model interface](https://github.com/azzh1/purls/blob/main/model/model_interface.py): `model/model_interface.py`
- [PURLS model](https://github.com/azzh1/purls/blob/main/model/purls.py): `model/purls.py`
- [Model base](https://github.com/azzh1/purls/blob/main/model/base.py): `model/base.py`

### Model components

- [Part attention](https://github.com/azzh1/purls/blob/main/model/utils/attention.py): `model/utils/attention.py`
- [Contrastive loss](https://github.com/azzh1/purls/blob/main/model/utils/losses.py): `model/utils/losses.py`
- [Projection layers](https://github.com/azzh1/purls/blob/main/model/utils/layers.py): `model/utils/layers.py`
- [Prompt tools](https://github.com/azzh1/purls/blob/main/model/utils/prompt_tools.py): `model/utils/prompt_tools.py`
- [Prediction metrics](https://github.com/azzh1/purls/blob/main/model/utils/losses.py): `model/utils/losses.py`

### Other components

- **Researcher**
- **Skeleton features**
- **CLIP text encoder**
- **Recognition results**

## Connections

- Researcher → Experiment runner: configures and starts (evidence: `README.md`)
- Experiment runner → Split labels: loads split labels (evidence: `main.py`)
- Experiment runner → Data module: constructs and sets up (evidence: `main.py`)
- Data module → NTU-120 dataset: dynamically selects (evidence: `data/data_interface.py`)
- Data module → NTU-60 dataset: dynamically selects (evidence: `data/data_interface.py`)
- NTU-120 dataset → Skeleton features: loads feature arrays (evidence: `data/ntu_120.py`)
- NTU-120 dataset → Skeleton preprocessing: uses splits and interpolation (evidence: `data/ntu_120.py`)
- Experiment runner → Train and test: fits and tests (evidence: `main.py`)
- Train and test → Data module: requests data loaders (evidence: `main.py`)
- Train and test → Model interface: trains and evaluates (evidence: `main.py`)
- Model interface → PURLS model: dynamically instantiates (evidence: `model/model_interface.py`)
- PURLS model → Model base: extends (evidence: `model/purls.py`)
- PURLS model → CLIP text encoder: encodes class text (evidence: `model/purls.py`)
- PURLS model → Part attention: computes part features (evidence: `model/purls.py`)
- PURLS model → Contrastive loss: calculates alignment loss (evidence: `model/purls.py`)
- Projection layers → Prompt tools: uses prompt adapter (evidence: `model/utils/layers.py`)
- Model interface → PURLS model: passes batches and labels (evidence: `model/model_interface.py`)
- Model interface → Recognition results: reports test accuracy
- Contrastive loss → Prediction metrics: computes predictions and accuracy (evidence: `model/utils/losses.py`)
