# ghassen-fatnassi/aibutlowlevel architecture

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

- Interactive diagram: https://gitdiagram.com/ghassen-fatnassi/aibutlowlevel
- Repository: https://github.com/ghassen-fatnassi/aibutlowlevel

## Overview

##### Project type and purpose
- This is an open-source “from-scratch” AI-model implementation library (AiButLowLevel).
- Purpose: demonstrate and experiment with core neural architectures in pure Python (and small C++ auto-diff stubs), grouped by model family (Attention, GANs, VAEs, Stable Diffusion, DeepRL, JAX tutorials).

##### File structure
- Top-level:
- LICENSE, .gitignore, README.md
- src/ – all code lives here
- Under src/:
- Attention/ – Python implementations of MHA variants, Shared utilities
- GANs/ – VanillaGAN.py
- General/ – Unet.py (general image-to-image backbone)
- VAEs/ – VAE.py, ConvVAE.py
- StableDiffusion/ – end-to-end pipeline broken into encoder, decoder, diffusion, attention, CLIP, model loader/converter
- DeepRL/ – comparison of PID vs DQN vs DoubleDQN
- jax_hell/ – JAX‐based tutorials (GMM, N-gram, CNN, Kalman filter, etc.) with embedded MNIST raw data
- .cph/ and *.cpp – C++ stubs for custom auto-diff (FMAutoDiff.cpp, RMAutoDiff.cpp)

##### Key insights from README
- Lists which models are implemented vs planned.
- Confirms focus on core algorithmic code, no “service” or “UI” layer.

- Model-Family Modules:
- Attention Module
- GAN Module
- VAE Module
- Stable Diffusion Module
- DeepRL Module
- Utility Modules:
- General (Unet)
- jax_hell (JAX experiments + data)
- C++ AutoDiff Layer
- External Dependencies (at the edge):
- Numpy / PyTorch / JAX
- Raw MNIST data (under jax_hell/data)

b. Relationships & interactions
- StableDiffusion pipeline invoking attention.py, clip.py, encoder/decoder, diffusion, model_loader.
- That General/Unet may be imported by multiple modules (e.g., VAEs or StableDiffusion).

c. Architectural patterns or principles
- Modular, folder-per-model-family pattern
- Layered pipeline in StableDiffusion (encoder → diffusion → decoder → pipeline)
- Separation of core algorithms (python) vs performance stubs (C++)
- Experimentation vs production code clearly separated

d. Key frameworks & libraries
- Python: torch, jax, numpy
- C++: custom auto-diff prototypes

- Use clear labels for each module/folder.
- Blue = Python model families
- Green = Utility/experiment modules
- Orange = C++ stubs
- Gray = external libraries or raw data

##### Detail
- Every sub-pipeline in StableDiffusion (5+ internal components).
- Standalone nature of DeepRL comparative scripts.
- Shareable code (General/Unet used by multiple model types).
- Call out the .cph hidden directory as the build/cache area.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Libraries and Data
    subgraph "External Dependencies"
        direction TB
        Torch["PyTorch"]:::external
        JAX["JAX"]:::external
        Numpy["NumPy"]:::external
    end

    %% Model Family Modules
    subgraph "Model Families"
        direction TB
        Attention["Attention Module"]:::model
        GAN["GAN Module"]:::model
        VAEs["VAE Module"]:::model
        SD["Stable Diffusion Module"]:::model
        DRL["DeepRL Module"]:::model
    end

    %% Utility Modules
    subgraph "Utility & Experiments"
        direction TB
        Unet["General Unet Utility"]:::util
        JAXhell["jax_hell Tutorials"]:::util
    end

    %% C++ AutoDiff Layer
    subgraph "C++ AutoDiff Stubs"
        direction TB
        FMAuto["FMAutoDiff.cpp"]:::cpp
        RMAuto["RMAutoDiff.cpp"]:::cpp
        CPH[".cph Cache Dir"]:::cpp
    end

    %% Stable Diffusion Components
    subgraph "StableDiffusion Pipeline" 
        direction TB
        SD_Enc["encoder.py"]:::model
        SD_Diff["diffusion.py"]:::model
        SD_DDPM["ddpm.py"]:::model
        SD_Dec["decoder.py"]:::model
        SD_Attn["attention.py"]:::model
        SD_CLIP["clip.py"]:::model
        SD_Loader["model_loader.py"]:::model
        SD_Conv["model_converter.py"]:::model
        SD_Pipe["pipeline.py"]:::model
    end

    %% jax_hell Data
    subgraph "MNIST Raw Data"
        direction TB
        MNIST["Raw MNIST Files"]:::external
    end

    %% Relationships: Dependencies
    Attention -->|imports| Torch
    GAN -->|imports| Torch
    GAN -->|imports| Numpy
    VAEs -->|imports| Torch
    VAEs -->|imports| Numpy
    DRL -->|imports| Torch
    DRL -->|imports| Numpy
    JAXhell -->|imports| JAX
    JAXhell -->|uses| MNIST

    Unet -->|used by| VAEs
    Unet -->|used by| SD
    FMAuto -->|planned integration| Attention
    RMAuto -->|planned integration| GAN
    CPH -->|cache for| FMAuto

    %% Stable Diffusion Pipeline flows
    SD --> SD_Pipe
    SD_Pipe -->|calls| SD_Enc
    SD_Pipe -->|calls| SD_Diff
    SD_Pipe -->|calls| SD_Dec
    SD_Pipe -->|uses| SD_Attn
    SD_Pipe -->|uses| SD_CLIP
    SD_Pipe -->|loads model| SD_Loader
    SD_Loader -->|converts with| SD_Conv

    %% Model Families group to specific modules
    SD -->|folder| SD_Enc
    SD --> SD_Diff
    SD --> SD_DDPM
    SD --> SD_Dec
    SD --> SD_Attn
    SD --> SD_CLIP
    SD --> SD_Loader
    SD --> SD_Conv
    SD --> SD_Pipe

    %% Click Events
    click Attention "https://github.com/ghassen-fatnassi/aibutlowlevel/tree/main/src/Attention"
    click GAN "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/GANs/VanillaGAN.py"
    click VAEs "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/VAEs/VAE.py"
    click VAEs "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/VAEs/ConvVAE.py"
    click SD "https://github.com/ghassen-fatnassi/aibutlowlevel/tree/main/src/StableDiffusion"
    click SD_Attn "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/attention.py"
    click SD_CLIP "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/clip.py"
    click SD_DDPM "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/ddpm.py"
    click SD_Diff "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/diffusion.py"
    click SD_Enc "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/encoder.py"
    click SD_Dec "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/decoder.py"
    click SD_Conv "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/model_converter.py"
    click SD_Loader "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/model_loader.py"
    click SD_Pipe "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/StableDiffusion/pipeline.py"
    click DRL "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/DeepRL/PID_vs_DQN_vs_DoubleDQN/VanillaDQN.py"
    click Unet "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/General/Unet.py"
    click JAXhell "https://github.com/ghassen-fatnassi/aibutlowlevel/tree/main/src/jax_hell"
    click MNIST "https://github.com/ghassen-fatnassi/aibutlowlevel/tree/main/src/jax_hell/data/MNIST/raw"
    click FMAuto "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/FMAutoDiff.cpp"
    click RMAuto "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/RMAutoDiff.cpp"
    click CPH "https://github.com/ghassen-fatnassi/aibutlowlevel/blob/main/src/.cph/.FMAutoDiff.cpp_13eb4a13c75e22eaa4b05ee09193500d.prob"

    %% Styles
    classDef model fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef util fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef cpp fill:#ffa500,stroke:#000,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px;
```
