ocrcontext 0.1.0__py3-none-any.whl

ocrcontext/llm/extractor.py

@@ -0,0 +1,63 @@
+"""LLM-agnostic structured extraction via LangChain's ``with_structured_output``.
+
+Give it any Pydantic schema and a chat model; get a populated model instance
+back. The Invoice schema in :mod:`ocrcontext.llm.schemas` is auto-detected so it
+uses the verbatim invoice prompt, but any schema works.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar
+
+from pydantic import BaseModel
+
+from .schemas import INVOICE_EXTRACTION_PROMPT, Invoice
+
+if TYPE_CHECKING:
+    from langchain_core.language_models import BaseChatModel
+
+TSchema = TypeVar("TSchema", bound=BaseModel)
+
+_GENERIC_PROMPT = (
+    "You are an expert document data extraction assistant. The text may come from "
+    "OCR and may contain scanning errors and missing characters. Extract the "
+    "requested fields faithfully from the document text. Do not invent values: if a "
+    "field is not present in the text, leave it null/empty. Preserve the document's "
+    "original language for textual fields and do not translate."
+)
+
+
+class StructuredExtractor:
+    """Extract a Pydantic schema from raw text using an injected chat model."""
+
+    def __init__(self, llm: "BaseChatModel") -> None:
+        self._llm = llm
+
+    def extract(
+        self,
+        text: str,
+        schema: type[TSchema],
+        *,
+        language: str = "auto",
+        system_prompt: str | None = None,
+    ) -> TSchema:
+        from langchain_core.messages import HumanMessage, SystemMessage
+
+        system = system_prompt or self._default_prompt(schema)
+        user = (
+            f"Language Context: {language}\n"
+            f"Extract detailed data from this document text:\n\n{text}"
+        )
+
+        structured = self._llm.with_structured_output(schema)
+        result = structured.invoke(
+            [SystemMessage(content=system), HumanMessage(content=user)]
+        )
+        # with_structured_output returns an instance of `schema`.
+        return result  # type: ignore[return-value]
+
+    @staticmethod
+    def _default_prompt(schema: type[BaseModel]) -> str:
+        if schema is Invoice:
+            return INVOICE_EXTRACTION_PROMPT
+        return _GENERIC_PROMPT

ocrcontext/llm/formatting.py

@@ -0,0 +1,39 @@
+"""Plain-text formatting, ported from lib/ocr/plain-text-format.ts.
+
+Strip Markdown syntax so the model's structured output stays clean plain text
+while keeping layout (blank lines, headings, bullets).
+"""
+
+from __future__ import annotations
+
+import re
+
+_HEADING_RE = re.compile(r"^\s{0,3}#{1,6}\s+")
+_BLOCKQUOTE_RE = re.compile(r"^(\s{0,3})>\s?")
+_BULLET_RE = re.compile(r"^(\s*)[-*+]\s+")
+_CODE_FENCE_RE = re.compile(r"```[^\n`]*\n?")
+_BOLD_RE = re.compile(r"\*\*([^*\n]+)\*\*")
+_UNDERSCORE_BOLD_RE = re.compile(r"__([^_\n]+)__")
+_INLINE_CODE_RE = re.compile(r"`([^`\n]+)`")
+_TRAILING_WS_RE = re.compile(r"[ \t]+$", re.MULTILINE)
+_EXTRA_BLANKS_RE = re.compile(r"\n{3,}")
+
+
+def strip_markdown_formatting(text: str, *, convert_bullets: bool = False) -> str:
+    lines = []
+    for line in text.split("\n"):
+        line = _HEADING_RE.sub("", line)
+        line = _BLOCKQUOTE_RE.sub(r"\1", line)
+        if convert_bullets:
+            line = _BULLET_RE.sub(r"\1• ", line)
+        lines.append(line)
+
+    result = "\n".join(lines)
+    result = _CODE_FENCE_RE.sub("", result)
+    result = _BOLD_RE.sub(r"\1", result)
+    result = _UNDERSCORE_BOLD_RE.sub(r"\1", result)
+    result = _INLINE_CODE_RE.sub(r"\1", result)
+    result = _TRAILING_WS_RE.sub("", result)
+    result = _EXTRA_BLANKS_RE.sub("\n\n", result)
+
+    return result.strip()

ocrcontext/llm/literal_preserve.py

@@ -0,0 +1,164 @@
+"""Literal / contact-data preservation, ported from lib/ocr/literal-preserve.ts.
+
+Emails, URLs, IBANs and card numbers are masked to ``{{OCRLITn}}`` placeholders
+before the LLM sees the text and restored verbatim afterwards, so the model
+cannot "fix" identifiers (e.g. bahadrkrsl@... -> bahadirkarsli@...).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Placeholders injected before LLM refine; restored verbatim after.
+def _token_for(index: int) -> str:
+    return f"{{{{OCRLIT{index}}}}}"
+
+
+EMAIL_PATTERN = re.compile(
+    r"[a-zA-Z0-9](?:[a-zA-Z0-9._%+-]*[a-zA-Z0-9])?"
+    r"@[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?\.[a-zA-Z]{2,}"
+)
+
+_LITERAL_PATTERNS: list[re.Pattern[str]] = [
+    EMAIL_PATTERN,
+    re.compile(r"https?://[^\s<>\"'\])}+]+", re.IGNORECASE),
+    re.compile(r"www\.[a-zA-Z0-9][a-zA-Z0-9.-]*\.[a-zA-Z]{2,}[^\s<>\"']*", re.IGNORECASE),
+    re.compile(r"\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b"),
+    re.compile(r"\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b"),
+]
+
+
+@dataclass
+class MaskResult:
+    masked_text: str
+    literals: list[str]
+
+
+def preprocess_literal_text(text: str) -> str:
+    """OCR often inserts spaces/newlines around @ - join before masking."""
+    text = re.sub(
+        r"([a-zA-Z0-9._%+-]+)\s*\n\s*@\s*([a-zA-Z0-9][a-zA-Z0-9.-]*)", r"\1@\2", text
+    )
+    text = re.sub(
+        r"([a-zA-Z0-9._%+-]+)\s+@\s+([a-zA-Z0-9][a-zA-Z0-9.-]*)", r"\1@\2", text
+    )
+    return text
+
+
+def extract_emails(text: str) -> list[str]:
+    normalized = preprocess_literal_text(text)
+    return [m.group(0) for m in EMAIL_PATTERN.finditer(normalized)]
+
+
+def _levenshtein(a: str, b: str) -> int:
+    m, n = len(a), len(b)
+    dp = [[0] * (n + 1) for _ in range(m + 1)]
+    for i in range(m + 1):
+        dp[i][0] = i
+    for j in range(n + 1):
+        dp[0][j] = j
+    for i in range(1, m + 1):
+        for j in range(1, n + 1):
+            cost = 0 if a[i - 1] == b[j - 1] else 1
+            dp[i][j] = min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost)
+    return dp[m][n]
+
+
+def _is_likely_same_email(candidate: str, original: str) -> bool:
+    c = candidate.lower().split("@")
+    o = original.lower().split("@")
+    if len(c) != 2 or len(o) != 2:
+        return False
+    c_local, c_domain = c
+    o_local, o_domain = o
+    if not c_local or not o_local or c_domain != o_domain:
+        return False
+    if candidate == original:
+        return True
+    max_dist = max(2, int(len(o_local) * 0.35))
+    return _levenshtein(c_local, o_local) <= max_dist
+
+
+def enforce_original_literals(original_text: str, refined_text: str) -> str:
+    """Force the OCR/original email spelling back if the model rewrote it."""
+    originals = extract_emails(original_text)
+    if not originals:
+        return refined_text
+
+    output = refined_text
+    for orig in originals:
+        parts = orig.split("@")
+        if len(parts) != 2:
+            continue
+        domain = parts[1]
+        if not domain:
+            continue
+        domain_escaped = re.escape(domain)
+        domain_re = re.compile(
+            r"[a-zA-Z0-9](?:[a-zA-Z0-9._%+-]*[a-zA-Z0-9])?@" + domain_escaped,
+            re.IGNORECASE,
+        )
+
+        def _replace(match: re.Match[str], _orig: str = orig) -> str:
+            text = match.group(0)
+            if text == _orig:
+                return _orig
+            return _orig if _is_likely_same_email(text, _orig) else text
+
+        output = domain_re.sub(_replace, output)
+
+    return output
+
+
+def _collect_non_overlapping_spans(text: str) -> list[tuple[int, int, str]]:
+    spans: list[tuple[int, int, str]] = []
+    for pattern in _LITERAL_PATTERNS:
+        for match in pattern.finditer(text):
+            spans.append((match.start(), match.end(), match.group(0)))
+
+    # start asc; at equal start, the longer span wins (so it is kept, shorter dropped).
+    spans.sort(key=lambda s: (s[0], -s[1]))
+
+    merged: list[tuple[int, int, str]] = []
+    for span in spans:
+        if not merged or span[0] >= merged[-1][1]:
+            merged.append(span)
+    return merged
+
+
+def mask_protected_literals(text: str) -> MaskResult:
+    preprocessed = preprocess_literal_text(text)
+    spans = _collect_non_overlapping_spans(preprocessed)
+    literals: list[str] = []
+    masked_text = ""
+    cursor = 0
+    for start, end, value in spans:
+        masked_text += preprocessed[cursor:start]
+        literals.append(value)
+        masked_text += _token_for(len(literals) - 1)
+        cursor = end
+    masked_text += preprocessed[cursor:]
+    return MaskResult(masked_text=masked_text, literals=literals)
+
+
+def unmask_protected_literals(text: str, literals: list[str]) -> str:
+    output = text
+    for i, literal in enumerate(literals):
+        placeholder = _token_for(i)
+        if placeholder in output:
+            output = output.replace(placeholder, literal)
+            continue
+        fuzzy = re.compile(r"\{\{\s*OCRLIT\s*" + str(i) + r"\s*\}\}", re.IGNORECASE)
+        output = fuzzy.sub(literal, output)
+    return output
+
+
+LITERAL_PRESERVE_PROMPT = """
+LITERAL / CONTACT DATA (CRITICAL):
+- Tokens like {{OCRLIT0}}, {{OCRLIT1}}, ... are frozen placeholders for emails, URLs, IBANs, and similar identifiers.
+- Copy every {{OCRLITn}} token EXACTLY — same spelling, same characters, same position in the sentence.
+- NEVER "fix", complete, or guess emails/usernames (e.g. do NOT change bahadrkrsl@outlook.com to bahadirkarsli@outlook.com).
+- NEVER invent @ symbols or domains. If a placeholder is present, output it unchanged.
+- Apply OCR fixes only to normal words around these placeholders, not to the placeholders themselves.
+"""

ocrcontext/llm/prompts.py

@@ -0,0 +1,157 @@
+"""Refinement prompts, ported VERBATIM from lib/ocr/refine.ts.
+
+These prompts were heavily tuned for fidelity; do not paraphrase them. Model
+selection (gpt-4.1 vs gpt-4o) is intentionally dropped — the chat model is
+injected by the caller. Only the per-mode temperature recommendation is kept.
+"""
+
+from __future__ import annotations
+
+from ..types import RefinementMode
+from ..utils.lang import language_full_name
+from .literal_preserve import LITERAL_PRESERVE_PROMPT
+
+
+def refine_temperature(mode: RefinementMode) -> float:
+    """Deterministic for handwriting/conservative; light creativity for layout."""
+    if mode == RefinementMode.CONSERVATIVE:
+        return 0.0
+    if mode == RefinementMode.HANDWRITING_PROSE:
+        return 0.0
+    if mode == RefinementMode.HANDWRITING_LAYOUT:
+        return 0.0
+    return 0.1
+
+
+_LAYOUT = """
+  LAYOUT MODE (for digital PDFs):
+  - Reconstruct clean document structure in plain text.
+  - Keep clear section separation with blank lines between paragraphs/sections.
+  - Preserve list structure as plain text list items (no markdown markers unless present in source).
+  - Preserve the original reading order and do not merge unrelated sections.
+"""
+
+_HANDWRITING_LAYOUT = """
+  HANDWRITING LAYOUT MODE (for handwritten notes, lists, tables and diagrams of any topic):
+  - FIDELITY FIRST: stay faithful to what is actually written. Your job is to fix OCR errors, NOT to
+    improve the text. Do NOT paraphrase, summarize, complete unfinished sentences, smooth awkward
+    phrasing, or add connecting words. A slightly awkward but faithful transcription is the goal.
+  - Fix only clear OCR errors: missing diacritics, visually confused letters, and words the OCR split
+    or joined. If a word is plausible as written, keep it exactly.
+  - If a word or phrase is illegible, give your closest LITERAL character reading. NEVER replace it
+    with a fluent but made-up sentence, and never add facts that are not in the source. It is better
+    to leave a rough/partial phrase than to invent a clean one.
+  - Remove lines that are ONLY margin ruler numbers (e.g. lone "23", "2213").
+  - PRESERVE all of the source's content: keep every heading, label, list item, definition,
+    and arrow ("→") line. Never drop a line. If you are unsure about a line, keep it.
+  - PRESERVE THE ORIGINAL ORDER: keep lines and sentences in the exact order they appear in the source.
+    Do NOT reorder, move, or merge sentences to make the text flow better. If the source order looks
+    odd, leave it odd — do not "fix" it.
+  - Keep numbered lists and definition paragraphs as they are; fix only OCR errors in them.
+  - LAYOUT: only tidy spacing — keep the source's own line and section breaks, put each existing heading
+    on its own line, leave ONE blank line between existing sections, and use "• " for bullets that are
+    already bullets. Do NOT restructure content. Keep it PLAIN TEXT: no Markdown symbols (#, *, _,
+    backticks, >) and no code fences.
+  - Do NOT translate.
+"""
+
+_HANDWRITING_PROSE = """
+  HANDWRITING PROSE MODE (poems, paragraphs, letters, notes — no sensitive data):
+  - FIDELITY FIRST: fix OCR errors but stay faithful to what is written. Do NOT paraphrase, rewrite
+    style, complete unfinished sentences, or add new words/sentences/ideas.
+  - Fix OCR errors: missing diacritics, visually confused letters, and words the OCR split or joined
+    (e.g. "düşünmedin sen" → "düşünmediysen"; split a wrongly-joined word). If a word is plausible as
+    written, keep it exactly — do NOT swap it for a synonym or a "better" word.
+  - Fix line breaks the OCR got wrong and keep real verse/paragraph breaks. Remove duplicate words and
+    stray margin numbers caused by OCR.
+  - Keep lines and sentences in their original order; do NOT reorder or move content.
+  - If a word is illegible, give your closest LITERAL reading; never invent a fluent replacement.
+  - Keep signatures, author names, and titles; only fix obvious typos in them.
+  - Do NOT translate. Keep the original language.
+"""
+
+_CONSERVATIVE = """
+  CONSERVATIVE MODE (for OCR images/scans):
+  - Perform minimal, character-level OCR correction only.
+  - Do NOT replace a valid-looking word with a different semantic word.
+  - If uncertain, keep the original token exactly as-is.
+  - Do NOT infer missing entities (names, places, brands, email local-parts) from context.
+  - Preserve line order and keep output close to source line-by-line.
+"""
+
+_MODE_INSTRUCTIONS = {
+    RefinementMode.LAYOUT: _LAYOUT,
+    RefinementMode.HANDWRITING_LAYOUT: _HANDWRITING_LAYOUT,
+    RefinementMode.HANDWRITING_PROSE: _HANDWRITING_PROSE,
+    RefinementMode.CONSERVATIVE: _CONSERVATIVE,
+}
+
+_SYSTEM_HANDWRITING_LAYOUT = (
+    "You are a world-class OCR post-processor for handwritten notes. "
+    "Fix OCR errors and tidy the layout, but stay faithful to what is written: "
+    "never paraphrase, complete, or invent text you cannot read. "
+    "Never alter frozen {{OCRLITn}} placeholders. Output plain text only."
+)
+_SYSTEM_HANDWRITING_PROSE = (
+    "You are a world-class OCR post-processor for handwritten prose and poetry. "
+    "Fix misread words and broken line breaks, but stay faithful: never paraphrase, "
+    "complete, or invent content, and never translate. "
+    "Never alter frozen {{OCRLITn}} placeholders. Output plain text only."
+)
+_SYSTEM_DEFAULT = (
+    "You are a world-class OCR post-processor. Fix OCR noise in normal prose only. "
+    "Never alter frozen {{OCRLITn}} placeholders (emails, URLs, banking IDs). "
+    "Never guess or complete email addresses or usernames. Output plain text only."
+)
+
+
+def build_refinement_prompt(
+    masked_text: str, language: str, mode: RefinementMode
+) -> tuple[str, str]:
+    """Return ``(system, user)`` prompt strings for the given mode."""
+    full_language = language_full_name(language) if language else None
+    if full_language and full_language != "auto":
+        language_prompt = (
+            f"The text is in {full_language}. Preserve the original language and only fix "
+            f"OCR errors using {full_language} spelling rules."
+        )
+    else:
+        language_prompt = (
+            "Preserve the original language of the text. Do not translate or change the language."
+        )
+
+    mode_instructions = _MODE_INSTRUCTIONS[mode]
+
+    user = f"""
+  You are an expert OCR post-processing AI. Your ONLY task is to reconstruct the original text from OCR output that contains scanning errors.
+  Never add new information and never remove existing information.
+  {mode_instructions}
+  {LITERAL_PRESERVE_PROMPT}
+
+  UNDERSTANDING OCR ERRORS:
+  OCR engines make SYSTEMATIC errors — they don't understand language, they only recognize shapes.
+
+  A) DIACRITIC STRIPPING (Turkish, French, German, Spanish, etc.)
+  B) VISUALLY SIMILAR CHARACTER CONFUSION (0↔O, rn→m, ...)
+  C) TRUNCATION & MISSING CHARACTERS
+  D) WORD BOUNDARY ERRORS
+
+  YOUR TASK:
+  1. Fix OCR errors in regular words using sentence context.
+  2. DO NOT translate. DO NOT change the language. DO NOT add or remove content.
+  3. DO NOT add commentary. Output ONLY the corrected plain text.
+  4. Output PLAIN TEXT only. Do NOT use Markdown syntax (#, *, _, backticks, >) and do NOT wrap the output in code fences.
+  5. {language_prompt}
+
+  Input Text:
+  {masked_text}
+  """
+
+    if mode == RefinementMode.HANDWRITING_LAYOUT:
+        system = _SYSTEM_HANDWRITING_LAYOUT
+    elif mode == RefinementMode.HANDWRITING_PROSE:
+        system = _SYSTEM_HANDWRITING_PROSE
+    else:
+        system = _SYSTEM_DEFAULT
+
+    return system, user

ocrcontext/llm/refiner.py

@@ -0,0 +1,114 @@
+"""LLM-agnostic OCR refinement, ported from lib/ocr/refine.ts::refineOcrText.
+
+Works with any LangChain ``BaseChatModel``. The fidelity pipeline is preserved:
+mask literals -> prompt -> invoke -> unmask -> enforce literals -> strip markdown
+-> drift/hallucination rejection.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from ..types import RefinementMode
+from .drift import refine_hallucinated_length, refinement_drifted
+from .formatting import strip_markdown_formatting
+from .literal_preserve import (
+    enforce_original_literals,
+    mask_protected_literals,
+    unmask_protected_literals,
+)
+from .prompts import build_refinement_prompt, refine_temperature
+
+if TYPE_CHECKING:
+    from langchain_core.language_models import BaseChatModel
+
+logger = logging.getLogger("ocrcontext.refine")
+
+
+class Refiner:
+    """Post-OCR refinement using an injected LangChain chat model."""
+
+    def __init__(self, llm: "BaseChatModel", *, apply_temperature: bool = True) -> None:
+        self._llm = llm
+        # When True, bind the mode's recommended temperature to the model call.
+        # Falls back gracefully for providers that reject the kwarg.
+        self._apply_temperature = apply_temperature
+
+    def refine(
+        self,
+        text: str,
+        language: str = "auto",
+        mode: RefinementMode = RefinementMode.CONSERVATIVE,
+    ) -> str:
+        """Refine OCR ``text``. Returns the original text unchanged on drift/empty."""
+        mask = mask_protected_literals(text)
+        system, user = build_refinement_prompt(mask.masked_text, language, mode)
+
+        raw = self._invoke(system, user, refine_temperature(mode))
+        refined = raw or mask.masked_text
+
+        unmasked = unmask_protected_literals(refined, mask.literals)
+        literal_safe = enforce_original_literals(text, unmasked)
+
+        convert_bullets = mode in (RefinementMode.HANDWRITING_LAYOUT, RefinementMode.LAYOUT)
+        cleaned = strip_markdown_formatting(literal_safe, convert_bullets=convert_bullets)
+
+        # Handwritten notes/prose: trust word + layout fixes; reject only wholesale
+        # hallucination (size bears little resemblance to source).
+        if mode in (RefinementMode.HANDWRITING_PROSE, RefinementMode.HANDWRITING_LAYOUT):
+            if not cleaned.strip():
+                return text
+            if refine_hallucinated_length(text, cleaned):
+                logger.warning(
+                    "Handwriting output length diverged too far; keeping original OCR text "
+                    "(mode=%s)",
+                    mode.value,
+                )
+                return text
+            return cleaned
+
+        if refinement_drifted(text, cleaned):
+            logger.warning(
+                "Output drifted too far from source; keeping original OCR text "
+                "(mode=%s, original_lines=%d, refined_lines=%d)",
+                mode.value,
+                len(text.split("\n")),
+                len(cleaned.split("\n")),
+            )
+            return text
+
+        return cleaned
+
+    def _invoke(self, system: str, user: str, temperature: float) -> str:
+        from langchain_core.messages import HumanMessage, SystemMessage
+
+        messages = [SystemMessage(content=system), HumanMessage(content=user)]
+
+        if self._apply_temperature:
+            try:
+                bound = self._llm.bind(temperature=temperature)
+                response = bound.invoke(messages)
+                return _message_text(response)
+            except Exception:
+                # Provider may not accept a temperature kwarg — fall back to plain invoke.
+                logger.debug("temperature bind failed; retrying without it", exc_info=True)
+
+        response = self._llm.invoke(messages)
+        return _message_text(response)
+
+
+def _message_text(response) -> str:
+    content = getattr(response, "content", response)
+    if isinstance(content, str):
+        return content
+    # Some providers return a list of content blocks.
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict) and "text" in block:
+                parts.append(str(block["text"]))
+        return "".join(parts)
+    return str(content)

ocrcontext/llm/schemas.py

@@ -0,0 +1,99 @@
+"""Built-in extraction schemas.
+
+The Invoice schema + extraction prompt are ported from
+app/api/invoices/process/route.ts, including the quantity back-fill rule.
+These double as ready-to-use schemas and as worked examples for users defining
+their own Pydantic schemas.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class LineItem(BaseModel):
+    description: Optional[str] = Field(None, description="Product/Service name.")
+    quantity: Optional[float] = Field(
+        None,
+        description=(
+            "Numeric quantity. If missing, calculate it as total / unit_price. "
+            "Default 1 only if neither is available."
+        ),
+    )
+    unit: Optional[str] = Field(None, description="Unit type (Adet, Kg, Saat, etc.).")
+    unit_price: Optional[float] = Field(None, description="Price per unit.")
+    tax_rate: Optional[str] = Field(
+        None, description="Tax percentage (e.g., 20, 10, 0) or pattern."
+    )
+    total: Optional[float] = Field(None, description="Total price for this line.")
+
+
+class Invoice(BaseModel):
+    supplier_name: Optional[str] = Field(None, description="Name of the vendor/supplier.")
+    invoice_date: Optional[str] = Field(None, description="Format YYYY-MM-DD.")
+    invoice_number: Optional[str] = Field(None, description="The invoice ID/number.")
+    tax_id: Optional[str] = Field(None, description="Tax ID / VKN / TCKN.")
+    tax_rate: Optional[str] = Field(
+        None, description="e.g. 'KDV %20' when KDV is 20%."
+    )
+    currency: Optional[str] = Field(None, description="Currency code (TRY, USD, EUR, etc.).")
+    total_amount: Optional[float] = Field(None, description="Final total amount (numeric).")
+    line_items: list[LineItem] = Field(
+        default_factory=list, description="Array of items/services."
+    )
+
+    @model_validator(mode="after")
+    def _backfill_line_item_quantities(self) -> "Invoice":
+        """Port of the route's quantity = total / unit_price correction."""
+        for item in self.line_items:
+            if item.unit_price is None or item.total is None:
+                continue
+            try:
+                unit_price = float(item.unit_price)
+                total = float(item.total)
+            except (TypeError, ValueError):
+                continue
+            if unit_price > 0:
+                calculated_qty = total / unit_price
+                qty = item.quantity
+                if (qty is None or qty == 1) and abs(calculated_qty - 1) > 0.01:
+                    item.quantity = round(calculated_qty, 2)
+        return self
+
+
+# Verbatim system prompt from app/api/invoices/process/route.ts.
+INVOICE_EXTRACTION_PROMPT = """You are an expert invoice data extraction assistant.
+
+CRITICAL RULES:
+1. **LANGUAGE REPAIR**:
+    - The text may come from OCR and may have missing characters.
+    - If language is 'tr' (Turkish), intelligently fix missing Turkish characters.
+
+2. **NUMBER PARSING**:
+    - Be extremely careful with comma (,) and dot (.).
+    - In Turkish/European invoices, '1.200,50' means One Thousand Two Hundred and 50 cents.
+    - NEVER confuse a quantity (e.g., 500) with a price (e.g. 5,00).
+
+3. **CURRENCY DETECTION**:
+    - Look for symbols: ₺, TL, TRY, USD, $, EUR, €.
+    - Prioritize 'TRY' / 'TL' unless explicitly stated otherwise.
+
+Extract the following fields if it exists:
+- 'supplier_name': Name of the vendor/supplier.
+- 'invoice_date': Format YYYY-MM-DD.
+- 'invoice_number': The invoice ID/number.
+- 'tax_id': Tax ID / VKN / TCKN.
+- 'tax_rate': It can be like 'KDV' and for example if it is 'KDV' and it is %20, write it as 'KDV %20' in excel.
+- 'currency': Currency code (TRY, USD, EUR, etc.).
+- 'total_amount': Final total amount (numeric).
+- 'line_items': An array of items/services. Each item should have:
+  - 'description': Product/Service name.
+  - 'quantity': Numeric quantity. If missing, calculate it as total / unit_price. Default 1 only if neither is available.
+  - 'unit': Unit type (Adet, Kg, Saat, etc.).
+  - 'unit_price': Price per unit.
+  - 'tax_rate': Tax percentage (e.g., 20, 10, 0) or pattern.
+  - 'total': Total price for this line.
+
+Return ONLY a valid JSON object. If a field is not found, use null."""