@hevmind/ask 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hevmind/ask",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "hev ask: a heading-anchored, agentic search overlay for Astro docs sites.",
   "keywords": [
@@ -28,11 +28,11 @@
     "ask": "./bin/ask.mjs"
   },
   "optionalDependencies": {
-    "@hevmind/ask-darwin-arm64": "0.3.1",
-    "@hevmind/ask-darwin-x64": "0.3.1",
-    "@hevmind/ask-linux-arm64": "0.3.1",
-    "@hevmind/ask-win32-x64": "0.3.1",
-    "@hevmind/ask-linux-x64": "0.3.1"
+    "@hevmind/ask-darwin-x64": "0.3.3",
+    "@hevmind/ask-darwin-arm64": "0.3.3",
+    "@hevmind/ask-linux-x64": "0.3.3",
+    "@hevmind/ask-win32-x64": "0.3.3",
+    "@hevmind/ask-linux-arm64": "0.3.3"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/search/loop.ts

@@ -485,36 +485,32 @@ async function* routedDigestAnswerLoop({
       const node = nodesById.get(candidate.id);
       if (node && !seen.has(node.id)) seen.set(node.id, node);
     }
-    if (seen.size && lastRole(messages) !== 'user') {
-      const sections = [...seen.values()].map((node) => openSectionResult(node, byId));
-      messages.push({ role: 'user', content: `Relevant sections:\n${JSON.stringify(sections)}` });
-    }
   }
 
-  // The answer is grounded in everything the model surfaced: sections it opened
-  // (full facts) ranked first, then the summaries from its searches. This lets it
-  // answer from search results without a separate open per section.
-  const grounded = new Map<string, DigestNode>([...opened, ...seen]);
-
-  if (lastRole(messages) === 'assistant') {
-    messages.push({
-      role: 'user',
-      content:
-        'Write the answer now, grounded in the sections from your search results and any you opened. Begin directly with the answer — no preamble. Do NOT say you will search, check, or look further: you cannot, and you already have the context you will get. If the sections do not cover the question, say so in one sentence. Link only to section urls you have seen.',
-    });
-  }
-
-  const sources = sourcesFromNodes(grounded, config.maxResults);
+  // Ground the answer in everything surfaced: opened sections (full facts) first,
+  // then searched summaries, capped to maxResults.
+  const grounded = [...new Map<string, DigestNode>([...opened, ...seen]).values()].slice(0, config.maxResults);
+  const sources = sourcesFromNodes(new Map(grounded.map((node) => [node.id, node])), config.maxResults);
   yield { type: 'sources', sources };
 
-  // Phase 2: streamed answer turn — no tools, so the model can only answer.
+  // Phase 2: a clean answer turn. Replaying the tool transcript keeps the model in
+  // "let me search more" mode (and it tries to call tools that no longer exist), so
+  // instead hand it just the question and the gathered sections — now it can only
+  // write the final prose answer.
+  const answerContext = grounded.map((node) => openSectionResult(node, byId));
+  const answerMessages: AnthropicMessage[] = [
+    {
+      role: 'user',
+      content: `Question: ${query}\n\nAnswer using only these documentation sections:\n${JSON.stringify(answerContext)}`,
+    },
+  ];
   for await (const event of tracedStream(
     stream,
     {
       apiKey,
       model: config.model,
-      system: answerSystem(system, sources),
-      messages,
+      system: routedAnswerSystemPrompt(digest),
+      messages: answerMessages,
       maxTokens: config.answerMaxTokens,
       signal,
     },
@@ -526,6 +522,27 @@ async function* routedDigestAnswerLoop({
   yield { type: 'done' };
 }
 
+/** Answer-only system prompt for the routed loop's final turn (no tools). */
+function routedAnswerSystemPrompt(digest: Digest): AnthropicTextBlock[] {
+  return [
+    {
+      type: 'text',
+      text: `You are the documentation assistant for this site. Write the answer to the user's question using ONLY the documentation sections provided in the next message. You have no tools — produce the final prose answer now.
+
+- Start IMMEDIATELY with the substance. Your first sentence must answer the question. Never open with "Based on…", "Here is…", "Sure", "Let me…", or any preamble or statement about searching, opening, or checking further.
+- Keep it tight: one or two short paragraphs, plus a short bullet list only if it genuinely helps. This renders in a small search popover, so do NOT use headings (#, ##) or horizontal rules (---).
+- For exact strings (flags, commands, identifiers, versions), quote a section's \`facts\` verbatim — never reword them.
+- Link to sections inline using their exact \`url\` from the provided sections, e.g. [autoscaling](/docs/concepts#kubernetes-autoscaling). Never invent a URL or anchor.
+- If the provided sections do not answer the question, say so plainly in one sentence and do not fabricate an answer.`,
+    },
+    {
+      type: 'text',
+      text: `<domain_context>\n${digest.context || ''}\n</domain_context>`,
+      cache_control: { type: 'ephemeral' },
+    },
+  ];
+}
+
 function sourcesFromNodes(opened: Map<string, DigestNode>, maxResults: number): Source[] {
   const sources: Source[] = [];
   const urls = new Set<string>();

package/src/search/prefilter.ts

@@ -11,6 +11,16 @@ export interface Candidate {
   snippet: string;
 }
 
+/** Grammatical/generic words that carry no topical signal in a docs query. */
+const STOPWORDS = new Set<string>([
+  'the', 'a', 'an', 'and', 'or', 'but', 'of', 'to', 'in', 'on', 'at', 'by', 'for', 'with', 'from', 'into', 'as',
+  'is', 'are', 'be', 'was', 'were', 'been', 'being', 'do', 'does', 'did', 'how', 'what', 'when', 'where', 'which',
+  'who', 'whom', 'why', 'can', 'could', 'should', 'would', 'shall', 'may', 'might', 'my', 'your', 'yours', 'you',
+  'i', 'it', 'its', 'this', 'that', 'these', 'those', 'there', 'here', 'we', 'our', 'us', 'me', 'if', 'then',
+  'else', 'not', 'no', 'so', 'than', 'too', 'very', 'just', 'also', 'only', 'out', 'about', 'up', 'set', 'get',
+  'use', 'using', 'used', 'via', 'want', 'need', 'make', 'have', 'has', 'will',
+]);
+
 /**
  * Distinctive tokens the digest carries for a section: its `terms`, the
  * tokens of its distilled `summary`, and the tokens of its verbatim `facts`. A
@@ -44,33 +54,52 @@ export function prefilter(
   perDocCap: number,
   nodes?: DigestNode[],
 ): Candidate[] {
-  const terms = expandQueryTerms(query, glossary);
-  if (!terms.length) return [];
+  const expanded = expandQueryTerms(query, glossary);
+  if (!expanded.length) return [];
+  // Drop grammatical/generic stopwords so a few ubiquitous words ("how", "set
+  // up", "with") don't dominate ranking. Fall back to the raw terms if the query
+  // is nothing but stopwords.
+  const filtered = expanded.filter((term) => term.length > 1 && !STOPWORDS.has(term));
+  const terms = filtered.length ? filtered : expanded;
 
   const signal = nodeSignal(nodes);
   // Inverse document frequency: down-weight terms common across the corpus
-  // (stopwords, ubiquitous words like "authentication" or "setup") so a rare,
-  // on-topic term ("oidc") dominates ranking. Without it, plain overlap buries
-  // the specific section under pages that merely share several common words —
-  // which degrades badly as the corpus grows (hundreds → thousands of sections).
+  // (ubiquitous words like "authentication") so a rare, on-topic term ("oidc")
+  // dominates. Without it, plain overlap buries the specific section under pages
+  // that merely share several common words — which degrades as the corpus grows.
   const df = new Map<string, number>();
-  for (const chunk of chunks) for (const token of chunk.tokens) df.set(token, (df.get(token) ?? 0) + 1);
+  let lengthSum = 0;
+  for (const chunk of chunks) {
+    lengthSum += chunk.tokens.size;
+    for (const token of chunk.tokens) df.set(token, (df.get(token) ?? 0) + 1);
+  }
   const total = chunks.length;
+  const avgLen = total ? lengthSum / total : 1;
   const weights = new Map(terms.map((term) => [term, Math.log(1 + total / (1 + (df.get(term) ?? 0)))]));
+  const b = 0.75; // BM25 length-normalization strength
 
   const scored = chunks
     .map((chunk) => {
       const boost = signal.get(chunk.id);
-      let score = 0;
+      // A query term in the section heading or page title is a strong topical
+      // signal — the page titled "OIDC Authentication" is what someone asking
+      // about "oidc" wants, far more than a page that merely mentions it.
+      const headingTokens = new Set([...tokenize(chunk.heading ?? ''), ...tokenize(chunk.docTitle ?? '')]);
+      let raw = 0;
       for (const term of terms) {
         const weight = weights.get(term) ?? 0;
-        if (chunk.tokens.has(term)) score += weight;
-        if (boost?.has(term)) score += weight;
+        if (chunk.tokens.has(term)) raw += weight;
+        if (boost?.has(term)) raw += weight;
+        if (headingTokens.has(term)) raw += weight * 3;
       }
-      return { chunk, score };
+      // Length-penalize (not -reward): a huge page (e.g. an autogenerated CLI flag
+      // dump that mentions nearly every term) is divided down, but short sections
+      // are not boosted — the floor at 1 avoids over-rewarding tiny reference stubs.
+      const norm = Math.max(1, 1 - b + (b * chunk.tokens.size) / (avgLen || 1));
+      return { chunk, score: raw / norm };
     })
     .filter((candidate) => candidate.score > 0)
-    .sort((a, b) => b.score - a.score || a.chunk.id.localeCompare(b.chunk.id));
+    .sort((a, b2) => b2.score - a.score || a.chunk.id.localeCompare(b2.chunk.id));
 
   const perDoc = new Map<string, number>();
   const capped = [];