| # 🔍 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/) | |