---

name: document-extraction description: "Use Sparrow Parse for structured extraction from images and PDFs with schemas, page types, table/markdown flows, hints, crop/annotation options, and pluggable VLM backends." metadata: disco-role: operating disable-model-invocation: true license: GPL 3.0

document-extraction

Use this sub-skill when the task is to extract structured JSON, markdown, page type labels, or table data from image/PDF documents through Sparrow Parse.

Route first

• Use this sub-skill for Sparrow Parse package calls, query/schema construction, page-type detection, markdown/table extraction choices, crop/annotation flags, and backend selection.
• Route FastAPI endpoints, multipart forms, curl commands, and service request construction to api-engine-and-cli.
• Route OCR service endpoint operation to ocr-service.
• Route UI upload/operation/deployment questions to ui-and-deployment.
• Route Sparrow Agents orchestration to agent-workflows.

Operating checklist

1. Choose the execution surface. Prefer direct sparrow-parse package calls for code-level extraction; use the Sparrow engine/CLI only when the user is already operating that interface. The package console command named sparrow-parse is broken upstream; use package imports or python -m sparrow_parse for the package self-message.
2. Build the query. For schema extraction, pass valid JSON examples such as {"invoice_number":"str","total":0.0} or arrays of objects. Use "*" for generic all-data extraction. Use page-type candidates with "*" only when the task is page classification.
3. Select backend and model. Confirm one supported backend method and model/space/API credential before constructing inference. See references/backend-options.md.
4. Choose document flow. For ordinary image/PDF extraction, call VLLMExtractor.run_inference. For table-only crops, set tables_only; for markdown-first extraction, use the two-stage markdown flow. See references/document-workflows.md.
5. Use safe local helpers before expensive inference. Build and validate prompts with scripts/parse_request_builder.py. Run the no-model fixture smoke in scripts/parse_input_smoke.py before testing a real backend.
6. Diagnose failures. Separate invalid user query JSON, invalid model JSON output, backend setup, PDF/poppler, table model downloads, and crop/debug artifacts. See references/troubleshooting.md.

Key contracts to remember

• sparrow-parse==1.5.6 exposes InferenceFactory(config).get_inference_instance() and VLLMExtractor().run_inference(...).
• run_inference returns (results, num_pages) and does not itself run schema validation; validation and page-number wrapping are performed by the Sparrow Parse pipeline layer.
• Valid backend methods are huggingface, local_gpu, mlx, ollama, vllm, and mistral; local_gpu is a placeholder unless a model is supplied outside the default factory path.
• validation_off, tables_only, and apply_annotation are parsed from extra backend options in the pipeline layer. Page-type, annotation, instruction, validation-query, markdown, and generic "*" flows bypass normal schema validation.
• PDF inputs are split into page images before VLM inference; poppler is required for PDF-to-image conversion.