first commit - MVE Incrementables Parser microservice with FastAPI, JWT, Celery, Redis

app/__init__.py

@@ -0,0 +1,2 @@
+# MVE Incrementables Parser Service
+__version__ = "1.0.0"

app/api/auth.py

@@ -0,0 +1,61 @@
+"""Authentication endpoints."""
+from fastapi import APIRouter, HTTPException, status, Request
+from datetime import timedelta
+import logging
+
+from app.core.config import get_settings
+from app.core.security import authenticate_user, create_access_token, check_rate_limit
+from app.schemas import LoginRequest, LoginResponse
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+
+@router.post("/login", response_model=LoginResponse)
+async def login(request: Request, credentials: LoginRequest):
+    """
+    Authenticate user and return JWT token.
+    
+    - **username**: Username
+    - **password**: Password
+    
+    Returns JWT access token with expiration time.
+    """
+    settings = get_settings()
+    
+    # Get client IP for rate limiting
+    client_ip = request.client.host if request.client else "unknown"
+    
+    # Check rate limit
+    if check_rate_limit(client_ip):
+        logger.warning(f"Rate limit exceeded for IP: {client_ip}")
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Too many login attempts. Please try again later."
+        )
+    
+    # Authenticate (never log the password)
+    logger.info(f"Login attempt for user: {credentials.username} from IP: {client_ip}")
+    
+    if not authenticate_user(credentials.username, credentials.password):
+        logger.warning(f"Failed login attempt for user: {credentials.username}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    # Create access token
+    access_token_expires = timedelta(minutes=settings.jwt_expires_minutes)
+    access_token = create_access_token(
+        data={"sub": credentials.username},
+        expires_delta=access_token_expires
+    )
+    
+    logger.info(f"Successful login for user: {credentials.username}")
+    
+    return LoginResponse(
+        access_token=access_token,
+        token_type="bearer",
+        expires_in=settings.jwt_expires_minutes * 60  # Convert to seconds
+    )

app/api/v1/incrementables.py

@@ -0,0 +1,322 @@
+"""Incrementables parsing endpoints."""
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Form, Header, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from celery.result import AsyncResult
+import hashlib
+import logging
+import uuid
+from typing import Optional
+
+from app.core.config import get_settings
+from app.core.security import decode_access_token
+from app.core.celery_app import celery_app
+from app.tasks.parse_tasks import parse_pdf_task
+from app.services.pdf_text import extract_text_from_pdf, PDFExtractionError
+from app.services.parser import parse_incrementables, ParsingError
+from app.schemas import (
+    ParseResponse, ParseAsyncResponse, TaskStatusResponse,
+    DocumentInfo, IncrementablesData, ExtractionInfo
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/v1/incrementables", tags=["Incrementables"])
+security = HTTPBearer()
+
+
+def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)) -> str:
+    """
+    Dependency to validate JWT token and extract username.
+    """
+    payload = decode_access_token(credentials.credentials)
+    username = payload.get("sub")
+    
+    if username is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid credentials"
+        )
+    
+    return username
+
+
+@router.post("/parse", response_model=ParseResponse)
+async def parse_pdf(
+    file: UploadFile = File(..., description="PDF file to parse"),
+    document_ref: Optional[str] = Form(None, description="Optional document reference or folio"),
+    x_correlation_id: Optional[str] = Header(None),
+    current_user: str = Depends(get_current_user)
+):
+    """
+    Parse incrementables section from uploaded PDF.
+    
+    - **file**: PDF file (required)
+    - **document_ref**: Optional document reference or folio
+    
+    Returns parsed incrementables data with metadata.
+    
+    **Authentication required**: Bearer token in Authorization header.
+    """
+    settings = get_settings()
+    
+    # Generate or use correlation ID
+    correlation_id = x_correlation_id or str(uuid.uuid4())
+    
+    logger.info(
+        f"Parse request received",
+        extra={
+            "correlation_id": correlation_id,
+            "pdf_filename": file.filename,
+            "document_ref": document_ref,
+            "user": current_user
+        }
+    )
+    
+    # Validate file type
+    if not file.filename.lower().endswith('.pdf'):
+        logger.warning(f"Invalid file type: {file.filename}", extra={"correlation_id": correlation_id})
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Only PDF files are accepted"
+        )
+    
+    # Validate content type
+    if file.content_type not in ["application/pdf", "application/x-pdf"]:
+        logger.warning(
+            f"Invalid content type: {file.content_type}",
+            extra={"correlation_id": correlation_id}
+        )
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid content type. Expected application/pdf, got {file.content_type}"
+        )
+    
+    # Read file content
+    try:
+        pdf_bytes = await file.read()
+    except Exception as e:
+        logger.error(f"Failed to read file: {str(e)}", extra={"correlation_id": correlation_id})
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to read uploaded file"
+        )
+    
+    # Validate file size
+    file_size_mb = len(pdf_bytes) / (1024 * 1024)
+    if file_size_mb > settings.max_file_mb:
+        logger.warning(
+            f"File too large: {file_size_mb:.2f} MB",
+            extra={"correlation_id": correlation_id}
+        )
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"File size exceeds maximum allowed size of {settings.max_file_mb} MB"
+        )
+    
+    # Calculate SHA256 hash
+    file_hash = hashlib.sha256(pdf_bytes).hexdigest()
+    
+    # Extract text from PDF
+    try:
+        text, page_count, extraction_method = extract_text_from_pdf(pdf_bytes)
+        logger.info(
+            f"Text extracted: {len(text)} characters, {page_count} pages",
+            extra={"correlation_id": correlation_id}
+        )
+    except PDFExtractionError as e:
+        logger.error(
+            f"PDF extraction failed: {str(e)}",
+            extra={"correlation_id": correlation_id}
+        )
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"Failed to extract text from PDF: {str(e)}"
+        )
+    
+    # Parse incrementables
+    try:
+        parsed_data = parse_incrementables(text)
+        logger.info(
+            f"Successfully parsed incrementables",
+            extra={
+                "correlation_id": correlation_id,
+                "currency": parsed_data["currency"],
+                "fletes": parsed_data["fletes"]
+            }
+        )
+    except ParsingError as e:
+        logger.error(
+            f"Parsing failed: {str(e)}",
+            extra={"correlation_id": correlation_id}
+        )
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"Failed to parse incrementables section: {str(e)}"
+        )
+    
+    # Build response
+    response = ParseResponse(
+        correlation_id=correlation_id,
+        document=DocumentInfo(
+            filename=file.filename,
+            pages=page_count,
+            sha256=file_hash
+        ),
+        incrementables=IncrementablesData(
+            currency=parsed_data["currency"],
+            fletes=parsed_data["fletes"],
+            seguros=parsed_data["seguros"],
+            almacenaje_consolidacion=parsed_data["almacenaje_consolidacion"],
+            regalias=parsed_data["regalias"]
+        ),
+        extraction=ExtractionInfo(
+            method=extraction_method,
+            anchors_found=parsed_data["anchors_found"],
+            warnings=parsed_data["warnings"]
+        )
+    )
+    
+    return response
+
+
+@router.post("/parse/async", response_model=ParseAsyncResponse)
+async def parse_pdf_async(
+    file: UploadFile = File(..., description="PDF file to parse"),
+    document_ref: Optional[str] = Form(None, description="Optional document reference or folio"),
+    x_correlation_id: Optional[str] = Header(None),
+    current_user: str = Depends(get_current_user)
+):
+    """
+    Parse incrementables section from uploaded PDF asynchronously using Celery.
+    
+    - **file**: PDF file (required)
+    - **document_ref**: Optional document reference or folio
+    
+    Returns task ID for checking status later.
+    
+    **Authentication required**: Bearer token in Authorization header.
+    """
+    settings = get_settings()
+    
+    # Generate or use correlation ID
+    correlation_id = x_correlation_id or str(uuid.uuid4())
+    
+    logger.info(
+        f"Async parse request received",
+        extra={
+            "correlation_id": correlation_id,
+            "pdf_filename": file.filename,
+            "document_ref": document_ref,
+            "user": current_user
+        }
+    )
+    
+    # Validate file type
+    if not file.filename.lower().endswith('.pdf'):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Only PDF files are accepted"
+        )
+    
+    # Validate content type
+    if file.content_type not in ["application/pdf", "application/x-pdf"]:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid content type. Expected application/pdf, got {file.content_type}"
+        )
+    
+    # Read file content
+    try:
+        pdf_bytes = await file.read()
+    except Exception as e:
+        logger.error(f"Failed to read file: {str(e)}", extra={"correlation_id": correlation_id})
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to read uploaded file"
+        )
+    
+    # Validate file size
+    file_size_mb = len(pdf_bytes) / (1024 * 1024)
+    if file_size_mb > settings.max_file_mb:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"File size exceeds maximum allowed size of {settings.max_file_mb} MB"
+        )
+    
+    # Convert bytes to hex for serialization
+    pdf_hex = pdf_bytes.hex()
+    
+    # Queue task
+    task = parse_pdf_task.delay(pdf_hex, file.filename, document_ref)
+    
+    logger.info(
+        f"Task queued: {task.id}",
+        extra={"correlation_id": correlation_id, "task_id": task.id}
+    )
+    
+    return ParseAsyncResponse(
+        task_id=task.id,
+        correlation_id=correlation_id,
+        status="queued",
+        message="Task queued for processing. Use /v1/incrementables/status/{task_id} to check progress."
+    )
+
+
+@router.get("/status/{task_id}", response_model=TaskStatusResponse)
+async def get_task_status(
+    task_id: str,
+    current_user: str = Depends(get_current_user)
+):
+    """
+    Get status of an async parsing task.
+    
+    - **task_id**: Task ID returned from /parse/async
+    
+    Returns task status and result if completed.
+    
+    **Authentication required**: Bearer token in Authorization header.
+    """
+    task_result = AsyncResult(task_id, app=celery_app)
+    
+    if task_result.state == "PENDING":
+        return TaskStatusResponse(
+            task_id=task_id,
+            status="pending",
+            result=None,
+            error=None
+        )
+    elif task_result.state == "STARTED":
+        return TaskStatusResponse(
+            task_id=task_id,
+            status="started",
+            result=None,
+            error=None
+        )
+    elif task_result.state == "SUCCESS":
+        result_data = task_result.result
+        if result_data.get("status") == "failed":
+            return TaskStatusResponse(
+                task_id=task_id,
+                status="failed",
+                result=None,
+                error=result_data.get("message", "Unknown error")
+            )
+        return TaskStatusResponse(
+            task_id=task_id,
+            status="completed",
+            result=result_data,
+            error=None
+        )
+    elif task_result.state == "FAILURE":
+        return TaskStatusResponse(
+            task_id=task_id,
+            status="failed",
+            result=None,
+            error=str(task_result.info)
+        )
+    else:
+        return TaskStatusResponse(
+            task_id=task_id,
+            status=task_result.state.lower(),
+            result=None,
+            error=None
+        )

app/core/celery_app.py

@@ -0,0 +1,25 @@
+"""Celery application configuration."""
+from celery import Celery
+from .config import get_settings
+
+settings = get_settings()
+
+celery_app = Celery(
+    "mve_incrementables_parser",
+    broker=settings.celery_broker_url,
+    backend=settings.celery_result_backend,
+    include=["app.tasks.parse_tasks"]
+)
+
+# Celery configuration
+celery_app.conf.update(
+    task_serializer="json",
+    accept_content=["json"],
+    result_serializer="json",
+    timezone="UTC",
+    enable_utc=True,
+    task_track_started=True,
+    task_time_limit=300,  # 5 minutes max
+    task_soft_time_limit=240,  # 4 minutes soft limit
+    result_expires=3600,  # Results expire after 1 hour
+)

app/core/config.py

@@ -0,0 +1,39 @@
+"""Configuration management using Pydantic Settings."""
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+    
+    # Service Info
+    service_name: str = "mve-incrementables-parser"
+    service_version: str = "1.0.0"
+    
+    # Authentication
+    auth_username: str
+    auth_password_hash: str
+    jwt_secret: str
+    jwt_expires_minutes: int = 60
+    jwt_algorithm: str = "HS256"
+    
+    # File Upload
+    max_file_mb: int = 10
+    
+    # Logging
+    log_level: str = "INFO"
+    
+    # Redis/Celery
+    redis_url: str = "redis://localhost:6379/0"
+    celery_broker_url: str = "redis://localhost:6379/0"
+    celery_result_backend: str = "redis://localhost:6379/0"
+    
+    class Config:
+        env_file = ".env"
+        case_sensitive = False
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings()

app/core/security.py

@@ -0,0 +1,99 @@
+"""Security utilities for authentication and JWT token management."""
+from datetime import datetime, timedelta
+from typing import Optional
+from jose import JWTError, jwt
+import bcrypt
+from fastapi import HTTPException, status
+from .config import get_settings
+import time
+from collections import defaultdict
+
+# Simple in-memory rate limiter for login attempts
+login_attempts = defaultdict(list)
+MAX_LOGIN_ATTEMPTS = 5
+LOGIN_WINDOW_SECONDS = 300  # 5 minutes
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash."""
+    try:
+        return bcrypt.checkpw(plain_password.encode('utf-8'), hashed_password.encode('utf-8'))
+    except Exception as e:
+        return False
+
+
+def get_password_hash(password: str) -> str:
+    """Generate password hash."""
+    return bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
+
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+    """Create JWT access token."""
+    settings = get_settings()
+    to_encode = data.copy()
+    
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=settings.jwt_expires_minutes)
+    
+    to_encode.update({"exp": expire, "iat": datetime.utcnow()})
+    encoded_jwt = jwt.encode(
+        to_encode, 
+        settings.jwt_secret, 
+        algorithm=settings.jwt_algorithm
+    )
+    return encoded_jwt
+
+
+def decode_access_token(token: str) -> dict:
+    """Decode and verify JWT token."""
+    settings = get_settings()
+    try:
+        payload = jwt.decode(
+            token, 
+            settings.jwt_secret, 
+            algorithms=[settings.jwt_algorithm]
+        )
+        return payload
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+def check_rate_limit(identifier: str) -> bool:
+    """
+    Simple rate limiter for login attempts.
+    Returns True if rate limit exceeded.
+    """
+    current_time = time.time()
+    
+    # Clean old attempts
+    login_attempts[identifier] = [
+        attempt_time for attempt_time in login_attempts[identifier]
+        if current_time - attempt_time < LOGIN_WINDOW_SECONDS
+    ]
+    
+    # Check if limit exceeded
+    if len(login_attempts[identifier]) >= MAX_LOGIN_ATTEMPTS:
+        return True
+    
+    # Record this attempt
+    login_attempts[identifier].append(current_time)
+    return False
+
+
+def authenticate_user(username: str, password: str) -> bool:
+    """Authenticate user with username and password."""
+    settings = get_settings()
+    
+    if username != settings.auth_username:
+        return False
+    
+    if not verify_password(password, settings.auth_password_hash):
+        return False
+    
+    return True

app/main.py

@@ -0,0 +1,90 @@
+"""Main FastAPI application."""
+import logging
+import sys
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+from contextlib import asynccontextmanager
+
+from app.core.config import get_settings
+from app.api import auth
+from app.api.v1 import incrementables
+from app.schemas import HealthResponse
+
+# Configure logging
+settings = get_settings()
+logging.basicConfig(
+    level=getattr(logging, settings.log_level.upper()),
+    format='{"time": "%(asctime)s", "level": "%(levelname)s", "name": "%(name)s", "message": "%(message)s"}',
+    stream=sys.stdout
+)
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager."""
+    logger.info(f"Starting {settings.service_name} v{settings.service_version}")
+    yield
+    logger.info(f"Shutting down {settings.service_name}")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title=settings.service_name,
+    version=settings.service_version,
+    description="MVE Incrementables Parser - Extracts incrementables data from PDFs",
+    lifespan=lifespan
+)
+
+
+# Exception handlers
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Handle validation errors with custom format."""
+    logger.warning(f"Validation error: {exc.errors()}")
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content={
+            "detail": "Validation error",
+            "errors": exc.errors()
+        }
+    )
+
+
+@app.exception_handler(Exception)
+async def general_exception_handler(request: Request, exc: Exception):
+    """Handle unexpected errors."""
+    logger.error(f"Unexpected error: {str(exc)}", exc_info=True)
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={
+            "detail": "Internal server error"
+        }
+    )
+
+
+# Health check endpoint
+@app.get("/health", response_model=HealthResponse, tags=["Health"])
+async def health_check():
+    """
+    Health check endpoint.
+    
+    Returns service status and version information.
+    """
+    return HealthResponse(
+        status="ok",
+        service=settings.service_name,
+        version=settings.service_version
+    )
+
+
+# Include routers
+app.include_router(auth.router)
+app.include_router(incrementables.router)
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=9876)

app/schemas.py

@@ -0,0 +1,81 @@
+"""Pydantic schemas for request/response validation."""
+from pydantic import BaseModel, Field
+from typing import Optional, List
+from datetime import datetime
+
+
+# Authentication Schemas
+class LoginRequest(BaseModel):
+    """Login request schema."""
+    username: str = Field(..., min_length=1)
+    password: str = Field(..., min_length=1)
+
+
+class LoginResponse(BaseModel):
+    """Login response schema."""
+    access_token: str
+    token_type: str = "bearer"
+    expires_in: int
+
+
+# Health Check Schema
+class HealthResponse(BaseModel):
+    """Health check response."""
+    status: str = "ok"
+    service: str
+    version: str
+
+
+# Incrementables Schemas
+class DocumentInfo(BaseModel):
+    """PDF document metadata."""
+    filename: str
+    pages: int
+    sha256: str
+
+
+class IncrementablesData(BaseModel):
+    """Parsed incrementables data."""
+    currency: str
+    fletes: float
+    seguros: Optional[float] = None
+    almacenaje_consolidacion: float
+    regalias: Optional[float] = None
+
+
+class ExtractionInfo(BaseModel):
+    """Information about the extraction process."""
+    method: str  # "text", "ocr" (future)
+    anchors_found: List[str]
+    warnings: List[str] = []
+
+
+class ParseResponse(BaseModel):
+    """Parse endpoint response."""
+    correlation_id: str
+    document: DocumentInfo
+    incrementables: IncrementablesData
+    extraction: ExtractionInfo
+
+
+# Async/Queue schemas
+class ParseAsyncResponse(BaseModel):
+    """Async parse endpoint response."""
+    task_id: str
+    correlation_id: str
+    status: str = "queued"
+    message: str = "Task queued for processing"
+
+
+class TaskStatusResponse(BaseModel):
+    """Task status response."""
+    task_id: str
+    status: str  # pending, started, completed, failed
+    result: Optional[dict] = None
+    error: Optional[str] = None
+
+
+class ErrorResponse(BaseModel):
+    """Error response schema."""
+    detail: str
+    correlation_id: Optional[str] = None

app/services/parser.py

@@ -0,0 +1,211 @@
+"""Parser service for extracting incrementables data from PDF text."""
+import re
+import logging
+from typing import Dict, Optional, List, Tuple
+from decimal import Decimal
+
+logger = logging.getLogger(__name__)
+
+
+class ParsingError(Exception):
+    """Custom exception for parsing errors."""
+    pass
+
+
+class IncrementablesParser:
+    """Parser for extracting incrementables data from PDF text."""
+    
+    # Anchor patterns to find the incrementables section
+    ANCHOR_PATTERNS = [
+        r"AJUSTE\s+DE\s+INCREMENTABLES\s+EN:",
+        r"INCREMENTABLES\s+EN:",
+        r"AJUSTE\s+INCREMENTABLES:",
+    ]
+    
+    # Field patterns
+    FIELD_PATTERNS = {
+        "fletes": r"Fletes[:\s]*\$?\s*([\d,]+\.?\d*)\s*(USD|MXN|EUR)?",
+        "seguros": r"Seguros[:\s]*(?:\$?\s*([\d,]+\.?\d*)\s*)?(USD|MXN|EUR)?",
+        "almacenaje": r"(?:Almacenaje[/\s]*(?:Consolidaci[oó]n)?)[:\s]*\$?\s*([\d,]+\.?\d*)\s*(USD|MXN|EUR)?",
+        "regalias": r"(?:Regal[ií]as?)[:\s]*(?:\$?\s*([\d,]+\.?\d*)\s*)?(USD|MXN|EUR)?",
+    }
+    
+    def __init__(self, text: str):
+        """
+        Initialize parser with PDF text.
+        
+        Args:
+            text: Extracted text from PDF
+        """
+        self.text = text
+        self.warnings: List[str] = []
+        self.anchors_found: List[str] = []
+    
+    def _find_incrementables_section(self) -> Optional[str]:
+        """
+        Find the incrementables section in the text.
+        
+        Returns:
+            Text snippet containing incrementables data, or None if not found
+        """
+        for pattern in self.ANCHOR_PATTERNS:
+            match = re.search(pattern, self.text, re.IGNORECASE | re.MULTILINE)
+            if match:
+                anchor_text = match.group(0)
+                self.anchors_found.append(anchor_text)
+                logger.info(f"Found anchor: {anchor_text}")
+                
+                # Extract the next ~500 characters after the anchor
+                start_pos = match.end()
+                section = self.text[start_pos:start_pos + 500]
+                return section
+        
+        return None
+    
+    def _extract_currency(self, section: str) -> str:
+        """
+        Extract currency from the section.
+        
+        Args:
+            section: Text section to search
+            
+        Returns:
+            Currency code (USD, MXN, EUR) or "USD" as default
+        """
+        currency_pattern = r"\b(USD|MXN|EUR)\b"
+        match = re.search(currency_pattern, section)
+        
+        if match:
+            return match.group(1)
+        
+        # Default to USD but add warning
+        self.warnings.append("Currency not explicitly found, defaulting to USD")
+        return "USD"
+    
+    def _parse_amount(self, value: Optional[str]) -> Optional[float]:
+        """
+        Parse monetary amount from string.
+        
+        Args:
+            value: String containing amount (e.g., "1,591.20" or "$1,591.20")
+            
+        Returns:
+            Float value or None if empty/invalid
+        """
+        if not value or value.strip() == "":
+            return None
+        
+        try:
+            # Remove $ and commas
+            cleaned = value.replace("$", "").replace(",", "").strip()
+            if not cleaned:
+                return None
+            
+            # Convert to Decimal for precision, then to float for JSON
+            amount = float(Decimal(cleaned))
+            return amount
+        except Exception as e:
+            logger.warning(f"Failed to parse amount '{value}': {str(e)}")
+            return None
+    
+    def _extract_field(self, section: str, field_name: str) -> Tuple[Optional[float], Optional[str]]:
+        """
+        Extract a specific field from the section.
+        
+        Args:
+            section: Text section to search
+            field_name: Name of field (fletes, seguros, almacenaje, regalias)
+            
+        Returns:
+            Tuple of (amount, currency) or (None, None)
+        """
+        pattern = self.FIELD_PATTERNS.get(field_name)
+        if not pattern:
+            return None, None
+        
+        match = re.search(pattern, section, re.IGNORECASE | re.MULTILINE)
+        if not match:
+            logger.warning(f"Field '{field_name}' not found in section")
+            return None, None
+        
+        groups = match.groups()
+        
+        # Extract amount (first group)
+        amount_str = groups[0] if len(groups) > 0 else None
+        amount = self._parse_amount(amount_str)
+        
+        # Extract currency (second group)
+        currency = groups[1] if len(groups) > 1 else None
+        
+        return amount, currency
+    
+    def parse(self) -> Dict:
+        """
+        Parse incrementables data from text.
+        
+        Returns:
+            Dictionary with parsed data including:
+            - currency
+            - fletes
+            - seguros (may be None)
+            - almacenaje_consolidacion
+            - regalias (may be None)
+            - warnings
+            - anchors_found
+            
+        Raises:
+            ParsingError: If incrementables section not found or parsing fails
+        """
+        # Find the section
+        section = self._find_incrementables_section()
+        if not section:
+            raise ParsingError(
+                "Incrementables section not found. Expected anchor like 'AJUSTE DE INCREMENTABLES EN:'"
+            )
+        
+        logger.debug(f"Found section: {section[:200]}...")
+        
+        # Extract currency
+        currency = self._extract_currency(section)
+        
+        # Extract fields
+        fletes, _ = self._extract_field(section, "fletes")
+        seguros, _ = self._extract_field(section, "seguros")
+        almacenaje, _ = self._extract_field(section, "almacenaje")
+        regalias, _ = self._extract_field(section, "regalias")
+        
+        # Validate required fields
+        if fletes is None:
+            raise ParsingError("Required field 'fletes' not found or invalid")
+        
+        if almacenaje is None:
+            raise ParsingError("Required field 'almacenaje/consolidacion' not found or invalid")
+        
+        # seguros and regalias can be None (empty)
+        
+        return {
+            "currency": currency,
+            "fletes": fletes,
+            "seguros": seguros,
+            "almacenaje_consolidacion": almacenaje,
+            "regalias": regalias,
+            "warnings": self.warnings,
+            "anchors_found": self.anchors_found,
+        }
+
+
+def parse_incrementables(text: str) -> Dict:
+    """
+    Parse incrementables data from PDF text.
+    
+    Args:
+        text: Extracted text from PDF
+        
+    Returns:
+        Dictionary with parsed incrementables data
+        
+    Raises:
+        ParsingError: If parsing fails
+    """
+    parser = IncrementablesParser(text)
+    return parser.parse()

app/services/pdf_text.py

@@ -0,0 +1,112 @@
+"""PDF text extraction service using PyMuPDF and pdfplumber."""
+import fitz  # PyMuPDF
+import pdfplumber
+import logging
+from typing import Tuple, Optional
+from io import BytesIO
+
+logger = logging.getLogger(__name__)
+
+
+class PDFExtractionError(Exception):
+    """Custom exception for PDF extraction errors."""
+    pass
+
+
+def extract_text_with_pymupdf(pdf_bytes: bytes) -> Tuple[str, int]:
+    """
+    Extract text from PDF using PyMuPDF (fitz).
+    
+    Args:
+        pdf_bytes: PDF file content as bytes
+        
+    Returns:
+        Tuple of (extracted_text, page_count)
+        
+    Raises:
+        PDFExtractionError: If extraction fails
+    """
+    try:
+        doc = fitz.open(stream=pdf_bytes, filetype="pdf")
+        
+        if doc.is_encrypted:
+            raise PDFExtractionError("PDF is encrypted and cannot be read")
+        
+        page_count = len(doc)
+        text_parts = []
+        
+        for page in doc:
+            text_parts.append(page.get_text())
+        
+        doc.close()
+        full_text = "\n".join(text_parts)
+        
+        logger.info(f"Extracted {len(full_text)} characters using PyMuPDF from {page_count} pages")
+        return full_text, page_count
+        
+    except Exception as e:
+        logger.warning(f"PyMuPDF extraction failed: {str(e)}")
+        raise PDFExtractionError(f"PyMuPDF extraction failed: {str(e)}")
+
+
+def extract_text_with_pdfplumber(pdf_bytes: bytes) -> Tuple[str, int]:
+    """
+    Extract text from PDF using pdfplumber (fallback method).
+    
+    Args:
+        pdf_bytes: PDF file content as bytes
+        
+    Returns:
+        Tuple of (extracted_text, page_count)
+        
+    Raises:
+        PDFExtractionError: If extraction fails
+    """
+    try:
+        with pdfplumber.open(BytesIO(pdf_bytes)) as pdf:
+            page_count = len(pdf.pages)
+            text_parts = []
+            
+            for page in pdf.pages:
+                page_text = page.extract_text()
+                if page_text:
+                    text_parts.append(page_text)
+            
+            full_text = "\n".join(text_parts)
+            
+            logger.info(f"Extracted {len(full_text)} characters using pdfplumber from {page_count} pages")
+            return full_text, page_count
+            
+    except Exception as e:
+        logger.error(f"pdfplumber extraction failed: {str(e)}")
+        raise PDFExtractionError(f"pdfplumber extraction failed: {str(e)}")
+
+
+def extract_text_from_pdf(pdf_bytes: bytes) -> Tuple[str, int, str]:
+    """
+    Extract text from PDF using available methods.
+    Tries PyMuPDF first, falls back to pdfplumber.
+    
+    Args:
+        pdf_bytes: PDF file content as bytes
+        
+    Returns:
+        Tuple of (extracted_text, page_count, method_used)
+        
+    Raises:
+        PDFExtractionError: If all extraction methods fail
+    """
+    # Try PyMuPDF first
+    try:
+        text, pages = extract_text_with_pymupdf(pdf_bytes)
+        return text, pages, "text"
+    except PDFExtractionError as e:
+        logger.warning(f"PyMuPDF failed, trying pdfplumber: {str(e)}")
+    
+    # Fallback to pdfplumber
+    try:
+        text, pages = extract_text_with_pdfplumber(pdf_bytes)
+        return text, pages, "text"
+    except PDFExtractionError as e:
+        logger.error(f"All extraction methods failed: {str(e)}")
+        raise PDFExtractionError("Failed to extract text from PDF using all available methods")

app/tasks/parse_tasks.py

@@ -0,0 +1,95 @@
+"""Celery tasks for PDF parsing."""
+import logging
+import hashlib
+from app.core.celery_app import celery_app
+from app.services.pdf_text import extract_text_from_pdf, PDFExtractionError
+from app.services.parser import parse_incrementables, ParsingError
+
+logger = logging.getLogger(__name__)
+
+
+@celery_app.task(bind=True, name="parse_pdf_task")
+def parse_pdf_task(self, pdf_bytes_hex: str, filename: str, document_ref: str = None):
+    """
+    Celery task to parse PDF incrementables asynchronously.
+    
+    Args:
+        self: Celery task instance
+        pdf_bytes_hex: PDF content as hex string (to serialize)
+        filename: Original filename
+        document_ref: Optional document reference
+        
+    Returns:
+        Dictionary with parsed data or error information
+    """
+    task_id = self.request.id
+    logger.info(f"Starting PDF parse task {task_id} for {filename}")
+    
+    try:
+        # Convert hex back to bytes
+        pdf_bytes = bytes.fromhex(pdf_bytes_hex)
+        
+        # Calculate SHA256
+        file_hash = hashlib.sha256(pdf_bytes).hexdigest()
+        
+        # Extract text
+        try:
+            text, page_count, extraction_method = extract_text_from_pdf(pdf_bytes)
+            logger.info(f"Task {task_id}: Extracted {len(text)} chars from {page_count} pages")
+        except PDFExtractionError as e:
+            logger.error(f"Task {task_id}: Extraction failed - {str(e)}")
+            return {
+                "status": "failed",
+                "error": "extraction_failed",
+                "message": str(e),
+                "task_id": task_id
+            }
+        
+        # Parse incrementables
+        try:
+            parsed_data = parse_incrementables(text)
+            logger.info(f"Task {task_id}: Successfully parsed incrementables")
+        except ParsingError as e:
+            logger.error(f"Task {task_id}: Parsing failed - {str(e)}")
+            return {
+                "status": "failed",
+                "error": "parsing_failed",
+                "message": str(e),
+                "task_id": task_id
+            }
+        
+        # Build successful response
+        result = {
+            "status": "completed",
+            "task_id": task_id,
+            "document": {
+                "filename": filename,
+                "pages": page_count,
+                "sha256": file_hash,
+                "document_ref": document_ref
+            },
+            "incrementables": {
+                "currency": parsed_data["currency"],
+                "fletes": parsed_data["fletes"],
+                "seguros": parsed_data["seguros"],
+                "almacenaje_consolidacion": parsed_data["almacenaje_consolidacion"],
+                "regalias": parsed_data["regalias"]
+            },
+            "extraction": {
+                "method": extraction_method,
+                "anchors_found": parsed_data["anchors_found"],
+                "warnings": parsed_data["warnings"]
+            }
+        }
+        
+        logger.info(f"Task {task_id}: Completed successfully")
+        return result
+        
+    except Exception as e:
+        logger.error(f"Task {task_id}: Unexpected error - {str(e)}", exc_info=True)
+        return {
+            "status": "failed",
+            "error": "unexpected_error",
+            "message": str(e),
+            "task_id": task_id
+        }