pdf-file-renamer 0.4.2__py3-none-any.whl

pdf_file_renamer-0.4.2.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: pdf-file-renamer
+Version: 0.4.2
+Summary: Intelligent PDF renaming using LLMs
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pydantic-ai>=1.0.17
+Requires-Dist: pydantic-settings>=2.7.1
+Requires-Dist: pymupdf>=1.26.5
+Requires-Dist: docling-parse>=2.0.0
+Requires-Dist: docling-core>=2.0.0
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typer>=0.19.2
+Requires-Dist: tenacity>=9.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.4; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.25.2; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: ruff>=0.9.1; extra == "dev"
+Requires-Dist: mypy>=1.14.1; extra == "dev"
+Dynamic: license-file
+
+# PDF Renamer
+
+[![PyPI version](https://img.shields.io/pypi/v/pdf-file-renamer.svg)](https://pypi.org/project/pdf-file-renamer/)
+[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![uv](https://img.shields.io/badge/uv-0.5+-orange.svg)](https://docs.astral.sh/uv/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![pydantic-ai](https://img.shields.io/badge/pydantic--ai-1.0+-green.svg)](https://ai.pydantic.dev/)
+[![GitHub](https://img.shields.io/badge/github-nostoslabs%2Fpdf--renamer-blue?logo=github)](https://github.com/nostoslabs/pdf-renamer)
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/nostoslabs/pdf-renamer)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Intelligent PDF file renaming using LLMs. This tool analyzes PDF content and metadata to suggest descriptive, standardized filenames.
+
+> 🚀 Works with **OpenAI**, **Ollama**, **LM Studio**, and any OpenAI-compatible API
+
+## Features
+
+- **Advanced PDF parsing** using docling-parse for better structure-aware extraction
+- **OCR fallback** for scanned PDFs with low text content
+- **Smart LLM prompting** with multi-pass analysis for improved accuracy
+- Suggests filenames in format: `Author-Topic-Year.pdf`
+- Dry-run mode to preview changes before applying
+- **Enhanced interactive mode** with options to accept, manually edit, retry, or skip each file
+- **Live progress display** with concurrent processing for speed
+- **Configurable concurrency** limits for API calls and PDF extraction
+- Batch processing of multiple PDFs with optional output directory
+
+## Installation
+
+### Quick Start (No Installation Required)
+
+```bash
+# Run directly with uvx
+uvx pdf-renamer --dry-run /path/to/pdfs
+```
+
+### Install from PyPI
+
+```bash
+# Using pip
+pip install pdf-file-renamer
+
+# Using uv
+uv pip install pdf-file-renamer
+```
+
+### Install from Source
+
+```bash
+# Clone and install
+git clone https://github.com/nostoslabs/pdf-renamer.git
+cd pdf-renamer
+uv sync
+```
+
+## Configuration
+
+Configure your LLM provider:
+
+**Option A: OpenAI (Cloud)**
+```bash
+cp .env.example .env
+# Edit .env and add your OPENAI_API_KEY
+```
+
+**Option B: Ollama or other local models**
+```bash
+# No API key needed for local models
+# Either set LLM_BASE_URL in .env or use --url flag
+echo "LLM_BASE_URL=http://patmos:11434/v1" > .env
+```
+
+## Usage
+
+### Quick Start
+
+```bash
+# Preview renames (dry-run mode)
+pdf-renamer --dry-run /path/to/pdf/directory
+
+# Actually rename files
+pdf-renamer --no-dry-run /path/to/pdf/directory
+
+# Interactive mode - review each file
+pdf-renamer --interactive --no-dry-run /path/to/pdf/directory
+```
+
+### Using uvx (No Installation)
+
+```bash
+# Run directly without installing
+uvx pdf-renamer --dry-run /path/to/pdfs
+
+# Run from GitHub
+uvx https://github.com/nostoslabs/pdf-renamer --dry-run /path/to/pdfs
+```
+
+### Options
+
+- `--dry-run/--no-dry-run`: Show suggestions without renaming (default: True)
+- `--interactive, -i`: Interactive mode with rich options:
+  - **Accept** - Use the suggested filename
+  - **Edit** - Manually modify the filename
+  - **Retry** - Ask the LLM to generate a new suggestion
+  - **Skip** - Skip this file and move to the next
+- `--model`: Model to use (default: llama3.2, works with any OpenAI-compatible API)
+- `--url`: Custom base URL for OpenAI-compatible APIs (default: http://localhost:11434/v1)
+- `--pattern`: Glob pattern for files (default: *.pdf)
+- `--output-dir, -o`: Move renamed files to a different directory
+- `--max-concurrent-api`: Maximum concurrent API calls (default: 3)
+- `--max-concurrent-pdf`: Maximum concurrent PDF extractions (default: 10)
+
+### Examples
+
+**Using OpenAI:**
+```bash
+# Preview all PDFs in current directory
+uvx pdf-renamer --dry-run .
+
+# Rename PDFs in specific directory
+uvx pdf-renamer --no-dry-run ~/Documents/Papers
+
+# Use a different OpenAI model
+uvx pdf-renamer --model gpt-4o --dry-run .
+```
+
+**Using Ollama (or other local models):**
+```bash
+# Using Ollama on patmos server with gemma model
+uvx pdf-renamer --url http://patmos:11434/v1 --model gemma3:latest --dry-run .
+
+# Using local Ollama with qwen model
+uvx pdf-renamer --url http://localhost:11434/v1 --model qwen2.5 --dry-run .
+
+# Set URL in environment and just use model flag
+export LLM_BASE_URL=http://patmos:11434/v1
+uvx pdf-renamer --model gemma3:latest --dry-run .
+```
+
+**Other examples:**
+```bash
+# Process only specific files
+uvx pdf-renamer --pattern "*2020*.pdf" --dry-run .
+
+# Interactive mode with local model
+uvx pdf-renamer --url http://patmos:11434/v1 --model gemma3:latest --interactive --no-dry-run .
+
+# Run directly from GitHub
+uvx https://github.com/nostoslabs/pdf-renamer --no-dry-run ~/Documents/Papers
+```
+
+## Interactive Mode
+
+When using `--interactive` mode, you'll be presented with each file one at a time with detailed options:
+
+```
+================================================================================
+Original: 2024-research-paper.pdf
+Suggested: Smith-Machine-Learning-Applications-2024.pdf
+Confidence: high
+Reasoning: Clear author and topic identified from abstract
+================================================================================
+
+Options:
+  y / yes / Enter - Accept suggested name
+  e / edit - Manually edit the filename
+  r / retry - Ask LLM to generate a new suggestion
+  n / no / skip - Skip this file
+
+What would you like to do? [y]:
+```
+
+This mode is perfect for:
+- **Reviewing suggestions** before applying them
+- **Fine-tuning filenames** that are close but not quite right
+- **Retrying** when the LLM suggestion isn't good enough
+- **Building confidence** in the tool before batch processing
+
+You can use interactive mode with `--dry-run` to preview without actually renaming files, or with `--no-dry-run` to apply changes immediately after confirmation.
+
+## How It Works
+
+1. **Extract**: Uses docling-parse to read first 5 pages with structure-aware parsing, falls back to PyMuPDF if needed
+2. **OCR**: Automatically applies OCR for scanned PDFs with minimal text
+3. **Metadata Enhancement**: Extracts focused hints (years, emails, author sections) to supplement unreliable PDF metadata
+4. **Analyze**: Sends full content excerpt to LLM with enhanced metadata and detailed extraction instructions
+5. **Multi-pass Review**: Low-confidence results trigger a second analysis pass with focused prompts
+6. **Suggest**: LLM returns filename in `Author-Topic-Year` format with confidence level and reasoning
+7. **Interactive Review** (optional): User can accept, edit, retry, or skip each suggestion
+8. **Rename**: Applies suggestions (if not in dry-run mode)
+
+## Cost Considerations
+
+**OpenAI:**
+- Uses `gpt-4o-mini` by default (very cost-effective)
+- Processes first ~4500 characters per PDF
+- Typical cost: ~$0.001-0.003 per PDF
+
+**Ollama/Local Models:**
+- Completely free (runs on your hardware)
+- Works with any Ollama model (llama3, qwen2.5, mistral, etc.)
+- Also compatible with LM Studio, vLLM, and other OpenAI-compatible endpoints
+
+## Filename Format
+
+The tool generates filenames in this format:
+- `Smith-Kalman-Filtering-Applications-2020.pdf`
+- `Adamy-Electronic-Warfare-Modeling-Techniques.pdf`
+- `Blair-Monopulse-Processing-Unresolved-Targets.pdf`
+
+Guidelines:
+- First author's last name
+- 3-6 word topic description (prioritizes clarity over brevity)
+- Year (if identifiable)
+- Hyphens between words
+- Target ~80 characters (can be longer if needed for clarity)

pdf_file_renamer-0.4.2.dist-info/RECORD

@@ -0,0 +1,26 @@
+pdf_file_renamer-0.4.2.dist-info/licenses/LICENSE,sha256=_w08V08WgoMpDMlGNlkIatC5QfQ_Ds_rXOBM8pl7ffE,1068
+pdf_renamer/__init__.py,sha256=3RvsqaTO80Ud1KZZdLL_Lh-HXxagncoqI4m6u3VL_UE,85
+pdf_renamer/main.py,sha256=5eTsrCQaotNwbdwJwandOlzrWODI73-L5mALHUIvqyw,140
+pdf_renamer/application/__init__.py,sha256=EebV66jsZjubnh6PSEeNGs0A_JGeYXFghzGLDQ92eco,348
+pdf_renamer/application/filename_service.py,sha256=Gk-nPnURsJYLDvoG_NZ4o_yHwAqK6bHU8kqzlev0XXM,2029
+pdf_renamer/application/pdf_rename_workflow.py,sha256=MEUmDR6bLRB-ncNgKk3ahIfsIIk3Gsw1048cId6pYv4,4710
+pdf_renamer/application/rename_service.py,sha256=rnScP2JwKMrIJcplFvxC0b2MOLzWqxpPKc3uDLHPjRI,2352
+pdf_renamer/domain/__init__.py,sha256=UPcXunsI30iFK9dupv2Fc_YDreT1tAqsYaGEAK9sJew,493
+pdf_renamer/domain/models.py,sha256=7S2ul3BoWi2aivWtmDa9LRlmeqURrGEV1sfSu8W6x5k,2246
+pdf_renamer/domain/ports.py,sha256=ecnpkFYB3259ZjaZaOVo1sjP8nXD3x1NGR6hN5nn3gc,2550
+pdf_renamer/infrastructure/__init__.py,sha256=CxBinDAuNm2X57-Y7XdXxVL6uHQXQqWpPrlznzu5_1M,182
+pdf_renamer/infrastructure/config.py,sha256=baNL5_6_NNiS50ZNdql7fDwQbeAwf6f58HGYIWFQxQQ,2464
+pdf_renamer/infrastructure/llm/__init__.py,sha256=evEhabaBshvekLO9DlAZvp-pQ_u03zYXqXaDfa9QUww,154
+pdf_renamer/infrastructure/llm/pydantic_ai_provider.py,sha256=FM2Sd3n3lltJC76afrem5QuuS8qApEma52YD-Y8K89Y,9207
+pdf_renamer/infrastructure/pdf/__init__.py,sha256=-WHYNLeBekm7jwIXRj4xpSIXyZz9olDiMIJLUjv2B-U,353
+pdf_renamer/infrastructure/pdf/composite.py,sha256=1tlZ_X9_KVY01GTr1Hg3x_Ag7g3g4ik6_8R0jip8Wx0,1791
+pdf_renamer/infrastructure/pdf/docling_extractor.py,sha256=7UamnbYFMgtD53oMqu1qKAq3FyQTQlq0Uw0k1sNzPw8,3964
+pdf_renamer/infrastructure/pdf/pymupdf_extractor.py,sha256=lwIPr9yhy2hZVnuvoLcZvmjYSzbTra0AyW59UvU7GgU,5455
+pdf_renamer/presentation/__init__.py,sha256=mxIxy8POUwewiMsmrOMVA8z9pe57lOghuwHZ5RAbMo4,201
+pdf_renamer/presentation/cli.py,sha256=ykZx22quR9ye-ui9bLrRinD7BSChjSbGTRsazCafo5s,7819
+pdf_renamer/presentation/formatters.py,sha256=ilUcXZ-7MpBlz7k7cqRAuixfkVT3cuD-pBcy5fsE2Qo,8514
+pdf_file_renamer-0.4.2.dist-info/METADATA,sha256=xSIAQrGaKmT2o2vOT5HlX6ILaTmDyYbn6P8YG8JtK8U,8668
+pdf_file_renamer-0.4.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdf_file_renamer-0.4.2.dist-info/entry_points.txt,sha256=IvW2oP2SRPv5qqFwDYBRCE53Q3JAyi_chbCo-0rdKQA,53
+pdf_file_renamer-0.4.2.dist-info/top_level.txt,sha256=CFtpWKQjLObHZIssi5I3q7FXfLJZWKpHo7uuAiJ0pVY,12
+pdf_file_renamer-0.4.2.dist-info/RECORD,,

pdf_file_renamer-0.4.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pdf_file_renamer-0.4.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdf-renamer = pdf_renamer.main:app

pdf_file_renamer-0.4.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nostos Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdf_file_renamer-0.4.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+pdf_renamer

pdf_renamer/__init__.py

@@ -0,0 +1,3 @@
+"""PDF Renamer - Intelligent PDF file renaming using LLMs."""
+
+__version__ = "0.4.2"

pdf_renamer/application/__init__.py

@@ -0,0 +1,7 @@
+"""Application layer - use cases and business logic orchestration."""
+
+from pdf_renamer.application.filename_service import FilenameService
+from pdf_renamer.application.pdf_rename_workflow import PDFRenameWorkflow
+from pdf_renamer.application.rename_service import RenameService
+
+__all__ = ["FilenameService", "PDFRenameWorkflow", "RenameService"]

pdf_renamer/application/filename_service.py

@@ -0,0 +1,70 @@
+"""Filename generation service - coordinates PDF extraction and LLM generation."""
+
+import re
+
+from pdf_renamer.domain.models import FilenameResult, PDFContent
+from pdf_renamer.domain.ports import FilenameGenerator, LLMProvider
+
+
+class FilenameService(FilenameGenerator):
+    """Service for generating filenames from PDF content."""
+
+    def __init__(self, llm_provider: LLMProvider) -> None:
+        """
+        Initialize the filename service.
+
+        Args:
+            llm_provider: LLM provider for filename generation
+        """
+        self.llm_provider = llm_provider
+
+    async def generate(self, original_filename: str, content: PDFContent) -> FilenameResult:
+        """
+        Generate a filename suggestion based on PDF content.
+
+        Args:
+            original_filename: Current filename
+            content: Extracted PDF content
+
+        Returns:
+            FilenameResult with suggestion
+        """
+        # Convert metadata to dictionary
+        metadata_dict = content.metadata.to_dict()
+
+        # Generate filename using LLM
+        result = await self.llm_provider.generate_filename(
+            original_filename=original_filename,
+            text_excerpt=content.text,
+            metadata_dict=metadata_dict,
+        )
+
+        # Sanitize the generated filename
+        result.filename = self.sanitize(result.filename)
+
+        return result
+
+    def sanitize(self, filename: str) -> str:
+        """
+        Sanitize a filename to be filesystem-safe.
+
+        Args:
+            filename: Raw filename
+
+        Returns:
+            Sanitized filename
+        """
+        # Remove or replace invalid characters
+        filename = re.sub(r'[<>:"/\\|?*]', "", filename)
+
+        # Replace multiple spaces/hyphens with single hyphen
+        filename = re.sub(r"[\s\-]+", "-", filename)
+
+        # Remove leading/trailing hyphens
+        filename = filename.strip("-")
+
+        # Limit length
+        if len(filename) > 100:
+            filename = filename[:100].rstrip("-")
+
+        return filename

pdf_renamer/application/pdf_rename_workflow.py

@@ -0,0 +1,144 @@
+"""PDF rename workflow - orchestrates the complete process."""
+
+import asyncio
+from collections.abc import Callable
+from pathlib import Path
+
+from pdf_renamer.domain.models import FileRenameOperation
+from pdf_renamer.domain.ports import (
+    FilenameGenerator,
+    FileRenamer,
+    PDFExtractor,
+)
+
+
+class PDFRenameWorkflow:
+    """
+    Orchestrates the PDF rename workflow.
+
+    This class follows the Single Responsibility Principle - it only coordinates
+    the workflow, delegating actual work to specialized services.
+    """
+
+    def __init__(
+        self,
+        pdf_extractor: PDFExtractor,
+        filename_generator: FilenameGenerator,
+        file_renamer: FileRenamer,
+        max_concurrent_api: int = 3,
+        max_concurrent_pdf: int = 10,
+    ) -> None:
+        """
+        Initialize the workflow.
+
+        Args:
+            pdf_extractor: PDF extraction service
+            filename_generator: Filename generation service
+            file_renamer: File renaming service
+            max_concurrent_api: Maximum concurrent API calls
+            max_concurrent_pdf: Maximum concurrent PDF extractions
+        """
+        self.pdf_extractor = pdf_extractor
+        self.filename_generator = filename_generator
+        self.file_renamer = file_renamer
+        self.api_semaphore = asyncio.Semaphore(max_concurrent_api)
+        self.pdf_semaphore = asyncio.Semaphore(max_concurrent_pdf)
+
+    async def process_pdf(
+        self,
+        pdf_path: Path,
+        status_callback: Callable[[str, dict[str, str]], None] | None = None,
+    ) -> FileRenameOperation | None:
+        """
+        Process a single PDF file.
+
+        Args:
+            pdf_path: Path to PDF file
+            status_callback: Optional callback for status updates (filename, status_dict)
+
+        Returns:
+            FileRenameOperation if successful, None if error
+        """
+        filename = pdf_path.name
+
+        try:
+            # Update status: extracting
+            if status_callback:
+                status_callback(filename, {"status": "Extracting", "stage": "📄"})
+
+            # Extract PDF content (with PDF semaphore to limit memory usage)
+            async with self.pdf_semaphore:
+                content = await self.pdf_extractor.extract(pdf_path)
+
+            # Generate filename (with API semaphore to limit API load)
+            if status_callback:
+                status_callback(filename, {"status": "Analyzing", "stage": "🤖"})
+
+            async with self.api_semaphore:
+                result = await self.filename_generator.generate(filename, content)
+
+            # Mark complete
+            if status_callback:
+                status_callback(
+                    filename,
+                    {
+                        "status": "Complete",
+                        "stage": "✓",
+                        "confidence": result.confidence.value,
+                    },
+                )
+
+            return FileRenameOperation(
+                original_path=pdf_path,
+                suggested_filename=result.filename,
+                confidence=result.confidence,
+                reasoning=result.reasoning,
+                text_excerpt=content.text,
+                metadata=content.metadata,
+            )
+
+        except Exception as e:
+            if status_callback:
+                status_callback(filename, {"status": "Error", "stage": "✗", "error": str(e)})
+            return None
+
+    async def process_batch(
+        self,
+        pdf_paths: list[Path],
+        status_callback: Callable[[str, dict[str, str]], None] | None = None,
+    ) -> list[FileRenameOperation | None]:
+        """
+        Process multiple PDF files concurrently.
+
+        Args:
+            pdf_paths: List of PDF paths to process
+            status_callback: Optional callback for status updates
+
+        Returns:
+            List of FileRenameOperation results (None for failures)
+        """
+        tasks = [self.process_pdf(pdf, status_callback) for pdf in pdf_paths]
+        return await asyncio.gather(*tasks, return_exceptions=False)
+
+    async def execute_rename(
+        self,
+        operation: FileRenameOperation,
+        output_dir: Path | None = None,
+        dry_run: bool = True,
+    ) -> bool:
+        """
+        Execute a rename operation.
+
+        Args:
+            operation: The rename operation to execute
+            output_dir: Optional output directory
+            dry_run: If True, don't actually rename
+
+        Returns:
+            True if successful
+
+        Raises:
+            RuntimeError: If rename fails
+        """
+        new_path = operation.create_new_path(output_dir)
+        return await self.file_renamer.rename(operation.original_path, new_path, dry_run)

pdf_renamer/application/rename_service.py

@@ -0,0 +1,79 @@
+"""File rename service - handles the actual file operations."""
+
+import shutil
+from pathlib import Path
+
+from pdf_renamer.domain.ports import FileRenamer
+
+
+class RenameService(FileRenamer):
+    """Service for renaming files with duplicate handling."""
+
+    async def rename(self, original_path: Path, new_path: Path, dry_run: bool = True) -> bool:
+        """
+        Rename a file with duplicate handling.
+
+        Args:
+            original_path: Original file path
+            new_path: New file path
+            dry_run: If True, don't actually rename
+
+        Returns:
+            True if successful (or would be successful in dry-run)
+
+        Raises:
+            RuntimeError: If rename fails
+        """
+        try:
+            # Check if source exists
+            if not original_path.exists():
+                msg = f"Source file does not exist: {original_path}"
+                raise RuntimeError(msg)
+
+            # Handle duplicates
+            final_path = self._handle_duplicate(new_path)
+
+            if dry_run:
+                # In dry-run, just verify we could do the operation
+                return True
+
+            # Perform the rename
+            if original_path.parent != final_path.parent:
+                # Moving to different directory
+                final_path.parent.mkdir(parents=True, exist_ok=True)
+                shutil.move(str(original_path), str(final_path))
+            else:
+                # Renaming in same directory
+                original_path.rename(final_path)
+
+            return True
+
+        except Exception as e:
+            msg = f"Failed to rename {original_path} to {new_path}: {e}"
+            raise RuntimeError(msg) from e
+
+    def _handle_duplicate(self, path: Path) -> Path:
+        """
+        Handle duplicate filenames by adding a counter suffix.
+
+        Args:
+            path: Desired path
+
+        Returns:
+            Path that doesn't conflict with existing files
+        """
+        if not path.exists():
+            return path
+
+        # Extract stem and suffix
+        stem = path.stem
+        suffix = path.suffix
+        parent = path.parent
+
+        # Try incrementing counter
+        counter = 1
+        while True:
+            new_path = parent / f"{stem}-{counter}{suffix}"
+            if not new_path.exists():
+                return new_path
+            counter += 1

pdf_renamer/domain/__init__.py

@@ -0,0 +1,25 @@
+"""Domain layer - pure business logic with no external dependencies."""
+
+from pdf_renamer.domain.models import (
+    FilenameResult,
+    FileRenameOperation,
+    PDFContent,
+    PDFMetadata,
+)
+from pdf_renamer.domain.ports import (
+    FilenameGenerator,
+    FileRenamer,
+    LLMProvider,
+    PDFExtractor,
+)
+
+__all__ = [
+    "FileRenameOperation",
+    "FileRenamer",
+    "FilenameGenerator",
+    "FilenameResult",
+    "LLMProvider",
+    "PDFContent",
+    "PDFExtractor",
+    "PDFMetadata",
+]