I Built a TUI to Visualize RAG Chunking because chunk_size=1000 is a Lie 📉

#rag #python #machinelearning #opensource

Let’s be honest for a second. When you are building a RAG (Retrieval-Augmented Generation) pipeline, how do you pick your chunk_size and overlap?

If you are like 90% of us, you copy-paste 1000 and 200 from a tutorial, run it, and hope the LLM doesn't hallucinate.

I realized I was doing "vibes-based engineering". I had no idea if my chunks were cutting sentences in half, if my overlap was actually preserving context, or if my retrieval was failing because of the embedding model or the chunking strategy.

So, I spent my nights and weekends building a tool to fix it.

Meet RAG-TUI.

It is an open-source, terminal-based visual debugger for RAG pipelines. It helps you see what your splitters are doing before you index millions of documents.

The Problem: "The Black Box"

We treat text splitters like black boxes. You feed in a PDF, and out comes a list of strings. But what do those strings look like?

Did you just cut a critical definition in half?
Is your 10% overlap actually capturing the previous sentence?
Are you feeding your embedding model garbage?

I got tired of printing chunks to the console to debug this. I wanted a UI, but I didn't want to leave my terminal.

The Solution: RAG-TUI

RAG-TUI is a lightweight CLI tool built in Python. You point it at a file, and it gives you an interactive dashboard to tune your indexing strategy in real-time.

Key Features (Why you might want this)

1. Real-time Visualization 🎨
Drag a slider to change the chunk_size. Watch the text re-chunk instantly.
The UI uses color-coded cards to show you exactly where one chunk ends and the next begins.

2. Quality Indicators 🚦
I added visual "linters" for your chunks:

🟢 Green: Clean break (ends with ., !, ?).
🟡 Yellow: Mid-phrase break (ends with ,, :).
🔴 Red: Hard cut (ends with a character).
⚠️ Warning: Chunk is too small (<50 tokens) or too large.

3. "Scientific" Batch Testing
Stop guessing. Enter 20 test queries ("What is the refund policy?", "How do I reset my password?"). RAG-TUI runs them against your current settings using local vector search and calculates a Hit Rate.

Hit Rate > 80%? Ship it.
Hit Rate < 60%? Your chunks are wrong. Change the strategy.

4. Privacy First (Ollama Support) 🔒
You don't need to send your private docs to OpenAI just to debug a splitter. RAG-TUI has native support for Ollama. You can run the entire debugging loop offline on your laptop.

💻 Under the Hood

For the Python nerds (like me), here is the stack that makes this possible:

UI: Textual (The best TUI framework, period).
Chunking: Chonkie (Blazing fast token splitting).
Vector DB: Usearch (Lightweight, in-memory vector search).
LLM: Async wrapper for Ollama/OpenAI.

🚀 How to Try It

I tried to make the onboarding as painless as possible.

pip install rag-tui

Then, just run:

rag-tui

(Make sure you have ollama serve running if you want to test embeddings!)

🤝 I Need Your Feedback!

This is currently in v0.0.2 Beta. It works, but I know there are edge cases I haven't found yet.

I am building this in public because I believe RAG tooling needs to get better. If you are learning RAG or building a production pipeline, please give this a spin.