@hevmind/ask 0.1.0

package/src/observability.ts

@@ -0,0 +1,213 @@
+// PostHog LLM observability for the agentic answer path.
+//
+// Emits $ai_generation / $ai_span / $ai_trace events over `fetch` so each
+// request shows up in PostHog's LLM analytics with model, token, latency, and
+// trace structure. Like `llm.ts`, this stays free of runtime dependencies and
+// edge-runtime friendly — it speaks PostHog's capture API directly rather than
+// pulling in `posthog-node`. Mirrors the pattern used in ../mind
+// (site/src/lib/agent-core.mjs).
+//
+// Everything degrades: with no PostHog key configured, `makeTelemetry` returns
+// a no-op sink, so the agentic path behaves exactly as before.
+
+import type { AnthropicUsage } from './llm.ts';
+
+/**
+ * How much prompt/response text ships to PostHog.
+ * - `off`: metadata only (model, tokens, latency, tool names). No text.
+ * - `redacted`: conversation + tool calls, but tool_result bodies are redacted.
+ * - `full` (default): everything. The corpus is public docs, so this is safe.
+ */
+export type CaptureMode = 'off' | 'redacted' | 'full';
+
+export interface GenerationEvent {
+  spanId: string;
+  spanName: string;
+  model: string;
+  input: unknown;
+  output: unknown;
+  usage?: AnthropicUsage;
+  latencyMs: number;
+  httpStatus?: number;
+}
+
+export interface SpanEvent {
+  spanId: string;
+  parentId?: string;
+  name: string;
+  input?: unknown;
+  output?: unknown;
+  ok: boolean;
+  latencyMs: number;
+}
+
+export interface TraceEvent {
+  name?: string;
+  latencyMs: number;
+  ok: boolean;
+}
+
+/** A telemetry sink. The no-op variant has the same shape so callers never branch. */
+export interface Telemetry {
+  readonly traceId: string;
+  generation(event: GenerationEvent): void;
+  span(event: SpanEvent): void;
+  trace(event: TraceEvent): void;
+}
+
+export interface TelemetryOptions {
+  /** PostHog project API key. Absent → telemetry is a no-op. */
+  apiKey?: string;
+  /** Ingestion host; defaults to PostHog US cloud. */
+  host?: string;
+  /** Content capture level; defaults to `full`. */
+  captureContent?: CaptureMode;
+  /** Distinct id for the person/session; defaults to `anonymous`. */
+  distinctId?: string;
+  /** Optional label attached to every event as `agent_scope`. */
+  scope?: string;
+  /** Reuse an existing trace id; one is generated otherwise. */
+  traceId?: string;
+  /** Cloudflare-style keep-alive so in-flight captures survive response end. */
+  waitUntil?: (promise: Promise<unknown>) => void;
+  /** Injectable for tests / non-standard runtimes. */
+  fetchImpl?: typeof fetch;
+  /** Injectable for tests. */
+  randomId?: () => string;
+}
+
+function defaultRandomId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  return c?.randomUUID ? c.randomUUID() : `trace-${Date.now()}`;
+}
+
+function noopTelemetry(traceId: string): Telemetry {
+  return {
+    traceId,
+    generation() {},
+    span() {},
+    trace() {},
+  };
+}
+
+/**
+ * Build a telemetry sink from explicit options. Returns a no-op sink when no
+ * PostHog key is set so the agentic path degrades gracefully.
+ */
+export function makeTelemetry(options: TelemetryOptions = {}): Telemetry {
+  const randomId = options.randomId ?? defaultRandomId;
+  const traceId = options.traceId ?? randomId();
+  const { apiKey } = options;
+  if (!apiKey) return noopTelemetry(traceId);
+
+  const host = (options.host ?? 'https://us.i.posthog.com').replace(/\/+$/, '');
+  const mode: CaptureMode = options.captureContent ?? 'full';
+  const distinctId = options.distinctId ?? 'anonymous';
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const { waitUntil, scope } = options;
+
+  const emit = (event: string, properties: Record<string, unknown>) => {
+    const body = JSON.stringify({
+      api_key: apiKey,
+      event,
+      distinct_id: distinctId,
+      properties: {
+        $ai_trace_id: traceId,
+        $ai_provider: 'anthropic',
+        $process_person_profile: false, // anonymous — no person profile
+        ...(scope ? { agent_scope: scope } : {}),
+        ...properties,
+      },
+    });
+    const sent = fetchImpl(`${host}/i/v0/e/`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body,
+    })
+      .then(() => undefined)
+      .catch(() => undefined);
+    if (waitUntil) waitUntil(sent);
+  };
+
+  // For `redacted`, blank out tool_result bodies (the injected document text)
+  // while keeping the conversation and tool calls intact.
+  const redact = (input: unknown): unknown => {
+    if (mode === 'full' || !Array.isArray(input)) return input;
+    return input.map((message) => {
+      const content = (message as { content?: unknown })?.content;
+      if (!Array.isArray(content)) return message;
+      return {
+        ...(message as object),
+        content: content.map((block) =>
+          (block as { type?: string })?.type === 'tool_result'
+            ? { ...(block as object), content: '[redacted]' }
+            : block,
+        ),
+      };
+    });
+  };
+
+  return {
+    traceId,
+    generation({ spanId, spanName, model, input, output, usage, latencyMs, httpStatus }) {
+      const props: Record<string, unknown> = {
+        $ai_span_id: spanId,
+        $ai_span_name: spanName,
+        $ai_model: model,
+        $ai_input_tokens: usage?.input_tokens ?? 0,
+        $ai_output_tokens: usage?.output_tokens ?? 0,
+        $ai_latency: latencyMs / 1000,
+      };
+      if (httpStatus !== undefined) {
+        props.$ai_http_status = httpStatus;
+        props.$ai_is_error = httpStatus >= 400;
+      }
+      if (mode !== 'off') {
+        props.$ai_input = redact(input);
+        props.$ai_output_choices = [{ role: 'assistant', content: output }];
+      }
+      emit('$ai_generation', props);
+    },
+    span({ spanId, parentId, name, input, output, ok, latencyMs }) {
+      const props: Record<string, unknown> = {
+        $ai_span_id: spanId,
+        $ai_span_name: name,
+        $ai_latency: latencyMs / 1000,
+        $ai_is_error: !ok,
+      };
+      if (parentId) props.$ai_parent_id = parentId;
+      if (mode !== 'off') {
+        if (input !== undefined) props.$ai_input_state = input;
+        if (output !== undefined) props.$ai_output_state = output;
+      }
+      emit('$ai_span', props);
+    },
+    trace({ name, latencyMs, ok }) {
+      emit('$ai_trace', {
+        $ai_span_name: name ?? 'hev ask agent',
+        $ai_latency: latencyMs / 1000,
+        $ai_is_error: !ok,
+      });
+    },
+  };
+}
+
+/**
+ * Read telemetry options from environment variables. `POSTHOG_KEY` (or
+ * `POSTHOG_API_KEY`) enables capture; both are checked so this slots into
+ * existing PostHog setups. `overrides` win over the environment.
+ */
+export function telemetryFromEnv(
+  env: Record<string, string | undefined> = process.env,
+  overrides: Partial<TelemetryOptions> = {},
+): TelemetryOptions {
+  const raw = env.POSTHOG_CAPTURE_CONTENT?.toLowerCase();
+  const captureContent =
+    raw === 'off' || raw === 'redacted' || raw === 'full' ? (raw as CaptureMode) : undefined;
+  return {
+    apiKey: env.POSTHOG_KEY ?? env.POSTHOG_API_KEY,
+    host: env.POSTHOG_HOST,
+    captureContent,
+    ...overrides,
+  };
+}

package/src/search/chunk.ts

@@ -0,0 +1,137 @@
+import GithubSlugger from 'github-slugger';
+
+export interface SourceDocument {
+  slug: string;
+  title: string;
+  group?: string;
+  description?: string;
+  body: string;
+}
+
+export interface Chunk {
+  id: string;
+  docSlug: string;
+  docTitle: string;
+  group?: string;
+  heading?: string;
+  anchorId?: string;
+  url: string;
+  text: string;
+  /** Raw section markdown (pre-clean). Used for verbatim fact extraction; not hashed. */
+  raw: string;
+  tokens: Set<string>;
+}
+
+interface SectionDraft {
+  heading?: string;
+  anchorId?: string;
+  lines: string[];
+}
+
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+
+export function tokenize(text: string): string[] {
+  return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+
+/**
+ * Strip Markdown/MDX syntax so excerpts read as prose. Code content is kept
+ * for searchability, but fence markers, tags, tables, and link/emphasis syntax
+ * are removed.
+ */
+export function cleanMarkdown(src: string): string {
+  return src
+    .replace(/^\s*(import|export)\s.+$/gm, ' ')
+    .replace(/```[a-zA-Z0-9]*\n?/g, ' ')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/<\/?[A-Za-z][^>]*>/g, ' ')
+    .replace(/^\s*\|?[\s:|-]{3,}\|?\s*$/gm, ' ')
+    .replace(/\|/g, ' ')
+    .replace(/^\s{0,3}#{1,6}\s+/gm, ' ')
+    .replace(/^\s{0,3}>\s?/gm, ' ')
+    .replace(/^\s{0,3}[-*+]\s+/gm, ' ')
+    .replace(/[*_~]{1,3}/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function cleanHeadingText(src: string): string {
+  return src
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/<\/?[A-Za-z][^>]*>/g, ' ')
+    .replace(/[*~]{1,3}/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function docSlugToUrl(slug: string, basePath: string): string {
+  const base = basePath.endsWith('/') ? basePath : basePath + '/';
+  if (slug === 'index') return base.replace(/\/$/, '') || '/';
+  return base + slug.replace(/\/index$/, '');
+}
+
+export function chunkDocument(
+  doc: SourceDocument,
+  basePath: string,
+  chunkHeadingDepth = 3,
+): Chunk[] {
+  const slugger = new GithubSlugger();
+  const sections: SectionDraft[] = [{ lines: [] }];
+  let current = sections[0];
+  const maxDepth = Math.max(2, Math.min(6, chunkHeadingDepth));
+
+  for (const line of doc.body.split(/\r?\n/)) {
+    const match = line.match(HEADING_RE);
+    if (!match) {
+      current.lines.push(line);
+      continue;
+    }
+
+    const level = match[1].length;
+    const heading = cleanHeadingText(match[2]);
+    const anchorId = slugger.slug(heading);
+
+    if (level >= 2 && level <= maxDepth) {
+      current = { heading, anchorId, lines: [line] };
+      sections.push(current);
+    } else {
+      current.lines.push(line);
+    }
+  }
+
+  return sections
+    .map((section, index): Chunk | null => {
+      const rawBody = section.lines.join('\n');
+      const cleanedBody = cleanMarkdown(rawBody);
+      const introPrefix = index === 0 ? [doc.description, cleanedBody] : [cleanedBody];
+      const text = introPrefix.filter(Boolean).join('\n').trim();
+      if (!text && !section.heading) return null;
+
+      const url = docSlugToUrl(doc.slug, basePath) + (section.anchorId ? `#${section.anchorId}` : '');
+      const id = section.anchorId ? `${doc.slug}#${section.anchorId}` : doc.slug;
+      return {
+        id,
+        docSlug: doc.slug,
+        docTitle: doc.title,
+        group: doc.group,
+        heading: section.heading,
+        anchorId: section.anchorId,
+        url,
+        text,
+        raw: rawBody,
+        tokens: new Set(tokenize(`${doc.title} ${doc.group ?? ''} ${section.heading ?? ''} ${text}`)),
+      };
+    })
+    .filter((chunk): chunk is Chunk => chunk !== null);
+}
+
+export function hashableChunkText(chunks: Pick<Chunk, 'id' | 'text'>[]): string {
+  return [...chunks]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((chunk) => `${chunk.id}\n${chunk.text}`)
+    .join('\n---\n');
+}

package/src/search/index.ts

@@ -0,0 +1,44 @@
+import { getCollection } from 'astro:content';
+import { chunkDocument, type Chunk, type SourceDocument } from './chunk';
+export { prefilter, type Candidate } from './prefilter';
+
+export type { Chunk } from './chunk';
+
+/**
+ * Reads the configured content collections into an in-memory heading chunk
+ * index. Built lazily once per server process.
+ */
+export async function buildIndex(
+  collections: string[] | null,
+  basePath: string,
+  chunkHeadingDepth: number,
+): Promise<Chunk[]> {
+  if (!collections?.length) {
+    throw new Error('[hev-ask] No collections configured. Pass `collections: ["docs"]` to the integration.');
+  }
+
+  const chunks: Chunk[] = [];
+  for (const name of collections) {
+    const docs = (await getCollection(name)) as Array<{
+      id?: string;
+      slug?: string;
+      body?: string;
+      data?: { title?: string; group?: string; description?: string };
+    }>;
+
+    for (const doc of docs) {
+      const slug = (doc.slug ?? doc.id ?? '').replace(/\.(md|mdx)$/i, '');
+      if (!slug) continue;
+      const source: SourceDocument = {
+        slug,
+        title: doc.data?.title ?? slug,
+        group: doc.data?.group,
+        description: doc.data?.description,
+        body: doc.body ?? '',
+      };
+      chunks.push(...chunkDocument(source, basePath, chunkHeadingDepth));
+    }
+  }
+
+  return chunks.sort((a, b) => a.id.localeCompare(b.id));
+}