RAG Chunk Visualizer

An interactive Streamlit app that makes retrieval augmented generation (RAG) visible — inspect how documents become chunks, how chunks become vectors, and how retrieval selects the context that grounds an answer.

Live demo: https://huggingface.co/spaces/HitendraKawale/rag-chunk-visualizer

What it does

• Chunking — upload .txt/.md documents and explore how chunk size and overlap split them
• Embeddings — embed chunks locally with sentence-transformers and inspect the vectors
• Embedding map — project embeddings to 2D (PCA or UMAP) and click points to inspect chunks
• Vector search — store vectors in LanceDB and preview nearest-neighbor results
• Retrieval — run a query, see which chunks are retrieved and where the query lands on the map
• Grounded generation — build the grounded prompt and generate an answer with the LLM provider of your choice

Embeddings always run locally; only the final answer-generation step calls an LLM.

Supported LLM providers

Provider	API key env var	Default model
Ollama (local, default)	—	llama3.2:3b
Anthropic (Claude)	ANTHROPIC_API_KEY	claude-opus-4-8
OpenAI (GPT)	OPENAI_API_KEY	gpt-5-mini
Google (Gemini)	GOOGLE_API_KEY	gemini-2.5-flash
xAI (Grok)	XAI_API_KEY	grok-4

Pick the provider and model under Answer Generation in the sidebar. API keys can be pasted directly into the sidebar (kept only in the browser session, never written to disk or logs) or supplied via environment variables.

Quickstart

Requires Python 3.11.

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

streamlit run streamlit_app.py

For the local default provider, install Ollama and pull a model:

ollama pull llama3.2:3b

To use a cloud provider instead, copy .env.example to .env, set the key(s) you need, and optionally set LLM_PROVIDER to make it the default.

Configuration

All settings are environment variables (loaded from .env if present). The most useful ones:

Variable	Default	Purpose
LLM_PROVIDER	ollama	Default answer-generation provider (ollama, anthropic, openai, google, xai)
LLM_MAX_TOKENS	2048	Output token budget (reasoning models need headroom)
LLM_TIMEOUT_SECONDS	120	Per-request timeout for generation
EMBEDDING_MODEL	sentence-transformers/all-MiniLM-L6-v2	Local embedding model
EMBEDDING_DEVICE	cpu	cpu or mps
CHUNK_SIZE / CHUNK_OVERLAP	500 / 75	Default chunking parameters
TOP_K	5	Default retrieval depth
PROJECTION_METHOD	pca	pca or umap

See .env.example for the full list, including per-provider model overrides.

Deployment (Hugging Face Spaces)

The repo is Space-ready: the YAML frontmatter at the top of this README is the Space config and the Dockerfile drives the build (Python 3.11-slim, CPU-only torch, Streamlit on port 8501).

1. Create a Space at https://huggingface.co/new-space — SDK: Docker, free CPU hardware is enough.
2. Push this repo to the Space, or upload it with the hf CLI.
3. In Space Settings → Variables, set LLM_PROVIDER to a cloud provider (a deployed Space cannot reach a local Ollama server).
4. Optionally add an API key (e.g. GOOGLE_API_KEY) under Space Settings → Secrets — note that a server-side key is shared by every visitor and billed/quota'd to you. Without one, visitors paste their own key in the sidebar.

Uploaded documents and the LanceDB table live on the Space's ephemeral disk and reset on restart, which suits this app's demo/debugging purpose.

Development

ruff check .            # lint
ruff format .           # format
pytest -q               # tests
python scripts/smoke_check.py   # dependency + config sanity check

Project structure

rag-chunk-visualiser/
├── data/                       # runtime data (gitignored): documents, lancedb, exports
├── scripts/
│   └── smoke_check.py
├── src/rag_chunk_visualizer/
│   ├── app/                    # Streamlit layout and session state
│   ├── core/                   # settings (env-driven) and logging
│   ├── models/                 # chunk / document dataclasses
│   ├── services/
│   │   ├── chunking_service.py
│   │   ├── document_service.py
│   │   ├── embedding_service.py
│   │   ├── llm_providers.py    # provider registry + generation backends
│   │   ├── rag_service.py      # grounded prompt building + dispatch
│   │   └── retrieval_service.py
│   ├── storage/                # LanceDB read/write/search
│   └── visualization/          # 2D projection + plotly map
├── tests/
├── streamlit_app.py            # entry point
├── Dockerfile                  # Hugging Face Spaces / container deploys
├── requirements.txt            # pip deploy path (CPU torch + project install)
└── pyproject.toml              # dependencies and tooling config