# jose-melo/t-jepa architecture

> Architecture diagram of the GitHub repository jose-melo/t-jepa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jose-melo/t-jepa
- Repository: https://github.com/jose-melo/t-jepa

## Overview

##### Project Type and Purpose
- This is an experimental deep learning framework focused on self-supervised learning for tabular data (an augmentation‐free Joint Embedding Predictive Architecture). Its main goal is to predict subsets of latent representations without data augmentations, thereby yielding competitive performance compared to standard gradient‐boosted machine learning techniques.
- The README and file structure show that the project supports both training (via run.py and launch_tjepa.sh) and benchmarking (via benchmark.py and numerous configuration files) among several models (e.g., AutoInt, DCNv2, FT-Transformer, MLP, ResNet) across different datasets.

##### Analyzing the File Structure
- Top-level directories:
- “src”: Contains all core source code with key components (datasets, models, training scripts, utility functions, and the T-JEPA-specific transformer).
- “datasets”: Holds data loading and preprocessing code.
- “benchmark” (both at the top level and under src/benchmark): Contains configuration files, model configurations, and scripts for running experiments.
- “scripts”: Provides shell scripts to launch training, benchmark runs, tuning, and experiments with various random seeds.
- “results”: Organized per dataset and per model, storing JSON outputs and summary files.
- Multiple configuration subdirectories (e.g., tuned_config, tuning_config) reside under src/benchmark and ensure decoupled configuration management for each experiment.
- Other key files include run.py (main entry for training/evaluation), benchmark.py (to run benchmarking experiments), and launch_tjepa.sh (to start pretraining).

##### Key Architectural Components
- Data Ingestion & Preprocessing:
- External datasets (downloaded via download_data.sh) and the “datasets” module that handles loading and embedded representations (e.g., adult_income.py, aloi.py).
- Core Training Pipeline:
- T-JEPA Learning Flow:
- Context Encoder
- Target Encoder
- Prediction Module (integrated in src/tjepa_transformer.py)
- Training and evaluation are orchestrated by src/train.py and integrated into the main run.py.
- Model Components:
- Benchmarking & Evaluation:
- Benchmarking scripts and configurations (benchmark.py, run_benchmark.py, various JSON config files under src/benchmark/tuned_config) that test and compare models across datasets.
- Configuration and Utility Modules:
- Config files (configs.py) and utilities (inside src/utils) like logging, checkpointing, and optimization functions.
- Experiment Orchestration:
- Shell scripts in the “scripts” folder (launch_tjepa.sh, bench_random_seed, tjepa_tuning) that allow parameter tuning and experiment runs.
- Results Storage:
- The “results” directory tree where outputs (JSON files and summaries) for different models and datasets are stored.

##### How They Interact
- The training process (triggered by run.py or launch_tjepa.sh) acquires data from the datasets folder, processes it via the data ingestion modules, and feeds it into the T-JEPA pipeline composed of the context encoder, target encoder, and prediction module.
- Model definitions (in src/models) are called by the training routines; these return latent representations used in predictions.
- Utility modules support training (e.g., logging, model saving, learning rate scheduling) and are linked with train_utils.
- Benchmarking scripts (benchmark.py, run_benchmark.py) leverage tuned configuration files to run experiments across multiple models and datasets, then save results into the “results” directory.
- The configuration (from both JSON and YAML files) decouples model hyperparameters and training regimes, ensuring flexibility in experiments.

##### Architectural Patterns and Design Principles
- Modularity: Each functionality (data loading, model definition, training loop, utility, benchmarking) is isolated in its own subdirectory.
- Configurability: Files under tuned_config and tuning_config separate experiment parameters from code.
- Extensibility: The clear separation between model implementations (each in its own file under src/models) and the overall pipeline (e.g., in src/train.py).
- Reproducibility: Scripts in “bench_random_seed” indicate careful logging of experiments and random seed management.

## Diagram (Mermaid)

```mermaid
graph TD
  %% Data Layer
  subgraph "Data Layer"
    DS["Datasets (src/datasets)"]:::data
    AD["Adult Income"]:::data
    AL["Aloi"]:::data
  end

  %% Training Pipeline
  subgraph "Training Pipeline"
    RP["run.py (Entry)"]:::training
    TP["src/train.py (Training Orchestration)"]:::training
    TTE["T-JEPA Transformer (src/tjepa_transformer.py)"]:::training
  end

  %% Model Components
  subgraph "Model Components"
    AINT["AutoInt (src/models/autoint.py)"]:::model
    DCN["DCNv2 (src/models/dcnv2.py)"]:::model
    FT["FT-Transformer (src/models/fttransformer.py)"]:::model
    MLP_NODE["MLP (src/models/mlp.py)"]:::model
    RES["ResNet (src/models/resnet.py)"]:::model
  end

  %% Benchmarking & Evaluation
  subgraph "Benchmarking & Evaluation"
    BS["Benchmark Script (benchmark.py)"]:::training
    RB["Run Benchmark (run_benchmark.py)"]:::training
    TC["Tuned Configs (src/benchmark/tuned_config)"]:::training
    TUC["Tuning Configs (src/benchmark/tuning_config)"]:::training
    MC["Model Configs (src/benchmark/model_configs)"]:::training
  end

  %% Configuration and Utility Modules
  subgraph "Configuration & Utility"
    GC["Global Config (src/configs.py)"]:::config
    LU["Log Utils (src/utils/log_utils.py)"]:::config
    TU["Train Utils (src/utils/train_utils.py)"]:::config
  end

  %% Experiment Orchestration
  subgraph "Experiment Orchestration"
    LS["Launch Script (scripts/launch_tjepa.sh)"]:::orchestration
    TT["T-JEPA Tuning (scripts/tjepa_tuning)"]:::orchestration
    BR["Bench Random Seed (scripts/bench_random_seed)"]:::orchestration
  end

  %% Results Storage
  subgraph "Results Storage"
    RES_DIR["Results Directory (results)"]:::results
  end

  %% Connections
  DS -->|"feeds_data"| RP
  AD -->|"part_of"| DS
  AL -->|"part_of"| DS

  RP -->|"orchestrates"| TP
  TP -->|"invokes"| TTE
  TTE <-->|"latent_exchange"| AINT
  TTE <-->|"latent_exchange"| DCN
  TTE <-->|"latent_exchange"| FT
  TTE <-->|"latent_exchange"| MLP_NODE
  TTE <-->|"latent_exchange"| RES

  GC -->|"configures"| TP
  LU -->|"supports"| TP
  TU -->|"supports"| TP

  TC -->|"supplies"| BS
  TUC -->|"supplies"| BS
  MC -->|"supplies"| BS
  GC -->|"configures"| BS

  LS -->|"triggers"| RP
  TT -->|"triggers"| BS
  BR -->|"triggers"| RP

  RP -->|"outputs"| RES_DIR
  BS -->|"logs"| RES_DIR
  RB -->|"logs"| RES_DIR

  %% Styles
  classDef data fill:#a2d2ff,stroke:#31708f,stroke-width:2px;
  classDef training fill:#bde0fe,stroke:#2a9d8f,stroke-width:2px;
  classDef model fill:#ffadad,stroke:#e63946,stroke-width:2px;
  classDef config fill:#ffbf69,stroke:#e76f51,stroke-width:2px;
  classDef orchestration fill:#ffe066,stroke:#f4a261,stroke-width:2px;
  classDef results fill:#f7d794,stroke:#e9c46a,stroke-width:2px;

  %% Click Events
  click DS "https://github.com/jose-melo/t-jepa/tree/main/src/datasets"
  click AD "https://github.com/jose-melo/t-jepa/blob/main/src/datasets/adult_income.py"
  click AL "https://github.com/jose-melo/t-jepa/blob/main/src/datasets/aloi.py"
  click RP "https://github.com/jose-melo/t-jepa/blob/main/run.py"
  click TP "https://github.com/jose-melo/t-jepa/blob/main/src/train.py"
  click TTE "https://github.com/jose-melo/t-jepa/blob/main/src/tjepa_transformer.py"
  click AINT "https://github.com/jose-melo/t-jepa/blob/main/src/models/autoint.py"
  click DCN "https://github.com/jose-melo/t-jepa/blob/main/src/models/dcnv2.py"
  click FT "https://github.com/jose-melo/t-jepa/blob/main/src/models/fttransformer.py"
  click MLP_NODE "https://github.com/jose-melo/t-jepa/blob/main/src/models/mlp.py"
  click RES "https://github.com/jose-melo/t-jepa/blob/main/src/models/resnet.py"
  click BS "https://github.com/jose-melo/t-jepa/blob/main/benchmark.py"
  click RB "https://github.com/jose-melo/t-jepa/blob/main/run_benchmark.py"
  click TC "https://github.com/jose-melo/t-jepa/tree/main/src/benchmark/tuned_config"
  click TUC "https://github.com/jose-melo/t-jepa/tree/main/src/benchmark/tuning_config"
  click MC "https://github.com/jose-melo/t-jepa/tree/main/src/benchmark/model_configs"
  click GC "https://github.com/jose-melo/t-jepa/blob/main/src/configs.py"
  click LU "https://github.com/jose-melo/t-jepa/blob/main/src/utils/log_utils.py"
  click TU "https://github.com/jose-melo/t-jepa/blob/main/src/utils/train_utils.py"
  click LS "https://github.com/jose-melo/t-jepa/blob/main/scripts/launch_tjepa.sh"
  click TT "https://github.com/jose-melo/t-jepa/tree/main/scripts/tjepa_tuning"
  click BR "https://github.com/jose-melo/t-jepa/tree/main/scripts/bench_random_seed"
  click RES_DIR "https://github.com/jose-melo/t-jepa/tree/main/results"
```
