# AGENTS.md

AI coding agent instructions for **stable-diffusion.cpp-rest**

## Project Overview

A C++ based REST API wrapper for the [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp.git) library, providing HTTP endpoints for image generation with Stable Diffusion models.

**Project Type:** Node.js Application
**Primary Language:** TypeScript (63% of codebase)
**Secondary Languages:** C (19%), C++ (18%)

## Architecture

**Project Structure:**
- `src/` - Source code
- `webui/app/` - Application code
- `webui/components/` - React/UI components
- `webui/lib/` - Library code
- `webui/public/` - Public assets
- `webui/app/img2img/` - Project files
- `webui/app/settings/` - Settings
- `webui/app/text2img/` - Project files
- `webui/app/upscaler/` - Project files
- `webui/components/auth/` - Project files
- `webui/components/ui/` - Project files

## Key Files

**Configuration:**
- `webui/package.json` - Node.js dependencies and scripts

**Documentation:**
- `CLAUDE.md`
- `HASHING_IMPLEMENTATION_GUIDE.md`
- `MODEL_DETECTION.md`
- `PAM_AUTHENTICATION.md`

## Code Style Guidelines

- Use camelCase for variables and functions
- Use PascalCase for classes and components
- Prefer const/let over var
- Use async/await over callbacks when possible

## Testing

**Test Files:**
- `TEST_RESULTS_SUMMARY.md`
- `src/test_model_detector.cpp`
- `test-auth/api_keys.json`
- `test-auth/users.json`

## Existing Project Guidelines

*The following guidelines were found in existing AI configuration files:*

### AI Agent Guidelines
**From CLAUDE.md:**
## Project Overview
This is a C++ REST API server that wraps the [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) library, providing HTTP endpoints for Stable Diffusion image generation. The server is built with a modular architecture featuring three main components: HTTP Server, Generation Queue, and Model Manager.

### Initial Setup and Build
```bash

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

# Build the project (parallel build)
cmake --build . --parallel

### Build Configuration Options
```bash

# Build with CUDA support (default: ON)
cmake -DSD_CUDA_SUPPORT=ON ..

# Build without CUDA
cmake -DSD_CUDA_SUPPORT=OFF ..

# Debug build
cmake -DCMAKE_BUILD_TYPE=Debug ..

# Release build (default)
cmake -DCMAKE_BUILD_TYPE=Release ..
```

### Clean and Rebuild
```bash

# Clean build artifacts
cd build
cmake --build . --target clean

# Or delete build directory entirely
rm -rf build
mkdir build && cd build
cmake ..
cmake --build . --parallel
```

### Threading Architecture
- **Main thread**: Initialization, signal handling, coordination
- **Server thread**: HTTP request handling (in `Server::serverThreadFunction()`)
- **Queue worker threads**: Generation processing (managed by GenerationQueue)
- Signal handler sets global `g_running` flag for graceful shutdown

### External Project Integration
The stable-diffusion.cpp library is built as an external project. Include directories and libraries are configured via the `sd-cpp` interface target:
```cmake
target_link_libraries(stable-diffusion-rest-server PRIVATE
    sd-cpp
    ggml
    ggml-base
    ggml-cpu
    ${DEPENDENCY_LIBRARIES}
)
```

When accessing stable-diffusion.cpp APIs, include from the installed headers:
- `#include <stable-diffusion.h>`
- `#include <ggml.h>`

The wrapper class `StableDiffusionWrapper` (`stable_diffusion_wrapper.cpp/h`) encapsulates all interactions with the stable-diffusion.cpp library.

## Model Architecture Detection System
The server includes an automatic model architecture detection system that analyzes checkpoint files to determine their type and required auxiliary models.

### Supported Architectures
The system can detect the following architectures:

| Architecture | Required Files | Command-Line Flags |
|-------------|----------------|-------------------|
| **SD 1.5** | VAE (optional) | `--vae vae-ft-mse-840000-ema-pruned.safetensors` |
| **SD 2.1** | VAE (optional) | `--vae vae-ft-ema-560000.safetensors` |
| **SDXL Base/Refiner** | VAE (optional) | `--vae sdxl_vae.safetensors` |
| **Flux Schnell** | VAE, CLIP-L, T5XXL | `--vae ae.safetensors --clip-l clip_l.safetensors --t5xxl t5xxl_fp16.safetensors` |
| **Flux Dev** | VAE, CLIP-L, T5XXL | `--vae ae.safetensors --clip-l clip_l.safetensors --t5xxl t5xxl_fp16.safetensors` |
| **Flux Chroma** | VAE, T5XXL | `--vae ae.safetensors --t5xxl t5xxl_fp16.safetensors` |
| **SD3** | VAE, CLIP-L, CLIP-G, T5XXL | `--vae sd3_vae.safetensors --clip-l clip_l.safetensors --clip-g clip_g.safetensors --t5xxl t5xxl_fp16.safetensors` |
| **Qwen2-VL** | Qwen2VL, Qwen2VL-Vision | `--qwen2vl qwen2vl.safetensors --qwen2vl-vision qwen2vl_vision.safetensors` |

### Testing the Detection System
A standalone test binary can be built to test model detection:

```bash
cd build
cmake -DBUILD_MODEL_DETECTOR_TEST=ON ..
cmake --build . --target test_model_detector

### Architecture-Specific Loading
The server will automatically use the correct parameters when loading models based on detected architecture. For architectures requiring multiple auxiliary models (Flux, SD3, Qwen), the server will:

1. Check if all required models are available
2. Return warnings via API if models are missing
3. Display warnings in WebUI with instructions to load missing models
4. Provide correct command-line flags for manual loading

See `MODEL_DETECTION.md` for complete documentation on the detection system.

## Web UI Architecture
The project includes a Next.js-based web UI located in `/webui` that provides a modern interface for interacting with the REST API.

### Building the Web UI
```bash

# Build Web UI manually
cd webui
npm install
npm run build

# Build via CMake (automatically copies to build directory)
cmake --build build --target webui-build
```

The built UI is automatically copied to `build/webui/` and served by the REST API server at `/ui/`.

### WebUI Structure
- **Framework**: Next.js 16 with React, TypeScript, and Tailwind CSS
- **Routing**: App router with static page generation
- **UI Components**: Shadcn/ui components in `/webui/components/ui/`
- **Pages**:
  - `/webui/app/text2img/page.tsx` - Text-to-image generation
  - `/webui/app/img2img/page.tsx` - Image-to-image generation
  - `/webui/app/upscaler/page.tsx` - Image upscaling
  - `/webui/app/models/page.tsx` - Model management
  - `/webui/app/queue/page.tsx` - Queue status

### Important Components
1. **Main Layout** (`/webui/components/main-layout.tsx`)
   - Provides consistent layout with sidebar and status bar
   - Includes `Sidebar` and `ModelStatusBar` components

2. **Sidebar** (`/webui/components/sidebar.tsx`)
   - Fixed position navigation (z-index: 40)
   - Always visible on the left side
   - Handles page navigation

3. **Model Status Bar** (`/webui/components/model-status-bar.tsx`)
   - Fixed position at bottom (z-index: 35)
   - Positioned with `left-64` to avoid overlapping sidebar
   - Shows current model status, queue status, and generation progress
   - Polls server every 1-5 seconds for updates

4. **Prompt Textarea** (`/webui/components/prompt-textarea.tsx`)
   - Advanced textarea with syntax highlighting
   - Autocomplete for LoRAs and embeddings
   - Suggestions dropdown (z-index: 30 - below sidebar)
   - Highlights LoRA tags (`<lora:name:weight>`) and embedding names

### Testing Cache Behavior
1. **First Load** (Cache Miss):
   ```bash
   # Open browser DevTools → Network tab
   # Load page → See all assets with Status 200
   # Check Response Headers for Cache-Control and ETag
   ```

2. **Reload** (Cache Hit):
   ```bash
   # Reload page → See assets with Status 200 (from disk cache)
   # Or Status 304 (Not Modified) if revalidating
   ```

3. **After Rebuild** (Cache Invalidation):
   ```bash
   # Rebuild UI: cmake --build build --target webui-build
   # Restart server
   # Reload page → Version checker shows update notification
   # Click Refresh → All assets redownloaded with new ETag
   ```

## PAM Authentication System

The server includes comprehensive PAM (Pluggable Authentication Modules) authentication support for integration with system authentication backends.

### PAM Implementation Components

1. **PamAuth Class** (`include/pam_auth.h`, `src/pam_auth.cpp`)
   - Encapsulates all PAM functionality
   - Handles PAM conversation callbacks
   - Provides conditional compilation stubs when PAM is disabled
   - Manages PAM service initialization and cleanup

2. **UserManager Integration** (`include/user_manager.h`, `src/user_manager.cpp`)
   - Provides `authenticatePam()` method
   - Manages PAM authentication enable/disable
   - Creates guest users for successful PAM authentication
   - Handles conditional compilation with `#ifdef ENABLE_PAM_AUTH`

3. **AuthMiddleware Integration** (`include/auth_middleware.h`, `src/auth_middleware.cpp`)
   - Routes PAM authentication requests
   - Extracts credentials from HTTP requests
   - Handles PAM-specific error responses
   - Integrates with existing authentication flow

4. **Build System Integration** (`CMakeLists.txt`, `cmake/FindPAM.cmake`)
   - Custom FindPAM.cmake module for PAM library detection
   - Conditional compilation with `ENABLE_PAM_AUTH` option
   - Proper linking when PAM is available
   - Graceful fallback when PAM is not available

### PAM Authentication Flow

1. **Request Reception**: HTTP request with credentials in JSON body
2. **Middleware Routing**: AuthMiddleware routes to PAM authentication
3. **Credential Extraction**: Username and password extracted from request
4. **PAM Authentication**: PamAuth class authenticates against system
5. **User Creation**: Successful authentication creates/updates user record
6. **Token Generation**: JWT token generated for subsequent requests

### PAM Service Configuration

Create a PAM service file at `/etc/pam.d/stable-diffusion-rest`:

```pam
# Basic PAM configuration for stable-diffusion-rest
auth    sufficient    pam_unix.so try_first_pass nullok_secure
auth    required    pam_deny.so

account sufficient    pam_unix.so
account required    pam_deny.so

password sufficient    pam_unix.so nullok_use_authtok nullok_secure md5 shadow
password required    pam_deny.so

session required    pam_limits.so
session required    pam_unix.so
```

### Conditional Compilation

PAM support is conditionally compiled based on the `ENABLE_PAM_AUTH` flag:

```cpp
#ifdef ENABLE_PAM_AUTH
// PAM-specific code
PamAuthResult PamAuth::authenticateInternal(const std::string& username, const std::string& password);
#else
// Stub implementations when PAM is not enabled
PamAuthResult PamAuth::authenticateInternal(const std::string& username, const std::string& password) {
    PamAuthResult result;
    result.success = false;
    result.errorMessage = "PAM authentication not available (compiled without PAM support)";
    result.errorCode = "PAM_NOT_AVAILABLE";
    return result;
}
#endif
```

### PAM Error Handling

The system provides comprehensive error handling for PAM authentication:

| Error Code | Description | PAM Error |
|------------|-------------|-----------|
| AUTHENTICATION_FAILED | Invalid credentials | PAM_AUTH_ERR |
| USER_NOT_FOUND | User does not exist | PAM_USER_UNKNOWN |
| CREDENTIAL_EXPIRED | Password expired | PAM_CRED_EXPIRED |
| ACCOUNT_EXPIRED | Account expired | PAM_ACCT_EXPIRED |
| PASSWORD_CHANGE_REQUIRED | Password change needed | PAM_NEW_AUTHTOK_REQD |
| MAX_TRIES_EXCEEDED | Too many failed attempts | PAM_MAXTRIES |
| AUTHENTICATION_UNAVAILABLE | PAM service unavailable | PAM_AUTHINFO_UNAVAIL |

### Testing PAM Authentication

Test PAM configuration with `pamtester`:

```bash
# Install pamtester
sudo apt-get install pamtester

# Test authentication
sudo pamtester stable-diffusion-rest username authenticate

# Test account management
sudo pamtester stable-diffusion-rest username acct_mgmt
```

### Security Considerations

1. **No Password Storage**: The server never stores user passwords
2. **Memory Management**: Passwords are cleared from memory after authentication
3. **Secure Transmission**: Always use HTTPS in production environments
4. **PAM Service Security**: Restrict permissions on PAM service files
5. **Account Lockout**: Configure account lockout in PAM to prevent brute force attacks

### Troubleshooting PAM Issues

1. **Check PAM Libraries**: Verify PAM libraries are installed
2. **Verify Build Configuration**: Ensure server was built with PAM support
3. **Test PAM Configuration**: Use `pamtester` to validate PAM service
4. **Check System Logs**: Review `/var/log/auth.log` or `journalctl`
5. **Verify Service File**: Ensure PAM service file syntax is correct

For detailed PAM authentication setup instructions, see [PAM_AUTHENTICATION.md](PAM_AUTHENTICATION.md).

## AI Coding Assistance Notes

**Important Considerations:**
- Check package.json for available scripts before running commands
- Be aware of Node.js version requirements
- Consider impact on bundle size when adding dependencies
- Project has 85 files across 16 directories
- Check build configuration files before making structural changes

---

*This AGENTS.md file was generated by Nanocoder. Update it as your project evolves.*