# 🔍 Forensic Image Analysis Agent

AI-powered forensic image analysis system that detects AI-generated, manipulated, or deepfake images using vision-capable LLMs and forensic tools.

## 🚀 Features

- **Vision Analysis**: Direct image analysis using GPT-5
- **Forensic Tools**: Multiple forensic analysis tools including:
  - JPEG compression analysis
  - Frequency domain analysis (DCT/FFT)
  - Denoiser residual statistics
  - Error Level Analysis (ELA)
  - TruFor AI-driven forgery detection
  - Camera fingerprint extraction (noiseprint)
- **Streaming Output**: Real-time analysis updates
- **Transparent Reasoning**: Detailed explanations of findings

## 📋 Setup for Hugging Face Spaces

### 1. Create a New Space

1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Choose:
   - **SDK**: Gradio
   - **Hardware**: CPU (or GPU if you need faster inference)
   - **Visibility**: Public or Private

### 2. Upload Files

Upload these files to your Space:
- `app.py` (main Gradio application)
- `requirements_hf.txt` → copy/rename to `requirements.txt` (HF Spaces compatible dependencies)
- `README.md` (this file)
- `src/` directory (your source code)
- `weights/` directory (optional - TruFor weights will auto-download on first use)
- `example_images/` directory (optional, for examples)

**Note**: TruFor model weights (~500MB) will be automatically downloaded on first use. You can optionally pre-upload them to `weights/trufor/trufor.pth.tar` to skip the download.

### 3. Set API Key

1. Go to your Space settings
2. Navigate to "Variables and secrets"
3. Add a new secret:
   - **Name**: `OPENAI_API_KEY`
   - **Value**: Your OpenAI API key

### 4. Configure Space

Create or update `.env` file (optional, API key should be set via HF Secrets):
```
OPENAI_API_KEY=your-key-here
```

## 🎯 Usage

1. **Upload an Image**: Click the image upload area or drag & drop an image
2. **Optional Query**: Add a specific question about the image (e.g., "Is this AI-generated?")
3. **Configure Settings**: 
   - Enable/disable forensic tools
   - Choose LLM model (gpt-5.1 recommended)
   - Adjust temperature
4. **Analyze**: Click "🔍 Analyze Image" button
5. **View Results**: See detailed analysis with visual description, forensic findings, and conclusion

## ⚙️ Configuration

### Models Supported
- `gpt-5.1` (recommended) - Latest vision model
- `gpt-5` - Standard GPT-5
- `gpt-5-mini` - Faster, more cost-effective
- `gpt-5-nano` - Lightweight option

### Forensic Tools
When enabled, the agent can use:
- **analyze_jpeg_compression**: Analyzes JPEG compression artifacts
- **analyze_frequency_domain**: DCT/FFT frequency analysis
- **extract_residuals**: Denoiser residual statistics
- **perform_ela**: Error Level Analysis
- **perform_trufor**: AI-driven forgery detection
- **extract_noiseprint**: Camera fingerprint extraction
- **execute_python_code**: Custom Python analysis

## 📁 Project Structure

```
.
├── app.py                 # Gradio UI application
├── app_requirements.txt    # Dependencies for HF Spaces
├── README.md              # This file
├── src/
│   ├── agents/
│   │   └── forensic_agent.py
│   └── tools/
│       └── forensic_tools.py
└── weights/               # Model weights (if any)
```

## 🔒 Privacy & Security

- Images are processed temporarily and deleted after analysis
- API keys are stored securely via Hugging Face Secrets
- No data is stored permanently

## 🐛 Troubleshooting

### API Key Issues
- Ensure `OPENAI_API_KEY` is set in Space Secrets
- Check that your API key is valid and has credits

### Model Loading Issues
- For TruFor, ensure model weights are in `weights/trufor/`
- Check that all dependencies are installed correctly

### Memory Issues
- Use `gpt-5-mini` for lower memory usage
- Disable forensic tools if running on CPU-only hardware

## 📝 License

[Add your license here]

## 🙏 Acknowledgments

- Built with [LangChain](https://www.langchain.com/) and [LangGraph](https://github.com/langchain-ai/langgraph)
- Powered by [OpenAI GPT-5](https://openai.com/)
- UI built with [Gradio](https://www.gradio.app/)