processor.py

# -*- coding: utf-8 -*-
"""
processor.py - Receipt Processing Engine (Claude API)
=====================================================
Analyzes receipt images via Claude API and returns structured JSON data.

Features:
- Image preprocessing (resize, format conversion, EXIF rotation)
- PDF support (PyMuPDF -> pdf2image -> raw PDF fallback)
- Claude Sonnet 4 API with retry logic (exponential backoff)
- Response parsing with markdown/code-block stripping
- Data normalization (dates, amounts, categories)
- Cross-validation (subtotal + tax + tip = total)
- Confidence scoring and review flagging
"""

import anthropic
import json
import base64
import io
import re
import time
import os
import sys
from datetime import datetime
from PIL import Image
import logging

# ---------------------------------------------------------------------------
# Logging setup
# ---------------------------------------------------------------------------
os.makedirs("logs", exist_ok=True)

# Force UTF-8 for log file on all platforms
_log_file_handler = logging.FileHandler(
    "logs/processing.log", encoding="utf-8"
)
_log_stream_handler = logging.StreamHandler(sys.stdout)

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    handlers=[_log_file_handler, _log_stream_handler],
)
logger = logging.getLogger("ReceiptProcessor")


class ReceiptProcessor:
    """
    Processes receipt images via Claude API to extract structured data.

    Attributes:
        config (dict): Full config from config.json
        client (anthropic.Anthropic): API client
        categories (list): Valid expense categories
        MAX_RETRIES (int): Max API call retries
    """

    MAX_RETRIES = 3
    RETRY_DELAY = 2  # seconds

    def __init__(self, config: dict):
        """
        Args:
            config: Parsed config.json dict.
        Raises:
            ValueError: If API key is missing or default placeholder.
        """
        self.config = config
        api_key = config.get("api_key", "")

        if not api_key or api_key == "YOUR_API_KEY_HERE":
            raise ValueError(
                "API key not set. Edit 'api_key' in config.json."
            )

        self.model = config["claude"]["model"]
        self.max_tokens = config["claude"]["max_tokens"]
        self.temperature = config["claude"]["temperature"]
        self.categories = config["categories"]
        self.confidence_threshold = config["validation"]["confidence_threshold"]
        self.review_threshold = config["validation"]["flag_for_review_threshold"]

        self.client = anthropic.Anthropic(
            api_key=api_key,
            timeout=60.0,
            max_retries=0,  # We handle retries ourselves
        )

        logger.info("ReceiptProcessor initialized (model: %s)", self.model)

    # ======================================================================
    # Main entry point
    # ======================================================================
    def process_receipt(self, image_path: str) -> dict:
        """
        Analyze a receipt image and return structured data.

        Flow:
        1. Load & preprocess image (resize, base64 encode)
        2. Call Claude API (with retry)
        3. Parse JSON response
        4. Normalize data (types, formats)
        5. Cross-validate amounts
        6. Validate required fields
        7. Determine review status

        Args:
            image_path: Path to the receipt image file.

        Returns:
            dict with keys: success, data, confidence, needs_review, issue, error
        """
        logger.info("Processing: %s", os.path.basename(image_path))

        try:
            # 1) Load image
            image_data, media_type = self._load_and_prepare_image(image_path)
            if image_data is None:
                return self._error_result("Failed to read image file")

            # 2) Call Claude API
            raw_response = self._call_api_with_retry(image_data, media_type)
            if raw_response is None:
                return self._error_result("API call failed (all retries exhausted)")

            # 3) Parse response
            data = self._parse_response(raw_response)
            if data is None:
                return self._error_result("Failed to parse API response")

            # 4) Normalize
            data = self._normalize_data(data)

            # 5) Cross-validate amounts
            data = self._cross_validate_amounts(data)

            # 6) Validate required fields
            is_valid, errors = self._validate_data(data)

            if not is_valid:
                logger.warning("Validation failed: %s", errors)
                return {
                    "success": True,
                    "data": data,
                    "confidence": data.get("confidence", 0.5),
                    "needs_review": True,
                    "issue": " / ".join(errors),
                    "error": None,
                }

            # 7) Confidence check
            confidence = data.get("confidence", 0.0)
            needs_review = confidence < self.review_threshold
            issue = self._identify_issues(data, confidence) if needs_review else None

            logger.info(
                "Done: %s | $%.2f | %s | confidence %.0f%%",
                data.get("vendor", "?"),
                data.get("total", 0),
                data.get("category", "?"),
                confidence * 100,
            )

            return {
                "success": True,
                "data": data,
                "confidence": confidence,
                "needs_review": needs_review,
                "issue": issue,
                "error": None,
            }

        except Exception as e:
            logger.error("Unexpected error: %s", str(e), exc_info=True)
            return self._error_result(str(e))

    # ======================================================================
    # Image loading
    # ======================================================================
    def _load_and_prepare_image(self, image_path: str):
        """
        Load image and convert to base64 for API.
        Handles JPEG/PNG/WEBP via PIL, PDF via PyMuPDF/pdf2image/raw.

        Returns:
            tuple: (base64_string, media_type) or (None, None)
        """
        try:
            ext = os.path.splitext(image_path)[1].lower()

            if ext == ".pdf":
                return self._load_pdf(image_path)

            with Image.open(image_path) as img:
                # Apply EXIF rotation (phone photos)
                try:
                    from PIL import ImageOps
                    img = ImageOps.exif_transpose(img)
                except Exception:
                    pass

                logger.info(
                    "Image loaded: %s (%dx%d, %s)",
                    os.path.basename(image_path),
                    img.width,
                    img.height,
                    img.mode,
                )
                return self._pil_to_base64(img)

        except Exception as e:
            logger.error("Image load failed: %s", str(e))
            return None, None

    def _pil_to_base64(self, img: Image.Image):
        """Convert PIL Image to base64 JPEG."""
        # Handle transparency (PNG, etc.)
        if img.mode in ("RGBA", "LA", "P"):
            bg = Image.new("RGB", img.size, (255, 255, 255))
            if img.mode == "P":
                img = img.convert("RGBA")
            if "A" in img.mode:
                bg.paste(img, mask=img.split()[-1])
            else:
                bg.paste(img)
            img = bg
        elif img.mode != "RGB":
            img = img.convert("RGB")

        # Resize if too large (max 2048px on longest side)
        max_dim = 2048
        if max(img.width, img.height) > max_dim:
            img.thumbnail((max_dim, max_dim), Image.Resampling.LANCZOS)
            logger.info("Resized to: %dx%d", img.width, img.height)

        if min(img.width, img.height) < 200:
            logger.warning("Image is very small (%dx%d)", img.width, img.height)

        buf = io.BytesIO()
        img.save(buf, format="JPEG", quality=90, optimize=True)
        b64 = base64.b64encode(buf.getvalue()).decode("ascii")
        return b64, "image/jpeg"

    def _load_pdf(self, pdf_path: str):
        """
        Load PDF - tries 3 methods in order:
        1. PyMuPDF (fitz) - best quality
        2. pdf2image (poppler) - requires system dependency
        3. Raw PDF base64 - Claude can read PDFs directly
        """
        logger.info("Loading PDF: %s", os.path.basename(pdf_path))

        # Method 1: PyMuPDF
        try:
            import fitz
            doc = fitz.open(pdf_path)
            if len(doc) == 0:
                logger.error("PDF has no pages")
                return None, None
            page = doc[0]
            mat = fitz.Matrix(200 / 72, 200 / 72)  # 200 DPI
            pix = page.get_pixmap(matrix=mat)
            img = Image.frombytes("RGB", [pix.width, pix.height], pix.samples)
            doc.close()
            logger.info("PDF converted via PyMuPDF: %dx%d", img.width, img.height)
            return self._pil_to_base64(img)
        except ImportError:
            logger.info("PyMuPDF not installed, trying alternatives")
        except Exception as e:
            logger.warning("PyMuPDF failed: %s", str(e))

        # Method 2: pdf2image
        try:
            from pdf2image import convert_from_path
            images = convert_from_path(pdf_path, first_page=1, last_page=1, dpi=200)
            if images:
                logger.info("PDF converted via pdf2image: %dx%d", images[0].width, images[0].height)
                return self._pil_to_base64(images[0])
        except ImportError:
            logger.info("pdf2image not installed, trying raw PDF")
        except Exception as e:
            logger.warning("pdf2image failed: %s", str(e))

        # Method 3: Send raw PDF (Claude supports PDF directly)
        try:
            with open(pdf_path, "rb") as f:
                pdf_bytes = f.read()
            b64 = base64.b64encode(pdf_bytes).decode("ascii")
            logger.info("Sending raw PDF (%d bytes)", len(pdf_bytes))
            return b64, "application/pdf"
        except Exception as e:
            logger.error("PDF load failed completely: %s", str(e))
            return None, None

    # ======================================================================
    # API call with retry
    # ======================================================================
    def _call_api_with_retry(self, data_b64: str, media_type: str):
        """
        Call Claude API with exponential backoff retry.

        - RateLimitError: retry with backoff
        - APIConnectionError: retry with backoff
        - 5xx errors: retry with backoff
        - 4xx errors: fail immediately (bad request / invalid key)

        Returns:
            str: Response text, or None on failure.
        """
        prompt = self._build_extraction_prompt()

        for attempt in range(1, self.MAX_RETRIES + 1):
            try:
                logger.info("API call (attempt %d/%d)", attempt, self.MAX_RETRIES)

                # Build content blocks based on media type
                if media_type == "application/pdf":
                    content_blocks = [
                        {
                            "type": "document",
                            "source": {
                                "type": "base64",
                                "media_type": "application/pdf",
                                "data": data_b64,
                            },
                        },
                        {"type": "text", "text": prompt},
                    ]
                else:
                    content_blocks = [
                        {
                            "type": "image",
                            "source": {
                                "type": "base64",
                                "media_type": media_type,
                                "data": data_b64,
                            },
                        },
                        {"type": "text", "text": prompt},
                    ]

                message = self.client.messages.create(
                    model=self.model,
                    max_tokens=self.max_tokens,
                    temperature=self.temperature,
                    messages=[{"role": "user", "content": content_blocks}],
                )

                if message.content and len(message.content) > 0:
                    text = message.content[0].text
                    logger.info("API response received (%d chars)", len(text))
                    return text
                else:
                    logger.warning("Empty response from API")
                    return None

            except anthropic.RateLimitError:
                wait = self.RETRY_DELAY * (2 ** (attempt - 1))
                logger.warning("Rate limited - waiting %ds", wait)
                time.sleep(wait)

            except anthropic.APIConnectionError as e:
                wait = self.RETRY_DELAY * attempt
                logger.warning("Connection error: %s - retrying in %ds", str(e), wait)
                time.sleep(wait)

            except anthropic.APIStatusError as e:
                logger.error("API error (%d): %s", e.status_code, str(e))
                if e.status_code >= 500:
                    time.sleep(self.RETRY_DELAY * attempt)
                    continue
                return None  # 4xx = don't retry

            except Exception as e:
                logger.error("Unexpected API error: %s", str(e))
                if attempt < self.MAX_RETRIES:
                    time.sleep(self.RETRY_DELAY)
                    continue
                return None

        logger.error("Max retries exhausted")
        return None

    # ======================================================================
    # Prompt
    # ======================================================================
    def _build_extraction_prompt(self) -> str:
        """Build the extraction prompt for Claude."""
        categories_list = "\n".join(f"  - {c}" for c in self.categories)

        return f"""Analyze this US receipt image carefully. Extract ALL information into a JSON object.

CRITICAL INSTRUCTIONS:
1. Read EVERY line of text on the receipt carefully before extracting.
2. The date format MUST be MM/DD/YYYY. If the year is 2-digit (e.g. "24"), convert to 4-digit (2024).
3. ALL monetary values must be plain numbers (no $ sign in JSON values).
4. Separate subtotal, tax, and tip clearly.
5. If the receipt is from a restaurant and tip is written by hand, estimate it carefully.
6. For vendor name, use the OFFICIAL business name (e.g., "Walmart Supercenter", "Starbucks Coffee").
7. Extract the full address if visible and provide city + state.
8. State must be a 2-letter US state code (e.g., "TX", "CA", "NY").
9. For payment method, look for "VISA", "MASTERCARD", "AMEX", "DISCOVER", "DEBIT", "CASH", etc.
10. For card_last_4, extract only the last 4 digits of the card number if shown.

MATHEMATICAL VERIFICATION:
- Verify: subtotal + tax + tip = total (within $0.02 tolerance)
- If tip is not present (non-restaurant), set tip to 0.
- If subtotal is not separately shown, calculate: subtotal = total - tax - tip

CATEGORY SELECTION (choose the BEST match):
{categories_list}

Category hints:
- Restaurants, cafes, fast food -> "Meals & Entertainment"
- Uber, Lyft, taxi, subway -> "Transportation"
- Hotels, motels, Airbnb -> "Lodging"
- Staples, Amazon office items -> "Office Supplies"
- Gas stations, fuel -> "Gas & Fuel"
- Parking meters, toll roads -> "Parking & Tolls"
- Phone, internet -> "Communication"
- Client dinners, entertainment with clients -> "Client Entertainment"
- Flights, car rentals, travel-related -> "Travel Expenses"
- Anything else -> "Miscellaneous"

CONFIDENCE SCORING:
- 0.95 to 1.0: ALL fields clearly readable, no ambiguity
- 0.85 to 0.94: One or two fields slightly unclear but best-guessed
- 0.70 to 0.84: Several fields hard to read, some guessing involved
- Below 0.70: Major portions unreadable, high uncertainty

RESPOND WITH ONLY THIS JSON STRUCTURE (no markdown, no explanation, no backticks):
{{
  "date": "MM/DD/YYYY or null if unreadable",
  "vendor": "Official business name",
  "location": "City, ST",
  "state": "XX",
  "subtotal": 0.00,
  "tax": 0.00,
  "tip": 0.00,
  "total": 0.00,
  "payment_method": "VISA/MASTERCARD/AMEX/DISCOVER/DEBIT/CASH/null",
  "card_last_4": "1234 or null",
  "category": "Category name from list above",
  "confidence": 0.95,
  "notes": "Any uncertainties, handwritten amounts, or special observations"
}}"""

    # ======================================================================
    # Response parsing
    # ======================================================================
    def _parse_response(self, response_text: str) -> dict:
        """
        Extract JSON from Claude response.
        Handles markdown code blocks, surrounding text, etc.
        """
        try:
            cleaned = response_text.strip()

            # Strip markdown code blocks
            if "```" in cleaned:
                match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", cleaned)
                if match:
                    cleaned = match.group(1)

            # Extract JSON object
            json_match = re.search(r"\{[\s\S]*\}", cleaned)
            if json_match:
                cleaned = json_match.group(0)

            data = json.loads(cleaned)

            if not isinstance(data, dict):
                logger.error("Parsed JSON is not a dict: %s", type(data))
                return None

            return data

        except json.JSONDecodeError as e:
            logger.error("JSON parse error: %s", str(e))
            logger.error("Raw response (first 300 chars): %s", response_text[:300])
            return None
        except Exception as e:
            logger.error("Parse error: %s", str(e))
            return None

    # ======================================================================
    # Data normalization
    # ======================================================================
    def _normalize_data(self, data: dict) -> dict:
        """
        Normalize extracted data types and formats:
        - Amounts: convert to float, strip $ and commas
        - Date: normalize to MM/DD/YYYY
        - Strings: strip whitespace, convert null-like to None
        - Category: map to closest valid category
        - card_last_4: digits only, last 4
        """
        # Amount fields
        for key in ("subtotal", "tax", "tip", "total"):
            val = data.get(key)
            if val is None or val == "" or val == "null":
                data[key] = 0.0
            elif isinstance(val, str):
                cleaned = re.sub(r"[^\d.\-]", "", val)
                try:
                    data[key] = round(float(cleaned), 2) if cleaned else 0.0
                except ValueError:
                    data[key] = 0.0
            else:
                data[key] = round(float(val), 2)

        # Date
        date_val = data.get("date")
        if date_val and isinstance(date_val, str) and date_val.lower() != "null":
            data["date"] = self._normalize_date(date_val)
        else:
            data["date"] = None

        # String fields
        for key in (
            "vendor", "location", "state", "payment_method",
            "card_last_4", "category", "notes",
        ):
            val = data.get(key)
            if val and isinstance(val, str):
                val = val.strip()
                if val.lower() in ("null", "none", "n/a", ""):
                    data[key] = None
                else:
                    data[key] = val
            else:
                data[key] = None

        # State code (2-letter uppercase)
        if data.get("state"):
            state = data["state"].upper().strip()
            data["state"] = state if (len(state) == 2 and state.isalpha()) else None

        # Card last 4 digits
        if data.get("card_last_4"):
            digits = re.sub(r"\D", "", str(data["card_last_4"]))
            data["card_last_4"] = digits[-4:] if len(digits) >= 4 else (digits or None)

        # Category validation/correction
        if data.get("category") not in self.categories:
            data["category"] = self._find_closest_category(data.get("category", ""))

        # Confidence
        conf = data.get("confidence")
        if conf is None or not isinstance(conf, (int, float)):
            data["confidence"] = 0.5
        else:
            data["confidence"] = max(0.0, min(1.0, float(conf)))

        # Ensure all expected keys exist
        defaults = {
            "date": None, "vendor": None, "location": None,
            "state": None, "subtotal": 0.0, "tax": 0.0,
            "tip": 0.0, "total": 0.0, "payment_method": None,
            "card_last_4": None, "category": "Miscellaneous",
            "confidence": 0.5, "notes": None,
        }
        for k, v in defaults.items():
            if k not in data:
                data[k] = v

        return data

    def _normalize_date(self, date_str: str) -> str:
        """
        Convert various date formats to MM/DD/YYYY.
        Supports: MM/DD/YYYY, YYYY-MM-DD, MM/DD/YY, "Jan 15, 2024", etc.
        """
        date_str = date_str.strip()

        # Numeric patterns: MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, MM/DD/YY
        patterns = [
            r"^(\d{1,2})[/\-.](\d{1,2})[/\-.](\d{4})$",
            r"^(\d{1,2})[/\-.](\d{1,2})[/\-.](\d{2})$",
            r"^(\d{4})[/\-.](\d{1,2})[/\-.](\d{1,2})$",
        ]

        for pattern in patterns:
            match = re.match(pattern, date_str)
            if match:
                groups = match.groups()
                if len(groups[0]) == 4:  # ISO format YYYY-MM-DD
                    y, m, d = int(groups[0]), int(groups[1]), int(groups[2])
                elif len(groups[2]) == 2:  # 2-digit year
                    m, d, y = int(groups[0]), int(groups[1]), int(groups[2])
                    y = 2000 + y if y < 50 else 1900 + y
                else:
                    m, d, y = int(groups[0]), int(groups[1]), int(groups[2])

                try:
                    dt = datetime(y, m, d)
                    return dt.strftime("%m/%d/%Y")
                except ValueError:
                    pass

        # English month: "Jan 15, 2024" / "January 15, 2024"
        month_names = {
            "jan": 1, "feb": 2, "mar": 3, "apr": 4, "may": 5, "jun": 6,
            "jul": 7, "aug": 8, "sep": 9, "oct": 10, "nov": 11, "dec": 12,
        }
        match = re.match(r"([A-Za-z]+)\s+(\d{1,2}),?\s+(\d{4})", date_str)
        if match:
            month_str = match.group(1)[:3].lower()
            if month_str in month_names:
                try:
                    dt = datetime(
                        int(match.group(3)), month_names[month_str], int(match.group(2))
                    )
                    return dt.strftime("%m/%d/%Y")
                except ValueError:
                    pass

        logger.warning("Date normalization failed (keeping original): %s", date_str)
        return date_str

    def _find_closest_category(self, input_cat: str) -> str:
        """Map input to the closest valid category using keyword matching."""
        if not input_cat:
            return "Miscellaneous"

        input_lower = input_cat.lower()

        keyword_map = {
            "meal": "Meals & Entertainment",
            "food": "Meals & Entertainment",
            "restaurant": "Meals & Entertainment",
            "dining": "Meals & Entertainment",
            "coffee": "Meals & Entertainment",
            "lunch": "Meals & Entertainment",
            "dinner": "Meals & Entertainment",
            "breakfast": "Meals & Entertainment",
            "transport": "Transportation",
            "uber": "Transportation",
            "lyft": "Transportation",
            "taxi": "Transportation",
            "ride": "Transportation",
            "hotel": "Lodging",
            "lodg": "Lodging",
            "motel": "Lodging",
            "airbnb": "Lodging",
            "inn": "Lodging",
            "office": "Office Supplies",
            "supply": "Office Supplies",
            "supplie": "Office Supplies",
            "stationer": "Office Supplies",
            "client": "Client Entertainment",
            "entertain": "Client Entertainment",
            "travel": "Travel Expenses",
            "flight": "Travel Expenses",
            "airline": "Travel Expenses",
            "rental": "Travel Expenses",
            "gas": "Gas & Fuel",
            "fuel": "Gas & Fuel",
            "petrol": "Gas & Fuel",
            "shell": "Gas & Fuel",
            "chevron": "Gas & Fuel",
            "park": "Parking & Tolls",
            "toll": "Parking & Tolls",
            "phone": "Communication",
            "internet": "Communication",
            "telecom": "Communication",
            "wireless": "Communication",
        }

        for keyword, category in keyword_map.items():
            if keyword in input_lower:
                return category

        # Exact match (case-insensitive)
        for cat in self.categories:
            if cat.lower() == input_lower:
                return cat

        return "Miscellaneous"

    # ======================================================================
    # Amount cross-validation
    # ======================================================================
    def _cross_validate_amounts(self, data: dict) -> dict:
        """
        Verify subtotal + tax + tip ~= total.
        Auto-correct when possible, flag discrepancies.
        """
        subtotal = data.get("subtotal", 0.0)
        tax = data.get("tax", 0.0)
        tip = data.get("tip", 0.0)
        total = data.get("total", 0.0)

        if total <= 0:
            if subtotal > 0:
                data["total"] = round(subtotal + tax + tip, 2)
                data["notes"] = self._append_note(
                    data.get("notes"), "Total auto-calculated (subtotal+tax+tip)"
                )
            return data

        calculated = round(subtotal + tax + tip, 2)
        diff = abs(calculated - total)

        if diff <= 0.02:
            return data  # Within tolerance

        # If subtotal is 0, back-calculate it
        if subtotal == 0 and total > 0:
            data["subtotal"] = round(total - tax - tip, 2)
            data["notes"] = self._append_note(
                data.get("notes"), "Subtotal back-calculated (total-tax-tip)"
            )
        elif diff > 0.02:
            data["notes"] = self._append_note(
                data.get("notes"),
                f"Amount mismatch: {subtotal}+{tax}+{tip}={calculated} vs total={total}",
            )
            data["confidence"] = min(data.get("confidence", 1.0), 0.88)

        return data

    @staticmethod
    def _append_note(existing, new_note: str) -> str:
        """Append to notes field."""
        if existing and str(existing).strip():
            return f"{str(existing).strip()} | {new_note}"
        return new_note

    # ======================================================================
    # Validation
    # ======================================================================
    def _validate_data(self, data: dict) -> tuple:
        """
        Validate extracted data. Returns (is_valid, error_list).
        """
        errors = []

        if not data.get("vendor"):
            errors.append("Missing vendor name")

        if not data.get("total") or data["total"] <= 0:
            errors.append("Missing or zero total amount")

        # Date format check
        if data.get("date"):
            try:
                parsed = datetime.strptime(data["date"], "%m/%d/%Y")
                if parsed > datetime.now():
                    errors.append("Future date")
                if parsed.year < 2015:
                    errors.append("Date too old")
            except ValueError:
                errors.append(f"Invalid date format: {data['date']}")

        # Amount range
        total = data.get("total", 0)
        max_amt = self.config["validation"]["max_amount"]
        if total > max_amt:
            errors.append(f"High amount (${total:,.2f})")

        # Negative amounts
        for key in ("subtotal", "tax", "tip", "total"):
            if data.get(key, 0) < 0:
                errors.append(f"Negative {key}")

        # Category
        if data.get("category") not in self.categories:
            errors.append(f"Invalid category: {data.get('category')}")

        return (len(errors) == 0, errors)

    def _identify_issues(self, data: dict, confidence: float) -> str:
        """Identify why review is needed."""
        issues = []

        if confidence < 0.7:
            issues.append("Very low confidence")
        elif confidence < self.review_threshold:
            issues.append("Low confidence")

        if not data.get("vendor"):
            issues.append("Unclear vendor")
        if not data.get("date"):
            issues.append("Unclear date")
        if data.get("total", 0) > 500:
            issues.append("High amount")

        notes = data.get("notes") or ""
        if any(w in notes.lower() for w in ("unclear", "uncertain", "unreadable", "blurry", "handwritten")):
            issues.append("Hard to read sections")

        return " / ".join(issues) if issues else "Review needed"

    # ======================================================================
    # Utility
    # ======================================================================
    @staticmethod
    def _error_result(error_msg: str) -> dict:
        """Create standardized error result."""
        return {
            "success": False,
            "data": None,
            "confidence": 0.0,
            "needs_review": False,
            "issue": None,
            "error": error_msg,
        }