realesrgan-api/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

## Overview

This is the Real-ESRGAN API project - a sophisticated, full-featured REST API for image upscaling using Real-ESRGAN. The API supports both synchronous and asynchronous (job-based) processing with Docker containerization for CPU and GPU deployments.

## Architecture

### Core Components

- **app/main.py**: FastAPI application with lifecycle management
- **app/routers/**: API endpoint handlers
  - `upscale.py`: Synchronous and async upscaling endpoints
  - `models.py`: Model management endpoints
  - `health.py`: Health checks and system monitoring
- **app/services/**: Business logic
  - `realesrgan_bridge.py`: Real-ESRGAN model loading and inference
  - `file_manager.py`: File handling and directory management
  - `worker.py`: Async job queue with thread pool
  - `model_manager.py`: Model downloading and metadata
- **app/schemas/**: Pydantic request/response models

### Data Directories

- `/data/uploads`: User uploaded files
- `/data/outputs`: Processed output images
- `/data/models`: Real-ESRGAN model weights (.pth files)
- `/data/temp`: Temporary processing files
- `/data/jobs`: Async job metadata and status

## Development Workflow

### Local Setup (CPU)

```bash
# Install dependencies
pip install -r requirements.txt -r requirements-cpu.txt

# Run development server
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Access API
# Swagger: http://localhost:8000/docs
# ReDoc: http://localhost:8000/redoc
```

### Docker Development

```bash
# Build CPU image
docker compose build

# Run container
docker compose up -d

# View logs
docker compose logs -f api

# Stop container
docker compose down
```

### GPU Development

```bash
# Build GPU image
docker compose -f docker-compose.gpu.yml build

# Run with GPU
docker compose -f docker-compose.gpu.yml up -d

# Check GPU usage
docker compose -f docker-compose.gpu.yml exec api nvidia-smi
```

## Configuration

### Environment Variables (prefix: RSR_)

All settings from `app/config.py` can be configured via environment:

```bash
RSR_UPLOAD_DIR=/data/uploads
RSR_OUTPUT_DIR=/data/outputs
RSR_MODELS_DIR=/data/models
RSR_EXECUTION_PROVIDERS=["cpu"]  # or ["cuda"] for GPU
RSR_TILE_SIZE=400               # Tile size for large images
RSR_MAX_UPLOAD_SIZE_MB=500
RSR_SYNC_TIMEOUT_SECONDS=300
```

### Docker Compose Environment

Set in `docker-compose.yml` or `docker-compose.gpu.yml` `environment` section.

## API Endpoints

### Key Endpoints

- **POST /api/v1/upscale**: Synchronous upscaling (direct response)
- **POST /api/v1/jobs**: Create async upscaling job
- **GET /api/v1/jobs/{job_id}**: Check job status
- **GET /api/v1/jobs/{job_id}/result**: Download result
- **GET /api/v1/models**: List available models
- **POST /api/v1/models/download**: Download models
- **GET /api/v1/health**: Health check
- **GET /api/v1/system**: System information

## Model Management

### Available Models

```python
'RealESRGAN_x2plus'          # 2x upscaling
'RealESRGAN_x3plus'          # 3x upscaling
'RealESRGAN_x4plus'          # 4x general purpose (default)
'RealESRGAN_x4plus_anime_6B' # 4x anime/art (lighter)
```

### Downloading Models

```bash
# Download specific model
curl -X POST http://localhost:8000/api/v1/models/download \
  -H 'Content-Type: application/json' \
  -d '{"models": ["RealESRGAN_x4plus"]}'

# List available models
curl http://localhost:8000/api/v1/models
```

## Async Job Processing

### Workflow

1. Submit image → POST /api/v1/jobs → returns `job_id`
2. Poll status → GET /api/v1/jobs/{job_id}
3. When status=completed → GET /api/v1/jobs/{job_id}/result

### Job States

- `queued`: Waiting in queue
- `processing`: Currently being processed
- `completed`: Successfully processed
- `failed`: Processing failed

## Integration with facefusion-api

This project follows similar patterns to facefusion-api:

- **File Management**: Same `file_manager.py` utilities
- **Worker Queue**: Similar async job processing architecture
- **Docker Setup**: Multi-variant CPU/GPU builds
- **Configuration**: Environment-based settings with pydantic
- **Gitea CI/CD**: Automatic Docker image building
- **API Structure**: Organized routers and services

## Development Tips

### Adding New Endpoints

1. Create handler in `app/routers/{domain}.py`
2. Define request/response schemas in `app/schemas/{domain}.py`
3. Include router in `app/main.py`: `app.include_router(router)`

### Adding Services

1. Create service module in `app/services/{service}.py`
2. Import and use in routers

### Testing

Run a quick test:

```bash
# Check API is running
curl http://localhost:8000/

# Check health
curl http://localhost:8000/api/v1/health

# Check system info
curl http://localhost:8000/api/v1/system
```

## Troubleshooting

### Models Not Loading

```bash
# Check if models directory exists and has permission
ls -la /data/models/

# Download models manually
curl -X POST http://localhost:8000/api/v1/models/download \
  -H 'Content-Type: application/json' \
  -d '{"models": ["RealESRGAN_x4plus"]}'
```

### GPU Not Detected

```bash
# Check GPU availability
docker compose -f docker-compose.gpu.yml exec api python -c "import torch; print(torch.cuda.is_available())"

# Check system GPU
nvidia-smi
```

### Permission Issues with Volumes

```bash
# Fix volume ownership
docker compose exec api chown -R 1000:1000 /data/
```

## Git Workflow

The project uses Gitea as the remote repository:

```bash
# Add remote
git remote add gitea <gitea-repo-url>

# Commit and push
git add .
git commit -m "Add feature"
git push gitea main
```

Gitea workflows automatically:
- Build Docker images (CPU and GPU)
- Run tests
- Publish to Container Registry

## Important Notes

- **Model Weights**: Downloaded from GitHub releases (~100MB each)
- **GPU Support**: Requires NVIDIA Docker runtime
- **Async Processing**: Uses thread pool (configurable workers)
- **Tile Processing**: Handles large images by splitting into tiles
- **Data Persistence**: Volumes recommended for production