feat: async OCR workflow - split submit + poll tools to avoid timeout issues

- Add submit_pdf_for_ocr() - submits immediately, returns task_id
- Add get_ocr_result() - polls for completion, saves Markdown
- Keep batch_ocr_pdf() as deprecated fallback
- Update README with new async usage pattern
- Update pyproject.toml description

README.md

@@ -4,37 +4,53 @@ Python MCP Server for PDF OCR batch processing.
 
 ## Features
 
-- **Batch OCR** - Process multiple PDF files and save results as Markdown
-- **Single File OCR** - Process a single PDF file directly
+- **Non-blocking OCR** - Submit PDF tasks and poll for results later (no blocking)
+- **Batch Processing** - Process multiple PDF files in one call
+- **Async Workflow** - Decoupled submission and result retrieval to avoid timeouts
 
-## Tool
+## Tools
 
-### `batch_ocr_pdf`
+### ⚠️ NEW: Async Workflow (Recommended)
 
-OCR process PDF file(s) using the OCR API. Supports both single file and directory modes.
+#### `submit_pdf_for_ocr`
+Submits PDF file(s) for OCR processing. Returns `task_id` immediately.
+**Does NOT wait for completion.**
 
 **Parameters:**
-- `input_file`: Path to a single PDF file to process (mutually exclusive with `input_dir`)
-- `input_dir`: Directory containing PDF files to process (mutually exclusive with `input_file`)
-- `output_dir`: Directory to save Markdown results (auto-created if not provided)
+- `input_file`: Path to a single PDF file
+- `input_dir`: Directory containing PDF files
+- `output_dir`: Output directory (auto-created)
 - `api_key`: OCR API key (optional, reads from `OCR_API_KEY` env var)
 - `base_url`: OCR API base URL (default: `https://agent.imqimacau.com`)
 
-**Usage Modes:**
+#### `get_ocr_result`
+Polls for OCR result by `task_id`. Saves result as Markdown when completed.
 
-1. **Single File Mode**: Provide `input_file` only
-   ```
-   input_file: /path/to/document.pdf
-   ```
+**Parameters:**
+- `task_id`: Task ID from `submit_pdf_for_ocr`
+- `wait_until_completed`: Keep polling until done (default: `True`)
+- `poll_interval`: Seconds between polls (default: 3)
+- `max_polls`: Maximum polls (default: 120 → max 360s wait)
 
-2. **Batch Mode**: Provide `input_dir` only
-   ```
-   input_dir: /path/to/pdf_directory
-   ```
+**⏱️ TIMEOUT RULE:** 50s (page 1) + 30s × (pages - 1).
+For an N-page PDF, set `max_polls` such that `max_polls * poll_interval ≥ 50 + 30*(N-1)`.
+Example: 10-page PDF → 320s needed → `max_polls=120, poll_interval=3` (360s) works.
 
-**Note:** `input_file` and `input_dir` are mutually exclusive. At least one must be provided.
+**Usage Example:**
+```
+1. submit_pdf_for_ocr(input_file="/path/to/doc.pdf")
+   → Returns: {"task_id": "abc123", ...}
 
-**Returns:** JSON with processing results (success/fail counts per file)
+2. get_ocr_result(task_id="abc123", wait_until_completed=True)
+   → Returns: {"status": "completed", "output_file": "/path/to/doc.md", ...}
+
+3. Check the Markdown file at output_file
+```
+
+### 🗑️ DEPRECATED: `batch_ocr_pdf`
+
+Original synchronous tool. **Kept for backward compatibility but NOT recommended.**
+Blocks and may time out with Hermes (default 120s). Use the async tools above instead.
 
 ---
 
@@ -63,7 +79,7 @@ Set your OCR API key as an environment variable:
 
 ```bash
 # Add to shell profile
-echo 'export OCR_API_KEY="your-api-key-here"' >> ~/.bashrc
+echo 'export OCR_API_KEY="***"' >> ~/.bashrc
 source ~/.bashrc
 ```
 
@@ -85,15 +101,20 @@ mcp_servers:
 
 ### Step 4: Restart Hermes
 
-Restart your Hermes agent to load the new MCP server. The tool `mcp_procleaning_batch_ocr_pdf` will be available in conversations.
+Restart your Hermes agent to load the new MCP server. Two new tools will be available:
+- `mcp_procleaning_submit_pdf_for_ocr`
+- `mcp_procleaning_get_ocr_result`
 
 ### Step 5: Test
 
 Run a test in Hermes:
 
 ```
-input_file: /path/to/test.pdf
-output_dir: /path/to/output
+1. submit_pdf_for_ocr(input_file="/path/to/test.pdf")
+   → Note the task_id
+
+2. get_ocr_result(task_id="...")
+   → Check the output Markdown file
 ```
 
 ---