imgtrail 0.1.0__tar.gz

imgtrail-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+
+# imgtrail state and output
+imgtrail-data/
+*.html
+findings.json
+.coverage
+coverage.xml
+htmlcov/

imgtrail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Endika Iglesias
+
+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.

imgtrail-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: imgtrail
+Version: 0.1.0
+Summary: Find out where else on the web your own photos show up
+Project-URL: Homepage, https://github.com/Endika/imgtrail
+Project-URL: Repository, https://github.com/Endika/imgtrail
+Project-URL: Issues, https://github.com/Endika/imgtrail/issues
+Project-URL: Changelog, https://github.com/Endika/imgtrail/blob/main/CHANGELOG.md
+Author-email: Endika Iglesias <endika2@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: instagram,osint,phash,privacy,reverse-image-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: imagehash>=4.3
+Requires-Dist: pillow>=10
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# imgtrail
+
+Find out where else on the web your own photos show up.
+
+Point it at your Instagram data export. It hashes every photo, collapses the near-duplicates
+so you never pay to search the same picture twice, runs each unique one through reverse image
+search, and then **downloads every candidate and compares it against your original** before
+putting it in the report. What you get back is a list you can trust, not a pile of URLs.
+
+```
+imgtrail scan ~/Downloads/instagram-export.zip --dry-run
+imgtrail scan ~/Downloads/instagram-export.zip
+imgtrail report --open
+```
+
+## What it finds, and what it doesn't
+
+It searches Google's index, so it finds your photos on **blogs, news sites, Pinterest, Tumblr,
+forums, scraper mirrors and shops that lifted your pictures**.
+
+It will **not** find a repost on another Instagram account. Instagram blocks crawling of post
+images, so they aren't in anyone's index — the only way such a repost surfaces here is
+indirectly, via one of the many "Instagram viewer" mirror sites that *are* indexed. Telegram,
+WhatsApp, TikTok, Facebook and private accounts are invisible to it too. If your question is
+"is someone reposting me inside Instagram", this is the wrong tool and there isn't a good one.
+
+## Install
+
+```
+pip install imgtrail
+```
+
+## Getting your photos
+
+Instagram → Settings → Accounts Centre → Your information and permissions → **Download your
+information**. Ask for JSON, high quality. You'll get a ZIP; hand it straight to `imgtrail scan`.
+No scraping, nothing against the terms of service, no rate limits.
+
+A plain folder of images works just as well.
+
+## Getting an API key
+
+imgtrail uses Google Cloud Vision's `WEB_DETECTION`. Create a project at
+[console.cloud.google.com](https://console.cloud.google.com), enable the **Cloud Vision API**,
+then Credentials → Create credentials → API key.
+
+```
+export IMGTRAIL_API_KEY=AIza...
+```
+
+**The first 1,000 images each month are free**, then $3.50 per 1,000. A typical profile costs
+nothing. Run `--dry-run` first and it will tell you exactly how many searches it would make and
+what they would cost before spending anything.
+
+## How the verification works
+
+Reverse image search returns a lot of near-misses. For every candidate, imgtrail downloads the
+image and compares perceptual hashes against your original:
+
+| Hamming distance | Verdict | Meaning |
+|---|---|---|
+| ≤ 8 | `confirmed` | The same image, possibly recompressed |
+| ≤ 16 | `likely` | Cropped, filtered or heavily edited |
+| > 16 | `rejected` | Not your photo |
+
+Only `confirmed` and `likely` reach the report. `visuallySimilarImages` is dropped entirely —
+it means "semantically alike", not "this is your photo", and it drowns the report in noise.
+
+## Commands
+
+```
+imgtrail scan SOURCE          index, dedupe, search and verify — resumable
+  --dry-run                   count the searches and their cost, call nothing
+  --limit N                   search at most N unique photos
+  --threshold N               pHash distance for "same photo" (default 6)
+  --ignore-domain DOMAIN      exclude a domain from results (repeatable)
+  --no-verify                 skip the download-and-compare pass
+imgtrail report --open        build the HTML report and open it
+imgtrail status               what's in the database so far
+```
+
+State lives in `./imgtrail-data`. Everything is idempotent: re-running `scan` searches only
+what it hasn't searched before, so an interrupted run costs nothing to resume.
+
+## Privacy
+
+Your photos are sent to Google Cloud Vision, and nowhere else. Nothing is uploaded to any
+server of mine — there isn't one. The database, the extracted export and the report all stay
+on your machine.
+
+## Architecture
+
+Ports and adapters, sized to the problem: the rules sit in the middle and know nothing
+about Google, SQLite or HTTP, so swapping a search backend touches exactly one file.
+
+```
+domain.py     fingerprints, grouping, verdicts, what counts as "your own platform"
+              — pure; no I/O, no SQL, no network
+ports.py      the boundaries: PhotoSource, ImageLoader, SearchEngine, ImageFetcher,
+              PhotoRepository, MatchRepository, ReportWriter
+services.py   the use cases: index, plan, search, verify, report
+adapters/     the details: sqlite_repository, vision, http_fetcher, local_files, html_report
+cli.py        the composition root — the one module that knows every layer
+```
+
+Adding TinEye or Yandex means writing one `SearchEngine` and wiring it in `cli.py`. Nothing
+in `domain.py` or `services.py` changes.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest             # 85 tests, no network, no mocks
+uv run ruff check .
+uv run ruff format .
+uv run mypy               # strict, and it passes on the tests too
+```
+
+The test doubles are real implementations, not mocks: an in-memory `DictPhotoSource`, a
+`FakeSearchEngine` that records what it was asked, and — where the wire itself is what needs
+testing — a real local HTTP server speaking Vision's JSON.
+
+## Licence
+
+MIT

imgtrail-0.1.0/README.md

@@ -0,0 +1,125 @@
+# imgtrail
+
+Find out where else on the web your own photos show up.
+
+Point it at your Instagram data export. It hashes every photo, collapses the near-duplicates
+so you never pay to search the same picture twice, runs each unique one through reverse image
+search, and then **downloads every candidate and compares it against your original** before
+putting it in the report. What you get back is a list you can trust, not a pile of URLs.
+
+```
+imgtrail scan ~/Downloads/instagram-export.zip --dry-run
+imgtrail scan ~/Downloads/instagram-export.zip
+imgtrail report --open
+```
+
+## What it finds, and what it doesn't
+
+It searches Google's index, so it finds your photos on **blogs, news sites, Pinterest, Tumblr,
+forums, scraper mirrors and shops that lifted your pictures**.
+
+It will **not** find a repost on another Instagram account. Instagram blocks crawling of post
+images, so they aren't in anyone's index — the only way such a repost surfaces here is
+indirectly, via one of the many "Instagram viewer" mirror sites that *are* indexed. Telegram,
+WhatsApp, TikTok, Facebook and private accounts are invisible to it too. If your question is
+"is someone reposting me inside Instagram", this is the wrong tool and there isn't a good one.
+
+## Install
+
+```
+pip install imgtrail
+```
+
+## Getting your photos
+
+Instagram → Settings → Accounts Centre → Your information and permissions → **Download your
+information**. Ask for JSON, high quality. You'll get a ZIP; hand it straight to `imgtrail scan`.
+No scraping, nothing against the terms of service, no rate limits.
+
+A plain folder of images works just as well.
+
+## Getting an API key
+
+imgtrail uses Google Cloud Vision's `WEB_DETECTION`. Create a project at
+[console.cloud.google.com](https://console.cloud.google.com), enable the **Cloud Vision API**,
+then Credentials → Create credentials → API key.
+
+```
+export IMGTRAIL_API_KEY=AIza...
+```
+
+**The first 1,000 images each month are free**, then $3.50 per 1,000. A typical profile costs
+nothing. Run `--dry-run` first and it will tell you exactly how many searches it would make and
+what they would cost before spending anything.
+
+## How the verification works
+
+Reverse image search returns a lot of near-misses. For every candidate, imgtrail downloads the
+image and compares perceptual hashes against your original:
+
+| Hamming distance | Verdict | Meaning |
+|---|---|---|
+| ≤ 8 | `confirmed` | The same image, possibly recompressed |
+| ≤ 16 | `likely` | Cropped, filtered or heavily edited |
+| > 16 | `rejected` | Not your photo |
+
+Only `confirmed` and `likely` reach the report. `visuallySimilarImages` is dropped entirely —
+it means "semantically alike", not "this is your photo", and it drowns the report in noise.
+
+## Commands
+
+```
+imgtrail scan SOURCE          index, dedupe, search and verify — resumable
+  --dry-run                   count the searches and their cost, call nothing
+  --limit N                   search at most N unique photos
+  --threshold N               pHash distance for "same photo" (default 6)
+  --ignore-domain DOMAIN      exclude a domain from results (repeatable)
+  --no-verify                 skip the download-and-compare pass
+imgtrail report --open        build the HTML report and open it
+imgtrail status               what's in the database so far
+```
+
+State lives in `./imgtrail-data`. Everything is idempotent: re-running `scan` searches only
+what it hasn't searched before, so an interrupted run costs nothing to resume.
+
+## Privacy
+
+Your photos are sent to Google Cloud Vision, and nowhere else. Nothing is uploaded to any
+server of mine — there isn't one. The database, the extracted export and the report all stay
+on your machine.
+
+## Architecture
+
+Ports and adapters, sized to the problem: the rules sit in the middle and know nothing
+about Google, SQLite or HTTP, so swapping a search backend touches exactly one file.
+
+```
+domain.py     fingerprints, grouping, verdicts, what counts as "your own platform"
+              — pure; no I/O, no SQL, no network
+ports.py      the boundaries: PhotoSource, ImageLoader, SearchEngine, ImageFetcher,
+              PhotoRepository, MatchRepository, ReportWriter
+services.py   the use cases: index, plan, search, verify, report
+adapters/     the details: sqlite_repository, vision, http_fetcher, local_files, html_report
+cli.py        the composition root — the one module that knows every layer
+```
+
+Adding TinEye or Yandex means writing one `SearchEngine` and wiring it in `cli.py`. Nothing
+in `domain.py` or `services.py` changes.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest             # 85 tests, no network, no mocks
+uv run ruff check .
+uv run ruff format .
+uv run mypy               # strict, and it passes on the tests too
+```
+
+The test doubles are real implementations, not mocks: an in-memory `DictPhotoSource`, a
+`FakeSearchEngine` that records what it was asked, and — where the wire itself is what needs
+testing — a real local HTTP server speaking Vision's JSON.
+
+## Licence
+
+MIT

imgtrail-0.1.0/imgtrail/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

imgtrail-0.1.0/imgtrail/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

imgtrail-0.1.0/imgtrail/adapters/__init__.py

@@ -0,0 +1 @@
+"""Concrete implementations of the ports. Nothing here is imported by the domain."""

imgtrail-0.1.0/imgtrail/adapters/html_report.py

@@ -0,0 +1,158 @@
+"""Renders a report as a self-contained HTML page, or as JSON."""
+
+from __future__ import annotations
+
+import base64
+import html
+import io
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from PIL import Image
+
+from imgtrail.domain import Report, Verdict
+from imgtrail.ports import ImageLoader
+
+THUMBNAIL_PX = 160
+BADGE_CLASS = {Verdict.CONFIRMED: "ok", Verdict.LIKELY: "warn"}
+
+CSS = """
+:root { --bg:#fbfbfa; --fg:#1a1a19; --muted:#6b6b68; --card:#fff; --line:#e5e4e0;
+        --ok:#1a7f4b; --ok-bg:#e6f4ec; --warn:#8a5a00; --warn-bg:#fdf3e0; --accent:#c2410c; }
+@media (prefers-color-scheme: dark) {
+  :root { --bg:#141413; --fg:#eeeeec; --muted:#9a9a96; --card:#1e1e1c; --line:#33332f;
+          --ok:#6ee7a8; --ok-bg:#12291d; --warn:#f0c674; --warn-bg:#2b2110; --accent:#fb923c; }
+}
+* { box-sizing:border-box; }
+body { margin:0; padding:2.5rem 1.5rem; background:var(--bg); color:var(--fg);
+       font:15px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+.wrap { max-width:900px; margin:0 auto; }
+h1 { font-size:1.6rem; margin:0 0 .3rem; letter-spacing:-.02em; }
+.sub { color:var(--muted); margin:0 0 2rem; }
+.stats { display:flex; flex-wrap:wrap; gap:2rem; padding:1rem 1.25rem; margin-bottom:2rem;
+         background:var(--card); border:1px solid var(--line); border-radius:10px; }
+.stat b { display:block; font-size:1.5rem; letter-spacing:-.02em; }
+.stat span { color:var(--muted); font-size:.8rem; text-transform:uppercase; letter-spacing:.06em; }
+.card { display:flex; gap:1.25rem; padding:1.25rem; margin-bottom:1rem; background:var(--card);
+        border:1px solid var(--line); border-radius:10px; }
+.card img { width:120px; height:120px; object-fit:cover; border-radius:8px; flex:none;
+            background:var(--line); }
+.card h2 { font-size:.95rem; margin:0 0 .1rem; }
+.card .meta { color:var(--muted); font-size:.8rem; margin:0 0 .8rem; }
+.card > div { min-width:0; flex:1; }
+ul { list-style:none; margin:0; padding:0; }
+li { padding:.45rem 0; border-top:1px solid var(--line); font-size:.9rem;
+     display:flex; gap:.6rem; align-items:baseline; flex-wrap:wrap; }
+a { color:var(--accent); text-decoration:none; word-break:break-all; }
+a:hover { text-decoration:underline; }
+.badge { font-size:.7rem; padding:.12rem .45rem; border-radius:99px; flex:none;
+         text-transform:uppercase; letter-spacing:.05em; font-weight:600; }
+.badge.ok { color:var(--ok); background:var(--ok-bg); }
+.badge.warn { color:var(--warn); background:var(--warn-bg); }
+.dom { font-weight:600; }
+.empty { padding:3rem; text-align:center; color:var(--muted); background:var(--card);
+         border:1px solid var(--line); border-radius:10px; }
+"""
+
+
+class HtmlReportWriter:
+    def __init__(self, loader: ImageLoader, thumbnail_px: int = THUMBNAIL_PX) -> None:
+        self._loader = loader
+        self._px = thumbnail_px
+
+    def write(self, report: Report, destination: Path) -> None:
+        destination.write_text(self._render(report), encoding="utf-8")
+
+    def _thumbnail(self, reference: str) -> str:
+        try:
+            with Image.open(io.BytesIO(self._loader.load(reference))) as opened:
+                converted = opened.convert("RGB")
+                converted.thumbnail((self._px, self._px))
+                buffer = io.BytesIO()
+                converted.save(buffer, format="PNG", optimize=True)
+        except (OSError, ValueError):
+            return ""
+        return "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode()
+
+    def _render(self, report: Report) -> str:
+        escape = html.escape
+        cards = []
+        for finding in report.findings:
+            items = []
+            for match in finding.matches:
+                distance = (
+                    f'<span class="meta">&#916;{match.distance}</span>'
+                    if match.distance is not None
+                    else ""
+                )
+                label = escape((match.title or match.target)[:110])
+                items.append(
+                    f'<li><span class="badge {BADGE_CLASS[match.verdict]}">'
+                    f"{escape(match.verdict.value)}</span>"
+                    f'<span class="dom">{escape(match.domain or "")}</span>'
+                    f'<a href="{escape(match.target)}" target="_blank" rel="noreferrer">'
+                    f"{label}</a>{distance}</li>"
+                )
+            copies = (
+                f" &middot; {finding.copies} copies in your profile" if finding.copies > 1 else ""
+            )
+            cards.append(
+                f'<div class="card"><img src="{self._thumbnail(finding.photo.path)}" alt="">'
+                f"<div><h2>{escape(Path(finding.photo.path).name)}</h2>"
+                f'<p class="meta">{len(finding.matches)} matches{copies}</p>'
+                f"<ul>{''.join(items)}</ul></div></div>"
+            )
+
+        body = "".join(cards) or (
+            '<div class="empty">None of your photos turned up on another site.</div>'
+        )
+
+        summary, tally = report.summary, report.summary.tally
+        tiles = [
+            ("Photos", summary.photos),
+            ("Unique", summary.unique),
+            ("Searched", summary.searched),
+            ("Confirmed", tally.get(Verdict.CONFIRMED, 0)),
+            ("Likely", tally.get(Verdict.LIKELY, 0)),
+            ("Discarded", tally.get(Verdict.REJECTED, 0) + tally.get(Verdict.UNREACHABLE, 0)),
+        ]
+        stats = "".join(f'<div class="stat"><b>{v}</b><span>{k}</span></div>' for k, v in tiles)
+
+        return (
+            '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+            '<meta name="viewport" content="width=device-width,initial-scale=1">'
+            f'<title>imgtrail</title><style>{CSS}</style></head><body><div class="wrap">'
+            "<h1>Where did your photos end up?</h1>"
+            '<p class="sub">Verified matches outside Instagram.</p>'
+            f'<div class="stats">{stats}</div>{body}</div></body></html>'
+        )
+
+
+class JsonReportWriter:
+    def write(self, report: Report, destination: Path) -> None:
+        payload = {
+            "summary": {
+                "photos": report.summary.photos,
+                "unique": report.summary.unique,
+                "searched": report.summary.searched,
+                "tally": {v.value: n for v, n in report.summary.tally.items()},
+            },
+            "findings": [
+                {
+                    "photo": finding.photo.path,
+                    "copies": finding.copies,
+                    "matches": [
+                        {
+                            **asdict(m),
+                            "kind": m.kind.value,
+                            "verdict": m.verdict.value,
+                            "domain": m.domain,
+                        }
+                        for m in finding.matches
+                    ],
+                }
+                for finding in report.findings
+            ],
+        }
+        destination.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")

imgtrail-0.1.0/imgtrail/adapters/http_fetcher.py

@@ -0,0 +1,37 @@
+"""Downloads candidate images so they can be checked against the original."""
+
+from __future__ import annotations
+
+import httpx
+
+MAX_BYTES = 25 * 1024 * 1024
+USER_AGENT = "Mozilla/5.0 (compatible; imgtrail/0.1; +reverse-image-verification)"
+
+
+class HttpImageFetcher:
+    def __init__(self, timeout: float = 20.0, client: httpx.Client | None = None) -> None:
+        self._client = client or httpx.Client(
+            timeout=timeout, headers={"User-Agent": USER_AGENT}, follow_redirects=True
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpImageFetcher:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def fetch(self, url: str) -> bytes | None:
+        """None whenever the URL does not yield an image we can compare."""
+        try:
+            response = self._client.get(url)
+            response.raise_for_status()
+        except httpx.HTTPError:
+            return None
+        if not response.headers.get("content-type", "").startswith("image/"):
+            return None
+        if len(response.content) > MAX_BYTES:
+            return None
+        return response.content

imgtrail-0.1.0/imgtrail/adapters/local_files.py

@@ -0,0 +1,45 @@
+"""Reads photos from an Instagram export archive or any folder of images."""
+
+from __future__ import annotations
+
+import zipfile
+from collections.abc import Iterator
+from pathlib import Path
+
+EXTENSIONS = frozenset({".jpg", ".jpeg", ".png", ".webp", ".heic", ".bmp"})
+
+SKIP_DIRECTORIES = frozenset({"profile", "other", "messages", "stories_activity", "avatars"})
+"""The export ships avatars and other people's content next to your own posts."""
+
+
+class FileImageLoader:
+    """Reads a photo back from disk. A reference is an absolute path."""
+
+    def load(self, reference: str) -> bytes:
+        return Path(reference).read_bytes()
+
+
+class LocalPhotoSource(FileImageLoader):
+    """Implements both PhotoSource and ImageLoader; a reference is an absolute path."""
+
+    def __init__(self, source: Path, workspace: Path) -> None:
+        self._source = source
+        self._workspace = workspace
+
+    def photos(self) -> Iterator[str]:
+        root = self._unpacked()
+        for path in sorted(root.rglob("*")):
+            if path.suffix.lower() not in EXTENSIONS:
+                continue
+            if SKIP_DIRECTORIES & {part.lower() for part in path.parts}:
+                continue
+            yield str(path.resolve())
+
+    def _unpacked(self) -> Path:
+        if self._source.is_file() and self._source.suffix.lower() == ".zip":
+            target = self._workspace / "extracted"
+            if not target.exists():
+                with zipfile.ZipFile(self._source) as archive:
+                    archive.extractall(target)
+            return target
+        return self._source