ppocrv5

What this skill does

# PP-OCRv5 API Skill

## When to Use This Skill

Invoke this skill in the following situations:
- Extract text from images (screenshots, photos, scans, charts)
- Read text from PDF or document images
- Perform OCR on any visual content containing text
- Parse structured documents (invoices, receipts, forms, tables)
- Recognize text in photos taken by mobile phones
- Extract text from URLs pointing to images or PDFs

Do not use this skill in the following situations:
- Plain text files that can be read directly with the Read tool
- Code files or markdown documents
- Tasks that do not involve image-to-text conversion

## How to Use This Skill

### Basic Workflow

1. **Identify the input source**:
   - User provides URL: Use the `--file-url` parameter
   - User provides local file path: Use the `--file-path` parameter
   - User uploads image: Save it first, then use `--file-path`

2. **Execute OCR**:
   ```bash
   python scripts/ocr_caller.py --file-url "URL provided by user" --pretty
   ```
   Or for local files:
   ```bash
   python scripts/ocr_caller.py --file-path "file path" --pretty
   ```

3. **Parse JSON response**:
   - Check the `ok` field: `true` means success, `false` means error
   - Extract text: `result.full_text` contains all recognized text
   - Get quality: `quality.quality_score` indicates recognition confidence (0.0-1.0)
   - Handle errors: If `ok` is false, display `error.message`

4. **Present results to user**:
   - Display extracted text in a readable format
   - If quality score is low (<0.5), alert the user
   - If structured output is needed, use `result.pages[].items[]` to get line-by-line data

### Mode Selection

Always use `--mode auto` (default) unless the user explicitly requests otherwise:

| User Request | Use Mode | Command Flag |
|--------------|----------|--------------|
| Default/unspecified | Auto (adaptive) | `--mode auto` (or omit) |
| "Quick recognition" / "fast" | Fast | `--mode fast` |
| "High precision" / "accurate" | Quality | `--mode quality` |

**Auto mode** (recommended): Automatically tries 1-3 times, progressively increasing correction levels, returning the best result.

### Usage Mode Examples

**Mode 1: Simple URL OCR**
```bash
python scripts/ocr_caller.py --file-url "https://example.com/invoice.jpg" --pretty
```

**Mode 2: Local File OCR**
```bash
python scripts/ocr_caller.py --file-path "./document.pdf" --pretty
```

**Mode 3: Fast Mode for Clear Images**
```bash
python scripts/ocr_caller.py --file-url "URL" --mode fast --pretty
```

### Understanding the Output

The script outputs JSON structure as follows:
```json
{
  "ok": true,
  "result": {
    "full_text": "All recognized text here...",
    "pages": [...]
  },
  "quality": {
    "quality_score": 0.85,
    "text_items": 42
  }
}
```

**Key fields to extract**:
- `result.full_text`: Complete text for the user
- `quality.quality_score`: 0.72+ is good, <0.5 is poor
- `error.message`: If `ok` is false, provides error description

### First-Time Configuration

If the user has not configured API credentials, run:
```bash
python scripts/configure.py
```

This will prompt for:
- `API_URL`: Paddle AI Studio endpoint
- `PADDLE_OCR_TOKEN`: User's access token

Configuration is saved to the `.env` file, only needs to be configured once.

### Error Handling

**Configuration missing**:
```
Error: API_URL not configured
```
→ Run `python scripts/configure.py`

**Authentication failed (403)**:
```
error_code: PROVIDER_AUTH_ERROR
```
→ Token is invalid, reconfigure with correct credentials

**Quota exceeded (429)**:
```
error_code: PROVIDER_QUOTA_EXCEEDED
```
→ Daily API quota exhausted, inform user to wait or upgrade

**No text detected**:
```
quality_score: 0.0, text_items: 0
```
→ Image may be blank, corrupted, or contain no text

## Quality Interpretation

When presenting results to users, consider the quality score:

| Quality Score | Explanation to User |
|---------------|---------------------|
| 0.90 - 1.00 | Excellent recognition quality |
| 0.72 - 0.89 | Good recognition quality (default target) |
| 0.50 - 0.71 | Fair recognition quality, may have some errors |
| 0.00 - 0.49 | Poor recognition quality or no text detected |

If quality is below 0.5, mention to the user and suggest:
- Try using `--mode quality` for better accuracy
- Check if the image is clear and contains text
- Provide a higher resolution image if possible

## Advanced Options

Use only when explicitly requested by the user:

**Include raw provider response** (for debugging):
```bash
python scripts/ocr_caller.py --file-url "URL" --return-raw-provider
```

**Request visualization** (show detection regions):
```bash
python scripts/ocr_caller.py --file-url "URL" --visualize
```

**Adjust auto mode parameters**:
```bash
python scripts/ocr_caller.py --file-url "URL" \
  --max-attempts 2 \
  --quality-target 0.80 \
  --budget-ms 20000
```

## Reference Documentation

For in-depth understanding of the OCR system, refer to:
- `references/agent_policy.md` - Auto mode strategy and quality scoring
- `references/normalized_schema.md` - Complete output schema specification
- `references/provider_api.md` - Provider API contract details

Load these reference documents into context when:
- Debugging complex issues
- User asks about quality scoring algorithm
- Need to understand adaptive retry mechanism
- Customizing auto mode parameters

## Testing the Skill

To verify the skill is working properly:
```bash
python scripts/smoke_test.py
```

This tests configuration and API connectivity.