5eTools Linux RAG Bundle

This folder is a portable local RAG bundle for indexing a 5eTools-style JSON data folder and querying it locally through a browser UI.

What this bundle includes

• app.py - FastAPI app that can bootstrap Qdrant, ingest reference JSON, search, and chat
• setup_linux.sh - Linux setup script to create a venv, install Python dependencies, and print next steps
• run_local.sh - starts the local API and UI
• requirements.txt - Python packages to install
• PUT REFERENCES HERE/ - drop your reference JSON tree here
• ui/ - simple local browser UI for indexing and querying
• data/ - local runtime data and configuration files created by the app

Fresh Linux install requirements

Install these first on a fresh Debian/Ubuntu-style machine:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip curl ca-certificates

Install Ollama

curl -fsSL https://ollama.com/install.sh | sh
ollama serve

In another shell, pull the models used by default:

ollama pull embeddinggemma
ollama pull qwen3-coder:30b

If you want smaller models, you can change them later in config.json.

Install Qdrant

Simplest option, Docker:

docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant

If Docker is not installed, install it first or run Qdrant another way and update config.json.

Bundle setup

From inside this folder:

bash setup_linux.sh

That script will:

• create .venv
• install Python dependencies
• create runtime directories
• create a default config.json if missing

Add your references

Put your JSON reference tree inside:

• PUT REFERENCES HERE/

Example:

• PUT REFERENCES HERE/backgrounds.json
• PUT REFERENCES HERE/spells/spells-phb.json
• PUT REFERENCES HERE/bestiary/bestiary-mm.json

Run locally

bash run_local.sh

Then open:

• API docs: http://127.0.0.1:8000/docs
• Local UI: http://127.0.0.1:8000/ui

Typical first-time flow

1. Start Ollama
2. Start Qdrant
3. Run bash setup_linux.sh
4. Put your source JSON into PUT REFERENCES HERE/
5. Run bash run_local.sh
6. In the UI, click bootstrap if needed
7. In the UI, ingest the references folder
8. Search or chat locally

Notes

• This bundle does not modify your source JSON files.
• It indexes one vector per entity/object where possible.
• Large entities are split into child chunks for better retrieval.
• Oversized parent entities are kept as metadata records but are not separately embedded when children exist.