pdf-modifier 1.9.1__py3-none-any.whl

pdf_modifier/__init__.py

@@ -0,0 +1,26 @@
+"""
+PDF Modifier - A dual-interface PDF modification tool.
+
+Provides both CLI (pdf-mod) and MCP server interfaces for PDF manipulation.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from .core import (
+    PDFAnalyzer,
+    PDFModifier,
+    PDFModifierError,
+    ReplacementSpec,
+)
+
+__version__ = version("pdf-modifier")
+
+__all__ = [
+    "PDFAnalyzer",
+    "PDFModifier",
+    "PDFModifierError",
+    "ReplacementSpec",
+    "__version__",
+]

pdf_modifier/__main__.py

@@ -0,0 +1,13 @@
+"""
+Entry point for `python -m pdf_modifier`.
+
+Launches the MCP server by default.
+Use `pdf-mod` command for CLI access.
+"""
+
+from __future__ import annotations
+
+from .interfaces.mcp import main
+
+if __name__ == "__main__":
+    main()

pdf_modifier/ai/__init__.py

@@ -0,0 +1 @@
+"""AI layer package — NaN Cloud integration."""

pdf_modifier/ai/client.py

@@ -0,0 +1,296 @@
+"""NaN Cloud API client using httpx async + null client for testing."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from ..logger import setup_logging
+from .exceptions import AIAuthenticationError, AIError, AIRateLimitError, AIServerError
+
+logger = setup_logging(__name__)
+
+DEFAULT_BASE_URL = "https://api.nan.builders/v1"
+DEFAULT_TIMEOUT = 30.0
+
+
+class NaNClient:
+    """Async HTTP client for NaN Cloud API.
+
+    Handles authentication, rate limiting retries, and error mapping.
+
+    Example:
+        >>> async with NaNClient() as client:
+        ...     msgs = [{"role": "user", "content": "Hello"}]
+        ...     result = await client.chat("mimo-v2.6-flash", msgs)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+    ) -> None:
+        # Accept either NaN Cloud or any OpenAI-compatible provider so the AI
+        # features work for more people. NaN key wins when both are present.
+        nan_key = os.environ.get("NAN_API_KEY")
+        openai_key = os.environ.get("OPENAI_API_KEY")
+        self._api_key = api_key or nan_key or openai_key or ""
+        # Base URL: explicit > NAN_BASE_URL > OPENAI_BASE_URL > provider default.
+        raw_url: str | None = (
+            base_url or os.environ.get("NAN_BASE_URL") or os.environ.get("OPENAI_BASE_URL")
+        )
+        if raw_url is None:
+            if nan_key:
+                raw_url = DEFAULT_BASE_URL
+            elif openai_key:
+                raw_url = "https://api.openai.com/v1"
+            else:
+                raw_url = DEFAULT_BASE_URL
+        self._base_url = (raw_url or DEFAULT_BASE_URL).rstrip("/")
+        self._is_nan = bool(nan_key)
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._client: httpx.AsyncClient | None = None
+
+    @property
+    def is_configured(self) -> bool:
+        """Whether an API key is available."""
+        return bool(self._api_key)
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Lazy-initialize the httpx client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                timeout=self._timeout,
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+        return self._client
+
+    async def chat(
+        self,
+        model: str,
+        messages: list[dict[str, str]],
+        temperature: float = 0.0,
+        **extra_kwargs: Any,
+    ) -> dict[str, Any]:
+        """Send a chat completion request to NaN Cloud."""
+        client = await self._get_client()
+
+        payload: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "temperature": temperature,
+            "chat_template_kwargs": {"enable_thinking": False},
+            **extra_kwargs,
+        }
+
+        last_exception: Exception | None = None
+
+        for attempt in range(self._max_retries):
+            try:
+                response = await client.post("/chat/completions", json=payload)
+
+                if response.status_code == 401:
+                    raise AIAuthenticationError("Invalid API key")
+                if response.status_code == 429:
+                    raise AIRateLimitError(
+                        f"Rate limit exceeded (attempt {attempt + 1}/{self._max_retries})"
+                    )
+                if response.status_code >= 500:
+                    raise AIServerError(f"Server error: {response.status_code}")
+                response.raise_for_status()
+
+                data: dict[str, Any] = response.json()
+                logger.debug("AI chat completed for model=%s", model)
+                return data
+
+            except (AIAuthenticationError, AIError):
+                raise
+            except httpx.HTTPStatusError:
+                raise
+            except httpx.RequestError as e:
+                last_exception = e
+                logger.warning(
+                    "AI chat attempt %d/%d failed for model=%s: %s",
+                    attempt + 1,
+                    self._max_retries,
+                    model,
+                    e,
+                )
+                if attempt < self._max_retries - 1:
+                    import asyncio
+
+                    await asyncio.sleep(2**attempt)
+
+        if last_exception:
+            raise last_exception
+        raise AIError("Chat request failed after retries")
+
+    async def embed(
+        self,
+        model: str,
+        input_text: str | list[str],
+    ) -> dict[str, Any]:
+        """Send an embedding request with retry logic."""
+        client = await self._get_client()
+
+        payload = {
+            "model": model,
+            "input": input_text,
+        }
+
+        last_exception: Exception | None = None
+
+        for attempt in range(self._max_retries):
+            try:
+                response = await client.post("/embeddings", json=payload)
+
+                if response.status_code == 401:
+                    raise AIAuthenticationError("Invalid API key")
+                if response.status_code == 429:
+                    raise AIRateLimitError(
+                        f"Rate limit exceeded (attempt {attempt + 1}/{self._max_retries})"
+                    )
+                if response.status_code >= 500:
+                    raise AIServerError(f"Server error: {response.status_code}")
+                response.raise_for_status()
+
+                data: dict[str, Any] = response.json()
+                logger.debug("AI embed completed for model=%s", model)
+                return data
+
+            except (AIAuthenticationError, AIError):
+                raise
+            except httpx.HTTPStatusError:
+                raise
+            except httpx.RequestError as e:
+                last_exception = e
+                logger.warning(
+                    "AI embed attempt %d/%d failed for model=%s: %s",
+                    attempt + 1,
+                    self._max_retries,
+                    model,
+                    e,
+                )
+                if attempt < self._max_retries - 1:
+                    import asyncio
+
+                    await asyncio.sleep(2**attempt)
+
+        if last_exception:
+            raise last_exception
+        raise AIError("Embed request failed after retries")
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> NaNClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+
+class NullAIClient:
+    """Mock AI client that returns predefined responses.
+
+    Used in unit tests to avoid real API calls.
+    """
+
+    def __init__(self) -> None:
+        self._call_count = 0
+        self._responses: dict[str, dict[str, Any]] = {
+            "chat": {
+                "choices": [
+                    {
+                        "message": {
+                            "content": (
+                                '{"fields": [{'
+                                '"name": "invoice_number", '
+                                '"value": "INV-2024-001", '
+                                '"confidence": 0.95}], '
+                                '"document_type": "invoice"}'
+                            )
+                        }
+                    }
+                ]
+            },
+            "classify": {
+                "choices": [
+                    {
+                        "message": {
+                            "content": (
+                                '{"document_type": "invoice", '
+                                '"confidence": 0.92, '
+                                '"alternatives": [{'
+                                '"type": "receipt", '
+                                '"confidence": 0.05}]}'
+                            )
+                        }
+                    }
+                ]
+            },
+            "redact": {
+                "choices": [
+                    {
+                        "message": {
+                            "content": (
+                                '{"items": [{'
+                                '"pii_type": "email", '
+                                '"value": "test@example.com", '
+                                '"suggested_replacement": "[REDACTED]"}]}'
+                            )
+                        }
+                    }
+                ]
+            },
+        }
+
+    @property
+    def is_configured(self) -> bool:
+        return True
+
+    @property
+    def call_count(self) -> int:
+        return self._call_count
+
+    async def chat(
+        self,
+        model: str,
+        messages: list[dict[str, str]],
+        temperature: float = 0.0,
+        **extra_kwargs: Any,
+    ) -> dict[str, Any]:
+        self._call_count += 1
+        return self._responses["chat"]
+
+    async def embed(
+        self,
+        model: str,
+        input_text: str | list[str],
+    ) -> dict[str, Any]:
+        self._call_count += 1
+        return {
+            "data": [{"embedding": [0.1] * 1536}],
+            "model": model,
+        }
+
+    async def close(self) -> None:
+        pass
+
+    async def __aenter__(self) -> NullAIClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

pdf_modifier/ai/exceptions.py

@@ -0,0 +1,29 @@
+"""AI exceptions for NaN Cloud operations."""
+
+from __future__ import annotations
+
+from ..core.exceptions import PDFModifierError
+
+
+class AIError(PDFModifierError):
+    """Base exception for AI operations."""
+
+    code = "AI_ERROR"
+
+
+class AIAuthenticationError(AIError):
+    """Raised when API authentication fails."""
+
+    code = "AI_AUTH_ERROR"
+
+
+class AIRateLimitError(AIError):
+    """Raised when rate limit is exceeded."""
+
+    code = "AI_RATE_LIMIT"
+
+
+class AIServerError(AIError):
+    """Raised when AI server returns an error."""
+
+    code = "AI_SERVER_ERROR"

pdf_modifier/ai/models.py

@@ -0,0 +1,81 @@
+"""AI-specific Pydantic models for NaN Cloud responses."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class DetectField(BaseModel):
+    """A detected field from document analysis."""
+
+    name: str = Field(description="Field name (e.g., 'invoice_number', 'date')")
+    value: str = Field(description="Extracted value")
+    confidence: float = Field(ge=0.0, le=1.0, description="Detection confidence (0-1)")
+    page: int | None = None
+    bbox: tuple[float, float, float, float] | None = None
+
+
+class DetectResult(BaseModel):
+    """Result of AI-powered field detection."""
+
+    success: bool = True
+    fields: list[DetectField] = Field(default_factory=list)
+    document_type: str | None = None
+    model: str = Field(description="Model used for detection")
+
+
+class ClassificationAlternative(BaseModel):
+    """Alternative classification with confidence."""
+
+    type: str = Field(description="Alternative document type")
+    confidence: float = Field(ge=0.0, le=1.0, description="Confidence score")
+
+
+class ClassifyResult(BaseModel):
+    """Result of document classification."""
+
+    success: bool = True
+    document_type: str = Field(description="Classified type (invoice, contract, CV, etc.)")
+    confidence: float = Field(ge=0.0, le=1.0)
+    alternatives: list[ClassificationAlternative] = Field(
+        default_factory=list,
+        description="Alternative classifications with confidence scores",
+    )
+    model: str = Field(description="Model used for classification")
+
+
+class RedactItem(BaseModel):
+    """A PII item found for redaction."""
+
+    pii_type: str = Field(description="Type of PII (email, phone, nif, credit_card, etc.)")
+    value: str = Field(description="The PII value found")
+    page: int | None = None
+    bbox: tuple[float, float, float, float] | None = None
+    confidence: float = Field(ge=0.0, le=1.0)
+    suggested_replacement: str = Field(
+        default="[REDACTED]", description="Suggested replacement text"
+    )
+
+
+class RedactResult(BaseModel):
+    """Result of PII redaction detection."""
+
+    success: bool = True
+    items: list[RedactItem] = Field(default_factory=list)
+    model: str = Field(description="Model used for redaction")
+
+
+class EmbeddingResult(BaseModel):
+    """Result of text embedding."""
+
+    success: bool = True
+    model: str
+    dimensions: int
+    embeddings: list[list[float]] = Field(description="List of embedding vectors")
+
+
+class EmbeddingQuery(BaseModel):
+    """Query for generating embeddings."""
+
+    model: str = Field(default="qwen3-embedding")
+    input: str | list[str] = Field(..., description="Text or list of texts to embed")

pdf_modifier/ai/prompts/__init__.py

@@ -0,0 +1,39 @@
+"""Jinja2 prompt template renderer."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader
+
+PROMPTS_DIR = Path(__file__).parent
+
+
+@lru_cache(maxsize=1)
+def get_template_env() -> Environment:
+    """Get a cached Jinja2 environment for prompt templates."""
+    return Environment(
+        loader=FileSystemLoader(str(PROMPTS_DIR)),
+        keep_trailing_newline=True,
+    )
+
+
+def render_prompt(template_name: str, **kwargs: Any) -> str:
+    """Render a prompt template with given variables.
+
+    Args:
+        template_name: Template file name (e.g., "detect_fields.j2").
+        **kwargs: Variables to substitute in the template.
+
+    Returns:
+        Rendered prompt string.
+
+    Raises:
+        FileNotFoundError: If template doesn't exist.
+    """
+    env = get_template_env()
+    template = env.get_template(template_name)
+    rendered: str = template.render(**kwargs)
+    return rendered

pdf_modifier/ai/prompts/classify_doc.j2

@@ -0,0 +1,23 @@
+You are a document classification AI. Classify the following document.
+
+Document text:
+{{ pdf_text }}
+
+Classify into one of these types:
+- invoice
+- contract
+- cv_resume
+- report
+- letter
+- receipt
+- form
+- other
+
+Return a JSON object:
+{
+  "document_type": "one_of_the_types_above",
+  "confidence": 0.95,
+  "alternatives": [
+    {"type": "second_choice", "confidence": 0.1}
+  ]
+}

pdf_modifier/ai/prompts/detect_fields.j2

@@ -0,0 +1,20 @@
+You are a document analysis AI. Analyze the following PDF text and extract structured fields.
+
+Document text:
+{{ pdf_text }}
+
+Extract all identifiable fields (invoice numbers, dates, amounts, names, addresses, etc.).
+Return a JSON object with this exact structure:
+{
+  "fields": [
+    {"name": "field_name", "value": "extracted_value", "confidence": 0.95}
+  ],
+  "document_type": "type_or_null"
+}
+
+Rules:
+- Only extract fields that are clearly present in the text
+- Confidence should reflect how certain you are (0.0-1.0)
+- Use snake_case for field names
+- If no fields are found, return empty fields array
+- Return only valid JSON (no markdown, no code fences, no extra prose)

pdf_modifier/ai/prompts/redact_pii.j2

@@ -0,0 +1,24 @@
+You are a PII redaction AI. Find all personally identifiable information in this document.
+
+Document text:
+{{ pdf_text }}
+
+Find and return all PII items including:
+- Names (person names)
+- Emails
+- Phone numbers
+- NIF/Tax IDs
+- Credit card numbers
+- Addresses
+- Dates of birth
+
+Return a JSON object:
+{
+  "items": [
+    {
+      "pii_type": "email|phone|nif|credit_card|name|address|dob|other",
+      "value": "the_found_value",
+      "suggested_replacement": "[REDACTED]"
+    }
+  ]
+}

pdf_modifier/ai/reviewer.py

@@ -0,0 +1,134 @@
+"""Optional AI consistency reviewer (NaN Cloud or any OpenAI-compatible API).
+
+The reviewer runs ONLY when an API key is configured in the environment
+(``NAN_API_KEY`` for NaN, or an OpenAI-compatible endpoint via ``NAN_BASE_URL`` +
+``AI_REVIEW_MODEL``). Without a key it ``skip``s — it is a second, semantic
+opinion layered on top of the deterministic ``ConsistencyValidator``, never a
+hard dependency, and it never blocks the replacement.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from .client import NaNClient
+from .exceptions import AIError
+from .router import ModelRouter, TaskType
+
+logger = logging.getLogger(__name__)
+
+_PROMPT = """Strictly review the target values a PDF text-replacement will write. Flag ONLY
+semantic/plausibility inconsistencies that deterministic arithmetic cannot catch, for example:
+- a total that is implausible for the stated number of nights,
+- a cancellation fee / refund that contradicts the stated policy ("cost of the first night"),
+- a date whose declared weekday is wrong for that calendar date,
+- a monetary figure that looks inconsistent with the others (a tax far from the stated rate).
+
+The values are already mutually consistent by arithmetic — do NOT report arithmetic mismatches.
+Return ONLY JSON, no prose:
+{"issues": [{"severity": "error" | "warning", "message": "...", "field": "..."}]}
+
+Target values:
+{values}
+"""
+
+
+@dataclass(frozen=True)
+class AIReviewFinding:
+    """A finding raised by the AI reviewer."""
+
+    severity: str
+    message: str
+    field: str
+
+    def __str__(self) -> str:
+        return f"[{self.severity}] {self.field}: {self.message}"
+
+
+@dataclass
+class AIReviewResult:
+    """Outcome of an AI review pass."""
+
+    skipped: bool = False
+    model: str | None = None
+    findings: list[AIReviewFinding] = field(default_factory=list)
+    error: str | None = None
+
+
+class AIReviewer:
+    """Runs a semantic consistency pass via an OpenAI-compatible chat API.
+
+    ``client`` may be injected (e.g. ``NullAIClient`` for tests). By default it
+    builds a ``NaNClient``, which reads ``NAN_API_KEY`` / ``NAN_BASE_URL`` from the
+    environment. The model defaults to the ``REVIEW`` routing (``mimo-v2.6-flash``) and
+    can be overridden via ``AI_REVIEW_MODEL``.
+    """
+
+    def __init__(self, client: Any | None = None, model: str | None = None) -> None:
+        self.client = client if client is not None else NaNClient()
+        self.model = model or os.environ.get("AI_REVIEW_MODEL") or self._default_model()
+
+    @staticmethod
+    def _default_model() -> str:
+        """Pick a sensible default model per provider (overridable via AI_REVIEW_MODEL)."""
+        if os.environ.get("NAN_API_KEY"):
+            return ModelRouter().get_model(TaskType.REVIEW)  # mimo-v2.6-flash
+        if os.environ.get("OPENAI_API_KEY"):
+            return "gpt-4o-mini"
+        return ModelRouter().get_model(TaskType.REVIEW)
+
+    def is_available(self) -> bool:
+        """Whether an API key is present (and the reviewer can actually run)."""
+        return bool(self.client.is_configured)
+
+    async def review(
+        self,
+        values: dict[str, object],
+        deterministic: dict[str, bool] | None = None,
+    ) -> AIReviewResult:
+        """Run a review pass. Returns ``skipped`` when no API key is configured."""
+        if not self.is_available():
+            return AIReviewResult(skipped=True, model=self.model)
+
+        # .replace() — the prompt contains literal braces in the JSON example, so
+        # str.format() would try to substitute them and raise KeyError.
+        prompt = _PROMPT.replace("{values}", json.dumps(values, default=str))
+        try:
+            data = await self.client.chat(
+                self.model,
+                [{"role": "user", "content": prompt}],
+                temperature=0.0,
+            )
+            content = data["choices"][0]["message"]["content"]
+            return AIReviewResult(model=self.model, findings=self._parse(content))
+        except AIError as exc:
+            logger.warning("AI review error: %s", exc)
+            return AIReviewResult(model=self.model, error=str(exc))
+        except Exception as exc:  # noqa: BLE001 — a failure must never block the caller
+            logger.warning("AI review failed unexpectedly: %s", exc)
+            return AIReviewResult(model=self.model, error=str(exc))
+
+    @staticmethod
+    def _parse(content: str) -> list[AIReviewFinding]:
+        """Best-effort parse of the model's JSON response into findings."""
+        try:
+            obj: dict[str, Any] = json.loads(content)
+        except (ValueError, TypeError):
+            return []
+        issues = obj.get("issues") or []
+        findings: list[AIReviewFinding] = []
+        for item in issues:
+            if not isinstance(item, dict):
+                continue
+            findings.append(
+                AIReviewFinding(
+                    severity=str(item.get("severity", "warning")),
+                    message=str(item.get("message", "")),
+                    field=str(item.get("field", "")),
+                )
+            )
+        return findings