laiye-doc-processing

# Laiye Agentic Document Processing (ADP)

Agentic Document Processing API — convert 10+ file formats（.jpeg,.jpg,.png,.bmp,.tiff,.pdf,.doc,.docx,.xls,.xlsx） to structured JSON/Excel with per-field confidence scores using VLM and LLM.

> **Base URL:** `https://adp-global.laiye.com/?utm_source=github`

## Quick Start

```bash
curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: $ADP_ACCESS_KEY" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: $(uuidgen)" \
  -d '{
    "app_key": "$ADP_APP_KEY",
    "app_secret": "$ADP_APP_SECRET",
    "file_url": "https://example.com/invoice.pdf"
  }'
```

Response:
```json
{
  "status": "success",
  "extraction_result": [
    {
      "field_key": "invoice_number",
      "field_value": "INV-2024-001",
      "field_type": "text",
      "confidence": 0.95,
      "source_pages": [1]
    },
    {
      "field_key": "total_amount",
      "field_value": "1000.00",
      "field_type": "number",
      "confidence": 0.98,
      "source_pages": [1]
    }
  ]
}
```

## Setup

### 1. Get Your API Credentials

```bash
# Contact ADP service provider to obtain:
# - app_key: Application access key
# - app_secret: Application secret key
# - X-Access-Key: Tenant-level access key
```

Save your credentials:
```bash
export ADP_ACCESS_KEY="your_access_key_here"
export ADP_APP_KEY="your_app_key_here"
export ADP_APP_SECRET="your_app_secret_here"
```

### 2. Configuration (Optional)

**Recommended: Use environment variables** (most secure):
```json5
{
  skills: {
    entries: {
      "adp-doc-extraction": {
        enabled: true,
        // API credentials loaded from environment variables
      },
    },
  },
}
```

**Security Note:**
- Set file permissions: `chmod 600 ~/.openclaw/openclaw.json`
- Never commit this file to version control
- Prefer environment variables or secret stores
- Rotate credentials regularly

## Common Tasks

### Extract from File URL

```bash
curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: $ADP_ACCESS_KEY" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: $(uuidgen)" \
  -d '{
    "app_key": "'"$ADP_APP_KEY"'",
    "app_secret": "'"$ADP_APP_SECRET"'",
    "file_url": "https://example.com/document.pdf"
  }'
```

### Extract from Base64

```bash
# Convert file to base64
file_base64=$(base64 -i document.pdf | tr -d '\n')

curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: $ADP_ACCESS_KEY" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: $(uuidgen)" \
  -d "{
    \"app_key\": \"$ADP_APP_KEY\",
    \"app_secret\": \"$ADP_APP_SECRET\",
    \"file_base64\": \"$file_base64\",
    \"file_name\": \"document.pdf\"
  }"
```

### Extract with VLM Results

```bash
curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: $ADP_ACCESS_KEY" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: $(uuidgen)" \
  -d '{
    "app_key": "'"$ADP_APP_KEY"'",
    "app_secret": "'"$ADP_APP_SECRET"'",
    "file_url": "https://example.com/document.pdf",
    "with_rec_result": true
  }'
```

Access VLM results: `response["doc_recognize_result"]`

### Async Extraction (Large Documents)

**Create extraction task:**
```bash
curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract/create/task" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: $ADP_ACCESS_KEY" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: $(uuidgen)" \
  -d '{
    "app_key": "'"$ADP_APP_KEY"'",
    "app_secret": "'"$ADP_APP_SECRET"'",
    "file_url": "https://example.com/large-document.pdf"
  }'

# Returns: {"task_id": "task_id_value", "metadata": {...}}
```

**Poll for results:**
```bash
curl -X GET "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract/query/task/{task_id}" \
  -H "X-Access-Key: $ADP_ACCESS_KEY"
```

## Advanced Features

### Custom Scale Parameter

Enhance VLM quality with higher resolution:
```bash
# model_params: { "scale": 2.0 }
```

### Specify Config Version

Use a specific extraction configuration:
```bash
# model_params: { "version_id": "config_version_id" }
```

### Document Recognition Only

Get VLM results without extraction:
```bash
curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/recognize" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: $ADP_ACCESS_KEY" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: $(uuidgen)" \
  -d '{
    "app_key": "'"$ADP_APP_KEY"'",
    "app_secret": "'"$ADP_APP_SECRET"'",
    "file_url": "https://example.com/document.pdf"
  }'
```

## When to Use

### Use ADP For:
- Invoice processing
- Order processing
- Receipt processing
- Financial document processing
- Logistics document processing
- Multi-table document data extraction

### Don't Use For:
- Video transcription
- audio transcription

## Best Practices

| Document Size | Endpoint | Notes |
|---------------|----------|-------|
| Small files | `/doc/extract` (sync) | Immediate response |
| Large files | `/doc/extract/create/task` (async) | Poll for results |

**File Input:**
- `file_url`: Prefer for large files (already hosted)
- `file_base64`: Use for direct upload (max 20MB)

**Confidence Scores:**
- Range: 0-1 per field
- Review fields with confidence <0.8 manually

**Response Structure:**
- `extraction_result`: Array of extracted fields
- `doc_recognize_result`: VLM results (when `with_rec_result=true`)
- `metadata`: Processing info (pages, time, model)

## Response Schema

### Success Response
```json
{
  "status": "success",
  "message": "string",
  "extraction_result": [
    {
      "field_key": "string",
      "field_value": "string",
      "field_type": "text|number|date|table",
      "confidence": 0.95,
      "source_pages": [1],
      "table_data": [...]  // for field_type="table"
    }
  ],
  "doc_recognize_result": [...],  // when with_rec_result=true
  "extract_config_version": "string",
  "metadata": {
    "total_pages": 5,
    "processing_time": 8.2,
    "model_used": "gpt-4o"
  }
}
```

### Error Response
```json
{
  "detail": "Error message description"
}
```

## Common Use Cases

### Invoice/Receipt Extraction
Extracts: invoice_number, invoice_date, vendor/customer_name, currency, vat_rate, total_amount_including_tax, total_amount_excluding_tax, line_items, etc.

### Purchase Order Extraction
Extracts: order_number, order_date, buyer_name/seller_name, address, total_amount, line_items, etc.

## Security & Privacy

### Data Handling

**Important:** Documents uploaded to ADP are transmitted to `https://adp-global.laiye.com/?utm_source=github` and processed on external servers.

**Before uploading sensitive documents:**
- Review ADP privacy policy and data retention policies
- Verify encryption in transit (HTTPS) and at rest
- Confirm data deletion/retention timelines
- Test with non-sensitive sample documents first

**Best practices:**
- Do not upload highly sensitive PII until you've confirmed security posture
- Use credentials with limited permissions if available
- Rotate credentials regularly (every 90 days recommended)
- Monitor API usage logs for unauthorized access
- Never log or commit credentials to repositories

### File Size Limits

- **Max file size:** 50MB
- **Supported formats:** .jpeg, .jpg, .png, .bmp, .tiff, .pdf, .doc, .docx, .xls, .xlsx
- **Concurrency limit:** Free users support 1 concurrent request, paid users support 2 concurrent requests
- **Timeout:** 10 minutes for sync requests

### Operational Safeguards

- Always use environment variables or secure secret stores for credentials
- Never include real credentials in code examples or documentation
- Use placeholder values like `"your_access_key_here"` in examples
- Set appropriate file permissions on configuration files (600)
- Enable credential rotation and monitor usage

## Billing

| Processing Stage | Cost |
|-----------------|------|
| Document Parsing | 0.5 credits/page |
| Purchase Order Extraction | 1.5 credits/page |
| Invoice/Receipt Extraction | 1.5 credits/page |
| Custom Extraction | 1 credit/page |

**New users:** 100 free credits per month, no application restrictions.

## Troubleshooting

| Error Code | Description | Common Causes & Solutions |
|------------|-------------|---------------------------|
| **400 Bad Request** | Invalid request parameters | • Missing `app_key` or `app_secret`<br>• Must provide exactly one input: `file_url` or `file_base64`<br>• Application has no published extraction config |
| **401 Unauthorized** | Authentication failed | • Invalid `X-Access-Key`<br>• Incorrect timestamp format (use Unix timestamp)<br>• Invalid signature format (must be UUID) |
| **404 Not Found** | Resource not found | • Application does not exist<br>• No published extraction config found for the application |
| **500 Internal Server Error** | Server-side processing error | • Document conversion failed<br>• VLM recognition timeout<br>• LLM extraction failure |
| **Sync Timeout** | Request processing timed out | • Large files should use async endpoint<br>• Poll `/query/task/{task_id}` for results |

## Pre-Publish Security Checklist

Before publishing or updating this skill, verify:

- [ ] `package.json` declares `requiredEnv` and `primaryEnv` for credentials
- [ ] `package.json` lists API endpoints in `endpoints` array
- [ ] All code examples use placeholder values not real credentials
- [ ] No credentials or secrets are embedded in `SKILL.md` or `package.json`
- [ ] Security & Privacy section documents data handling and risks
- [ ] Configuration examples include security warnings for plaintext storage
- [ ] File permission guidance is included for config files

## References

- **API Base URL:** https://adp-global.laiye.com/
- **Flow Documentation:** [ADP Flow Index](../../refers/backend/flows/ADP-Flow-Index.md)
- **Extraction Flow:** [Document Extraction Flow](../../refers/backend/flows/09-Doc-Extraction-Flow.md)
- **Recognition Flow:** [Document Recognition Flow](../../refers/backend/flows/08-Doc-Recognition-Flow.md)