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

orchestrator/__init__.py

@@ -1,7 +1,7 @@
-"""Orchestration layer for photo deduplication workflow.
+"""Orchestration layer for photo stack finding workflow.
 
 This module provides the web-based interface and pipeline orchestration for the
-photo deduplication system. It includes:
+photo stack finding system. It includes:
 
 - FastAPI web application (app)
 - Pipeline orchestration and execution (PipelineOrchestrator)

orchestrator/app.py

@@ -1,4 +1,4 @@
-"""FastAPI orchestration server for photo deduplication.
+"""FastAPI orchestration server for photo stack finding.
 
 This provides a web-based interface for configuring and running the pipeline.
 
@@ -209,7 +209,7 @@ async def lifespan_manager(app: FastAPI) -> AsyncIterator[None]:
 
 
 # Pass the new lifespan function to the FastAPI constructor
-app = FastAPI(title="Photo Dedup Orchestrator", lifespan=lifespan_manager)
+app = FastAPI(title="Photo Stack Finder Orchestrator", lifespan=lifespan_manager)
 
 
 @app.get("/")
@@ -876,9 +876,7 @@ async def websocket_progress(
 async def serve_review_identical() -> FileResponse:
     """Serve identical files review interface."""
     static_path = (
-        Path(CONFIG.orchestrator.STATIC_DIR)
-        if CONFIG.orchestrator.STATIC_DIR
-        else Path(__file__).parent / "static"
+        Path(CONFIG.orchestrator.STATIC_DIR) if CONFIG.orchestrator.STATIC_DIR else Path(__file__).parent / "static"
     )
     return FileResponse(static_path / "review_identical.html")
 
@@ -887,9 +885,7 @@ async def serve_review_identical() -> FileResponse:
 async def serve_review_sequences() -> FileResponse:
     """Serve sequences review interface."""
     static_path = (
-        Path(CONFIG.orchestrator.STATIC_DIR)
-        if CONFIG.orchestrator.STATIC_DIR
-        else Path(__file__).parent / "static"
+        Path(CONFIG.orchestrator.STATIC_DIR) if CONFIG.orchestrator.STATIC_DIR else Path(__file__).parent / "static"
     )
     return FileResponse(static_path / "review_sequences.html")
 
@@ -899,13 +895,12 @@ static_dir = Path(CONFIG.orchestrator.STATIC_DIR) if CONFIG.orchestrator.STATIC_
 if static_dir and static_dir.exists():
     app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
 
+
 # Serve review_common.js from static directory
 @app.get("/review_common.js")
 async def serve_review_common_js() -> FileResponse:
     """Serve review_common.js from static directory."""
     static_path = (
-        Path(CONFIG.orchestrator.STATIC_DIR)
-        if CONFIG.orchestrator.STATIC_DIR
-        else Path(__file__).parent / "static"
+        Path(CONFIG.orchestrator.STATIC_DIR) if CONFIG.orchestrator.STATIC_DIR else Path(__file__).parent / "static"
     )
     return FileResponse(static_path / "review_common.js", media_type="application/javascript")

orchestrator/build_pipeline.py

@@ -1,6 +1,6 @@
 """Pipeline construction using PipelineBuilder pattern.
 
-This module constructs the complete photo deduplication pipeline using the
+This module constructs the complete photo stack finding pipeline using the
 new port-based orchestration system.  All 8 stages are wired together via
 Channel connections based on their InputPort/OutputPort declarations.
 """
@@ -19,7 +19,6 @@ from utils import (
     ComputePerceptualHash,
     ComputePerceptualMatch,
     ComputeShaBins,
-    ComputeTemplates,
     ComputeTemplateSimilarity,
     ComputeVersions,
     InputPort,
@@ -31,18 +30,21 @@ from .pipeline_orchestrator import PipelineOrchestrator
 
 
 def build_pipeline(source_dir: Path) -> PipelineOrchestrator:
-    """Build the complete photo deduplication pipeline.
-
-    Constructs a pipeline graph with 8-9 stages connected via ports:
-    1. ComputeShaBins - Hash files and bin by SHA256
-    2. ComputeIdentical - Find byte-identical duplicates
-    3. ComputeTemplates - Bin photos by filename template
-    4. ComputeVersions - Detect version patterns in filenames
-    5. ComputeTemplateSimilarity - Match photos with similar templates
-    6. ComputeIndices - Find sequences with overlapping indices
-    7. ComputePerceptualHash - Compute perceptual hashes and bin
-    8. ComputePerceptualMatch - Match photos by perceptual hash similarity
-    9. ComputeBenchmarks - (Optional, controlled by CONFIG.benchmark.ENABLED)
+    """Build the complete photo stack finding pipeline.
+
+    Constructs a pipeline graph with 7-8 stages connected via ports:
+    1. ComputeShaBins - Hash files, bin by SHA256, extract templates
+    2. ComputeIdentical - Find byte-identical duplicates, output template bins
+    3. ComputeVersions - Detect version patterns in filenames
+    4. ComputeTemplateSimilarity - Match photos with similar templates
+    5. ComputeIndices - Find sequences with overlapping indices
+    6. ComputePerceptualHash - Compute perceptual hashes and bin
+    7. ComputePerceptualMatch - Match photos by perceptual hash similarity
+    8. ComputeBenchmarks - (Optional, controlled by CONFIG.benchmark.ENABLED)
+
+    Note: ComputeTemplates stage has been merged into ComputeIdentical.
+    Template extraction now happens during SHA binning in ComputeShaBins,
+    and template binning happens in ComputeIdentical's finalise() method.
 
     Args:
         source_dir: Root directory containing photos to process
@@ -60,17 +62,13 @@ def build_pipeline(source_dir: Path) -> PipelineOrchestrator:
         # SHA256 Hashing and Binning
         sha_bins_stage = ComputeShaBins(source_path=source_dir)
 
-        # Identical Files Detection
+        # Identical Files Detection (outputs template bins)
         identical_stage = ComputeIdentical()
         Channel(sha_bins_stage.sha_bins_o, identical_stage.sha_bins_i)
 
-        # Template Binning
-        templates_stage = ComputeTemplates()
-        Channel(identical_stage.nonidentical_o, templates_stage.nonidentical_photos_i)
-
-        # Version Detection
+        # Version Detection (receives template bins directly from ComputeIdentical)
         versions_stage = ComputeVersions()
-        Channel(templates_stage.template_bins_o, versions_stage.template_bins_i)
+        Channel(identical_stage.nonidentical_o, versions_stage.template_bins_i)
 
         # Template Similarity
         template_similarity_stage = ComputeTemplateSimilarity()

orchestrator/orchestrator_runner.py

@@ -68,25 +68,25 @@ def get_os_subdir() -> str:
 
     Returns:
         OS-specific subdirectory name:
-        - 'window' for Windows
+        - 'windows' for Windows
         - 'linux' for Linux
         - 'darwin' for macOS
         - Platform name for others
 
     Example:
-        work_dir = source_parent / "photo_dedup" / get_os_subdir()
-        # Windows: .../photo_dedup/window/
-        # Linux:   .../photo_dedup/linux/
-        # macOS:   .../photo_dedup/darwin/
+        work_dir = source_parent / "photo_stack_finder" / get_os_subdir()
+        # Windows: .../photo_stack_finder/windows/
+        # Linux:   .../photo_stack_finder/linux/
+        # macOS:   .../photo_stack_finder/darwin/
     """
     platform = sys.platform
     if platform.startswith("win"):
-        return "window"
+        return "windows"
     if platform.startswith("linux"):
         return "linux"
     if platform.startswith("darwin"):
         return "darwin"
-    return platform  # Fallback for other platforms
+    return platform  # Fallback for other platforms  # Fallback for other platforms
 
 
 @dataclass
@@ -468,7 +468,7 @@ class OrchestratorRunner:
             # Default work_dir if not provided: OS-specific subdirectory
             source_path = Path(CONFIG.paths.SOURCE_DIR)
             os_subdir = get_os_subdir()
-            CONFIG.paths.WORK_DIR = str(source_path.parent / "photo_dedup" / os_subdir)
+            CONFIG.paths.WORK_DIR = str(source_path.parent / "photo_stack_finder" / os_subdir)
 
         # Create work directory if it doesn't exist
         CONFIG.paths.work_dir.mkdir(parents=True, exist_ok=True)
@@ -483,6 +483,9 @@ class OrchestratorRunner:
         if "debug_mode" in config:
             CONFIG.processing.DEBUG_MODE = config["debug_mode"]
 
+        if "skip_byte_identical" in config:
+            CONFIG.processing.SKIP_BYTE_IDENTICAL = config["skip_byte_identical"]
+
         # Update gate thresholds if provided
         if config.get("gate_thresholds"):
             assert CONFIG.processing.GATE_THRESHOLDS is not None

orchestrator/pipeline_builder.py

@@ -1,126 +1,126 @@
-"""Pipeline builder with automatic stage and channel registration.
-
-Provides a context manager that enables declarative pipeline construction:
-- Stages created within the context auto-register with the graph
-- Channels created within the context auto-register edges
-- Graph validation happens automatically on context exit
-- Execution order is computed automatically
-- PipelineOrchestrator is created ready to execute
-
-Usage:
-    with PipelineBuilder() as builder:
-        # Stages and channels auto-register during construction
-        stage1 = MyStage(path1, "stage1")
-        stage2 = MyStage(path2, "stage2")
-        Channel(stage1.output_o, stage2.input_i)
-
-    # After context exit, builder.orchestrator is ready
-    builder.orchestrator.execute()
-
-Architecture:
-- Uses graph_context module for auto-registration
-- Context manager pattern provides explicit scoping
-- Validates graph structure on exit (fail-fast on errors)
-- Cleans up registration state even on exceptions
-"""
-
-from __future__ import annotations
-
-from typing import Any, Literal
-
-from utils import graph_context
-from utils.pipeline_graph import PipelineGraph
-
-from .pipeline_orchestrator import PipelineOrchestrator
-
-
-class PipelineBuilder:
-    """Context manager for building pipeline graphs with auto-registration.
-
-    Creates a scoped context where:
-    - PipelineStage instances automatically register with the graph
-    - Channel instances automatically register edges
-    - Graph validation happens on context exit
-    - Orchestrator is created and ready to execute
-
-    The builder uses the graph_context module to enable auto-registration.
-    This provides explicit scoping through the context manager while avoiding
-    manual registration calls.
-
-    Attributes:
-        graph: The PipelineGraph being constructed
-        orchestrator: The PipelineOrchestrator created on successful exit
-                      (None until __exit__ completes successfully)
-    """
-
-    def __init__(self) -> None:
-        """Initialize builder with empty graph.
-
-        The orchestrator is not created until __exit__ succeeds.
-        """
-        self.graph = PipelineGraph()
-        self.orchestrator: PipelineOrchestrator | None = None
-
-    def __enter__(self) -> PipelineBuilder:
-        """Enter context - enable auto-registration.
-
-        Sets the active graph context to enable stages and channels to
-        auto-register during construction.
-
-        Returns:
-            self for use in 'with' statement
-        """
-        graph_context.set_active_graph(self.graph)
-        return self
-
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: Any,
-    ) -> Literal[False]:
-        """Exit context - validate graph and create orchestrator.
-
-        Performs final graph validation and setup:
-        1. If no exception occurred during construction:
-           - Validates graph structure (cycles, connectivity, ports)
-           - Computes execution order (topological sort)
-           - Creates PipelineOrchestrator ready to execute
-
-        2. Always clears the active graph context (stops registration)
-
-        Args:
-            exc_type: Exception type (if raised in context)
-            exc_val: Exception value (if raised in context)
-            exc_tb: Exception traceback (if raised in context)
-
-        Returns:
-            False (never suppresses exceptions)
-
-        Raises:
-            ValueError: If graph validation fails (cycles, disconnected components,
-                       unbound ports, etc.)
-
-        Note:
-            The orchestrator is only created if no exception occurred during
-            construction AND validation succeeds. Check if builder.orchestrator
-            is not None before using.
-        """
-        try:
-            # Only validate and create orchestrator if construction succeeded
-            if exc_type is None:
-                # Validate graph structure (raises ValueError on failure)
-                self.graph.validate()
-
-                # Compute execution order (topological sort)
-                self.graph.compute_execution_order()
-
-                # Create orchestrator ready to execute
-                self.orchestrator = PipelineOrchestrator(self.graph)
-        finally:
-            # Always clear the active graph context to stop registration
-            # This ensures clean state even if validation fails or exceptions occur
-            graph_context.set_active_graph(None)
-
-        # Never suppress exceptions
-        return False
+"""Pipeline builder with automatic stage and channel registration.
+
+Provides a context manager that enables declarative pipeline construction:
+- Stages created within the context auto-register with the graph
+- Channels created within the context auto-register edges
+- Graph validation happens automatically on context exit
+- Execution order is computed automatically
+- PipelineOrchestrator is created ready to execute
+
+Usage:
+    with PipelineBuilder() as builder:
+        # Stages and channels auto-register during construction
+        stage1 = MyStage(path1, "stage1")
+        stage2 = MyStage(path2, "stage2")
+        Channel(stage1.output_o, stage2.input_i)
+
+    # After context exit, builder.orchestrator is ready
+    builder.orchestrator.execute()
+
+Architecture:
+- Uses graph_context module for auto-registration
+- Context manager pattern provides explicit scoping
+- Validates graph structure on exit (fail-fast on errors)
+- Cleans up registration state even on exceptions
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from utils import graph_context
+from utils.pipeline_graph import PipelineGraph
+
+from .pipeline_orchestrator import PipelineOrchestrator
+
+
+class PipelineBuilder:
+    """Context manager for building pipeline graphs with auto-registration.
+
+    Creates a scoped context where:
+    - PipelineStage instances automatically register with the graph
+    - Channel instances automatically register edges
+    - Graph validation happens on context exit
+    - Orchestrator is created and ready to execute
+
+    The builder uses the graph_context module to enable auto-registration.
+    This provides explicit scoping through the context manager while avoiding
+    manual registration calls.
+
+    Attributes:
+        graph: The PipelineGraph being constructed
+        orchestrator: The PipelineOrchestrator created on successful exit
+                      (None until __exit__ completes successfully)
+    """
+
+    def __init__(self) -> None:
+        """Initialize builder with empty graph.
+
+        The orchestrator is not created until __exit__ succeeds.
+        """
+        self.graph = PipelineGraph()
+        self.orchestrator: PipelineOrchestrator | None = None
+
+    def __enter__(self) -> PipelineBuilder:
+        """Enter context - enable auto-registration.
+
+        Sets the active graph context to enable stages and channels to
+        auto-register during construction.
+
+        Returns:
+            self for use in 'with' statement
+        """
+        graph_context.set_active_graph(self.graph)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> Literal[False]:
+        """Exit context - validate graph and create orchestrator.
+
+        Performs final graph validation and setup:
+        1. If no exception occurred during construction:
+           - Validates graph structure (cycles, connectivity, ports)
+           - Computes execution order (topological sort)
+           - Creates PipelineOrchestrator ready to execute
+
+        2. Always clears the active graph context (stops registration)
+
+        Args:
+            exc_type: Exception type (if raised in context)
+            exc_val: Exception value (if raised in context)
+            exc_tb: Exception traceback (if raised in context)
+
+        Returns:
+            False (never suppresses exceptions)
+
+        Raises:
+            ValueError: If graph validation fails (cycles, disconnected components,
+                       unbound ports, etc.)
+
+        Note:
+            The orchestrator is only created if no exception occurred during
+            construction AND validation succeeds. Check if builder.orchestrator
+            is not None before using.
+        """
+        try:
+            # Only validate and create orchestrator if construction succeeded
+            if exc_type is None:
+                # Validate graph structure (raises ValueError on failure)
+                self.graph.validate()
+
+                # Compute execution order (topological sort)
+                self.graph.compute_execution_order()
+
+                # Create orchestrator ready to execute
+                self.orchestrator = PipelineOrchestrator(self.graph)
+        finally:
+            # Always clear the active graph context to stop registration
+            # This ensures clean state even if validation fails or exceptions occur
+            graph_context.set_active_graph(None)
+
+        # Never suppress exceptions
+        return False