query.js

/**
 * WHAT THIS FILE DOES
 *
 * The query pipeline — the "R" and the "G" in RAG.
 *
 *   question -> vector -> find 5 nearest chunks -> send them to the LLM
 *
 * Retrieval (R) happens in SQL: pgvector compares the question's vector to
 * every stored chunk vector and returns the closest ones. Generation (G) is the
 * LLM writing an answer from ONLY those chunks — which is what keeps the answer
 * grounded in your documents instead of the model's general knowledge.
 *
 * See docs/04-code-walkthrough.md for a line-by-line explanation.
 *
 * @author  Raqibul Hasan Moon <rhmoon21@gmail.com>
 * @created 2026-08-12
 */

const { pool } = require("./db");
const { embedText, generateAnswer } = require("./embeddings");

/*
The <=> operator is pgvector's cosine distance. Semantically similar text produces vectors that point in the same direction — so the distance between them is small. Flip that with 1 - distance and you get a similarity score, where anything close to 1 means a strong match.

I found 0.7 to be a reliable threshold in my testing — chunks above that were almost always relevant. Anything below 0.5 and the retrieval was really stretching, pulling chunks that shared a keyword or two but weren't actually answering the question.

When that happens, the system prompt instruction ("if the context does not contain enough information, say so clearly") becomes important. A well-behaved model will tell the user it doesn't know rather than guess.

We also surface the source filename. Once you've ingested more than one document, users need to know whether that answer came from the architecture spec or the incident report.
*/

async function queryDocuments(question) {
  // The question is embedded with the same model used at ingest time. This is
  // not optional — vectors from two different models live in unrelated
  // coordinate spaces, so comparing across them yields meaningless distances.
  const questionEmbedding = await embedText(question);

  // How this query works:
  //
  //   embedding <=> $1  -> cosine DISTANCE (0 = identical, 2 = opposite)
  //   1 - (that)        -> cosine SIMILARITY, the human-friendly 0..1 score
  //
  // ORDER BY uses the raw distance, ascending, because "closest first" is
  // literally smallest distance first. We order by the distance rather than by
  // the derived `similarity` alias so the expression stays in the form a
  // pgvector index can serve; ordering by 1 - distance inverts the direction
  // and prevents the index from being used.
  //
  // Note there is no similarity threshold in SQL: we always take the best 5
  // and let the model judge. The system prompt in generateAnswer() instructs it
  // to admit when the context is insufficient, which handles weak matches more
  // gracefully than returning nothing at all.
  const { rows } = await pool.query(
    `SELECT content, source,
            1 - (embedding <=> $1::vector) AS similarity
     FROM documents
     ORDER BY embedding <=> $1::vector
     LIMIT 5`,
    [JSON.stringify(questionEmbedding)],
  );

  if (rows.length === 0) {
    return { answer: "No relevant documents found.", sources: [] };
  }

  const context = rows.map((r) => r.content).join("\n\n---\n\n");
  const answer = await generateAnswer(context, question);

  return {
    answer,
    sources: [...new Set(rows.map((r) => r.source))],
    topSimilarity: parseFloat(rows[0].similarity).toFixed(3),
  };
}

module.exports = { queryDocuments };