Configuration

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

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

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

Options

Choosing a provider

provider selects who serves both the runtime loop and the offline digest build. The search behavior, digest format, and endpoint contract are identical across providers — only the model and the key env var change.

// astro.config.mjs — the default; reads ANTHROPIC_API_KEY
hevAsk({
  collections: ["docs"],
  // model defaults to claude-haiku-4-5
});

// astro.config.mjs — reads OPENAI_API_KEY
hevAsk({
  collections: ["docs"],
  provider: "openai",
  // model defaults to gpt-4.1-mini
});

// astro.config.mjs — reads OPENROUTER_API_KEY
hevAsk({
  collections: ["docs"],
  provider: "openrouter",
  model: "anthropic/claude-haiku-4.5", // or any OpenRouter model slug
});

OpenRouter is the widest door: one OPENROUTER_API_KEY reaches every model it routes. providerBaseUrl opens the rest — any OpenAI-compatible Chat Completions endpoint works with provider: "openai":

hevAsk({
  collections: ["docs"],
  provider: "openai",
  providerBaseUrl: "https://my-gateway.example.com/v1",
  model: "my-model",
});

Models in the agentic loop must support tool calling; the digest builder also needs forced tool choice. Current models from the major providers all qualify.

What the integration does

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

• injects the endpoint route, pointing at @hevmind/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/digest (the committed tree, globbed in);
• adds the digestDir tree as watched files so dev reloads when the digest changes;
• warns if collections is empty.

At build (astro:build:start) it runs the digest build when the provider’s key (ANTHROPIC_API_KEY by default) 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 "@hevmind/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.