Day 3 of Ask TanStack Query: the manual is now a stack of cards

You cannot hand an assistant a whole manual for every question. Each page has to be cut into small pieces, and each piece needs a way to be found later.

Today the program did that cut, turned every piece into a list of numbers that stand for its meaning, and stored the result. It is the step between the pile of docs from Day 2 and an assistant that can look things up.

The database is one table called chunks. Each row is one card: which page it came from, the title, the text, and 1,536 numbers that represent the meaning of that text.

A second copy of the text is kept for exact-word search, the way Cmd+F works. That part waits until a later day.

The table is locked. A public key in a browser cannot read it. Only the server, using a secret key, can.

The first cutter does not look for sentences or headings. It takes about 1,500 characters, then starts the next card 200 characters early so a sentence on the edge appears on both cards. That overlap is the only clever part.

def chunk_fixed(text, size=1500, overlap=200):
    if not text:
        return []
    chunks = []
    start = 0
    while True:
        chunks.append(text[start : start + size])
        if start + size >= len(text):
            break
        start += size - overlap
    return chunks

Starting this simple leaves a "before" version. Later, a smarter cutter can be measured against it.

Ten random cards were enough to see the problem.

One card from a page called InfiniteQueryObserverOptions begins ether errors should be thrown. The word was Whether. The cut landed in the middle of it.

Another, from TimeoutManager, begins meoutManager } from '@tanstack/query-core'. That is the middle of a code sample, not the start of an explanation.

The save worked. The cards are the messy part. A character count does not know where a word or a code block ends.

Day 3 was six commits.

• The table. sql/01_schema.sql creates chunks, turns on meaning search, and locks the table.
• The database library. Python can now talk to Supabase.
• Shared setup. app/clients.py holds the OpenAI client and the database client so every later script uses the same ones.
• The cutter. ingest/chunking.py slices each page into fixed-size cards.
• The save. ingest/embed.py cut 270 pages into 905 cards, asked OpenAI for the meaning-numbers 50 cards at a time, and stored them.
• The journal. Two bad cards are written down, so the next cutter has something to beat.

Next, a question goes in and an answer comes back from these cards, with the page it came from. The bad cuts stay in the journal until the cutter gets smarter.

Related: Day 2 of Ask TanStack Query: I went and got the books and the quiz