ragflow-skill-python0418

SKILL.md

---
name: ragflow-dataset-ingest
description: "Use for RAGFlow dataset tasks: create, list, inspect, update, or delete datasets; upload, list, update, or delete documents; start or stop parsing; check parse status; retrieve chunks with `search.py`; and list configured models."
metadata:
  openclaw:
    requires:
      env:
        - RAGFLOW_API_URL
        - RAGFLOW_API_KEY
      bins:
        - python3
    primaryEnv: RAGFLOW_API_KEY
---

# RAGFlow Dataset And Retrieval

Use only the bundled scripts in `scripts/`.
Prefer `--json` so returned fields can be relayed exactly.
Follow `reference.md` for all user-facing output.

## Use This Skill When

- the user wants to create, list, inspect, update, or delete RAGFlow datasets
- the user wants to upload, list, update, or delete documents in a dataset
- the user wants to start parsing, stop parsing, or check parse progress
- the user wants to retrieve chunks from one or more datasets
- the user wants to list configured RAGFlow models

## Core Workflow

1. Resolve the target dataset or document IDs first.
2. Run the matching script from `scripts/`.
3. Use `--json` unless a script only needs a simple text response.
4. Return API fields exactly; do not guess missing details.

Common commands:

```bash
python3 scripts/datasets.py list --json
python3 scripts/datasets.py info DATASET_ID --json
python3 scripts/datasets.py create "Example Dataset" --description "Quarterly reports" --json
python3 scripts/update_dataset.py DATASET_ID --name "Updated Dataset" --json
python3 scripts/upload.py DATASET_ID /path/to/file.pdf --json
python3 scripts/upload.py list DATASET_ID --json
python3 scripts/update_document.py DATASET_ID DOC_ID --name "Updated Document" --json
python3 scripts/parse.py DATASET_ID DOC_ID1 [DOC_ID2 ...] --json
python3 scripts/stop_parse_documents.py DATASET_ID DOC_ID1 [DOC_ID2 ...] --json
python3 scripts/parse_status.py DATASET_ID --json
python3 scripts/search.py "query" --json
python3 scripts/search.py "query" DATASET_ID --json
python3 scripts/search.py --dataset-ids DATASET_ID1,DATASET_ID2 --doc-ids DOC_ID1,DOC_ID2 "query" --json
python3 scripts/search.py --retrieval-test --kb-id DATASET_ID "query" --json
python3 scripts/list_models.py --json
```

## Guardrails

- For any delete action, list the exact items first and require explicit user confirmation before executing.
- Delete only by explicit dataset IDs or document IDs. If the user gives names or fuzzy descriptions, resolve IDs first.
- Upload does not start parsing. Start parsing only when the user asks for it.
- `parse.py` returns immediately after the start request; use `parse_status.py` for progress.
- For progress requests, use `parse_status.py` on the most specific scope available:
  - dataset specified: inspect that dataset
  - document IDs specified: pass `--doc-ids`
  - no dataset specified: list datasets first, then aggregate status across datasets
- If a parse status result includes `progress_msg`, surface it directly. For `FAIL`, treat it as the primary error detail.
- Use `--retrieval-test` only for single-dataset debugging or when the user explicitly asks for that endpoint.

## Output Rules

- Follow `reference.md`.
- Use tables for 3+ items when possible.
- Preserve `api_error`, `error`, `message`, and related fields exactly as returned.
- Never fabricate progress percentages or inferred causes.