# bhangun/alkhawarizm architecture

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

- Interactive diagram: https://gitdiagram.com/bhangun/alkhawarizm
- Repository: https://github.com/bhangun/alkhawarizm

## Overview

Al-Khawarizm is a Java foundation for tensor math, model topology, weight handling, and hardware execution—not a text-generation or training-loop application. The principal workflow is that a downstream engine selects a model family and device, loads model weights, then uses neural-network primitives and a compute backend for forward-pass operations. The README also documents autograd for downstream training and model conversion, quantization, and RAG-related capabilities. Several links below reflect README-level architecture rather than inspected runtime wiring; unsampled implementation details are represented at their existing module directories.

Main entry points: [`core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/backend/ComputeBackend.java`](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/backend/ComputeBackend.java) (Compute backend SPI), [`models`](https://github.com/bhangun/alkhawarizm/tree/main/models) (Model families), [`core/alkhawarizm-nn/src/main/java/tech/kayys/alkhawarizm/core/nn/NNModule.java`](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-nn/src/main/java/tech/kayys/alkhawarizm/core/nn/NNModule.java) (NN primitives), [`core/alkhawarizm-safetensor-spi/src/main/java/tech/kayys/alkhawarizm/safetensor/spi/SafetensorEngine.java`](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-safetensor-spi/src/main/java/tech/kayys/alkhawarizm/safetensor/spi/SafetensorEngine.java) (SafeTensor engine SPI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model topology"]
  node_families["Model families"]
  node_modelspi["Model SPI<br/>[ModelConfig.java]"]
  node_nn["NN primitives<br/>[NNModule.java]"]
end

subgraph group_weights["Weights and formats"]
  node_safetensor["SafeTensor loading"]
  node_safetensorspi["SafeTensor engine SPI"]
  node_quant["Weight quantization"]
  node_ggufload["GGUF loading<br/>[GGUFLoader.java]"]
  node_ggufconvert["GGUF conversion<br/>[GGUFConverter.java]"]
  node_storage["Model storage SPI"]
end

subgraph group_compute["Tensor compute"]
  node_tensor["Tensor API<br/>[Tensor.java]"]
  node_backendspi["Compute backend SPI"]
  node_memory["Inference memory"]
end

subgraph group_hardware["Hardware backends"]
  node_cpu["CPU backend<br/>[CpuBackend.java]"]
  node_cuda["CUDA backend<br/>[CUDABackend.java]"]
  node_metal["Metal backend"]
  node_rocm["ROCm backend"]
  node_blackwell["Blackwell backend"]
end

subgraph group_extensions["Supporting capabilities"]
  node_autograd["Autograd"]
  node_rag["RAG API<br/>[RagPipeline.java]"]
  node_sd["Diffusion pipeline"]
  node_whisper["Speech pipeline"]
end

node_engine(("Downstream engine"))

node_engine -->|"uses contracts"| node_modelspi
node_engine -->|"uses topology"| node_families
node_families -->|"implements SPI"| node_modelspi
node_engine -->|"loads models"| node_safetensorspi
node_safetensorspi -.->|"loads weights"| node_safetensor
node_engine -.->|"loads GGUF"| node_ggufload
node_engine -.->|"stores artifacts"| node_storage
node_engine -.->|"quantizes weights"| node_quant
node_engine -->|"executes topology"| node_nn
node_nn -->|"operates on"| node_tensor
node_tensor -->|"dispatches compute"| node_backendspi
node_engine -.->|"uses memory"| node_memory
node_backendspi -->|"implemented by"| node_cpu
node_backendspi -->|"implemented by"| node_cuda
node_backendspi -->|"implemented by"| node_metal
node_backendspi -->|"implemented by"| node_rocm
node_backendspi -.->|"implemented by"| node_blackwell
node_ggufconvert -.->|"produces format"| node_ggufload
node_engine -->|"uses gradients"| node_autograd
node_engine -.->|"uses RAG API"| node_rag
node_engine -.->|"uses model pipeline"| node_sd
node_engine -.->|"uses speech pipeline"| node_whisper

click node_families "https://github.com/bhangun/alkhawarizm/tree/main/models"
click node_modelspi "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-spi-model/src/main/java/tech/kayys/alkhawarizm/spi/model/ModelConfig.java"
click node_nn "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-nn/src/main/java/tech/kayys/alkhawarizm/core/nn/NNModule.java"
click node_tensor "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/tensor/Tensor.java"
click node_backendspi "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/backend/ComputeBackend.java"
click node_memory "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/memory/InferenceSession.java"
click node_safetensor "https://github.com/bhangun/alkhawarizm/tree/main/core/alkhawarizm-safetensor-loader"
click node_safetensorspi "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-safetensor-spi/src/main/java/tech/kayys/alkhawarizm/safetensor/spi/SafetensorEngine.java"
click node_quant "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-safetensor-quantization/src/main/java/tech/kayys/alkhawarizm/safetensor/quantization/QuantizationEngine.java"
click node_ggufload "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-gguf-core/src/main/java/tech/kayys/alkhawarizm/gguf/loader/GGUFLoader.java"
click node_ggufconvert "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-gguf-converter/src/main/java/tech/kayys/alkhawarizm/converter/GGUFConverter.java"
click node_storage "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-spi-model/src/main/java/tech/kayys/alkhawarizm/spi/model/ModelStorageService.java"
click node_cpu "https://github.com/bhangun/alkhawarizm/blob/main/backend/cpu/alkhawarizm-backend-cpu/src/main/java/tech/kayys/alkhawarizm/backend/cpu/CpuBackend.java"
click node_cuda "https://github.com/bhangun/alkhawarizm/blob/main/backend/cuda/alkhawarizm-backend-cuda/src/main/java/tech/kayys/alkhawarizm/backend/cuda/CUDABackend.java"
click node_metal "https://github.com/bhangun/alkhawarizm/blob/main/backend/metal/alkhawarizm-backend-metal/src/main/java/tech/kayys/alkhawarizm/backend/metal/MetalComputeBackend.java"
click node_rocm "https://github.com/bhangun/alkhawarizm/blob/main/backend/rocm/alkhawarizm-kernel-rocm/src/main/java/tech/kayys/alkhawarizm/rocm/binding/RocmHipBinding.java"
click node_blackwell "https://github.com/bhangun/alkhawarizm/blob/main/backend/blackwell/alkhawarizm-kernel-blackwell/src/main/java/tech/kayys/alkhawarizm/blackwell/binding/BlackwellBinding.java"
click node_autograd "https://github.com/bhangun/alkhawarizm/blob/main/core/autograd/src/main/java/tech/kayys/alkhawarizm/autograd/AutogradEngine.java"
click node_rag "https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-safetensor-api/src/main/java/tech/kayys/alkhawarizm/safetensor/api/RagPipeline.java"
click node_sd "https://github.com/bhangun/alkhawarizm/blob/main/models/alkhawarizm-model-common/src/main/java/tech/kayys/alkhawarizm/models/StableDiffusionPipeline.java"
click node_whisper "https://github.com/bhangun/alkhawarizm/blob/main/models/alkhawarizm-model-common/broken_models/WhisperPipeline.java"

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_families,node_modelspi,node_nn toneBlue
class node_safetensor,node_safetensorspi,node_quant,node_ggufload,node_ggufconvert,node_storage toneAmber
class node_tensor,node_backendspi,node_memory toneMint
class node_cpu,node_cuda,node_metal,node_rocm,node_blackwell toneRose
class node_autograd,node_rag,node_sd,node_whisper,node_engine toneIndigo
```

## Components

### Model topology

- [Model families](https://github.com/bhangun/alkhawarizm/tree/main/models): `models`
- [Model SPI](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-spi-model/src/main/java/tech/kayys/alkhawarizm/spi/model/ModelConfig.java): `core/alkhawarizm-spi-model/src/main/java/tech/kayys/alkhawarizm/spi/model/ModelConfig.java`
- [NN primitives](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-nn/src/main/java/tech/kayys/alkhawarizm/core/nn/NNModule.java): `core/alkhawarizm-nn/src/main/java/tech/kayys/alkhawarizm/core/nn/NNModule.java`

### Weights and formats

- [SafeTensor loading](https://github.com/bhangun/alkhawarizm/tree/main/core/alkhawarizm-safetensor-loader): `core/alkhawarizm-safetensor-loader`
- [SafeTensor engine SPI](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-safetensor-spi/src/main/java/tech/kayys/alkhawarizm/safetensor/spi/SafetensorEngine.java): `core/alkhawarizm-safetensor-spi/src/main/java/tech/kayys/alkhawarizm/safetensor/spi/SafetensorEngine.java`
- [Weight quantization](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-safetensor-quantization/src/main/java/tech/kayys/alkhawarizm/safetensor/quantization/QuantizationEngine.java): `core/alkhawarizm-safetensor-quantization/src/main/java/tech/kayys/alkhawarizm/safetensor/quantization/QuantizationEngine.java`
- [GGUF loading](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-gguf-core/src/main/java/tech/kayys/alkhawarizm/gguf/loader/GGUFLoader.java): `core/alkhawarizm-gguf-core/src/main/java/tech/kayys/alkhawarizm/gguf/loader/GGUFLoader.java`
- [GGUF conversion](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-gguf-converter/src/main/java/tech/kayys/alkhawarizm/converter/GGUFConverter.java): `core/alkhawarizm-gguf-converter/src/main/java/tech/kayys/alkhawarizm/converter/GGUFConverter.java`
- [Model storage SPI](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-spi-model/src/main/java/tech/kayys/alkhawarizm/spi/model/ModelStorageService.java): `core/alkhawarizm-spi-model/src/main/java/tech/kayys/alkhawarizm/spi/model/ModelStorageService.java`

### Tensor compute

- [Tensor API](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/tensor/Tensor.java): `core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/tensor/Tensor.java`
- [Compute backend SPI](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/backend/ComputeBackend.java): `core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/backend/ComputeBackend.java`
- [Inference memory](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/memory/InferenceSession.java): `core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/memory/InferenceSession.java`

### Hardware backends

- [CPU backend](https://github.com/bhangun/alkhawarizm/blob/main/backend/cpu/alkhawarizm-backend-cpu/src/main/java/tech/kayys/alkhawarizm/backend/cpu/CpuBackend.java): `backend/cpu/alkhawarizm-backend-cpu/src/main/java/tech/kayys/alkhawarizm/backend/cpu/CpuBackend.java`
- [CUDA backend](https://github.com/bhangun/alkhawarizm/blob/main/backend/cuda/alkhawarizm-backend-cuda/src/main/java/tech/kayys/alkhawarizm/backend/cuda/CUDABackend.java): `backend/cuda/alkhawarizm-backend-cuda/src/main/java/tech/kayys/alkhawarizm/backend/cuda/CUDABackend.java`
- [Metal backend](https://github.com/bhangun/alkhawarizm/blob/main/backend/metal/alkhawarizm-backend-metal/src/main/java/tech/kayys/alkhawarizm/backend/metal/MetalComputeBackend.java): `backend/metal/alkhawarizm-backend-metal/src/main/java/tech/kayys/alkhawarizm/backend/metal/MetalComputeBackend.java`
- [ROCm backend](https://github.com/bhangun/alkhawarizm/blob/main/backend/rocm/alkhawarizm-kernel-rocm/src/main/java/tech/kayys/alkhawarizm/rocm/binding/RocmHipBinding.java): `backend/rocm/alkhawarizm-kernel-rocm/src/main/java/tech/kayys/alkhawarizm/rocm/binding/RocmHipBinding.java`
- [Blackwell backend](https://github.com/bhangun/alkhawarizm/blob/main/backend/blackwell/alkhawarizm-kernel-blackwell/src/main/java/tech/kayys/alkhawarizm/blackwell/binding/BlackwellBinding.java): `backend/blackwell/alkhawarizm-kernel-blackwell/src/main/java/tech/kayys/alkhawarizm/blackwell/binding/BlackwellBinding.java`

### Supporting capabilities

- [Autograd](https://github.com/bhangun/alkhawarizm/blob/main/core/autograd/src/main/java/tech/kayys/alkhawarizm/autograd/AutogradEngine.java): `core/autograd/src/main/java/tech/kayys/alkhawarizm/autograd/AutogradEngine.java`
- [RAG API](https://github.com/bhangun/alkhawarizm/blob/main/core/alkhawarizm-safetensor-api/src/main/java/tech/kayys/alkhawarizm/safetensor/api/RagPipeline.java): `core/alkhawarizm-safetensor-api/src/main/java/tech/kayys/alkhawarizm/safetensor/api/RagPipeline.java`
- [Diffusion pipeline](https://github.com/bhangun/alkhawarizm/blob/main/models/alkhawarizm-model-common/src/main/java/tech/kayys/alkhawarizm/models/StableDiffusionPipeline.java): `models/alkhawarizm-model-common/src/main/java/tech/kayys/alkhawarizm/models/StableDiffusionPipeline.java`
- [Speech pipeline](https://github.com/bhangun/alkhawarizm/blob/main/models/alkhawarizm-model-common/broken_models/WhisperPipeline.java): `models/alkhawarizm-model-common/broken_models/WhisperPipeline.java`

### Other components

- **Downstream engine**

## Connections

- Downstream engine → Model SPI: uses contracts (evidence: `README.md`)
- Downstream engine → Model families: uses topology (evidence: `README.md`)
- Model families → Model SPI: implements SPI (evidence: `README.md`)
- Downstream engine → SafeTensor engine SPI: loads models (evidence: `core/alkhawarizm-safetensor-spi/src/main/java/tech/kayys/alkhawarizm/safetensor/spi/SafetensorEngine.java`)
- SafeTensor engine SPI → SafeTensor loading: loads weights
- Downstream engine → GGUF loading: loads GGUF
- Downstream engine → Model storage SPI: stores artifacts
- Downstream engine → Weight quantization: quantizes weights
- Downstream engine → NN primitives: executes topology (evidence: `README.md`)
- NN primitives → Tensor API: operates on (evidence: `core/alkhawarizm-nn/src/main/java/tech/kayys/alkhawarizm/core/nn/NNModule.java`)
- Tensor API → Compute backend SPI: dispatches compute (evidence: `core/alkhawarizm-tensor/src/main/java/tech/kayys/alkhawarizm/core/tensor/Tensor.java`)
- Downstream engine → Inference memory: uses memory
- Compute backend SPI → CPU backend: implemented by (evidence: `README.md`)
- Compute backend SPI → CUDA backend: implemented by (evidence: `README.md`)
- Compute backend SPI → Metal backend: implemented by (evidence: `README.md`)
- Compute backend SPI → ROCm backend: implemented by (evidence: `README.md`)
- Compute backend SPI → Blackwell backend: implemented by
- GGUF conversion → GGUF loading: produces format
- Downstream engine → Autograd: uses gradients (evidence: `README.md`)
- Downstream engine → RAG API: uses RAG API
- Downstream engine → Diffusion pipeline: uses model pipeline
- Downstream engine → Speech pipeline: uses speech pipeline
