"""Utility functions for DocuParse AI.""" from __future__ import annotations import json import logging import os import tempfile from pathlib import Path from typing import Optional logger = logging.getLogger(__name__) ALLOWED_EXTENSIONS = {".pdf", ".png", ".jpg", ".jpeg", ".txt"} MAX_FILE_SIZE_MB = 10 MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024 def validate_file(file_path: str) -> None: """ Validate file exists, has allowed extension, and is within size limits. Raises ValueError on failure. """ p = Path(file_path) if not p.exists(): raise ValueError(f"File not found: {file_path}") ext = p.suffix.lower() if ext not in ALLOWED_EXTENSIONS: raise ValueError( f"Unsupported file type: '{ext}'. Supported types: " + ", ".join(sorted(ALLOWED_EXTENSIONS)).upper() ) size = p.stat().st_size if size > MAX_FILE_SIZE_BYTES: raise ValueError( f"File too large: {size / 1024 / 1024:.1f} MB. Maximum allowed: {MAX_FILE_SIZE_MB} MB." ) def get_file_extension(file_path: str) -> str: """Return lowercase file extension including the dot.""" return Path(file_path).suffix.lower() def pretty_json(data: dict, indent: int = 2) -> str: """Serialise dict to formatted JSON string.""" return json.dumps(data, indent=indent, ensure_ascii=False, default=str) def setup_logging(level: str = "INFO") -> None: """Configure basic logging.""" logging.basicConfig( level=getattr(logging, level.upper(), logging.INFO), format="%(asctime)s | %(name)s | %(levelname)s | %(message)s", ) def save_temp_file(data: bytes, suffix: str) -> str: """Save bytes to a secure temporary file. Caller must delete it.""" fd, path = tempfile.mkstemp(suffix=suffix) try: with os.fdopen(fd, "wb") as f: f.write(data) except Exception: os.close(fd) raise return path def delete_temp_file(path: str) -> None: """Safely delete a temporary file.""" try: if path and os.path.exists(path): os.remove(path) except Exception as e: logger.warning("Could not delete temp file %s: %s", path, e) def truncate_text(text: str, max_chars: int = 8000) -> str: """Truncate text to maximum character count for LLM input.""" if len(text) <= max_chars: return text half = max_chars // 2 truncated = text[:half] + "\n\n[... TEXT TRUNCATED ...]\n\n" + text[-half:] logger.info("Document text truncated from %d to ~%d chars", len(text), max_chars) return truncated