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

{pdf_renamer → pdf_file_renamer}/__init__.py

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

pdf_file_renamer/application/__init__.py

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

pdf_file_renamer/application/filename_service.py

@@ -0,0 +1,172 @@
+"""Filename generation service - coordinates PDF extraction and LLM generation."""
+
+import re
+
+from pdf_file_renamer.domain.models import ConfidenceLevel, FilenameResult, PDFContent
+from pdf_file_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
+        """
+        # If DOI metadata is available, use it directly for high-confidence naming
+        if content.doi_metadata:
+            return self._generate_from_doi(content)
+
+        # Otherwise, fall back to LLM-based generation
+        # 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 _generate_from_doi(self, content: PDFContent) -> FilenameResult:
+        """
+        Generate filename directly from DOI metadata.
+
+        Args:
+            content: PDF content with DOI metadata
+
+        Returns:
+            FilenameResult with very high confidence
+        """
+        doi_meta = content.doi_metadata
+        if not doi_meta:
+            msg = "DOI metadata not available"
+            raise ValueError(msg)
+
+        # Extract components for filename
+        author = doi_meta.first_author or "Unknown"
+
+        # Get title and clean it
+        title = doi_meta.title or "Document"
+        # Extract key words from title (remove common words)
+        title_words = self._extract_key_words(title)
+
+        year = doi_meta.year or ""
+
+        # Build filename: Author-KeyWords-Year
+        parts = [author]
+        if title_words:
+            parts.append(title_words)
+        if year:
+            parts.append(year)
+
+        filename = "-".join(parts)
+        filename = self.sanitize(filename)
+
+        return FilenameResult(
+            filename=filename,
+            confidence=ConfidenceLevel.VERY_HIGH,
+            reasoning=f"Filename generated from DOI metadata (DOI: {doi_meta.doi}). "
+            f"Author: {author}, Year: {year}",
+        )
+
+    def _extract_key_words(self, title: str, max_words: int = 6) -> str:
+        """
+        Extract key words from title, removing common words.
+
+        Args:
+            title: Paper title
+            max_words: Maximum number of words to include
+
+        Returns:
+            Hyphenated key words
+        """
+        # Common words to skip
+        stop_words = {
+            "a",
+            "an",
+            "the",
+            "and",
+            "or",
+            "but",
+            "in",
+            "on",
+            "at",
+            "to",
+            "for",
+            "of",
+            "with",
+            "by",
+            "from",
+            "as",
+            "is",
+            "was",
+            "are",
+            "were",
+            "been",
+            "be",
+            "this",
+            "that",
+            "these",
+            "those",
+        }
+
+        # Clean and split title
+        words = re.sub(r"[^\w\s-]", " ", title.lower()).split()
+
+        # Filter stop words and keep significant words
+        key_words = [w for w in words if w not in stop_words and len(w) > 2]
+
+        # Limit to max_words
+        key_words = key_words[:max_words]
+
+        # Capitalize first letter of each word
+        key_words = [w.capitalize() for w in key_words]
+
+        return "-".join(key_words)
+
+    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 → pdf_file_renamer}/application/pdf_rename_workflow.py

@@ -1,11 +1,13 @@
 """PDF rename workflow - orchestrates the complete process."""
 
 import asyncio
+import contextlib
 from collections.abc import Callable
 from pathlib import Path
 
-from pdf_renamer.domain.models import FileRenameOperation
-from pdf_renamer.domain.ports import (
+from pdf_file_renamer.domain.models import FileRenameOperation
+from pdf_file_renamer.domain.ports import (
+    DOIExtractor,
     FilenameGenerator,
     FileRenamer,
     PDFExtractor,
@@ -25,6 +27,7 @@ class PDFRenameWorkflow:
         pdf_extractor: PDFExtractor,
         filename_generator: FilenameGenerator,
         file_renamer: FileRenamer,
+        doi_extractor: DOIExtractor | None = None,
         max_concurrent_api: int = 3,
         max_concurrent_pdf: int = 10,
     ) -> None:
@@ -35,12 +38,14 @@ class PDFRenameWorkflow:
             pdf_extractor: PDF extraction service
             filename_generator: Filename generation service
             file_renamer: File renaming service
+            doi_extractor: Optional DOI extraction 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.doi_extractor = doi_extractor
         self.api_semaphore = asyncio.Semaphore(max_concurrent_api)
         self.pdf_semaphore = asyncio.Semaphore(max_concurrent_pdf)
 
@@ -62,17 +67,36 @@ class PDFRenameWorkflow:
         filename = pdf_path.name
 
         try:
+            # Try DOI extraction first (if extractor available)
+            doi_metadata = None
+            if self.doi_extractor:
+                if status_callback:
+                    status_callback(filename, {"status": "DOI Lookup", "stage": "🔍"})
+
+                # DOI extraction is optional, continue if it fails
+                with contextlib.suppress(Exception):
+                    doi_metadata = await self.doi_extractor.extract_doi(pdf_path)
+
             # Update status: extracting
             if status_callback:
-                status_callback(filename, {"status": "Extracting", "stage": "📄"})
+                status = "Extracting" if not doi_metadata else "Extracting (DOI found)"
+                status_callback(filename, {"status": status, "stage": "📄"})
 
             # Extract PDF content (with PDF semaphore to limit memory usage)
             async with self.pdf_semaphore:
                 content = await self.pdf_extractor.extract(pdf_path)
 
+            # Attach DOI metadata to content if found
+            if doi_metadata:
+                # Create new content with DOI metadata
+                from dataclasses import replace
+
+                content = replace(content, doi_metadata=doi_metadata)
+
             # Generate filename (with API semaphore to limit API load)
             if status_callback:
-                status_callback(filename, {"status": "Analyzing", "stage": "🤖"})
+                status = "Analyzing" if not doi_metadata else "Formatting (DOI-based)"
+                status_callback(filename, {"status": status, "stage": "🤖"})
 
             async with self.api_semaphore:
                 result = await self.filename_generator.generate(filename, content)
@@ -95,6 +119,7 @@ class PDFRenameWorkflow:
                 reasoning=result.reasoning,
                 text_excerpt=content.text,
                 metadata=content.metadata,
+                doi_metadata=content.doi_metadata,
             )
 
         except Exception as e:

{pdf_renamer → pdf_file_renamer}/application/rename_service.py

@@ -3,7 +3,7 @@
 import shutil
 from pathlib import Path
 
-from pdf_renamer.domain.ports import FileRenamer
+from pdf_file_renamer.domain.ports import FileRenamer
 
 
 class RenameService(FileRenamer):

{pdf_renamer → pdf_file_renamer}/domain/__init__.py

@@ -1,12 +1,12 @@
 """Domain layer - pure business logic with no external dependencies."""
 
-from pdf_renamer.domain.models import (
+from pdf_file_renamer.domain.models import (
     FilenameResult,
     FileRenameOperation,
     PDFContent,
     PDFMetadata,
 )
-from pdf_renamer.domain.ports import (
+from pdf_file_renamer.domain.ports import (
     FilenameGenerator,
     FileRenamer,
     LLMProvider,

{pdf_renamer → pdf_file_renamer}/domain/models.py

@@ -10,12 +10,39 @@ from pydantic import BaseModel, Field
 class ConfidenceLevel(str, Enum):
     """Confidence level for filename suggestions."""
 
+    VERY_HIGH = "very_high"  # DOI-backed metadata
     HIGH = "high"
     MEDIUM = "medium"
     LOW = "low"
     ERROR = "error"
 
 
+@dataclass(frozen=True)
+class DOIMetadata:
+    """Metadata extracted from DOI lookup."""
+
+    doi: str
+    title: str | None = None
+    authors: list[str] | None = None
+    year: str | None = None
+    journal: str | None = None
+    publisher: str | None = None
+    raw_bibtex: str | None = None
+
+    @property
+    def first_author(self) -> str | None:
+        """Get the first author's last name."""
+        if not self.authors or len(self.authors) == 0:
+            return None
+        # Extract last name from first author (handles "Last, First" or "First Last" formats)
+        first = self.authors[0]
+        if "," in first:
+            return first.split(",")[0].strip()
+        # Assume last word is last name
+        parts = first.strip().split()
+        return parts[-1] if parts else None
+
+
 class FilenameResult(BaseModel):
     """Result of filename generation."""
 
@@ -56,6 +83,7 @@ class PDFContent:
     text: str
     metadata: PDFMetadata
     page_count: int
+    doi_metadata: DOIMetadata | None = None
 
 
 @dataclass
@@ -68,6 +96,7 @@ class FileRenameOperation:
     reasoning: str
     text_excerpt: str
     metadata: PDFMetadata
+    doi_metadata: DOIMetadata | None = None
 
     @property
     def new_filename(self) -> str:

{pdf_renamer → pdf_file_renamer}/domain/ports.py

@@ -3,7 +3,24 @@
 from abc import ABC, abstractmethod
 from pathlib import Path
 
-from pdf_renamer.domain.models import FilenameResult, PDFContent
+from pdf_file_renamer.domain.models import DOIMetadata, FilenameResult, PDFContent
+
+
+class DOIExtractor(ABC):
+    """Interface for DOI extraction and metadata lookup."""
+
+    @abstractmethod
+    async def extract_doi(self, pdf_path: Path) -> DOIMetadata | None:
+        """
+        Extract DOI from PDF and fetch metadata.
+
+        Args:
+            pdf_path: Path to the PDF file
+
+        Returns:
+            DOIMetadata if DOI found and validated, None otherwise
+        """
+        pass
 
 
 class PDFExtractor(ABC):

{pdf_renamer → pdf_file_renamer}/infrastructure/__init__.py

@@ -1,5 +1,5 @@
 """Infrastructure layer - external dependencies and implementations."""
 
-from pdf_renamer.infrastructure.config import Settings, get_settings
+from pdf_file_renamer.infrastructure.config import Settings, get_settings
 
 __all__ = ["Settings", "get_settings"]

pdf_file_renamer/infrastructure/doi/__init__.py

@@ -0,0 +1,5 @@
+"""DOI extraction infrastructure."""
+
+from pdf_file_renamer.infrastructure.doi.pdf2doi_extractor import PDF2DOIExtractor
+
+__all__ = ["PDF2DOIExtractor"]

pdf_file_renamer/infrastructure/doi/pdf2doi_extractor.py

@@ -0,0 +1,129 @@
+"""DOI extraction using pdf2doi library."""
+
+import asyncio
+import re
+from pathlib import Path
+
+import pdf2doi
+
+from pdf_file_renamer.domain.models import DOIMetadata
+from pdf_file_renamer.domain.ports import DOIExtractor
+
+
+class PDF2DOIExtractor(DOIExtractor):
+    """Extract DOI from PDF files using pdf2doi library."""
+
+    def __init__(self) -> None:
+        """Initialize the PDF2DOI extractor."""
+        # Suppress pdf2doi verbose output
+        pdf2doi.config.set("verbose", False)
+
+    async def extract_doi(self, pdf_path: Path) -> DOIMetadata | None:
+        """
+        Extract DOI from PDF and fetch metadata.
+
+        Args:
+            pdf_path: Path to the PDF file
+
+        Returns:
+            DOIMetadata if DOI found and validated, None otherwise
+        """
+        try:
+            # Run pdf2doi in executor to avoid blocking
+            loop = asyncio.get_event_loop()
+            results = await loop.run_in_executor(
+                None, pdf2doi.pdf2doi, str(pdf_path)
+            )
+
+            if not results or len(results) == 0:
+                return None
+
+            # Get the first result
+            result = results[0]
+
+            # Check if DOI was found
+            identifier = result.get("identifier")
+            if not identifier:
+                return None
+
+            identifier_type = result.get("identifier_type", "")
+            if identifier_type.lower() not in ("doi", "arxiv"):
+                return None
+
+            # Extract metadata from validation_info (bibtex)
+            validation_info = result.get("validation_info", "")
+
+            # Parse bibtex for metadata
+            title = self._extract_bibtex_field(validation_info, "title")
+            authors = self._extract_bibtex_authors(validation_info)
+            year = self._extract_bibtex_field(validation_info, "year")
+            journal = self._extract_bibtex_field(validation_info, "journal")
+            publisher = self._extract_bibtex_field(validation_info, "publisher")
+
+            return DOIMetadata(
+                doi=identifier,
+                title=title,
+                authors=authors,
+                year=year,
+                journal=journal,
+                publisher=publisher,
+                raw_bibtex=validation_info if validation_info else None,
+            )
+
+        except Exception:
+            # Silently fail - DOI extraction is opportunistic
+            return None
+
+    def _extract_bibtex_field(self, bibtex: str, field: str) -> str | None:
+        """
+        Extract a field from bibtex string.
+
+        Args:
+            bibtex: Bibtex string
+            field: Field name to extract
+
+        Returns:
+            Field value or None
+        """
+        if not bibtex:
+            return None
+
+        # Match field = {value} or field = "value"
+        pattern = rf"{field}\s*=\s*[{{\"](.*?)[\}}\"](,|\n|$)"
+        match = re.search(pattern, bibtex, re.IGNORECASE)
+
+        if match:
+            return match.group(1).strip()
+
+        return None
+
+    def _extract_bibtex_authors(self, bibtex: str) -> list[str] | None:
+        """
+        Extract authors from bibtex string.
+
+        Args:
+            bibtex: Bibtex string
+
+        Returns:
+            List of author names or None
+        """
+        if not bibtex:
+            return None
+
+        # Match author = {Name1 and Name2 and Name3}
+        pattern = r"author\s*=\s*[{\"](.*?)[\}\"](,|\n|$)"
+        match = re.search(pattern, bibtex, re.IGNORECASE)
+
+        if not match:
+            return None
+
+        authors_str = match.group(1).strip()
+
+        # Split by "and" and clean up
+        authors = [
+            author.strip()
+            for author in re.split(r"\s+and\s+", authors_str, flags=re.IGNORECASE)
+            if author.strip()
+        ]
+
+        return authors if authors else None

pdf_file_renamer/infrastructure/llm/__init__.py

@@ -0,0 +1,5 @@
+"""LLM provider implementations."""
+
+from pdf_file_renamer.infrastructure.llm.pydantic_ai_provider import PydanticAIProvider
+
+__all__ = ["PydanticAIProvider"]

{pdf_renamer → pdf_file_renamer}/infrastructure/llm/pydantic_ai_provider.py

@@ -17,8 +17,8 @@ from tenacity import (
     wait_exponential,
 )
 
-from pdf_renamer.domain.models import ConfidenceLevel, FilenameResult
-from pdf_renamer.domain.ports import LLMProvider
+from pdf_file_renamer.domain.models import ConfidenceLevel, FilenameResult
+from pdf_file_renamer.domain.ports import LLMProvider
 
 # System prompt for filename generation
 FILENAME_GENERATION_PROMPT = """You are an expert at creating concise, descriptive filenames for academic papers and technical documents.

pdf_file_renamer/infrastructure/pdf/__init__.py

@@ -0,0 +1,7 @@
+"""PDF extraction implementations."""
+
+from pdf_file_renamer.infrastructure.pdf.composite import CompositePDFExtractor
+from pdf_file_renamer.infrastructure.pdf.docling_extractor import DoclingPDFExtractor
+from pdf_file_renamer.infrastructure.pdf.pymupdf_extractor import PyMuPDFExtractor
+
+__all__ = ["CompositePDFExtractor", "DoclingPDFExtractor", "PyMuPDFExtractor"]

{pdf_renamer → pdf_file_renamer}/infrastructure/pdf/composite.py

@@ -2,8 +2,8 @@
 
 from pathlib import Path
 
-from pdf_renamer.domain.models import PDFContent
-from pdf_renamer.domain.ports import PDFExtractor
+from pdf_file_renamer.domain.models import PDFContent
+from pdf_file_renamer.domain.ports import PDFExtractor
 
 
 class CompositePDFExtractor(PDFExtractor):

{pdf_renamer → pdf_file_renamer}/infrastructure/pdf/docling_extractor.py

@@ -6,8 +6,8 @@ from pathlib import Path
 from docling_core.types.doc.page import TextCellUnit
 from docling_parse.pdf_parser import DoclingPdfParser
 
-from pdf_renamer.domain.models import PDFContent, PDFMetadata
-from pdf_renamer.domain.ports import PDFExtractor
+from pdf_file_renamer.domain.models import PDFContent, PDFMetadata
+from pdf_file_renamer.domain.ports import PDFExtractor
 
 
 class DoclingPDFExtractor(PDFExtractor):

{pdf_renamer → pdf_file_renamer}/infrastructure/pdf/pymupdf_extractor.py

@@ -5,8 +5,8 @@ from pathlib import Path
 
 import pymupdf
 
-from pdf_renamer.domain.models import PDFContent, PDFMetadata
-from pdf_renamer.domain.ports import PDFExtractor
+from pdf_file_renamer.domain.models import PDFContent, PDFMetadata
+from pdf_file_renamer.domain.ports import PDFExtractor
 
 
 class PyMuPDFExtractor(PDFExtractor):

{pdf_renamer → pdf_file_renamer}/main.py

@@ -1,6 +1,6 @@
 """Main entry point for the PDF renamer application."""
 
-from pdf_renamer.presentation.cli import app
+from pdf_file_renamer.presentation.cli import app
 
 if __name__ == "__main__":
     app()

pdf_file_renamer/presentation/__init__.py

@@ -0,0 +1,6 @@
+"""Presentation layer - CLI and user interaction."""
+
+from pdf_file_renamer.presentation.cli import app
+from pdf_file_renamer.presentation.formatters import ProgressDisplay
+
+__all__ = ["ProgressDisplay", "app"]

{pdf_renamer → pdf_file_renamer}/presentation/cli.py

@@ -9,19 +9,20 @@ import typer
 from rich.console import Console
 from rich.live import Live
 
-from pdf_renamer.application import (
+from pdf_file_renamer.application import (
     FilenameService,
     PDFRenameWorkflow,
     RenameService,
 )
-from pdf_renamer.infrastructure.config import Settings
-from pdf_renamer.infrastructure.llm import PydanticAIProvider
-from pdf_renamer.infrastructure.pdf import (
+from pdf_file_renamer.infrastructure.config import Settings
+from pdf_file_renamer.infrastructure.doi import PDF2DOIExtractor
+from pdf_file_renamer.infrastructure.llm import PydanticAIProvider
+from pdf_file_renamer.infrastructure.pdf import (
     CompositePDFExtractor,
     DoclingPDFExtractor,
     PyMuPDFExtractor,
 )
-from pdf_renamer.presentation.formatters import (
+from pdf_file_renamer.presentation.formatters import (
     InteractivePrompt,
     ProgressDisplay,
     ResultsTable,
@@ -64,6 +65,9 @@ def create_workflow(settings: Settings) -> PDFRenameWorkflow:
         retry_max_wait=settings.retry_max_wait,
     )
 
+    # Create DOI extractor
+    doi_extractor = PDF2DOIExtractor()
+
     # Create application services
     filename_service = FilenameService(llm_provider)
     file_renamer = RenameService()
@@ -73,6 +77,7 @@ def create_workflow(settings: Settings) -> PDFRenameWorkflow:
         pdf_extractor=pdf_extractor,
         filename_generator=filename_service,
         file_renamer=file_renamer,
+        doi_extractor=doi_extractor,
         max_concurrent_api=settings.max_concurrent_api,
         max_concurrent_pdf=settings.max_concurrent_pdf,
     )

{pdf_renamer → pdf_file_renamer}/presentation/formatters.py

@@ -7,7 +7,7 @@ from rich.prompt import Prompt
 from rich.table import Table
 from rich.text import Text
 
-from pdf_renamer.domain.models import FileRenameOperation
+from pdf_file_renamer.domain.models import FileRenameOperation
 
 
 class ProgressDisplay:

{pdf_file_renamer-0.4.2.dist-info → pdf_file_renamer-0.6.0.dist-info}/METADATA

@@ -1,28 +1,28 @@
 Metadata-Version: 2.4
 Name: pdf-file-renamer
-Version: 0.4.2
+Version: 0.6.0
 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-Python: >=3.11
+Requires-Dist: docling-core>=2.0.0
+Requires-Dist: docling-parse>=2.0.0
+Requires-Dist: pdf2doi>=1.7
 Requires-Dist: pydantic-ai>=1.0.17
 Requires-Dist: pydantic-settings>=2.7.1
+Requires-Dist: pydantic>=2.10.6
 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
+Requires-Dist: typer>=0.19.2
 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
+Requires-Dist: mypy>=1.14.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.2; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.1; extra == 'dev'
+Description-Content-Type: text/markdown
 
 # PDF Renamer
 
@@ -44,9 +44,11 @@ Intelligent PDF file renaming using LLMs. This tool analyzes PDF content and met
 
 ## Features
 
+- **DOI-based naming** - Automatically extracts DOI and fetches authoritative metadata for academic papers
 - **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
+- **Hybrid approach** - Uses DOI metadata when available, falls back to LLM analysis for other documents
 - 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
@@ -209,19 +211,44 @@ You can use interactive mode with `--dry-run` to preview without actually renami
 
 ## 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)
+### Intelligent Hybrid Approach
+
+The tool uses a multi-strategy approach to generate accurate filenames:
+
+1. **DOI Detection** (for academic papers)
+   - Searches PDF for DOI identifiers using [pdf2doi](https://github.com/MicheleCotrufo/pdf2doi)
+   - If found, queries authoritative metadata (title, authors, year, journal)
+   - Generates filename with **very high confidence** from validated metadata
+   - **Saves API costs** - no LLM call needed for papers with DOIs
+
+2. **LLM Analysis** (fallback for non-academic PDFs)
+   - **Extract**: Uses docling-parse to read first 5 pages with structure-aware parsing, falls back to PyMuPDF if needed
+   - **OCR**: Automatically applies OCR for scanned PDFs with minimal text
+   - **Metadata Enhancement**: Extracts focused hints (years, emails, author sections) to supplement unreliable PDF metadata
+   - **Analyze**: Sends full content excerpt to LLM with enhanced metadata and detailed extraction instructions
+   - **Multi-pass Review**: Low-confidence results trigger a second analysis pass with focused prompts
+   - **Suggest**: LLM returns filename in `Author-Topic-Year` format with confidence level and reasoning
+
+3. **Interactive Review** (optional): User can accept, edit, retry, or skip each suggestion
+4. **Rename**: Applies suggestions (if not in dry-run mode)
+
+### Benefits of DOI Integration
+
+- **Accuracy**: DOI metadata is canonical and verified
+- **Speed**: Instant lookup vs. LLM processing time
+- **Cost**: Free DOI lookups save on API costs for academic papers
+- **Reliability**: Works even when PDF text extraction is poor
 
 ## Cost Considerations
 
-**OpenAI:**
+**DOI-based Naming (Academic Papers):**
+- **Completely free** - No API costs
+- **No LLM needed** - Direct metadata lookup
+- Works for most academic papers with embedded DOIs
+
+**OpenAI (Fallback):**
 - Uses `gpt-4o-mini` by default (very cost-effective)
+- Only called when DOI not found
 - Processes first ~4500 characters per PDF
 - Typical cost: ~$0.001-0.003 per PDF
 

pdf_file_renamer-0.6.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+pdf_file_renamer/__init__.py,sha256=yCEfy0jblhbUMNTSjJKPuW4zADXoI6IfICx8XvB4R8Q,85
+pdf_file_renamer/main.py,sha256=FTEEb-9QmOOsN9SE8L1SZvFVIkVpQDy8xZ5a8t8CWUs,145
+pdf_file_renamer/application/__init__.py,sha256=riSV7UXBenkDst7Nnf11N1_RuRtM7wpKdwugxOhumS4,363
+pdf_file_renamer/application/filename_service.py,sha256=IbeCNBwyhFlCMCZveq16nmQ2qvyTdtgLmr6PDWPckOs,4868
+pdf_file_renamer/application/pdf_rename_workflow.py,sha256=gd53KoR1aFrK__6TArm7Rtn1yNxylEI2ikmubDOByF4,5842
+pdf_file_renamer/application/rename_service.py,sha256=vviNQolk_w-qDQvOKTKj8ZhqYyyNWL-VJMfuUnL6WLw,2357
+pdf_file_renamer/domain/__init__.py,sha256=jxbH3h6xaCnSRuBxclFESl6ZE1pua_I1K4CRAaYxu_I,503
+pdf_file_renamer/domain/models.py,sha256=QwN79TzWmqvQvz-m9ymebvAx3pWlVpSWXNdSEAk4qq0,3186
+pdf_file_renamer/domain/ports.py,sha256=ebOcHptiOK119NCmIwM32_fbRK5xkZP9K67vjL-4k0g,2976
+pdf_file_renamer/infrastructure/__init__.py,sha256=C3ZQ7WCPCa6PMfP00lu4wqb0r57GVyDdiD5EL2DhCeY,187
+pdf_file_renamer/infrastructure/config.py,sha256=baNL5_6_NNiS50ZNdql7fDwQbeAwf6f58HGYIWFQxQQ,2464
+pdf_file_renamer/infrastructure/doi/__init__.py,sha256=8N9ZEwfG7q5xomzh187YtP8t4CfEBHM334xNRblPeuI,153
+pdf_file_renamer/infrastructure/doi/pdf2doi_extractor.py,sha256=rAo0q5HTCqVTyyIXzW3D6riGS5Q9xlXhbT2AY0Hb7nk,3820
+pdf_file_renamer/infrastructure/llm/__init__.py,sha256=ToB8__mHvXwaIukGKPEAQ8SeC4ZLiH4auZI1P1yH5PQ,159
+pdf_file_renamer/infrastructure/llm/pydantic_ai_provider.py,sha256=kVsmj0NIawkj-1WWM0hZXbsNH09GabVZm9HPlYsxGuo,9217
+pdf_file_renamer/infrastructure/pdf/__init__.py,sha256=uMHqxSXNLZH5WH_e1kXrp9m7uTqPkiI2hXjNo6rCRoo,368
+pdf_file_renamer/infrastructure/pdf/composite.py,sha256=dNrrcGTsGf1LLF4F0AoF7jRbvLkgRGnIF6XNGlg92n4,1801
+pdf_file_renamer/infrastructure/pdf/docling_extractor.py,sha256=auZrJpK7mMg1mUXK6ptjZC1pnAUQje1h7ZAS7gFUBzo,3974
+pdf_file_renamer/infrastructure/pdf/pymupdf_extractor.py,sha256=C61udZCqGqiVx7T0HWNyjvnhgv5AgMIcCYtrhgHOJwk,5465
+pdf_file_renamer/presentation/__init__.py,sha256=1VR44GoPGTixk3hG5YzhGyQf7a4BTKsJBd2VP3rHcFM,211
+pdf_file_renamer/presentation/cli.py,sha256=0t_59-utRWLNCYjFetU0ZHoF1DPTjdNiWM9Au0jFaOg,8013
+pdf_file_renamer/presentation/formatters.py,sha256=Yl-Et7OKMfthyLqTA5qEtSAqh0PfHKp3lNNBA_dn01c,8519
+pdf_file_renamer-0.6.0.dist-info/METADATA,sha256=6XmqT7jtJuqkWlks3FlPWCpNP_tKOGokhxy2Yju5R7k,9912
+pdf_file_renamer-0.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pdf_file_renamer-0.6.0.dist-info/entry_points.txt,sha256=0fEGYy60chGE9rECWeCVPxjxzz6vMtIAYdFvmH7xzbw,63
+pdf_file_renamer-0.6.0.dist-info/licenses/LICENSE,sha256=_w08V08WgoMpDMlGNlkIatC5QfQ_Ds_rXOBM8pl7ffE,1068
+pdf_file_renamer-0.6.0.dist-info/RECORD,,

{pdf_file_renamer-0.4.2.dist-info → pdf_file_renamer-0.6.0.dist-info}/WHEEL

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

pdf_file_renamer-0.6.0.dist-info/entry_points.txt

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

pdf_file_renamer-0.4.2.dist-info/RECORD

@@ -1,26 +0,0 @@
-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/entry_points.txt

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

pdf_file_renamer-0.4.2.dist-info/top_level.txt

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

pdf_renamer/application/__init__.py

@@ -1,7 +0,0 @@
-"""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

@@ -1,70 +0,0 @@
-"""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/infrastructure/llm/__init__.py

@@ -1,5 +0,0 @@
-"""LLM provider implementations."""
-
-from pdf_renamer.infrastructure.llm.pydantic_ai_provider import PydanticAIProvider
-
-__all__ = ["PydanticAIProvider"]

pdf_renamer/infrastructure/pdf/__init__.py

@@ -1,7 +0,0 @@
-"""PDF extraction implementations."""
-
-from pdf_renamer.infrastructure.pdf.composite import CompositePDFExtractor
-from pdf_renamer.infrastructure.pdf.docling_extractor import DoclingPDFExtractor
-from pdf_renamer.infrastructure.pdf.pymupdf_extractor import PyMuPDFExtractor
-
-__all__ = ["CompositePDFExtractor", "DoclingPDFExtractor", "PyMuPDFExtractor"]

pdf_renamer/presentation/__init__.py

@@ -1,6 +0,0 @@
-"""Presentation layer - CLI and user interaction."""
-
-from pdf_renamer.presentation.cli import app
-from pdf_renamer.presentation.formatters import ProgressDisplay
-
-__all__ = ["ProgressDisplay", "app"]