paddleocr-skills 1.0.0 → 1.1.0

package/templates/ppocrv5/scripts/ppocrv5/_lib.py

@@ -1,635 +1,635 @@
-"""
-Core library for PP-OCRv5 API Skill
-- ProviderClient: HTTP client for Paddle AI Studio API
-- Mapper: snake_case <-> camelCase conversion
-- Normalizer: Provider response -> normalized output
-- QualityEvaluator: Quality scoring for auto mode
-"""
-
-import hashlib
-import json
-import logging
-import math
-import os
-import re
-import sys
-import time
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-
-import httpx
-
-logger = logging.getLogger(__name__)
-
-# =============================================================================
-# Constants
-# =============================================================================
-
-# Quality scoring weights
-QUALITY_TEXT_COUNT_WEIGHT = 0.6
-QUALITY_CONFIDENCE_WEIGHT = 0.4
-QUALITY_THRESHOLD_DEFAULT = 0.72
-
-# Retry and timeout
-DEFAULT_TIMEOUT_MS = 25000
-DEFAULT_MAX_RETRY = 2
-DEFAULT_CACHE_TTL_SEC = 600
-
-# Normalization constants
-NORM_REFERENCE_COUNT = 50  # Reference count for normalization
-
-
-# =============================================================================
-# Environment & Config
-# =============================================================================
-
-class Config:
-    """
-    Configuration manager - reads from .env file and environment variables
-
-    Priority order:
-    1. Environment variables (already set in shell)
-    2. .env file in project root
-    3. Raise error if not found
-    """
-
-    _env_loaded = False
-
-    @staticmethod
-    def load_env():
-        """Load .env file using python-dotenv"""
-        if Config._env_loaded:
-            return
-
-        try:
-            from dotenv import load_dotenv
-
-            # Find .env file (in project root, which is parent of scripts/)
-            project_root = Path(__file__).parent.parent
-            env_file = project_root / ".env"
-
-            if env_file.exists():
-                load_dotenv(env_file)
-                logger.debug(f"Loaded .env from {env_file}")
-            else:
-                logger.debug(f".env file not found at {env_file}")
-
-            Config._env_loaded = True
-
-        except ImportError:
-            logger.warning("python-dotenv not installed, skipping .env file loading")
-            logger.warning("Install with: pip install python-dotenv")
-            Config._env_loaded = True
-
-    @staticmethod
-    def get_api_url() -> str:
-        """
-        Get API URL from environment.
-
-        Priority:
-        1. API_URL environment variable
-        2. AISTUDIO_HOST environment variable (legacy)
-
-        Returns:
-            Full API URL (https://...com/ocr)
-        """
-        Config.load_env()
-
-        # Priority 1: Direct API_URL
-        api_url = os.getenv("API_URL", "").strip()
-        if api_url:
-            # Normalize: ensure it starts with https:// and ends with /ocr
-            api_url = re.sub(r'^https?://', '', api_url)  # Remove protocol
-            api_url = re.sub(r'/ocr$', '', api_url)  # Remove /ocr if exists
-            return f"https://{api_url}/ocr"
-
-        # Priority 2: Legacy AISTUDIO_HOST
-        host = os.getenv("AISTUDIO_HOST", "").strip()
-        if host:
-            host = Config.normalize_host(host)
-            return f"https://{host}/ocr"
-
-        # Not found
-        raise ValueError(
-            "API not configured. Get your API at: https://aistudio.baidu.com/paddleocr/task"
-        )
-
-    @staticmethod
-    def normalize_host(host: str) -> str:
-        """
-        Normalize host to bare hostname without protocol or path.
-        Examples:
-          - your-subdomain.aistudio-app.com -> your-subdomain.aistudio-app.com
-          - https://your-subdomain.aistudio-app.com -> your-subdomain.aistudio-app.com
-          - https://your-subdomain.aistudio-app.com/ocr -> your-subdomain.aistudio-app.com
-        """
-        # Remove http:// or https://
-        host = re.sub(r'^https?://', '', host)
-        # Remove trailing path (e.g., /ocr or /)
-        host = re.sub(r'/.*$', '', host)
-        return host.strip()
-
-    @staticmethod
-    def get_token() -> str:
-        """
-        Get token from environment.
-
-        Priority:
-          1. PADDLE_OCR_TOKEN environment variable
-          2. PADDLE_OCR_TOKEN_FALLBACK key
-          3. COZE_PP_OCRV5_* prefix scan
-        """
-        Config.load_env()
-
-        # Priority 1: Direct token
-        token = os.getenv("PADDLE_OCR_TOKEN", "").strip()
-        if token:
-            return token
-
-        # Priority 2: Fallback env key
-        fallback_key = os.getenv("PADDLE_OCR_TOKEN_FALLBACK", "").strip()
-        if fallback_key:
-            token = os.getenv(fallback_key, "").strip()
-            if token:
-                logger.info(f"Using token from fallback key: {fallback_key}")
-                return token
-
-        # Priority 3: Scan for COZE_PP_OCRV5_ prefix
-        for key, value in os.environ.items():
-            if key.startswith("COZE_PP_OCRV5_"):
-                logger.info(f"Using token from auto-detected key: {key}")
-                return value.strip()
-
-        # Not found
-        raise ValueError(
-            "TOKEN not configured. Get your API at: https://aistudio.baidu.com/paddleocr/task"
-        )
-
-    @staticmethod
-    def get_timeout_ms() -> int:
-        return int(os.getenv("PADDLE_OCR_TIMEOUT_MS", str(DEFAULT_TIMEOUT_MS)))
-
-    @staticmethod
-    def get_max_retry() -> int:
-        return int(os.getenv("PADDLE_OCR_MAX_RETRY", str(DEFAULT_MAX_RETRY)))
-
-    @staticmethod
-    def get_cache_ttl_sec() -> int:
-        return int(os.getenv("PADDLE_OCR_CACHE_TTL_SEC", str(DEFAULT_CACHE_TTL_SEC)))
-
-
-# =============================================================================
-# Mapper: snake_case <-> camelCase
-# =============================================================================
-
-class Mapper:
-    """Convert between snake_case (Python) and camelCase (Provider API)"""
-
-    @staticmethod
-    def snake_to_camel(name: str) -> str:
-        """Convert snake_case to camelCase"""
-        components = name.split('_')
-        return components[0] + ''.join(x.title() for x in components[1:])
-
-    @staticmethod
-    def camel_to_snake(name: str) -> str:
-        """Convert camelCase to snake_case"""
-        s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
-        return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
-
-    @staticmethod
-    def dict_to_camel(data: Dict[str, Any]) -> Dict[str, Any]:
-        """Convert dict keys from snake_case to camelCase, drop None values"""
-        result = {}
-        for k, v in data.items():
-            if v is None:
-                continue  # Drop None values
-            camel_key = Mapper.snake_to_camel(k)
-            result[camel_key] = v
-        return result
-
-    @staticmethod
-    def dict_to_snake(data: Dict[str, Any]) -> Dict[str, Any]:
-        """Convert dict keys from camelCase to snake_case"""
-        result = {}
-        for k, v in data.items():
-            snake_key = Mapper.camel_to_snake(k)
-            result[snake_key] = v
-        return result
-
-
-# =============================================================================
-# Quality Evaluator
-# =============================================================================
-
-class QualityEvaluator:
-    """Evaluate OCR quality based on text items and scores"""
-
-    @staticmethod
-    def norm(n: int, max_n: int = NORM_REFERENCE_COUNT) -> float:
-        """Normalize text count: min(1, log(1+n)/log(1+max_n))"""
-        if n <= 0:
-            return 0.0
-        return min(1.0, math.log(1 + n) / math.log(1 + max_n))
-
-    @staticmethod
-    def evaluate(rec_texts: List[str], rec_scores: Optional[List[float]] = None) -> Dict[str, Any]:
-        """
-        Evaluate quality from provider's prunedResult
-        Returns: {
-          "quality_score": float,
-          "avg_rec_score": float,
-          "text_items": int,
-          "warnings": List[str]
-        }
-        """
-        text_items = len(rec_texts) if rec_texts else 0
-        warnings = []
-
-        # Average recognition score
-        if rec_scores and len(rec_scores) > 0:
-            avg_rec_score = sum(rec_scores) / len(rec_scores)
-        else:
-            avg_rec_score = 0.5  # Default if missing
-            if text_items > 0:
-                warnings.append("rec_scores missing, using default 0.5")
-
-        # Quality score: weighted combination of text count and confidence
-        if text_items == 0:
-            quality_score = 0.0
-            warnings.append("No text items detected")
-        else:
-            norm_count = QualityEvaluator.norm(text_items)
-            quality_score = QUALITY_TEXT_COUNT_WEIGHT * norm_count + QUALITY_CONFIDENCE_WEIGHT * avg_rec_score
-
-        return {
-            "quality_score": round(quality_score, 4),
-            "avg_rec_score": round(avg_rec_score, 4),
-            "text_items": text_items,
-            "warnings": warnings
-        }
-
-
-# =============================================================================
-# Normalizer
-# =============================================================================
-
-class Normalizer:
-    """Normalize provider response to unified output schema"""
-
-    @staticmethod
-    def normalize_response(
-        provider_response: Dict[str, Any],
-        request_id: str,
-        api_url: str,
-        status_code: int,
-        mode: str,
-        selected_attempt: int,
-        attempts_history: List[Dict[str, Any]],
-        return_raw: bool = False
-    ) -> Dict[str, Any]:
-        """
-        Convert provider response to normalized output.
-
-        Args:
-            provider_response: Raw response from provider
-            request_id: Unique request ID
-            api_url: API endpoint used
-            status_code: HTTP status code
-            mode: fast/quality/auto
-            selected_attempt: Which attempt was selected (1-indexed)
-            attempts_history: List of attempt details
-            return_raw: Whether to include raw_provider in output
-
-        Returns:
-            Normalized output dict
-        """
-        error_code = provider_response.get("errorCode", -1)
-
-        if error_code != 0:
-            # Error response
-            error_msg = provider_response.get("errorMsg", "Unknown error")
-            return {
-                "ok": False,
-                "request_id": request_id,
-                "provider": {
-                    "api_url": api_url,
-                    "status_code": status_code,
-                    "log_id": provider_response.get("logId")
-                },
-                "result": None,
-                "quality": None,
-                "agent_trace": {
-                    "mode": mode,
-                    "selected_attempt": selected_attempt,
-                    "attempts": attempts_history
-                },
-                "raw_provider": provider_response if return_raw else None,
-                "error": {
-                    "code": Normalizer._map_error_code(error_code, status_code),
-                    "message": error_msg,
-                    "details": {
-                        "error_code": error_code,
-                        "status_code": status_code
-                    }
-                }
-            }
-
-        # Success response
-        result = provider_response.get("result", {})
-        ocr_results = result.get("ocrResults", [])
-
-        pages = []
-        all_texts = []
-        total_items = 0
-        total_scores_sum = 0.0
-        total_scores_count = 0
-
-        for page_idx, ocr_res in enumerate(ocr_results):
-            pruned = ocr_res.get("prunedResult", {})
-            rec_texts = pruned.get("rec_texts", [])
-            rec_scores = pruned.get("rec_scores", [])
-            rec_boxes = pruned.get("rec_boxes", [])
-            rec_polys = pruned.get("rec_polys", [])
-
-            items = []
-            page_text_lines = []
-
-            for i, text in enumerate(rec_texts):
-                score = rec_scores[i] if i < len(rec_scores) else None
-                box = None
-                if i < len(rec_boxes):
-                    box = rec_boxes[i]
-                elif i < len(rec_polys):
-                    # Flatten polygon to box (simplified)
-                    box = rec_polys[i]
-
-                item = {"text": text}
-                if score is not None:
-                    item["score"] = round(score, 4)
-                    total_scores_sum += score
-                    total_scores_count += 1
-                if box is not None:
-                    item["box"] = box
-
-                items.append(item)
-                page_text_lines.append(text)
-                total_items += 1
-
-            page_text = "\n".join(page_text_lines)
-            all_texts.append(page_text)
-
-            page_avg_conf = 0.0
-            if total_scores_count > 0:
-                page_avg_conf = total_scores_sum / total_scores_count
-
-            pages.append({
-                "page_index": page_idx,
-                "text": page_text,
-                "avg_confidence": round(page_avg_conf, 4) if items else 0.0,
-                "items": items
-            })
-
-        full_text = "\n\n".join(all_texts)
-
-        # Get quality from last attempt (selected one)
-        quality_info = None
-        if attempts_history and selected_attempt <= len(attempts_history):
-            last_attempt = attempts_history[selected_attempt - 1]
-            quality_info = {
-                "quality_score": last_attempt.get("quality_score", 0.0),
-                "avg_rec_score": last_attempt.get("avg_rec_score", 0.0),
-                "text_items": total_items,
-                "warnings": last_attempt.get("warnings", [])
-            }
-        else:
-            # Fallback: compute quality on the fly
-            quality_info = QualityEvaluator.evaluate(
-                rec_texts=[item["text"] for page in pages for item in page["items"]],
-                rec_scores=[item.get("score") for page in pages for item in page["items"] if "score" in item]
-            )
-
-        return {
-            "ok": True,
-            "request_id": request_id,
-            "provider": {
-                "api_url": api_url,
-                "status_code": status_code,
-                "log_id": provider_response.get("logId")
-            },
-            "result": {
-                "pages": pages,
-                "full_text": full_text
-            },
-            "quality": quality_info,
-            "agent_trace": {
-                "mode": mode,
-                "selected_attempt": selected_attempt,
-                "attempts": attempts_history
-            },
-            "raw_provider": provider_response if return_raw else None,
-            "error": None
-        }
-
-    @staticmethod
-    def _map_error_code(error_code: int, status_code: int) -> str:
-        """Map provider error code to unified error code"""
-        if status_code == 403:
-            return "PROVIDER_AUTH_ERROR"
-        elif status_code == 429:
-            return "PROVIDER_QUOTA_EXCEEDED"
-        elif status_code == 503:
-            return "PROVIDER_OVERLOADED"
-        elif status_code == 504:
-            return "PROVIDER_TIMEOUT"
-        elif error_code == 500:
-            return "PROVIDER_BAD_REQUEST"
-        else:
-            return "PROVIDER_ERROR"
-
-
-# =============================================================================
-# Provider Client
-# =============================================================================
-
-class ProviderClient:
-    """HTTP client for Paddle AI Studio PP-OCRv5 API"""
-
-    def __init__(
-        self,
-        api_url: str,
-        token: str,
-        timeout_ms: int = 25000,
-        max_retry: int = 2
-    ):
-        self.api_url = api_url
-        self.token = token
-        self.timeout_ms = timeout_ms
-        self.max_retry = max_retry
-        self.client = httpx.Client(timeout=timeout_ms / 1000.0)
-
-    def call(self, payload: Dict[str, Any]) -> Tuple[Dict[str, Any], int, float]:
-        """
-        Call provider API with retry on 503/504.
-
-        Returns:
-            (response_json, status_code, elapsed_ms)
-        """
-        headers = {
-            "Authorization": f"token {self.token}",
-            "Content-Type": "application/json"
-        }
-
-        attempt = 0
-        while attempt <= self.max_retry:
-            start_time = time.time()
-            try:
-                resp = self.client.post(self.api_url, json=payload, headers=headers)
-                elapsed_ms = (time.time() - start_time) * 1000
-
-                # Parse response
-                try:
-                    resp_json = resp.json()
-                except (json.JSONDecodeError, ValueError) as e:
-                    logger.warning(f"Failed to parse JSON response: {e}")
-                    resp_json = {"errorCode": -1, "errorMsg": "Invalid JSON response"}
-
-                # Retry on 503/504
-                if resp.status_code in [503, 504] and attempt < self.max_retry:
-                    logger.warning(f"Attempt {attempt + 1} failed with {resp.status_code}, retrying...")
-                    backoff_ms = 200 * (4 ** attempt) + (hash(str(time.time())) % 100)
-                    time.sleep(backoff_ms / 1000.0)
-                    attempt += 1
-                    continue
-
-                return resp_json, resp.status_code, elapsed_ms
-
-            except httpx.TimeoutException:
-                elapsed_ms = (time.time() - start_time) * 1000
-                if attempt < self.max_retry:
-                    logger.warning(f"Attempt {attempt + 1} timed out, retrying...")
-                    backoff_ms = 200 * (4 ** attempt) + (hash(str(time.time())) % 100)
-                    time.sleep(backoff_ms / 1000.0)
-                    attempt += 1
-                    continue
-                else:
-                    return {
-                        "errorCode": 504,
-                        "errorMsg": "Request timed out"
-                    }, 504, elapsed_ms
-
-            except Exception as e:
-                elapsed_ms = (time.time() - start_time) * 1000
-                logger.error(f"Request failed: {e}")
-                return {
-                    "errorCode": -1,
-                    "errorMsg": f"Request failed: {str(e)}"
-                }, 500, elapsed_ms
-
-        # Should not reach here
-        return {"errorCode": -1, "errorMsg": "Max retries exceeded"}, 500, 0.0
-
-    def close(self):
-        """Close HTTP client"""
-        self.client.close()
-
-
-# =============================================================================
-# Cache
-# =============================================================================
-
-class SimpleCache:
-    """In-memory TTL cache for normalized results"""
-
-    def __init__(self, ttl_sec: int = 600):
-        self.ttl_sec = ttl_sec
-        self._cache: Dict[str, Tuple[Any, float]] = {}
-
-    def get(self, key: str) -> Optional[Any]:
-        """Get cached value if not expired"""
-        if key in self._cache:
-            value, expiry = self._cache[key]
-            if time.time() < expiry:
-                return value
-            else:
-                del self._cache[key]
-        return None
-
-    def set(self, key: str, value: Any):
-        """Set cache value with TTL"""
-        expiry = time.time() + self.ttl_sec
-        self._cache[key] = (value, expiry)
-
-    @staticmethod
-    def make_key(file_input: str, options: Dict[str, Any]) -> str:
-        """
-        Generate cache key from file and options.
-        For performance, only hash first 1KB of large inputs.
-        """
-        # For large inputs (base64 encoded files), only hash first 1KB
-        input_sample = file_input[:1024] if len(file_input) > 1024 else file_input
-        file_hash = hashlib.sha256(input_sample.encode()).hexdigest()[:16]
-
-        options_str = json.dumps(options, sort_keys=True)
-        options_hash = hashlib.sha256(options_str.encode()).hexdigest()[:16]
-        return f"{file_hash}_{options_hash}"
-
-
-# =============================================================================
-# Agent Policy
-# =============================================================================
-
-class AgentPolicy:
-    """Generate attempt strategies for auto mode"""
-
-    @staticmethod
-    def get_attempts_config(mode: str, max_attempts: int = 3) -> List[Dict[str, Any]]:
-        """
-        Get list of attempt configurations based on mode.
-
-        Args:
-            mode: 'fast', 'quality', or 'auto'
-            max_attempts: Max attempts for auto mode
-
-        Returns:
-            List of option dicts
-        """
-        if mode == "fast":
-            return [{
-                "use_doc_orientation_classify": False,
-                "use_doc_unwarping": False,
-                "use_textline_orientation": False
-            }]
-
-        elif mode == "quality":
-            return [{
-                "use_doc_orientation_classify": True,
-                "use_doc_unwarping": True,
-                "use_textline_orientation": False
-            }]
-
-        elif mode == "auto":
-            attempts = [
-                # Attempt 1: fast path
-                {
-                    "use_doc_orientation_classify": False,
-                    "use_doc_unwarping": False,
-                    "use_textline_orientation": False
-                },
-                # Attempt 2: orientation fix
-                {
-                    "use_doc_orientation_classify": True,
-                    "use_doc_unwarping": False,
-                    "use_textline_orientation": False
-                },
-                # Attempt 3: unwarping fix
-                {
-                    "use_doc_orientation_classify": True,
-                    "use_doc_unwarping": True,
-                    "use_textline_orientation": False
-                }
-            ]
-            return attempts[:max_attempts]
-
-        else:
-            raise ValueError(f"Unknown mode: {mode}")
+"""
+Core library for PP-OCRv5 API Skill
+- ProviderClient: HTTP client for Paddle AI Studio API
+- Mapper: snake_case <-> camelCase conversion
+- Normalizer: Provider response -> normalized output
+- QualityEvaluator: Quality scoring for auto mode
+"""
+
+import hashlib
+import json
+import logging
+import math
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+# Quality scoring weights
+QUALITY_TEXT_COUNT_WEIGHT = 0.6
+QUALITY_CONFIDENCE_WEIGHT = 0.4
+QUALITY_THRESHOLD_DEFAULT = 0.72
+
+# Retry and timeout
+DEFAULT_TIMEOUT_MS = 25000
+DEFAULT_MAX_RETRY = 2
+DEFAULT_CACHE_TTL_SEC = 600
+
+# Normalization constants
+NORM_REFERENCE_COUNT = 50  # Reference count for normalization
+
+
+# =============================================================================
+# Environment & Config
+# =============================================================================
+
+class Config:
+    """
+    Configuration manager - reads from .env file and environment variables
+
+    Priority order:
+    1. Environment variables (already set in shell)
+    2. .env file in project root
+    3. Raise error if not found
+    """
+
+    _env_loaded = False
+
+    @staticmethod
+    def load_env():
+        """Load .env file using python-dotenv"""
+        if Config._env_loaded:
+            return
+
+        try:
+            from dotenv import load_dotenv
+
+            # Find .env file (in project root, which is parent of scripts/)
+            project_root = Path(__file__).parent.parent
+            env_file = project_root / ".env"
+
+            if env_file.exists():
+                load_dotenv(env_file)
+                logger.debug(f"Loaded .env from {env_file}")
+            else:
+                logger.debug(f".env file not found at {env_file}")
+
+            Config._env_loaded = True
+
+        except ImportError:
+            logger.warning("python-dotenv not installed, skipping .env file loading")
+            logger.warning("Install with: pip install python-dotenv")
+            Config._env_loaded = True
+
+    @staticmethod
+    def get_api_url() -> str:
+        """
+        Get API URL from environment.
+
+        Priority:
+        1. API_URL environment variable
+        2. AISTUDIO_HOST environment variable (legacy)
+
+        Returns:
+            Full API URL (https://...com/ocr)
+        """
+        Config.load_env()
+
+        # Priority 1: Direct API_URL
+        api_url = os.getenv("API_URL", "").strip()
+        if api_url:
+            # Normalize: ensure it starts with https:// and ends with /ocr
+            api_url = re.sub(r'^https?://', '', api_url)  # Remove protocol
+            api_url = re.sub(r'/ocr$', '', api_url)  # Remove /ocr if exists
+            return f"https://{api_url}/ocr"
+
+        # Priority 2: Legacy AISTUDIO_HOST
+        host = os.getenv("AISTUDIO_HOST", "").strip()
+        if host:
+            host = Config.normalize_host(host)
+            return f"https://{host}/ocr"
+
+        # Not found
+        raise ValueError(
+            "API not configured. Get your API at: https://aistudio.baidu.com/paddleocr/task"
+        )
+
+    @staticmethod
+    def normalize_host(host: str) -> str:
+        """
+        Normalize host to bare hostname without protocol or path.
+        Examples:
+          - your-subdomain.aistudio-app.com -> your-subdomain.aistudio-app.com
+          - https://your-subdomain.aistudio-app.com -> your-subdomain.aistudio-app.com
+          - https://your-subdomain.aistudio-app.com/ocr -> your-subdomain.aistudio-app.com
+        """
+        # Remove http:// or https://
+        host = re.sub(r'^https?://', '', host)
+        # Remove trailing path (e.g., /ocr or /)
+        host = re.sub(r'/.*$', '', host)
+        return host.strip()
+
+    @staticmethod
+    def get_token() -> str:
+        """
+        Get token from environment.
+
+        Priority:
+          1. PADDLE_OCR_TOKEN environment variable
+          2. PADDLE_OCR_TOKEN_FALLBACK key
+          3. COZE_PP_OCRV5_* prefix scan
+        """
+        Config.load_env()
+
+        # Priority 1: Direct token
+        token = os.getenv("PADDLE_OCR_TOKEN", "").strip()
+        if token:
+            return token
+
+        # Priority 2: Fallback env key
+        fallback_key = os.getenv("PADDLE_OCR_TOKEN_FALLBACK", "").strip()
+        if fallback_key:
+            token = os.getenv(fallback_key, "").strip()
+            if token:
+                logger.info(f"Using token from fallback key: {fallback_key}")
+                return token
+
+        # Priority 3: Scan for COZE_PP_OCRV5_ prefix
+        for key, value in os.environ.items():
+            if key.startswith("COZE_PP_OCRV5_"):
+                logger.info(f"Using token from auto-detected key: {key}")
+                return value.strip()
+
+        # Not found
+        raise ValueError(
+            "TOKEN not configured. Get your API at: https://aistudio.baidu.com/paddleocr/task"
+        )
+
+    @staticmethod
+    def get_timeout_ms() -> int:
+        return int(os.getenv("PADDLE_OCR_TIMEOUT_MS", str(DEFAULT_TIMEOUT_MS)))
+
+    @staticmethod
+    def get_max_retry() -> int:
+        return int(os.getenv("PADDLE_OCR_MAX_RETRY", str(DEFAULT_MAX_RETRY)))
+
+    @staticmethod
+    def get_cache_ttl_sec() -> int:
+        return int(os.getenv("PADDLE_OCR_CACHE_TTL_SEC", str(DEFAULT_CACHE_TTL_SEC)))
+
+
+# =============================================================================
+# Mapper: snake_case <-> camelCase
+# =============================================================================
+
+class Mapper:
+    """Convert between snake_case (Python) and camelCase (Provider API)"""
+
+    @staticmethod
+    def snake_to_camel(name: str) -> str:
+        """Convert snake_case to camelCase"""
+        components = name.split('_')
+        return components[0] + ''.join(x.title() for x in components[1:])
+
+    @staticmethod
+    def camel_to_snake(name: str) -> str:
+        """Convert camelCase to snake_case"""
+        s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
+        return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
+
+    @staticmethod
+    def dict_to_camel(data: Dict[str, Any]) -> Dict[str, Any]:
+        """Convert dict keys from snake_case to camelCase, drop None values"""
+        result = {}
+        for k, v in data.items():
+            if v is None:
+                continue  # Drop None values
+            camel_key = Mapper.snake_to_camel(k)
+            result[camel_key] = v
+        return result
+
+    @staticmethod
+    def dict_to_snake(data: Dict[str, Any]) -> Dict[str, Any]:
+        """Convert dict keys from camelCase to snake_case"""
+        result = {}
+        for k, v in data.items():
+            snake_key = Mapper.camel_to_snake(k)
+            result[snake_key] = v
+        return result
+
+
+# =============================================================================
+# Quality Evaluator
+# =============================================================================
+
+class QualityEvaluator:
+    """Evaluate OCR quality based on text items and scores"""
+
+    @staticmethod
+    def norm(n: int, max_n: int = NORM_REFERENCE_COUNT) -> float:
+        """Normalize text count: min(1, log(1+n)/log(1+max_n))"""
+        if n <= 0:
+            return 0.0
+        return min(1.0, math.log(1 + n) / math.log(1 + max_n))
+
+    @staticmethod
+    def evaluate(rec_texts: List[str], rec_scores: Optional[List[float]] = None) -> Dict[str, Any]:
+        """
+        Evaluate quality from provider's prunedResult
+        Returns: {
+          "quality_score": float,
+          "avg_rec_score": float,
+          "text_items": int,
+          "warnings": List[str]
+        }
+        """
+        text_items = len(rec_texts) if rec_texts else 0
+        warnings = []
+
+        # Average recognition score
+        if rec_scores and len(rec_scores) > 0:
+            avg_rec_score = sum(rec_scores) / len(rec_scores)
+        else:
+            avg_rec_score = 0.5  # Default if missing
+            if text_items > 0:
+                warnings.append("rec_scores missing, using default 0.5")
+
+        # Quality score: weighted combination of text count and confidence
+        if text_items == 0:
+            quality_score = 0.0
+            warnings.append("No text items detected")
+        else:
+            norm_count = QualityEvaluator.norm(text_items)
+            quality_score = QUALITY_TEXT_COUNT_WEIGHT * norm_count + QUALITY_CONFIDENCE_WEIGHT * avg_rec_score
+
+        return {
+            "quality_score": round(quality_score, 4),
+            "avg_rec_score": round(avg_rec_score, 4),
+            "text_items": text_items,
+            "warnings": warnings
+        }
+
+
+# =============================================================================
+# Normalizer
+# =============================================================================
+
+class Normalizer:
+    """Normalize provider response to unified output schema"""
+
+    @staticmethod
+    def normalize_response(
+        provider_response: Dict[str, Any],
+        request_id: str,
+        api_url: str,
+        status_code: int,
+        mode: str,
+        selected_attempt: int,
+        attempts_history: List[Dict[str, Any]],
+        return_raw: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Convert provider response to normalized output.
+
+        Args:
+            provider_response: Raw response from provider
+            request_id: Unique request ID
+            api_url: API endpoint used
+            status_code: HTTP status code
+            mode: fast/quality/auto
+            selected_attempt: Which attempt was selected (1-indexed)
+            attempts_history: List of attempt details
+            return_raw: Whether to include raw_provider in output
+
+        Returns:
+            Normalized output dict
+        """
+        error_code = provider_response.get("errorCode", -1)
+
+        if error_code != 0:
+            # Error response
+            error_msg = provider_response.get("errorMsg", "Unknown error")
+            return {
+                "ok": False,
+                "request_id": request_id,
+                "provider": {
+                    "api_url": api_url,
+                    "status_code": status_code,
+                    "log_id": provider_response.get("logId")
+                },
+                "result": None,
+                "quality": None,
+                "agent_trace": {
+                    "mode": mode,
+                    "selected_attempt": selected_attempt,
+                    "attempts": attempts_history
+                },
+                "raw_provider": provider_response if return_raw else None,
+                "error": {
+                    "code": Normalizer._map_error_code(error_code, status_code),
+                    "message": error_msg,
+                    "details": {
+                        "error_code": error_code,
+                        "status_code": status_code
+                    }
+                }
+            }
+
+        # Success response
+        result = provider_response.get("result", {})
+        ocr_results = result.get("ocrResults", [])
+
+        pages = []
+        all_texts = []
+        total_items = 0
+        total_scores_sum = 0.0
+        total_scores_count = 0
+
+        for page_idx, ocr_res in enumerate(ocr_results):
+            pruned = ocr_res.get("prunedResult", {})
+            rec_texts = pruned.get("rec_texts", [])
+            rec_scores = pruned.get("rec_scores", [])
+            rec_boxes = pruned.get("rec_boxes", [])
+            rec_polys = pruned.get("rec_polys", [])
+
+            items = []
+            page_text_lines = []
+
+            for i, text in enumerate(rec_texts):
+                score = rec_scores[i] if i < len(rec_scores) else None
+                box = None
+                if i < len(rec_boxes):
+                    box = rec_boxes[i]
+                elif i < len(rec_polys):
+                    # Flatten polygon to box (simplified)
+                    box = rec_polys[i]
+
+                item = {"text": text}
+                if score is not None:
+                    item["score"] = round(score, 4)
+                    total_scores_sum += score
+                    total_scores_count += 1
+                if box is not None:
+                    item["box"] = box
+
+                items.append(item)
+                page_text_lines.append(text)
+                total_items += 1
+
+            page_text = "\n".join(page_text_lines)
+            all_texts.append(page_text)
+
+            page_avg_conf = 0.0
+            if total_scores_count > 0:
+                page_avg_conf = total_scores_sum / total_scores_count
+
+            pages.append({
+                "page_index": page_idx,
+                "text": page_text,
+                "avg_confidence": round(page_avg_conf, 4) if items else 0.0,
+                "items": items
+            })
+
+        full_text = "\n\n".join(all_texts)
+
+        # Get quality from last attempt (selected one)
+        quality_info = None
+        if attempts_history and selected_attempt <= len(attempts_history):
+            last_attempt = attempts_history[selected_attempt - 1]
+            quality_info = {
+                "quality_score": last_attempt.get("quality_score", 0.0),
+                "avg_rec_score": last_attempt.get("avg_rec_score", 0.0),
+                "text_items": total_items,
+                "warnings": last_attempt.get("warnings", [])
+            }
+        else:
+            # Fallback: compute quality on the fly
+            quality_info = QualityEvaluator.evaluate(
+                rec_texts=[item["text"] for page in pages for item in page["items"]],
+                rec_scores=[item.get("score") for page in pages for item in page["items"] if "score" in item]
+            )
+
+        return {
+            "ok": True,
+            "request_id": request_id,
+            "provider": {
+                "api_url": api_url,
+                "status_code": status_code,
+                "log_id": provider_response.get("logId")
+            },
+            "result": {
+                "pages": pages,
+                "full_text": full_text
+            },
+            "quality": quality_info,
+            "agent_trace": {
+                "mode": mode,
+                "selected_attempt": selected_attempt,
+                "attempts": attempts_history
+            },
+            "raw_provider": provider_response if return_raw else None,
+            "error": None
+        }
+
+    @staticmethod
+    def _map_error_code(error_code: int, status_code: int) -> str:
+        """Map provider error code to unified error code"""
+        if status_code == 403:
+            return "PROVIDER_AUTH_ERROR"
+        elif status_code == 429:
+            return "PROVIDER_QUOTA_EXCEEDED"
+        elif status_code == 503:
+            return "PROVIDER_OVERLOADED"
+        elif status_code == 504:
+            return "PROVIDER_TIMEOUT"
+        elif error_code == 500:
+            return "PROVIDER_BAD_REQUEST"
+        else:
+            return "PROVIDER_ERROR"
+
+
+# =============================================================================
+# Provider Client
+# =============================================================================
+
+class ProviderClient:
+    """HTTP client for Paddle AI Studio PP-OCRv5 API"""
+
+    def __init__(
+        self,
+        api_url: str,
+        token: str,
+        timeout_ms: int = 25000,
+        max_retry: int = 2
+    ):
+        self.api_url = api_url
+        self.token = token
+        self.timeout_ms = timeout_ms
+        self.max_retry = max_retry
+        self.client = httpx.Client(timeout=timeout_ms / 1000.0)
+
+    def call(self, payload: Dict[str, Any]) -> Tuple[Dict[str, Any], int, float]:
+        """
+        Call provider API with retry on 503/504.
+
+        Returns:
+            (response_json, status_code, elapsed_ms)
+        """
+        headers = {
+            "Authorization": f"token {self.token}",
+            "Content-Type": "application/json"
+        }
+
+        attempt = 0
+        while attempt <= self.max_retry:
+            start_time = time.time()
+            try:
+                resp = self.client.post(self.api_url, json=payload, headers=headers)
+                elapsed_ms = (time.time() - start_time) * 1000
+
+                # Parse response
+                try:
+                    resp_json = resp.json()
+                except (json.JSONDecodeError, ValueError) as e:
+                    logger.warning(f"Failed to parse JSON response: {e}")
+                    resp_json = {"errorCode": -1, "errorMsg": "Invalid JSON response"}
+
+                # Retry on 503/504
+                if resp.status_code in [503, 504] and attempt < self.max_retry:
+                    logger.warning(f"Attempt {attempt + 1} failed with {resp.status_code}, retrying...")
+                    backoff_ms = 200 * (4 ** attempt) + (hash(str(time.time())) % 100)
+                    time.sleep(backoff_ms / 1000.0)
+                    attempt += 1
+                    continue
+
+                return resp_json, resp.status_code, elapsed_ms
+
+            except httpx.TimeoutException:
+                elapsed_ms = (time.time() - start_time) * 1000
+                if attempt < self.max_retry:
+                    logger.warning(f"Attempt {attempt + 1} timed out, retrying...")
+                    backoff_ms = 200 * (4 ** attempt) + (hash(str(time.time())) % 100)
+                    time.sleep(backoff_ms / 1000.0)
+                    attempt += 1
+                    continue
+                else:
+                    return {
+                        "errorCode": 504,
+                        "errorMsg": "Request timed out"
+                    }, 504, elapsed_ms
+
+            except Exception as e:
+                elapsed_ms = (time.time() - start_time) * 1000
+                logger.error(f"Request failed: {e}")
+                return {
+                    "errorCode": -1,
+                    "errorMsg": f"Request failed: {str(e)}"
+                }, 500, elapsed_ms
+
+        # Should not reach here
+        return {"errorCode": -1, "errorMsg": "Max retries exceeded"}, 500, 0.0
+
+    def close(self):
+        """Close HTTP client"""
+        self.client.close()
+
+
+# =============================================================================
+# Cache
+# =============================================================================
+
+class SimpleCache:
+    """In-memory TTL cache for normalized results"""
+
+    def __init__(self, ttl_sec: int = 600):
+        self.ttl_sec = ttl_sec
+        self._cache: Dict[str, Tuple[Any, float]] = {}
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get cached value if not expired"""
+        if key in self._cache:
+            value, expiry = self._cache[key]
+            if time.time() < expiry:
+                return value
+            else:
+                del self._cache[key]
+        return None
+
+    def set(self, key: str, value: Any):
+        """Set cache value with TTL"""
+        expiry = time.time() + self.ttl_sec
+        self._cache[key] = (value, expiry)
+
+    @staticmethod
+    def make_key(file_input: str, options: Dict[str, Any]) -> str:
+        """
+        Generate cache key from file and options.
+        For performance, only hash first 1KB of large inputs.
+        """
+        # For large inputs (base64 encoded files), only hash first 1KB
+        input_sample = file_input[:1024] if len(file_input) > 1024 else file_input
+        file_hash = hashlib.sha256(input_sample.encode()).hexdigest()[:16]
+
+        options_str = json.dumps(options, sort_keys=True)
+        options_hash = hashlib.sha256(options_str.encode()).hexdigest()[:16]
+        return f"{file_hash}_{options_hash}"
+
+
+# =============================================================================
+# Agent Policy
+# =============================================================================
+
+class AgentPolicy:
+    """Generate attempt strategies for auto mode"""
+
+    @staticmethod
+    def get_attempts_config(mode: str, max_attempts: int = 3) -> List[Dict[str, Any]]:
+        """
+        Get list of attempt configurations based on mode.
+
+        Args:
+            mode: 'fast', 'quality', or 'auto'
+            max_attempts: Max attempts for auto mode
+
+        Returns:
+            List of option dicts
+        """
+        if mode == "fast":
+            return [{
+                "use_doc_orientation_classify": False,
+                "use_doc_unwarping": False,
+                "use_textline_orientation": False
+            }]
+
+        elif mode == "quality":
+            return [{
+                "use_doc_orientation_classify": True,
+                "use_doc_unwarping": True,
+                "use_textline_orientation": False
+            }]
+
+        elif mode == "auto":
+            attempts = [
+                # Attempt 1: fast path
+                {
+                    "use_doc_orientation_classify": False,
+                    "use_doc_unwarping": False,
+                    "use_textline_orientation": False
+                },
+                # Attempt 2: orientation fix
+                {
+                    "use_doc_orientation_classify": True,
+                    "use_doc_unwarping": False,
+                    "use_textline_orientation": False
+                },
+                # Attempt 3: unwarping fix
+                {
+                    "use_doc_orientation_classify": True,
+                    "use_doc_unwarping": True,
+                    "use_textline_orientation": False
+                }
+            ]
+            return attempts[:max_attempts]
+
+        else:
+            raise ValueError(f"Unknown mode: {mode}")