Nutrient Document Processing

Use Nutrient DWS for managed document workflows where fidelity, compliance, or multi-step processing matters more than local-tool convenience.

Setup

• Get a Nutrient DWS API key at https://dashboard.nutrient.io/sign_up/?product=processor.
• Direct API calls use

  Authorization: Bearer $NUTRIENT_API_KEY

  .

  export NUTRIENT_API_KEY="nutr_sk_..."
  

• MCP setups commonly use

  @nutrient-sdk/dws-mcp-server

  with

  NUTRIENT_DWS_API_KEY

  .
• Scripts live in

  scripts/

  relative to this SKILL.md. Use the directory containing this SKILL.md as the working directory:

  cd <directory containing this SKILL.md> && uv run scripts/<script>.py --help
  

• Page ranges use

  start:end

  with 0-based indexes and end-exclusive semantics. Negative indexes count from the end.

When to use

• Generate PDFs from HTML templates, uploaded assets, or remote URLs.
• Convert Office, HTML, image, and PDF files between supported formats.
• OCR scans and extract text, tables, or key-value pairs.
• Redact PII, watermark, sign, fill forms, merge, split, rotate, flatten, or encrypt PDFs.
• Produce delivery targets like PDF/A, PDF/UA, optimized PDFs, or linearized PDFs.
• Check credits before large, batch, or AI-heavy runs.

Tool preference

1. Prefer

   scripts/*.py

   for covered single-operation workflows.
2. Use

   assets/templates/custom-workflow-template.py

   for multi-step jobs that should still run through the Python client.
3. Use the modular

   references/

   docs and direct API payloads for capabilities that do not yet have a dedicated helper script, especially HTML/URL generation and compliance tuning.
4. Use local PDF utilities only for lightweight inspection. Use Nutrient when output fidelity or compliance matters.

Single-operation scripts

• convert.py

  -> convert between

  pdf

  ,

  pdfa

  ,

  pdfua

  ,

  docx

  ,

  xlsx

  ,

  pptx

  ,

  png

  ,

  jpeg

  ,

  webp

  ,

  html

  , and

  markdown

• merge.py

  -> merge multiple files into one PDF

• split.py

  -> split one PDF into multiple PDFs by page ranges

• add-pages.py

  -> append blank pages

• delete-pages.py

  -> remove specific pages

• duplicate-pages.py

  -> reorder or duplicate pages into a new PDF

• rotate.py

  -> rotate selected pages

• ocr.py

  -> OCR scanned PDFs or images

• extract-text.py

  -> extract text to JSON

• extract-table.py

  -> extract tables

• extract-key-value-pairs.py

  -> extract key-value pairs

• watermark-text.py

  -> apply a text watermark

• redact-ai.py

  -> detect and apply AI-powered redactions

• sign.py

  -> digitally sign a local PDF

• password-protect.py

  -> write encrypted output PDFs

• optimize.py

  -> apply optimization and linearization-style options via JSON

Multi-Step Workflow Rule

Do not add new committed pipeline scripts under

scripts/

.

When the user asks for multiple operations in one run:

1. Copy

   assets/templates/custom-workflow-template.py

   to a temporary location such as

   /tmp/ndp-workflow-<task>.py

   .
2. Implement the combined workflow in that temporary script.
3. Run it with

   uv run /tmp/ndp-workflow-<task>.py ...

   .
4. Return generated output files.
5. Delete the temporary script unless the user explicitly asks to keep it.

PDF Requirements

• split.py

  requires a multi-page PDF and cannot extract ranges from a single-page document.

• delete-pages.py

  must retain at least one page and cannot delete the entire document.

• sign.py

  only accepts local file paths for the main PDF.

Decision rules

• Prefer a helper script when one already covers the requested operation cleanly.
• If you control the source markup, prefer HTML generation over browser print workflows.
• Use remote

  file.url

  inputs when the source already lives at a stable URL and you want to avoid local uploads.
• Use

  output.type

  for conversion and finalization targets. Use

  actions

  for transformations when building direct API payloads.
• OCR before text extraction, key-value extraction, or semantic redaction on scans.
• Prefer preset or regex redaction when the target is explicit. Use AI redaction only for contextual or natural-language requests.
• Use the PDF manipulation reference for merge, split, rotate, flatten, and page-range workflows instead of inferring those payloads from conversion examples.
• Treat PDF/A and PDF/UA as compliance targets, not cosmetic export formats. Choose the target up front and validate final artifacts when requirements are contractual.
• For PDF/UA, clean born-digital inputs and structured HTML usually tag better than rasterized or flattened source PDFs.
• For delivery optimization, linearize or optimize unsigned output artifacts instead of mutating already signed files.
• When the user asks for multiple steps, keep destructive or final steps late in the sequence. Use the workflow recipes when ordering is ambiguous.

Anti-patterns

• Do not OCR born-digital PDFs just because the task mentions extraction. Extract first and OCR only if the text layer is missing.
• Do not flatten forms or annotations until the user confirms the artifact no longer needs to stay editable.
• Do not sign, archive, or linearize intermediate working files. Keep those as final-delivery steps.
• Do not promise PDF/A or PDF/UA compliance without a validation step when the requirement is contractual.
• Do not commit temporary workflow scripts under

  scripts/

  .

Reference map

Read only what you need:

• references/request-basics.md

  -> endpoint model, auth, multipart vs JSON, credits, limits, and errors

• references/generation-and-conversion.md

  -> HTML/URL generation and format conversion

• references/pdf-manipulation.md

  -> merge, split, page-range, rotate, and flatten workflows

• references/extraction-and-ocr.md

  -> OCR, text extraction, tables, and key-value workflows

• references/security-signing-and-forms.md

  -> redaction, watermarking, signatures, forms, and passwords

• references/compliance-and-optimization.md

  -> PDF/A, PDF/UA, optimization, and linearization

• references/workflow-recipes.md

  -> end-to-end sequencing patterns for common business document workflows

Rules

• Fail fast when required arguments are missing.
• Write outputs to explicit paths and print created files.
• Do not log secrets.
• All client methods are async and should run via

  asyncio.run(main())

  .
• If import fails, install dependency with

  uv add nutrient-dws

  .

Security Hardening Addendum

• Prefer a pinned, preinstalled MCP server binary over runtime package fetches.
  • Preferred:

    npm i -g @nutrient-sdk/dws-mcp-server@<pinned-version>

  • Avoid unpinned runtime fetch in production paths.
• Never store

  NUTRIENT_DWS_API_KEY

  in committed JSON config files.
  • Use process env injection at runtime (shell/export, secrets manager, or host env).
• Restrict file access with

  SANDBOX_PATH

  to the minimum required working directory.
• Before enabling MCP mode in production, verify package provenance and lock version.