# Context-Aware Image Anonymization with Multi-Agent Reasoning

**Anonymous CVPR Submission - Supplementary Code**

This repository contains the implementation code for the CVPR submission. All identifying information has been removed for double-blind review.

## Installation & Quick Start

### Prerequisites

**Hardware Requirements:**
- **GPU**: NVIDIA GPU with 20GB+ VRAM (recommended: L40S 48GB, A100, or H100)
- **RAM**: 32GB+ system memory
- **Storage**: 50GB+ free disk space

**Software Requirements:**
- Python 3.11+
- CUDA 12.1+
- Conda (Anaconda or Miniconda)

### Environment Setup

```bash
# Create conda environment
conda create -n anonymizer python=3.11 -y
conda activate anonymizer

# Install PyTorch with CUDA 12.1
pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu121

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

### Configuration

```bash
# Copy example configuration
cp .env.example .env

# Edit configuration (recommended: use Ollama for local inference)
# Set USE_OLLAMA_VISION=true for privacy-preserving local execution
nano .env
```

### Model Downloads

1. **YOLOv8m-seg**: Auto-downloads on first run
2. **Grounded-SAM-2**: See `docs/` for setup instructions
3. **Stable Diffusion XL**: Auto-downloads via Diffusers library
4. **Ollama Models**: Install Ollama and run `ollama pull qwen2.5vl:32b`

### Quick Start

```bash
# Process a single image
python -m mcp.clients.agents.main \
  input.jpg \
  output.jpg \
  --backend grounded-sam-2

# Launch web GUI
python gui_web_anonymizer.py
```

## Project Structure

```
code/
├── mcp/                      # MCP servers and multi-agent clients
│   ├── servers/              # Detection, inpainting, auditing servers
│   └── clients/agents/       # Orchestrator, Generative, Auditor agents
├── tools/                    # Testing and debugging utilities
├── scripts/                  # Setup scripts
├── prompts/                  # Agent system prompts
├── models/                   # Model weights (see README for setup)
├── batch_process.py          # Batch processing script
├── gui_web_anonymizer.py     # Web-based GUI
├── requirements.txt          # Python dependencies
└── .env.example              # Configuration template
```

## Key Components

### Multi-Agent Architecture
- **OrchestratorAgent**: Coordinates the anonymization workflow
- **GenerativeAgent**: Performs diffusion-based inpainting
- **AuditorAgent**: Verifies PII removal and quality
- **UserProxyAgent**: Handles user interactions

### Detection Backends
- YOLOv8m-seg for person segmentation
- Custom YOLOv8s for license plate detection
- YOLO-TS for traffic sign detection
- Grounded-SAM-2 for indirect PII detection

### Inpainting Models
- SDXL + OpenPose ControlNet (persons)
- SDXL + Canny ControlNet (objects)
- Vision LLM for context-aware descriptions

## Documentation

Detailed algorithmic specifications and implementation details are provided in the supplementary PDF.

## Hardware Configuration

### Single GPU (24GB+ VRAM)
```bash
export INPAINT_USE_SDXL=true
export INPAINT_SDXL_RESOLUTION=768
```

### Dual GPU (Recommended)
```bash
# GPU 0: Agent + SDXL + Detection
# GPU 1: Vision model (Ollama)
./restart_ollama.sh --start-only --gpu 0,1
```

## Reproducibility

All hyperparameters used in the paper are documented in:
- `.env.example` - Environment configuration with all parameters
- Supplementary PDF - Complete algorithm specifications

## License

Code provided for research purposes only. Review component licenses before use.

## Support

For questions during the review period, please use the CVPR review system.
