@hevmind/ask 0.1.0

package/src/endpoint.ts

@@ -0,0 +1,247 @@
+import type { APIRoute } from 'astro';
+import config from 'virtual:hev-ask/config';
+import digest from 'virtual:hev-ask/digest';
+import {
+  decodePathValue,
+  getGlossaryEntry,
+  getOverview,
+  getSection,
+  listGlossary,
+  listSectionSummaries,
+} from './digest/read.ts';
+import { makeTelemetry, telemetryFromEnv } from './observability';
+import { hashableChunkText } from './search/chunk';
+import { buildIndex, prefilter, type Candidate, type Chunk } from './search/index';
+import { runAgenticAnswerLoop, type AgenticEvent } from './search/loop';
+
+export const prerender = false;
+
+let indexPromise: Promise<Chunk[]> | null = null;
+let staleWarningIssued = false;
+
+function getIndex(): Promise<Chunk[]> {
+  if (!indexPromise) indexPromise = buildIndex(config.collections, config.basePath, config.chunkHeadingDepth);
+  return indexPromise;
+}
+
+// Merge the runtime environments the endpoint may run under: Cloudflare's
+// per-request `locals.runtime.env` wins over `process.env` (Node adapters),
+// which wins over build-time `import.meta.env`.
+function resolveEnv(locals: unknown): Record<string, string | undefined> {
+  const fromRuntime = (locals as { runtime?: { env?: Record<string, string> } })?.runtime?.env ?? {};
+  const fromProcess = (typeof process !== 'undefined' ? process.env : undefined) ?? {};
+  const fromImportMeta = (import.meta as { env?: Record<string, string> }).env ?? {};
+  return { ...fromImportMeta, ...fromProcess, ...fromRuntime };
+}
+
+function resolveApiKey(locals: unknown): string | undefined {
+  return resolveEnv(locals).ANTHROPIC_API_KEY;
+}
+
+// PostHog LLM tracing for the answer loop. On Cloudflare, capture promises
+// must be handed to `ctx.waitUntil` or they are cancelled when the SSE stream
+// closes. No POSTHOG_KEY in the environment → no-op sink.
+function resolveTelemetry(locals: unknown) {
+  const ctx = (locals as { runtime?: { ctx?: { waitUntil?: (promise: Promise<unknown>) => void } } })
+    ?.runtime?.ctx;
+  const waitUntil = ctx?.waitUntil ? (promise: Promise<unknown>) => ctx.waitUntil!(promise) : undefined;
+  return makeTelemetry(telemetryFromEnv(resolveEnv(locals), { waitUntil }));
+}
+
+// The overlay fetches suggested questions from the base route. Sub-routes expose
+// keyless reads over the committed digest for CLI, MCP, and generated clients.
+export const GET: APIRoute = ({ params, request }) => {
+  const resource = resourceSegments(params.resource);
+  if (!resource.length) return json({ suggestions: digest.suggestions ?? [], model: config.model });
+  return readResource(resource, request);
+};
+
+export const POST: APIRoute = async ({ request, locals, params }) => {
+  if (resourceSegments(params.resource).length) return notFound();
+
+  let query: string | undefined;
+  let mode: string | undefined;
+  try {
+    ({ query, mode } = await request.json());
+  } catch {
+    return json({ error: 'Invalid JSON body.' }, 400);
+  }
+  if (!query || !query.trim()) return json({ results: [], query: '', model: config.model, mode: 'keyword' });
+
+  let chunks: Chunk[];
+  try {
+    chunks = await getIndex();
+    void warnIfStale(chunks);
+  } catch (err) {
+    return json({ error: (err as Error).message }, 500);
+  }
+
+  const keywordCandidates = prefilter(
+    chunks,
+    query,
+    digest.glossary,
+    Math.max(config.maxResults, config.candidatePerSearch),
+    config.perDocCap,
+    digest.nodes,
+  );
+
+  const apiKey = resolveApiKey(locals);
+  const keywordResults = () =>
+    toResults(keywordCandidates, new Map(chunks.map((chunk) => [chunk.id, chunk])), config.maxResults);
+
+  if (mode === 'agentic' && !apiKey) {
+    return json({
+      results: keywordResults(),
+      query,
+      model: config.model,
+      mode: 'keyword',
+      warning: 'AI search is unavailable because ANTHROPIC_API_KEY is not configured.',
+    });
+  }
+
+  if (mode === 'keyword' || !apiKey) {
+    return json({
+      results: keywordResults(),
+      query,
+      model: config.model,
+      mode: 'keyword',
+    });
+  }
+
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const send = (event: string, data: unknown) => {
+        controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+      };
+      try {
+        for await (const ev of runAgenticAnswerLoop({
+          apiKey,
+          query: query as string,
+          chunks,
+          digest,
+          telemetry: resolveTelemetry(locals),
+          config: {
+            model: config.model,
+            maxIterations: config.maxIterations,
+            candidatePerSearch: config.candidatePerSearch,
+            perDocCap: config.perDocCap,
+            maxResults: config.maxResults,
+            answerMaxTokens: config.answerMaxTokens,
+          },
+          signal: request.signal,
+        })) {
+          if (request.signal.aborted) break;
+          forward(send, ev, config.model);
+        }
+      } catch (err) {
+        // The HTTP status is already committed once streaming starts, so surface
+        // failures as an SSE error event rather than a status change.
+        send('error', { error: (err as Error).message });
+      } finally {
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache, no-transform',
+      connection: 'keep-alive',
+    },
+  });
+};
+
+function readResource(resource: string[], request: Request): Response {
+  const [rawRoot, ...rest] = resource;
+  const root = decodePathValue(rawRoot).trim();
+
+  if (root === 'glossary') {
+    if (!rest.length) return json({ terms: listGlossary(digest) });
+    const entry = getGlossaryEntry(digest, rest.join('/'));
+    return entry ? json(entry) : notFound('No glossary entry matched that term or alias.');
+  }
+
+  if (root === 'sections') {
+    if (!rest.length) {
+      const group = new URL(request.url).searchParams.get('group');
+      return json({ sections: listSectionSummaries(digest, group) });
+    }
+    const node = getSection(digest, rest.join('/'));
+    return node ? json(node) : notFound('No section matched that id.');
+  }
+
+  if (root === 'overview' && rest.length === 0) return json(getOverview(digest));
+
+  return notFound();
+}
+
+function resourceSegments(value: string | undefined): string[] {
+  return (value ?? '')
+    .split('/')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function forward(send: (event: string, data: unknown) => void, ev: AgenticEvent, model: string): void {
+  if (ev.type === 'sources') send('sources', { sources: ev.sources, model, mode: 'agentic' });
+  else if (ev.type === 'token') send('token', { text: ev.text });
+  else if (ev.type === 'search') send('search', { query: ev.query });
+  else if (ev.type === 'done') send('done', {});
+}
+
+interface KeywordResult {
+  title: string;
+  heading?: string;
+  url: string;
+  group?: string;
+  snippet: string;
+}
+
+function toResults(candidates: Candidate[], byId: Map<string, Chunk>, maxResults: number): KeywordResult[] {
+  return candidates
+    .map((candidate) => {
+      const chunk = byId.get(candidate.id);
+      return chunk ? chunkToResult(chunk, candidate.snippet) : null;
+    })
+    .filter((result): result is KeywordResult => result !== null)
+    .slice(0, maxResults);
+}
+
+function chunkToResult(chunk: Chunk, snippet: string): KeywordResult {
+  return {
+    title: chunk.docTitle,
+    heading: chunk.heading,
+    url: chunk.url,
+    group: chunk.group,
+    snippet,
+  };
+}
+
+async function warnIfStale(chunks: Chunk[]) {
+  if (staleWarningIssued || !digest.contentHash || typeof crypto === 'undefined' || !crypto.subtle) return;
+  staleWarningIssued = true;
+  const hash = await sha256Hex(hashableChunkText(chunks)).catch(() => '');
+  if (hash && hash !== digest.contentHash) {
+    console.warn('[hev-ask] Digest content hash is stale; run `ask digest build` to refresh it.');
+  }
+}
+
+async function sha256Hex(text: string): Promise<string> {
+  const data = new TextEncoder().encode(text);
+  const digest = await crypto.subtle.digest('SHA-256', data);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function notFound(error = 'Not found.'): Response {
+  return json({ error }, 404);
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { default } from './integration';
+export type { HevAskOptions } from './types';

package/src/integration.ts

@@ -0,0 +1,146 @@
+import type { AstroIntegration } from 'astro';
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { EMPTY_DIGEST, normalizeDigest } from './digest/schema';
+import type { HevAskOptions, ResolvedConfig } from './types';
+
+const CONFIG_VIRTUAL_ID = 'virtual:hev-ask/config';
+const DIGEST_VIRTUAL_ID = 'virtual:hev-ask/digest';
+const execFileAsync = promisify(execFile);
+
+/**
+ * Astro integration that mounts the hev ask endpoint and exposes resolved
+ * configuration plus the committed ask digest through virtual modules.
+ */
+export default function hevAsk(options: HevAskOptions = {}): AstroIntegration {
+  const config: ResolvedConfig = {
+    collections: options.collections ?? null,
+    model: options.model ?? 'claude-haiku-4-5',
+    digestModel: options.digestModel ?? 'claude-opus-4-8',
+    endpoint: options.endpoint ?? '/api/ask',
+    basePath: options.basePath ?? '/docs/',
+    maxResults: options.maxResults ?? 6,
+    answerMaxTokens: options.answerMaxTokens ?? 1024,
+    maxIterations: options.maxIterations ?? 4,
+    chunkHeadingDepth: options.chunkHeadingDepth ?? 3,
+    candidatePerSearch: options.candidatePerSearch ?? 8,
+    perDocCap: options.perDocCap ?? 2,
+    digestPath: options.digestPath ?? '.hev-ask/digest.json',
+    digestContentGlobs: options.digestContentGlobs,
+  };
+
+  let siteRoot = process.cwd();
+
+  return {
+    name: '@hevmind/ask',
+    hooks: {
+      'astro:config:setup': ({ config: astroConfig, injectRoute, updateConfig, logger, addWatchFile }) => {
+        siteRoot = fileURLToPath(astroConfig.root);
+        updateConfig({
+          vite: { plugins: [virtualConfigPlugin(config), virtualDigestPlugin(config, siteRoot)] },
+        });
+
+        injectRoute({
+          pattern: resourceRoutePattern(config.endpoint),
+          entrypoint: '@hevmind/ask/endpoint',
+          prerender: false,
+        });
+
+        addWatchFile(new URL(config.digestPath, astroConfig.root));
+
+        if (!config.collections?.length) {
+          logger.warn('No `collections` configured; search will error until you set e.g. collections: ["docs"].');
+        }
+        logger.info(`search endpoint at ${config.endpoint} (model: ${config.model})`);
+      },
+      'astro:build:start': async ({ logger }) => {
+        if (!config.collections?.length) return;
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+          logger.warn(`ANTHROPIC_API_KEY is not set; using committed ${config.digestPath} if present.`);
+          return;
+        }
+
+        try {
+          const output = await runDigestBuild(siteRoot, config);
+          if (output) logger.info(output);
+        } catch (err) {
+          logger.warn(`digest build failed; using committed artifact if present. ${(err as Error).message}`);
+        }
+      },
+    },
+  };
+}
+
+/** Serializes the resolved config into a virtual module the endpoint imports. */
+function virtualConfigPlugin(config: ResolvedConfig) {
+  const resolvedId = '\0' + CONFIG_VIRTUAL_ID;
+  return {
+    name: 'hev-ask:config',
+    resolveId(id: string) {
+      return id === CONFIG_VIRTUAL_ID ? resolvedId : undefined;
+    },
+    load(id: string) {
+      return id === resolvedId ? `export default ${JSON.stringify(config)};` : undefined;
+    },
+  };
+}
+
+function virtualDigestPlugin(config: ResolvedConfig, siteRoot: string) {
+  const resolvedId = '\0' + DIGEST_VIRTUAL_ID;
+  return {
+    name: 'hev-ask:digest',
+    resolveId(id: string) {
+      return id === DIGEST_VIRTUAL_ID ? resolvedId : undefined;
+    },
+    load(id: string) {
+      if (id !== resolvedId) return undefined;
+      const digest = readDigest(siteRoot, config.digestPath);
+      return `export default ${JSON.stringify(digest)};`;
+    },
+  };
+}
+
+function readDigest(siteRoot: string, digestPath: string) {
+  try {
+    return normalizeDigest(JSON.parse(readFileSync(path.resolve(siteRoot, digestPath), 'utf8')));
+  } catch {
+    return EMPTY_DIGEST;
+  }
+}
+
+async function runDigestBuild(siteRoot: string, config: ResolvedConfig): Promise<string> {
+  const askBin = fileURLToPath(new URL('../bin/ask.mjs', import.meta.url));
+  const args = [
+    askBin,
+    'digest',
+    'build',
+    '--digest-path',
+    config.digestPath,
+    '--base-path',
+    config.basePath,
+    '--chunk-heading-depth',
+    String(config.chunkHeadingDepth),
+    '--digest-model',
+    config.digestModel,
+  ];
+  for (const collection of config.collections ?? []) args.push('--collection', collection);
+  for (const glob of config.digestContentGlobs ?? []) args.push('--content-glob', glob);
+
+  const { stdout, stderr } = await execFileAsync(process.execPath, args, {
+    cwd: siteRoot,
+    env: process.env,
+    maxBuffer: 1024 * 1024 * 8,
+  });
+  const output = [stdout, stderr].map((value) => value.trim()).filter(Boolean).join('\n');
+  return output.replace(/^\[hev-ask\]\s*/gm, '');
+}
+
+function resourceRoutePattern(endpoint: string): string {
+  if (endpoint === '/') return '/[...resource]';
+  const base = endpoint.endsWith('/') && endpoint.length > 1 ? endpoint.slice(0, -1) : endpoint;
+  return `${base}/[...resource]`;
+}

package/src/llm.ts

@@ -0,0 +1,239 @@
+// Minimal Anthropic Messages API client over fetch — keeps the package free of
+// runtime dependencies and edge-runtime friendly.
+
+const API_URL = 'https://api.anthropic.com/v1/messages';
+const API_VERSION = '2023-06-01';
+
+export interface AnthropicMessage {
+  role: 'user' | 'assistant';
+  content: unknown;
+}
+
+export interface AnthropicTextBlock {
+  type: 'text';
+  text: string;
+  cache_control?: { type: 'ephemeral' };
+}
+
+export interface AnthropicToolResultBlock {
+  type: 'tool_result';
+  tool_use_id: string;
+  content: string;
+}
+
+export interface AnthropicTool {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface CallClaudeOptions {
+  apiKey: string;
+  model: string;
+  system: string | AnthropicTextBlock[];
+  messages: AnthropicMessage[];
+  tools?: AnthropicTool[];
+  toolChoice?: { type: 'tool'; name: string } | { type: 'auto' };
+  maxTokens?: number;
+  /** Aborts the upstream request when the client disconnects. */
+  signal?: AbortSignal;
+}
+
+export interface AnthropicUsage {
+  input_tokens: number;
+  output_tokens: number;
+}
+
+export interface AnthropicResponse {
+  content: Array<
+    | { type: 'text'; text: string }
+    | { type: 'tool_use'; id: string; name: string; input: unknown }
+  >;
+  stop_reason: string | null;
+  /** Token counts returned by the Messages API; used for observability. */
+  usage?: AnthropicUsage;
+}
+
+function requestBody(opts: CallClaudeOptions, stream: boolean) {
+  return JSON.stringify({
+    model: opts.model,
+    max_tokens: opts.maxTokens ?? 2048,
+    system: opts.system,
+    messages: opts.messages,
+    tools: opts.tools,
+    tool_choice: opts.toolChoice,
+    stream: stream || undefined,
+  });
+}
+
+function headers(apiKey: string) {
+  return {
+    'content-type': 'application/json',
+    'x-api-key': apiKey,
+    'anthropic-version': API_VERSION,
+  };
+}
+
+export async function callClaude(opts: CallClaudeOptions): Promise<AnthropicResponse> {
+  const res = await fetch(API_URL, {
+    method: 'POST',
+    headers: headers(opts.apiKey),
+    body: requestBody(opts, false),
+    signal: opts.signal,
+  });
+
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '');
+    throw new Error(`Anthropic API ${res.status}: ${detail.slice(0, 500)}`);
+  }
+
+  return (await res.json()) as AnthropicResponse;
+}
+
+/** High-level events surfaced from the Anthropic SSE stream. */
+export type StreamEvent =
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; id: string; name: string; input: unknown }
+  | { type: 'stop'; stopReason: string | null; usage?: AnthropicUsage };
+
+/**
+ * Streams a Messages API response, yielding text deltas as they arrive and
+ * fully-reconstructed tool_use blocks once their streamed JSON input completes.
+ */
+export async function* streamClaude(opts: CallClaudeOptions): AsyncGenerator<StreamEvent> {
+  const res = await fetch(API_URL, {
+    method: 'POST',
+    headers: headers(opts.apiKey),
+    body: requestBody(opts, true),
+    signal: opts.signal,
+  });
+
+  if (!res.ok || !res.body) {
+    const detail = res.ok ? 'no response body' : await res.text().catch(() => '');
+    throw new Error(`Anthropic API ${res.status}: ${detail.slice(0, 500)}`);
+  }
+
+  const reader = res.body.getReader();
+  // `{ stream: true }` so multibyte tokens split across network chunks decode
+  // without producing replacement characters.
+  const decoder = new TextDecoder('utf-8');
+  const state = newSseState();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const { events, state: next } = parseSseChunk(decoder.decode(value, { stream: true }), state);
+    Object.assign(state, next);
+    for (const event of events) yield event;
+  }
+}
+
+interface SseToolBlock {
+  kind: 'tool_use';
+  id: string;
+  name: string;
+  json: string;
+}
+interface SseTextBlock {
+  kind: 'text';
+}
+type SseBlock = SseToolBlock | SseTextBlock;
+
+export interface SseParseState {
+  /** Bytes not yet terminated by a blank line. */
+  buffer: string;
+  /** Content blocks indexed by their position in the message. */
+  blocks: Record<number, SseBlock>;
+  /** Token usage accumulated from `message_start` / `message_delta` frames. */
+  usage: AnthropicUsage;
+}
+
+export function newSseState(): SseParseState {
+  return { buffer: '', blocks: {}, usage: { input_tokens: 0, output_tokens: 0 } };
+}
+
+/**
+ * Pure, network-free SSE frame parser. Feeds on decoded text chunks and returns
+ * any high-level events that completed, plus the carried-over parse state.
+ */
+export function parseSseChunk(
+  chunk: string,
+  prev: SseParseState,
+): { events: StreamEvent[]; state: SseParseState } {
+  const events: StreamEvent[] = [];
+  const blocks = prev.blocks;
+  const usage = prev.usage ?? { input_tokens: 0, output_tokens: 0 };
+  let buffer = prev.buffer + chunk;
+
+  let sep: number;
+  while ((sep = buffer.indexOf('\n\n')) !== -1) {
+    const frame = buffer.slice(0, sep);
+    buffer = buffer.slice(sep + 2);
+
+    const data = frame
+      .split('\n')
+      .filter((line) => line.startsWith('data:'))
+      .map((line) => line.slice(5).trim())
+      .join('');
+    if (!data || data === '[DONE]') continue;
+
+    let payload: Record<string, unknown>;
+    try {
+      payload = JSON.parse(data) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+
+    const type = payload.type;
+    if (type === 'content_block_start') {
+      const index = payload.index as number;
+      const block = payload.content_block as { type?: string; id?: string; name?: string };
+      if (block?.type === 'tool_use') {
+        blocks[index] = { kind: 'tool_use', id: block.id ?? '', name: block.name ?? '', json: '' };
+      } else {
+        blocks[index] = { kind: 'text' };
+      }
+    } else if (type === 'content_block_delta') {
+      const index = payload.index as number;
+      const delta = payload.delta as { type?: string; text?: string; partial_json?: string };
+      if (delta?.type === 'text_delta' && typeof delta.text === 'string') {
+        events.push({ type: 'text', text: delta.text });
+      } else if (delta?.type === 'input_json_delta') {
+        const block = blocks[index];
+        if (block?.kind === 'tool_use') block.json += delta.partial_json ?? '';
+      }
+    } else if (type === 'content_block_stop') {
+      const block = blocks[payload.index as number];
+      if (block?.kind === 'tool_use') {
+        let input: unknown = {};
+        try {
+          input = JSON.parse(block.json || '{}');
+        } catch {
+          input = {};
+        }
+        events.push({ type: 'tool_use', id: block.id, name: block.name, input });
+      }
+    } else if (type === 'message_start') {
+      // Carries the prompt token count; no event, just accumulate usage.
+      const message = payload.message as { usage?: { input_tokens?: number } } | undefined;
+      if (typeof message?.usage?.input_tokens === 'number') {
+        usage.input_tokens = message.usage.input_tokens;
+      }
+    } else if (type === 'message_delta') {
+      const delta = payload.delta as { stop_reason?: string | null };
+      const deltaUsage = payload.usage as { output_tokens?: number } | undefined;
+      if (typeof deltaUsage?.output_tokens === 'number') {
+        usage.output_tokens = deltaUsage.output_tokens;
+      }
+      const hasUsage = usage.input_tokens > 0 || usage.output_tokens > 0;
+      events.push({
+        type: 'stop',
+        stopReason: delta?.stop_reason ?? null,
+        ...(hasUsage ? { usage: { ...usage } } : {}),
+      });
+    }
+    // `ping` and `message_stop` need no surfaced event.
+  }
+
+  return { events, state: { buffer, blocks, usage } };
+}