ailang-parse

AILANG Parse — Universal Document Parsing

Parse any document into structured blocks via the AILANG Parse API. 17 input formats, 9 output formats, one consistent schema.

MCP Tools (Preferred)

This plugin registers an MCP server at https://docparse.ailang.sunholo.com/mcp/. The following tools are available automatically:

Tool	Purpose
mcpParse	Parse any document into blocks, Markdown, or HTML
mcpConvert	Convert between 17 input and 9 output formats
mcpFormats	Discover formats, 26 samples, pricing tiers, capabilities
mcpEstimate	Predict cost/latency before parsing
mcpAuth	Start device auth to get an API key (RFC 8628)
mcpAuthPoll	Poll for auth completion
mcpAccount	View tier, quota, usage, pricing, history

Recommended workflow: Call mcpFormats first to discover capabilities, then mcpEstimate to check cost, then mcpParse to parse. If auth is needed, the error response tells you to call mcpAuth.

Shell Scripts (Fallback)

# 1. Check connection
bash scripts/health.sh

# 2. See available test files
bash scripts/samples.sh

# 3. Parse a document
bash scripts/parse.sh data/test_files/sample.docx blocks

# 4. Estimate cost before parsing
bash scripts/estimate.sh report.pdf blocks

When to Use This Skill

• User asks to parse, extract, or convert a document
• User has DOCX, PDF, PPTX, XLSX, CSV, HTML, Markdown, EPUB, ODT, ODP, ODS files
• User wants structured data from Office documents (tables, headings, track changes, comments)
• User wants to extract text from PDFs, images, audio, or video
• User asks about AILANG Parse API endpoints or capabilities
• User needs Unstructured.io API compatibility
• User wants to estimate parsing costs or check quota

API Base URLs

Environment	URL
Production	https://docparse.ailang.sunholo.com
Test	https://ailang-test-docparse-api-rrmdhcxo4a-ew.a.run.app
Dev	https://ailang-dev-docparse-api-ejjw6zt3bq-ew.a.run.app

Default: production. Set DOCPARSE_URL env var to override.

Authentication

API key with dp_ prefix. Pass as apiKey in the JSON body, or set DOCPARSE_API_KEY env var for skill scripts.

Get a key: Visit https://sunholo-data.github.io/docparse/dashboard.html

For headless agents: Use the device authorization flow:

bash scripts/device-auth.sh

Core Endpoints

Endpoint	Method	Purpose
/api/v1/parse	POST	Parse any document
/api/v1/estimate	POST	Check cost before parsing
/api/v1/capabilities	GET	Full service contract
/api/v1/samples	GET	Test files for verification
/api/v1/formats	GET	Supported formats
/api/v1/pricing	GET	Tier definitions + credit costs
/api/v1/health	GET	Service status
/general/v0/general	POST	Unstructured API drop-in

Parsing Documents

# Named JSON parameters (preferred)
curl -X POST "$DOCPARSE_URL/api/v1/parse" \
  -H "Content-Type: application/json" \
  -d "{\"filepath\":\"report.docx\",\"outputFormat\":\"blocks\",\"apiKey\":\"$DOCPARSE_API_KEY\"}"

Output formats: blocks (structured JSON), markdown, html, a2ui

All formats return the same block types: Text, Heading, Table, Image, Audio, Video, List, Section, Change.

Available Scripts

Script	Usage	Purpose
scripts/health.sh	bash scripts/health.sh	Check API health
scripts/parse.sh	bash scripts/parse.sh <filepath> [format]	Parse a document
scripts/estimate.sh	bash scripts/estimate.sh <filepath> [format]	Estimate cost
scripts/samples.sh	bash scripts/samples.sh	List test files
scripts/capabilities.sh	bash scripts/capabilities.sh	Full service contract
scripts/device-auth.sh	bash scripts/device-auth.sh	Get API key via device flow

Workflow: Parse a Document

1. Check health: bash scripts/health.sh
2. Estimate cost: bash scripts/estimate.sh report.docx blocks
3. Parse: bash scripts/parse.sh report.docx blocks
4. Use the result: The response contains structured blocks (JSON)

Workflow: Verify Integration

1. List samples: bash scripts/samples.sh
2. Parse a test file: bash scripts/parse.sh data/test_files/sample.docx blocks
3. Check the response has result field with blocks array
4. Compare response shape to the capability manifest's golden examples

Error Codes

Code	Retryable	Fix
INPUT_NOT_FOUND	No	Check file path, use /api/v1/samples for test files
UNSUPPORTED_FORMAT	No	Check /api/v1/formats for supported types
INVALID_API_KEY	No	Check key format (dp_ + 32 hex chars)
QUOTA_EXCEEDED	After reset	Wait for daily reset or upgrade tier
AI_UNAVAILABLE	Yes	Retry — AI backend temporarily down
PARSE_FAILED	Maybe	File may be corrupt

All errors include suggested_fix — a plain-text instruction you can act on directly.

Credit Costs

Format	Credits
Office (DOCX, PPTX, XLSX, ODT, ODP, ODS)	1
Text (CSV, Markdown, HTML, EPUB)	1
PDF	3
Image (PNG, JPG, GIF, TIFF, WebP)	3
Audio (MP3, WAV)	5
Video (MP4)	10

Deployment & Release

DocParse uses a three-environment pipeline managed from the ailang-multivac repo:

Push to main  →  Dev  (automatic, per-push)
Tag v*        →  Test (automatic, versioned images)
Promote       →  Prod (manual, exact image copy — no rebuild)

Action	Command (from ailang-multivac repo)
Check status	scripts/release.sh status
Tag for test	scripts/release.sh tag docparse v0.9.0
Promote to prod	scripts/release.sh promote docparse
Monitor builds	gcloud builds list --project=ailang-multivac-deploy --region=europe-west3 --limit=5

Verify after deploy

# Test environment
curl https://ailang-test-docparse-api-rrmdhcxo4a-ew.a.run.app/api/v1/health

# Production
curl https://docparse.ailang.sunholo.com/api/v1/health
curl https://docparse.ailang.sunholo.com/api/v1/capabilities | jq .base_url

GCP Projects

Env	Project	Prefix
Dev	ailang-multivac-dev	ailang-dev
Test	ailang-multivac-test	ailang-test
Prod	ailang-multivac	ailang

Cloud Build triggers live in ailang-multivac-deploy (europe-west3).

Resources

• API Reference — full endpoint documentation
• Integration Guide — Python, TypeScript, curl examples