selects 0.1.0__py3-none-any.whl

selects/__init__.py

@@ -0,0 +1,3 @@
+"""selects – local AI-assisted travel photo and video culling."""
+
+__version__ = "0.1.0"

selects/__main__.py

@@ -0,0 +1,4 @@
+from selects.cli import main
+
+if __name__ == "__main__":
+    main()

selects/classical/aesthetic_grade.py

@@ -0,0 +1,101 @@
+"""Natural auto-edit for selects's /api/enhance endpoint.
+
+Rewritten 2026-05-25 — user feedback: previous CLAHE pipeline still over-
+sharpened and bumped contrast on already-good photos. The new approach is
+"do as little as possible" — only correct what's actually wrong:
+
+  - If the dynamic range is already wide (p1→p99 spans most of [0,255]),
+    skip the stretch entirely.
+  - If shadows aren't actually blocked, skip CLAHE.
+  - Always skip the unsharp mask (was the main over-sharpening offender).
+  - White balance correction is *very* subtle (15% pull toward neutral)
+    so warm sunsets and cool snow scenes are preserved.
+  - Highlight roll-off only kicks in if there's measurable clipping.
+
+For a photo that's already well-exposed and well-balanced, this function
+is now nearly a passthrough — which is the desired behaviour.
+"""
+from __future__ import annotations
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+def auto_edit(img: Image.Image) -> Image.Image:
+    """Apply a natural auto-edit. Returns a new RGB Image."""
+    arr = np.array(img.convert("RGB"))
+
+    lab = cv2.cvtColor(arr, cv2.COLOR_RGB2LAB)
+    L, A, B = cv2.split(lab)
+
+    L_f = L.astype(np.float32)
+
+    # ── Diagnostics on the input image ─────────────────────────────────────
+    p_low, p_high = np.percentile(L_f, [1.0, 99.0])
+    dyn_range = p_high - p_low
+    # How much of the image is sitting against the top of the curve.
+    pct_clipped_hi = float((L_f > 245).mean())
+    pct_clipped_lo = float((L_f < 10).mean())
+    # Where the median sits — used to decide if shadows are genuinely blocked.
+    median = float(np.median(L_f))
+
+    needs_stretch = dyn_range < 200  # default 8-bit range is ~255, so this
+                                     # only triggers on low-contrast images
+    needs_shadow_lift = median < 80 and pct_clipped_lo > 0.05
+    needs_highlight_recover = pct_clipped_hi > 0.04
+
+    L_out = L  # default: untouched
+
+    # ── 1. Percentile stretch — only if range is genuinely narrow ──────────
+    if needs_stretch and dyn_range > 8:
+        L_out = np.clip(
+            (L_f - p_low) * (255.0 / dyn_range),
+            0, 255,
+        ).astype(np.uint8)
+
+    # ── 2. CLAHE — only if shadows are actually blocked ────────────────────
+    if needs_shadow_lift:
+        clahe = cv2.createCLAHE(clipLimit=1.5, tileGridSize=(8, 8))
+        L_clahe = clahe.apply(L_out)
+        # 75% original + 25% CLAHE — very gentle local lift.
+        L_out = cv2.addWeighted(L_out, 0.75, L_clahe, 0.25, 0)
+
+    # ── 3. Highlight roll-off — only if clipping detected ──────────────────
+    if needs_highlight_recover:
+        roll_lut = np.arange(256, dtype=np.float32)
+        above = roll_lut > 232
+        roll_lut[above] = 232 + (roll_lut[above] - 232) * 0.70
+        roll_lut = np.clip(roll_lut, 0, 255).astype(np.uint8)
+        L_out = cv2.LUT(L_out, roll_lut)
+
+    # ── 4. White balance — always subtle (15% pull toward neutral) ─────────
+    a_mean = float(A.mean())
+    b_mean = float(B.mean())
+    a_drift = a_mean - 128.0
+    b_drift = b_mean - 128.0
+    # Only correct if there's an obvious cast (>5 units off neutral).
+    if abs(a_drift) > 5 or abs(b_drift) > 5:
+        a_corr = np.clip(A.astype(np.float32) - a_drift * 0.15, 0, 255).astype(np.uint8)
+        b_corr = np.clip(B.astype(np.float32) - b_drift * 0.15, 0, 255).astype(np.uint8)
+    else:
+        a_corr, b_corr = A, B
+
+    lab_out = cv2.merge([L_out, a_corr, b_corr])
+    rgb_out = cv2.cvtColor(lab_out, cv2.COLOR_LAB2RGB)
+
+    # NOTE: removed the unsharp-mask step. The user reported it over-sharpens
+    # everything. Sharpening should be a deliberate per-photo edit, not part
+    # of an auto pipeline.
+
+    return Image.fromarray(rgb_out)
+
+
+def aesthetic_grade(
+    img: Image.Image,
+    preset: str = "natural",
+    has_face: bool = False,
+) -> Image.Image:
+    """Backwards-compat shim — old callers passed preset / has_face."""
+    _ = preset, has_face
+    return auto_edit(img)

selects/classical/auto_reject.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+BLUR_THRESHOLD = 30.0
+CLIP_THRESHOLD = 0.95
+
+
+@dataclass
+class RejectInput:
+    blur: float
+    exposure_score: float
+    clipped_ratio: float
+    faces_count: int
+
+
+@dataclass
+class RejectResult:
+    auto_reject: bool
+    reason: str | None
+
+
+def evaluate_reject(inp: RejectInput) -> RejectResult:
+    if inp.blur < BLUR_THRESHOLD:
+        return RejectResult(True, "severe_blur")
+    if inp.clipped_ratio > CLIP_THRESHOLD:
+        if inp.exposure_score < 0.1 and inp.faces_count == 0:
+            return RejectResult(True, "blown_out" if inp.exposure_score > 0.5 else "all_black")
+    return RejectResult(False, None)

selects/classical/blur.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import numpy as np
+
+
+def laplacian_variance(img: np.ndarray) -> float:
+    """Variance of Laplacian as a sharpness proxy. Higher = sharper."""
+    import cv2
+
+    gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
+    try:
+        if cv2.cuda.getCudaEnabledDeviceCount() > 0:
+            return _gpu_lap_var(gray)
+    except AttributeError:
+        pass
+    lap = cv2.Laplacian(gray, cv2.CV_64F)
+    return float(lap.var())
+
+
+def _gpu_lap_var(gray: np.ndarray) -> float:
+    import cv2
+
+    gpu = cv2.cuda_GpuMat()
+    gpu.upload(gray)
+    lap = cv2.cuda.createLaplacianFilter(cv2.CV_8U, cv2.CV_64F, ksize=1).apply(gpu)
+    lap_cpu = lap.download()
+    return float(lap_cpu.var())

selects/classical/exposure.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class ExposureResult:
+    score: float
+    mean: float
+    clipped_ratio: float
+
+
+def exposure_score(img: np.ndarray) -> ExposureResult:
+    """Score in [0,1]. Higher = better exposed. 0 = all-black or all-white."""
+    import cv2
+
+    gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
+    mean = float(gray.mean()) / 255.0
+
+    n = gray.size
+    clipped = float(((gray < 8).sum() + (gray > 247).sum()) / n)
+
+    midness = 1.0 - 2.0 * abs(mean - 0.5)
+    # Normalise std to [0,1]: max theoretical std for a bimodal 0/255 image is 127.5
+    std_norm = min(float(gray.std()) / 127.5, 1.0)
+    score = max(0.0, midness * (1.0 - clipped) * (0.5 + 0.5 * std_norm))
+    return ExposureResult(score=score, mean=mean, clipped_ratio=clipped)

selects/classical/faces.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+_detector = None
+
+
+@dataclass
+class Face:
+    x: int
+    y: int
+    w: int
+    h: int
+    confidence: float
+    embedding: Optional[np.ndarray] = field(default=None, compare=False)
+    # Sub-model outputs from buffalo_l (the default FaceAnalysis loads all
+    # modules — detection, recognition, landmark_2d_106, landmark_3d_68/pose).
+    kps: Optional[np.ndarray] = field(default=None, compare=False)              # 5x2 keypoints
+    landmark_2d_106: Optional[np.ndarray] = field(default=None, compare=False)  # 106x2 landmarks
+    pose: Optional[np.ndarray] = field(default=None, compare=False)             # (pitch, yaw, roll) deg
+
+
+def _get_detector():
+    global _detector
+    if _detector is not None:
+        return _detector
+    from insightface.app import FaceAnalysis
+
+    providers = ["CUDAExecutionProvider", "CPUExecutionProvider"]
+    app = FaceAnalysis(name="buffalo_l", providers=providers)
+    app.prepare(ctx_id=0, det_size=(640, 640))
+    _detector = app
+    return app
+
+
+def detect_faces(img: np.ndarray) -> list[Face]:
+    import cv2
+
+    bgr = cv2.cvtColor(img, cv2.COLOR_RGB2BGR)
+    det = _get_detector()
+    faces = det.get(bgr)
+    result = []
+    for f in faces:
+        x1, y1, x2, y2 = (int(v) for v in f.bbox)
+        emb: Optional[np.ndarray] = None
+        if hasattr(f, "embedding") and f.embedding is not None:
+            emb = np.array(f.embedding, dtype=np.float32)
+
+        def _arr(name: str) -> Optional[np.ndarray]:
+            v = getattr(f, name, None)
+            return np.array(v, dtype=np.float64) if v is not None else None
+
+        result.append(
+            Face(
+                x=x1, y=y1, w=x2 - x1, h=y2 - y1,
+                confidence=float(f.det_score), embedding=emb,
+                kps=_arr("kps"),
+                landmark_2d_106=_arr("landmark_2d_106"),
+                pose=_arr("pose"),
+            )
+        )
+    return result

selects/classical/straighten.py

@@ -0,0 +1,111 @@
+"""Quick auto-straighten using probabilistic Hough lines.
+
+Finds near-horizontal lines (skies, horizons, building tops) and rotates the
+image so their median angle becomes exactly horizontal. Robust enough for
+casual phone photos; not a full perspective correction.
+"""
+from __future__ import annotations
+
+import cv2
+import numpy as np
+from PIL import Image
+
+# Maximum rotation we'll apply (degrees). Anything more is usually a
+# deliberate composition, not an error.
+MAX_ROTATION_DEG = 12.0
+# We only consider line segments whose angle is within this band of strictly
+# horizontal (in degrees). Outside this band the line probably isn't a horizon.
+HORIZONTAL_BAND_DEG = 20.0
+
+
+def estimate_rotation_angle(img: Image.Image) -> float:
+    """Return the angle (degrees) by which the image should be rotated to
+    appear straight. Positive = rotate CCW. Returns 0 if no good signal.
+    """
+    arr = np.array(img.convert("RGB"))
+    gray = cv2.cvtColor(arr, cv2.COLOR_RGB2GRAY)
+    # Mild blur to suppress micro-edges
+    gray = cv2.GaussianBlur(gray, (5, 5), 0)
+    edges = cv2.Canny(gray, 60, 180)
+    h, w = edges.shape
+
+    min_line_len = int(min(h, w) * 0.18)
+    max_line_gap = int(min(h, w) * 0.03)
+
+    lines = cv2.HoughLinesP(
+        edges,
+        rho=1,
+        theta=np.pi / 360.0,
+        threshold=80,
+        minLineLength=min_line_len,
+        maxLineGap=max_line_gap,
+    )
+    if lines is None or len(lines) == 0:
+        return 0.0
+
+    angles = []
+    weights = []
+    for line in lines:
+        x1, y1, x2, y2 = line[0]
+        dx = x2 - x1
+        dy = y2 - y1
+        # Skip vertical-ish lines — building edges shouldn't drive the horizon
+        length = (dx * dx + dy * dy) ** 0.5
+        if length < 4:
+            continue
+        # Angle relative to horizontal, in (-90, 90]
+        angle = np.degrees(np.arctan2(dy, dx))
+        # Normalise so we only look at near-horizontal candidates
+        if angle > 90:
+            angle -= 180
+        if angle < -90:
+            angle += 180
+        if abs(angle) > HORIZONTAL_BAND_DEG:
+            continue
+        angles.append(angle)
+        weights.append(length)
+
+    if not angles:
+        return 0.0
+
+    # Weighted median: more confidence in longer lines
+    pairs = sorted(zip(angles, weights))
+    total = sum(w for _, w in pairs)
+    acc = 0.0
+    median_angle = 0.0
+    for a, w in pairs:
+        acc += w
+        if acc >= total / 2:
+            median_angle = a
+            break
+
+    # Clamp to a sane maximum so we don't twist images sideways
+    if median_angle > MAX_ROTATION_DEG:
+        median_angle = MAX_ROTATION_DEG
+    elif median_angle < -MAX_ROTATION_DEG:
+        median_angle = -MAX_ROTATION_DEG
+
+    return float(median_angle)
+
+
+def straighten(img: Image.Image) -> tuple[Image.Image, float]:
+    """Return (straightened image, applied angle in degrees)."""
+    angle = estimate_rotation_angle(img)
+    if abs(angle) < 0.4:
+        return img.convert("RGB"), 0.0
+
+    arr = np.array(img.convert("RGB"))
+    h, w = arr.shape[:2]
+    M = cv2.getRotationMatrix2D((w / 2, h / 2), angle, 1.0)
+    rotated = cv2.warpAffine(
+        arr, M, (w, h),
+        flags=cv2.INTER_CUBIC,
+        borderMode=cv2.BORDER_REPLICATE,
+    )
+    # Crop a small border to hide the rotation triangles
+    if abs(angle) > 0.4:
+        crop_pct = min(0.04, abs(angle) / MAX_ROTATION_DEG * 0.04)
+        cx = int(w * crop_pct)
+        cy = int(h * crop_pct)
+        rotated = rotated[cy : h - cy, cx : w - cx]
+    return Image.fromarray(rotated), float(angle)

selects/cli.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import webbrowser
+from pathlib import Path
+
+import click
+
+from selects.config import get_folder_config
+from selects.db import init_db
+from selects.gpu import detect_capabilities
+from selects.indexer.orchestrator import index_folder
+from selects.pipeline import run_classical_stage
+
+
+@click.group()
+def main():
+    """selects — local AI-assisted travel photo & video culling."""
+
+
+@main.command()
+@click.argument("folder", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option(
+    "--pass", "pass_",
+    type=click.Choice(["all", "index", "classical", "embed", "tag", "smart_tag", "ram_tag",
+                       "thematic", "date", "story", "face_embed", "moment"]),
+    default="all",
+)
+def index(folder: Path, pass_: str):
+    """Index a folder and run available pipeline stages."""
+    cfg = get_folder_config(folder)
+    init_db(cfg.db_path)
+
+    if pass_ in ("all", "index"):
+        added = index_folder(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] {name}", err=True),
+        )
+        click.echo(f"indexed: {added} new files")
+
+    if pass_ in ("all", "classical"):
+        processed = run_classical_stage(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] classical: {name}", err=True),
+        )
+        click.echo(f"classical: {processed} processed")
+
+    if pass_ == "embed":
+        from selects.ml.embed import run_embedding_stage
+        n = run_embedding_stage(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] embed: {name}", err=True),
+        )
+        click.echo(f"embed: {n} processed")
+
+    if pass_ == "tag":
+        from selects.ml.tags import run_tag_stage
+        n = run_tag_stage(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] tag: {name}", err=True),
+        )
+        click.echo(f"tag: {n} photos tagged")
+
+    if pass_ == "smart_tag":
+        from selects.ml.smart_clusters import run_smart_cluster_stage
+        n = run_smart_cluster_stage(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] smart_tag: {name}", err=True),
+        )
+        click.echo(f"smart_tag: {n} photos clustered")
+
+    if pass_ == "thematic":
+        from selects.ml.thematic_clusters import run_thematic_stage
+        n = run_thematic_stage(cfg, on_progress=None)
+        click.echo(f"thematic: {n} location clusters")
+
+    if pass_ == "date":
+        from selects.ml.thematic_clusters import run_date_stage
+        n = run_date_stage(cfg, on_progress=None)
+        click.echo(f"date: {n} day clusters")
+
+    if pass_ == "ram_tag":
+        from selects.ml.ram_tags import run_ram_tagging_stage
+        n = run_ram_tagging_stage(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] ram_tag: {name}", err=True),
+        )
+        click.echo(f"ram_tag: {n} photos tagged")
+
+    if pass_ in ("all", "story"):
+        from selects.ml.stories import run_story_stage
+        n = run_story_stage(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] story: {name}", err=True),
+        )
+        click.echo(f"story: {n} stories built")
+
+    if pass_ == "face_embed":
+        from selects.ml.faces import run_face_embedding_stage
+        n = run_face_embedding_stage(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] face_embed: {name}", err=True),
+        )
+        click.echo(f"face_embed: {n} photos processed")
+
+    if pass_ == "moment":
+        from selects.ml.moments import run_moment_stage
+        n = run_moment_stage(
+            cfg,
+            on_progress=lambda i, t, name: click.echo(f"[{i}/{t}] moment: {name}", err=True),
+        )
+        click.echo(f"moment: {n} moments built")
+
+
+@main.command()
+@click.argument(
+    "folder",
+    required=False,
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+)
+@click.option("--port", default=8000, type=int)
+@click.option("--host", default="127.0.0.1", type=str)
+@click.option("--no-browser", is_flag=True)
+@click.option("--no-background", is_flag=True, help="Don't auto-run indexer on startup")
+def serve(folder: Path | None, port: int, host: str, no_browser: bool, no_background: bool):
+    """Serve the web UI + API.
+
+    With FOLDER: serve that folder as the (bootstrap) library. Without FOLDER:
+    serve the registry's active library if one exists, otherwise start with no
+    active library so the web onboarding page can create the first one.
+    """
+    import threading
+
+    import uvicorn
+
+    from selects.server.app import build_app
+    from selects.server.library_manager import LibraryManager
+
+    if folder is not None:
+        cfg = get_folder_config(folder)
+        init_db(cfg.db_path)
+        app = build_app(cfg, run_background=not no_background)
+    else:
+        manager = LibraryManager()
+        _libs, active_id = manager.list_libraries()
+        if active_id is not None:
+            try:
+                manager.activate(active_id)
+            except Exception:
+                pass
+        app = build_app(manager=manager, run_background=not no_background)
+
+    url = f"http://{'127.0.0.1' if host == '0.0.0.0' else host}:{port}"
+
+    if not no_browser:
+        def _open_browser():
+            import time
+
+            time.sleep(1.5)
+            webbrowser.open(url)
+
+        threading.Thread(target=_open_browser, daemon=True).start()
+
+    click.echo(f"selects serving at {url}")
+    uvicorn.run(app, host=host, port=port, log_level="warning")
+
+
+@main.command()
+def doctor():
+    """Report CUDA / NVDEC / nvImageCodec / cv2.cuda capabilities."""
+    caps = detect_capabilities()
+    click.echo(f"CUDA              : {'yes' if caps.cuda_available else 'no'} ({caps.device_name})")
+    click.echo(f"CUDA capability   : {caps.cuda_capability}")
+    click.echo(f"VRAM              : {caps.vram_total_mb} MB")
+    click.echo(f"NVDEC (torchcodec): {'yes' if caps.nvdec_available else 'no'}")
+    click.echo(f"nvImageCodec      : {'yes' if caps.nvimgcodec_available else 'no'}")
+    click.echo(f"cv2.cuda          : {'yes' if caps.cv2_cuda_available else 'no'}")

selects/config.py

@@ -0,0 +1,74 @@
+"""selects configuration via pydantic-settings."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class FolderConfig(BaseSettings):
+    """Per-folder runtime configuration.
+
+    All fields can be overridden via env vars prefixed SELECTS_.
+    Example: SELECTS_WEB_PORT=9000
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="SELECTS_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    folder: Path
+    web_port: int = 8765
+    web_host: str = "127.0.0.1"
+
+    # Burst detection
+    burst_window_seconds: int = 3
+    burst_similarity_threshold: float = 0.92
+
+    # Aesthetic curation thresholds (combined = AP_WEIGHT*AP + NIMA_WEIGHT*NIMA).
+    # Per-scope gate: photo must be in the top 25% of its scope (day/place/person).
+    # Library-wide floor: photo must also be in the top 35% globally — a
+    # mediocre photo isn't rescued just because its scope is thin.
+    ap_weight: float = 0.6
+    nima_weight: float = 0.4
+    aesthetic_per_scope_pct: float = 75.0   # top 25% within scope
+    aesthetic_library_pct: float = 50.0     # top 50% globally — generous default;
+                                            # bump higher (e.g. 65) to tighten
+
+    # Processing speed mode: "fast" skips some ML steps for quick preview
+    speed_mode: Literal["fast", "full"] = "full"
+
+    @field_validator("folder", mode="before")
+    @classmethod
+    def resolve_folder(cls, v: object) -> Path:
+        return Path(str(v)).expanduser().resolve()
+
+    # ------------------------------------------------------------------ #
+    # Derived paths (stored under <folder>/.selects/)                  #
+    # ------------------------------------------------------------------ #
+
+    @property
+    def state_dir(self) -> Path:
+        """Hidden state directory inside the watched folder."""
+        return self.folder / ".selects"
+
+    @property
+    def db_path(self) -> Path:
+        return self.state_dir / "index.db"
+
+    @property
+    def thumbs_dir(self) -> Path:
+        return self.state_dir / "thumbs"
+
+    @property
+    def previews_dir(self) -> Path:
+        return self.state_dir / "previews"
+
+
+def get_folder_config(folder: Path | str, **overrides: object) -> FolderConfig:
+    """Create a FolderConfig for the given folder, with optional field overrides."""
+    return FolderConfig(folder=folder, **overrides)  # type: ignore[arg-type]