lensgrep 0.1.0__py3-none-any.whl

lensgrep/__init__.py

@@ -0,0 +1,3 @@
+"""lensgrep — grep for your photo library."""
+
+__version__ = "0.1.0"

lensgrep/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m lensgrep`."""
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

lensgrep/cli.py

@@ -0,0 +1,344 @@
+"""lensgrep CLI - Typer commands."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .core.cluster import cluster_all
+from .core.db import Database
+from .core.embedder import Embedder
+from .core.paths import data_dir, db_path
+from .core.scanner import Scanner
+
+# Force UTF-8 stdout/stderr — Windows legacy code pages (cp1250 etc.) choke on
+# common output chars otherwise. No-op on POSIX.
+for _stream in (sys.stdout, sys.stderr):
+    reconfigure = getattr(_stream, "reconfigure", None)
+    if reconfigure is not None:
+        with contextlib.suppress(OSError, ValueError):
+            reconfigure(encoding="utf-8", errors="replace")
+
+app = typer.Typer(
+    name="lensgrep",
+    help="Grep for your photo library. Find any person across thousands of photos, locally.",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = Console()
+
+
+def _version_cb(value: bool) -> None:
+    if value:
+        console.print(f"lensgrep {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version", callback=_version_cb, is_eager=True, help="Print version and exit."
+        ),
+    ] = None,
+) -> None:
+    pass
+
+
+@app.command()
+def scan(
+    paths: Annotated[list[Path], typer.Argument(help="Folders or files to scan (recursive).")],
+    incremental: Annotated[
+        bool,
+        typer.Option("--incremental/--full", help="Skip already-scanned files based on mtime."),
+    ] = True,
+    gpu: Annotated[bool, typer.Option("--gpu/--cpu", help="Use CUDA if available.")] = True,
+    max_side: Annotated[
+        int, typer.Option(help="Downscale images longer than this for detection.")
+    ] = 2400,
+    recluster: Annotated[
+        bool, typer.Option("--recluster/--no-recluster", help="Re-run DBSCAN after scan.")
+    ] = True,
+) -> None:
+    """Scan folders for faces and store embeddings in the local database."""
+    db = Database()
+    embedder = Embedder(gpu=gpu)
+    scanner = Scanner(db, embedder, max_side=max_side)
+
+    console.print(f"[cyan]>>[/] scanning {len(paths)} root(s) -> {db_path()}")
+    stats = scanner.scan(paths, incremental=incremental)
+    console.print(
+        f"[green]done[/]  scanned={stats.scanned}  skipped={stats.skipped}  "
+        f"new={stats.new_or_changed}  faces+={stats.faces_added}  fail={stats.failures}"
+    )
+
+    if recluster and stats.faces_added > 0:
+        console.print("[cyan]>>[/] re-clustering...")
+        counts = cluster_all(db)
+        n_clusters = sum(1 for k in counts if k >= 0)
+        n_noise = counts.get(-1, 0)
+        console.print(f"[green]clustered[/] {n_clusters} groups, {n_noise} unassigned")
+
+    db.close()
+
+
+@app.command()
+def people(
+    min_size: Annotated[int, typer.Option(help="Minimum cluster size to show.")] = 5,
+    limit: Annotated[int, typer.Option(help="Max rows to display.")] = 50,
+) -> None:
+    """List detected clusters of faces - name them with `lensgrep name`."""
+    db = Database()
+    clusters = db.cluster_summary(min_size=min_size)[:limit]
+    persons = {p.id: p for p in db.list_persons()}
+
+    table = Table(title="People (clusters)")
+    table.add_column("Cluster", justify="right", style="cyan")
+    table.add_column("Faces", justify="right")
+    table.add_column("Named as", style="green")
+    for cid, n, pid, _pname in clusters:
+        name = persons[pid].name if pid in persons else "-"
+        table.add_row(str(cid), str(n), name)
+    console.print(table)
+
+    named_table = Table(title="\nNamed persons")
+    named_table.add_column("Name", style="green")
+    named_table.add_column("Faces", justify="right")
+    named_table.add_column("Note", style="dim")
+    for p in db.list_persons():
+        named_table.add_row(p.name, str(p.face_count), p.note or "")
+    console.print(named_table)
+
+    db.close()
+
+
+@app.command()
+def name(
+    cluster_id: Annotated[int, typer.Argument(help="Cluster id from `lensgrep people`.")],
+    person_name: Annotated[str, typer.Argument(help="Name to assign.")],
+    note: Annotated[str | None, typer.Option(help="Optional note.")] = None,
+) -> None:
+    """Tag a cluster of faces with a person's name."""
+    db = Database()
+    with db.tx():
+        pid = db.upsert_person(person_name, note)
+        n = db.assign_person_to_cluster(cluster_id, pid)
+    console.print(f"[green]ok[/] '{person_name}' <- cluster {cluster_id}, assigned {n} face(s)")
+    db.close()
+
+
+@app.command()
+def find(
+    person_name: Annotated[str, typer.Argument(help="Person name to find photos of.")],
+    limit: Annotated[int, typer.Option("-n", "--limit", help="Max photos to list.")] = 50,
+    paths_only: Annotated[
+        bool, typer.Option("--paths", help="Print file paths only (one per line).")
+    ] = False,
+) -> None:
+    """Find photos of a tagged person."""
+    db = Database()
+    person = db.get_person(person_name)
+    if person is None:
+        console.print(f"[red]error[/] no such person: {person_name}")
+        raise typer.Exit(1)
+    rows = db.find_images_for_person(person.id, limit=limit)
+    seen: set[str] = set()
+    rows = [r for r in rows if not (r[1] in seen or seen.add(r[1]))]
+
+    if paths_only:
+        for _fid, p, _d, _s in rows:
+            console.print(p, highlight=False, markup=False)
+    else:
+        table = Table(title=f"Photos of {person.name}  ({len(rows)} shown)")
+        table.add_column("#", justify="right")
+        table.add_column("path")
+        table.add_column("det", justify="right")
+        table.add_column("sharp", justify="right")
+        for i, (_fid, p, d, s) in enumerate(rows, 1):
+            table.add_row(str(i), p, f"{d:.2f}", f"{s:.0f}")
+        console.print(table)
+
+    db.close()
+
+
+@app.command()
+def export(
+    person_name: Annotated[str, typer.Argument(help="Person to export.")],
+    out_dir: Annotated[Path, typer.Argument(help="Destination folder.")],
+    limit: Annotated[int, typer.Option("-n", "--limit", help="Max photos.")] = 1000,
+    mode: Annotated[str, typer.Option(help="copy | symlink | hardlink")] = "copy",
+) -> None:
+    """Copy/symlink all photos of a person into a folder."""
+    from .exporters.files import export_person_files
+
+    db = Database()
+    n = export_person_files(db, person_name, out_dir, limit=limit, mode=mode)
+    console.print(f"[green]ok[/] exported {n} photo(s) to {out_dir}")
+    db.close()
+
+
+@app.command()
+def lora(
+    person_name: Annotated[str, typer.Argument(help="Person to build LoRA dataset for.")],
+    out_dir: Annotated[Path, typer.Argument(help="Destination folder for the dataset.")],
+    size: Annotated[
+        int, typer.Option("-n", "--size", help="Target dataset size (35-60 recommended).")
+    ] = 50,
+    resolution: Annotated[int, typer.Option(help="Crop resolution (1024 for SDXL/Flux).")] = 1024,
+    token: Annotated[
+        str | None, typer.Option(help="Caption token. Defaults to lowercased person name.")
+    ] = None,
+    captions: Annotated[str, typer.Option(help="template | none")] = "template",
+) -> None:
+    """Build a Flux/SDXL LoRA training dataset for a tagged person."""
+    from .exporters.lora import build_lora_dataset
+
+    db = Database()
+    n = build_lora_dataset(
+        db,
+        person_name,
+        out_dir,
+        size=size,
+        resolution=resolution,
+        token=token,
+        captions=captions,
+    )
+    console.print(
+        f"[green]ok[/] LoRA dataset: {n} image(s) at {resolution}x{resolution} -> {out_dir}"
+    )
+    console.print(f"  Token: [cyan]{token or person_name.lower().replace(' ', '_')}[/]")
+    console.print("  Next: open AI Toolkit / kohya_ss -> point dataset path here -> train.")
+    db.close()
+
+
+@app.command()
+def stats() -> None:
+    """Show database statistics."""
+    db = Database()
+    s = db.stats()
+    table = Table(title=f"lensgrep - {data_dir()}")
+    table.add_column("metric", style="cyan")
+    table.add_column("value", justify="right")
+    for k, v in s.items():
+        table.add_row(k.replace("_", " "), f"{v:,}")
+    console.print(table)
+    db.close()
+
+
+@app.command()
+def dupes(
+    near: Annotated[
+        bool,
+        typer.Option(
+            "--near/--exact", help="Find perceptually-similar duplicates (default: --exact only)."
+        ),
+    ] = False,
+    threshold: Annotated[
+        int,
+        typer.Option(
+            help="pHash Hamming distance for --near (0=identical, 5=common dupes, 10=loose)."
+        ),
+    ] = 5,
+    keep: Annotated[
+        str,
+        typer.Option(
+            help="Which file to keep per group: largest | oldest | newest | shortest-path"
+        ),
+    ] = "largest",
+    mode: Annotated[
+        str, typer.Option(help="What to do with victims: list | delete | symlink")
+    ] = "list",
+    limit: Annotated[int, typer.Option("-n", "--limit", help="Max groups to display.")] = 50,
+) -> None:
+    """Find duplicate photos in the indexed library.
+
+    By default, --exact (bit-identical files) and --mode list (read-only).
+    Run `lensgrep dupes --mode delete` to actually free disk space.
+    """
+    from .core.dedupe import (
+        execute_actions,
+        find_exact_duplicates,
+        find_near_duplicates,
+        plan_actions,
+    )
+
+    db = Database()
+    if near:
+        console.print(f"[cyan]>>[/] finding near-duplicates (pHash distance <= {threshold})...")
+        groups = find_near_duplicates(db, threshold=threshold)
+        actions_threshold: int | None = threshold
+    else:
+        console.print("[cyan]>>[/] finding exact duplicates (SHA-256 match)...")
+        groups = find_exact_duplicates(db)
+        actions_threshold = None
+
+    if not groups:
+        console.print("[green]No duplicates found.[/]")
+        db.close()
+        return
+
+    actions = plan_actions(groups, strategy=keep, max_keeper_distance=actions_threshold)
+    total_freeable = sum(a.bytes_freed for a in actions)
+
+    console.print(
+        f"[yellow]Found {len(groups)} group(s), {sum(len(a.victims) for a in actions)} extra file(s), "
+        f"could free {total_freeable / 1024 / 1024:.1f} MB.[/]"
+    )
+
+    for i, act in enumerate(actions[:limit], 1):
+        t = Table(title=f"Group {i}  (keep={keep})", show_lines=False)
+        t.add_column("role", style="cyan")
+        t.add_column("path")
+        t.add_column("size", justify="right")
+        t.add_column("WxH", justify="right")
+        t.add_row(
+            "KEEP",
+            act.keeper.path,
+            f"{act.keeper.size / 1024:.0f} KB",
+            f"{act.keeper.width}x{act.keeper.height}" if act.keeper.width else "?",
+        )
+        for v in act.victims:
+            t.add_row(
+                f"[red]{mode}[/]",
+                v.path,
+                f"{v.size / 1024:.0f} KB",
+                f"{v.width}x{v.height}" if v.width else "?",
+            )
+        console.print(t)
+
+    if mode == "list":
+        console.print(
+            "\n[dim]Read-only listing. Re-run with [bold]--mode delete[/bold] or [bold]--mode symlink[/bold] to act.[/]"
+        )
+    else:
+        removed, freed = execute_actions(db, actions, mode=mode)
+        console.print(f"[green]ok[/] {mode}d {removed} file(s), freed {freed / 1024 / 1024:.1f} MB")
+
+    db.close()
+
+
+@app.command()
+def recluster(
+    eps: Annotated[float, typer.Option(help="DBSCAN epsilon (cosine distance).")] = 0.35,
+    min_samples: Annotated[int, typer.Option(help="DBSCAN min samples.")] = 5,
+) -> None:
+    """Re-cluster all face embeddings."""
+    db = Database()
+    console.print(f"[cyan]>>[/] re-clustering (eps={eps}, min_samples={min_samples})...")
+    counts = cluster_all(db, eps=eps, min_samples=min_samples)
+    n_clusters = sum(1 for k in counts if k >= 0)
+    n_noise = counts.get(-1, 0)
+    console.print(f"[green]done[/] {n_clusters} clusters, {n_noise} noise")
+    db.close()
+
+
+if __name__ == "__main__":
+    app()

lensgrep/core/__init__.py

@@ -0,0 +1 @@
+"""lensgrep core: database, scanning, embedding, search, clustering."""

lensgrep/core/cluster.py

@@ -0,0 +1,44 @@
+"""DBSCAN clustering of face embeddings."""
+
+from __future__ import annotations
+
+import numpy as np
+from sklearn.cluster import DBSCAN
+
+from .db import Database
+
+
+def normalize(embs: np.ndarray) -> np.ndarray:
+    return embs / (np.linalg.norm(embs, axis=1, keepdims=True) + 1e-9)
+
+
+def cluster_all(
+    db: Database,
+    eps: float = 0.35,
+    min_samples: int = 5,
+) -> dict[int, int]:
+    """Cluster all faces in DB by ArcFace cosine distance.
+
+    Returns: {cluster_id: count}.  Cluster -1 = noise.
+    Writes cluster_id back to faces table.
+    """
+    ids, embs = db.all_face_embeddings()
+    if not ids:
+        return {}
+    embs = normalize(embs.astype(np.float32))
+    db_clust = DBSCAN(eps=eps, min_samples=min_samples, metric="cosine", n_jobs=-1)
+    labels = db_clust.fit_predict(embs)
+
+    counts: dict[int, int] = {}
+    for lab in labels:
+        counts[int(lab)] = counts.get(int(lab), 0) + 1
+
+    with db.tx():
+        db.set_cluster_ids(zip(ids, (int(x) for x in labels), strict=True))
+        # Carry forward any existing person_id assignments to faces that just
+        # joined a named cluster on this scan. Without this, an incremental
+        # scan can index new photos of a tagged person but find/export/lora
+        # won't see them until the user manually re-runs `lensgrep name`.
+        db.propagate_persons_through_clusters()
+
+    return counts