Skip to main content
skill CX Codex

document-granular-decompose — Claude Code skill: how to install

document-granular-decompose sends local documents to the TianGong AI Unstructure /mineru_with_images endpoint and returns raw fulltext without extra JSON markup.

MIT 113 installs ★ 11 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a claude-code
Open on GitHub

What document-granular-decompose does

This skill triggers scripts/mineru_fulltext_extract.py to upload local files to the /mineru_with_images endpoint via a multipart request. It forces return_txt=true on every API call. The script pulls text directly from response.txt or falls back to joining non-empty chunks from response.result[].text. It also normalizes upstream Markdown underscores, converting \_ back to _.

A strict allowlist validates document types before making network calls. Supported formats include PDF, image formats like .png and .jpg, plus common Office files such as .docx or .xlsx. Any unlisted file extension causes an immediate local error.

Without UNSTRUCTURED_API_BASE_URL and UNSTRUCTURED_AUTH_TOKEN present in the environment, the script exits immediately. Overriding the backend model remains optional through UNSTRUCTURED_PROVIDER and UNSTRUCTURED_MODEL.

What it helps with

  • extract plain fulltext from PDF and Office files using MinerU
  • filter out unsupported extensions locally before making network calls
  • pipe parsed text to stdout or write directly to a file
  • configure Unstructure API authentication through environment variables

Example prompts for the agent

  • Extract plain text from annual_report.pdf using document-granular-decompose
  • Parse presentation.pptx with document-granular-decompose and save the result to output.txt

How to install document-granular-decompose

1Skills CLI (Vercel)

npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a claude-code

2Manually: put the files in place

~/.claude/skills/document-granular-decompose/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/document-granular-decompose/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about document-granular-decompose

How to install document-granular-decompose in Claude Code?

Run npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a claude-code. This saves the configuration to ~/.claude/skills/document-granular-decompose/SKILL.md.

What does document-granular-decompose do?

It sends local files to the TianGong AI Unstructure /mineru_with_images endpoint and outputs fulltext extracted with MinerU.

Which environment variables are required?

You must export UNSTRUCTURED_API_BASE_URL with your service endpoint and UNSTRUCTURED_AUTH_TOKEN with the bearer token. Settings for UNSTRUCTURED_PROVIDER and UNSTRUCTURED_MODEL are optional.

Source text

SKILL.md · MIT
---
name: document-granular-decompose
description: Upload local documents to TianGong AI Unstructure `/mineru_with_images` API for fine-grained parsing and return only plain fulltext content. Use when a task needs document fulltext extraction with `return_txt=true`, strict file-type allowlist validation, API base URL/auth token from environment variables, and optional provider/model overrides.
---

# Document Granular Decompose

## Core Goal
- Parse a local document through `POST /mineru_with_images`.
- Always force `return_txt=true`.
- Read environment variables for endpoint, request identity, and model routing:
  - `UNSTRUCTURED_API_BASE_URL` (example: `https://your-unstructured-host:7770`)
  - `UNSTRUCTURED_AUTH_TOKEN`
  - `UNSTRUCTURED_PROVIDER` (optional)
  - `UNSTRUCTURED_MODEL` (optional)
- Return only plain fulltext (prefer API `txt`; fallback to joined `result[].text`).

## Triggering Conditions
- Need robust document fulltext extraction for PDF/Office/image files.
- Need image-aware MinerU parsing but only textual output for downstream chunking/search/summarization.
- Need to standardize provider/model/token input via environment variables instead of ad-hoc command parameters.

## Workflow
1. Prepare environment variables.

```bash
export UNSTRUCTURED_AUTH_TOKEN="your-fastapi-bearer-token"
export UNSTRUCTURED_API_BASE_URL="https://your-unstructured-host:7770"
# Optional routing overrides. Omit them to let the server choose its defaults.
export UNSTRUCTURED_PROVIDER="vllm"
export UNSTRUCTURED_MODEL="Qwen/Qwen3.5-122B-A10B-FP8"
```

2. Run extraction and print fulltext to stdout.

```bash
python3 scripts/mineru_fulltext_extract.py \
  --file "/absolute/path/to/document.pdf"
```

3. Save fulltext to a local file when needed.

```bash
python3 scripts/mineru_fulltext_extract.py \
  --file "/absolute/path/to/document.pdf" \
  --output "/absolute/path/to/fulltext.txt"
```

## Request Contract
- Endpoint resolution:
  - `--api-url` if provided
  - else `UNSTRUCTURED_API_BASE_URL + /mineru_with_images`
  - else fail fast with missing environment variable error
- Method: `POST` multipart form.
- Query params:
  - Force `return_txt=true` (always set by script).
- Form fields sent:
  - `file` (required)
  - `provider` (optional, from `UNSTRUCTURED_PROVIDER` when set)
  - `model` (optional, from `UNSTRUCTURED_MODEL` when set)
- Header sent:
  - `Authorization: Bearer $UNSTRUCTURED_AUTH_TOKEN`

## Supported File Types (Strict)
- Supported file types:
  - `.bmp, .doc, .docm, .docx, .dot, .dotx, .gif, .jp2, .jpeg, .jpg, .odp, .odt, .pdf, .png, .pot, .potx, .pps, .ppsx, .ppt, .pptm, .pptx, .tiff, .webp, .xls, .xlsm, .xlsx, .xlt, .xltx`
- Office formats:
  - `.doc, .docm, .docx, .dot, .dotx, .odp, .odt, .pot, .potx, .pps, .ppsx, .ppt, .pptm, .pptx, .xls, .xlsm, .xlsx, .xlt, .xltx`
- Any other extension is rejected before sending API requests.

## Output Rules
- Success output must be plain text fulltext only.
- Normalize the confirmed upstream Markdown underscore escape (`\_` to `_`)
  in both supported response paths; preserve other backslashes and escapes.
- Fulltext source priority:
  1. `response.txt`
  2. join non-empty `response.result[].text` by blank lines
- Do not output chunk metadata/json unless the user explicitly requests debugging.

## Error Handling
- Missing required env vars (`UNSTRUCTURED_API_BASE_URL`, `UNSTRUCTURED_AUTH_TOKEN`): fail fast with actionable message.
- Missing `UNSTRUCTURED_PROVIDER` or `UNSTRUCTURED_MODEL`: omit the form field and let the service choose its default.
- HTTP 401/403: report token/auth issue.
- HTTP 4xx/5xx: print status and API error body if available.
- Missing text in response: fail with explicit schema mismatch error.

## References
- `references/env.md`
- `references/request-response.md`

## Assets
- `assets/config.example.env`

## Scripts
- `scripts/mineru_fulltext_extract.py`

© tiangong-ai · MIT · tiangong-ai/agent-skills

Similar skills

All skills for Office documents →

From the same set5

Project sponsors

Companies that keep this analytics open