feat: add data_extractor and query_extraction tools (DWS Data Extraction API)

[jdrhyne]

Summary

Adds the data extraction workflow primitive to the MCP server, targeting the standalone DWS Data Extraction API (POST /extraction/parse) — a separate product with its own key, not a json-content output of the Processor /build endpoint.

• data_extractor — POST /extraction/parse with a mode (text/structure/understand/agentic) and output format. Spatial output (typed elements with bounding boxes + confidence + reading order) is written to outputPath and summarized inline; markdown is returned inline (or to a file when outputPath is given).
• query_extraction — reads a saved spatial-extraction file and returns filtered element slices inline (by pages, region/bbox, minConfidence, elementTypes), so an agent pulls only the coordinates/values it needs into context.
• A worked extract → query → act example (examples/invoice-extraction-workflow.md).

Architecture

Reuses the existing DwsApiClient abstraction — data_extractor runs on a second client instance authenticated with a new NUTRIENT_EXTRACTION_API_KEY (separate from the Processor NUTRIENT_DWS_API_KEY). No new HTTP plumbing. document_processor's description no longer advertises standalone extraction and points to data_extractor.

Design notes

• Context safety: large spatial output goes to a file; the inline summary is content-free (counts, low-confidence flags, page geometry only — no document text). Markdown also honors outputPath to avoid overflowing the conversation.
• Sandbox: all reads/writes go through the existing sandbox resolvers; absolute paths are re-rooted/contained as in the other tools.
• Robustness: a 2xx response lacking output.elements is rejected before writing, so a non-extraction body can't overwrite the target file.

Testing

• pnpm test: 120 passing (62 skipped). New tests/extract.test.ts (14 cases) covers routing (spatial→file / markdown→inline / markdown→file), the no-PII-in-summary guarantee, sandbox containment, the non-spatial-body guard, the missing-key error, and every query_extraction filter. tests/environment.test.ts + tests/mcp-tools.test.ts updated.
• tsc, eslint, prettier, and pnpm build all clean.
• The 2 pre-existing key-gated live integration tests (build/sign) are unchanged by this PR.

Follow-up

• Live verification (deferred): the handlers are built against Nutrient's published Data Extraction schema (endpoint, instructions shape, element fields). One live /extraction/parse call with a pdf_live_ key should confirm the response shape and capture a fixture before release. Tracked as U0 in docs/plans/2026-06-07-001-feat-dws-data-extraction-workflow-plan.md.

Plan: docs/plans/2026-06-07-001-feat-dws-data-extraction-workflow-plan.md

[jdrhyne]

U0 — live /extraction/parse verification (do before merge)

The handlers are built against Nutrient's published Data Extraction schema, but no live call has run yet (no key was available during development). One real request confirms the response shape and gives us a recorded fixture. Costs ~2–3 credits total.

Steps

# 1. Set the Data Extraction key (SEPARATE from NUTRIENT_DWS_API_KEY; starts with pdf_live_)
export NUTRIENT_EXTRACTION_API_KEY=pdf_live_...   # or add to .env (gitignored)

# 2a. Spatial (structure mode, ~1.5 credits) — confirms the element schema
curl -sS -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer $NUTRIENT_EXTRACTION_API_KEY" \
  -F "file=@tests/assets/example.pdf" \
  -F 'instructions={"mode":"structure","output":{"format":"spatial"}}' \
  | tee tests/fixtures/extraction-spatial-sample.json | jq '.output.elements[0], .metrics'

# 2b. Markdown (text mode, ~1 credit)
curl -sS -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer $NUTRIENT_EXTRACTION_API_KEY" \
  -F "file=@tests/assets/example.pdf" \
  -F 'instructions={"mode":"text","output":{"format":"markdown"}}' \
  | jq '.output | keys'

Acceptance criteria — the code reads exactly these paths (src/dws/extract.ts)

• Spatial: output.elements is an array; each element has type, confidence, bounds.{x,y,width,height}, page.pageIndex. metrics.pagesProcessed is present.
  • summarizeSpatial uses element.type / element.confidence / element.page.pageIndex / metrics.pagesProcessed
  • query_extraction filters on element.bounds / confidence / page.pageIndex / type
• Markdown: response has output.markdown (string).

If the field names match → no code change needed; just drop the captured response into tests/fixtures/ and (optionally) swap the inline fixture in tests/extract.test.ts for it, then this is release-ready.

If anything differs → adjust the SpatialElement / ExtractionResponse types and the filter/summary field access in src/dws/extract.ts (and the instructions shape if options.language / output.includeWords placement differs from the docs).

Tracked as U0 in docs/plans/2026-06-07-001-feat-dws-data-extraction-workflow-plan.md.