{"id":47714359,"url":"https://github.com/turnert2005/artefex","last_synced_at":"2026-04-02T18:48:28.854Z","repository":{"id":347671342,"uuid":"1194855655","full_name":"turnert2005/artefex","owner":"turnert2005","description":"Neural forensic restoration - diagnose and reverse media degradation chains","archived":false,"fork":false,"pushed_at":"2026-03-29T01:10:22.000Z","size":204,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T01:15:33.232Z","etag":null,"topics":["cli","forensics","image-processing","image-quality","image-restoration","jpeg","neural-network","onnx","python","steganography"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turnert2005.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T22:39:25.000Z","updated_at":"2026-03-29T01:10:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/turnert2005/artefex","commit_stats":null,"previous_names":["turnert2005/artefex"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/turnert2005/artefex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turnert2005%2Fartefex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turnert2005%2Fartefex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turnert2005%2Fartefex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turnert2005%2Fartefex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turnert2005","download_url":"https://codeload.github.com/turnert2005/artefex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turnert2005%2Fartefex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31313394,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","forensics","image-processing","image-quality","image-restoration","jpeg","neural-network","onnx","python","steganography"],"created_at":"2026-04-02T18:48:26.380Z","updated_at":"2026-04-02T18:48:28.838Z","avatar_url":"https://github.com/turnert2005.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# artefex\n\n**Forensic image analysis - detect AI content, trace image history, assess quality, and clean artifacts.**\n\n[![CI](https://github.com/turnert2005/artefex/actions/workflows/ci.yml/badge.svg)](https://github.com/turnert2005/artefex/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Version](https://img.shields.io/badge/version-1.0.0-purple.svg)](https://github.com/turnert2005/artefex/releases/tag/v1.0.0)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n[Getting Started](#install) | [Commands](#commands) | [Contributing](CONTRIBUTING.md) | [Discussions](https://github.com/turnert2005/artefex/discussions)\n\n\u003c/div\u003e\n\n---\n\nEvery 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**.\n\nThink of it as `git log` for media degradation, followed by intelligent undo.\n\n## Why Artefex?\n\n| | Other tools | Artefex |\n|---|---|---|\n| **Approach** | Blindly upscale/denoise everything | Diagnose first, then reverse each degradation step |\n| **Analysis** | None | 13 forensic detectors - JPEG artifacts, platform fingerprinting, AI detection, steganography, forgery |\n| **AI Detection** | None | SAFE neural classifier - 98.9% accuracy on modern generators (GPT-4o, FLUX, SD-3, Midjourney) |\n| **Restoration** | One-size-fits-all filter | FBCNN JPEG cleaning (+3-4 dB), neural denoising (+13-21 dB), neural deblurring (+0.6-1.2 dB), LaMa inpainting with face protection |\n| **Extensibility** | Closed | Plugin system for custom detectors and restorers |\n| **Interface** | Usually GUI-only | CLI + Python API + Web UI + Docker |\n\n## Install\n\n```bash\npip install artefex               # core (images only)\npip install artefex[web]          # adds web UI\npip install artefex[video]        # adds video support\npip install artefex[neural]       # adds ONNX neural models\npip install artefex[all]          # everything\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/turnert2005/artefex.git\ncd artefex\npip install -e \".[all]\"\n```\n\nOr with Docker:\n\n```bash\ndocker compose up             # web UI at http://localhost:8787\n```\n\n## Neural Models\n\nArtefex uses pre-trained neural models for forensic analysis and restoration. Install the models after setup:\n\n```bash\npython train/convert_pretrained.py --install\nartefex models list                              # verify installation\n```\n\n| Model | Task | Size | Performance | License |\n|-------|------|------|-------------|---------|\n| FBCNN | JPEG artifact removal | 274 MB | +2.7 to +4.3 dB PSNR improvement | Apache 2.0 |\n| DnCNN color blind | Noise removal | 2.6 MB | +13 to +21 dB PSNR improvement | MIT (KAIR) |\n| NAFNet GoPro-w32 | Blur/detail recovery | 65.7 MB | +0.6 to +1.2 dB on moderate blur | MIT (megvii) |\n| SAFE | AI image detection | 5.5 MB | 98.9% accuracy on modern generators | Apache 2.0 |\n| LaMa | Physical damage repair | 88 MB | Inpainting with face protection | Apache 2.0 (OpenCV) |\n\nArtefex 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.\n\n## Quick start\n\n```bash\n# Diagnose what happened to an image\nartefex analyze photo.jpg\n\n# Get a quality grade (A-F)\nartefex grade photo.jpg\n\n# Reverse the degradation chain\nartefex restore photo.jpg\n\n# Full forensic audit\nartefex audit photo.jpg\n```\n\n## Commands\n\n### Analysis\n\n```bash\nartefex analyze photo.jpg                     # diagnose degradation chain\nartefex analyze photo.jpg --json              # machine-readable output\nartefex analyze photo.jpg --verbose           # detailed detection info\nartefex analyze https://example.com/img.jpg   # analyze from URL\nartefex analyze ./photos/                     # batch mode\n```\n\n### Quality grading\n\n```bash\nartefex grade photo.jpg                       # A-F grade with score\nartefex grade ./photos/ --export csv          # batch export as CSV\nartefex grade ./photos/ --export markdown     # batch export as markdown\n```\n\n### Forensic tools\n\n```bash\nartefex report photo.jpg                      # text forensic report\nartefex report photo.jpg --html               # rich HTML report with charts\nartefex timeline photo.jpg                    # ASCII degradation timeline\nartefex story photo.jpg                       # natural language forensic narrative\nartefex heatmap photo.jpg                     # spatial degradation heatmap\nartefex palette photo.jpg                     # extract dominant color palette\nartefex orient photo.jpg --fix                # detect and fix orientation\nartefex audit photo.jpg                       # comprehensive audit (all tools)\n```\n\n### Restoration\n\n```bash\nartefex restore photo.jpg                     # reverse the degradation chain\nartefex restore photo.jpg --format png        # convert output format\nartefex restore photo.jpg --no-neural         # classical methods only\nartefex restore ./photos/                     # batch restore\nartefex restore-preview photo.jpg             # save each step as separate file\n```\n\n### Comparison\n\n```bash\nartefex compare original.jpg restored.jpg     # MSE, PSNR, SSIM, heatmap\nartefex gallery ./originals/ ./restored/      # HTML side-by-side gallery\nartefex duplicates ./photos/                  # find duplicate images\nartefex duplicates ./photos/ --threshold 0.8  # adjust similarity threshold\n```\n\n### Video\n\n```bash\nartefex video-analyze clip.mp4                # sample frames for degradation\nartefex video-restore clip.mp4                # restore frame by frame\n```\n\n### Web and automation\n\n```bash\nartefex web                                   # launch web UI with drag-and-drop\nartefex watch ./inbox/ --restore              # auto-process new images\nartefex dashboard ./photos/                   # generate HTML overview dashboard\nartefex rename-by-grade ./photos/ --dry-run   # preview grade-based renaming\nartefex parallel-analyze ./photos/            # multi-process batch analysis\n```\n\n### System\n\n```bash\nartefex version                               # show version and dependency status\nartefex models list                           # show available neural models\nartefex models import deblock-v1 model.onnx   # import a model\nartefex plugins                               # list installed plugins\n```\n\n## What it detects\n\n| Category | Detector | Method |\n|---|---|---|\n| Compression | JPEG artifacts | 8x8 block boundary discontinuity analysis |\n| Compression | Multiple re-compressions | Double quantization + ringing detection |\n| Resolution | Upscaling/loss | High-frequency spectral analysis + autocorrelation |\n| Color | Color shift | Channel imbalance + clip ratio analysis |\n| Artifacts | Screenshot remnants | Border uniformity + aspect ratio + dimensions |\n| Noise | Sensor/added noise | Laplacian MAD estimation |\n| Overlay | Watermarks | Tile correlation + histogram peaks + alpha channel |\n| Metadata | EXIF stripping | Metadata presence/completeness checks |\n| Provenance | Platform fingerprint | Dimension/compression/EXIF signatures for Twitter, Instagram, WhatsApp, Facebook, Telegram, Discord, Imgur |\n| Provenance | AI-generated content | SAFE neural classifier (98.9% accuracy) with heuristic fallback (frequency, histogram, noise, patch analysis) |\n| Security | Steganography | LSB analysis, chi-square test, entropy, pairs analysis |\n| Provenance | Camera/device ID | Sensor noise PRNU analysis (DSLR, smartphone, webcam, scanner) |\n| Forgery | Copy-move detection | Patch-based feature matching for cloned regions |\n| Physical | Damage detection | Bright flaking, scratch, tear, and stain detection with face-protected LaMa inpainting |\n\n**14 forensic detectors** run on every image, providing a complete degradation chain analysis.\n\n## Python API\n\n```python\nfrom artefex import analyze, restore, grade\n\n# Diagnose\nresult = analyze(\"photo.jpg\")\nfor d in result.degradations:\n    print(f\"{d.name}: {d.confidence:.0%} confidence, severity {d.severity:.0%}\")\n\n# Grade\ngrade_result = grade(\"photo.jpg\")\nprint(f\"Grade: {grade_result}\")\n\n# Restore\nrestore(\"photo.jpg\", output=\"photo_restored.png\")\n```\n\n## Configuration\n\nCreate `.artefex.toml` in your project or `~/.artefex.toml` globally:\n\n```toml\n[analysis]\nmin_confidence = 0.15\n\n[restore]\nuse_neural = true\noutput_format = \"png\"\n\n[web]\nport = 8787\n```\n\nAlso supports `[tool.artefex]` in `pyproject.toml`.\n\n## Training custom models\n\n```bash\ncd train/\npython generate_data.py --source /path/to/clean --output ./data --type deblock\npython deblock_train.py --data ./data --epochs 50\nartefex models import deblock-v1 ./models/deblock_v1.onnx\n```\n\n## Plugins\n\nArtefex supports community plugins via Python entry points:\n\n```toml\n# In your plugin's pyproject.toml\n[project.entry-points.\"artefex.detectors\"]\nmy_detector = \"my_package:MyDetector\"\n\n[project.entry-points.\"artefex.restorers\"]\nmy_restorer = \"my_package:MyRestorer\"\n```\n\nSee `examples/custom_plugin.py` for a complete example.\n\n## Architecture\n\n```\nartefex analyze \u003cimage\u003e\n    |\n    v\n+------------------------+\n| 13 Built-in Detectors  |  JPEG, noise, color, resolution, screenshot,\n| + Plugin Detectors     |  watermark, EXIF, platform, AI-gen, stego,\n|                        |  camera ID, copy-move forgery\n+------------------------+\n    |\n    v\n+------------------------+\n| Degradation Chain      |  Sorted by severity, graded A-F\n+------------------------+\n    |\n    v\n+------------------------+\n| Restoration Pipeline   |  Neural (ONNX) -\u003e Plugin -\u003e Classical\n+------------------------+\n    |\n    v\n  restored image + report + heatmap + grade\n```\n\n## Roadmap\n\n- [x] **v0.1** - Detection engine (8 detectors) + classical restoration pipeline\n- [x] **v0.2** - Neural ONNX models, web UI, video/GIF support, training pipeline, plugin system\n- [x] **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\n- [x] **v0.4** - Test ONNX model generation, model download infrastructure, SHA-256 verification\n- [x] **v0.5** - Video temporal coherence, audio passthrough via ffmpeg, multi-codec output\n- [x] **v0.8** - 244 tests (unit + integration + edge cases + E2E), API stability with TypedDicts\n- [x] **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)**\n- [ ] **v1.1** - First-launch model auto-downloader, improved inpainting with user-adjustable masks\n- [ ] **v1.2** - Interactive web UI with WebSocket progress and batch management\n- [ ] **v1.3** - Expanded model zoo (super-resolution, dehazing)\n- [ ] **v1.4** - Multi-class AI detection (real vs AI-generated vs AI-modified vs AI-upscaled)\n\n## Contributing\n\nWe welcome contributions of all sizes - from typo fixes to new detectors. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.\n\n**New here?** Look for issues labeled [`good first issue`](https://github.com/turnert2005/artefex/labels/good%20first%20issue) - these are scoped tasks designed for first-time contributors.\n\n**Have questions?** Join the [Discussions](https://github.com/turnert2005/artefex/discussions).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturnert2005%2Fartefex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturnert2005%2Fartefex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturnert2005%2Fartefex/lists"}