README_SPACE.md

🔍 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
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 and LangGraph
• Powered by OpenAI GPT-5
• UI built with Gradio