Every image on the internet has been through hell: screenshotted, re-compressed, platform-resized, color-shifted, watermarked, and re-shared dozens of times. Existing tools blindly upscale or denoise. Artefex is different - it first diagnoses what happened to your media, then reverses each step specifically.

Think of it as git log for media degradation, followed by intelligent undo.

Why Artefex?

Install

pip install artefex               # core (images only)
pip install artefex[web]          # adds web UI
pip install artefex[video]        # adds video support
pip install artefex[neural]       # adds ONNX neural models
pip install artefex[all]          # everything

Or install from source:

git clone https://github.com/turnert2005/artefex.git
cd artefex
pip install -e ".[all]"

Or with Docker:

docker compose up             # web UI at http://localhost:8787

Neural Models

Artefex uses pre-trained neural models for forensic analysis and restoration. Install the models after setup:

python train/convert_pretrained.py --install
artefex models list                              # verify installation

Artefex works without neural models using classical signal processing. Neural models provide dramatically better results for JPEG artifacts, noise, blur, AI detection, and physical damage repair.

Quick start

# Diagnose what happened to an image
artefex analyze photo.jpg

# Get a quality grade (A-F)
artefex grade photo.jpg

# Reverse the degradation chain
artefex restore photo.jpg

# Full forensic audit
artefex audit photo.jpg

Commands

Analysis

artefex analyze photo.jpg                     # diagnose degradation chain
artefex analyze photo.jpg --json              # machine-readable output
artefex analyze photo.jpg --verbose           # detailed detection info
artefex analyze https://example.com/img.jpg   # analyze from URL
artefex analyze ./photos/                     # batch mode

Quality grading

artefex grade photo.jpg                       # A-F grade with score
artefex grade ./photos/ --export csv          # batch export as CSV
artefex grade ./photos/ --export markdown     # batch export as markdown

Forensic tools

artefex report photo.jpg                      # text forensic report
artefex report photo.jpg --html               # rich HTML report with charts
artefex timeline photo.jpg                    # ASCII degradation timeline
artefex story photo.jpg                       # natural language forensic narrative
artefex heatmap photo.jpg                     # spatial degradation heatmap
artefex palette photo.jpg                     # extract dominant color palette
artefex orient photo.jpg --fix                # detect and fix orientation
artefex audit photo.jpg                       # comprehensive audit (all tools)

Restoration

artefex restore photo.jpg                     # reverse the degradation chain
artefex restore photo.jpg --format png        # convert output format
artefex restore photo.jpg --no-neural         # classical methods only
artefex restore ./photos/                     # batch restore
artefex restore-preview photo.jpg             # save each step as separate file

Comparison

artefex compare original.jpg restored.jpg     # MSE, PSNR, SSIM, heatmap
artefex gallery ./originals/ ./restored/      # HTML side-by-side gallery
artefex duplicates ./photos/                  # find duplicate images
artefex duplicates ./photos/ --threshold 0.8  # adjust similarity threshold

Video

artefex video-analyze clip.mp4                # sample frames for degradation
artefex video-restore clip.mp4                # restore frame by frame

Web and automation

artefex web                                   # launch web UI with drag-and-drop
artefex watch ./inbox/ --restore              # auto-process new images
artefex dashboard ./photos/                   # generate HTML overview dashboard
artefex rename-by-grade ./photos/ --dry-run   # preview grade-based renaming
artefex parallel-analyze ./photos/            # multi-process batch analysis

System

artefex version                               # show version and dependency status
artefex models list                           # show available neural models
artefex models import deblock-v1 model.onnx   # import a model
artefex plugins                               # list installed plugins

What it detects

14 forensic detectors run on every image, providing a complete degradation chain analysis.

Python API

from artefex import analyze, restore, grade

# Diagnose
result = analyze("photo.jpg")
for d in result.degradations:
    print(f"{d.name}: {d.confidence:.0%} confidence, severity {d.severity:.0%}")

# Grade
grade_result = grade("photo.jpg")
print(f"Grade: {grade_result}")

# Restore
restore("photo.jpg", output="photo_restored.png")

Configuration

Create .artefex.toml in your project or ~/.artefex.toml globally:

[analysis]
min_confidence = 0.15

[restore]
use_neural = true
output_format = "png"

[web]
port = 8787

Also supports [tool.artefex] in pyproject.toml.

Training custom models

cd train/
python generate_data.py --source /path/to/clean --output ./data --type deblock
python deblock_train.py --data ./data --epochs 50
artefex models import deblock-v1 ./models/deblock_v1.onnx

Plugins

Artefex supports community plugins via Python entry points:

# In your plugin's pyproject.toml
[project.entry-points."artefex.detectors"]
my_detector = "my_package:MyDetector"

[project.entry-points."artefex.restorers"]
my_restorer = "my_package:MyRestorer"

See examples/custom_plugin.py for a complete example.

Architecture

artefex analyze <image>
    |
    v
+------------------------+
| 13 Built-in Detectors  |  JPEG, noise, color, resolution, screenshot,
| + Plugin Detectors     |  watermark, EXIF, platform, AI-gen, stego,
|                        |  camera ID, copy-move forgery
+------------------------+
    |
    v
+------------------------+
| Degradation Chain      |  Sorted by severity, graded A-F
+------------------------+
    |
    v
+------------------------+
| Restoration Pipeline   |  Neural (ONNX) -> Plugin -> Classical
+------------------------+
    |
    v
  restored image + report + heatmap + grade

Roadmap

• v0.1 - Detection engine (8 detectors) + classical restoration pipeline
• v0.2 - Neural ONNX models, web UI, video/GIF support, training pipeline, plugin system
• v0.3 - Platform fingerprinting (7 platforms), AI-generated detection, steganography, camera ID, copy-move forgery, A-F grading, accessibility checker, color palette extraction, orientation correction, duplicate detection, quality gate for CI/CD, batch dashboard, HTML reports with histograms, forensic narrative generation
• v0.4 - Test ONNX model generation, model download infrastructure, SHA-256 verification
• v0.5 - Video temporal coherence, audio passthrough via ffmpeg, multi-codec output
• v0.8 - 244 tests (unit + integration + edge cases + E2E), API stability with TypedDicts
• v1.0 - Pre-trained neural models (FBCNN +3-4 dB JPEG, DnCNN +13-21 dB noise, NAFNet deblurring, SAFE 98.9% AI detection, LaMa inpainting with face protection), 14 forensic detectors, guided web UI, Windows packaging (current)
• v1.1 - First-launch model auto-downloader, improved inpainting with user-adjustable masks
• v1.2 - Interactive web UI with WebSocket progress and batch management
• v1.3 - Expanded model zoo (super-resolution, dehazing)
• v1.4 - Multi-class AI detection (real vs AI-generated vs AI-modified vs AI-upscaled)

Contributing

We welcome contributions of all sizes - from typo fixes to new detectors. See CONTRIBUTING.md for setup and guidelines.

New here? Look for issues labeled good first issue - these are scoped tasks designed for first-time contributors.

Have questions? Join the Discussions.

License

MIT