Configuration

The hevAsk() integration is the default export of @hev/ask. It takes one options object. Only collections is effectively required; everything else has a default.

// astro.config.mjs
import hevAsk from "@hev/ask";

export default defineConfig({
  integrations: [
    hevAsk({
      collections: ["docs"],
      basePath: "/docs/",
      model: "claude-haiku-4-5",
      maxResults: 6,
    }),
  ],
});

Options

Option	Type	Default	Description
collections	string[]	—	Content collection name(s) to index and search. Without it the endpoint errors and the integration warns at build.
basePath	string	'/docs/'	Slug → URL prefix. A doc’s URL is basePath + slug, plus #anchor for a section.
endpoint	string	'/api/ask'	Route the search endpoint is injected at. Must match the overlay’s endpoint prop if you change it.
model	string	'claude-haiku-4-5'	Claude model for the agentic search loop.
kgModel	string	'claude-opus-4-8'	Model for the offline knowledge-graph builder.
maxResults	number	6	Source sections the AI answer may ground in and cite (the Sources footer size); also the keyword result row cap.
answerMaxTokens	number	1024	Token budget for the streamed AI answer.
maxIterations	number	4	Maximum search tool rounds before the model must stop searching and answer.
chunkHeadingDepth	number	3	Deepest heading used as a chunk boundary. 2 = ##; 3 = ## and ###.
candidatePerSearch	number	8	Chunks returned by each search tool call.
perDocCap	number	2	Max chunks from one document returned by a single prefilter call.
kgPath	string	'.hev-ask/kg.json'	Path to the committed knowledge-graph artifact, relative to the site root.
kgContentGlobs	string[]	derived	Globs the offline builder reads. Defaults to Markdown/MDX under each configured collection directory.

What the integration does

When Astro starts up (astro:config:setup) the integration:

• injects the endpoint route, pointing at @hev/ask/endpoint, with prerender: false so it renders on demand;
• registers two virtual modules — virtual:hev-ask/config (the resolved options) and virtual:hev-ask/kg (the committed knowledge graph, inlined);
• adds kgPath as a watched file so dev reloads when the graph changes;
• warns if collections is empty.

At build (astro:build:start) it runs the knowledge-graph build when ANTHROPIC_API_KEY is present (hash-gated, usually a no-op), and otherwise logs a warning and proceeds with the committed artifact. The build never fails for lack of a key.

TypeScript

The options type is exported for editor help and config typing:

import type { HevAskOptions } from "@hev/ask";

Tuning notes

• Chunk granularity: raise chunkHeadingDepth to 3 (the default) for finer section anchors on long pages; drop to 2 if your ### sections are too small to stand alone as results.
• Latency: lower maxIterations to cap agentic round-trips; raise it if multi-part questions need more search rounds.
• Result spread: perDocCap keeps one long page from filling the results; raise it if a single page legitimately holds most of the answers.
• Recall vs. noise: candidatePerSearch controls how many chunks each search hands the model — more candidates, more recall, more tokens.