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

{photo_stack_finder-0.1.7.dist-info → photo_stack_finder-0.1.8.dist-info}/METADATA

@@ -1,18 +1,17 @@
 Metadata-Version: 2.4
 Name: photo-stack-finder
-Version: 0.1.7
-Summary: Photo deduplication using perceptual hashing and sequence detection
+Version: 0.1.8
+Summary: Photo organization and duplicate detection using perceptual hashing and sequence detection
 Author: Geoff Barrett
 Maintainer: Geoff Barrett
-License: AGPL-3.0-or-later
-Project-URL: Homepage, https://github.com/gbarrett28/photo_dedup
-Project-URL: Repository, https://github.com/gbarrett28/photo_dedup
-Project-URL: Issues, https://github.com/gbarrett28/photo_dedup/issues
-Project-URL: Discussions, https://github.com/gbarrett28/photo_dedup/discussions
-Keywords: photo,deduplication,perceptual-hashing,image-processing
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/gbarrett28/photo_stack_finder
+Project-URL: Repository, https://github.com/gbarrett28/photo_stack_finder
+Project-URL: Issues, https://github.com/gbarrett28/photo_stack_finder/issues
+Project-URL: Discussions, https://github.com/gbarrett28/photo_stack_finder/discussions
+Keywords: photo,organization,duplicate-detection,perceptual-hashing,image-processing
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: End Users/Desktop
-Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -54,7 +53,7 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Dynamic: license-file
 
-# Photo Dedup
+# Photo Stack Finder
 
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
@@ -92,20 +91,20 @@ You love Google Photos' daily memories and search features. But they're **clutte
 
 **The Deployment Problem:**
 
-You can't easily act on the duplicates Photo Dedup finds:
+You can't easily act on the duplicates Photo Stack Finder finds:
 - ❌ **Takeout → Delete All → Re-upload** loses face recognition training
 - ❌ **Not reliable enough** for automatic deletion
 - ❌ **Google doesn't support bulk delete** anyway
 - ❌ **Manual deletion** of thousands of photos is impractical
 
-**Photo Dedup's Real Value:**
+**Photo Stack Finder's Real Value:**
 
 1. **Immediate:** Identify duplicate photo stacks in your library
 2. **Analysis:** Understand how many duplicates you have and why
 3. **Advocacy:** Generate evidence for a Google Photos enhancement request
 4. **Future-ready:** Export stack definitions if/when Google adds stacking support
 
-**The Solution:** Photo Dedup intelligently finds **spatial duplicates** - all photos that originate from the **same source image** using multiple techniques:
+**The Solution:** Photo Stack Finder intelligently finds **spatial duplicates** - all photos that originate from the **same source image** using multiple techniques:
 - **Byte-identical detection** - Same file, different names/locations
 - **Perceptual hashing** - Different resolutions, crops, edits, or format conversions of the same photo
 - **Template similarity** - Hierarchical clustering to find versions of the same original
@@ -154,7 +153,7 @@ You can't easily act on the duplicates Photo Dedup finds:
 - JPEG + HEIC (same photo, different formats)
 - IMG_1234.jpg + IMG_1234(1).jpg (sync duplicates)
 
-**How Photo Dedup Helps:**
+**How Photo Stack Finder Helps:**
 
 1. **Proves it's solvable:** This tool finds the stacks - Google could do it natively
 2. **Quantifies the problem:** See how many duplicates you have
@@ -197,11 +196,11 @@ See **[GOOGLE_ENHANCEMENT_REQUEST.md](GOOGLE_ENHANCEMENT_REQUEST.md)** for how t
 
 ```bash
 # Install directly from GitHub
-pip install git+https://github.com/gbarrett28/photo_dedup.git
+pip install git+https://github.com/gbarrett28/photo_stack_finder.git
 
 # Or clone and install in development mode
-git clone https://github.com/gbarrett28/photo_dedup.git
-cd photo_dedup
+git clone https://github.com/gbarrett28/photo_stack_finder.git
+cd photo_stack_finder
 pip install -e .
 ```
 
@@ -209,8 +208,8 @@ pip install -e .
 
 ```bash
 # Clone the repository
-git clone https://github.com/gbarrett28/photo_dedup.git
-cd photo_dedup
+git clone https://github.com/gbarrett28/photo_stack_finder.git
+cd photo_stack_finder
 
 # Create virtual environment
 python -m venv .venv
@@ -227,7 +226,7 @@ pip install -e ".[dev]"  # Install with development tools
 
 ```bash
 # After pip installation, simply run:
-photo-dedup
+photo-stack-finder
 
 # Or if running from source:
 cd src/scripts
@@ -301,7 +300,7 @@ Archived implementation plans, test strategies, and status reports are in **[doc
 ## Project Structure
 
 ```
-photo_dedup/
+photo_stack_finder/
 ├── src/
 │   ├── utils/              # Pipeline stages and utilities
 │   ├── photo_compare/      # Image comparison algorithms
@@ -392,7 +391,7 @@ This software is licensed under AGPL v3, which means:
 - ✅ **Network use requires sharing source** (even SaaS deployments)
 - 💼 **Commercial licensing available** for proprietary use
 
-💼 **Commercial licensing:** Contact via [GitHub Discussions](https://github.com/gbarrett28/photo_dedup/discussions)
+💼 **Commercial licensing:** Contact via [GitHub Discussions](https://github.com/gbarrett28/photo_stack_finder/discussions)
 
 📄 **See [LICENSE](LICENSE) for full legal text**
 📖 **See [LICENSING.md](LICENSING.md) for usage examples and FAQ**

photo_stack_finder-0.1.8.dist-info/RECORD

@@ -0,0 +1,75 @@
+orchestrator/__init__.py,sha256=PL9kksVIKleMuDzY_XqjJSfMWXTQKbvug2D7B828UUA,1315
+orchestrator/app.py,sha256=QV93njSDXRQR22fWy-QC7uxnCyyWeSCB__SzwM-sS9o,34257
+orchestrator/build_pipeline.py,sha256=CrQxY1k_sWanwOB4AaKmf8N2n9N9hIICU9vDcsCB0SI,4481
+orchestrator/orchestrator_runner.py,sha256=VlaXfj26BfD6QMmdravL3KB6HX_GbMsYkuy_vKK7F4s,20262
+orchestrator/pipeline_builder.py,sha256=0cZRyceoWt8gUjTCdmO6Eo88NwJIH8LvYbd8LpAxkIQ,4549
+orchestrator/pipeline_orchestrator.py,sha256=ouAnxPZ86vkzfsc_T1v0cL6sFcBHEluM6JarYdQUfIU,25328
+orchestrator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orchestrator/review_persistence.py,sha256=YJh6nhvs8AzuucOw0yRm3yyKc-IrBND686zIqcfdzqw,5751
+orchestrator/static/favicon.svg,sha256=TVNER-nLkPBBb9lZRaruak9jvyXyyfIKgyD2koQcyqk,622
+orchestrator/static/orchestrator.css,sha256=FFo_jgobZsTp0dT-kE-WAphRslX-ube-9jLwvRRmCRU,11672
+orchestrator/static/orchestrator.html,sha256=hNYOrmXEX0RcxNkhz8iP96wSmNyYL6K6SaNd1CWo_50,13963
+orchestrator/static/orchestrator.js,sha256=IKFQT5gg6r9sxcD5z8NZQNJIYEtvYO_UyaSEEN3DI9o,32512
+orchestrator/static/review_common.js,sha256=t8-AI4ohQbtqSC1iWvR5x0FNlwIxl8gVO2qZsI-VtnI,5875
+orchestrator/static/review_identical.html,sha256=Pq8TYbDSBbajC3p_XvlIOC1lbv0eJN_TcymGUw1lDE8,31487
+orchestrator/static/review_sequences.html,sha256=oEWRtcMfEvu09F3r-hw8rRfECjcE48BHtht2CdGlw3E,54681
+overlap_metrics/__init__.py,sha256=9RbbN6RoFBX4JdVHBTmh2WGG2p94U8th-uoG52qztoY,11184
+overlap_metrics/config.py,sha256=U7i1MbxHGWHjod-zNlx2Aptl2yJzCzTCo5_2a1LAExs,3832
+overlap_metrics/core.py,sha256=LiF-Ti6l0GrwxySzwxY2xwRBjJxC0brQf1e9yS8HiRA,9372
+overlap_metrics/estimators.py,sha256=9v5BeCCJph_d6JdSN6x0D9NbrukCNx71a5K8Q1oBNsk,10741
+overlap_metrics/metrics.py,sha256=Rvk4DJFWM4m7NrkP22LUE38I-A_pA_ONiXM3GjJ05jY,9873
+overlap_metrics/registry.py,sha256=GZOs0gNCKPwUt60tJ7td6pLZozDstDzoIlxjNaQCRSQ,3552
+overlap_metrics/utils.py,sha256=IICoLUy08AnEsMLqxRG7zftlBSmRvqYiSrg2kwK2S0Q,4521
+photo_compare/__init__.py,sha256=0lsL76bUIomc_kdy_AFY7irsGcBfqI8r7IO8lYYYg88,4876
+photo_compare/base.py,sha256=YsLim2GMB_oLH4GgeMYfW77kiEuonUEMoIMzJ8G3hnM,9356
+photo_compare/config.py,sha256=16f32Fh-yLGrZuTudqYMrb0hDWHDbkYtgDvm3sR61Zw,7556
+photo_compare/distance.py,sha256=Y1gW-pl6PUqtvsRTph4HhXyg_xXmj_IlRKEk2hZ6tg8,566
+photo_compare/feature_methods.py,sha256=wjplbd9Qd1oYenQsVDoGXvUnrPTqiBEDsSihP4o2WSA,6904
+photo_compare/file_hash.py,sha256=5IDCQlMK8qIvZF4M_w9Wr53Q7TSfoHg79ENnVjiH1pc,977
+photo_compare/hash_methods.py,sha256=mRzbvPLpnbtXKcrIDyMBb8DWgjwE220ToJUD1ed4zmc,3684
+photo_compare/histogram_methods.py,sha256=G20hOiHJi_LEII5x1_ZgU-FnZ8lVyENQc-LSsZAg-MU,5018
+photo_compare/pixel_methods.py,sha256=3tUZ0ZR6CqKGJg2YOn-wMEoE0LWMJ6113n1q1lyeJZE,2363
+photo_compare/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+photo_compare/structural_methods.py,sha256=nimULDnzb98cShv5-MM8sumFGYnpQv-bxAF_X5NMq1o,4255
+photo_compare/types.py,sha256=PyA-ydJcTJwHMtaFXpJwe73GwTBwb9I9odc90XrbkKU,971
+photo_stack_finder-0.1.8.dist-info/licenses/LICENSE,sha256=bmBV3PYoSFRs600gmAehqmuaIZIVUl8kGQoZWhapVnM,1468
+scripts/orchestrate.py,sha256=HOGDxrMDCtCofj3l_ryuGunJytfKKISUuGC7GcSKs50,9287
+utils/__init__.py,sha256=HBnCM-7JniIigj-NctrXV9UXAlZNRMijf_GdNDzlBkY,5196
+utils/base_pipeline_stage.py,sha256=xPVFt8RjNqI6f80wshICzyShiP0kQbQxNgDUnmDpE6Y,6369
+utils/base_ports.py,sha256=6wHfAdvTz5oB1hLWrs4lMQB-mzsOe6T4v0JR9_aAW3A,5240
+utils/benchmark_utils.py,sha256=RdlCpKdrZXFOUUc5rXQ8yL8KcgS09kZi-bU37nqvzgg,30026
+utils/channel.py,sha256=f2njTAs6bCtYNui31yIrXrtNN1CK0E86M7wUJiTP768,2586
+utils/comparison_gates.py,sha256=nH5UBWbFpLPCLVyON0veiH_KgtBrVBayIgm3abbX_s0,23794
+utils/compute_benchmarks.py,sha256=tienoHmMB2iQgQLZRtmocj1jc40XYqlbrDSVGyxViTA,13868
+utils/compute_identical.py,sha256=OVzs8iDAB2oeV3rH0o6vwHqHbFUU443civu6XAjjxcg,10373
+utils/compute_indices.py,sha256=W3MvToDHgrGtN-_Q-LaWNXQ7VEJCJiODRsfx7sPUWnk,9304
+utils/compute_perceptual_hash.py,sha256=EHwDbnXd5JCk_vMQPU0F59SQEvLpIIz_qO5h7im0HRQ,4915
+utils/compute_perceptual_match.py,sha256=hIZkA7vtFoHvOg3YbEwioEx0XZxxk7VIzFI6nS-I680,10258
+utils/compute_sha_bins.py,sha256=kSAHM-5gtZ6LA8daebUoX1btlJ2o2QVNC0CdIvU-_Xg,7019
+utils/compute_template_similarity.py,sha256=YU4IgQdinp7X7Vv63oz6K7rfGOke3TRTUJ-EBxbxloA,21449
+utils/compute_templates.py,sha256=yVYfmaJlfOgeDJ2tdJ5iLd-n4SnPbjepl7eUBP3N1Js,5079
+utils/compute_versions.py,sha256=GnvuJ4Bv_u3qlyDclRJ9H3dQ62nmfLCs5CAe2bJVyS4,20337
+utils/config.py,sha256=R8xy9RLZAliLY9J8ZKkQABQX6KugfuFum7L5EwagEZA,15660
+utils/data_io.py,sha256=MTkLdWYFTi6qfuUNKJR9JJ2d1gL-Hg7NG8ws-nByepk,2412
+utils/graph_context.py,sha256=5vIiSOkzQ1s1vVliWYyjSy7NPvnMEDvrH9aqsivgneM,1558
+utils/logger.py,sha256=vgKgsAAcqb-0dlOYdRHtsnBTqbuHOVTU-9h35plDgqU,1887
+utils/models.py,sha256=TZkGh7AYHp36yJy5i06iSDdQiJh7Nq5GmGx1vpAnkGA,15300
+utils/photo_file.py,sha256=IHuo_x6VbLeHfl2QDtkDAO1xtaObCMolt2OrBioNtdY,20679
+utils/pipeline_graph.py,sha256=A39fIj647_IIS43tubvNROFZN2K_oj6hgkf3dG9H6lc,13262
+utils/pipeline_stage.py,sha256=vuEUw9CCkIQzqS0k3Uy_Ez2XYCxGOgIXwDCStfgyLXQ,16978
+utils/plot_helpers.py,sha256=Q1M1o8QndLhMXvNaxx-0bnusvQYGkU_2GyC6jsB1iNI,4451
+utils/ports.py,sha256=JlwlLW0ViwhofeYWrQ_clboZkM4x5hnsg5GkefyNJgs,4318
+utils/progress.py,sha256=q7M4xTYowsX8T_fXbDkJDzbcjQ7qhE_ayCZawEnbc3c,14936
+utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+utils/report_builder.py,sha256=okRhMUAbV1540eS8epyZ97Lkalq1a8JFOhM4MXXBpzA,3940
+utils/review_types.py,sha256=PY08IioeOSIYKvxCZlcbyyvbYLPVG8hzXFbUCBp_Me4,1713
+utils/review_utils.py,sha256=-mGRFF7s6fde67BDxnwPJNogw0bQeVAEw6ztPYMr6xU,8520
+utils/sequence.py,sha256=CPPn4CWQb16iAhVVswknwBUl0gTEHzNJHCvSOV6Hevk,34751
+utils/sequence_clustering.py,sha256=MuUSWbQ-7W6PJhbdFKrwPUBHNBe2JNNv2Atvgg0_uEg,5754
+utils/template.py,sha256=zB5JZOc4HRylDrj1u7kV5NcxsbLYy2ZjeLwtVQcM7lA,1704
+utils/template_parsing.py,sha256=Li1kseXrnjPf_KiIyae7iMEZWQg60bQIA8zOta1POfE,2460
+photo_stack_finder-0.1.8.dist-info/METADATA,sha256=THw8oGEoaRtvmxmaQ-qx5tAOLGDBJQ_xxnfymePU_50,17193
+photo_stack_finder-0.1.8.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+photo_stack_finder-0.1.8.dist-info/entry_points.txt,sha256=ZHWJIeylUGZYa_8Rjt3QxbWiCCVZZx3FQShTNg91zNQ,64
+photo_stack_finder-0.1.8.dist-info/top_level.txt,sha256=VmNqTeDiNgCj3LZJICyRF2Uc4buZQ7LxgSob-BoImk0,57
+photo_stack_finder-0.1.8.dist-info/RECORD,,

scripts/orchestrate.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-"""Photo Deduplication Orchestrator - Web Interface Entry Point.
+"""Photo Stack Finderlication Orchestrator - Web Interface Entry Point.
 
-This provides a web-based interface for the photo deduplication pipeline.
+This provides a web-based interface for the photo stack finding pipeline.
 
 Usage:
     python orchestrate.py
@@ -38,10 +38,10 @@ def build_arg_parser() -> argparse.ArgumentParser:
         Configured ArgumentParser instance
     """
     parser = argparse.ArgumentParser(
-        description="Photo Dedup Orchestrator - Web Interface",
+        description="Photo Stack Finder Orchestrator - Web Interface",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
-This is a web interface for the photo deduplication pipeline.
+This is a web interface for the photo stack finding pipeline.
 
 For the web interface, just run:
   - python orchestrate.py
@@ -277,11 +277,13 @@ def main() -> None:
 
     # Add platform-specific instructions
     if is_linux:
-        lines.extend([
-            "To access the web interface:",
-            f"  Open your browser to: {url}",
-            "",
-        ])
+        lines.extend(
+            [
+                "To access the web interface:",
+                f"  Open your browser to: {url}",
+                "",
+            ]
+        )
 
     lines.append("Press Ctrl+C to stop the server")
     print_banner("", lines)
@@ -302,7 +304,7 @@ def main() -> None:
 
     # Start server
     try:
-        uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+        uvicorn.run(app, host=args.host, port=args.port, log_level="info", access_log=False)
     except KeyboardInterrupt:
         print("\n🛑 Server stopped by user")
     except Exception:

utils/__init__.py

@@ -1,4 +1,4 @@
-"""Utilities for photo deduplication."""
+"""Utilities for photo stack finding."""
 
 from __future__ import annotations
 
@@ -26,7 +26,6 @@ from .compute_perceptual_hash import ComputePerceptualHash
 from .compute_perceptual_match import ComputePerceptualMatch
 from .compute_sha_bins import ComputeShaBins
 from .compute_template_similarity import ComputeTemplateSimilarity
-from .compute_templates import ComputeTemplates
 from .compute_versions import ComputeVersions
 
 # Config module exports
@@ -109,6 +108,9 @@ from .template import (
     partial_format,
 )
 
+# Template parsing module exports (extract_template not exported - internal use only)
+# INDEX_T exported via sequence module
+
 __all__ = [
     # Config
     "CONFIG",
@@ -136,7 +138,6 @@ __all__ = [
     "ComputePerceptualMatch",
     "ComputeShaBins",
     "ComputeTemplateSimilarity",
-    "ComputeTemplates",
     "ComputeVersions",
     # Configuration
     "Config",

utils/base_pipeline_stage.py

@@ -1,171 +1,171 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from collections.abc import Callable
-from pathlib import Path
-
-from .base_ports import StageProtocol
-from .models import IdenticalGroup, ReviewType, SequenceGroup
-from .ports import InputPort
-from .progress import ProgressInfo, ProgressTracker
-
-
-class BasePipelineStage(ABC, StageProtocol):
-    """Base class for polymorphic PipelineStage for use in lists of pipeline stages."""
-
-    path: Path
-    stage_name: str
-    stage_id: int | None
-    description: str
-    sequence_review_result: list[SequenceGroup]
-    identical_review_result: list[IdenticalGroup]
-    _progress_tracker: ProgressTracker | None
-    _phase_callback: Callable[[str], None] | None  # Called by run() to notify phase changes
-    ref_photos_init: int | None
-    ref_photos_final: int | None
-    ref_seqs_init: int | None
-    ref_seqs_final: int | None
-    total_photos: int | None  # Total photos including duplicates (invariant - should never change)
-
-    def __init__(
-        self,
-        path: Path,
-        stage_name: str,
-    ):
-        """Initialize pipeline stage with output path and name.
-
-        Args:
-            path: Path where stage results will be cached
-            stage_name: Human-readable name for progress tracking
-        """
-        self.path = path
-        self.stage_name = stage_name
-        self.stage_id = None  # Set by PipelineGraph.compute_execution_order()
-        self.description = ""  # Override in subclasses for UI tooltips
-        self.sequence_review_result = []  # Pre-computed sequence review data (built during run())
-        self.identical_review_result = []  # Pre-computed identical review data (built during run())  # Pre-computed identical review data (built during run())
-        self._progress_tracker = None
-        self._phase_callback = None  # Set by orchestrator before calling run()
-
-        self.ref_photos_init = None
-        self.ref_photos_final = None
-        self.ref_seqs_init = None
-        self.ref_seqs_final = None
-        self.total_photos = None
-
-        # Performance metrics (set after stage completes)
-        self.elapsed_seconds: float | None = None
-        self.throughput: float | None = None  # items per second
-
-    def get_ref_photo_count(self) -> int | None:
-        """Get count of reference photos after stage has run.
-
-        Returns:
-            Number of reference photos after stage has run (None if there are none or the stage has not run).
-        """
-        return self.ref_photos_final
-
-    def get_ref_sequence_count(self) -> int | None:
-        """Get count of reference sequences after stage has run.
-
-        Returns:
-            Number of reference sequences after stage has run (None if there are none or the stage has not run).
-        """
-        return self.ref_seqs_final
-
-    @abstractmethod
-    def run(self) -> None:
-        """Execute pipeline stage - must be implemented by subclass."""
-        ...
-
-    @abstractmethod
-    def finalise(self) -> None:
-        """Hook to call at the end of run - must be implemented by subclass."""
-        ...
-
-    @abstractmethod
-    def needs_review(self) -> ReviewType:
-        """Discover what type of review this stage produces.
-
-        This allows the orchestrator to dynamically discover which stages
-        produce reviewable output without hard-coding stage names.
-
-        Returns:
-            - "none": No reviewable output (default)
-            - "photos": Produces photo groups (byte-identical duplicates)
-            - "sequences": Produces sequence groups (similar sequences)
-        """
-        ...
-
-    @abstractmethod
-    def has_review_data(self) -> bool:
-        """Check if review data is ACTUALLY available for this stage.
-
-        Checks three conditions:
-        1. Stage has completed (cache file exists)
-        2. Stage is capable of producing review data (needs_review() != "none")
-        3. Review data actually exists (review lists not empty)
-
-        Returns:
-            True if stage has completed and has reviewable data available
-        """
-        ...
-
-    def get_progress(self) -> ProgressInfo | None:
-        """Get current progress information for UI polling.
-
-        Returns:
-            ProgressInfo with formatted progress data if stage is currently executing,
-            None if stage is not running
-
-        Note:
-            This method is called by the orchestrator during execution to poll
-            progress for UI updates.
-        """
-        # Direct access with combined check for type narrowing
-        if self._progress_tracker is None:
-            return None
-        return self._progress_tracker.get_snapshot()
-
-    def get_cache_timestamp(self) -> float:
-        """Get the modification time of the cache file.
-
-        Returns:
-            Cache file's mtime (seconds since epoch), or raises RuntimeError if cache doesn't exist
-        """
-        if self.path.exists():
-            mtime = self.path.stat().st_mtime
-            if mtime is None:
-                raise RuntimeError("mtime is None for existing file")
-            return mtime
-        raise RuntimeError(f"{self.stage_name} get_cache_timestamp called before cache file has been created")
-
-    def _cache_is_valid(self) -> bool:
-        """Check if cache exists and is newer than all input port dependencies.
-
-        Uses isinstance() check on __dict__ items to avoid triggering property getters
-        and causing errors when stages haven't run yet.
-
-        Returns:
-            True if cache is valid and can be used, False otherwise
-        """
-        if not self.path.exists():
-            return False
-
-        cache_mtime = self.get_cache_timestamp()
-
-        # Check if any input port dependency is newer than our cache
-        # Use __dict__ to avoid triggering property getters
-        for attr_value in self.__dict__.values():
-            # Check for InputPort type directly
-            if isinstance(attr_value, InputPort) and attr_value.is_bound():
-                upstream_timestamp = attr_value.timestamp()
-
-                if upstream_timestamp is None:
-                    raise ValueError(f"{self.__class__.__name__} getting None timestamp from upstream")
-
-                if upstream_timestamp > cache_mtime:
-                    # Upstream data is newer, our cache is stale
-                    return False
-
-        return True
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from pathlib import Path
+
+from .base_ports import StageProtocol
+from .models import IdenticalGroup, ReviewType, SequenceGroup
+from .ports import InputPort
+from .progress import ProgressInfo, ProgressTracker
+
+
+class BasePipelineStage(ABC, StageProtocol):
+    """Base class for polymorphic PipelineStage for use in lists of pipeline stages."""
+
+    path: Path
+    stage_name: str
+    stage_id: int | None
+    description: str
+    sequence_review_result: list[SequenceGroup]
+    identical_review_result: list[IdenticalGroup]
+    _progress_tracker: ProgressTracker | None
+    _phase_callback: Callable[[str], None] | None  # Called by run() to notify phase changes
+    ref_photos_init: int | None
+    ref_photos_final: int | None
+    ref_seqs_init: int | None
+    ref_seqs_final: int | None
+    total_photos: int | None  # Total photos including duplicates (invariant - should never change)
+
+    def __init__(
+        self,
+        path: Path,
+        stage_name: str,
+    ):
+        """Initialize pipeline stage with output path and name.
+
+        Args:
+            path: Path where stage results will be cached
+            stage_name: Human-readable name for progress tracking
+        """
+        self.path = path
+        self.stage_name = stage_name
+        self.stage_id = None  # Set by PipelineGraph.compute_execution_order()
+        self.description = ""  # Override in subclasses for UI tooltips
+        self.sequence_review_result = []  # Pre-computed sequence review data (built during run())
+        self.identical_review_result = []  # Pre-computed identical review data (built during run())  # Pre-computed identical review data (built during run())
+        self._progress_tracker = None
+        self._phase_callback = None  # Set by orchestrator before calling run()
+
+        self.ref_photos_init = None
+        self.ref_photos_final = None
+        self.ref_seqs_init = None
+        self.ref_seqs_final = None
+        self.total_photos = None
+
+        # Performance metrics (set after stage completes)
+        self.elapsed_seconds: float | None = None
+        self.throughput: float | None = None  # items per second
+
+    def get_ref_photo_count(self) -> int | None:
+        """Get count of reference photos after stage has run.
+
+        Returns:
+            Number of reference photos after stage has run (None if there are none or the stage has not run).
+        """
+        return self.ref_photos_final
+
+    def get_ref_sequence_count(self) -> int | None:
+        """Get count of reference sequences after stage has run.
+
+        Returns:
+            Number of reference sequences after stage has run (None if there are none or the stage has not run).
+        """
+        return self.ref_seqs_final
+
+    @abstractmethod
+    def run(self) -> None:
+        """Execute pipeline stage - must be implemented by subclass."""
+        ...
+
+    @abstractmethod
+    def finalise(self) -> None:
+        """Hook to call at the end of run - must be implemented by subclass."""
+        ...
+
+    @abstractmethod
+    def needs_review(self) -> ReviewType:
+        """Discover what type of review this stage produces.
+
+        This allows the orchestrator to dynamically discover which stages
+        produce reviewable output without hard-coding stage names.
+
+        Returns:
+            - "none": No reviewable output (default)
+            - "photos": Produces photo groups (byte-identical duplicates)
+            - "sequences": Produces sequence groups (similar sequences)
+        """
+        ...
+
+    @abstractmethod
+    def has_review_data(self) -> bool:
+        """Check if review data is ACTUALLY available for this stage.
+
+        Checks three conditions:
+        1. Stage has completed (cache file exists)
+        2. Stage is capable of producing review data (needs_review() != "none")
+        3. Review data actually exists (review lists not empty)
+
+        Returns:
+            True if stage has completed and has reviewable data available
+        """
+        ...
+
+    def get_progress(self) -> ProgressInfo | None:
+        """Get current progress information for UI polling.
+
+        Returns:
+            ProgressInfo with formatted progress data if stage is currently executing,
+            None if stage is not running
+
+        Note:
+            This method is called by the orchestrator during execution to poll
+            progress for UI updates.
+        """
+        # Direct access with combined check for type narrowing
+        if self._progress_tracker is None:
+            return None
+        return self._progress_tracker.get_snapshot()
+
+    def get_cache_timestamp(self) -> float:
+        """Get the modification time of the cache file.
+
+        Returns:
+            Cache file's mtime (seconds since epoch), or raises RuntimeError if cache doesn't exist
+        """
+        if self.path.exists():
+            mtime = self.path.stat().st_mtime
+            if mtime is None:
+                raise RuntimeError("mtime is None for existing file")
+            return mtime
+        raise RuntimeError(f"{self.stage_name} get_cache_timestamp called before cache file has been created")
+
+    def _cache_is_valid(self) -> bool:
+        """Check if cache exists and is newer than all input port dependencies.
+
+        Uses isinstance() check on __dict__ items to avoid triggering property getters
+        and causing errors when stages haven't run yet.
+
+        Returns:
+            True if cache is valid and can be used, False otherwise
+        """
+        if not self.path.exists():
+            return False
+
+        cache_mtime = self.get_cache_timestamp()
+
+        # Check if any input port dependency is newer than our cache
+        # Use __dict__ to avoid triggering property getters
+        for attr_value in self.__dict__.values():
+            # Check for InputPort type directly
+            if isinstance(attr_value, InputPort) and attr_value.is_bound():
+                upstream_timestamp = attr_value.timestamp()
+
+                if upstream_timestamp is None:
+                    raise ValueError(f"{self.__class__.__name__} getting None timestamp from upstream")
+
+                if upstream_timestamp > cache_mtime:
+                    # Upstream data is newer, our cache is stale
+                    return False
+
+        return True