diff --git a/README.md b/README.md index ec3b55f..59ed83c 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,53 @@ OPENWEBUI_KB_ID=your-knowledge-base-uuid-here This ensures PodX attaches documents consistently to the same Knowledge Base. +## Using podx-tools + +PodX includes a helper script `./scripts/podx-tools.sh` for interacting with OpenWebUI. + +### Common commands + +- **Check OpenWebUI connectivity** + ```bash + ./scripts/podx-tools.sh owui-health + ``` + Verifies that OpenWebUI is reachable at `$OPENWEBUI_URL`. + +- **List Knowledge Bases** + ```bash + ./scripts/podx-tools.sh owui-kbs + ``` + Lists available Knowledge Bases with their UUIDs. + +- **Resolve Knowledge Base ID by name** + ```bash + ./scripts/podx-tools.sh owui-kb-resolve "Homelab Library" + ``` + Resolves the fixed UUID for a KB by its human-readable name. + +- **Debug KB info** + ```bash + ./scripts/podx-tools.sh owui-kb-debug "Homelab Library" + ``` + +- **Attach a file** + ```bash + ./scripts/podx-tools.sh owui-attach "Homelab Library" /path/to/file.txt + ``` + Uploads a transcript or document to a KB. Supports `.txt`, `.md`, `.json`, and `.html`. + +- **List files in a KB** + ```bash + ./scripts/podx-tools.sh owui-kb-files "Homelab Library" + ``` + +### Notes + +- `OPENWEBUI_URL`, `OPENWEBUI_API_KEY`, and `OPENWEBUI_KB_ID` must be set in your `.env`. +- JSON files are optional. Only attach them if you want their contents searchable. +- Duplicate or empty content may be rejected by OpenWebUI with a `400` error. + + ## Troubleshooting ### Common errors and fixes