photo-stack-finder 0.1.7__py3-none-any.whl → 0.1.8__py3-none-any.whl

utils/config.py

@@ -1,4 +1,4 @@
-"""Global configuration for photo_dedup project."""
+"""Global configuration for photo_stack_finder project."""
 
 from __future__ import annotations
 
@@ -22,6 +22,9 @@ class ProcessingConfig:
     # Random seeds for reproducibility
     DEFAULT_RANDOM_SEED: int = 12345
 
+    # Byte-identical detection (skip to trust SHA256 uniqueness)
+    SKIP_BYTE_IDENTICAL: bool = True
+
     # Sequential gates configuration (order matters)
     # Gates are executed in order, short-circuiting on first failure
     # "aspect_ratio" is special gate, others are photo_compare methods
@@ -76,7 +79,7 @@ class ProcessingConfig:
     TARGET_FPR: float = 0.00075  # Target false positive rate for benchmark thresholds
 
     # Logging configuration
-    LOG_LEVEL: str = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+    LOG_LEVEL: str = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL  # DEBUG, INFO, WARNING, ERROR, CRITICAL
 
 
 @dataclass
@@ -105,7 +108,7 @@ class PathsConfig:
 
     SOURCE_DIR: str = ""
     WORK_DIR: str = ""
-    WORK_DIR_NAME: str = "photo_dedup"
+    WORK_DIR_NAME: str = "photo_stack_finder"
 
     # ALL filenames are now consistently abstracted as configurable constants
     # Pipeline data files
@@ -316,7 +319,7 @@ class OrchestratorConfig:
     """Configuration for orchestrator server and UI."""
 
     # Directory naming
-    DEFAULT_WORK_DIR_NAME: str = "photo_dedup"  # Default work directory name (relative to source parent)
+    DEFAULT_WORK_DIR_NAME: str = "photo_stack_finder"  # Default work directory name (relative to source parent)
 
     # Static asset paths (computed relative to package)
     # These are set dynamically and should not be overridden
@@ -344,7 +347,7 @@ ARG_CONFIG_MAP: list[tuple[str, str, Any, bool]] = [
 
 @dataclass
 class Config:
-    """Global configuration for photo_dedup."""
+    """Global configuration for photo_stack_finder."""
 
     processing: ProcessingConfig
     sequences: SequenceConfig

utils/data_io.py

@@ -1,83 +1,83 @@
-"""Data I/O utilities for CSV file handling with error handling.
-
-This module provides standardized functions for loading and saving CSV files
-with consistent error handling, logging, and user feedback.
-"""
-
-import logging
-import sys
-from pathlib import Path
-from typing import Any
-
-import pandas as pd
-
-# Configure logger for this module
-logger = logging.getLogger(__name__)
-
-
-def load_required_csv(
-    path: Path,
-    error_message: str,
-    **pandas_kwargs: Any,
-) -> pd.DataFrame:
-    """Load a CSV file or exit with error message if not found.
-
-    This function is designed for user-facing scripts that require specific
-    input files. If the file doesn't exist, it prints an error message and
-    exits the program with status code 1.
-
-    Args:
-        path: Path to the CSV file to load
-        error_message: Error message to display if file doesn't exist
-        **pandas_kwargs: Additional keyword arguments to pass to pd.read_csv()
-
-    Returns:
-        The loaded DataFrame
-
-    Raises:
-        SystemExit: If the file doesn't exist (exits with code 1)
-
-    Example:
-        >>> df = load_required_csv(
-        ...     Path("data/scores.csv"),
-        ...     "scores.csv not found. Run benchmark first.",
-        ...     index_col=0
-        ... )
-    """
-    if not path.exists():
-        logger.error(error_message)
-        sys.exit(1)
-
-    # read_csv returns DataFrame, but mypy doesn't infer this from **kwargs
-    result: pd.DataFrame = pd.read_csv(path, **pandas_kwargs)
-    return result
-
-
-def save_dataframe_with_logging(
-    df: pd.DataFrame,
-    path: Path,
-    description: str,
-    **pandas_kwargs: Any,
-) -> None:
-    """Save DataFrame to CSV with logging.
-
-    Saves the DataFrame and prints a confirmation message indicating
-    what was saved and where.
-
-    Args:
-        df: DataFrame to save
-        path: Path where the CSV should be saved
-        description: Human-readable description of what's being saved (for logging)
-        **pandas_kwargs: Additional keyword arguments to pass to pd.to_csv()
-
-    Example:
-        >>> save_dataframe_with_logging(
-        ...     outliers_df,
-        ...     output_dir / "outliers.csv",
-        ...     "outlier pairs",
-        ...     index=False
-        ... )
-        # Prints: "Saved 42 outlier pairs to output/outliers.csv"
-    """
-    df.to_csv(path, **pandas_kwargs)
-    logger.info(f"Saved {len(df)} {description} to {path}")
+"""Data I/O utilities for CSV file handling with error handling.
+
+This module provides standardized functions for loading and saving CSV files
+with consistent error handling, logging, and user feedback.
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+# Configure logger for this module
+logger = logging.getLogger(__name__)
+
+
+def load_required_csv(
+    path: Path,
+    error_message: str,
+    **pandas_kwargs: Any,
+) -> pd.DataFrame:
+    """Load a CSV file or exit with error message if not found.
+
+    This function is designed for user-facing scripts that require specific
+    input files. If the file doesn't exist, it prints an error message and
+    exits the program with status code 1.
+
+    Args:
+        path: Path to the CSV file to load
+        error_message: Error message to display if file doesn't exist
+        **pandas_kwargs: Additional keyword arguments to pass to pd.read_csv()
+
+    Returns:
+        The loaded DataFrame
+
+    Raises:
+        SystemExit: If the file doesn't exist (exits with code 1)
+
+    Example:
+        >>> df = load_required_csv(
+        ...     Path("data/scores.csv"),
+        ...     "scores.csv not found. Run benchmark first.",
+        ...     index_col=0
+        ... )
+    """
+    if not path.exists():
+        logger.error(error_message)
+        sys.exit(1)
+
+    # read_csv returns DataFrame, but mypy doesn't infer this from **kwargs
+    result: pd.DataFrame = pd.read_csv(path, **pandas_kwargs)
+    return result
+
+
+def save_dataframe_with_logging(
+    df: pd.DataFrame,
+    path: Path,
+    description: str,
+    **pandas_kwargs: Any,
+) -> None:
+    """Save DataFrame to CSV with logging.
+
+    Saves the DataFrame and prints a confirmation message indicating
+    what was saved and where.
+
+    Args:
+        df: DataFrame to save
+        path: Path where the CSV should be saved
+        description: Human-readable description of what's being saved (for logging)
+        **pandas_kwargs: Additional keyword arguments to pass to pd.to_csv()
+
+    Example:
+        >>> save_dataframe_with_logging(
+        ...     outliers_df,
+        ...     output_dir / "outliers.csv",
+        ...     "outlier pairs",
+        ...     index=False
+        ... )
+        # Prints: "Saved 42 outlier pairs to output/outliers.csv"
+    """
+    df.to_csv(path, **pandas_kwargs)
+    logger.info(f"Saved {len(df)} {description} to {path}")

utils/graph_context.py

@@ -1,44 +1,44 @@
-"""Global graph context for pipeline auto-registration.
-
-This module holds the active PipelineGraph instance during pipeline
-construction. Stages and channels auto-register with this graph when
-instantiated within a PipelineBuilder context.
-
-Architecture:
-- Breaks circular dependency between pipeline_stage, pipeline_graph, and channel
-- Provides clean separation of concerns (graph context vs stage implementation)
-- Enables auto-registration pattern without tight coupling
-"""
-
-# FIXME: Is this thread-safe?
-
-from __future__ import annotations
-
-from .pipeline_graph import PipelineGraph
-
-# Circular dependency resolved by moving BaseChannel from channel.py to ports.py
-# Previous cycle: channel → graph_context → pipeline_graph → channel (via BaseChannel)
-# Now: pipeline_graph → ports (BaseChannel), channel → ports (BaseChannel), no cycle!
-
-# Global graph context set by PipelineBuilder context manager
-_active_graph: PipelineGraph | None = None
-
-
-def get_active_graph() -> PipelineGraph | None:
-    """Get the currently active pipeline graph for auto-registration.
-
-    Returns:
-        The active PipelineGraph if within a PipelineBuilder context, None otherwise
-    """
-    return _active_graph
-
-
-def set_active_graph(graph: PipelineGraph | None) -> None:
-    """Set the active pipeline graph for auto-registration.
-
-    Args:
-        graph: The PipelineGraph to set as active, or None to clear
-    """
-    global _active_graph  # noqa: PLW0603
-    # Library configuration pattern - global state for graph context
-    _active_graph = graph
+"""Global graph context for pipeline auto-registration.
+
+This module holds the active PipelineGraph instance during pipeline
+construction. Stages and channels auto-register with this graph when
+instantiated within a PipelineBuilder context.
+
+Architecture:
+- Breaks circular dependency between pipeline_stage, pipeline_graph, and channel
+- Provides clean separation of concerns (graph context vs stage implementation)
+- Enables auto-registration pattern without tight coupling
+"""
+
+# FIXME: Is this thread-safe?
+
+from __future__ import annotations
+
+from .pipeline_graph import PipelineGraph
+
+# Circular dependency resolved by moving BaseChannel from channel.py to ports.py
+# Previous cycle: channel → graph_context → pipeline_graph → channel (via BaseChannel)
+# Now: pipeline_graph → ports (BaseChannel), channel → ports (BaseChannel), no cycle!
+
+# Global graph context set by PipelineBuilder context manager
+_active_graph: PipelineGraph | None = None
+
+
+def get_active_graph() -> PipelineGraph | None:
+    """Get the currently active pipeline graph for auto-registration.
+
+    Returns:
+        The active PipelineGraph if within a PipelineBuilder context, None otherwise
+    """
+    return _active_graph
+
+
+def set_active_graph(graph: PipelineGraph | None) -> None:
+    """Set the active pipeline graph for auto-registration.
+
+    Args:
+        graph: The PipelineGraph to set as active, or None to clear
+    """
+    global _active_graph  # noqa: PLW0603
+    # Library configuration pattern - global state for graph context
+    _active_graph = graph

utils/logger.py

@@ -1,4 +1,4 @@
-"""Logging module for photo_dedup project.
+"""Logging module for photo_stack_finder project.
 
 Provides centralized logging configuration that reads from CONFIG.
 """
@@ -32,7 +32,7 @@ def get_logger() -> logging.Logger:
     # Library configuration pattern - global state for logger
 
     if _logger is None:
-        _logger = logging.getLogger("photo_dedup")
+        _logger = logging.getLogger("photo_stack_finder")
         _logger.setLevel(getattr(logging, CONFIG.processing.LOG_LEVEL))
 
         # Console handler with formatting

utils/models.py

@@ -292,7 +292,7 @@ class IdenticalGroup(BaseModel):
     """Model for a group of byte-identical photos.
 
     Represents a set of photos that have identical SHA256 hashes and are verified
-    to be byte-for-byte identical. Used in review UI for photo deduplication decisions.
+    to be byte-for-byte identical. Used in review UI for photo stack finding decisions.
     """
 
     group_id: str = Field(..., description="Stable group identifier (SHA256 hash of sorted photo SHA256s)")
@@ -353,7 +353,7 @@ class SequenceGroup(BaseModel):
     """Model for a group of similar photo sequences.
 
     Represents multiple photo sequences that share similar template patterns or
-    perceptual features. Used in review UI for sequence-level deduplication decisions.
+    perceptual features. Used in review UI for sequence-level stack finding decisions.
     """
 
     group_id: str = Field(..., description="Stable group identifier")

utils/photo_file.py

@@ -18,6 +18,7 @@ import pillow_heif
 from PIL import ExifTags, Image, ImageOps
 
 from .config import CONFIG
+from .template_parsing import INDEX_T
 
 pillow_heif.register_heif_opener()
 
@@ -67,20 +68,7 @@ class ImageData:
         Returns:
             Aspect ratio (width/height)
         """
-        if "aspect_ratio" not in self._photo.cache:
-            # Need to load pixels to get dimensions
-            raw_pixels = self._photo._load_raw_pixels()
-            h, w = raw_pixels.shape[:2]
-            aspect_ratio = w / h if h > 0 else 0.0
-
-            # Store in PhotoFile permanently
-            self._photo.cache["aspect_ratio"] = aspect_ratio
-            self._photo.cache["width"] = w
-            self._photo.cache["height"] = h
-
-            return aspect_ratio
-        # Already calculated, return cached value
-        return cast(float, self._photo.cache["aspect_ratio"])
+        return self._photo.aspect_ratio
 
     def get_pixels(self) -> npt.NDArray[np.uint8]:
         """Get pixels (EXIF orientation applied).
@@ -104,14 +92,6 @@ class ImageData:
         # Load raw pixels
         raw_pixels = self._photo._load_raw_pixels()
 
-        # Cache dimensions if not already done
-        if "aspect_ratio" not in self._photo.cache:
-            h, w = raw_pixels.shape[:2]
-            aspect_ratio = w / h if h > 0 else 0.0
-            self._photo.cache["aspect_ratio"] = aspect_ratio
-            self._photo.cache["width"] = w
-            self._photo.cache["height"] = h
-
         # Cache in context manager scope
         self._pixels = raw_pixels
         return raw_pixels
@@ -122,10 +102,7 @@ class ImageData:
         Returns:
             Width in pixels
         """
-        # Ensure dimensions are cached
-        if "width" not in self._photo.cache:
-            _ = self.get_aspect_ratio()  # Triggers dimension extraction
-        return cast(int, self._photo.cache["width"])
+        return self._photo.width
 
     def get_height(self) -> int:
         """Get height (triggers dimension extraction if needed).
@@ -133,10 +110,7 @@ class ImageData:
         Returns:
             Height in pixels
         """
-        # Ensure dimensions are cached
-        if "height" not in self._photo.cache:
-            _ = self.get_aspect_ratio()  # Triggers dimension extraction
-        return cast(int, self._photo.cache["height"])
+        return self._photo.height
 
     def get_normalization_rotation(self) -> int:
         """Get rotation needed to normalize photo to landscape.
@@ -148,8 +122,8 @@ class ImageData:
             return self._original_rotation
 
         # Get dimensions (may trigger dimension extraction)
-        width = self.get_width()
-        height = self.get_height()
+        width = self._photo.width
+        height = self._photo.height
 
         # Portrait photos need 90° CCW rotation to become landscape
         self._original_rotation = 90 if width < height else 0
@@ -184,14 +158,8 @@ class ImageData:
         # Apply rotation using numpy
         if rotation == 0:
             rotated_pixels = original_pixels
-        elif rotation == 90:
-            rotated_pixels = np.rot90(original_pixels, k=1)  # 90° CCW
-        elif rotation == 180:
-            rotated_pixels = np.rot90(original_pixels, k=2)  # 180°
-        elif rotation == 270:
-            rotated_pixels = np.rot90(original_pixels, k=3)  # 270° CCW (= 90° CW)
         else:
-            raise ValueError(f"Invalid rotation angle: {rotation}. Must be 0, 90, 180, or 270.")
+            rotated_pixels = np.rot90(original_pixels, k=rotation // 90)  # 90° CCW
 
         # Cache and return
         self._pixels_cache[rotation] = rotated_pixels
@@ -277,52 +245,43 @@ class PhotoFile:
         mime: str,
         size_bytes: int,
         file_id: int,
+        width: int,
+        height: int,
+        template: str | None = None,
+        template_index: INDEX_T | None = None,
     ):
-        """Create a PhotoFile record with core properties.
+        """Create a PhotoFile record with metadata extracted from file.
 
-        Core properties computed during tree walk: path, mime, size_bytes.
-        All other properties (pixels, dimensions, EXIF) are computed lazily.
+        All metadata is provided by the caller (typically ComputeShaBins.stage_worker())
+        which performs the file I/O. PhotoFile.__init__ never opens files - it's a
+        pure data container.
 
         Args:
                 path: Path to the photo file (None for anonymized test fixtures)
                 mime: MIME type
                 size_bytes: File size in bytes
                 file_id: Unique identifier
+                width: Image width with EXIF orientation applied
+                height: Image height with EXIF orientation applied
+                template: Optional template pattern for this file (for test mocking)
+                template_index: Optional template index tuple (for test mocking)
         """
         self.id: int = file_id
         self.path: Path | None = path
         self.mime: str = mime
         self.size_bytes: int = size_bytes
+        self.width: int = width
+        self.height: int = height
 
-        # Cache for lazy-loaded values (pixels, dimensions, EXIF, method preparations)
-        self.cache: dict[str | tuple[str, int], Any] = {}
-
-    @property
-    def pixels(self) -> int:
-        """Get pixel count (lazy-loaded and cached).
-
-        Computes width * height on first access by opening the image.
-        Cached for subsequent accesses.
+        self.pixels: int = self.width * self.height
+        self.aspect_ratio: float = self.width / self.height if self.height != 0 else 0.0
 
-        Returns:
-                Total pixel count (width * height, rotation-invariant)
-        """
-        if "pixels" not in self.cache:
-            self.cache["pixels"] = self._compute_pixels()
-        result: int = self.cache["pixels"]
-        return result
-
-    def _compute_pixels(self) -> int:
-        """Compute pixel count by opening the image.
+        # Cache for lazy-loaded values (EXIF, method preparations, similarity scores)
+        self.cache: dict[str | tuple[str, int], Any] = {}
 
-        Returns:
-                Total pixels (width * height)
-        """
-        assert self.path is not None, f"Photo {self.id} has None path - cannot compute pixels"
-        with Image.open(self.path) as img:
-            width: int = img.width
-            height: int = img.height
-            return width * height
+        # Store template in cache if provided (for tests)
+        if template is not None and template_index is not None:
+            self.cache["TEMPLATE"] = (template, template_index)
 
     @contextmanager
     def image_data(self) -> Iterator[ImageData]:
@@ -341,23 +300,13 @@ class PhotoFile:
             AssertionError: If path is None and dimension values not in cache
 
         Example:
-            >>> with photo.image_data() as img:
+            >>> with self.image_data() as img:
             ...     # No pixels loaded yet
-            ...     if img.get_aspect_ratio() < 0.5:
+            ...     if img._photo.aspect_ratio < 0.5:
             ...         return  # Early exit, pixels never loaded
             ...     # Only load pixels if needed
             ...     pixels = img.get_pixels()
         """
-        # For test fixtures: Allow path=None if dimension values are pre-populated
-        if self.path is None:
-            required_keys = {"aspect_ratio", "width", "height"}
-            cache_str_keys = {k for k in self.cache if isinstance(k, str)}
-            missing_keys = required_keys - cache_str_keys
-            assert not missing_keys, (
-                f"Cannot get image data for photo {self.id}: path is None. "
-                f"Test fixtures must pre-populate: {missing_keys}"
-            )
-
         # Create lazy accessor
         data = ImageData(self)
 
@@ -388,19 +337,57 @@ class PhotoFile:
         The tuple is designed for use with min() to pick the "best" photo:
         - Prefer higher pixel count (negated)
         - Prefer larger file size (negated)
-        - Use path as tiebreaker
+        - Use template as tiebreaker (keeps sequences together)
         - Use ID as final tiebreaker
 
         Returns:
-                Tuple of (-pixels, -size_bytes, path_str, id)
+                Tuple of (-pixels, -size_bytes, template, id)
+
+        """
+        return -self.pixels, -self.size_bytes, self.template, self.id
+
+    @property
+    def template(self) -> str:
+        """Get template pattern for this photo's filename.
+
+        Template is extracted during SHA binning stage and cached.
+        Before SHA stage, falls back to the full path string.
+
+        Returns:
+            Template string (e.g., "IMG_{P0}.jpg" for "IMG_1234.jpg")
 
+        Example:
+            >>> photo.template  # After SHA stage
+            "IMG_{P0}.jpg"
         """
-        return -self.pixels, -self.size_bytes, str(self.path), self.id
+        if "TEMPLATE" in self.cache:
+            template_str: str = cast(str, self.cache["TEMPLATE"][0])
+            return template_str
+        return str(self.path)  # Fallback before SHA stage
+
+    @property
+    def template_index(self) -> INDEX_T:
+        """Get digit sequence index for this photo's filename.
+
+        Returns:
+            Tuple of digit sequences (e.g., ("1234",) for "IMG_1234.jpg")
+            Empty tuple if template not yet cached.
+
+        Example:
+            >>> photo.template_index  # After SHA stage
+            ("1234",)
+        """
+        if "TEMPLATE" in self.cache:
+            index: INDEX_T = cast(INDEX_T, self.cache["TEMPLATE"][1])
+            return index
+        return ()  # Fallback before SHA stage
 
     # === Lazy-loading properties for metadata ===
 
     @property
-    def exif_data(self) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
+    def exif_data(
+        self,
+    ) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
         """Get EXIF data (lazy-loaded and cached).
 
         Returns:
@@ -412,7 +399,9 @@ class PhotoFile:
         return result
 
     @property
-    def image_properties(self) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
+    def image_properties(
+        self,
+    ) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
         """Get PIL Image properties (format/mode/size lazy-loaded).
 
         Note: Width, height, and aspect_ratio are no longer included here.
@@ -427,7 +416,9 @@ class PhotoFile:
         return cast(dict[str, Any], self.cache["image_props"])
 
     @property
-    def google_metadata(self) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
+    def google_metadata(
+        self,
+    ) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
         """Get Google Photos sidecar metadata (lazy-loaded and cached).
 
         Returns:
@@ -441,7 +432,9 @@ class PhotoFile:
         return result
 
     @property
-    def xmp_metadata(self) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
+    def xmp_metadata(
+        self,
+    ) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
         """Get XMP sidecar metadata (lazy-loaded and cached).
 
         Returns:
@@ -455,7 +448,9 @@ class PhotoFile:
         return result
 
     @property
-    def supplemental_metadata(self) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
+    def supplemental_metadata(
+        self,
+    ) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
         """Get supplemental metadata (lazy-loaded and cached).
 
         Returns:
@@ -470,7 +465,9 @@ class PhotoFile:
 
     # === Internal metadata loaders ===
 
-    def _load_exif(self) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
+    def _load_exif(
+        self,
+    ) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
         """Load EXIF data from the image.
 
         Returns:
@@ -498,7 +495,9 @@ class PhotoFile:
 
         return result
 
-    def _load_image_format(self) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
+    def _load_image_format(
+        self,
+    ) -> dict[str, Any]:  # pragma: no cover - Reserved for future metadata features
         """Load PIL Image format and mode (lightweight properties).
 
         Note: Width, height, aspect_ratio are no longer eager properties.