paddleocr-skills 1.0.0

package/templates/ppocrv5/references/ppocrv5/agent_policy.md

@@ -0,0 +1,258 @@
+# Agent Policy: Auto Mode Strategy
+
+This document defines the execution strategies for the three OCR modes, with emphasis on the auto mode's adaptive retry logic.
+
+## Mode Overview
+
+| Mode | Strategy | Use Case |
+|------|----------|----------|
+| `fast` | Single call, all corrections off | Lowest latency, suitable for high-quality scans |
+| `quality` | Single call, all corrections on | Maximum quality, slower, suitable for complex documents |
+| `auto` | Adaptive multiple attempts, quality scoring | Balanced performance, production default |
+
+## Mode: fast
+
+**Single attempt**, minimal preprocessing.
+
+**Options:**
+```json
+{
+  "use_doc_orientation_classify": false,
+  "use_doc_unwarping": false,
+  "use_textline_orientation": false
+}
+```
+
+**Suitable scenarios:**
+- Input is known high-quality images (scanned documents, screenshots)
+- Latency is critical
+- Text is already correctly oriented
+
+## Mode: quality
+
+**Single attempt**, all corrections enabled.
+
+**Options:**
+```json
+{
+  "use_doc_orientation_classify": true,
+  "use_doc_unwarping": true,
+  "use_textline_orientation": false
+}
+```
+
+**Suitable scenarios:**
+- Input quality is unknown or poor (photos, rotated PDFs)
+- Maximum accuracy is required
+- Latency is acceptable (2-3x slower than fast)
+
+## Mode: auto (default)
+
+**Adaptive strategy**: Start fast, escalate progressively if quality is insufficient.
+
+### Attempt Sequence
+
+#### Attempt 1: Fast Path
+```json
+{
+  "use_doc_orientation_classify": false,
+  "use_doc_unwarping": false,
+  "use_textline_orientation": false
+}
+```
+
+**If `quality_score >= quality_target`**: Stop and return result.
+
+**Otherwise**: Continue to Attempt 2.
+
+---
+
+#### Attempt 2: Orientation Correction
+```json
+{
+  "use_doc_orientation_classify": true,
+  "use_doc_unwarping": false,
+  "use_textline_orientation": false
+}
+```
+
+Enable page-level orientation detection (0°/90°/180°/270°).
+
+**If `quality_score >= quality_target`**: Stop and return result.
+
+**Otherwise**: Continue to Attempt 3.
+
+---
+
+#### Attempt 3: Unwarping Correction
+```json
+{
+  "use_doc_orientation_classify": true,
+  "use_doc_unwarping": true,
+  "use_textline_orientation": false
+}
+```
+
+Add perspective correction and skew correction.
+
+**If `quality_score >= quality_target`**: Stop and return result.
+
+**Otherwise**: Select the best attempt so far.
+
+---
+
+#### Optional Attempt 4: Textline Orientation
+
+*(Reserved for future use)*
+
+```json
+{
+  "use_doc_orientation_classify": true,
+  "use_doc_unwarping": true,
+  "use_textline_orientation": true
+}
+```
+
+Add line-by-line angle correction (rarely needed).
+
+### Stop Conditions
+
+Auto mode stops when **any** of the following conditions are met:
+
+1. **Quality target reached**: `quality_score >= quality_target` (default 0.72)
+2. **Max attempts reached**: `attempt_count >= max_attempts` (default 3)
+3. **Budget exceeded**: `total_elapsed_ms >= budget_ms` (default 25000)
+
+### Selection Strategy
+
+If multiple attempts are completed, **select the attempt with the highest `quality_score`**.
+
+## Quality Scoring
+
+Quality score balances text quantity and recognition confidence.
+
+### Formula
+
+```
+quality_score = 0                                        if text_items == 0
+              = 0.6 * norm(text_items) + 0.4 * avg_rec_score  otherwise
+
+norm(n) = min(1, log(1+n) / log(1+50))
+```
+
+Where:
+- `text_items`: Number of recognized text blocks
+- `avg_rec_score`: Average of all recognition confidence scores (0.0-1.0)
+- If `rec_scores` is missing, default to `0.5`
+
+### Interpretation
+
+| Quality Score | Interpretation |
+|---------------|----------------|
+| 0.90 - 1.00 | Excellent (high confidence, many items) |
+| 0.72 - 0.89 | Good (default target) |
+| 0.50 - 0.71 | Fair (may need retry) |
+| 0.00 - 0.49 | Poor (may be low-quality input or blank) |
+
+### Default Target
+
+`quality_target = 0.72`
+
+This balances cost (API calls) and quality. Adjust with `--quality-target` if needed.
+
+## Budget Management
+
+Auto mode respects a **total time budget** (default 25000ms).
+
+- Before each attempt, check: `elapsed_ms < budget_ms`
+- If budget exceeded, stop and return best attempt so far
+- Provider timeout is independent (`PADDLE_OCR_TIMEOUT_MS`, default 25000ms)
+
+**Example:**
+- Attempt 1: 1200ms, quality 0.61 → Continue
+- Attempt 2: 1800ms, quality 0.79 → Stop (target reached)
+- Total: 3000ms
+
+## Error Handling
+
+### Provider Errors
+
+If an attempt fails with a provider error (authentication, quota, etc.):
+- **Stop immediately** (do not retry with different options)
+- Return error response with failed attempt shown in trace
+
+### Temporary Errors (503/504)
+
+- Retry **within the same attempt** (up to 2 retries with backoff)
+- If all retries fail, treat as error and stop
+
+## Examples
+
+### Example 1: Fast Path Success
+
+**Input:** High-quality scanned invoice
+
+**Execution:**
+1. Attempt 1 (fast): quality_score = 0.85 → **Stop**
+
+**Result:** Select Attempt 1, total time 1.2s
+
+---
+
+### Example 2: Retry with Improvement
+
+**Input:** Photo of rotated document
+
+**Execution:**
+1. Attempt 1 (fast): quality_score = 0.48 → Continue
+2. Attempt 2 (orientation): quality_score = 0.81 → **Stop**
+
+**Result:** Select Attempt 2, total time 3.1s
+
+---
+
+### Example 3: All Attempts Needed
+
+**Input:** Photo of warped document
+
+**Execution:**
+1. Attempt 1 (fast): quality_score = 0.35 → Continue
+2. Attempt 2 (orientation): quality_score = 0.58 → Continue
+3. Attempt 3 (unwarping): quality_score = 0.76 → **Stop**
+
+**Result:** Select Attempt 3, total time 5.2s
+
+---
+
+### Example 4: No Improvement
+
+**Input:** Blank or corrupted image
+
+**Execution:**
+1. Attempt 1 (fast): quality_score = 0.0, text_items = 0 → Continue
+2. Attempt 2 (orientation): quality_score = 0.0, text_items = 0 → Continue
+3. Attempt 3 (unwarping): quality_score = 0.0, text_items = 0 → **Stop**
+
+**Result:** Select Attempt 1 (all are 0.0), return with warning
+
+## Tuning Parameters
+
+Users can override defaults via CLI:
+
+```bash
+--mode auto \
+--max-attempts 2 \             # Reduce to 2 for faster execution (but less robustness)
+--budget-ms 15000 \            # Stricter budget
+--quality-target 0.80          # Higher quality standard
+```
+
+## Testing Auto Mode
+
+For unit tests, simulate provider responses with different `rec_texts` and `rec_scores` to verify:
+
+1. Quality score calculation
+2. Attempt selection (highest score wins)
+3. Early stopping (when target is reached)
+4. Budget enforcement
+
+See `scripts/tests/test_agent_policy.py`.

package/templates/ppocrv5/references/ppocrv5/normalized_schema.md

@@ -0,0 +1,257 @@
+# Normalized Output Schema
+
+This document defines the unified output format returned by `ocr_caller.py`, and the format that downstream agents/tools should expect.
+
+## Schema Version
+
+**v0.1** (stable)
+
+## Output Structure
+
+All responses follow this top-level structure:
+
+```typescript
+{
+  ok: boolean,              // true indicates OCR success
+  request_id: string,       // Unique request ID (e.g.: "req_abc123")
+  provider: ProviderInfo,   // Provider API metadata
+  result: Result | null,    // OCR results (null on error)
+  quality: Quality | null,  // Quality metrics (null on error)
+  agent_trace: AgentTrace,  // Execution trace for transparency
+  raw_provider: any | null, // Raw provider response (if --return-raw-provider is used)
+  error: Error | null       // Error details (null on success)
+}
+```
+
+## ProviderInfo
+
+```typescript
+{
+  api_url: string,          // Full API endpoint used
+  status_code: number,      // HTTP status code
+  log_id: string | null     // Provider's log ID (if available)
+}
+```
+
+## Result (success only)
+
+```typescript
+{
+  pages: Page[],            // Array of pages (one per image/PDF page)
+  full_text: string         // All text joined by "\n\n"
+}
+```
+
+### Page
+
+```typescript
+{
+  page_index: number,       // 0-based page number
+  text: string,             // Page text (items joined by "\n")
+  avg_confidence: number,   // Average confidence for this page (0.0-1.0)
+  items: TextItem[]         // Individual text blocks/lines
+}
+```
+
+### TextItem
+
+```typescript
+{
+  text: string,             // Recognized text
+  score?: number,           // Confidence score (0.0-1.0), may be missing
+  box?: number[] | number[][]  // Bounding box or polygon, may be missing
+}
+```
+
+**Box format:**
+- `[xmin, ymin, xmax, ymax]` - Bounding box (4 numbers)
+- Or polygon points (array of arrays)
+
+## Quality (success only)
+
+```typescript
+{
+  quality_score: number,    // Overall quality (0.0-1.0)
+  avg_rec_score: number,    // Average recognition confidence (0.0-1.0)
+  text_items: number,       // Total text items detected
+  warnings: string[]        // Warnings (e.g.: "rec_scores missing")
+}
+```
+
+### Quality Score Formula
+
+```
+quality_score = 0  if text_items == 0
+              = 0.6 * norm(text_items) + 0.4 * avg_rec_score  otherwise
+
+norm(n) = min(1, log(1+n) / log(1+50))
+```
+
+## AgentTrace
+
+```typescript
+{
+  mode: "fast" | "quality" | "auto",  // Execution mode
+  selected_attempt: number,           // Attempt used (1-indexed)
+  attempts: Attempt[]                 // Details of all attempts
+}
+```
+
+### Attempt
+
+```typescript
+{
+  attempt: number,                    // Attempt number (1-indexed)
+  provider_time_ms: number,           // Provider call latency
+  quality_score: number,              // Quality score for this attempt
+  avg_rec_score: number,              // Average recognition score
+  text_items: number,                 // Number of text items
+  warnings: string[],                 // Warnings for this attempt
+  options_effective: {                // OCR options used
+    use_doc_orientation_classify: boolean,
+    use_doc_unwarping: boolean,
+    use_textline_orientation: boolean
+  }
+}
+```
+
+## Error (error only)
+
+```typescript
+{
+  code: ErrorCode,          // Unified error code
+  message: string,          // Human-readable error message
+  details: object           // Additional error context
+}
+```
+
+### ErrorCode Enum
+
+- `PROVIDER_AUTH_ERROR` - Authentication failed (403)
+- `PROVIDER_QUOTA_EXCEEDED` - Quota/rate limit exceeded (429)
+- `PROVIDER_BAD_REQUEST` - Invalid parameters (500)
+- `PROVIDER_OVERLOADED` - Service overloaded (503)
+- `PROVIDER_TIMEOUT` - Gateway timeout (504)
+- `PROVIDER_ERROR` - Other provider errors
+
+## Example: Success Response
+
+```json
+{
+  "ok": true,
+  "request_id": "req_abc123",
+  "provider": {
+    "api_url": "https://example.aistudio-app.com/ocr",
+    "status_code": 200,
+    "log_id": "log_xyz"
+  },
+  "result": {
+    "pages": [
+      {
+        "page_index": 0,
+        "text": "Invoice\nAmount: $123.45",
+        "avg_confidence": 0.95,
+        "items": [
+          {"text": "Invoice", "score": 0.98, "box": [10, 20, 100, 50]},
+          {"text": "Amount: $123.45", "score": 0.92, "box": [10, 60, 200, 90]}
+        ]
+      }
+    ],
+    "full_text": "Invoice\nAmount: $123.45"
+  },
+  "quality": {
+    "quality_score": 0.79,
+    "avg_rec_score": 0.95,
+    "text_items": 2,
+    "warnings": []
+  },
+  "agent_trace": {
+    "mode": "auto",
+    "selected_attempt": 1,
+    "attempts": [
+      {
+        "attempt": 1,
+        "provider_time_ms": 1200,
+        "quality_score": 0.79,
+        "avg_rec_score": 0.95,
+        "text_items": 2,
+        "warnings": [],
+        "options_effective": {
+          "use_doc_orientation_classify": false,
+          "use_doc_unwarping": false,
+          "use_textline_orientation": false
+        }
+      }
+    ]
+  },
+  "raw_provider": null,
+  "error": null
+}
+```
+
+## Example: Error Response
+
+```json
+{
+  "ok": false,
+  "request_id": "req_def456",
+  "provider": {
+    "api_url": "https://example.aistudio-app.com/ocr",
+    "status_code": 403,
+    "log_id": null
+  },
+  "result": null,
+  "quality": null,
+  "agent_trace": {
+    "mode": "auto",
+    "selected_attempt": 1,
+    "attempts": [
+      {
+        "attempt": 1,
+        "provider_time_ms": 150,
+        "quality_score": 0.0,
+        "avg_rec_score": 0.0,
+        "text_items": 0,
+        "warnings": ["Provider error: Authentication failed"],
+        "options_effective": {
+          "use_doc_orientation_classify": false,
+          "use_doc_unwarping": false,
+          "use_textline_orientation": false
+        }
+      }
+    ]
+  },
+  "raw_provider": null,
+  "error": {
+    "code": "PROVIDER_AUTH_ERROR",
+    "message": "Authentication failed",
+    "details": {
+      "error_code": 403,
+      "status_code": 403
+    }
+  }
+}
+```
+
+## Usage Guide
+
+### For Agents/Scripts
+
+1. **Check `ok` first**: `if response.ok:`
+2. **Extract text**: `response.result.full_text`
+3. **Extract structured data**: `response.result.pages[].items[]`
+4. **Check quality**: `response.quality.quality_score` (0.72+ is usually good)
+5. **Handle errors**: `response.error.code` and `response.error.message`
+
+### For Debugging
+
+1. **Check trace**: `response.agent_trace.attempts` shows all attempts and their quality
+2. **Selected attempt**: `response.agent_trace.selected_attempt` indicates which one was selected
+3. **Raw provider**: Use `--return-raw-provider` to see raw API response
+
+## Compatibility Notes
+
+- **Missing scores**: `items[].score` may not exist if provider didn't return scores
+- **Missing boxes**: `items[].box` may not exist if provider didn't return geometry
+- **Empty results**: `text_items == 0` means no text detected (not necessarily an error)
+- **Warnings**: Check `quality.warnings` for non-fatal issues (e.g.: missing fields)

package/templates/ppocrv5/references/ppocrv5/provider_api.md

@@ -0,0 +1,140 @@
+# Provider API Reference: Paddle AI Studio PP-OCRv5
+
+This document describes the external provider API contract that this skill depends on.
+
+## Endpoint
+
+**POST** `https://<AISTUDIO_HOST>/ocr`
+
+Where `<AISTUDIO_HOST>` is provided by the user (e.g.: `your-subdomain.aistudio-app.com`).
+
+## Authentication
+
+**Header:**
+```
+Authorization: token <ACCESS_TOKEN>
+```
+
+Where `<ACCESS_TOKEN>` is the API token obtained by the user from Paddle AI Studio.
+
+## Request Body
+
+```jsonc
+{
+  "file": "https://example.com/image.png",  // URL or base64 (without data: prefix)
+  "fileType": 1,                            // 0=PDF, 1=Image
+  "visualize": false,                       // Default false (avoid large responses)
+
+  // Text detection options
+  "textDetLimitSideLen": 736,               // Maximum side length for detection
+  "textDetLimitType": "max",                // "min" or "max"
+  "textDetThresh": 0.3,                     // Detection threshold
+  "textDetBoxThresh": 0.6,                  // Box threshold
+  "textDetUnclipRatio": 1.5,                // Unclip ratio
+
+  // Text recognition options
+  "textRecScoreThresh": 0.0,                // Recognition score threshold
+
+  // Document preprocessing options
+  "useDocOrientationClassify": false,       // Enable orientation correction
+  "useDocUnwarping": false,                 // Enable unwarping/skew correction
+  "useTextlineOrientation": false           // Enable textline orientation
+}
+```
+
+### Key Parameters
+
+- **file**: URL or base64 string of image/PDF (without `data:` URI prefix)
+- **fileType**:
+  - `0` = PDF
+  - `1` = Image
+- **visualize**: If `true`, returns visualization image (increases response size)
+- **useDocOrientationClassify**: Correct page orientation (0°/90°/180°/270°)
+- **useDocUnwarping**: Correct perspective distortion and skew
+- **useTextlineOrientation**: Correct individual text line angles
+
+## Response Structure
+
+### Success Response (errorCode == 0)
+
+```jsonc
+{
+  "errorCode": 0,
+  "errorMsg": "",
+  "logId": "unique-log-id",
+  "result": {
+    "ocrResults": [
+      {
+        "prunedResult": {
+          "rec_texts": ["Invoice", "Amount", "123.45"],  // Recognized text
+          "rec_scores": [0.98, 0.95, 0.92],              // Confidence scores (may be missing)
+          "rec_boxes": [                                  // Bounding boxes (may be missing)
+            [10, 20, 100, 50],
+            [10, 60, 150, 90],
+            [200, 60, 300, 90]
+          ],
+          "rec_polys": [...]                              // Polygons (alternative to boxes)
+        }
+      }
+    ]
+  }
+}
+```
+
+### Error Response (errorCode != 0)
+
+```jsonc
+{
+  "errorCode": 500,
+  "errorMsg": "Invalid parameter",
+  "logId": "unique-log-id"
+}
+```
+
+## Error Codes
+
+| HTTP Status | errorCode | Meaning | Mapped Error Code |
+|-------------|-----------|---------|-------------------|
+| 403 | N/A | Authentication failed | `PROVIDER_AUTH_ERROR` |
+| 429 | N/A | Quota/rate limit exceeded | `PROVIDER_QUOTA_EXCEEDED` |
+| 500 | 500 | Invalid parameters | `PROVIDER_BAD_REQUEST` |
+| 503 | N/A | Service overloaded | `PROVIDER_OVERLOADED` |
+| 504 | N/A | Gateway timeout | `PROVIDER_TIMEOUT` |
+| Other | Other | Unknown error | `PROVIDER_ERROR` |
+
+## Field Compatibility Notes
+
+- **rec_scores**: May be missing or empty. Default to 0.5 if needed.
+- **rec_boxes**: May be missing. Use `rec_polys` as fallback.
+- **rec_polys**: May be missing. Bounding box information may not be available.
+- **visualize result**: Only returned when `visualize: true` (not recommended for auto mode).
+
+## Best Practices
+
+1. **Always set visualize to false** unless explicitly requested by user (reduces response size and latency)
+2. **Handle missing fields gracefully** (rec_scores, rec_boxes, rec_polys may not exist)
+3. **Retry on 503/504** with exponential backoff (up to 2 retries)
+4. **Never log or print tokens** in any output or logs
+5. **Normalize host input** to handle user errors (https://, trailing /ocr, etc.)
+
+## Request Example
+
+```bash
+curl -X POST https://your-subdomain.aistudio-app.com/ocr \
+  -H "Authorization: token YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file": "https://example.com/test.png",
+    "fileType": 1,
+    "visualize": false,
+    "useDocOrientationClassify": true,
+    "useDocUnwarping": false,
+    "useTextlineOrientation": false,
+    "textDetLimitSideLen": 736,
+    "textDetLimitType": "max",
+    "textDetThresh": 0.3,
+    "textDetBoxThresh": 0.6,
+    "textDetUnclipRatio": 1.5,
+    "textRecScoreThresh": 0.0
+  }'
+```