SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsclawshire-doc-extract-engine

clawshire-doc-extract-engine

Office & productivity

View repository

Updated 10-16 00:00

About this skill

ClawShire Universal Document Extraction Engine Skill

Upload your own PDF → describe the fields to extract in natural language → get structured JSON. Suitable for any PDF such as resumes, contracts, research reports, manuals, etc.

Service address: https://api.clawshire.cn Prerequisites: Set CLAWSHIRE_API_KEY. The script uses only the Python standard library and requires no third-party dependencies to be installed.

Agent invocation guide (important)

The user only needs to provide the PDF path + a one-sentence request, and the Agent automatically completes the entire workflow, with no need for the user to manually pass any ID.

Typical trigger phrases:

  • "Help me extract basic information, work experience, and skills from this resume PDF"
  • "Extract the parties, amount, and signing date from this contract"
  • "Parse this research report and extract the company name, rating, and target price"

Agent execution order (fully automatic, intermediate IDs require no user involvement):

1. upload PDF               → 获得 document_id
2. schema-create            → 获得 conversation_id
3. schema-chat "用户需求"   → 获得 schema（504 时自动 fallback 到 schema-get）
4. session-create           → 获得 session_id
5. extract --auto-end       → 获得结构化结果 + 自动打印摘要

Time estimate: schema-chat about 30 seconds to 3 minutes,extract about 1 to 5 minutes, please inform the user to wait.

Quick start (complete an extraction in three steps)

export CLAWSHIRE_API_KEY="sk-..."
SCRIPT="python skills/clawshire-doc-extract-engine/scripts/clawshire_doc_extract_client.py"

# 第一步：上传 PDF，记下返回的 document_id
$SCRIPT upload 合同.pdf

# 第二步：设计提取字段（一句话描述即可，遇到 504 会自动拉取服务端结果）
$SCRIPT schema-create --doc-ids <document_id>
$SCRIPT schema-chat <conversation_id> "提取甲方、乙方、合同金额、签署日期" --save-as 合同

# 第三步：创建 Session 并提取（完成后自动打印覆盖率摘要）
$SCRIPT session-create --name "合同提取" --from-lib 合同 --doc-ids <document_id>
$SCRIPT extract --session-id <session_id> --doc-ids <document_id> --out result.json --auto-end

--auto-end Automatically archive and trigger platform experience learning; after extraction is complete, always output structured data, which Claude can directly read and display to the user.

Standard workflow (complete 7-step API)

1. Upload PDF

POST /api/v1/doc-extract-engine/upload，multipart/form-data, field name files(multiple allowed).

Response:{"document_ids": [...], "count": N}

2. Start the Schema design conversation

POST .../schema-conversations，body：{"document_ids": ["id1","id2"]}

Response:{"conversation_id": <int>}

3. Describe the extraction requirements in natural language

POST .../schema-conversations/{conversation_id}/chat，body：{"message": "请提取甲方、乙方、合同金额、签署日期"}

The response is JSON after server-side aggregation of SSE, containing schema、messages、results and other fields (subject to the actual return).

If the response does not include the complete schema:GET .../schema-conversations/{conversation_id} fetch the current state.

4. Create an extraction Session

POST .../sessions，body：

{
  "session_name": "合同-项目A",
  "extraction_schema": { "type": "object", "properties": { ... } },
  "document_ids": ["id1", "id2"]
}

Response:{"session_id": <int>}

5. Execute extraction

POST .../extract，body：{"session_id": 1, "document_ids": ["id1","id2"]}

The response contains batch_id、results , etc.

6. Iterative correction (optional)

POST .../batches/{batch_id}/chat，body：{"message": "把金额统一成数字，去掉货币符号"}

Can be repeated for multiple rounds.

7. Archive

POST .../batches/{batch_id}/end

Advanced usage: save tokens & save quota

Output behavior description

extract、batch-result、batch-chat commandalwaysoutputs the structured data of the actual API response (results[].data) to stdout, so that both Claude and the user can directly see the extracted content.

Option Effect
extract --quiet Additionally print a field coverage summary (progress bar)
batch-result --summary Additionally print field coverage, used when querying an existing batch
batch-chat --quiet Additionally print a field coverage summary

Save quota: local extraction cache

The first extraction automatically writes to ~/.clawshire/cache.json(isolated across four dimensions by API Key + BaseURL + session_id + doc_ids , so switching environments will not cause contamination).

# 首次提取（写入缓存）
$SCRIPT extract --session-id 1 --doc-ids id1,id2 --out result.json --quiet

# 再次访问同一批文档，命中缓存则不消耗额度
$SCRIPT extract --session-id 1 --doc-ids id1,id2 --use-cache --quiet

Note：--use-cache When there is a cache miss, a clear prompt is printed and then the real extraction is executed; when there is a cache hit but that batch has already been archived by --auto-end , an "archive snapshot" warning is displayed.

Save schema-chat: local Schema library

Schema saved to ~/.clawshire/schemas.json, reused across API Keys, no need to repeat schema-chat.

# 查询已有 schema（支持关键字过滤）
$SCRIPT schema-lib-list
$SCRIPT schema-lib-list --search 合同

# schema-chat 时自动保存（同名已存在时跳过，不静默覆盖）
$SCRIPT schema-chat 1 "提取甲方、乙方、金额" --save-as 合同 --description "合同通用 schema"

# 手动保存（允许覆盖已有 schema，会提示原保存时间）
$SCRIPT schema-lib-save --name 合同 --file schema.json

# 跳过 schema-chat，直接从库创建 Session
$SCRIPT session-create --name "批量任务" --from-lib 合同 --doc-ids id1,id2,id3

CLI full parameter reference

# 连通性检查
$SCRIPT status

# 上传（本地路径 或 http/https URL，可混用）
$SCRIPT upload a.pdf "https://example.com/b.pdf"

# Schema 流程
$SCRIPT schema-create --doc-ids id1,id2
$SCRIPT schema-chat <conv_id> "描述需求" [--save-as 名称] [--description 描述]
$SCRIPT schema-get <conv_id>

# Session 流程
$SCRIPT session-create --name 名称 (--schema-file schema.json | --from-lib 名称) --doc-ids id1,id2
$SCRIPT sessions
$SCRIPT history <session_id>

# 提取
$SCRIPT extract --session-id <sid> --doc-ids id1,id2 \
  [--out [path.json]] [--auto-end] [--quiet] [--use-cache]

# Batch 操作
$SCRIPT batch-result <batch_id> [--out [path.json]] [--summary]
$SCRIPT batch-chat <batch_id> "修正说明" [--out [path.json]] [--quiet]
$SCRIPT batch-end <batch_id>

# Schema 库管理
$SCRIPT schema-lib-list [--search 关键字]
$SCRIPT schema-lib-save --name 名称 --file schema.json [--description 描述]
$SCRIPT schema-lib-delete 名称

Additional notes

Authentication：Authorization: Bearer $CLAWSHIRE_API_KEY Local debugging：export CLAWSHIRE_API_BASE_URL=http://localhost:8452 Dependencies: The script requires no third-party libraries, using only the Python standard library (urllib, json, argparse, etc.); the platform must have MEME_PLUGIN_REFLECT_ENGINE_ENABLED Time consumption：extract / schema-chat / batch-chat may take several minutes; the user should be informed to wait

Relationship with announcement data: This skilldoes not need met_uuid, suitable for generic extraction from any PDF the user has on hand; if only an announcement link is available, use clawshire-data-query to view existing structured results.

Error code Handling
401 Check CLAWSHIRE_API_KEY
413 Single file exceeds platform MAX_UPLOAD_MB
503 Plugin not enabled or engine URL not configured
502 Engine timeout or SSE error, retry later