private-document-ai-with-openvino-x-7

原始内容

---
name: local-document-ai-openvino
description: Private local document AI for Intel hardware. Parse PDFs, invoices, screenshots, and diagrams with MinerU 2.5 on OpenVINO GenAI, keep the model warm in a local service, and output structured JSON/Markdown with user-defined invoice fields.
---

# Private Document AI with OpenVINO

Turn local PDFs, invoices, screenshots, and diagrams into one of two useful outcomes:

1. `to-data`: classify the document and extract structured fields, tables, and JSON, including user-requested key fields.
2. `to-code`: turn screenshots, forms, and architecture diagrams into code or Jupyter notebook scaffolds.

Everything runs locally and is built for Intel CPU/GPU acceleration with OpenVINO GenAI.
The default device is `CPU` for workshop stability. Set `MINERU_OPENVINO_DEVICE=GPU` or `AUTO` only after validating the target AI PC.

The default user experience is app-like:

- the first call auto-starts a local service
- HTTP/FastAPI service is preferred when available
- the standard-library IPC service is used as a fallback
- direct CLI parsing remains available with `--no-server`
- the model stays resident after warmup so later calls avoid repeat model loading

The default runtime path in this release is:

- MinerU 2.5 Pro
- preconverted OpenVINO INT4 model bundle
- local PDF rendering with `pypdfium2`
- no local model export step

## Why install this skill

Install this when you want one local workflow for:

- invoice and receipt extraction
- private PDF understanding
- table and key-value extraction
- architecture diagram to notebook generation
- screenshot to HTML/React scaffold generation

This skill is especially good for demos because it already includes:

- medical invoice `to-data` flows
- restaurant invoice `to-data` flows
- custom invoice field extraction such as invoice number, date, seller, and amount due
- architecture diagram `to-code -> jupyter-notebook` flows
- local HTML reports for easy review and screenshots

## 30-second start

Check the environment:

```bash
python "{baseDir}/scripts/check_env.py"
```

Install with the fastest available local installer path:

```powershell
powershell -ExecutionPolicy Bypass -File "{baseDir}/scripts/install.ps1"
```

Warm up the local document AI service:

```bash
python "{baseDir}/scripts/run_skill.py" --warmup-server
```

Or run directly from the CLI. Server mode is automatic by default:

```bash
python "{baseDir}/scripts/run_skill.py" --mode to-data --file "/absolute/path/to/invoice.pdf" --out "/absolute/path/to/artifacts/invoice_data" --extract "tables,entities,kv_pairs"
```

For invoice demos with custom key fields:

```bash
python "{baseDir}/scripts/run_skill.py" --mode to-data --file "/absolute/path/to/invoice.pdf" --out "/absolute/path/to/artifacts/invoice_data" --extract "tables,entities,kv_pairs" --fields "invoice_number,invoice_date,total_amount,vendor_name"
```

For repeated workshop demos, prefer the persistent local server mode:

```bash
python "{baseDir}/scripts/run_skill.py" --warmup-server
python "{baseDir}/scripts/run_skill.py" --mode to-data --file "/absolute/path/to/invoice.pdf" --out "/absolute/path/to/artifacts/invoice_data" --extract "tables,entities,kv_pairs" --fields "invoice_number,invoice_date,total_amount,vendor_name"
```

One-command invoice demo:

```powershell
powershell -ExecutionPolicy Bypass -File "{baseDir}/scripts/demo_invoice.ps1"
```

## Example prompts

Use prompts like these in OpenClaw:

```text
Use $local-document-ai-openvino to parse this local PDF and give me a structured report.
```

```text
Use $local-document-ai-openvino to extract invoice fields, tables, and key-value pairs from this medical invoice.
```

```text
Use $local-document-ai-openvino to classify this receipt and return normalized JSON.
```

```text
Use $local-document-ai-openvino to extract only these invoice fields from this file: invoice_number, invoice_date, total_amount, vendor_name. Return a structured JSON result with just those requested fields.
```

```text
Use $local-document-ai-openvino to extract these custom fields from this invoice: buyer_tax_id, seller_tax_id, amount_due, check_code. Save the full parse artifacts, but highlight the requested fields in the final structured output.
```

```text
Use $local-document-ai-openvino to turn this architecture diagram into a Jupyter notebook scaffold.
```

```text
Use $local-document-ai-openvino to convert this UI screenshot into an HTML scaffold.
```

## What you get

Typical outputs include:

- `parsed.json`
- `parsed.md`
- `result_report.html`
- `task_output/structured_record.json`
- `task_output/normalized.json`
- `task_output/requested_fields.json`
- `task_output/requested_fields_record.json`
- `task_output/notebook.ipynb`
- `code_preview.html`

## Best demo paths

If you are evaluating the skill for the first time, start here:

1. run `--warmup-server` once to start the persistent local parser and preload the model
2. `to-data` on an invoice PDF; local service mode is automatic
3. review `result_report.html`
4. inspect `structured_record.json`
5. rerun with `--fields` and inspect `requested_fields_record.json`
6. then try `to-code` with a diagram image and target `jupyter-notebook`

## Persistent local server mode

Use server mode when the same machine will parse multiple PDFs/images. This is the default path.

Why this helps:

1. The first request loads and compiles the MinerU/OpenVINO GenAI runtime once.
2. Later agent calls send lightweight local IPC requests to the resident process.
3. Model weights stay in the process memory instead of being moved repeatedly.
4. The HTTP service layer makes future Web UI, desktop UI, and multi-agent integrations easier.
5. The standard-library IPC server remains as a fallback when HTTP dependencies are unavailable.
6. The normal CLI path remains available for one-off runs and debugging with `--no-server`.

Warm up the server before a hands-on session:

```bash
python "{baseDir}/scripts/run_skill.py" --warmup-server
```

Inspect the server:

```bash
python "{baseDir}/scripts/run_skill.py" --server-status
```

Run through the resident server:

```bash
python "{baseDir}/scripts/run_skill.py" --mode to-data --file "/absolute/path/to/invoice.pdf" --out "/absolute/path/to/artifacts/invoice_data" --extract "tables,entities,kv_pairs" --fields "invoice_number,invoice_date,total_amount,vendor_name"
```

Force a specific local service transport if needed:

```bash
python "{baseDir}/scripts/run_skill.py" --server-kind http --server-status
python "{baseDir}/scripts/run_skill.py" --server-kind ipc --server-status
```

Disable service mode for debugging:

```bash
python "{baseDir}/scripts/run_skill.py" --no-server --mode parse --file "/absolute/path/to/file.pdf"
```

Release memory after the workshop:

```bash
python "{baseDir}/scripts/run_skill.py" --shutdown-server
```

Server mode uses these implementation files:

- `{baseDir}/scripts/parse_client.py`
- `{baseDir}/scripts/http_parse_server.py`
- `{baseDir}/scripts/persistent_parse_server.py`

The server listens only on `127.0.0.1` loopback by default and does not bind to external network interfaces.
If the default port is occupied, set `LOCAL_DOCUMENT_AI_SERVER_PORT` before starting the server.
For HTTP service mode, set `LOCAL_DOCUMENT_AI_HTTP_PORT` if port `47274` is occupied.

## Custom key-field extraction

After the skill is installed, users can ask for a custom field list at call time.
This is the recommended pattern for invoice demos.

Use the `fields` parameter with `to-data`:

- CLI: `--fields "invoice_number,invoice_date,total_amount,vendor_name"`
- config JSON: `"fields": "invoice_number,invoice_date,total_amount,vendor_name"`
- slash-command style: `fields=invoice_number,invoice_date,total_amount,vendor_name`

The skill will:

1. parse the full document locally with MinerU on OpenVINO
2. keep the standard `kv_pairs`, `entities`, `tables`, and traceability artifacts
3. resolve the requested field names to canonical keys when possible
4. write a focused structured output for only those requested fields

The two demo-friendly outputs are:

- `task_output/requested_fields.json`
  This includes each requested field, the matched canonical key, whether it was found, the primary match, and all matches.
- `task_output/requested_fields_record.json`
  This is the compact final record keyed by the user-requested field names.

Recommended invoice demo field names:

- `invoice_number`
- `invoice_code`
- `check_code`
- `invoice_date`
- `buyer_tax_id`
- `seller_tax_id`
- `vendor_name`
- `customer_name`
- `subtotal`
- `tax_amount`
- `total_amount`
- `amount_due`

Common aliases are also supported when they can be normalized to canonical keys, for example:

- `seller`
- `buyer`
- `invoice no`
- `invoice date`
- `total`
- `amount due`

## Core pipeline

Use this skill as a local document-to-action pipeline:

1. Parse the document into a canonical structured representation.
2. Optionally continue into `to-data` or `to-code`.
3. Save outputs into a predictable artifact folder with traceability.

## Read only if needed

Load these references when you need the schema or output contracts:

- `{baseDir}/references/schema.md`
- `{baseDir}/references/mode_guide.md`
- `{baseDir}/references/output_contracts.md`

## Primary entrypoint

Use this published entrypoint:

- CLI orchestrator: `{baseDir}/scripts/run_skill.py`
- recommended default path: `{baseDir}/scripts/run_skill.py --mode to-data --file ...`
- one-command invoice demo: `{baseDir}/scripts/demo_invoice.ps1`

Do not call these implementation scripts directly from the skill:

- `parse_document.py`
- `parse_client.py`
- `persistent_parse_server.py`
- `transform_doc_to_data.py`
- `transform_doc_to_code.py`

## Local readiness

Check the environment before processing real documents:

```bash
python "{baseDir}/scripts/check_env.py"
```

For workshops, the simplest setup is installing into a skill-local `.vendor` directory.
The installer uses `uv pip` when `uv` is available and falls back to `pip`.
The entry scripts auto-detect the skill-local `.vendor`, so you do not need to edit `PYTHONPATH`:

```bash
python "{baseDir}/scripts/install_local_runtime.py"
```

If you prefer, a normal virtual environment also works:

```bash
python -m pip install -r "{baseDir}/requirements.txt"
```

Download the preconverted MinerU OpenVINO model bundle into the skill-local `models/` folder, or point the skill at it with an environment variable:

```bash
set MINERU_OPENVINO_MODEL_DIR=C:\absolute\path\to\MinerU2.5-Pro-2604-1.2B-int4-ov
```

For the most stable hands-on setup, keep the default CPU path. To test acceleration on a validated Intel AI PC:

```bash
set MINERU_OPENVINO_DEVICE=GPU
```

Recommended model bundle:

- `https://www.modelscope.cn/models/snake7gun/MinerU2.5-Pro-2604-1.2B-int4-ov`

Workshop-friendly download example:

```bash
git clone --depth 1 https://www.modelscope.cn/snake7gun/MinerU2.5-Pro-2604-1.2B-int4-ov.git "{baseDir}/models/MinerU2.5-Pro-2604-1.2B-int4-ov"
```

Run a quick orchestration smoke test:

```bash
python "{baseDir}/scripts/smoke_test.py"
```

Model assets are discovered from:

- `MINERU_OPENVINO_MODEL_DIR`
- `MINERU_MODEL_DIR`
- `{baseDir}/models/MinerU2.5-Pro-2604-1.2B-int4-ov/`
- `{baseDir}/models/mineru2.5-int4-ov/`

Prefer using a predownloaded model bundle for workshops. This skill does not require local export or automatic model download.

## Supported modes

### `parse`

Use when the user wants the structured parse only.

Outputs:

- `parsed.json`
- `parsed.md`
- `result_report.html`
- extracted layout, tables, or figures when available

### `to-data`

Use when the user wants structured extraction, normalization, or document classification.

Typical outputs under `task_output/`:

- `entities.json`
- `kv_pairs.json`
- `table_index.json`
- `normalized.json`
- `structured_record.json`
- `requested_fields.json`
- `requested_fields_record.json`
- `traceability.json`

### `to-code`

Use when the user wants implementation-oriented output from the parse result.

Supported targets:

- `react`
- `html-css`
- `json-schema`
- `jupyter-notebook`

Typical outputs under `task_output/`:

- `component_map.json`
- `field_schema.json`
- `ui_blueprint.json`
- `notes.md`
- `traceability.json`
- target-specific artifacts such as `app.jsx`, `index.html`, `styles.css`, `schema.json`, `notebook.ipynb`, or `notebook_plan.json`

Treat all generated code and notebooks as drafts. Review them before running, publishing, or connecting them to real systems.

## Published package scope

The published ClawHub bundle is intentionally CLI-first.

- main workflow: `scripts/run_skill.py`
- diagnostics: `scripts/check_env.py`
- smoke verification: `scripts/smoke_test.py`

Developer-only local UI helpers are kept out of the public release bundle.

## Pipeline rules

Always follow these rules:

1. Prefer local execution.
2. Always parse first into `parsed.json`.
3. Generate downstream artifacts from `parsed.json`, not raw OCR text alone.
4. Preserve page numbers, reading order, block types, and source anchors when possible.
5. Write traceability for downstream outputs.
6. Mark low-confidence regions or assumptions explicitly.
7. Do not silently drop tables, figures, formulas, charts, or key-value regions.
8. Save outputs into one artifact folder per run.
9. For confidential documents, prefer an explicit private `--out` directory and remove artifacts after review.

## Output contract

Default output folder:

`./artifacts/<document_stem>/`

Expected top-level outputs:

- `effective_config.json`
- `run_report.json`
- `parsed.json`
- `parsed.md`
- `result_report.html`
- `task_output/`

`to-code` runs may also emit:

- `code_preview.html`

## CLI examples

### Parse

```bash
python "{baseDir}/scripts/run_skill.py" \
  --mode parse \
  --file "/absolute/path/to/report.pdf" \
  --out "/absolute/path/to/artifacts/report_parse"
```

### To-data

```bash
python "{baseDir}/scripts/run_skill.py" \
  --mode to-data \
  --file "/absolute/path/to/invoice.pdf" \
  --out "/absolute/path/to/artifacts/invoice_data" \
  --extract "tables,entities,kv_pairs"
```

### To-data with custom fields

```bash
python "{baseDir}/scripts/run_skill.py" \
  --mode to-data \
  --file "/absolute/path/to/invoice.pdf" \
  --out "/absolute/path/to/artifacts/invoice_data" \
  --extract "tables,entities,kv_pairs" \
  --fields "invoice_number,invoice_date,total_amount,vendor_name"
```

### To-code

```bash
python "{baseDir}/scripts/run_skill.py" \
  --mode to-code \
  --file "/absolute/path/to/ui_mockup.png" \
  --out "/absolute/path/to/artifacts/ui_code" \
  --target "react" \
  --title "Generated App"
```

### To-code notebook target

```bash
python "{baseDir}/scripts/run_skill.py" \
  --mode to-code \
  --file "/absolute/path/to/architecture_diagram.png" \
  --out "/absolute/path/to/artifacts/notebook_code" \
  --target "jupyter-notebook" \
  --title "OpenVINO Notebook"
```

## Slash-command examples

```text
/skill local-document-ai-openvino parse file=./docs/report.pdf
```

```text
/skill local-document-ai-openvino to-data file=./docs/invoice.pdf extract=tables,entities,kv_pairs
```

```text
/skill local-document-ai-openvino to-data file=./docs/invoice.pdf extract=tables,entities,kv_pairs fields=invoice_number,invoice_date,total_amount,vendor_name
```

```text
/skill local-document-ai-openvino to-code file=./mockups/architecture.png target=jupyter-notebook
```

## Optional local demo UI

Start the local UI when the user wants an interactive demo page:

```bash
python "{baseDir}/scripts/serve_skill_ui.py"
```

The UI lets the user:

- preview a local file
- choose `parse`, `to-data`, or `to-code`
- choose the `to-code` target
- run the pipeline and inspect the generated local HTML reports

The bundled UI only allows preview/run access for local files under the skill directory and common user content folders such as Downloads, Documents, Desktop, and Pictures.

## Failure behavior

If a run fails:

- state which stage failed
- do not claim outputs were created if they were not
- prefer writing `error.json` with failure details
- recommend `parse` first when the downstream request is ambiguous
- surface stderr or a concise failure summary when available

## Safety notes

- Use a virtual environment for dependency installation.
- Review and approve model downloads only when you explicitly intend to.
- Keep outputs in a private local folder when documents are sensitive.
- Review generated code and notebooks before execution.
- Delete artifacts when they are no longer needed.
- The wrapper always uses the bundled local scripts and the current Python interpreter. It does not allow custom interpreter or script-directory overrides.

## Short reminder

Present this skill as a local document-understanding workflow with downstream actions and customizable field extraction, not as a plain OCR wrapper.

name: local-document-ai-openvino description: Private local document AI for Intel hardware. Parse PDFs, invoices, screenshots, and diagrams with MinerU 2.5 on OpenVINO GenAI, keep the model warm in a local service, and output structured JSON/Markdown with user-defined invoice fields.

Private Document AI with OpenVINO

Turn local PDFs, invoices, screenshots, and diagrams into one of two useful outcomes:

to-data: classify the document and extract structured fields, tables, and JSON, including user-requested key fields.
to-code: turn screenshots, forms, and architecture diagrams into code or Jupyter notebook scaffolds.

Everything runs locally and is built for Intel CPU/GPU acceleration with OpenVINO GenAI. The default device is CPU for workshop stability. Set MINERU_OPENVINO_DEVICE=GPU or AUTO only after validating the target AI PC.

The default user experience is app-like:

the first call auto-starts a local service
HTTP/FastAPI service is preferred when available
the standard-library IPC service is used as a fallback
direct CLI parsing remains available with --no-server
the model stays resident after warmup so later calls avoid repeat model loading

The default runtime path in this release is:

MinerU 2.5 Pro
preconverted OpenVINO INT4 model bundle
local PDF rendering with pypdfium2
no local model export step

Why install this skill

Install this when you want one local workflow for:

invoice and receipt extraction
private PDF understanding
table and key-value extraction
architecture diagram to notebook generation
screenshot to HTML/React scaffold generation

This skill is especially good for demos because it already includes:

medical invoice to-data flows
restaurant invoice to-data flows
custom invoice field extraction such as invoice number, date, seller, and amount due
architecture diagram to-code -> jupyter-notebook flows
local HTML reports for easy review and screenshots

30-second start

Check the environment:

python "{baseDir}/scripts/check_env.py"

Install with the fastest available local installer path:

powershell -ExecutionPolicy Bypass -File "{baseDir}/scripts/install.ps1"

Warm up the local document AI service:

python "{baseDir}/scripts/run_skill.py" --warmup-server

Or run directly from the CLI. Server mode is automatic by default:

python "{baseDir}/scripts/run_skill.py" --mode to-data --file "/absolute/path/to/invoice.pdf" --out "/absolute/path/to/artifacts/invoice_data" --extract "tables,entities,kv_pairs"

For invoice demos with custom key fields:

python "{baseDir}/scripts/run_skill.py" --mode to-data --file "/absolute/path/to/invoice.pdf" --out "/absolute/path/to/artifacts/invoice_data" --extract "tables,entities,kv_pairs" --fields "invoice_number,invoice_date,total_amount,vendor_name"

For repeated workshop demos, prefer the persistent local server mode:

python "{baseDir}/scripts/run_skill.py" --warmup-server
python "{baseDir}/scripts/run_skill.py" --mode to-data --file "/absolute/path/to/invoice.pdf" --out "/absolute/path/to/artifacts/invoice_data" --extract "tables,entities,kv_pairs" --fields "invoice_number,invoice_date,total_amount,vendor_name"

One-command invoice demo:

powershell -ExecutionPolicy Bypass -File "{baseDir}/scripts/demo_invoice.ps1"

Example prompts

Use prompts like these in OpenClaw:

Use $local-document-ai-openvino to parse this local PDF and give me a structured report.

Use $local-document-ai-openvino to extract invoice fields, tables, and key-value pairs from this medical invoice.

Use $local-document-ai-openvino to classify this receipt and return normalized JSON.

Use $local-document-ai-openvino to extract only these invoice fields from this file: invoice_number, invoice_date, total_amount, vendor_name. Return a structured JSON result with just those requested fields.

Use $local-document-ai-openvino to extract these custom fields from this invoice: buyer_tax_id, seller_tax_id, amount_due, check_code. Save the full parse artifacts, but highlight the requested fields in the final structured output.

Use $local-document-ai-openvino to turn this architecture diagram into a Jupyter notebook scaffold.

Use $local-document-ai-openvino to convert this UI screenshot into an HTML scaffold.

What you get

Typical outputs include:

parsed.json
parsed.md
result_report.html
task_output/structured_record.json
task_output/normalized.json
task_output/requested_fields.json
task_output/requested_fields_record.json
task_output/notebook.ipynb
code_preview.html

Best demo paths

If you are evaluating the skill for the first time, start here:

run --warmup-server once to start the persistent local parser and preload the model
to-data on an invoice PDF; local service mode is automatic
review result_report.html
inspect structured_record.json
rerun with --fields and inspect requested_fields_record.json
then try to-code with a diagram image and target jupyter-notebook

Persistent local server mode

Use server mode when the same machine will parse multiple PDFs/images. This is the default path.

Why this helps:

The first request loads and compiles the MinerU/OpenVINO GenAI runtime once.
Later agent calls send lightweight local IPC requests to the resident process.
Model weights stay in the process memory instead of being moved repeatedly.
The HTTP service layer makes future Web UI, desktop UI, and multi-agent integrations easier.
The standard-library IPC server remains as a fallback when HTTP dependencies are unavailable.
The normal CLI path remains available for one-off runs and debugging with --no-server.

Warm up the server before a hands-on session:

python "{baseDir}/scripts/run_skill.py" --warmup-server

Inspect the server:

python "{baseDir}/scripts/run_skill.py" --server-status

Run through the resident server:

python "{baseDir}/scripts/run_skill.py" --mode to-data --file "/absolute/path/to/invoice.pdf" --out "/absolute/path/to/artifacts/invoice_data" --extract "tables,entities,kv_pairs" --fields "invoice_number,invoice_date,total_amount,vendor_name"

Force a specific local service transport if needed:

python "{baseDir}/scripts/run_skill.py" --server-kind http --server-status
python "{baseDir}/scripts/run_skill.py" --server-kind ipc --server-status

Disable service mode for debugging:

python "{baseDir}/scripts/run_skill.py" --no-server --mode parse --file "/absolute/path/to/file.pdf"

Release memory after the workshop:

python "{baseDir}/scripts/run_skill.py" --shutdown-server

Server mode uses these implementation files:

{baseDir}/scripts/parse_client.py
{baseDir}/scripts/http_parse_server.py
{baseDir}/scripts/persistent_parse_server.py

The server listens only on 127.0.0.1 loopback by default and does not bind to external network interfaces. If the default port is occupied, set LOCAL_DOCUMENT_AI_SERVER_PORT before starting the server. For HTTP service mode, set LOCAL_DOCUMENT_AI_HTTP_PORT if port 47274 is occupied.

Custom key-field extraction

After the skill is installed, users can ask for a custom field list at call time. This is the recommended pattern for invoice demos.

Use the fields parameter with to-data:

CLI: --fields "invoice_number,invoice_date,total_amount,vendor_name"
config JSON: "fields": "invoice_number,invoice_date,total_amount,vendor_name"
slash-command style: fields=invoice_number,invoice_date,total_amount,vendor_name

The skill will:

parse the full document locally with MinerU on OpenVINO
keep the standard kv_pairs, entities, tables, and traceability artifacts
resolve the requested field names to canonical keys when possible
write a focused structured output for only those requested fields

The two demo-friendly outputs are:

task_output/requested_fields.json This includes each requested field, the matched canonical key, whether it was found, the primary match, and all matches.
task_output/requested_fields_record.json This is the compact final record keyed by the user-requested field names.

Recommended invoice demo field names:

invoice_number
invoice_code
check_code
invoice_date
buyer_tax_id
seller_tax_id
vendor_name
customer_name
subtotal
tax_amount
total_amount
amount_due

Common aliases are also supported when they can be normalized to canonical keys, for example:

seller
buyer
invoice no
invoice date
total
amount due

Core pipeline

Use this skill as a local document-to-action pipeline:

Parse the document into a canonical structured representation.
Optionally continue into to-data or to-code.
Save outputs into a predictable artifact folder with traceability.

Read only if needed

Load these references when you need the schema or output contracts:

{baseDir}/references/schema.md
{baseDir}/references/mode_guide.md
{baseDir}/references/output_contracts.md

Primary entrypoint

Use this published entrypoint:

CLI orchestrator: {baseDir}/scripts/run_skill.py
recommended default path: {baseDir}/scripts/run_skill.py --mode to-data --file ...
one-command invoice demo: {baseDir}/scripts/demo_invoice.ps1

Do not call these implementation scripts directly from the skill:

parse_document.py
parse_client.py
persistent_parse_server.py
transform_doc_to_data.py
transform_doc_to_code.py

Local readiness

Check the environment before processing real documents:

python "{baseDir}/scripts/check_env.py"

For workshops, the simplest setup is installing into a skill-local .vendor directory. The installer uses uv pip when uv is available and falls back to pip. The entry scripts auto-detect the skill-local .vendor, so you do not need to edit PYTHONPATH:

python "{baseDir}/scripts/install_local_runtime.py"

If you prefer, a normal virtual environment also works:

python -m pip install -r "{baseDir}/requirements.txt"

Download the preconverted MinerU OpenVINO model bundle into the skill-local models/ folder, or point the skill at it with an environment variable:

set MINERU_OPENVINO_MODEL_DIR=C:\absolute\path\to\MinerU2.5-Pro-2604-1.2B-int4-ov

For the most stable hands-on setup, keep the default CPU path. To test acceleration on a validated Intel AI PC:

set MINERU_OPENVINO_DEVICE=GPU

Recommended model bundle:

https://www.modelscope.cn/models/snake7gun/MinerU2.5-Pro-2604-1.2B-int4-ov

Workshop-friendly download example:

git clone --depth 1 https://www.modelscope.cn/snake7gun/MinerU2.5-Pro-2604-1.2B-int4-ov.git "{baseDir}/models/MinerU2.5-Pro-2604-1.2B-int4-ov"

Run a quick orchestration smoke test:

python "{baseDir}/scripts/smoke_test.py"

Model assets are discovered from:

MINERU_OPENVINO_MODEL_DIR
MINERU_MODEL_DIR
{baseDir}/models/MinerU2.5-Pro-2604-1.2B-int4-ov/
{baseDir}/models/mineru2.5-int4-ov/

Prefer using a predownloaded model bundle for workshops. This skill does not require local export or automatic model download.

Supported modes

`parse`

Use when the user wants the structured parse only.

Outputs:

parsed.json
parsed.md
result_report.html
extracted layout, tables, or figures when available

`to-data`

Use when the user wants structured extraction, normalization, or document classification.

Typical outputs under task_output/:

entities.json
kv_pairs.json
table_index.json
normalized.json
structured_record.json
requested_fields.json
requested_fields_record.json
traceability.json

`to-code`

Use when the user wants implementation-oriented output from the parse result.

Supported targets:

react
html-css
json-schema
jupyter-notebook

Typical outputs under task_output/:

component_map.json
field_schema.json
ui_blueprint.json
notes.md
traceability.json
target-specific artifacts such as app.jsx, index.html, styles.css, schema.json, notebook.ipynb, or notebook_plan.json

Treat all generated code and notebooks as drafts. Review them before running, publishing, or connecting them to real systems.

Published package scope

The published ClawHub bundle is intentionally CLI-first.

main workflow: scripts/run_skill.py
diagnostics: scripts/check_env.py
smoke verification: scripts/smoke_test.py

Developer-only local UI helpers are kept out of the public release bundle.

Pipeline rules

Always follow these rules:

Prefer local execution.
Always parse first into parsed.json.
Generate downstream artifacts from parsed.json, not raw OCR text alone.
Preserve page numbers, reading order, block types, and source anchors when possible.
Write traceability for downstream outputs.
Mark low-confidence regions or assumptions explicitly.
Do not silently drop tables, figures, formulas, charts, or key-value regions.
Save outputs into one artifact folder per run.
For confidential documents, prefer an explicit private --out directory and remove artifacts after review.

Output contract

Default output folder:

./artifacts/<document_stem>/

Expected top-level outputs:

effective_config.json
run_report.json
parsed.json
parsed.md
result_report.html
task_output/

to-code runs may also emit:

code_preview.html

CLI examples

Parse

python "{baseDir}/scripts/run_skill.py" \
  --mode parse \
  --file "/absolute/path/to/report.pdf" \
  --out "/absolute/path/to/artifacts/report_parse"

To-data

python "{baseDir}/scripts/run_skill.py" \
  --mode to-data \
  --file "/absolute/path/to/invoice.pdf" \
  --out "/absolute/path/to/artifacts/invoice_data" \
  --extract "tables,entities,kv_pairs"

To-data with custom fields

python "{baseDir}/scripts/run_skill.py" \
  --mode to-data \
  --file "/absolute/path/to/invoice.pdf" \
  --out "/absolute/path/to/artifacts/invoice_data" \
  --extract "tables,entities,kv_pairs" \
  --fields "invoice_number,invoice_date,total_amount,vendor_name"

To-code

python "{baseDir}/scripts/run_skill.py" \
  --mode to-code \
  --file "/absolute/path/to/ui_mockup.png" \
  --out "/absolute/path/to/artifacts/ui_code" \
  --target "react" \
  --title "Generated App"

To-code notebook target

python "{baseDir}/scripts/run_skill.py" \
  --mode to-code \
  --file "/absolute/path/to/architecture_diagram.png" \
  --out "/absolute/path/to/artifacts/notebook_code" \
  --target "jupyter-notebook" \
  --title "OpenVINO Notebook"

Slash-command examples

/skill local-document-ai-openvino parse file=./docs/report.pdf

/skill local-document-ai-openvino to-data file=./docs/invoice.pdf extract=tables,entities,kv_pairs

/skill local-document-ai-openvino to-data file=./docs/invoice.pdf extract=tables,entities,kv_pairs fields=invoice_number,invoice_date,total_amount,vendor_name

/skill local-document-ai-openvino to-code file=./mockups/architecture.png target=jupyter-notebook

Optional local demo UI

Start the local UI when the user wants an interactive demo page:

python "{baseDir}/scripts/serve_skill_ui.py"

The UI lets the user:

preview a local file
choose parse, to-data, or to-code
choose the to-code target
run the pipeline and inspect the generated local HTML reports

The bundled UI only allows preview/run access for local files under the skill directory and common user content folders such as Downloads, Documents, Desktop, and Pictures.

Failure behavior

If a run fails:

state which stage failed
do not claim outputs were created if they were not
prefer writing error.json with failure details
recommend parse first when the downstream request is ambiguous
surface stderr or a concise failure summary when available

Safety notes

Use a virtual environment for dependency installation.
Review and approve model downloads only when you explicitly intend to.
Keep outputs in a private local folder when documents are sensitive.
Review generated code and notebooks before execution.
Delete artifacts when they are no longer needed.
The wrapper always uses the bundled local scripts and the current Python interpreter. It does not allow custom interpreter or script-directory overrides.

Short reminder

Present this skill as a local document-understanding workflow with downstream actions and customizable field extraction, not as a plain OCR wrapper.