feat: add receipt OCR pipeline (refs #69)

Implement receipt-specific OCR extraction for fuel receipts:

- Pattern matching modules for date, currency, and fuel data extraction
- Receipt-optimized image preprocessing for thermal receipts
- POST /extract/receipt endpoint with field extraction
- Confidence scoring per extracted field
- Cross-validation of fuel receipt data
- Unit tests for all pattern matchers

Extracted fields: merchantName, transactionDate, totalAmount,
fuelQuantity, pricePerUnit, fuelGrade

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ocr/app/routers/extract.py

@@ -1,10 +1,19 @@
 """OCR extraction endpoints."""
 import logging
+from typing import Optional
 
-from fastapi import APIRouter, File, HTTPException, Query, UploadFile
+from fastapi import APIRouter, File, Form, HTTPException, Query, UploadFile
 
 from app.extractors.vin_extractor import vin_extractor
-from app.models import BoundingBox, OcrResponse, VinAlternative, VinExtractionResponse
+from app.extractors.receipt_extractor import receipt_extractor
+from app.models import (
+    BoundingBox,
+    OcrResponse,
+    ReceiptExtractedField,
+    ReceiptExtractionResponse,
+    VinAlternative,
+    VinExtractionResponse,
+)
 from app.services import ocr_service
 
 logger = logging.getLogger(__name__)
@@ -154,3 +163,97 @@ async def extract_vin(
         processingTimeMs=result.processing_time_ms,
         error=result.error,
     )
+
+
+@router.post("/receipt", response_model=ReceiptExtractionResponse)
+async def extract_receipt(
+    file: UploadFile = File(..., description="Receipt image file"),
+    receipt_type: Optional[str] = Form(
+        default=None,
+        description="Receipt type hint: 'fuel' for specialized extraction",
+    ),
+) -> ReceiptExtractionResponse:
+    """
+    Extract data from a receipt image using OCR.
+
+    Optimized for fuel receipts with pattern-based field extraction:
+    - HEIC conversion (if needed)
+    - Grayscale conversion
+    - High contrast enhancement (for thermal receipts)
+    - Adaptive thresholding
+    - Pattern matching for dates, amounts, fuel quantities
+
+    Supports HEIC, JPEG, PNG formats.
+    Processing time target: <3 seconds.
+
+    - **file**: Receipt image file (max 10MB)
+    - **receipt_type**: Optional hint ("fuel" for gas station receipts)
+
+    Returns:
+    - **receiptType**: Detected type ("fuel" or "unknown")
+    - **extractedFields**: Dictionary of extracted fields with confidence scores
+      - merchantName: Gas station or store name
+      - transactionDate: Date in YYYY-MM-DD format
+      - totalAmount: Total purchase amount
+      - fuelQuantity: Gallons/liters purchased (fuel receipts)
+      - pricePerUnit: Price per gallon/liter (fuel receipts)
+      - fuelGrade: Octane rating or fuel type (fuel receipts)
+    - **rawText**: Full OCR text
+    - **processingTimeMs**: Processing time in milliseconds
+    """
+    # Validate file presence
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="No file provided")
+
+    # Read file content
+    content = await file.read()
+    file_size = len(content)
+
+    # Validate file size
+    if file_size > MAX_SYNC_SIZE:
+        raise HTTPException(
+            status_code=413,
+            detail=f"File too large. Max: {MAX_SYNC_SIZE // (1024*1024)}MB",
+        )
+
+    if file_size == 0:
+        raise HTTPException(status_code=400, detail="Empty file provided")
+
+    logger.info(
+        f"Receipt extraction: {file.filename}, "
+        f"size: {file_size} bytes, "
+        f"content_type: {file.content_type}, "
+        f"receipt_type: {receipt_type}"
+    )
+
+    # Perform receipt extraction
+    result = receipt_extractor.extract(
+        image_bytes=content,
+        content_type=file.content_type,
+        receipt_type=receipt_type,
+    )
+
+    if not result.success:
+        logger.warning(f"Receipt extraction failed for {file.filename}: {result.error}")
+        raise HTTPException(
+            status_code=422,
+            detail=result.error or "Failed to extract data from receipt image",
+        )
+
+    # Convert internal fields to API response format
+    extracted_fields = {
+        name: ReceiptExtractedField(
+            value=field.value,
+            confidence=field.confidence,
+        )
+        for name, field in result.extracted_fields.items()
+    }
+
+    return ReceiptExtractionResponse(
+        success=result.success,
+        receiptType=result.receipt_type,
+        extractedFields=extracted_fields,
+        rawText=result.raw_text,
+        processingTimeMs=result.processing_time_ms,
+        error=result.error,
+    )