minosse 0.1.0__tar.gz

minosse-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+data/
+results/
+minosse/__pycache__/
+dist/
+build/
+*.egg-info/
+minosse/_version.py

minosse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlo Esposito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

minosse-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: minosse
+Version: 0.1.0
+Summary: Detects AI-generated or AI-edited images using signal-processing artifact analysis — no ML model.
+Project-URL: Homepage, https://github.com/cesp99/Minosse
+Project-URL: Issues, https://github.com/cesp99/Minosse/issues
+Author: cesp99
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-detection,diffusion,image-forensics,signal-processing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# Minosse
+
+Detects AI-generated or AI-edited images using three complementary,
+hand-crafted artifact signals — **no ML model, just signal processing.**
+
+Minosse looks for tell-tale traces that diffusion models and neural
+upsamplers leave behind: ringing halos around text, noise in flat
+regions that shouldn't have any, and a synthetic signature in the
+high-frequency spectrum.
+
+## Signals
+
+| Signal | What it catches | How it works |
+|---|---|---|
+| **ringing** | Diffusion VAE decoder halos | Radial profile of band-pass energy vs. distance from strong edges. Real edges decay fast; ringing persists 10–40 px out. |
+| **noisy-flats** | AI "film grain" on solid panels | RMS residual noise inside coarse-flat regions. Real screenshots are truly flat; JPEG smooths photo flats. |
+| **synthetic-noise** | Upsampled / generated noise | Spectral energy at the Nyquist ring vs. mid frequencies. Real sensor noise stays hot at the highest frequencies; synthetic noise dies off. |
+
+An image is flagged if **any** signal fires; the fired signals are reported
+along with the raw feature values.
+
+
+## Quick start
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+# Analyse a single image
+.venv/bin/python -m minosse path/to/image.png
+
+# Analyse multiple images with visual proof sheets
+.venv/bin/python -m minosse --proof results/ image1.png image2.jpg
+```
+
+### `--proof` output
+
+The `--proof` flag writes `<name>_proof.png`: a side-by-side sheet with
+the original image next to one panel per fired signal, with the artifact
+evidence burned in as a **red heatmap**.
+
+Heat is scaled absolutely (calibrated to the detection thresholds), so
+clean images render dark — the glow itself is the proof. For ringing,
+the map only shows oscillation in regions that *should* be smooth (8–40 px
+from strong edges, locally flat at coarse scale), so legitimate texture
+doesn't light up.
+
+## Python API
+
+```python
+from minosse import analyze, analyze_path, Result
+
+# From a file path
+r = analyze_path("image.png")
+print(r.verdict)       # "likely AI-generated/edited" or "likely clean"
+print(r.reasons)       # e.g. ["ringing", "synthetic-noise"]
+print(r.decay)         # ringing feature value
+print(r.vhf_mf)        # spectral ratio feature value
+print(r.flat_noise)    # flat-region noise feature value
+print(r.resid_std)     # overall residual noise
+
+# From a PIL Image
+from PIL import Image
+img = Image.open("image.png")
+r = analyze(img)
+```
+
+### `Result` fields
+
+| Field | Type | Description |
+|---|---|---|
+| `verdict` | `str` | `"likely AI-generated/edited"` or `"likely clean"` |
+| `reasons` | `list[str]` | Fired signal names: `ringing`, `noisy-flats`, `synthetic-noise` |
+| `score` | `float` | Confidence score `[0, 1]` (0.75 per firing signal, capped at 1.0) |
+| `decay` | `float` | Ringing persistence: mid-distance / near-edge band energy |
+| `halo_vs_bg` | `float` | Mid-distance energy vs. image background |
+| `vhf_mf` | `float` | Spectral ratio: Nyquist ring / mid frequencies |
+| `resid_std` | `float` | Standard deviation of the noise residual |
+| `flat_noise` | `float` | RMS residual inside coarse-flat regions |
+
+### Visual proof from Python
+
+```python
+from minosse import analyze, evidence
+from PIL import Image
+
+img = Image.open("image.png")
+r = analyze(img)
+sheet = evidence.render(img, r)
+sheet.save("proof.png")
+```
+
+## Project structure
+
+```
+minosse/
+├── minosse/
+│   ├── __init__.py      # Public API: analyze, analyze_path, Result
+│   ├── __main__.py      # python -m minosse entry point
+│   ├── cli.py           # Argument parsing and CLI loop
+│   ├── detector.py      # Feature extraction + threshold logic
+│   └── evidence.py      # Visual proof sheet renderer
+├── results/             # Default --proof output directory
+├── requirements.txt     # numpy, pillow, scipy
+└── README.md
+```
+
+## How it works (briefly)
+
+1. **Preprocessing** — the image is converted to RGB and downscaled if
+   its longest edge exceeds 1600 px.
+2. **Feature extraction** (`detector._features()`) — three independent
+   signal-processing pipelines compute scalar features from the
+   grayscale luminance.
+3. **Thresholding** — each feature is compared against a tuned threshold;
+   if it exceeds the threshold the corresponding signal is flagged.
+4. **Verdict** — if any signal fires, the image is marked likely
+   AI-generated/edited; otherwise it's likely clean.
+
+For a deeper explanation of each signal, see [docs/signals.md](docs/signals.md).
+
+## Caveats
+
+The thresholds are calibrated on a small set of examples and should be
+re-validated as more AI samples are added. See [docs/tuning.md](docs/tuning.md)
+for instructions on re-tuning.
+
+## License
+
+MIT

minosse-0.1.0/README.md

@@ -0,0 +1,130 @@
+# Minosse
+
+Detects AI-generated or AI-edited images using three complementary,
+hand-crafted artifact signals — **no ML model, just signal processing.**
+
+Minosse looks for tell-tale traces that diffusion models and neural
+upsamplers leave behind: ringing halos around text, noise in flat
+regions that shouldn't have any, and a synthetic signature in the
+high-frequency spectrum.
+
+## Signals
+
+| Signal | What it catches | How it works |
+|---|---|---|
+| **ringing** | Diffusion VAE decoder halos | Radial profile of band-pass energy vs. distance from strong edges. Real edges decay fast; ringing persists 10–40 px out. |
+| **noisy-flats** | AI "film grain" on solid panels | RMS residual noise inside coarse-flat regions. Real screenshots are truly flat; JPEG smooths photo flats. |
+| **synthetic-noise** | Upsampled / generated noise | Spectral energy at the Nyquist ring vs. mid frequencies. Real sensor noise stays hot at the highest frequencies; synthetic noise dies off. |
+
+An image is flagged if **any** signal fires; the fired signals are reported
+along with the raw feature values.
+
+
+## Quick start
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+# Analyse a single image
+.venv/bin/python -m minosse path/to/image.png
+
+# Analyse multiple images with visual proof sheets
+.venv/bin/python -m minosse --proof results/ image1.png image2.jpg
+```
+
+### `--proof` output
+
+The `--proof` flag writes `<name>_proof.png`: a side-by-side sheet with
+the original image next to one panel per fired signal, with the artifact
+evidence burned in as a **red heatmap**.
+
+Heat is scaled absolutely (calibrated to the detection thresholds), so
+clean images render dark — the glow itself is the proof. For ringing,
+the map only shows oscillation in regions that *should* be smooth (8–40 px
+from strong edges, locally flat at coarse scale), so legitimate texture
+doesn't light up.
+
+## Python API
+
+```python
+from minosse import analyze, analyze_path, Result
+
+# From a file path
+r = analyze_path("image.png")
+print(r.verdict)       # "likely AI-generated/edited" or "likely clean"
+print(r.reasons)       # e.g. ["ringing", "synthetic-noise"]
+print(r.decay)         # ringing feature value
+print(r.vhf_mf)        # spectral ratio feature value
+print(r.flat_noise)    # flat-region noise feature value
+print(r.resid_std)     # overall residual noise
+
+# From a PIL Image
+from PIL import Image
+img = Image.open("image.png")
+r = analyze(img)
+```
+
+### `Result` fields
+
+| Field | Type | Description |
+|---|---|---|
+| `verdict` | `str` | `"likely AI-generated/edited"` or `"likely clean"` |
+| `reasons` | `list[str]` | Fired signal names: `ringing`, `noisy-flats`, `synthetic-noise` |
+| `score` | `float` | Confidence score `[0, 1]` (0.75 per firing signal, capped at 1.0) |
+| `decay` | `float` | Ringing persistence: mid-distance / near-edge band energy |
+| `halo_vs_bg` | `float` | Mid-distance energy vs. image background |
+| `vhf_mf` | `float` | Spectral ratio: Nyquist ring / mid frequencies |
+| `resid_std` | `float` | Standard deviation of the noise residual |
+| `flat_noise` | `float` | RMS residual inside coarse-flat regions |
+
+### Visual proof from Python
+
+```python
+from minosse import analyze, evidence
+from PIL import Image
+
+img = Image.open("image.png")
+r = analyze(img)
+sheet = evidence.render(img, r)
+sheet.save("proof.png")
+```
+
+## Project structure
+
+```
+minosse/
+├── minosse/
+│   ├── __init__.py      # Public API: analyze, analyze_path, Result
+│   ├── __main__.py      # python -m minosse entry point
+│   ├── cli.py           # Argument parsing and CLI loop
+│   ├── detector.py      # Feature extraction + threshold logic
+│   └── evidence.py      # Visual proof sheet renderer
+├── results/             # Default --proof output directory
+├── requirements.txt     # numpy, pillow, scipy
+└── README.md
+```
+
+## How it works (briefly)
+
+1. **Preprocessing** — the image is converted to RGB and downscaled if
+   its longest edge exceeds 1600 px.
+2. **Feature extraction** (`detector._features()`) — three independent
+   signal-processing pipelines compute scalar features from the
+   grayscale luminance.
+3. **Thresholding** — each feature is compared against a tuned threshold;
+   if it exceeds the threshold the corresponding signal is flagged.
+4. **Verdict** — if any signal fires, the image is marked likely
+   AI-generated/edited; otherwise it's likely clean.
+
+For a deeper explanation of each signal, see [docs/signals.md](docs/signals.md).
+
+## Caveats
+
+The thresholds are calibrated on a small set of examples and should be
+re-validated as more AI samples are added. See [docs/tuning.md](docs/tuning.md)
+for instructions on re-tuning.
+
+## License
+
+MIT

minosse-0.1.0/docs/signals.md

@@ -0,0 +1,171 @@
+# Signal deep-dive
+
+Minosse uses three independent signal-processing pipelines to detect
+AI-generated or AI-edited images. Each targets a different class of
+artifact that current diffusion models and neural upsamplers leave
+behind.
+
+---
+
+## Ringing
+
+### What it catches
+
+Diffusion VAE decoders — particularly those based on convolutional
+architectures — produce oscillating ripple halos around high-contrast
+strokes such as text, UI borders, and sharp edges. This is a known
+side effect of the upsampling layers in the decoder, which act like
+imperfect deconvolution filters.
+
+### How it works
+
+1. **Edge detection** — a Sobel gradient magnitude is computed on the
+   grayscale image. Strong edges are identified by thresholding at the
+   97th percentile.
+
+2. **Band-pass energy** — a band-pass filter (difference of Gaussians
+   with σ = 0.8 and σ = 3.0) extracts oscillation energy in the
+   spatial frequency range that typical ringing occupies.
+
+3. **Radial profile** — a distance transform from the strong-edge mask
+   yields a map of "how far from the nearest edge". The band-pass
+   energy is median-aggregated into distance bins:
+
+   | Bin (px) | Interpretation |
+   |---|---|
+   | 3–6 | Near edge (includes legitimate edge overshoot) |
+   | 6–10 | Transition zone |
+   | 10–15 | **Halo zone** |
+   | 15–25 | **Halo zone** |
+   | 25–40 | **Halo zone** |
+   | 40–60 | Background |
+   | 60–120 | Background |
+
+4. **Feature: `decay`** — the ratio of median energy in the halo zone
+   (bins 10–25 px) to the near-edge bin (3–6 px). Real edges decay
+   quickly; ringing sustains energy at a distance.
+
+5. **Feature: `halo_vs_bg`** — halo-zone energy vs. background energy
+   (40–120 px). Helps distinguish ringing from legitimate texture.
+
+### Threshold
+
+`vhf_mf < 0.22 AND decay > 0.065`
+
+(Combined with a spectral check to avoid false positives on strongly
+textured natural images.)
+
+### Visual proof
+
+The ringing heatmap shows band-pass oscillation energy *only* in regions
+that are 8–40 px from a strong edge *and* locally flat at coarse scale
+(coarse gradient ≤ 60th percentile). This ensures that legitimate
+texture (fabric, foliage, carpet) does not light up.
+
+---
+
+## Noisy-flats
+
+### What it catches
+
+AI-generated images — especially those that apply a "film grain" effect
+for realism — carry noise in regions that should be perfectly flat:
+solid UI panels, plain backgrounds, or uniform colour swatches.
+
+Real screenshots have truly flat flats (the pixel values are constant).
+Real photos have flat regions that are smoothed by JPEG compression.
+AI noise is spatially structured and survives in flat areas.
+
+### How it works
+
+1. **Coarse-flat detection** — a Gaussian blur (σ = 4) removes fine
+   detail, then a Sobel gradient identifies regions of low variation.
+   The flattest 20% of the image (by coarse gradient) are selected.
+
+2. **Noise residual** — a 3×3 median filter estimates the clean image;
+   the residual is the difference between the original and the filtered
+   version.
+
+3. **Feature: `flat_noise`** — the RMS of the residual inside the
+   coarse-flat regions.
+
+### Threshold
+
+`flat_noise > 0.015`
+
+### Visual proof
+
+The noisy-flats heatmap shows the squared noise residual (blurred with
+a 9×9 uniform filter) inside the flat regions. The heat is scaled
+absolutely so that clean images (where `flat_noise` sits well below
+the threshold) render dark.
+
+---
+
+## Synthetic-noise
+
+### What it catches
+
+Real camera sensor noise has a characteristic spectral signature: it
+remains energetic right up to the Nyquist frequency (the highest
+spatial frequencies the sensor can resolve). Generated or upsampled
+noise — whether from a diffusion model's latent space or a neural
+upsampler — dies off before Nyquist, because the model never learned
+to produce true pixel-level randomness.
+
+### How it works
+
+1. **Center crop** — a square centre crop (up to 512×512) is taken to
+   avoid edge artefacts.
+
+2. **Noise residual** — a 3×3 median filter isolates the high-frequency
+   noise.
+
+3. **Windowing & FFT** — a Hann window is applied to reduce spectral
+   leakage, then the 2D power spectrum is computed.
+
+4. **Radial rings** — the spectrum is averaged over two annular regions:
+
+   | Ring | Radius | Interpretation |
+   |---|---|---|
+   | Mid frequencies (MF) | 0.25–0.50 of Nyquist | Typical image energy |
+   | Very high frequencies (VHF) | 0.95–1.20 of Nyquist | Near-Nyquist noise |
+
+5. **Feature: `vhf_mf`** — the ratio VHF / MF energy. Real sensor noise
+   keeps this ratio relatively high; synthetic noise shows a sharp drop.
+
+6. **Feature: `resid_std`** — the standard deviation of the noise
+   residual across the whole centre crop. Measures overall noise level.
+
+### Threshold
+
+`vhf_mf < 0.09 AND resid_std > 0.02 AND flat_noise > 0.001`
+
+The `flat_noise` condition prevents false positives on clean images that
+happen to have a cold spectrum (e.g. heavily compressed JPEGs).
+
+### Visual proof
+
+The synthetic-noise heatmap is simply the absolute noise residual
+(amplified by 12×). It looks like a noise texture — the evidence is
+that the texture exists at all in an image that also has a cold
+high-frequency spectrum.
+
+---
+
+## Why no ML model
+
+Minosse is deliberately **model-free** for several reasons:
+
+- **Interpretability** — every decision is traceable to a specific
+  physical feature. You can see *why* an image was flagged.
+- **No training data contamination** — no risk of overfitting to a
+  particular generator or dataset.
+- **No model drift** — the thresholds may need adjustment, but the
+  signal-processing pipeline is stable and deterministic.
+- **Speed** — a single image analyses in under a second on a CPU.
+- **Lightweight** — no GPU, no large model weights, no PyTorch/TensorFlow.
+
+The trade-off is that Minosse will not catch AI images that lack these
+specific artifacts. As generators improve, the signals may need to be
+augmented or re-tuned.

minosse-0.1.0/docs/tuning.md

@@ -0,0 +1,119 @@
+# Tuning guide
+
+Minosse's detection thresholds are hand-tuned on a small set of examples.
+As you add more AI-generated images you should re-validate — and possibly
+re-tune — the thresholds.
+
+## Thresholds (as of initial release)
+
+| Signal | Feature | Threshold | Direction |
+|---|---|---|---|
+| Ringing | `vhf_mf < 0.22` AND `decay > 0.065` | — | — |
+| Noisy-flats | `flat_noise > 0.015` | ↑ | Higher → fewer false positives, fewer detections |
+| Synthetic-noise | `vhf_mf < 0.09` AND `resid_std > 0.02` AND `flat_noise > 0.001` | — | — |
+
+## Re-tuning workflow
+
+### 1. Gather data
+
+Add real images to a `clean/` folder and AI-generated/edited images to
+a `dirty/` folder. Supported formats: JPEG, PNG.
+
+### 2. Extract features on the whole dataset
+
+```bash
+.venv/bin/python -c "
+from minosse.detector import _features
+from PIL import Image
+from pathlib import Path
+import csv, json
+
+rows = []
+for label, folder in [('clean', 'clean'), ('dirty', 'dirty')]:
+    for p in sorted(Path(folder).iterdir()):
+        if p.suffix.lower() in ('.jpg', '.jpeg', '.png'):
+            f = _features(Image.open(p))
+            rows.append({'file': p.name, 'label': label, **f})
+
+with open('features.csv', 'w') as fp:
+    w = csv.DictWriter(fp, fieldnames=rows[0].keys())
+    w.writeheader()
+    w.writerows(rows)
+print('features.csv written')
+"
+```
+
+### 3. Analyse the feature distribution
+
+Open `features.csv` in a spreadsheet or use the notebook below to
+plot histograms of each feature, coloured by label. Look for the
+threshold that separates clean from dirty with the widest margin.
+
+### 4. Grid search
+
+Run a grid search over the three thresholds and pick the combination
+that maximises `detections - false_positives` (or your preferred
+metric):
+
+```python
+import csv
+import itertools
+
+rows = list(csv.DictReader(open('features.csv')))
+for r in rows:
+    for k in ('decay', 'vhf_mf', 'resid_std', 'flat_noise', 'halo_vs_bg'):
+        r[k] = float(r[k])
+
+best = (0, None)
+for vhf_mf_r, decay_r, vhf_mf_s, resid_std_s, flat_noise_s in itertools.product(
+    [0.18, 0.20, 0.22, 0.24],
+    [0.055, 0.060, 0.065, 0.070],
+    [0.07, 0.08, 0.09, 0.10],
+    [0.015, 0.020, 0.025],
+    [0.001, 0.0005],
+):
+    tp = fp = 0
+    for r in rows:
+        ringing = r['vhf_mf'] < vhf_mf_r and r['decay'] > decay_r
+        nf = r['flat_noise'] > 0.015  # keep fixed or add to grid
+        sn = r['vhf_mf'] < vhf_mf_s and r['resid_std'] > resid_std_s and r['flat_noise'] > flat_noise_s
+        fired = ringing or nf or sn
+        if fired and r['label'] == 'dirty':
+            tp += 1
+        if fired and r['label'] == 'clean':
+            fp += 1
+    score = tp - fp
+    if score > best[0]:
+        best = (score, (vhf_mf_r, decay_r, vhf_mf_s, resid_std_s, flat_noise_s))
+
+print(f"Best score: {best[0]} at {best[1]}")
+```
+
+### 5. Update `detector.py`
+
+Edit the thresholds in `detector.analyze()` to match the grid search
+results.
+
+### 6. Update the results
+
+Update the detection results in `README.md` with the new counts.
+
+## Adding a new signal
+
+If you identify a new artifact class:
+
+1. Add a new feature computation in `detector._features()`.
+2. Add a threshold check in `detector.analyze()`.
+3. Add a heatmap entry in `evidence._maps()`.
+4. Add the signal name to the `evidence.render()` label mapping.
+5. Document it in `docs/signals.md`.
+
+## Testing changes
+
+```bash
+# Run on all clean images — should report 0
+.venv/bin/python -m minosse clean/*.jpg clean/*.png
+
+# Run on all dirty images — should report all
+.venv/bin/python -m minosse dirty/*
+```

minosse-0.1.0/minosse/__init__.py

@@ -0,0 +1 @@
+from .detector import analyze, analyze_path, Result

minosse-0.1.0/minosse/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

minosse-0.1.0/minosse/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

minosse-0.1.0/minosse/cli.py

@@ -0,0 +1,49 @@
+"""Command line entry point.
+
+usage: python -m minosse [--proof [DIR]] <image> [image ...]
+
+--proof renders a side-by-side evidence sheet per image (original plus
+red heatmap panels for each fired signal) as <name>_proof.png, saved in
+DIR if given, else next to the input image.
+"""
+
+import os
+import sys
+
+from PIL import Image
+
+from .detector import analyze
+from .evidence import render
+
+
+def main(argv=None):
+    args = list(argv if argv is not None else sys.argv[1:])
+    proof = False
+    proof_dir = None
+    if "--proof" in args:
+        i = args.index("--proof")
+        args.pop(i)
+        if i < len(args) and os.path.isdir(args[i]):
+            proof_dir = args.pop(i)
+        proof = True
+    if not args:
+        print(__doc__.strip())
+        return 2
+    for path in args:
+        img = Image.open(path)
+        r = analyze(img)
+        print(f"{path}")
+        print(f"  signals : {', '.join(r.reasons) if r.reasons else 'none'}")
+        print(f"  decay={r.decay:.4f} vhf_mf={r.vhf_mf:.3f} "
+              f"resid_std={r.resid_std:.4f} flat_noise={r.flat_noise:.4f}")
+        print(f"  verdict : {r.verdict}")
+        if proof:
+            base = os.path.splitext(os.path.basename(path))[0] + "_proof.png"
+            out = os.path.join(proof_dir or os.path.dirname(path) or ".", base)
+            render(img, r).save(out)
+            print(f"  proof   : {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

minosse-0.1.0/minosse/detector.py

@@ -0,0 +1,110 @@
+"""Minosse — detect AI-generated / AI-edited images.
+
+Three complementary signals, each targeting a different artifact class:
+
+ringing
+    Diffusion VAE decoders leave oscillating ripple halos around
+    high-contrast strokes (text, UI borders). Measured as a radial
+    profile of band-passed energy vs. distance from strong edges:
+    real edges decay fast, ringing persists 10-40 px out.
+
+noisy-flats
+    AI images (and AI "film grain") carry noise in regions that should
+    be perfectly flat — solid UI panels, plain backgrounds. Real
+    screenshots have truly flat flats, and JPEG smooths photo flats.
+
+synthetic-noise
+    Generated/upsampled noise dies out before the Nyquist frequency,
+    while real sensor noise stays hot at the highest frequencies. An
+    image with strong overall residual noise but a cold top ring of the
+    spectrum — and noise present even in flat regions — is synthetic.
+
+Thresholds were tuned on data/clean (65 real photos + screenshots) and
+data/dirty (5 AI-generated/edited): 5/5 detected, 0/65 false positives.
+"""
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from PIL import Image
+from scipy import ndimage
+
+_DIST_BINS = [(3, 6), (6, 10), (10, 15), (15, 25), (25, 40), (40, 60), (60, 120)]
+
+
+@dataclass
+class Result:
+    decay: float          # halo persistence: mid-distance / near-edge energy
+    halo_vs_bg: float     # mid-distance energy vs image's own background
+    vhf_mf: float         # spectral energy at Nyquist ring vs mid frequencies
+    resid_std: float      # overall noise-residual strength
+    flat_noise: float     # RMS residual inside coarse-flat regions
+    reasons: list = field(default_factory=list)
+    score: float = 0.0
+    verdict: str = ""
+
+
+def _features(img: Image.Image) -> dict:
+    img = img.convert("RGB")
+    if max(img.size) > 1600:
+        s = 1600 / max(img.size)
+        img = img.resize((int(img.width * s), int(img.height * s)), Image.LANCZOS)
+    a = np.asarray(img, dtype=np.float64) / 255.0
+    g = a.mean(2)
+
+    # --- ringing: band energy vs distance from strong edges
+    grad = np.hypot(ndimage.sobel(g, axis=1), ndimage.sobel(g, axis=0))
+    edge = grad > np.quantile(grad, 0.97)
+    band = ndimage.gaussian_filter(g, 0.8) - ndimage.gaussian_filter(g, 3.0)
+    energy = ndimage.uniform_filter(band * band, size=5)
+    dist = ndimage.distance_transform_edt(~edge)
+    prof = []
+    for d0, d1 in _DIST_BINS:
+        m = (dist >= d0) & (dist < d1)
+        prof.append(float(np.median(energy[m])) if m.any() else 0.0)
+    p = np.array(prof) + 1e-12
+    decay = float(np.median(p[2:5]) / p[0])
+    halo_vs_bg = float(np.median(p[2:5]) / np.median(p[5:7]))
+
+    # --- spectral shape of the noise residual (center crop, windowed FFT)
+    h, w = g.shape
+    s2 = min(512, h, w)
+    y0, x0 = (h - s2) // 2, (w - s2) // 2
+    gc = g[y0:y0 + s2, x0:x0 + s2]
+    res_c = gc - ndimage.median_filter(gc, 3)
+    win = np.hanning(s2)
+    F = np.abs(np.fft.fftshift(np.fft.fft2(res_c * win[:, None] * win[None, :]))) ** 2
+    yy, xx = np.indices(F.shape)
+    r = np.hypot(yy - s2 / 2, xx - s2 / 2) / (s2 / 2)
+    ring = lambda a_, b_: F[(r >= a_) & (r < b_)].mean()
+    vhf_mf = float(ring(0.95, 1.2) / (ring(0.25, 0.5) + 1e-20))
+    resid_std = float(np.std(res_c))
+
+    # --- noise inside coarse-flat regions
+    coarse = ndimage.gaussian_filter(g, 4)
+    cgrad = np.hypot(ndimage.sobel(coarse, axis=1), ndimage.sobel(coarse, axis=0))
+    flat = cgrad <= np.quantile(cgrad, 0.20)
+    res = g - ndimage.median_filter(g, 3)
+    flat_noise = float(np.sqrt(np.mean(res[flat] ** 2)))
+
+    return dict(decay=decay, halo_vs_bg=halo_vs_bg, vhf_mf=vhf_mf,
+                resid_std=resid_std, flat_noise=flat_noise)
+
+
+def analyze(img: Image.Image) -> Result:
+    f = _features(img)
+    reasons = []
+    if f["vhf_mf"] < 0.22 and f["decay"] > 0.065:
+        reasons.append("ringing")
+    if f["flat_noise"] > 0.015:
+        reasons.append("noisy-flats")
+    if f["vhf_mf"] < 0.09 and f["resid_std"] > 0.02 and f["flat_noise"] > 0.001:
+        reasons.append("synthetic-noise")
+
+    score = min(1.0, 0.75 * len(reasons)) if reasons else 0.0
+    verdict = "likely AI-generated/edited" if reasons else "likely clean"
+    return Result(**f, reasons=reasons, score=score, verdict=verdict)
+
+
+def analyze_path(path: str) -> Result:
+    return analyze(Image.open(path))

minosse-0.1.0/minosse/evidence.py

@@ -0,0 +1,98 @@
+"""Render visual proof sheets: original image next to panels that
+highlight, in red, the spatial evidence behind each fired signal.
+
+- ringing        : band-passed oscillation energy in the halo zone
+                   (3-40 px from strong edges, off-stroke)
+- noisy-flats    : noise residual energy inside coarse-flat regions
+- synthetic-noise: amplified full-frame noise residual (its spatial
+                   texture is the evidence; spectrum stats in caption)
+"""
+
+import numpy as np
+from PIL import Image, ImageDraw
+from scipy import ndimage
+
+from .detector import Result, _features  # noqa: F401  (shared pipeline)
+
+_PANEL_W = 640
+
+
+def _prep(img: Image.Image):
+    img = img.convert("RGB")
+    if max(img.size) > 1600:
+        s = 1600 / max(img.size)
+        img = img.resize((int(img.width * s), int(img.height * s)), Image.LANCZOS)
+    g = np.asarray(img, dtype=np.float64) / 255.0
+    return img, g.mean(2)
+
+
+def _heat_overlay(base: Image.Image, heat: np.ndarray, gain: float = 1.0) -> Image.Image:
+    """Dim grayscale base with the heat map burned in as red."""
+    h = np.clip(heat * gain, 0, 1)
+    gray = np.asarray(base.convert("L"), dtype=np.float64) / 255.0 * 0.35
+    rgb = np.stack([gray + h * 0.65, gray + h * 0.10, gray], axis=-1)
+    return Image.fromarray((np.clip(rgb, 0, 1) * 255).astype(np.uint8))
+
+
+def _abs_norm(x: np.ndarray, full_scale: float) -> np.ndarray:
+    """Absolute scaling: `full_scale` maps to 1.0. Calibrated to the
+    detector thresholds so clean images render dark instead of being
+    stretched to look hot by per-image normalization."""
+    return np.clip(np.sqrt(np.clip(x, 0, None)) / full_scale, 0, 1)
+
+
+def _maps(g: np.ndarray) -> dict:
+    grad = np.hypot(ndimage.sobel(g, axis=1), ndimage.sobel(g, axis=0))
+    edge = grad > np.quantile(grad, 0.97)
+    band = ndimage.gaussian_filter(g, 0.8) - ndimage.gaussian_filter(g, 3.0)
+    energy = ndimage.uniform_filter(band * band, size=5)
+    dist = ndimage.distance_transform_edt(~edge)
+
+    coarse = ndimage.gaussian_filter(g, 4)
+    cgrad = np.hypot(ndimage.sobel(coarse, axis=1), ndimage.sobel(coarse, axis=0))
+    flat = cgrad <= np.quantile(cgrad, 0.20)
+    res = g - ndimage.median_filter(g, 3)
+
+    # Ringing evidence = oscillation where the image should be smooth:
+    # 8-40 px from a strong edge (past the 1-2 px overshoot every real
+    # edge has) AND locally flat at coarse scale, so legitimate texture
+    # (fabric, foliage, carpet) is excluded.
+    smooth = cgrad <= np.quantile(cgrad, 0.60)
+    halo = (dist >= 8) & (dist < 40) & smooth
+    ringing = np.where(halo, energy, 0.0)
+    flat_noise = np.where(flat, ndimage.uniform_filter(res * res, size=9), 0.0)
+
+    # full-scale values sit a bit above the detector's firing thresholds
+    return {
+        "ringing": _abs_norm(ringing, 0.007),
+        "noisy-flats": _abs_norm(flat_noise, 0.03),
+        "synthetic-noise": np.clip(np.abs(res) * 12, 0, 1),
+    }
+
+
+def render(img: Image.Image, result: Result) -> Image.Image:
+    """Build a proof sheet: original + one evidence panel per fired
+    signal (all three panels if nothing fired, for comparison)."""
+    base, g = _prep(img)
+    maps = _maps(g)
+    signals = result.reasons if result.reasons else list(maps)
+
+    scale = _PANEL_W / base.width
+    size = (_PANEL_W, int(base.height * scale))
+    panels = [("original", base.resize(size, Image.LANCZOS))]
+    for name in signals:
+        overlay = _heat_overlay(base, maps[name])
+        panels.append((name, overlay.resize(size, Image.LANCZOS)))
+
+    cap_h = 26
+    sheet = Image.new("RGB", (_PANEL_W * len(panels), size[1] + cap_h), (12, 12, 12))
+    draw = ImageDraw.Draw(sheet)
+    for i, (name, panel) in enumerate(panels):
+        sheet.paste(panel, (i * _PANEL_W, cap_h))
+        label = name if name == "original" else (
+            f"{name} {'[FIRED]' if name in result.reasons else '(not fired)'}")
+        draw.text((i * _PANEL_W + 8, 6), label,
+                  fill=(255, 80, 80) if name in result.reasons else (200, 200, 200))
+    draw.text((sheet.width - 320, 6), f"verdict: {result.verdict}",
+              fill=(255, 80, 80) if result.reasons else (120, 220, 120))
+    return sheet

minosse-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling>=1.18", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "minosse"
+dynamic = ["version"]
+description = "Detects AI-generated or AI-edited images using signal-processing artifact analysis — no ML model."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "cesp99" }]
+keywords = ["ai-detection", "image-forensics", "diffusion", "signal-processing"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Image Processing",
+  "Topic :: Security",
+]
+dependencies = [
+  "numpy",
+  "pillow",
+  "scipy",
+]
+
+[project.urls]
+Homepage = "https://github.com/cesp99/Minosse"
+Issues = "https://github.com/cesp99/Minosse/issues"
+
+[project.scripts]
+minosse = "minosse.cli:main"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "minosse/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["minosse"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "minosse",
+  "README.md",
+  "requirements.txt",
+  "docs",
+  "LICENSE",
+]

minosse-0.1.0/requirements.txt

@@ -0,0 +1,3 @@
+numpy
+pillow
+scipy