CareMax Upload & OCR

Requires caremax-auth as a sibling directory (../caremax-auth/). If missing, tell the user to install caremax-auth first (e.g. npx skills add KittenYang/caremax-skills).

Upload medical report files (PDF, JPG, PNG, HEIC) and extract structured data via AI-powered OCR.

Session-based workflow: upload → OCR → review → confirm. All operations are on a single session.

Checkpoint & resume: Every pipeline step saves progress to the database. If OCR fails mid-way (LLM timeout, worker crash, network error), retrying automatically resumes from the last checkpoint — no work is lost.

Agent default behavior (MANDATORY)

1. 1. Upload and OCR are one continuous workflow. When the user uploads report files (or asks you to upload/扫描/识别体检报告等), after $UPLOAD returns successfully you must in the same turn run $OCRSTREAM <session_id> using the returned session_id. Do not end the task after upload.sh alone.
2. Upload-only exception: Skip immediate OCR only if the user explicitly asked to upload without recognition (e.g. 只上传、不要识别、别跑 OCR、只存文件). If unclear, default to running OCR after upload.
3. Progress: Stream each SSE line to the user as it arrives (normalize / ocr / structure / …).
4. After step=done: Always continue to Step 3 (review). Do not auto-call confirm — wait for user approval before Step 4.

Prerequisites — Auto-Auth (MANDATORY)

CODEBLOCK0

If any script returns no_credentials → run bash ../caremax-auth/scripts/auth-flow.sh [base_url] (from this skill’s root, sibling of caremax-auth/).

Step 1: Upload (creates session)

CODEBLOCK1

Returns:
CODEBLOCK2

Save the session_id.

Step 2: OCR with real-time progress

CODEBLOCK3

Outputs one JSON per line:
CODEBLOCK4

Display progress to the user as each line arrives.

Key progress events

step	meaning
INLINECODE12	Pipeline is resuming from a saved checkpoint (not starting from zero)
INLINECODE13

Informational message (e.g. which step was resumed from) | | normalize | Loading and preprocessing files | | ocr | OCR text extraction per page | | ocr_retry | Retrying previously failed pages only | | structure | AI analyzing and grouping reports | | normalize_indicators | Standardizing indicator names | | done | Complete — data field contains the full results | | error | Pipeline failed — check message for details |

If step=resume appears, tell the user: "正在从上次的进度继续处理（不需要重新开始）"

Error responses from $OCRSTREAM

code	meaning	action
INLINECODE25	Another OCR run is still active	Wait and retry, or poll INLINECODE26
INLINECODE27

Free OCR quota exhausted | Tell user to upgrade | | (no code) | Pipeline error (LLM timeout etc.) | Retry — will auto-resume from checkpoint |

Step 2b: Poll status (when SSE disconnects)

If the SSE stream disconnects (network timeout, terminal closed), use the status endpoint to check progress:

CODEBLOCK5

Returns:
CODEBLOCK6

Field guide:

• - status = processing + is_stale = false → OCR is still running normally
• INLINECODE30 + is_stale = true → Worker crashed/timed out, safe to retry OCR
• INLINECODE32 → OCR completed! Fetch session detail for results
• INLINECODE33 + error present → Last OCR attempt failed, retry will resume from checkpoint
• INLINECODE35 → How far the pipeline got (normalize → ocr → structure → done)
• INLINECODE36 → Number of pages that failed OCR (will be retried on next attempt)

Polling workflow:
CODEBLOCK7

Step 3: Review results (MANDATORY)

Parse the step=done data. Show formatted summary. Do NOT auto-confirm.

Each report has a reportType field: lab, genetic, imaging, pathology, or other.

Lab reports (reportType = "lab")

Show indicators table: CODEBLOCK8

Non-lab reports (reportType = "genetic" / "imaging" / etc.)

Show summary + sections: CODEBLOCK9

Supported file types

• - Images (JPG/PNG/HEIC): PaddleOCR → structure
• PDF (any size): Azure Mistral Document AI page-split → structure

- Large PDFs (e.g. 23-page gene report, 9.6MB) are fully supported

Step 4: Confirm and save

After user confirms:

CODEBLOCK10

Returns: INLINECODE44

Resuming incomplete sessions

When the user asks to continue/resume a previous upload, or when checking for unfinished work:

Step A: Find pending sessions

CODEBLOCK11

Show a summary of pending sessions to the user (file names, dates, status).

Step B: Resume based on status

• - uploading: Start OCR directly → go to Step 2 ($OCRSTREAM <session_id>)

- If there's a saved checkpoint (previous failed attempt), OCR auto-resumes from it

• - processing: Check with status endpoint first:

  $APICALL GET "/api/skill/sessions/<session_id>/status"
  

- is_stale = false → still running, wait or poll - is_stale = true → worker died, safe to retry: $OCRSTREAM <session_id> (auto-resumes from checkpoint)

• - awaiting_confirm: Get session detail → show results → go to Step 3 (review & confirm)

CODEBLOCK13

If the session is awaiting_confirm, the response includes ocr_result with the previously parsed reports — display them for review and proceed to Step 3 (confirm).

Resume-aware response handling

When $OCRSTREAM outputs step=done:

• - resumed = true in the data → tell user: "已从上次的进度恢复，OCR 结果已就绪"
• INLINECODE57 (or absent) → normal fresh run

When $OCRSTREAM outputs step=error:

• - code = processing_in_progress → tell user OCR is still running, poll /status instead
• INLINECODE62 → tell user to upgrade
• No code → LLM/network error, safe to retry (will auto-resume from checkpoint)

Step C: Delete individual reports or stale sessions

Delete a single report (does NOT affect other reports in the same session):

CODEBLOCK14

Delete an entire session (cascade deletes ALL files + reports):

CODEBLOCK15

Other session operations

CODEBLOCK16