Quadtrix-cpp

Requirements

Core Requirements

Python Dependencies

The backend installs:

fastapi
uvicorn[standard]
pydantic
pydantic-settings
httpx
redis
torch
tiktoken

These are declared in backend/requirements.txt.

C++ Dependencies

The native C++ path has no third-party runtime dependency. It builds from:

main.cpp
config/config.h
include/*.h

2. Install Backend and PyTorch Dependencies

cd backend
..\.venv\Scripts\python.exe -m pip install -r requirements.txt
cd ..

3. Install Frontend Dependencies

cd frontend
npm.cmd install
cd ..

Use npm.cmd on Windows PowerShell if direct npm execution is blocked by PowerShell execution policy.

Python Backend Cannot Import Dependencies

Install dependencies into the repository virtual environment:

cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\backend
..\.venv\Scripts\python.exe -m pip install -r requirements.txt

Setup

The commands below use PowerShell from the repository root:

cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp

4. Build the Frontend

cd frontend
npm.cmd run build
cd ..

5. Build the C++ Executable

If quadtrix.exe already exists, this step is optional. To rebuild:

g++ -std=c++17 -O2 -I. -Iinclude -o quadtrix.exe main.cpp

For extra CPU optimization on GCC/Clang:

g++ -std=c++17 -O3 -march=native -I. -Iinclude -o quadtrix.exe main.cpp

Production Build

npm.cmd run build

Preview Production Build

npm.cmd run preview

Open the preview URL, usually:

http://localhost:4173

Rebuild C++ After Changing Hyperparameters

Any change in config/config.h requires recompilation:

g++ -std=c++17 -O2 -I. -Iinclude -o quadtrix.exe main.cpp

Scaling Guide

1. Create a Python Virtual Environment

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip

Option A: Run PyTorch Chat in the Web UI

This is the simplest web path when a PyTorch checkpoint is available.

Terminal 1:

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:

cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\frontend
npm.cmd run dev

Open:

http://localhost:5173

Select the .pt or PyTorch backend in the UI. The FastAPI app loads the checkpoint through engine/inference.py.

Option B: Run C++ Terminal Chat

The C++ executable supports terminal chat directly:

cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp
.\quadtrix.exe data\input.txt --chat

Set the number of generated tokens per answer:

.\quadtrix.exe data\input.txt --chat --chat-tokens 300

The C++ chat path requires best_model.bin unless GPT_MODEL_PATH points to another checkpoint.

Option C: Run C++ Generation

.\quadtrix.exe data\input.txt --generate

Generation streams tokens until interrupted with Ctrl+C.

Option D: Train the C++ Model

.\quadtrix.exe data\input.txt

Training writes the best checkpoint to:

best_model.bin

Option E: Train the PyTorch Model

cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp
.\.venv\Scripts\python.exe engine\main.py

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:

$env:QUADTRIX_TRAIN_DATA="C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\data\input.txt"
.\.venv\Scripts\python.exe engine\main.py

The PyTorch training script saves its checkpoint as:

best_model.pt

C++ Environment Variables

Example:

$env:GPT_MODEL_PATH="C:\models\quadtrix-best.bin"
.\quadtrix.exe data\input.txt --chat

Backend Environment

Create backend/.env if you want to override defaults:

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.

Configuration

C++ Configuration

Edit config/config.h and rebuild the C++ executable.

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;

CLI Inference

Interactive chat:

.\.venv\Scripts\python.exe engine\inference.py --checkpoint "engine\best_model.pt"

Single prompt:

.\.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:

FastAPI Backend

The production-style API lives in backend/main.py.

Start it with:

cd C:\Users\Admin\Documents\GitHub\Quadtrix.cpp\backend
..\.venv\Scripts\python.exe -m uvicorn main:app --host 127.0.0.1 --port 3001

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

API Reference

Base URL:

http://localhost:3001

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.

Training Comparison

Comparison to Related Projects

Troubleshooting