rst2kb

 ____  ____ _____ ____  _  ____
|  _ \/ ___|_   _|___ \| |/ / __ )
| |_) \___ \ | |   __) | ' /|  _ \
|  _ < ___) || |  / __/| . \| |_) |
|_| \_\____/ |_| |_____|_|\_\____/

Python utility to prepare .rst documentation for RAG in Open WebUI. It exports docs to .txt files with a manifest, and can optionally upload files to an existing Open WebUI Knowledge Base.

Documentation

• docs/README.md: documentation index
• docs/architecture.md: system architecture and data flow diagrams
• docs/operations.md: runbook for export/upload and validation
• docs/troubleshooting.md: common failures and fixes

Requirements

• Python 3.12+
• uv
• Open WebUI URL, API key, and Knowledge Base ID (only for upload mode)

Install

uv sync

Usage

Dry-run discovery:

uv run python rst2kb.py export --dry-run --source source --output /tmp/owui-rag

Export all RST files:

uv run python rst2kb.py export --source source --output /tmp/owui-rag

Export and keep raw RST copies:

uv run python rst2kb.py export --source source --output /tmp/owui-rag --copy-raw

Upload exported files to Open WebUI:

export OPENWEBUI_API_KEY="YOUR_API_KEY"
uv run python rst2kb.py upload \
  --output /tmp/owui-rag \
  --openwebui-url http://localhost:3000 \
  --knowledge-id YOUR_KNOWLEDGE_ID

Upload behavior notes

• Empty .txt files are skipped (reported with status: "skipped" and error: "empty text content").
• Duplicate content in the same upload batch is skipped to avoid duplicate-content API errors.
• Skipped files do not count as failed uploads.

Test

uv run python -m unittest -v rst2kb_test

Output

• OUT/txt/**/*.txt: exported text files
• OUT/raw/**/*.rst: optional raw copies when --copy-raw is used
• OUT/manifest.json: export summary and per-file details
• OUT/upload_report.json: upload results per file

Environment variables

• OPENWEBUI_API_KEY: bearer token used by upload mode

Known limits

• Upload mode does not create a Knowledge Base; it requires an existing --knowledge-id.
• Upload mode requires files to be processed by Open WebUI before attach and can take time for large datasets.

---

Disclaimer

This project was built using AI-assisted development ("vibe coding") with human oversight and review at each step. While the code has been tested and verified, you should review it before using in production environments.