Frame the article embedding search experiment

Success is not “I followed the tutorial.” Success is producing evidence that: query embedding + article embeddings produce a stable top-1 for the fixture question. The accepted input is narrow on purpose: article texts, embedding function (fake or API), query string. That narrowness is what lets you inspect every field and prevents a toy demo from being narrated as a production system.

Record the baseline you must beat: keyword overlap ranking on the same articles. If the finished artifact cannot beat that baseline on the fixture below, stop and revise the claim before writing more code.

export const acceptance = {
  project: "a semantic-search service that embeds support articles and ranks them with cosine similarity",
  invariant: "index and query vectors use the same model and dimension",
  expected: "The query \u201creset password\u201d returns the password-reset article first with a finite score.",
} as const;

Expected evidence: The query “reset password” returns the password-reset article first with a finite score.. Treat the printout as a claim about this fixture, not as proof that the toolchain merely started.

For the semantic search over support articles, a decorative win often looks like a clean run that never checks top-1 article id match on gold queries; similarity in (-1,1). Write the metric down now so later pages cannot redefine success after the fact. Also note the operational threat you will eventually gate on: sending confidential article bodies to a third-party embed API without review.

For embedding-api-lab, write the claim on a sticky note in this exact shape: “Given article texts, embedding function (fake or API), query string, the article embedding search will …”. Fill the ellipsis with the observable part of: query embedding + article embeddings produce a stable top-1 for the fixture question. Tape the baseline beside it: keyword overlap ranking on the same articles. If someone later replaces your metric with a vibe check, the sticky note is how you push back.

Also sketch the one-sentence user story: a person uses this output to rank articles by cosine similarity to an embedded query. If that sentence needs a dashboard, a model zoo, or five services, the lab scope is too wide—shrink the fixture (three short support articles + one gold query) until the story fits on one screen.

Decide now whether live network calls are allowed on page 1. For this lab they usually are not; inventory and contracts should run offline against three short support articles + one gold query. Note the metric you will eventually require (top-1 article id match on gold queries; similarity in [-1,1]) so page 4 cannot invent a softer target. The characteristic failure to keep in mind is comparing raw tokens without vectors, or dimension mismatch.

At the experiment brief stage for embedding-api-lab, the job is narrower than finishing a product demo. You are creating one progressive evidence piece about three short support articles + one gold query that later pages inherit without redefining success. Keep that fixture small enough to inspect by hand, keep outputs copy-pasteable as text, and refuse to narrate this baseline as if it were a production SLA: keyword overlap ranking on the same articles.

For this page specifically, success looks like a falsifiable claim and baseline written before coding while still centering the user decision to rank articles by cosine similarity to an embedded query. If you cannot point to a file, command, or assertion that proves that for the article embedding search, stay on this page instead of advancing.

Glossary: tool · Glossary: structured output · Cheatsheet: production ops signals

Next