AGENTS.md - Agent Guide for stable-diffusion.cpp-rest (fszontagh/stable-diffusion.cpp-rest)

This document contains essential information for agents working with the stable-diffusion.cpp-rest codebase.

Project Overview

This is a C++ REST API server that wraps the stable-diffusion.cpp library, providing HTTP endpoints for image generation with Stable Diffusion models. The project includes both a C++ backend and a Next.js frontend (webui).

Always use todo tools to track the status

Build Commands

Main Build Process

# Create build directory and configure
mkdir build && cd build
cmake ..
cmake --build . -j

# Alternative: Use the existing rule file command
cd build
cmake --build . -j

Always use the build directory for compiling the project.

Web UI Only

cd webui
npm install
npm run build

Web UI Development Workflow

# For faster development when only changing the webui
cd webui; npm run build-static

# This builds the webui and copies the static files to build/webui/
# No need to rebuild the entire server or stop it during webui updates
# The server will automatically serve the updated static files
# always cd into the webui directory before run npm

Project Structure

C++ Backend

src/ - Source files (.cpp)
include/ - Header files (.h)
CMakeLists.txt - Main build configuration
.clang-format - C++ formatting rules (Chromium-based, 4-space indent)

Web Frontend

webui/ - Next.js React application
webui/package.json - Node.js dependencies
webui/tsconfig.json - TypeScript configuration
webui/next.config.ts - Next.js config (static export with /ui basePath)

Model Organization

Models are stored in /data/SD_MODELS/ (not in project root to keep directory clean). Supported model types include:

CHECKPOINT (.safetensors, .pt, .ckpt)
LORA models
VAE models
Various other types (embeddings, upscalers, etc.)

Code Standards and Conventions

C++ Standards

C++17 standard
NO using aliases - Never use aliases like: using json = nlohmann::json;
Follow Rule of 5 for class design
Use absolute paths when printing directory/file names to console
4-space indentation (configured in .clang-format)

TypeScript/React Standards

TypeScript with strict mode enabled
Next.js 16 with React 19
Tailwind CSS for styling
ESLint with Next.js configuration
Path aliases: @/* maps to webui root

Key Architecture Patterns

Model Detection System

The project uses intelligent model detection in src/model_detector.cpp:

Detects architecture: SD 1.5, SD 2.1, SDXL, Flux, SD3, Qwen2VL
Traditional models → ctxParams.model_path
Modern architectures → ctxParams.diffusion_model_path
Unknown architectures fallback to traditional loading

Three-Tier Architecture

HTTP Server - Request parsing, response formatting
Generation Queue - Sequential job processing, thread-safe
Model Manager - Model loading, architecture detection, memory management

Authentication System

Multiple authentication methods supported:

none - No authentication (default)
jwt - JWT token authentication
api-key - Static API keys
unix - Unix system authentication
pam - PAM authentication (requires libpam0g-dev)
optional - Authentication optional

Server Testing

Start server in background during testing: cd build; ./src/stable-diffusion-rest-server --models-dir /data/SD_MODELS --port 8082 --host 0.0.0.0 --ui-dir ./webui --verbose

Important Gotchas

Build System

Keep build/_deps folder - Rebuilding dependencies takes very long time
Web UI automatically builds with main project via CMake
CMake automatically downloads and builds stable-diffusion.cpp as external project
For webui-only changes, use npm run build-static to avoid rebuilding the entire server
The build-static command copies the built webui to build/webui/ for the server to serve

Path Management

Always use absolute paths when printing to console
Models directory: /data/SD_MODELS/ (not project root)
The build wenui directory is in the build folder: build/webui
Keep project directory clean - no output/queue directories in root

Web UI Configuration

Next.js configured for static export (output: 'export')
Base path: /ui
Asset prefix: /ui
No image optimization (unoptimized: true)

Development Workflow

Code Changes: Make changes to C++ or TypeScript files
Build: Run cmake --build . -j4 from build directory
Test: Use appropriate test methods (shell scripts, browser tools)
Web UI Updates: If changing webui, the build process includes it. If the API server already running and no changes made in the c++ code, just build the webui: cd webui; npm run build-static but do not stop the running API server
Commit: Always commit and push changes, reference related issues

MCP Tools Integration

Always use available MCP tools for speeding up tasks
Gogs MCP tools for repository issue management
- When user asks about issues, always use mcp_gogs_* tools for current repo
- Current repository: fszontagh/stable-diffusion.cpp-rest
- always create gogs issues based on the user request. Check if an issue exists with the same request
- always manage the gogs issues. If a task is done, mark in the issue. If the issue is closeable, close it

Configuration Files

.clang-format - C++ code formatting
.clang-tidy - C++ static analysis
webui/tsconfig.json - TypeScript configuration
webui/eslint.config.mjs - ESLint configuration
webui/next.config.ts - Next.js build configuration

Dependencies

C++ Dependencies

stable-diffusion.cpp (auto-downloaded by CMake)
CUDA Toolkit (optional, for GPU acceleration)
PAM libraries (optional, for PAM auth)

Web UI Dependencies

Node.js and npm
Next.js 16
React 19
Tailwind CSS 4
Radix UI components

Model File Formats

The project supports various model quantization levels:

f32, f16 - Floating point formats
q8_0, q4_0, q3_k - Quantized formats
GGUF format for converted models
Original .safetensors and .ckpt formats

Remember: This project serves as a bridge between the C++ stable-diffusion.cpp library and web applications, with emphasis on performance, security, and ease of use.

AGENTS.md 6.3 KB History Raw