feat: add maintenance receipt extraction pipeline with Gemini + regex (refs #150)

- New MaintenanceReceiptExtractor: Gemini-primary extraction with regex
  cross-validation for dates, amounts, and odometer readings
- New maintenance_receipt_validation.py: cross-validation patterns for
  structured field confidence adjustment
- New POST /extract/maintenance-receipt endpoint reusing
  ReceiptExtractionResponse model
- Per-field confidence scores (0.0-1.0) with Gemini base 0.85,
  boosted/reduced by regex agreement

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

ocr/app/routers/extract.py

@@ -6,6 +6,7 @@ from fastapi import APIRouter, BackgroundTasks, File, Form, HTTPException, Query
 
 from app.extractors.vin_extractor import vin_extractor
 from app.extractors.receipt_extractor import receipt_extractor
+from app.extractors.maintenance_receipt_extractor import maintenance_receipt_extractor
 from app.extractors.manual_extractor import manual_extractor
 from app.models import (
     BoundingBox,
@@ -267,6 +268,95 @@ async def extract_receipt(
     )
 
 
+@router.post("/maintenance-receipt", response_model=ReceiptExtractionResponse)
+async def extract_maintenance_receipt(
+    file: UploadFile = File(..., description="Maintenance receipt image file"),
+) -> ReceiptExtractionResponse:
+    """
+    Extract data from a maintenance receipt image using OCR + Gemini.
+
+    Gemini-primary extraction with regex cross-validation:
+    - OCR preprocessing (HEIC conversion, contrast, thresholding)
+    - PaddleOCR text extraction
+    - Gemini semantic field extraction from OCR text
+    - Regex cross-validation for dates, amounts, odometer
+
+    Supports HEIC, JPEG, PNG formats.
+
+    - **file**: Maintenance receipt image file (max 10MB)
+
+    Returns:
+    - **receiptType**: "maintenance"
+    - **extractedFields**: Dictionary of extracted fields with confidence scores
+      - serviceName: Service performed (e.g., "Oil Change")
+      - serviceDate: Date in YYYY-MM-DD format
+      - totalCost: Total cost
+      - shopName: Shop or business name
+      - laborCost: Labor cost (if broken out)
+      - partsCost: Parts cost (if broken out)
+      - odometerReading: Odometer reading (if present)
+      - vehicleInfo: Vehicle description (if present)
+    - **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"Maintenance receipt extraction: {file.filename}, "
+        f"size: {file_size} bytes, "
+        f"content_type: {file.content_type}"
+    )
+
+    # Perform maintenance receipt extraction
+    result = maintenance_receipt_extractor.extract(
+        image_bytes=content,
+        content_type=file.content_type,
+    )
+
+    if not result.success:
+        logger.warning(
+            f"Maintenance receipt extraction failed for {file.filename}: {result.error}"
+        )
+        raise HTTPException(
+            status_code=422,
+            detail=result.error or "Failed to extract data from maintenance receipt",
+        )
+
+    # 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,
+    )
+
+
 @router.post("/manual", response_model=ManualJobResponse)
 async def extract_manual(
     background_tasks: BackgroundTasks,