A plain-language tour of the ideas behind RAG Jazz — written so a recruiter,
a curious musician, or anyone new to AI can follow along.
The big picture
Most chatbots answer from whatever they memorized during training.
That can sound confident and still be wrong — especially on niche topics
like jazz harmony.
RAG Jazz works differently. It keeps a small, curated library
of jazz-piano theory pages. When you ask a question, it first
looks up the most relevant passages from that library, then asks
an AI to explain those passages in friendly language — with citations.
Think of it like an open-book test: the model is allowed to answer, but
only while looking at the pages it just pulled from the book.
What is RAG?
RAG stands for Retrieval-Augmented Generation.
Three words, three steps:
Retrieval — find relevant text in a knowledge base.
Augmented — attach that text to the user’s question.
Generation — have a language model write an answer from it.
Why bother? Because retrieval keeps answers
grounded in sources you chose, instead of pure guessing.
If the library doesn’t cover a topic, the system can say so instead of
inventing a fake music-theory fact.
Embeddings & “hundreds of dimensions”
Computers don’t “understand” sentences the way people do. To compare meaning,
we convert each passage into a long list of numbers called an
embedding (or vector).
In this project, each chunk becomes a vector with
384 numbers (often called 384 dimensions), using a model named
all-MiniLM-L6-v2. Rough analogy:
A GPS point needs 2 numbers (latitude, longitude).
A point in a room needs 3 (x, y, z).
A “meaning point” here needs 384 — far too many to draw literally,
but excellent for measuring sameness of ideas.
Passages about similar ideas land near each other in that high-dimensional space.
“Tritone substitution” and “altered dominant” end up closer than
“tritone substitution” and “walking bass,” even if they share few exact words.
Cosine similarity (how “near” is measured)
Once everything is a vector, we need a score for “how related is A to B?”
This app uses cosine similarity.
Imagine two arrows starting from the same origin. Cosine similarity cares about
the angle between them, not how long they are:
Same direction → similarity near 1 (very related).
Right angle → near 0 (unrelated).
Opposite directions → near −1 (rare in this setup).
When you ask a question, your question is also turned into a 384-number vector.
The system finds the library chunks whose vectors point most the same way —
those become the “matching passages,” and the UI shows the score as a percentage.
Important: retrieval happens in the full 384-d space. The colorful 3D map is only
a sketch for humans.
The 3D map (PCA) — and what it is not
Humans can’t see 384 dimensions. So this site compresses the library into
3 dimensions with a method called
PCA (Principal Component Analysis).
PCA finds the “most informative camera angles” on the data — directions where
the points vary a lot — and projects everything into a 3D view you can orbit.
Colors group points by Wikipedia article.
That map is great for intuition (“these topics cluster over here”). It is
not a perfect picture of cosine neighbors. A chunk can be a
top match for your question in 384-d and still look far away on the PCA map.
That’s expected geometry, not a bug.
Click any sphere after asking a question to see its article, section, and
real cosine score versus your query.
This project’s specific pipeline
Here’s the concrete recipe behind RAG Jazz:
1. Knowledge base
~39 curated Wikipedia articles focused on jazz piano theory
(harmony, scales, voicings, progressions, foundations).
Chosen to be useful from beginner ideas (intervals, triads) through advanced
ones (Coltrane changes, upper structures) — without dumping unrelated mega-articles.
2. Chunking
Articles are split into short passages of about 650 characters,
with 50 characters of overlap so ideas aren’t cut awkwardly at boundaries.
That produced roughly 800+ chunks, each tagged with article title,
section, and source URL.
Leading leftover punctuation from splits is cleaned so passages read naturally.
3. Indexing
Each chunk is embedded with MiniLM (384-d) and stored in
ChromaDB, configured for cosine distance.
A PCA projection of those embeddings is precomputed for the interactive 3D map.
4. Answering
The app retrieves the top matches (default 5), with light
diversification so you don’t get five near-identical snippets from one section.
Those passages are sent to a free-tier language model on
Groq (default model: openai/gpt-oss-20b) with
instructions to answer like a friendly teacher and cite sources.
If the model is unavailable or rate-limited, you still get the retrieved passages —
the lookup step still works at $0.
What happens when you click Ask
Your question is embedded into the same 384-d space as the library.
Cosine similarity ranks the closest chunks.
A short shortlist (diversified) becomes the open-book context.
The language model writes a grounded answer with light citations.
The 3D map places your query and highlights those neighbors; click points
to inspect titles, sections, and cosine scores.
That’s the whole loop: search by meaning → read the sources → explain clearly.