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)