diff --git a/.github/workflows/github-package.yml b/.github/workflows/github-package.yml new file mode 100644 index 0000000..cbcb92a --- /dev/null +++ b/.github/workflows/github-package.yml @@ -0,0 +1,44 @@ +name: Publish GitHub Package + +on: + workflow_dispatch: + push: + tags: + - "v*" + +permissions: + contents: read + packages: write + +jobs: + publish-github-package: + name: Publish to GitHub Packages + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Node.js for GitHub Packages + uses: actions/setup-node@v4 + with: + node-version: "20" + registry-url: "https://npm.pkg.github.com" + scope: "@eamon2009" + cache: "npm" + cache-dependency-path: frontend/package-lock.json + + - name: Build frontend assets + run: | + npm --prefix frontend ci + npm --prefix frontend run build + + - name: Prepare GitHub Packages metadata + run: | + npm pkg set name="@eamon2009/quadtrix" + npm pkg set publishConfig.registry="https://npm.pkg.github.com" + + - name: Publish package + run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index f86d76f..82e644e 100644 --- a/.gitignore +++ b/.gitignore @@ -14,4 +14,3 @@ engine/fine-tune/input.txt *best_model.pt *.pt *exe -PUBLISHING.md \ No newline at end of file diff --git a/README.md b/README.md index 8c5685c..2f5dea3 100644 --- a/README.md +++ b/README.md @@ -1,565 +1,971 @@ # Quadtrix.cpp -

-image +Quadtrix.cpp is a local language model project with several execution paths: - - - -

+- A dependency-free C++17 transformer implementation with manual forward and backward passes. +- A PyTorch training and inference path for faster experimentation on CPU, CUDA, or supported accelerator backends. +- A FastAPI middleware layer for chat sessions, health checks, backend selection, and feedback. +- A React + TypeScript frontend for local chat, settings, session history, and model status. +- Optional package/CLI support through `bin/quadtrix.js`. -[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) -[[Release](https://github.com/Eamon2009/Quadtrix.cpp/releases/tag/v1.01)] -## Quadtrix.cpp a autoregressive language model in two variants: +> [!IMPORTANT] +> Please be aware that several commands listed in this documentation—specifically those involving file paths and directory navigation—should not be directly copied and pasted into your terminal. Because file structures and path syntax (such as / vs \) vary significantly across operating systems like Windows, macOS, and Linux, you must manually adjust these arguments to match your local environment. Ensure you verify your current working directory and replace any placeholder paths with the absolute or relative path specific to your machine to avoid execution errors. -CPU Implementation (C++17): Fully custom from-scratch implementation with zero external dependencies. Features a hand-rolled Tensor class with manual gradient tracking, explicit forward/backward passes through transformer blocks (multi-head self-attention, feedforward MLPs, layer normalization), AdamW optimizer with momentum and weight decay, and cross-entropy loss. All operations—matrix multiplications, softmax, GELU activations, attention scoring—are raw C++ arithmetic with no framework overhead. +The project is designed as a technical learning implementation. The C++ path exposes the transformer internals directly: tensor operations, attention, layer normalization, cross-entropy, analytical gradients, AdamW, checkpointing, and autoregressive generation. +## v1.1.0 +run_20260508_110726 -GPU Implementation (PyTorch + CUDA): Architecturally identical transformer (same layer configs, attention heads, embedding dimensions) but delegates tensor operations to PyTorch's CUDA backend for GPU parallelization. The model structure remains unchanged; only the compute substrate shifts from CPU to GPU tensor cores. +--- +run_20260430_192930 -Training Pipeline: Both versions follow standard autoregressive training: tokenize input text → forward pass through embedding + N transformer blocks → compute cross-entropy loss on next-token predictions → backpropagation to compute gradients → AdamW weight updates. Repeated over batches until convergence. +--- +## Contents + +- [System Architecture](#system-architecture) +- [Repository Structure](#repository-structure) +- [Requirements](#requirements) +- [Setup](#setup) +- [Run the Project](#run-the-project) +- [C++ Backend](#c-backend) +- [PyTorch Backend](#pytorch-backend) +- [FastAPI Backend](#fastapi-backend) +- [Frontend](#frontend) +- [NPM CLI](#npm-cli) +- [Configuration](#configuration) +- [API Reference](#api-reference) +- [Training Details](#training-details) +- [Reports and Results](#reports-and-results) +- [Troubleshooting](#troubleshooting) +- [License](#license) + +## System Architecture + +Quadtrix has four main layers: + +```text +User Interface + React + Vite frontend + PWA assets and service worker + +API Layer + FastAPI app in backend/ + Session storage, request validation, CORS, health checks + +Model Backends + C++ executable: main.cpp + include/ + PyTorch checkpoint: engine/inference.py + engine/best_model.pt or engine/best_model .pt + +Training and Data + C++ character-level training from data/input.txt + PyTorch GPT-2 BPE training from engine/input.txt or QUADTRIX_TRAIN_DATA +``` -GPU Extension Limitation: A native CUDA implementation (custom kernels for matrix ops, attention, etc.) requires access to NVIDIA hardware for development and testing, currently unavailable. The PyTorch version serves as a GPU-accelerated alternative without requiring hand-written CUDA -image +### Backend Modes +| Backend | Path | Purpose | +|---|---|---| +| C++ CPU | `main.cpp`, `include/`, `config/` | Manual transformer training, generation, terminal chat | +| PyTorch | `engine/main.py`, `engine/inference.py` | Faster training/inference with `torch` and `tiktoken` | +| iGPU | `iGPU/` | Experimental integrated-GPU inference/training scripts | +| API | `backend/main.py` | FastAPI middleware used by the frontend | +| Web UI | `frontend/` | Local chat interface and PWA shell | +## Repository Structure ---- -# Leaderboard -| s.no | time | val_bpb | CORE | Description | Date | Contributors | -|---|-------------|---------|------|-------------|------|--------------| -| 0 | 39.4 min | 1.3145 | 0.82M | Quadtrix CPU baseline, small data (200K chars), fragmented output | 2026 | @Eamon2009 | -| 1 | 61.3 min | 0.7176 | 10.82M |Quadtrix Colab large-scale run, coherent paragraphs, strong convergence | 2026 | @Eamon2009 | -| 2 | 6.1 min | 0.9250 | 1.99M | Quadtrix T4 optimized run, fast training, stable learning, basic coherence | 2026 | @Eamon2009 | -| 3 | 76.2 min | 1.6371 | ~0.82M | Quadtrix.cpp Extended CPU training (3000 iters) | 2026 | @Eamon2009 | ---- +This is the current project layout, excluding generated caches such as `.git/`, `.venv/`, `.npm-cache/`, and build outputs. -### Hardware Execution Backends +```text +Quadtrix.cpp/ +|-- .github/ +| |-- ISSUE_TEMPLATE/ +| |-- workflows/ +| | |-- ci.yml +| | `-- release.yml +| |-- dependabot.yml +| `-- pull_request_template.md +|-- backend/ +| |-- middleware/ +| | |-- error_handler.py +| | |-- logging.py +| | `-- __init__.py +| |-- router/ +| | |-- chat.py +| | |-- feedback.py +| | |-- health.py +| | |-- sessions.py +| | `-- __init__.py +| |-- README.md +| |-- config.py +| |-- inference.py +| |-- main.py +| |-- models.py +| |-- requirements.txt +| |-- server.py +| `-- session_store.py +|-- bin/ +| `-- quadtrix.js +|-- config/ +| `-- config.h +|-- data/ +| |-- data_set.py +| `-- input.txt +|-- engine/ +| |-- data/ +| | |-- data_set.py +| | `-- input.txt +| |-- fine-tune/ +| | |-- chat.py +| | |-- data-set.py +| | `-- main.py +| |-- logs/ +| |-- engine.c +| |-- export_weights.py +| |-- fineweb_30mb.txt +| |-- fineweb_dataset.py +| |-- inference.py +| `-- main.py +|-- frontend/ +| |-- public/ +| | |-- icon.svg +| | |-- manifest.webmanifest +| | `-- sw.js +| |-- src/ +| | |-- api/ +| | |-- components/ +| | |-- hooks/ +| | |-- store/ +| | |-- types/ +| | |-- utils/ +| | |-- App.tsx +| | |-- index.css +| | |-- main.tsx +| | `-- registerServiceWorker.ts +| |-- index.html +| |-- manifest.webmanifest +| |-- package.json +| |-- tailwind.config.ts +| |-- tsconfig.json +| |-- vite.config.ts +| `-- sw.js +|-- gpu/ +| |-- dataloader.h +| `-- model.h +|-- iGPU/ +| |-- inference.py +| `-- main.py +|-- include/ +| |-- attention.h +| |-- backward.h +| |-- block.h +| |-- dataloader.h +| |-- embedding.h +| |-- feedforward.h +| |-- gpt.h +| |-- layernorm.h +| |-- linear.h +| |-- tensor.h +| `-- torch_bridge.h +|-- model/ +| |-- Cmakelists.txt +| `-- export_tokenizer.py +|-- scripts/ +| `-- build_torch.ps1 +|-- src/ +| |-- torch_example.cpp +| `-- torch_main.cpp +|-- contributing.md +|-- LICENSE +|-- main.cpp +|-- package.json +|-- quadtrix.exe +|-- quadtrix_training_report.png +|-- README.md +|-- run.md +`-- SECURITY.md +``` -| Device | Technical Execution Pathway | -| :--- | :--- | -| **CPU** | Utilizes vectorized instructions (AVX/SSE) and multi-threading for sequential or small-batch inference. | -| **CUDA** | Leverages NVIDIA’s parallel computing platform for high-throughput training and inference on discrete GPUs. | -| **iGPU** | Targets Integrated GPUs (e.g., Intel Iris, AMD Radeon, or Apple Silicon M-series) via backends like **Metal (MPS)**, **DirectML**, or **oneAPI/SYCL**, optimizing for power-efficient local execution. | -## What is this? +### Important Files + +| File | Role | +|---|---| +| `main.cpp` | C++ entry point for training, generation, and terminal chat | +| `config/config.h` | C++ hyperparameters, data path defaults, checkpoint path defaults | +| `include/tensor.h` | Custom tensor operations used by the C++ model | +| `include/gpt.h` | GPT language model implementation and generation path | +| `include/backward.h` | Analytical backpropagation and AdamW optimizer state | +| `data/input.txt` | Default C++ training corpus | +| `engine/main.py` | PyTorch training script | +| `engine/inference.py` | PyTorch checkpoint loading and generation | +| `backend/main.py` | FastAPI application entry point | +| `backend/inference.py` | Backend adapter for PyTorch and C++ model services | +| `frontend/src/` | React chat application | +| `bin/quadtrix.js` | Node CLI wrapper for setup, chat, and training | + +## Requirements + +### Core Requirements + +| Tool | Version | Used For | +|---|---:|---| +| Python | 3.10+ recommended | Backend, PyTorch training, PyTorch inference | +| Node.js | 18+ | Frontend and CLI | +| npm | bundled with Node.js | Frontend dependencies | +| C++ compiler | C++17 support | Building `main.cpp` | +| Git | any recent version | Cloning and source control | + +### Python Dependencies + +The backend installs: + +```text +fastapi +uvicorn[standard] +pydantic +pydantic-settings +httpx +redis +torch +tiktoken +``` -Quadtrix.cpp is a transformer learning laboratory. Write your own backprop, debug attention matrices, export to bare-metal C. If you've read the Attention paper and want to *implement* it rather than just call `model.fit()`, this is for you. +These are declared in `backend/requirements.txt`. -**Philosophy**: Frameworks hide the fundamentals. This project reveals them. Every gradient, every checkpoint, every matrix multiply lives in code you can step through with a debugger. +### C++ Dependencies -**Parallel tracks**: Native C++ training path (educational), PyTorch path (faster iteration), DirectML path (Windows iGPU), pure C inference (deployment), web frontend (chat UI). +The native C++ path has no third-party runtime dependency. It builds from: -## Quick Start +```text +main.cpp +config/config.h +include/*.h +``` -```bash -# Native C++ path - train from scratch -g++ -std=c++17 -O2 -I. -Iinclude -o quadtrix main.cpp -./quadtrix data/input.txt +## Setup -# PyTorch path - faster experimentation -pip install torch tiktoken numpy -python engine/main.py +The commands below use PowerShell from the repository root: -# Interactive chat -./quadtrix data/input.txt --chat -python engine/inference.py +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp ``` -## Overview +### 1. Create a Python Virtual Environment -**Quadtrix** is a self-contained C++17 implementation of a GPT-style transformer language model trained at the character level. It implements the full pipeline — tokenisation, forward pass, analytical backpropagation, and autoregressive generation — in a single dependency-free codebase. +```powershell +python -m venv .venv +.\.venv\Scripts\python.exe -m pip install --upgrade pip +``` -The project is a faithful port of the Python/PyTorch training loop written in C++ with hand-derived gradients for every layer: linear projections, multi-head causal self-attention, layer normalisation, feed-forward blocks, softmax, ReLU, dropout, and cross-entropy loss. +### 2. Install Backend and PyTorch Dependencies -**Training run v1.0** used a 31M-character children's story corpus, reaching a validation loss of **1.6371** in 76 minutes on CPU. +```powershell +cd backend +..\.venv\Scripts\python.exe -m pip install -r requirements.txt +cd .. +``` ---- +### 3. Install Frontend Dependencies -## Architecture - -Quadtrix uses a decoder-only transformer (GPT-2 style) with pre-layer-normalisation residual blocks. - -``` -Input tokens [B, T] - │ - ▼ -Token Embedding [vocab_size × n_embd] - + -Position Embedding [block_size × n_embd] - │ - ▼ -┌─────────────────────────────────┐ -│ Transformer Block × n_layer │ -│ │ -│ ┌──────────────────────────┐ │ -│ │ LayerNorm (pre-LN) │ │ -│ └──────────┬───────────────┘ │ -│ ▼ │ -│ ┌──────────────────────────┐ │ -│ │ Multi-Head Causal Attn │ │ -│ │ n_head × head_size │ │ -│ │ + causal mask │ │ -│ │ + dropout │ │ -│ └──────────┬───────────────┘ │ -│ ▼ (residual +) │ -│ ┌──────────────────────────┐ │ -│ │ LayerNorm (pre-LN) │ │ -│ └──────────┬───────────────┘ │ -│ ▼ │ -│ ┌──────────────────────────┐ │ -│ │ Feed-Forward MLP │ │ -│ │ Linear → ReLU → Linear │ │ -│ │ (4× expansion) +dropout │ │ -│ └──────────┬───────────────┘ │ -│ ▼ (residual +) │ -└─────────────────────────────────┘ - │ - ▼ -LayerNorm → Linear → Logits [B, T, vocab_size] - │ - ▼ -Cross-Entropy Loss / Softmax + Multinomial Sampling -``` - -### Hyperparameters — v1.0 - -| Parameter | Value | Notes | -|------------------|---------|--------------------------------| -| `batch_size` | 4 | Sequences per step | -| `block_size` | 64 | Context window (tokens) | -| `n_embd` | 128 | Embedding dimension | -| `n_head` | 4 | Attention heads | -| `n_layer` | 4 | Transformer blocks | -| `dropout` | 0.2 | Applied to attn weights + proj | -| `learning_rate` | 3e-4 | AdamW, β₁=0.9, β₂=0.999 | -| `max_iters` | 3000 | | -| `eval_interval` | 200 | | -| **Total params** | **0.83 M** | (826,985) | +```powershell +cd frontend +npm.cmd install +cd .. +``` ---- +Use `npm.cmd` on Windows PowerShell if direct `npm` execution is blocked by PowerShell execution policy. + +### 4. Build the Frontend -## Training +```powershell +cd frontend +npm.cmd run build +cd .. +``` -The model was trained on a 31.4M-character corpus of short children's stories (`data/input.txt`), split 90/10 into train and validation sets. +### 5. Build the C++ Executable -| Set | Tokens | -|------------|-------------| -| Train | 28,311,139 | -| Validation | 3,145,683 | -| Vocabulary | 105 characters | +If `quadtrix.exe` already exists, this step is optional. To rebuild: -Training used full **analytical backpropagation** — hand-derived gradients through every operator (cross-entropy → lm_head → layernorm → MHA → FFN → embeddings) without any automatic differentiation library. +```powershell +g++ -std=c++17 -O2 -I. -Iinclude -o quadtrix.exe main.cpp +``` -The gradient computation follows this chain: +For extra CPU optimization on GCC/Clang: +```powershell +g++ -std=c++17 -O3 -march=native -I. -Iinclude -o quadtrix.exe main.cpp ``` -dLoss/dLogits → dW_lmhead → d(LayerNorm_f) - → for each Block (reverse): - d(FFN residual) → d(LN2) → d(fc2) → d(ReLU) → d(fc1) - d(MHA residual) → d(LN1) → d(proj) - → for each Head: - d(wei@V) → d(softmax) → d(scale) → d(Q@Kᵀ) - → d(Wk), d(Wq), d(Wv) - → d(tok_emb), d(pos_emb) + +## Run the Project + +Quadtrix UI screenshot + +### Option A: Run PyTorch Chat in the Web UI + +This is the simplest web path when a PyTorch checkpoint is available. + +Terminal 1: + +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\backend +..\.venv\Scripts\python.exe -m uvicorn main:app --host 127.0.0.1 --port 3001 ``` ---- +Terminal 2: -## Training Log - -Training run: **Quadtrix v1.0** - -``` ------------------------------------------------------------- - Quadtrix v1.0 2026 - iter train val elapsed eta - ────────────────────────────────────────────────────── - 0/3000 4.6523 4.6570 15s — [saved] - 200/3000 2.4876 2.4478 427s 5976s [saved] - 400/3000 2.2965 2.3334 783s 5091s [saved] - 600/3000 2.2971 2.2572 1105s 4418s [saved] - 800/3000 2.2424 2.2018 1331s 3660s [saved] - 1000/3000 2.1570 2.2009 1569s 3138s [saved] - 1200/3000 2.0914 2.0577 1791s 2687s [saved] - 1400/3000 1.9575 2.0151 2013s 2301s [saved] - 1600/3000 1.9409 1.9532 2317s 2028s [saved] - 1800/3000 1.8233 1.8250 2673s 1782s [saved] - 2000/3000 1.7386 1.7724 2999s 1500s [saved] - 2200/3000 1.6850 1.7256 3353s 1219s [saved] - 2400/3000 1.7298 1.7403 3697s 924s - 2600/3000 1.7204 1.6680 4031s 620s [saved] - 2800/3000 1.5717 1.6471 4347s 310s [saved] - 3000/3000 1.7055 1.6371 4571s 0s [saved] - ────────────────────────────────────────────────────── - - done - | time : 4571.1s (76.2 min) - | best val : 1.6371 - | weights : best_model.bin ------------------------------------------------------------- -``` - -The model crosses 2.0 val loss around iteration 1200 and continues to improve steadily to **1.6371** — a drop of 3.02 nats from random initialisation. +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\frontend +npm.cmd run dev +``` ---- +Open: -## Inference & Sample Outputs +```text +http://localhost:5173 +``` -Weights are loaded from `best_model.bin` and generation proceeds autoregressively: at each step the model consumes the last `block_size` tokens, computes logits over the vocabulary, applies softmax, and samples the next token from the resulting distribution. +Select the `.pt` or PyTorch backend in the UI. The FastAPI app loads the checkpoint through `engine/inference.py`. -### Chat Transcript +### Option B: Run C++ Terminal Chat -> The following samples were produced by the trained v1.0 checkpoint. -> The model operates at the character level and was trained on children's stories — expect emergent narrative structure, invented words, and short-form prose. +The C++ executable supports terminal chat directly: ---- +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp +.\quadtrix.exe data\input.txt --chat +``` -**You:** hi how are you +Set the number of generated tokens per answer: -**Quadtrix:** +```powershell +.\quadtrix.exe data\input.txt --chat --chat-tokens 300 ``` -said. You big his's reat cably hawere cast wen. Anted the on feer -the girl the heri beg that's appy and happecing apy his. Whe mommmy -had alowith of thad very the rand a coove the ses and the + +The C++ chat path requires `best_model.bin` unless `GPT_MODEL_PATH` points to another checkpoint. + +### Option C: Run C++ Generation + +```powershell +.\quadtrix.exe data\input.txt --generate ``` ---- +Generation streams tokens until interrupted with `Ctrl+C`. -**You:** what is life +### Option D: Train the C++ Model -**Quadtrix:** +```powershell +.\quadtrix.exe data\input.txt ``` -st happe. It happ a liked back abp happy thing flongs way. -"Lily lood take maked a fiside apie?" Tom and abed Timm. -A na starhe of her that they was is they," that and Timmy -flauch seer aing time tri + +Training writes the best checkpoint to: + +```text +best_model.bin ``` ---- +### Option E: Train the PyTorch Model + +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp +.\.venv\Scripts\python.exe engine\main.py +``` -**You:** Timmy is a +The PyTorch script looks for `engine/input.txt` by default. If that file is not present, point the script at an existing corpus with `QUADTRIX_TRAIN_DATA`: -**Quadtrix:** +```powershell +$env:QUADTRIX_TRAIN_DATA="C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\data\input.txt" +.\.venv\Scripts\python.exe engine\main.py ``` -bog the scated justo prove the bret you. Timmy nevery some -the gecid. Her neplay to bet starked a way, that litked cliend. -They shat corsee get. -Ben it lows mured she happlay mom and had says." -Tom + +The PyTorch training script saves its checkpoint as: + +```text +best_model.pt ``` ---- +## C++ Backend + +The C++ implementation is the educational core of the project. + +### C++ Features -**You:** Once upon a time +- Character-level tokenizer built from the input corpus. +- Train/validation split through `DataLoader`. +- Decoder-only transformer architecture. +- Token and positional embeddings. +- Multi-head causal self-attention. +- Feed-forward MLP blocks. +- Pre-layer normalization and residual connections. +- Cross-entropy loss. +- Manual analytical backward pass. +- AdamW optimization. +- Checkpoint saving/loading. +- Autoregressive generation. +- Terminal chat mode. -**Quadtrix:** +### C++ Runtime Arguments + +```text +quadtrix.exe [data_path] [--generate] [--chat] [--chat-tokens N] ``` -, and said askiced and so owas said sri -The his brickerys and stew hhat and saw and stark a din't -She stingry and asked day. Timmy watch and played to cones. -It eve smors and he skiseed auch pived el make + +| Argument | Description | +|---|---| +| `data_path` | Plain-text corpus used to build the tokenizer and train/validation split | +| `--generate` | Load weights and continuously generate text | +| `--chat` | Load weights and start interactive terminal chat | +| `--chat-tokens N` | Set maximum generated tokens per chat response | + +### C++ Environment Variables + +| Variable | Default | Description | +|---|---|---| +| `GPT_DATA_PATH` | `data/input.txt` | Overrides the default C++ data file | +| `GPT_MODEL_PATH` | `best_model.bin` | Overrides the model checkpoint path | + +Example: + +```powershell +$env:GPT_MODEL_PATH="C:\models\quadtrix-best.bin" +.\quadtrix.exe data\input.txt --chat ``` ---- +## PyTorch Backend -### Extended Free Generation +The PyTorch path mirrors the transformer idea with `torch`, `torch.nn`, and `tiktoken`. +### Training + +```powershell +.\.venv\Scripts\python.exe engine\main.py ``` -usidpy the nis the girl Mian in the she foll pot stwed note ful to -snid sids funded araving many to them big strear birng and That the -momn,'s saw and icked aging for the cor dad and spzy ited thankeft -the beecia rear who rah gight sad, and and help ceated and blut the -waye! Shearted started, "Yes. I wout she feare scal the dingred asked -not dearve had s g. It was hat startedry like his -in the the was give grin Lily. -Tim ould and hoppen rand tce to the - faind her time. As and Ben't -the sise askep. It every and sticked Lia loshe wentimed toohld the -cookes and he gagayss in hen greveryby. +Important defaults in `engine/main.py`: + +| Parameter | Value | +|---|---:| +| `batch_size` | 16 | +| `block_size` | 32 | +| `max_iters` | 10000 | +| `eval_interval` | 10 | +| `learning_rate` | 1e-3 | +| `n_embd` | 64 | +| `n_head` | 4 | +| `n_layer` | 4 | +| `dropout` | 0.1 | +| Tokenizer | GPT-2 BPE through `tiktoken` | -One day, here stomed trreave one up in Annamecy it noted Mise with -that make tret a like. +### CLI Inference -Tom." -T'vey, ""As smie, a, "I's wurre and not make day, but tway it? -Lily. The stach, says eveere they am and then a to happprosh apper, -and his plh? That you obo. The garded rike, nothis to fring they -is his ared to shing itsed and old neved the pretoy beard shappy -hingse they him at happy his stroughts have nex's by. +Interactive chat: + +```powershell +.\.venv\Scripts\python.exe engine\inference.py --checkpoint "engine\best_model.pt" ``` -### Observations +Single prompt: -- The model has learned basic English word-level shapes after 3000 iterations despite training at the character level. -- Names (`Timmy`, `Lily`, `Tom`, `Ben`, `Mia`) appear consistently — likely the most frequent tokens in the story corpus. -- Dialogue punctuation (`"`, `'`, `,`) is placed plausibly. -- Sentence-level structure emerges: the model produces recognisable story beats ("One day,", "It was", "and said"). -- At 0.83M parameters and block_size=64, the context window is narrow; longer-range coherence will improve with larger `block_size` and more iterations. +```powershell +.\.venv\Scripts\python.exe engine\inference.py --checkpoint "engine\best_model.pt" --prompt "Once upon a time" --max-new-tokens 100 --temperature 1.0 +``` ---- +Available inference flags: + +| Flag | Description | +|---|---| +| `--checkpoint` | Path to `.pt` checkpoint | +| `--prompt` | Generate once instead of starting interactive chat | +| `--max-new-tokens` | Maximum generated tokens | +| `--temperature` | Sampling temperature | +| `--top-k` | Optional top-k sampling cutoff | + +## FastAPI Backend -## Main Structure +The production-style API lives in `backend/main.py`. +Start it with: + +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\backend +..\.venv\Scripts\python.exe -m uvicorn main:app --host 127.0.0.1 --port 3001 ``` -Quadtrix.cpp/ -├── config/ -│ └── config.h # All hyperparameters — edit here to retrain -├── include/ -│ ├── tensor.h # CPU float tensor: 2D/3D ops, matmul, softmax, etc. -│ ├── linear.h # nn.Linear equivalent (weight + optional bias) -│ ├── embedding.h # nn.Embedding (token + position lookup tables) -│ ├── layernorm.h # nn.LayerNorm (γ/β, ε=1e-5) -│ ├── attention.h # Head (causal mask, scaled dot-product) + MultiHeadAttention -│ ├── feedforward.h # FeedForward: Linear → ReLU → Linear → Dropout -│ ├── block.h # Transformer Block (pre-LN, dual residual) -│ ├── gpt.h # GPTLanguageModel, cross_entropy, generate() -│ ├── dataloader.h # Char tokeniser (stoi/itos), train/val split, get_batch() -│ └── backward.h # Full analytical backprop + AdamW state -├── data/ -│ └── input.txt # Training corpus (plain text) -├── main.cpp # Training pipeline -└── README.md +The FastAPI backend provides: + +- `POST /api/chat` +- `GET /api/health` +- `GET /api/stats` +- session creation/listing/deletion +- message persistence through in-memory or Redis-backed session storage +- feedback capture +- CORS configuration for the frontend +- PyTorch checkpoint loading through `backend/inference.py` + +### Backend Environment + +Create `backend/.env` if you want to override defaults: + +```text +API_PORT=3001 +CORS_ORIGINS=http://localhost:5173 +REDIS_URL= +LOG_LEVEL=INFO +MAX_SESSIONS=1000 +SESSION_TTL_HOURS=24 +CPP_SERVER_URL=http://localhost:8080 +TORCH_CHECKPOINT_PATH=../engine/best_model.pt +REQUEST_TIMEOUT_SECONDS=60 ``` ---- +The checked-in backend default is `../engine/best_model .pt` with a space before `.pt`. If your checkpoint is named `best_model.pt`, set `TORCH_CHECKPOINT_PATH=../engine/best_model.pt` in `backend/.env`. + +Note: the FastAPI C++ adapter expects a C++-compatible HTTP service at `CPP_SERVER_URL` with `/health` and `/generate`. The current `main.cpp` source provides terminal training/chat/generation. Use the PyTorch backend for the web UI unless you have a compatible C++ HTTP service running. -## Building +## Frontend -**Requirements:** GCC ≥ 9 or Clang ≥ 10, C++17, no external dependencies. +The frontend is a React + TypeScript + Vite app. -```bash -# Compile -g++ -std=c++17 -O2 -I. -o quadtrix main.cpp +### Development Server -# Or use Make -make +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\frontend +npm.cmd run dev +``` -# Train on your own text -./quadtrix data/input.txt +Open: -# Generate only (loads best_model.bin) -./quadtrix data/input.txt --generate +```text +http://localhost:5173 ``` ---- +### Production Build + +```powershell +npm.cmd run build +``` + +### Preview Production Build + +```powershell +npm.cmd run preview +``` + +Open the preview URL, usually: + +```text +http://localhost:4173 +``` + +### PWA Files + +The frontend includes installable web app files: + +```text +frontend/manifest.webmanifest +frontend/sw.js +frontend/public/manifest.webmanifest +frontend/public/sw.js +frontend/src/registerServiceWorker.ts +``` + +Install from Chrome or Edge after running the production preview. The installed app still needs the FastAPI backend running at the configured API URL. + +## NPM CLI + +The root package exposes a `quadtrix` CLI through `bin/quadtrix.js`. + +```text +quadtrix chat [--api-port 3001] [--web-port 5173] [--no-open] +quadtrix train --backend cpp [--data data/input.txt] +quadtrix train --backend python +quadtrix setup +``` + +From the repository root: + +```powershell +npm.cmd install +npm.cmd run build:frontend +node bin\quadtrix.js setup +``` + +Run the packaged chat wrapper: + +```powershell +node bin\quadtrix.js chat --api-port 3001 --web-port 5173 +``` + +Train through the wrapper: + +```powershell +node bin\quadtrix.js train --backend cpp --data data\input.txt +node bin\quadtrix.js train --backend python --data data\input.txt +``` ## Configuration -All hyperparameters live in `config/config.h`. Rebuild after any change. +### C++ Configuration + +Edit `config/config.h` and rebuild the C++ executable. ```cpp -// config/config.h +static const int BATCH_SIZE = 4; +static const int BLOCK_SIZE = 64; +static const int MAX_ITERS = 3000; +static const int EVAL_INTERVAL = 200; +static const float LEARNING_RATE = 3e-4f; +static const int EVAL_ITERS = 10; +static const int N_EMBD = 128; +static const int N_HEAD = 4; +static const int N_LAYER = 4; +static const float DROPOUT = 0.2f; +``` -static const int BATCH_SIZE = 4; // sequences per gradient step -static const int BLOCK_SIZE = 64; // context window length -static const int MAX_ITERS = 3000; // total training iterations -static const int EVAL_INTERVAL = 200; // evaluate every N steps -static const float LEARNING_RATE = 3e-4f; // AdamW learning rate -static const int EVAL_ITERS = 10; // batches per eval estimate -static const int N_EMBD = 128; // embedding dimension -static const int N_HEAD = 4; // number of attention heads -static const int N_LAYER = 4; // number of transformer blocks -static const float DROPOUT = 0.2f; // dropout probability +### C++ Model Shape + +| Parameter | Meaning | +|---|---| +| `BATCH_SIZE` | Number of sequences per gradient step | +| `BLOCK_SIZE` | Context length in tokens | +| `N_EMBD` | Embedding width | +| `N_HEAD` | Number of attention heads | +| `N_LAYER` | Number of transformer blocks | +| `DROPOUT` | Dropout probability during training | +| `LEARNING_RATE` | AdamW learning rate | +| `MAX_ITERS` | Total training iterations | +| `EVAL_INTERVAL` | Evaluation/checkpoint interval | + +### Scaling Guide + +| Goal | Change | +|---|---| +| Better local coherence | Increase `BLOCK_SIZE` | +| Higher model capacity | Increase `N_EMBD` and `N_LAYER` | +| Faster CPU runs | Use fewer layers or lower embedding width | +| Faster optimized build | Compile with `-O3 -march=native` | +| More stable loss estimates | Increase `EVAL_ITERS` | + +## API Reference + +Base URL: + +```text +http://localhost:3001 ``` -### Scaling guide +### Health + +```text +GET /api/health +``` -| Target | Suggestion | -|------------------|---------------------------------------------------------| -| Better coherence | ↑ `block_size` (256–512), ↑ `n_embd` (256+) | -| Faster training | ↑ `batch_size`, compile with `-O3 -march=native` | -| Smaller model | ↓ `n_layer` (2), ↓ `n_embd` (64) | -| More parameters | ↑ `n_embd` (512), ↑ `n_layer` (6–8) | +Example: ---- +```powershell +Invoke-RestMethod http://localhost:3001/api/health +``` -## Design Notes +### Stats -### Why C++17, no dependencies? +```text +GET /api/stats +``` -The goal is full transparency. Every multiply-accumulate, every softmax row, every gradient derivation is readable in the source. There is no framework between the math and the metal. +Example: -### Analytical backprop +```powershell +Invoke-RestMethod http://localhost:3001/api/stats +``` -Rather than automatic differentiation, Quadtrix implements explicit backward passes for each operator. The derivations follow the standard formulations: +### Chat -- **Cross-entropy:** `d_logits = softmax(logits) − one_hot(target)` scaled by `1/BT` -- **Linear:** `dX = dOut @ Wᵀ`, `dW += Xᵀ @ dOut`, `db += Σ dOut` -- **LayerNorm:** Ba et al. (2016) three-term formula via saved `μ`, `σ⁻¹`, `x̂` -- **Softmax:** `d_pre[i] = s[i] * (d[i] − Σⱼ s[j] d[j])` -- **ReLU:** `dX[i] = dOut[i] if pre_relu[i] > 0 else 0` -- **Attention:** product rule through `Q @ Kᵀ`, causal mask zeros upper-triangle grads -- **Embeddings:** scatter-add for tokens, batch-sum for positions +```text +POST /api/chat +``` -### Causal masking +PyTorch backend example: + +```powershell +Invoke-RestMethod ` + -Uri http://localhost:3001/api/chat ` + -Method Post ` + -ContentType "application/json" ` + -Body '{ + "session_id": null, + "prompt": "Once upon a time", + "max_tokens": 100, + "temperature": 1.0, + "stream": false, + "model_backend": "torch" + }' +``` -The upper-triangular mask is applied before softmax by setting future positions to `-1e30`. During backprop these positions receive zero gradient (the `-inf` entries have zero softmax output, so `s[i] * (...)` = 0). +C++ backend example, when a compatible C++ HTTP service is available: + +```powershell +Invoke-RestMethod ` + -Uri http://localhost:3001/api/chat ` + -Method Post ` + -ContentType "application/json" ` + -Body '{ + "session_id": null, + "prompt": "Once upon a time", + "max_tokens": 100, + "temperature": 1.0, + "stream": false, + "model_backend": "cpp" + }' +``` + +### Sessions -### Dropout +```text +GET /api/sessions +POST /api/sessions +DELETE /api/sessions/{id} +GET /api/sessions/{id}/messages +``` -Both the attention weight matrix and the projection output have independent dropout masks sampled during each forward pass. The same masks are stored and reused in the backward pass (`d = d * mask / (1 - p)`). +### Feedback ---- -## Training Metrics +```text +POST /api/feedback +``` + +## Training Details + +Quadtrix uses a decoder-only transformer in the GPT family. + +```text +Input token IDs [B, T] + -> token embedding + -> positional embedding + -> transformer block x N + -> layer norm + -> masked multi-head self-attention + -> residual add + -> layer norm + -> feed-forward MLP + -> residual add + -> final layer norm + -> language-model head + -> logits [B, T, vocab_size] + -> cross-entropy loss +``` + +### C++ Manual Backpropagation + +The C++ path implements gradients explicitly through: + +- Cross-entropy and softmax. +- Final projection layer. +- Final layer normalization. +- Feed-forward MLP layers. +- ReLU activation. +- Attention projection. +- Scaled dot-product attention. +- Causal mask. +- Query, key, and value projections. +- Token and positional embeddings. + +Gradient flow: + +```text +dLoss/dLogits + -> lm_head + -> final layer norm + -> each transformer block in reverse + -> feed-forward residual branch + -> layer norm 2 + -> MLP fc2, activation, fc1 + -> attention residual branch + -> layer norm 1 + -> output projection + -> each attention head + -> attention weights @ value + -> softmax + -> scaled QK^T + -> query/key/value projections + -> token embedding gradients + -> position embedding gradients +``` -The training report visualizes three critical dynamics: +### Causal Masking -**Loss curves** (left panel): Cross-entropy decreases from 4.5 to 1.6 over 3000 iterations. Training and validation losses track closely, indicating effective learning without severe overfitting. +Future tokens are masked before softmax so each position can only attend to current and previous positions. Masked entries receive zero useful probability mass and therefore do not contribute meaningful gradient during the attention backward pass. -**Wall-clock efficiency** (middle panel): Linear relationship between validation loss and elapsed time demonstrates consistent GPU utilization and efficient batching. +### Optimizer -**Generalization gap** (right panel): Difference between validation and training loss oscillates around zero with peak divergence of 0.0754. This healthy pattern suggests the model learns general patterns rather than memorizing training data. +The C++ path uses AdamW-style updates with: -**Final metrics**: -- Validation loss: **1.6371** (iteration 3000) -- Training parameters: 0.83M params, 105 vocab tokens, 28.3M training / 3.1M validation tokens -- Architecture: `n_layer=4, n_embd=128` +- First moment estimate. +- Second moment estimate. +- Weight decay. +- Learning-rate-controlled parameter updates. + +## Reports and Results + +### Leaderboard + +| s.no | Time | Val BPB / Loss | Core | Description | Date | Contributors | +|---:|---:|---:|---:|---|---|---| +| 0 | 39.4 min | 1.3145 | 0.82M | Quadtrix CPU baseline, small data, fragmented output | 2026 | @Eamon2009 | +| 1 | 61.3 min | 0.7176 | 10.82M | Quadtrix Colab large-scale run, coherent paragraphs, strong convergence | 2026 | @Eamon2009 | +| 2 | 6.1 min | 0.9250 | 1.99M | Quadtrix T4 optimized run, fast training, stable learning, basic coherence | 2026 | @Eamon2009 | +| 3 | 76.2 min | 1.6371 | ~0.82M | Quadtrix.cpp extended CPU training, 3000 iterations | 2026 | @Eamon2009 | + +### Hardware Execution Backends + +| Device | Execution Path | +|---|---| +| CPU | Native C++ implementation and PyTorch CPU fallback | +| CUDA | PyTorch CUDA acceleration when available | +| iGPU | Experimental scripts for integrated-GPU style execution paths | + +### Training Metrics + +Final C++ run metrics documented in the project: + +| Metric | Value | +|---|---:| +| Validation loss | 1.6371 | +| Parameters | 826,985 | +| Vocabulary | 105 characters | +| Training tokens | ~28.3M | +| Validation tokens | ~3.1M | +| Training time | ~76.2 min | +| Architecture | 4 layers, 4 heads, 128 embedding width | + +### Python (PyTorch) -## Training Comparison & Scaling Analysis -## Python (Pytorch) ![Training Report](quadtrix_training_report.png) -## c++ -Screenshot 2026-04-24 182327 +### C++ -The following table compares three distinct training runs across different architectures and datasets, demonstrating empirical scaling law behavior: +C++ training screenshot -| Metric | **Run 1: Character-Level** | **Run 2: Small Scale** | **Run 3: Large Scale** | -|--------|---------------------------|------------------------|------------------------| -| **Architecture** | | | | +### Training Comparison + +| Metric | Character-Level | Small Scale | Large Scale | +|---|---:|---:|---:| | Parameters | 0.83M | 2.00M | 19.17M | | Layers | 4 | 4 | 4 | | Embedding Dim | 128 | 200 | 200 | | Attention Heads | 4 | 4 | 4 | | Context Length | 64 | 200 | 200 | -| **Dataset** | | | | -| Corpus | `tinystories` | `tinystories` | Children's Stories | -| Vocab Size | 105 (char) | 110 (char) | ~50K (BPE) | -| Training Tokens | 28.3M | 79.6M | Unknown | -| Validation Tokens | 3.1M | 8.8M | Unknown | -| Data Volume | - | 88.5 MB | - | -| **Training Config** | | | | +| Corpus | TinyStories | TinyStories | Children's Stories | +| Vocab Size | 105 char | 110 char | ~50K BPE | | Total Iterations | 3,000 | 5,000 | 5,000 | -| Hardware | CPU/CUDA | CUDA (Tesla T4) | Unknown | -| Wall-Clock Time | ~76 min | 5.97 min | Unknown | -| Throughput | - | ~838 iter/min | - | -| **Final Performance** | | | | -| **Train Loss** | 1.5632 | **0.9045** | Unknown | -| **Val Loss** | **1.6371** | **0.9301** | Unknown | +| Hardware | CPU/CUDA | CUDA T4 | Unknown | +| Final Train Loss | 1.5632 | 0.9045 | Unknown | +| Final Val Loss | 1.6371 | 0.9301 | Unknown | | Generalization Gap | 0.0739 | 0.0256 | Unknown | -| Peak Gap | 0.0754 @ iter 2800 | Unknown | Unknown | -| **Convergence** | | | | -| Initial Loss | 4.5 | 4.6946 | ~5.0 | -| Loss Reduction | 65.7% | 80.2% | ~80% | -| Saved Checkpoints | Every 200 iters | Every 200 iters | Multiple | -| Best Iteration | 3000 | 4999 | Unknown | -### Scaling Law Observations +### Comparison to Related Projects -**1. Parameter Count vs Performance** +| Project | Focus | Language | Autograd | +|---|---|---|---| +| nanoGPT | Minimal GPT training | Python | PyTorch | +| minGPT | Educational GPT | Python | PyTorch | +| llama2.c | Inference-oriented C implementation | C | None | +| Quadtrix.cpp | Training, inference, web UI, multi-backend experiments | C++/Python/TypeScript | Manual C++ + PyTorch | -The relationship between model size and loss follows the expected power law: +## Troubleshooting -``` -L(N) ∝ N^(-α) -``` +### PowerShell Blocks `npm` -Where `N` is parameter count and `α ≈ 0.076` based on our data: -- 0.83M params → Val Loss 1.6371 -- 2.00M params → Val Loss 0.9301 (43.2% reduction for 2.4× params) -- 19.17M params → Expected Val Loss ~0.65-0.75 (extrapolated) +Use: -**2. Data Efficiency** +```powershell +npm.cmd install +npm.cmd run dev +npm.cmd run build +``` -Token scaling shows diminishing returns: -- Run 1: 28.3M tokens @ 1.6371 loss -- Run 2: 79.6M tokens @ 0.9301 loss (2.8× data → 43% loss reduction) +### Python Backend Cannot Import Dependencies -This suggests we're in the data-limited regime where increasing model capacity yields better returns than increasing data alone. +Install dependencies into the repository virtual environment: -**3. Compute Efficiency** +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\backend +..\.venv\Scripts\python.exe -m pip install -r requirements.txt +``` -Run 2 achieved superior performance despite shorter wall-clock time (5.97 min vs 76 min), highlighting the importance of: -- Hardware acceleration (Tesla T4 CUDA) -- Larger batch processing -- Optimized data pipeline +### PyTorch Checkpoint Is Missing -**4. Generalization Dynamics** +Check the configured checkpoint path: -Both runs show healthy train/val convergence: -- Run 1: Final gap of 0.0739 (4.5% relative) -- Run 2: Final gap of 0.0256 (2.8% relative) +```powershell +Test-Path "C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\engine\best_model.pt" +``` -Smaller gap in Run 2 suggests better regularization or more diverse training data per parameter. +If it is missing, train first: -**5. Neural Scaling Law Projection** +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp +.\.venv\Scripts\python.exe engine\main.py +``` -Extrapolating from our empirical data: +### C++ Chat Cannot Find Weights -| Target Loss | Estimated Params | Estimated Tokens | Expected Compute | -|-------------|-----------------|------------------|------------------| -| 1.0 | ~1.5M | ~50M | ~2-3 min (T4) | -| 0.8 | ~3-4M | ~100M | ~8-12 min (T4) | -| 0.6 | ~15-20M | ~300M | ~40-60 min (T4) | -| 0.5 | ~40-50M | ~1B | ~3-5 hours (T4) | +The C++ chat and generation modes need `best_model.bin`. -**Chinchilla-optimal ratio**: For compute-efficient training at this scale, target N ≈ 20 × D (parameters ≈ 20 × training tokens in billions). +Train first: -1. **Scaling works**: Doubling parameters reduces loss by ~30-40% consistently -2. **Hardware matters**: GPU acceleration provides 12× speedup with better loss -3. **Small models saturate quickly**: Beyond 5K iterations, gains diminish without more capacity -4. **Character-level is competitive**: At small scale, character models perform reasonably despite simpler tokenization -5. **Generalization is healthy**: Both runs avoid severe overfitting, suggesting good regularization defaults +```powershell +.\quadtrix.exe data\input.txt +``` +Or point to an existing checkpoint: -## Comparison to Other Projects +```powershell +$env:GPT_MODEL_PATH="C:\path\to\best_model.bin" +.\quadtrix.exe data\input.txt --chat +``` -| Project | Focus | Language | Autograd | -|---------|-------|----------|----------| -| **nanoGPT** | Minimal PyTorch GPT | Python | PyTorch | -| **llama2.c** | Inference only | C | None | -| **minGPT** | Educational PyTorch | Python | PyTorch | -| **Quadtrix.cpp** | Training + inference, multi-backend | C++/Python/C | Manual + PyTorch | +### Frontend Cannot Reach Backend -## Building From Source +Start the FastAPI backend: -**Requirements**: -- C++17 compiler (GCC 7+, Clang 5+, MSVC 2017+) -- Python 3.8+ (for PyTorch paths) -- CMake 3.15+ (for LibTorch experiments) +```powershell +cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\backend +..\.venv\Scripts\python.exe -m uvicorn main:app --host 127.0.0.1 --port 3001 +``` + +Then check: -**Minimal build** (C++ only): -```bash -g++ -std=c++17 -O2 -I. -Iinclude -o quadtrix main.cpp +```powershell +Invoke-RestMethod http://localhost:3001/api/health ``` -**With LibTorch**: -```bash -# Download libtorch from pytorch.org -cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/libtorch -cmake --build build --config Release +### Port Already in Use + +Check common ports: + +```powershell +Get-NetTCPConnection -LocalPort 3001 +Get-NetTCPConnection -LocalPort 5173 +Get-NetTCPConnection -LocalPort 4173 +Get-NetTCPConnection -LocalPort 8080 ``` -**Python environment**: -```bash -python -m venv venv -source venv/bin/activate # Windows: venv\Scripts\activate -pip install torch tiktoken numpy +### Rebuild C++ After Changing Hyperparameters + +Any change in `config/config.h` requires recompilation: + +```powershell +g++ -std=c++17 -O2 -I. -Iinclude -o quadtrix.exe main.cpp ``` ---- -## Reference -- Architecture based on "Attention Is All You Need" (Vaswani et al., 2017) -- GPT-2 (Radford et al., 2019). +## References ---- +- Vaswani et al., "Attention Is All You Need", 2017. +- Radford et al., GPT-2 technical work, 2019. +- nanoGPT and minGPT as educational reference points. ## License MIT - -*Quadtrix.cpp · val loss 1.6371 · 0.83M params · 76 min on CPU* diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b19496f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,73 @@ +# Security Policy + +Quadtrix.cpp is a local-first transformer learning project. The repository includes native C++ code, Python inference and training code, a FastAPI backend, a React frontend, model checkpoints, and sample datasets. Security reports are welcome, especially when they affect local execution, backend API exposure, dependency safety, or handling of model/data files. + +## Supported Versions + +Security fixes are considered for: + +| Version | Supported | +| --- | --- | +| `master` / active development branch | Yes | +| Latest tagged release | Yes | +| Older releases | Best effort | + +If a fix affects both the C++ runtime and the Python or web paths, please call that out in the report so the patch can cover the whole stack. + +## Reporting a Vulnerability + +Please do not open a public issue for a vulnerability that could put users at risk. + +Preferred reporting path: + +1. Use GitHub's private vulnerability reporting or security advisory flow for this repository, if available. +2. Include enough detail to reproduce the issue locally. +3. Share the affected component: C++ runtime, Python engine, FastAPI backend, React frontend, packaging, model files, or documentation. + +Helpful details include: + +- Affected commit, branch, or release. +- Operating system and runtime versions. +- Exact command or request used to reproduce the issue. +- Expected behavior and actual behavior. +- Logs, stack traces, or crash output. +- Whether the issue requires a crafted model, dataset, prompt, HTTP request, or environment variable. + +You should receive an acknowledgement as soon as the report is reviewed. Fix timing depends on impact and complexity. + +## Security Scope + +In scope examples: + +- Memory safety bugs in the native C++ runtime. +- Crashes or denial-of-service issues caused by malformed input files, prompts, checkpoints, or HTTP requests. +- Backend API behavior that exposes local files, environment variables, model paths, prompts, sessions, or generated text unexpectedly. +- Unsafe dependency updates or dependency confusion risks in Python, npm, or GitHub Actions. +- Cross-site scripting, service worker, or PWA issues in the frontend. +- Secret leakage through logs, generated artifacts, bundled files, or example configuration. + +Out of scope examples: + +- Expected model hallucinations or low-quality generated text. +- Prompt injection against a local toy model without a concrete data exposure or code execution path. +- Reports that require already having arbitrary code execution on the user's machine. +- Vulnerabilities in third-party services or packages unless the repository uses them in an unsafe way. + +## Local Deployment Notes + +Quadtrix.cpp is intended to run locally during development. + +- Keep the FastAPI backend bound to `127.0.0.1` unless you intentionally expose it. +- Do not commit real `.env` files, tokens, API keys, private datasets, or private checkpoints. +- Treat downloaded model checkpoints and datasets as untrusted inputs. +- Rebuild native binaries from source when possible instead of trusting unknown executables. +- Review changes to service workers, PWA manifests, backend routing, and CORS settings carefully. + +## Dependency Updates + +The project uses C++, Python, npm, and GitHub Actions. When updating dependencies: + +- Prefer minimal version bumps tied to a clear reason. +- Run the relevant local checks from `contributing.md`. +- Watch for lockfile changes and generated build output. +- Note any security-related update in the pull request summary. diff --git a/benchmark.cpp b/benchmark.cpp new file mode 100644 index 0000000..041c725 --- /dev/null +++ b/benchmark.cpp @@ -0,0 +1,296 @@ +// Run: +// .\quadtrix_bench.exe data\input.txt +// .\quadtrix_bench.exe data\input.txt --tokens 100 --runs 10 --warmup 3 +// +// Flags (all optional): +// --tokens N tokens to generate per run (default: 50) +// --runs N how many timed runs per prompt (default: 5) +// --warmup N un-timed warmup runs per prompt (default: 2) + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "config/config.h" +#include "include/dataloader.h" +#include "include/gpt.h" + +static bool file_exists(const std::string &p) +{ + std::ifstream f(p.c_str(), std::ios::binary); + return f.good(); +} + +static double now_ms() +{ + using namespace std::chrono; + return duration( + steady_clock::now().time_since_epoch()) + .count(); +} + +static double mean(const std::vector &v) +{ + return std::accumulate(v.begin(), v.end(), 0.0) / v.size(); +} + +static double stdev(const std::vector &v, double m) +{ + double sq = 0.0; + for (double x : v) + sq += (x - m) * (x - m); + return std::sqrt(sq / v.size()); +} + +static double timed_run(GPTLanguageModel &model, + DataLoader &dl, + const std::vector &prompt_ctx, + int n_tokens) +{ + std::vector ctx = prompt_ctx; + + double t0 = now_ms(); + for (int i = 0; i < n_tokens; ++i) + { + ctx = model.generate(ctx, 1); + if ((int)ctx.size() > BLOCK_SIZE) + ctx = std::vector(ctx.end() - BLOCK_SIZE, ctx.end()); + } + return now_ms() - t0; +} + +// + +static void section(const std::string &title) +{ + ; + std::cout << " " << title << "\n"; +} + +struct PromptResult +{ + std::string label; + int prompt_tokens; + int gen_tokens; + double avg_ms; + double min_ms; + double max_ms; + double std_ms; + double avg_tps; // tokens per second +}; + +static PromptResult bench_prompt(GPTLanguageModel &model, + DataLoader &dl, + const std::string &prompt, + int n_tokens, + int n_runs, + int n_warmup) +{ + // encode + std::vector ctx = dl.encode(prompt); + if (ctx.empty()) + ctx = {0}; + if ((int)ctx.size() > BLOCK_SIZE) + ctx = std::vector(ctx.end() - BLOCK_SIZE, ctx.end()); + + int prompt_len = (int)ctx.size(); + + // warmup (un-timed) + for (int i = 0; i < n_warmup; ++i) + timed_run(model, dl, ctx, n_tokens); + + // timed runs + std::vector times; + times.reserve(n_runs); + for (int i = 0; i < n_runs; ++i) + times.push_back(timed_run(model, dl, ctx, n_tokens)); + + double m = mean(times); + double sd = stdev(times, m); + double mn = *std::min_element(times.begin(), times.end()); + double mx = *std::max_element(times.begin(), times.end()); + double tps = n_tokens / (m / 1000.0); + + // truncate prompt for display + std::string label = prompt.size() > 30 + ? prompt.substr(0, 27) + "..." + : prompt; + + return PromptResult{label, prompt_len, n_tokens, m, mn, mx, sd, tps}; +} + +static void print_table(const std::vector &results) +{ + section("RESULTS"); + + // header + std::cout << std::left + << std::setw(34) << "Prompt" + << std::right + << std::setw(8) << "P.Tok" + << std::setw(8) << "G.Tok" + << std::setw(10) << "Avg ms" + << std::setw(10) << "Min ms" + << std::setw(10) << "Max ms" + << std::setw(9) << "Std ms" + << std::setw(10) << "tok/s" + << "\n"; + std::cout << std::string(99, '-') << "\n"; + + std::cout << std::fixed; + for (const auto &r : results) + { + std::cout << std::left + << std::setw(34) << r.label + << std::right + << std::setw(8) << r.prompt_tokens + << std::setw(8) << r.gen_tokens + << std::setw(10) << std::setprecision(1) << r.avg_ms + << std::setw(10) << std::setprecision(1) << r.min_ms + << std::setw(10) << std::setprecision(1) << r.max_ms + << std::setw(9) << std::setprecision(1) << r.std_ms + << std::setw(10) << std::setprecision(2) << r.avg_tps + << "\n"; + } + + double total_avg_tps = 0.0; + double best_tps = 0.0; + for (const auto &r : results) + { + total_avg_tps += r.avg_tps; + best_tps = std::max(best_tps, r.avg_tps); + } + double overall_tps = total_avg_tps / results.size(); + + std::cout << "\n Overall avg throughput : " + << std::setprecision(2) << overall_tps << " tok/s\n"; + std::cout << " Peak throughput : " + << std::setprecision(2) << best_tps << " tok/s\n"; + std::cout << " ms per token (avg) : " + << std::setprecision(2) << 1000.0 / overall_tps << " ms\n"; +} + +static void save_csv(const std::vector &results, + const std::string &path) +{ + std::ofstream f(path); + if (!f) + { + std::cerr << "[WARN] Could not write CSV to " << path << "\n"; + return; + } + f << "prompt,prompt_tokens,gen_tokens,avg_ms,min_ms,max_ms,std_ms,tok_per_sec\n"; + for (const auto &r : results) + { + f << "\"" << r.label << "\"," + << r.prompt_tokens << "," + << r.gen_tokens << "," + << r.avg_ms << "," + << r.min_ms << "," + << r.max_ms << "," + << r.std_ms << "," + << r.avg_tps << "\n"; + } + std::cout << "\n CSV saved to: " << path << "\n"; +} + +int main(int argc, char *argv[]) +{ + + std::string data_path = DEFAULT_CLEANED_PATH; + std::string model_path = BEST_MODEL_PATH; + int n_tokens = 50; + int n_runs = 5; + int n_warmup = 2; + + for (int i = 1; i < argc; ++i) + { + std::string a = argv[i]; + if (a == "--tokens" && i + 1 < argc) + n_tokens = std::atoi(argv[++i]); + else if (a == "--runs" && i + 1 < argc) + n_runs = std::atoi(argv[++i]); + else if (a == "--warmup" && i + 1 < argc) + n_warmup = std::atoi(argv[++i]); + else + data_path = a; + } + + std::cout << " Quadtrix Inference Benchmark\n"; + std::cout << " data : " << data_path << "\n"; + std::cout << " model : " << model_path << "\n"; + std::cout << " tokens : " << n_tokens << " per run\n"; + std::cout << " runs : " << n_runs << " timed + " + << n_warmup << " warmup\n"; + + DataLoader dl; + try + { + dl.load(data_path); + } + catch (const std::exception &e) + { + std::cerr << "[ERROR] " << e.what() << "\n"; + return 1; + } + + if (!file_exists(model_path)) + { + std::cerr << "[ERROR] Weights not found at " << model_path << "\n"; + std::cerr << "[HINT] Train first, or set " << MODEL_PATH_ENV_VAR << "\n"; + return 1; + } + + GPTLanguageModel model(dl.vocab_size, N_EMBD, N_HEAD, N_LAYER, BLOCK_SIZE, SEED); + model.load(model_path); + + std::cout << "\n[OK] Model loaded (" << model.num_params() / 1.0e6f + << " M params)\n"; + + std::vector prompts = { + "", + "The", // 1-token prompt + "Once upon a time", // short prompt + "The quick brown fox jumps", // medium prompt + std::string(1, 'a'), // long prompt (stress-tests context window) + }; + + section("RUNNING"); + std::vector results; + results.reserve(prompts.size()); + + for (size_t i = 0; i < prompts.size(); ++i) + { + std::string display = prompts[i].empty() + ? "(empty / BOS)" + : (prompts[i].size() > 30 + ? prompts[i].substr(0, 27) + "..." + : prompts[i]); + + std::cout << " [" << (i + 1) << "/" << prompts.size() << "] \"" + << display << "\" ... " << std::flush; + + PromptResult r = bench_prompt(model, dl, + prompts[i], + n_tokens, n_runs, n_warmup); + results.push_back(r); + + std::cout << std::fixed << std::setprecision(2) + << r.avg_tps << " tok/s\n"; + } + + print_table(results); + save_csv(results, "benchmark_results.csv"); + + std::cout << "\n"; + + std::cout << " Done.\n"; + return 0; +} \ No newline at end of file diff --git a/benchmark_results.csv b/benchmark_results.csv new file mode 100644 index 0000000..7496a05 --- /dev/null +++ b/benchmark_results.csv @@ -0,0 +1,6 @@ +prompt,prompt_tokens,gen_tokens,avg_ms,min_ms,max_ms,std_ms,tok_per_sec +"",1,50,2027,1848.4,2314.78,168.952,24.667 +"The",3,50,2561.63,2241.3,2986.35,306.631,19.5188 +"Once upon a time",16,50,3038.74,2885.22,3225.42,126.5,16.4542 +"The quick brown fox jumps",25,50,3975,3561.3,4783.34,454.592,12.5786 +"a",1,50,1862.99,1808.71,1929.64,46.4738,26.8386 diff --git a/contributing.md b/contributing.md new file mode 100644 index 0000000..3705488 --- /dev/null +++ b/contributing.md @@ -0,0 +1,162 @@ +# Contributing to Quadtrix.cpp + +Thanks for helping improve Quadtrix.cpp. This project is a transformer learning lab with several execution paths: native C++ training and inference, PyTorch experiments, a FastAPI backend, and a React + TypeScript chat UI. Contributions are easiest to review when they keep those paths clear and testable. + +## Good First Contributions + +Useful contributions include: + +- Fixing correctness bugs in the C++ transformer implementation. +- Improving training, inference, checkpoint loading, or export scripts. +- Making the FastAPI backend more reliable and easier to run locally. +- Improving the React chat UI without hiding the model/backend behavior. +- Adding focused documentation for setup, model files, datasets, or run commands. +- Tightening CI, dependency versions, packaging, or release steps. + +For larger model architecture changes, open an issue first so the design can be discussed before a big patch lands. + +## Repository Layout + +```text +Quadtrix.cpp/ + main.cpp Native C++ entry point + include/ C++ headers + src/ C++ source files + engine/ PyTorch training, inference, export, and model files + backend/ FastAPI backend and session handling + frontend/ React + TypeScript chat UI + iGPU/ Integrated GPU experiments + config/ Runtime configuration + data/ Local datasets and helpers + .github/workflows/ CI and release workflows +``` + +## Development Setup + +From the repository root: + +```powershell +python -m venv .venv +.\.venv\Scripts\python.exe -m pip install --upgrade pip +cd backend +..\.venv\Scripts\python.exe -m pip install -r requirements.txt +``` + +Install frontend dependencies: + +```powershell +cd frontend +npm.cmd install +``` + +Build the native C++ runtime from the repository root: + +```bash +g++ -std=c++17 -O2 -I. -Iinclude -o quadtrix main.cpp +``` + +## Running Locally + +Run the C++ model: + +```powershell +.\Quadtrix.exe data\input.txt --chat +``` + +Run the C++ HTTP server: + +```powershell +.\Quadtrix.exe data\input.txt --server --port 8080 +``` + +Run the FastAPI backend: + +```powershell +cd backend +..\.venv\Scripts\python.exe -m uvicorn main:app --host 127.0.0.1 --port 3001 +``` + +Run the frontend: + +```powershell +cd frontend +npm.cmd run dev +``` + +Open the app at: + +```text +http://localhost:5173 +``` + +## Checks Before Opening a Pull Request + +Run the checks that match your change. + +C++: + +```bash +g++ -std=c++17 -O2 -I. -Iinclude -o quadtrix main.cpp +``` + +Python: + +```powershell +.\.venv\Scripts\python.exe -m compileall backend engine iGPU +cd backend +..\.venv\Scripts\python.exe -c "from main import app; print(app.title)" +``` + +Frontend: + +```powershell +cd frontend +npm.cmd run build +``` + +If you cannot run a relevant check, mention that in the pull request and explain why. + +## Pull Request Guidelines + +- Keep changes focused on one problem or feature. +- Use the existing style of the file you are editing. +- Avoid committing generated artifacts unless the project already expects them. +- Do not commit `.env` files, secrets, private datasets, or personal checkpoints. +- Update `README.md`, `run.md`, or related docs when commands or behavior change. +- Include screenshots or short notes for UI changes. +- Mention any change that affects model files, ports, CORS, service workers, or packaging. + +The pull request template asks for: + +- Summary and user-facing impact. +- C++ build status. +- Backend smoke-test status. +- Frontend build status. +- Documentation or screenshot updates when needed. + +## Coding Notes + +For C++ changes: + +- Prefer clear, debuggable code over clever abstractions. +- Keep the educational value of the implementation visible. +- Be careful with tensor shapes, bounds, and ownership. +- Add comments only where the math or control flow is not obvious. + +For Python changes: + +- Keep backend behavior explicit and local-development friendly. +- Avoid broad exception swallowing around model loading or inference. +- Treat model paths, datasets, and request payloads as untrusted inputs. + +For frontend changes: + +- Keep the chat UI practical and responsive. +- Preserve the ability to switch between the C++ backend and the `.pt` path. +- Make loading, error, and disconnected states clear. + +## Documentation Style + +Use concrete commands and paths. Quadtrix.cpp has multiple runtime paths, so say exactly which path a command belongs to: C++, PyTorch, FastAPI backend, frontend, iGPU, or packaging. + +When documenting training results, include the hardware, dataset, iteration count, elapsed time, and validation metric so results can be compared fairly. diff --git a/docs/Quadtrix_Educational_Paper.pdf b/docs/Quadtrix_Educational_Paper.pdf new file mode 100644 index 0000000..d8d2a3a Binary files /dev/null and b/docs/Quadtrix_Educational_Paper.pdf differ diff --git a/docs/run_20260430_192930.png b/docs/run_20260430_192930.png new file mode 100644 index 0000000..8548392 Binary files /dev/null and b/docs/run_20260430_192930.png differ diff --git a/docs/run_20260508_110726.png b/docs/run_20260508_110726.png new file mode 100644 index 0000000..5848440 Binary files /dev/null and b/docs/run_20260508_110726.png differ diff --git a/engine/fineweb_dataset.py b/engine/fineweb_dataset.py index 0a9f86e..9a0107f 100644 --- a/engine/fineweb_dataset.py +++ b/engine/fineweb_dataset.py @@ -36,10 +36,10 @@ def download_fineweb_sample(output_dir="engine", target_size_mb=30): current_bytes += sample_size if (i + 1) % 100 == 0: - print(f"Collected {i + 1} samples (~{current_bytes / (1024*1024):.2f} MB)") + print(f"Collected {i + 1} samples ({current_bytes / (1024*1024):.2f} MB)") print(f"\nDownloaded {len(samples)} samples ({current_bytes / (1024*1024):.2f} MB)") - output_file = os.path.join(output_dir, "fineweb_30mb.txt") + output_file = os.path.join(output_dir, "input.txt") with open(output_file, 'w', encoding='utf-8') as f: for sample in samples: f.write(sample['text']) @@ -54,7 +54,7 @@ def download_fineweb_sample(output_dir="engine", target_size_mb=30): if __name__ == "__main__": try: download_fineweb_sample() - print("\n✓ Download completed successfully!") + print("\nDownload completed successfully!") except Exception as e: print(f"\ Error: {e}") print("\nMake sure you have the 'datasets' library installed:") diff --git a/engine/main.py b/engine/main.py index 4553843..cffb4cb 100644 --- a/engine/main.py +++ b/engine/main.py @@ -65,7 +65,7 @@ def success(msg): log(f" ok {msg}") # CONFIGURATION -cleaned_path = Path(os.environ.get("QUADTRIX_TRAIN_DATA", SCRIPT_DIR / "input.txt")) +cleaned_path = Path(os.environ.get("data", SCRIPT_DIR / "input.txt")) train_split = 0.9 seed = 1337 diff --git a/frontend/public/icon.svg b/frontend/public/icon.svg index b010998..43d7866 100644 --- a/frontend/public/icon.svg +++ b/frontend/public/icon.svg @@ -1,75 +1,42 @@ - - - - - - + - - - - + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - > - - - - - - - - C - - - - - ++ - - + + + + + + + + + + + + - - \ No newline at end of file + diff --git a/frontend/src/components/chat/EmptyState.tsx b/frontend/src/components/chat/EmptyState.tsx index 19fdf7a..ce75d9a 100644 --- a/frontend/src/components/chat/EmptyState.tsx +++ b/frontend/src/components/chat/EmptyState.tsx @@ -2,8 +2,8 @@ export function EmptyState() { return (
-
- Quadtrix.cpp icon +
+ Quadtrix.cpp icon

Quadtrix.cpp

diff --git a/frontend/src/components/layout/Topbar.tsx b/frontend/src/components/layout/Topbar.tsx index 62167b7..a6ed610 100644 --- a/frontend/src/components/layout/Topbar.tsx +++ b/frontend/src/components/layout/Topbar.tsx @@ -24,8 +24,8 @@ export function Topbar() {
-
- Quadtrix.cpp icon +
+ Quadtrix.cpp icon
diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..28be669 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,19 @@ +{ + "name": "quadtrix", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "quadtrix", + "version": "1.0.0", + "license": "MIT", + "bin": { + "quadtrix": "bin/quadtrix.js" + }, + "engines": { + "node": ">=18" + } + } + } +} diff --git a/package.json b/package.json index 613490f..a4a24c5 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,17 @@ { "name": "quadtrix", - "version": "1.0.0", + "version": "1.0.2", "description": "CLI for running Quadtrix.cpp chat and local training.", "license": "MIT", + "author": "Eamon", + "repository": { + "type": "git", + "url": "https://github.com/Eamon2009/Quadtrix.cpp.git" + }, + "bugs": { + "url": "https://github.com/Eamon2009/Quadtrix.cpp/issues" + }, + "homepage": "https://github.com/Eamon2009/Quadtrix.cpp#readme", "bin": { "quadtrix": "bin/quadtrix.js" }, @@ -42,4 +51,4 @@ "engines": { "node": ">=18" } -} +} \ No newline at end of file