README.md

---
license: mit
language:
  - en
library_name: pytorch
tags:
  - image-classification
  - computer-vision
  - ai-detection
  - deepfake-detection
  - pytorch
  - image-quality
datasets:
  - custom
metrics:
  - accuracy
pipeline_tag: image-classification
model-index:
  - name: TIGAS
    results:
      - task:
          type: image-classification
          name: AI-Generated Image Detection
        metrics:
          - type: accuracy
            value: 0.656
            name: Validation Accuracy
          - type: loss
            value: 0.308
            name: Validation Loss
---

# TIGAS - Trained Image Generation Authenticity Score

<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-red.svg)](https://pytorch.org/)

**Neural network metric for detecting AI-generated images**

[GitHub Repository](https://github.com/H1merka/TIGAS) • [Documentation](https://github.com/H1merka/TIGAS/blob/main/README_eng.md)

</div>

## Model Description

TIGAS (Trained Image Generation Authenticity Score) is a multi-branch neural network designed to distinguish between real/natural images and AI-generated/fake images. It provides a continuous score in the range [0, 1]:

- **1.0** — Natural/Real image
- **0.0** — AI-Generated/Fake image

### Architecture

The model uses a **Full Mode** architecture with three complementary analysis branches:

1. **Perceptual Features** — Multi-scale CNN extracting visual patterns at 1/2, 1/4, 1/8, 1/16 resolutions
2. **Spectral Analysis** — FFT-based frequency domain analysis for detecting GAN artifacts
3. **Statistical Consistency** — Distribution analysis and moment estimation
4. **Cross-Modal Attention** — Fuses features from all branches for final prediction

### Model Specifications

| Property | Value |
|----------|-------|
| **Parameters** | ~18.9M |
| **Input Size** | 256×256 RGB |
| **Output** | Single score [0, 1] |
| **Architecture** | TIGASModel (Full Mode) |
| **File Size** | ~217 MB |

## Training Details

### Dataset

- **Training samples**: 128,776 images
- **Validation samples**: 14,167 images
- **Test samples**: 14,126 images
- **Total**: 157,069 images
- **Class balance**: ~46% real, ~54% fake

### Training Configuration

| Parameter | Value |
|-----------|-------|
| Epochs | 3 |
| Batch Size | 8 |
| Image Size | 256×256 |
| Learning Rate | 1e-4 (with warmup) |
| Optimizer | AdamW |
| Scheduler | Cosine Annealing |
| Mixed Precision | Enabled (AMP) |
| Hardware | NVIDIA RTX 3050 Ti (4GB VRAM) |

### Training Results

| Epoch | Train Loss | Val Loss | Val Accuracy |
|-------|------------|----------|--------------|
| 0 | 0.4115 | 0.3262 | 61.46% |
| 1 | 0.3707 | 0.3099 | 65.09% |
| 2 | 0.3506 | **0.3079** | **65.55%** |

**Note**: This is an early checkpoint after 3 epochs of training. The model is still learning and accuracy will improve with more training epochs (recommended: 30-50 epochs for production use).

## Usage

### Installation

```bash
pip install torch torchvision
pip install huggingface-hub

# Clone the TIGAS repository
git clone https://github.com/H1merka/TIGAS.git
cd TIGAS
pip install -e .
```

### Quick Start

```python
from tigas import TIGAS

# Initialize with auto-download from HuggingFace Hub
tigas = TIGAS(auto_download=True)

# Evaluate single image
score = tigas('path/to/image.jpg')
print(f"Authenticity Score: {score:.4f}")

# Interpretation
if score > 0.7:
    print("Likely REAL (High Confidence)")
elif score > 0.5:
    print("Probably REAL (Medium Confidence)")
elif score > 0.3:
    print("Probably FAKE (Medium Confidence)")
else:
    print("Likely FAKE (High Confidence)")
```

### Batch Processing

```python
import torch
from tigas import TIGAS

tigas = TIGAS(auto_download=True, device='cuda')

# Process batch of images
images = torch.randn(8, 3, 256, 256)  # [B, C, H, W]
scores = tigas(images)
print(f"Mean score: {scores.mean():.4f}")
```

### Directory Processing

```python
from tigas import TIGAS

tigas = TIGAS(auto_download=True)

# Evaluate all images in directory
results = tigas.compute_directory(
    'path/to/images/',
    return_paths=True,
    batch_size=32
)

for img_path, score in results.items():
    print(f"{img_path}: {score:.4f}")
```

### As a Differentiable Loss Function

```python
from tigas import TIGAS

tigas = TIGAS(auto_download=True)

# In generator training loop
generated_images = generator(noise)
authenticity_score = tigas(generated_images)

# Maximize authenticity (make images look more real)
loss = 1.0 - authenticity_score.mean()
loss.backward()
```

### Command Line

```bash
# Single image evaluation
python scripts/evaluate.py --image test.jpg --auto_download

# Directory evaluation
python scripts/evaluate.py --image_dir images/ --auto_download --batch_size 32

# Save results
python scripts/evaluate.py --image_dir images/ --output results.json --plot
```

## Loading the Model Manually

```python
import torch
from huggingface_hub import hf_hub_download

# Download checkpoint
checkpoint_path = hf_hub_download(
    repo_id="H1merka/TIGAS",
    filename="best_model.pt"
)

# Load checkpoint
checkpoint = torch.load(checkpoint_path, map_location='cpu')

# Access model weights
model_state_dict = checkpoint['model_state_dict']
epoch = checkpoint['epoch']
best_val_loss = checkpoint['best_val_loss']

print(f"Loaded model from epoch {epoch}")
print(f"Best validation loss: {best_val_loss:.4f}")
```

## Checkpoint Contents

The checkpoint file (`best_model.pt`) contains:

| Key | Description |
|-----|-------------|
| `model_state_dict` | Model weights |
| `optimizer_state_dict` | Optimizer state (for resume training) |
| `scheduler_state_dict` | LR scheduler state |
| `scaler_state_dict` | AMP GradScaler state |
| `epoch` | Training epoch number |
| `global_step` | Global training step |
| `best_val_loss` | Best validation loss achieved |
| `train_history` | Training loss history |
| `val_history` | Validation metrics history |

## Limitations

- **Early Training Stage**: This checkpoint is from early training (3 epochs). For production use, train for 30-50+ epochs.
- **Dataset Bias**: Performance may vary on images from generators not represented in the training set.
- **Resolution Dependency**: Best results at 256×256. Other resolutions are automatically resized.
- **Adversarial Robustness**: Not specifically hardened against adversarial attacks.

## Intended Use

### Primary Use Cases

- Detecting AI-generated images in content moderation
- Evaluating quality of generative models
- Research on image authenticity
- Integration as a loss function for training more realistic generators

### Out-of-Scope Use

- Legal evidence without human verification
- Sole basis for content removal decisions
- Real-time processing of high-volume streams (without optimization)

## Citation

```bibtex
@software{tigas2025,
  title = {TIGAS: Trained Image Generation Authenticity Score},
  author = {Morgenshtern, Dmitrij},
  year = {2025},
  url = {https://github.com/H1merka/TIGAS},
  license = {MIT}
}
```

## License

This model is released under the [MIT License](LICENSE).

## Contact

- **GitHub**: [H1merka/TIGAS](https://github.com/H1merka/TIGAS)
- **Issues**: [GitHub Issues](https://github.com/H1merka/TIGAS/issues)