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

pdf_renamer/domain/models.py

@@ -0,0 +1,80 @@
+"""Domain models - core business entities."""
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class ConfidenceLevel(str, Enum):
+    """Confidence level for filename suggestions."""
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    ERROR = "error"
+
+
+class FilenameResult(BaseModel):
+    """Result of filename generation."""
+
+    model_config = {"use_enum_values": True}
+
+    filename: str = Field(description="Suggested filename without extension")
+    confidence: ConfidenceLevel = Field(description="Confidence level of the suggestion")
+    reasoning: str = Field(description="Explanation of why this filename was chosen")
+
+
+@dataclass(frozen=True)
+class PDFMetadata:
+    """Metadata extracted from PDF."""
+
+    title: str | None = None
+    author: str | None = None
+    subject: str | None = None
+    keywords: str | None = None
+    creator: str | None = None
+    producer: str | None = None
+    creation_date: str | None = None
+    modification_date: str | None = None
+    # Focused metadata extracted from document content
+    header_text: str | None = None
+    year_hints: list[str] | None = None
+    email_hints: list[str] | None = None
+    author_hints: list[str] | None = None
+
+    def to_dict(self) -> dict[str, str | list[str] | None]:
+        """Convert to dictionary, excluding None values."""
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+@dataclass(frozen=True)
+class PDFContent:
+    """Extracted content from PDF."""
+
+    text: str
+    metadata: PDFMetadata
+    page_count: int
+
+
+@dataclass
+class FileRenameOperation:
+    """Represents a file rename operation."""
+
+    original_path: Path
+    suggested_filename: str
+    confidence: ConfidenceLevel
+    reasoning: str
+    text_excerpt: str
+    metadata: PDFMetadata
+
+    @property
+    def new_filename(self) -> str:
+        """Get the new filename with extension."""
+        return f"{self.suggested_filename}.pdf"
+
+    def create_new_path(self, output_dir: Path | None = None) -> Path:
+        """Create the new path for the renamed file."""
+        target_dir = output_dir if output_dir else self.original_path.parent
+        return target_dir / self.new_filename

pdf_renamer/domain/ports.py

@@ -0,0 +1,106 @@
+"""Domain ports - interfaces for external dependencies (Dependency Inversion Principle)."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from pdf_renamer.domain.models import FilenameResult, PDFContent
+
+
+class PDFExtractor(ABC):
+    """Interface for PDF text extraction."""
+
+    @abstractmethod
+    async def extract(self, pdf_path: Path) -> PDFContent:
+        """
+        Extract text and metadata from a PDF file.
+
+        Args:
+            pdf_path: Path to the PDF file
+
+        Returns:
+            PDFContent with extracted text and metadata
+
+        Raises:
+            RuntimeError: If extraction fails
+        """
+        pass
+
+
+class LLMProvider(ABC):
+    """Interface for LLM providers."""
+
+    @abstractmethod
+    async def generate_filename(
+        self,
+        original_filename: str,
+        text_excerpt: str,
+        metadata_dict: dict[str, str | list[str] | None],
+    ) -> FilenameResult:
+        """
+        Generate a filename suggestion using an LLM.
+
+        Args:
+            original_filename: Current filename
+            text_excerpt: Extracted text from PDF
+            metadata_dict: PDF metadata dictionary
+
+        Returns:
+            FilenameResult with suggestion and confidence
+
+        Raises:
+            RuntimeError: If generation fails
+        """
+        pass
+
+
+class FilenameGenerator(ABC):
+    """Interface for filename generation service."""
+
+    @abstractmethod
+    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
+        """
+        pass
+
+    @abstractmethod
+    def sanitize(self, filename: str) -> str:
+        """
+        Sanitize a filename to be filesystem-safe.
+
+        Args:
+            filename: Raw filename
+
+        Returns:
+            Sanitized filename
+        """
+        pass
+
+
+class FileRenamer(ABC):
+    """Interface for file renaming operations."""
+
+    @abstractmethod
+    async def rename(self, original_path: Path, new_path: Path, dry_run: bool = True) -> bool:
+        """
+        Rename a file.
+
+        Args:
+            original_path: Original file path
+            new_path: New file path
+            dry_run: If True, don't actually rename
+
+        Returns:
+            True if successful
+
+        Raises:
+            RuntimeError: If rename fails
+        """
+        pass

pdf_renamer/infrastructure/__init__.py

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

pdf_renamer/infrastructure/config.py

@@ -0,0 +1,94 @@
+"""Configuration management using Pydantic Settings."""
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # LLM Configuration
+    llm_provider: Literal["openai"] = Field(
+        default="openai",
+        description="LLM provider to use",
+    )
+    llm_model: str = Field(
+        default="llama3.2",
+        description="Model name to use",
+    )
+    llm_base_url: str = Field(
+        default="http://localhost:11434/v1",
+        description="Base URL for OpenAI-compatible API",
+    )
+    openai_api_key: str | None = Field(
+        default=None,
+        description="OpenAI API key (optional for local models)",
+    )
+
+    # PDF Extraction Configuration
+    pdf_max_pages: int = Field(
+        default=5,
+        ge=1,
+        le=50,
+        description="Maximum pages to extract from PDF",
+    )
+    pdf_max_chars: int = Field(
+        default=8000,
+        ge=1000,
+        le=50000,
+        description="Maximum characters to extract from PDF",
+    )
+    pdf_extractor: Literal["docling", "pymupdf"] = Field(
+        default="docling",
+        description="PDF extractor to use (docling for better structure, pymupdf for speed)",
+    )
+
+    # Processing Configuration
+    max_concurrent_api: int = Field(
+        default=3,
+        ge=1,
+        le=20,
+        description="Maximum concurrent API calls",
+    )
+    max_concurrent_pdf: int = Field(
+        default=10,
+        ge=1,
+        le=50,
+        description="Maximum concurrent PDF extractions",
+    )
+
+    # Retry Configuration
+    retry_max_attempts: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+        description="Maximum retry attempts for API calls",
+    )
+    retry_min_wait: int = Field(
+        default=4,
+        ge=1,
+        le=60,
+        description="Minimum wait time for exponential backoff (seconds)",
+    )
+    retry_max_wait: int = Field(
+        default=30,
+        ge=1,
+        le=300,
+        description="Maximum wait time for exponential backoff (seconds)",
+    )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Get cached settings instance (singleton pattern)."""
+    return Settings()

pdf_renamer/infrastructure/llm/__init__.py

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

pdf_renamer/infrastructure/llm/pydantic_ai_provider.py

@@ -0,0 +1,234 @@
+"""LLM provider using Pydantic AI for structured output generation."""
+
+from openai import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AsyncOpenAI,
+    RateLimitError,
+)
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIModel
+from pydantic_ai.providers.openai import OpenAIProvider
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from pdf_renamer.domain.models import ConfidenceLevel, FilenameResult
+from pdf_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.
+
+Your task is to analyze PDF content and suggest a clear, descriptive filename that accurately captures the document's identity.
+
+CRITICAL: PDF metadata (title, author, subject) is often UNRELIABLE or MISSING. Always prioritize what you find in the actual document text over metadata fields.
+
+Filename Format: Author-Topic-Year
+Example: Smith-Neural-Networks-Deep-Learning-2020
+
+EXTRACTION STRATEGY:
+1. AUTHOR: Look for author names in these locations (in order of reliability):
+   - First page header/title area
+   - After the title (often in smaller font or with affiliations)
+   - Paper byline (e.g., "by John Smith" or "Authors: Smith et al.")
+   - Email addresses can help confirm author names
+   - If multiple authors, use ONLY the first author's last name
+   - IGNORE metadata author field if it conflicts with document text
+
+2. TOPIC/TITLE: Look for the main title in:
+   - Large text at top of first page (usually biggest font)
+   - Abstract section which often restates the title
+   - Running headers on subsequent pages
+   - Condense long titles to key terms (3-6 words)
+   - Remove generic words like "A Study of", "An Analysis of", "Introduction to"
+   - Keep domain-specific terminology intact
+
+3. YEAR: Look for publication year in:
+   - Copyright notice or footer on first page
+   - Date near title or author information
+   - Conference/journal citation info
+   - Page headers/footers
+   - ONLY include year if you find it clearly stated
+   - Do NOT guess or estimate years
+
+EXAMPLES OF GOOD FILENAMES:
+- Hinton-Deep-Learning-Review-2015
+- Vapnik-Support-Vector-Networks-1995
+- Goodfellow-Generative-Adversarial-Networks-2014
+- Hochreiter-Long-Short-Term-Memory-1997
+
+FORMATTING RULES:
+- Use hyphens between ALL words (no spaces or underscores)
+- Use title case for all words
+- Remove special characters: colons, quotes, commas, parentheses
+- Target 60-100 characters total (can be shorter or slightly longer if needed)
+- If title is very long, focus on the most distinctive/searchable terms
+
+CONFIDENCE LEVELS:
+- HIGH: You found author (first page), clear title, and year in the document text
+- MEDIUM: You found title and either author OR year, or title is very clear but other elements missing
+- LOW: Document text is unclear, heavily formatted, or you can only extract partial information
+
+IMPORTANT: When metadata contradicts document text, TRUST THE DOCUMENT TEXT. Explain your reasoning briefly."""
+
+
+class PydanticAIProvider(LLMProvider):
+    """LLM provider using Pydantic AI with structured outputs."""
+
+    def __init__(
+        self,
+        model_name: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        retry_max_attempts: int = 3,
+        retry_min_wait: int = 4,
+        retry_max_wait: int = 30,
+    ) -> None:
+        """
+        Initialize the Pydantic AI provider.
+
+        Args:
+            model_name: Model name to use
+            api_key: API key (optional for local models)
+            base_url: Base URL for OpenAI-compatible API
+            retry_max_attempts: Maximum retry attempts
+            retry_min_wait: Minimum wait time for retries (seconds)
+            retry_max_wait: Maximum wait time for retries (seconds)
+        """
+        self.model_name = model_name
+        self.retry_max_attempts = retry_max_attempts
+        self.retry_min_wait = retry_min_wait
+        self.retry_max_wait = retry_max_wait
+
+        # Create model with appropriate configuration
+        if base_url:
+            client = AsyncOpenAI(base_url=base_url, api_key=api_key or "dummy-key")
+            provider = OpenAIProvider(openai_client=client)
+            model = OpenAIModel(model_name, provider=provider)
+        else:
+            if api_key:
+                client = AsyncOpenAI(api_key=api_key)
+                provider = OpenAIProvider(openai_client=client)
+                model = OpenAIModel(model_name, provider=provider)
+            else:
+                model = OpenAIModel(model_name)
+
+        # Create agent with structured output
+        self.agent: Agent[None, FilenameResult] = Agent(
+            model=model,
+            output_type=FilenameResult,
+            system_prompt=FILENAME_GENERATION_PROMPT,
+        )
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=2, min=4, max=30),
+        retry=retry_if_exception_type(
+            (APIError, APIConnectionError, RateLimitError, APITimeoutError)
+        ),
+        reraise=True,
+    )
+    async def generate_filename(
+        self,
+        original_filename: str,
+        text_excerpt: str,
+        metadata_dict: dict[str, str | list[str] | None],
+    ) -> FilenameResult:
+        """
+        Generate filename using LLM with retry logic.
+
+        Args:
+            original_filename: Current filename
+            text_excerpt: Extracted text from PDF
+            metadata_dict: PDF metadata dictionary
+
+        Returns:
+            FilenameResult with suggestion
+
+        Raises:
+            RuntimeError: If generation fails after retries
+        """
+        try:
+            # Build context for LLM
+            context_parts = [f"Original filename: {original_filename}"]
+
+            # Add metadata hints if available
+            if title := metadata_dict.get("title"):
+                context_parts.append(f"PDF Title metadata (may be unreliable): {title}")
+            if author := metadata_dict.get("author"):
+                context_parts.append(f"PDF Author metadata (may be unreliable): {author}")
+            if subject := metadata_dict.get("subject"):
+                context_parts.append(f"PDF Subject metadata (may be unreliable): {subject}")
+
+            # Add focused metadata hints
+            year_hints = metadata_dict.get("year_hints")
+            if year_hints and isinstance(year_hints, list):
+                context_parts.append(f"Years found in document: {', '.join(year_hints)}")
+
+            email_hints = metadata_dict.get("email_hints")
+            if email_hints and isinstance(email_hints, list):
+                context_parts.append(
+                    f"Email addresses found (often near authors): {', '.join(email_hints[:2])}"
+                )
+
+            author_hints = metadata_dict.get("author_hints")
+            if author_hints and isinstance(author_hints, list):
+                context_parts.append("Possible author sections:\n" + "\n".join(author_hints[:2]))
+            if header_text := metadata_dict.get("header_text"):
+                context_parts.append(f"First 500 chars (likely title/author area):\n{header_text}")
+
+            # Add full text excerpt
+            context_parts.append(f"\nFull content excerpt (first ~5 pages):\n{text_excerpt}")
+
+            context = "\n".join(context_parts)
+
+            # Generate filename
+            result = await self.agent.run(context)
+            suggestion = result.output
+
+            # If confidence is low, try a focused second pass
+            if suggestion.confidence == ConfidenceLevel.LOW:
+                suggestion = await self._retry_with_focus(original_filename, text_excerpt)
+
+            return suggestion
+
+        except Exception as e:
+            msg = f"Failed to generate filename: {e}"
+            raise RuntimeError(msg) from e
+
+    async def _retry_with_focus(self, original_filename: str, text_excerpt: str) -> FilenameResult:
+        """
+        Retry filename generation with more focused prompting.
+
+        Args:
+            original_filename: Current filename
+            text_excerpt: Extracted text from PDF
+
+        Returns:
+            FilenameResult from second pass
+        """
+        # Focus on first portion of text
+        first_pages = text_excerpt[:4000]
+
+        focused_context = f"""SECOND PASS - The initial analysis had low confidence. Please analyze more carefully.
+
+Original filename: {original_filename}
+
+FOCUS ON: The first few pages contain the most important metadata (title, author, year).
+Look VERY carefully at:
+1. The largest text on page 1 (this is usually the title)
+2. Text immediately after the title (usually authors and affiliations)
+3. Any dates, copyright notices, or publication info on page 1
+4. Headers and footers that might contain publication info
+
+First pages content:
+{first_pages}
+
+Please extract whatever information you can find with certainty. If you cannot find author or year, that's OK - just provide the best title you can determine."""
+
+        result = await self.agent.run(focused_context)
+        return result.output

pdf_renamer/infrastructure/pdf/__init__.py

@@ -0,0 +1,7 @@
+"""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/infrastructure/pdf/composite.py

@@ -0,0 +1,57 @@
+"""Composite PDF extractor that tries multiple strategies."""
+
+from pathlib import Path
+
+from pdf_renamer.domain.models import PDFContent
+from pdf_renamer.domain.ports import PDFExtractor
+
+
+class CompositePDFExtractor(PDFExtractor):
+    """
+    Composite PDF extractor that tries multiple extractors in sequence.
+
+    This implements the Chain of Responsibility pattern with fallback strategy.
+    """
+
+    def __init__(self, extractors: list[PDFExtractor]) -> None:
+        """
+        Initialize the composite extractor.
+
+        Args:
+            extractors: List of extractors to try in order
+        """
+        if not extractors:
+            msg = "At least one extractor must be provided"
+            raise ValueError(msg)
+        self.extractors = extractors
+
+    async def extract(self, pdf_path: Path) -> PDFContent:
+        """
+        Try extractors in sequence until one succeeds.
+
+        Args:
+            pdf_path: Path to PDF file
+
+        Returns:
+            PDFContent from first successful extractor
+
+        Raises:
+            RuntimeError: If all extractors fail
+        """
+        errors: list[str] = []
+
+        for extractor in self.extractors:
+            try:
+                content = await extractor.extract(pdf_path)
+                # Only accept if we got meaningful text
+                if len(content.text.strip()) > 100:
+                    return content
+                errors.append(f"{extractor.__class__.__name__}: Insufficient text extracted")
+            except Exception as e:
+                errors.append(f"{extractor.__class__.__name__}: {e}")
+                continue
+
+        # All extractors failed
+        error_msg = "; ".join(errors)
+        msg = f"All PDF extractors failed for {pdf_path}: {error_msg}"
+        raise RuntimeError(msg)