# 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
```bash
# 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. Use ninja instead make

### Web UI Only
```bash
cd webui
npm install
npm run build
```

### Web UI Development Workflow
```bash
# 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
1. **HTTP Server** - Request parsing, response formatting
2. **Generation Queue** - Sequential job processing, thread-safe
3. **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**: Never kill running server processes - the user manages server lifecycle
- Agents should not start/stop servers unless explicitly requested

## 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

1. **Code Changes**: Make changes to C++ or TypeScript files
2. **Build**: Run `cmake --build . -j4` from build directory
3. **Test**: Use appropriate test methods (shell scripts, browser tools)
4. **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
5. **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.