One question, step by step
Which artists blend hip hop with R&B, and what are some of their albums?
Every value below is real output from this run. Embeddings: openai/text-embedding-3-small. LLM: openai/gpt-5-mini. Both via OpenRouter.
Indexing
This happened earlier, when the Chroma collection was built, and ran for every artist. Here we follow the one chunk that ended up ranked #1 for this question (JAŸ-Z) back to the CSV row it came from.
1
Read the CSV row
The source data: one line of artists.csv, plus this artist’s rows in releases.csv.
51 rows in artists.csv100 release rows for JAŸ-Z
f82bcf78-5b69-4622-a5ef-73800768d9ac,JAŸ-Z,Person,US,US rapper,male,United States,pop; rap; hip-hop; hip hop; hiphop; pop rap; rapper; us; mashup; hip hop rnb and dance hall; united states; grammy winner; boom bap; east coast hip hop; hardcore hip hop; new york hip hop; luxury rap; relic inn; chipmunk soul,JAŸ‐Z; JAY‐Z; jay z; Jay‐Z; Jaÿ‐Z; JAY:Z; JAY Z; Shawn C Carter; Shawn Carter; S. Carter; Shawn Corey Carter; Jayz; Hova; Jay-Hova; Jigga; Jay Z; Jay - Z; Hova da God,1969-12-04,https://musicbrainz.org/artist/f82bcf78-5b69-4622-a5ef-73800768d9ac,2026-10-05T05:05:14.242906+00:00
2
Load it into a Document
A document loader turns each CSV row into a LangChain Document: pageContent (the text) and metadata (where it came from).
1 CSV row → 1 Document
const docs = await new CSVLoader('data/artists.csv').load();pageContent
artist_mbid: f82bcf78-5b69-4622-a5ef-73800768d9ac
artist_name: JAŸ-Z
artist_type: Person
country: US
disambiguation: US rapper
gender: male
area: United States
tags: pop; rap; hip-hop; hip hop; hiphop; pop rap; rapper; us; mashup; hip hop rnb and dance hall; united states; grammy winner; boom bap; east coast hip hop; hardcore hip hop; new york hip hop; luxury rap; relic inn; chipmunk soul
aliases: JAŸ‐Z; JAY‐Z; jay z; Jay‐Z; Jaÿ‐Z; JAY:Z; JAY Z; Shawn C Carter; Shawn Carter; S. Carter; Shawn Corey Carter; Jayz; Hova; Jay-Hova; Jigga; Jay Z; Jay - Z; Hova da God
begin_date: 1969-12-04
source_url: https://musicbrainz.org/artist/f82bcf78-5b69-4622-a5ef-73800768d9ac
collected_at: 2026-10-05T05:0… 17 more charactersmetadata
{
"source": "data/artists.csv",
"line": 32
}
3
Reshape into one profile per artist
Our own step: the artist row and all its release rows become one readable profile. Duplicate releases (same album, other countries or formats) are merged, keeping the earliest year.
1 artist row + 100 release rows → 1 Document of 2,133 chars
const profiles = await loadArtistDocuments(); // src/lib/pipeline.tspageContent
Artist: JAŸ-Z
Type: Person
Country: US (United States)
Description: US rapper
Active since: 1969-12-04
Tags: pop; rap; hip-hop; hip hop; hiphop; pop rap; rapper; us; mashup; hip hop rnb and dance hall; united states; grammy winner; boom bap; east coast hip hop; hardcore hip hop; new york hip hop; luxury rap; relic inn; chipmunk soul
Also known as: JAŸ‐Z; JAY‐Z; jay z; Jay‐Z; Jaÿ‐Z; JAY:Z; JAY Z; Shawn C Carter; Shawn Carter; S. Carter; Shawn Corey Carter; Jayz; Hova; Jay-Hova; Jigga; Jay Z; Jay - Z; Hova da God
Releases:
- In My Lifetime / I Can’t Get Wid Dat (1994)
- In My Lifetime (1995)
- Can’t Knock the Hustle (Fool's Paradise remix) (1996)
- Can’t Knock the Hustle (1996)
- Feelin’ It (1996)
- I’ll Be (1996)
- Can't Knock the Hustle (1996)
- Ain’t No Nigga (1996)
- Reasonable Doubt (1996)
- Dead Presidents (1996)
- Hustlers EP (1996)
- Ain't No Playa (1996)
- Time After Time / All of… 1,233 more charactersmetadata (kept on every chunk, usable as a filter)
{
"artist_mbid": "f82bcf78-5b69-4622-a5ef-73800768d9ac",
"artist_name": "JAŸ-Z",
"country": "US",
"gender": "male",
"artist_type": "Person",
"release_count": 53
}
4
Split into chunks
The splitter cuts the profile into pieces of at most 800 characters, breaking at line ends where it can. Each chunk repeats up to 100 characters from the end of the one before, so a sentence cut at a boundary still appears whole in one of them.
1 Document → 3 chunks
const splitter = new RecursiveCharacterTextSplitter({ chunkSize: 800, chunkOverlap: 100 });
const chunks = await splitDocuments(profiles); // splits, then adds the "(continued)" headerrepeated also starts the next chunk (overlap)header added by us, so the chunk still names its artist
f82bcf78-5b69-4622-a5ef-73800768d9ac-0777 charsArtist: JAŸ-Z Type: Person Country: US (United States) Description: US rapper Active since: 1969-12-04 Tags: pop; rap; hip-hop; hip hop; hiphop; pop rap; rapper; us; mashup; hip hop rnb and dance hall; united states; grammy winner; boom bap; east coast hip hop; hardcore hip hop; new york hip hop; luxury rap; relic inn; chipmunk soul Also known as: JAŸ‐Z; JAY‐Z; jay z; Jay‐Z; Jaÿ‐Z; JAY:Z; JAY Z; Shawn C Carter; Shawn Carter; S. Carter; Shawn Corey Carter; Jayz; Hova; Jay-Hova; Jigga; Jay Z; Jay - Z; Hova da God Releases: - In My Lifetime / I Can’t Get Wid Dat (1994) - In My Lifetime (1995) - Can’t Knock the Hustle (Fool's Paradise remix) (1996) - Can’t Knock the Hustle (1996) - Feelin’ It (1996) - I’ll Be (1996) - Can't Knock the Hustle (1996) - Ain’t No Nigga (1996)
f82bcf78-5b69-4622-a5ef-73800768d9ac-1815 charsranked #1 for this questionArtist: JAŸ-Z (continued) - Feelin’ It (1996) - I’ll Be (1996) - Can't Knock the Hustle (1996) - Ain’t No Nigga (1996) - Reasonable Doubt (1996) - Dead Presidents (1996) - Hustlers EP (1996) - Ain't No Playa (1996) - Time After Time / All of My Days (1996) - In My Lifetime, Vol. 1 (1997) - Rocafella Mixtape (1997) - Who You Wit (1997) - Sunshine (1997) - It's Alright / The Doe (1998) - Lobster & Scrimp (1998) - The City is Mine (1998) - Wishing on a Star (1998) - Vol. 2… Hard Knock Life (1998) - Can I Get a... (1998) - The City Is Mine (1998) - A Million and One Questions (1998) - Nigga What, Nigga Who (1998) - Vol. 2... Hard Knock Life (1998) - Be Alone No More (1998) - Hard Knock Life (Ghetto Anthem) (1998) - A Million And One Questions (Extended Mix) (1998) - Vol. 3… Life and Times of S. Carter (1999)
f82bcf78-5b69-4622-a5ef-73800768d9ac-2781 charsArtist: JAŸ-Z (continued) - A Million And One Questions (Extended Mix) (1998) - Vol. 3… Life and Times of S. Carter (1999) - Vol.3.. Life and Times of S. Carter (1999) - Can I Get a... (Def Jam's Rush Hour) (1999) - Jigga My N**** (1999) - Do It Again (Put Ya Hands Up) (1999) - Hard Knock Life (1999) - I Just Wanna Love U (Give It 2 Me) (2000) - Big Pimpin’ (2000) - Big Pimpin' (2000) - The Dynasty: Roc La Familia (2000) - Anything (2000) - The Blueprint (2001) - It's Obvious (2001) - Izzo (H.O.V.A.) (2001) - Unplugged (2001) - Girls, Girls, Girls (2001) - The Hits & Unreleased, Volume 1 (2001) - Guilty Until Proven Innocent (2001) - Izzo (H.O.V.A) (2001) - The Blueprint²: The Gift & The Curse (2002) - The Best of Both Worlds (2002) - Song Cry (2002) - Chapter One (2002)
5
Embed the chunk
The embedding model reads the chunk’s text and returns a fixed-length list of numbers. Texts with similar meaning get similar lists. No single number means anything on its own; the meaning is in the overall pattern.
815 chars → 1,536 numbersvector length 1.000
const vectors = await embeddings.embedDocuments(chunks.map((c) => c.pageContent));[-0.0040, -0.0462, -0.0215, -0.0170, 0.0368, -0.0212, -0.0304, 0.0430, … 1,528 more]
negativepositive· hover the strip to read a value
OpenAI’s vectors come out with length 1. For vectors of length 1, cosine similarity is just the dot product, which is what step 9 relies on.
6
Store it in Chroma
The vector store keeps each chunk’s vector next to its text and metadata, under a stable id. It’s saved to disk, so this whole indexing phase doesn’t run again until you reindex.
collection music-artists179 records in total
await vectorStore.addDocuments(chunks, { ids }); // ids like <artist_mbid>-<n>id
f82bcf78-5b69-4622-a5ef-73800768d9ac-1
embedding
1,536 numbers (step 5)
document
the chunk text (step 4)
metadata, as stored (Chroma flattens LangChain’s loc field)
{
"country": "US",
"release_count": 53,
"artist_mbid": "f82bcf78-5b69-4622-a5ef-73800768d9ac",
"gender": "male",
"locTo": 39,
"artist_type": "Person",
"locFrom": 13,
"artist_name": "JAŸ-Z"
}Query time
This ran just now, for this question.
7
The question
Plain text from the user. Nothing about it is matched by keywords: it is turned into a vector like the chunks were.
72 chars
Which artists blend hip hop with R&B, and what are some of their albums?
8
Embed the question
The same embedding model turns the question into the same kind of vector. It has to be the same model: vectors from different models aren’t comparable.
→ 1,536 numbers614 ms
const queryVector = await embeddings.embedQuery(question);[0.0102, -0.0255, -0.0082, 0.0204, 0.0001, -0.0665, 0.0214, 0.0692, … 1,528 more]
9
Search for the nearest chunks
Chroma compares the question vector with all 179 stored vectors and returns the closest ones. It reports cosine distance (1 − similarity), so lower is closer. Only the top 6 go on to the prompt.
179 vectors → top 69 ms
const results = await vectorStore.similaritySearchVectorWithScore(queryVector, 6);| # | Artist | Chunk | Distance | Similarity (1 − distance) |
|---|---|---|---|---|
| 1 | JAŸ-Z | discography | 0.584 | |
| 2 | JAŸ-Z | discography | 0.588 | |
| 3 | JAŸ-Z | profile | 0.619 | |
| 4 | Kendrick Lamar | discography | 0.639 | |
| 5 | Rihanna | discography | 0.651 | |
| 6 | Beyoncé | discography | 0.652 | |
| Cut-off: only the top 6 go into the prompt. These just missed: | ||||
| 7 | Drake | discography | 0.658 | |
| 8 | Drake | profile | 0.658 | |
| 9 | Kendrick Lamar | profile | 0.661 | |
| 10 | Rihanna | profile | 0.667 | |
Where #1’s score comes from
Multiply the two vectors number by number, then add up all 1,536 products. That sum is the cosine similarity. No single dimension decides it: the score is many small agreements (red) minus disagreements (blue).
[0.0102, -0.0255, -0.0082, 0.0204, 0.0001, -0.0665, 0.0214, 0.0692, … 1,528 more]
[-0.0040, -0.0462, -0.0215, -0.0170, 0.0368, -0.0212, -0.0304, 0.0430, … 1,528 more]
[-0.0000, 0.0012, 0.0002, -0.0003, 0.0000, 0.0014, -0.0007, 0.0030, … 1,528 more]
sum of products = 0.4162 = cosine similarity → Chroma’s distance = 1 − 0.4162 = 0.5838 (reported: 0.5839)
10
Fill the prompt
The 6 retrieved chunks are numbered and pasted into a fixed template, together with the question. This is everything the LLM will know about our data.
template + 6 chunks + question → 5,100 chars
const messages = await ragPrompt.formatMessages({ context: formatContext(docs), question });filled in the retrieved chunks; the rest is the fixed template
system message
You answer questions about music artists using only the context below. Each context block is a chunk of an artist profile from MusicBrainz. If the context doesn't contain the answer, say "I don't know based on the data." Name the artists you use, and don't add facts that aren't in the context. Context: [1] Artist: JAŸ-Z (continued) - Feelin’ It (1996) - I’ll Be (1996) - Can't Knock the Hustle (1996) - Ain’t No Nigga (1996) - Reasonable Doubt (1996) - Dead Presidents (1996) - Hustlers EP (1996) - Ain't No Playa (1996) - Time After Time / All of My Days (1996) - In My Lifetime, Vol. 1 (1997) - Rocafella Mixtape (1997) - Who You Wit (1997) - Sunshine (1997) - It's Alright / The Doe (1998) - Lobster & Scrimp (1998) - The City is Mine (1998) - Wishing on a Star (1998) - Vol. 2… Hard Knock Life (1998) - Can I Get a... (1998) - The City Is Mine (1998) - A Million and One Questions (1998) - Nigga What, Nigga Who (1998) - Vol. 2... Hard Knock Life (1998) - Be Alone No More (1998) - Hard Knock Life (Ghetto Anthem) (1998) - A Million And One Questions (Extended Mix) (1998) - Vol. 3… Life and Times of S. Carter (1999) [2] Artist: JAŸ-Z (continued) - A Million And One Questions (Extended Mix) (1998) - Vol. 3… Life and Times of S. Carter (1999) - Vol.3.. Life and Times of S. Carter (1999) - Can I Get a... (Def Jam's Rush Hour) (1999) - Jigga My N**** (1999) - Do It Again (Put Ya Hands Up) (1999) - Hard Knock Life (1999) - I Just Wanna Love U (Give It 2 Me) (2000) - Big Pimpin’ (2000) - Big Pimpin' (2000) - The Dynasty: Roc La Familia (2000) - Anything (2000) - The Blueprint (2001) - It's Obvious (2001) - Izzo (H.O.V.A.) (2001) - Unplugged (2001) - Girls, Girls, Girls (2001) - The Hits & Unreleased, Volume 1 (2001) - Guilty Until Proven Innocent (2001) - Izzo (H.O.V.A) (2001) - The Blueprint²: The Gift & The Curse (2002) - The Best of Both Worlds (2002) - Song Cry (2002) - Chapter One (2002) [3] Artist: JAŸ-Z Type: Person Country: US (United States) Description: US rapper Active since: 1969-12-04 Tags: pop; rap; hip-hop; hip hop; hiphop; pop rap; rapper; us; mashup; hip hop rnb and dance hall; united states; grammy winner; boom bap; east coast hip hop; hardcore hip hop; new york hip hop; luxury rap; relic inn; chipmunk soul Also known as: JAŸ‐Z; JAY‐Z; jay z; Jay‐Z; Jaÿ‐Z; JAY:Z; JAY Z; Shawn C Carter; Shawn Carter; S. Carter; Shawn Corey Carter; Jayz; Hova; Jay-Hova; Jigga; Jay Z; Jay - Z; Hova da God Releases: - In My Lifetime / I Can’t Get Wid Dat (1994) - In My Lifetime (1995) - Can’t Knock the Hustle (Fool's Paradise remix) (1996) - Can’t Knock the Hustle (1996) - Feelin’ It (1996) - I’ll Be (1996) - Can't Knock the Hustle (1996) - Ain’t No Nigga (1996) [4] Artist: Kendrick Lamar (continued) - Overly Dedicated (2010) - Look Out for Detox (2010) - She Needs Me (remix) (ringtone) (2010) - 6’7’ Freestyle (2010) - The Heart, Part 1 (2010) - Ronald Reagan Era (2011) - Section.80 (2011) - My People (2011) - Hood Gone Love It (2011) - Compton State of Mind (2011) - Rapper Shit (2011) - Vanity Slave, Pt. 2 (2011) - Sex With Society (2011) - HiiiPoWeR (2011) - Moscato (2011) - Hol’ Up (2011) - Swimming Pools (Drank) (2012) - ILLuminate (2012) - Westside, Right on Time (2012) - The Recipe (2012) - good kid, m.A.A.d city (2012) - Poetic Justice (2012) - Swimming Pools (Drank) (Remixes) (2012) - Cartoon & Cereal (2012) - Let Us Move On (prod. Jeff Bhasker and Plain Pat) (2012) - Let Us Move On (2012) - Fuckin’ Problems (2012) - Push Thru (2012) - Ever Heard of Section 80 (2012) [5] Artist: Rihanna (continued) - Pon de Replay (Dance Remixes) (2005) - Bring It Back (2005) - Music Of The Sun (2005) - The One (2005) - Pon De Replay (Dance Remixes) (2005) - Pon De Replay (2005) - We Ride (Club Mixes) (2006) - A Girl Like Me (2006) - We Ride (2006) - Unfaithful (2006) - S.O.S. (2006) - Break It Off (2006) - SOS (2006) - Unfaithful (Remix EP) (2006) - SOS (Remixes) (2006) - Unfaithful (Remixes) (2006) - S.O.S. (Mixes) (2006) - Roll It (2007) - Umbrella (2007) - Good Girl Gone Bad (2007) - Don’t Stop the Music: Remixes (2007) - Umbrella (Remixes) (2007) - Shut Up and Drive (2007) - Don't Stop the Music (2007) - Umbrella (Travis Barker Remix) (2007) [6] Artist: Beyoncé (continued) Country: US (United States) Active since: 1981-09-04 Tags: pop; rap; dance; house; american; vocalist; singer-songwriter; hip hop; hard rock; funk; country; bass; actress; soul; electropop; disco; rnb; pianist; americana; director; southern hip hop; icon; 2000s; dance-pop; adult contemporary; pop rock; pop rap; neo soul; progressive house; club; dancer; hip hop rnb and dance hall; hip hop soul; contemporary country; teen pop; pop soul; sxsw; top 100; grammy winner; r&b; singer/songwriter; contemporary r&b; 2010s; mbs-333; art pop; alternative r&b; moombahton; trap; slim thug; contemporary pop; future bass; top 10; texas rapper; 2020s; texas music; nuno; cultural icon; businesswoman; philanthropist; houston texas music; best female artist; top 5; best female emcee; best female rapper
user message
Which artists blend hip hop with R&B, and what are some of their albums?
11
Call the LLM
The model reads the prompt and generates an answer, token by token. It has no access to Chroma or the CSVs, only to the text in step 10.
openai/gpt-5-mini
const response = await model.invoke(messages);8.9 sresponse time
1,721input tokens
1,030output tokens
832of those spent reasoning (not shown)
12
The answer
Check it against step 9: everything it says should come from the chunks that were retrieved.
468 chars
Artists used: JAŸ-Z; Beyoncé - JAŸ-Z — tagged with "hip hop rnb and dance hall" in the data. Some of his releases listed in the context: Reasonable Doubt (1996); Vol. 2… Hard Knock Life (1998); Vol. 3… Life and Times of S. Carter (1999); The Dynasty: Roc La Familia (2000); The Blueprint (2001); The Blueprint²: The Gift & The Curse (2002). - Beyoncé — tagged with "hip hop rnb and dance hall" in the data. I don't know based on the data which of her albums to list.