Add clean Model Card and Inference Documentation

README.md

@@ -0,0 +1,84 @@
+# Complete Multi-Task Image Auditor - Model Card
+
+This document provides a quick overview and instruction guide on how to load and run inference on the trained multi-task adversarial image auditor model.
+
+## Model Description
+The Complete Multi-Task Auditor is based on a `ResNet101` backbone augmented with a text encoder and specialized prediction heads. It is designed to evaluate images against six safety categories while providing interpretability metrics like seam quality and text faithfulness.
+
+### Output Metrics
+- **Global Safety Score:** Overall safety probability (1.0 = Safe, 0.0 = Unsafe).
+- **Category Probabilities:** Softmax probabilities across 6 classes: `Safe`, `Violence`, `Sexual`, `Hate`, `Illegal Activity`, and `Sensitive IP`.
+- **Faithfulness Score:** Evaluates how faithfully the image represents the given text prompt.
+- **Seam Quality:** Detects inpainting or generation artifacts (0.0 = Poor, 1.0 = flawless).
+- **Binary Map:** Adversarial/hotspot activation heatmap (numpy array).
+
+---
+
+## Quick Start: How to Use the Model
+
+### 1. Requirements
+Ensure you have the required dependencies and the tokenization/model definition loaded. You need the `auditor_inference.py` script accessible to import the architecture.
+
+```bash
+pip install torch torchvision numpy Pillow
+```
+
+### 2. Loading the Model Weights
+Once you or your team have downloaded the model from the Hugging Face repository, you can instantiate the architecture and load the checkpoint.
+
+```python
+import torch
+from PIL import Image
+
+# Import the model architecture and required globals from the standalone script
+from auditor_inference import CompleteMultiTaskAuditor, SimpleTokenizer, inference
+
+# Initialize the model (Ensure NUM_CLASSES=6 matches your training)
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+tokenizer = SimpleTokenizer(vocab_size=50000)
+
+model = CompleteMultiTaskAuditor(num_classes=6, vocab_size=50000)
+model.to(device)
+
+# Load the trained weights downloaded from HF
+checkpoint_path = "complete_auditor_best.pth"
+model.load_state_dict(torch.load(checkpoint_path, map_location=device))
+
+# Set to evaluation mode
+model.eval()
+print("Model loaded successfully!")
+```
+
+### 3. Running Inference
+You can use the built-in `inference` function added to the standalone script to easily benchmark and extract all metrics.
+
+```python
+# Load your image
+image_path = "path/to/your/test_image.jpg"
+image = Image.open(image_path).convert("RGB")
+
+# Provide the prompt used to generate the image (if applicable)
+prompt = "A photo of..." 
+
+# Run the inference function
+results = inference(model=model, tokenizer=tokenizer, image=image, prompt=prompt)
+
+# Print the metrics
+print("\n--- Auditor Results ---")
+print(f"Global Safety Score: {results['global_safety_score']:.4f}")
+print(f"Seam Quality:        {results['seam_quality']:.4f}")
+print(f"Faithfulness Score:  {results['faithfulness_score']:.4f}")
+
+print("\n--- Category Probabilities ---")
+for category, prob in results['category_probabilities'].items():
+    print(f"{category:>16}: {prob:.4f}")
+
+# The binary heatmap mask is available for visualization
+heatmap_array = results['binary_map']
+```
+
+## Interpreting Results
+* **Safety Score > 0.5**: Image is generally evaluated as safe.
+* **Category High Probability**: The model strongly suspects the image contains content from the respective category.
+* **Seam Quality < 0.5**: Indicates strong probability of visual anomalies, deepfake seams, or poor image quality.
+* **Faithfulness**: Helps determine if the adversarial content was strictly directed by the user's prompt or originated spontaneously.