@stainless-api/docs 0.1.0-beta.136 → 0.1.0-beta.138

package/virtual-module.d.ts

@@ -19,6 +19,7 @@ declare module 'virtual:stl-starlight-virtual-module' {
   export const PROPERTY_SETTINGS: PropertySettingsType;
   export const MIDDLEWARE: StlStarlightMiddleware;
   export const ENABLE_CONTEXT_MENU: boolean;
+  export const CONTEXT_MENU_ENABLE_THIRD_PARTY: boolean;
   export const STAINLESS_PROJECT: string | undefined;
   export const LLMS_TXT_DESCRIPTION: string | null;
   export const LLMS_TXT_DETAIL_THRESHOLD: number;
@@ -53,6 +54,7 @@ declare module 'virtual:stl-docs-virtual-module' {
   export const API_REFERENCE_BASE_PATH: string;
   export const ENABLE_PROSE_MARKDOWN_RENDERING: boolean;
   export const ENABLE_CONTEXT_MENU: boolean;
+  export const CONTEXT_MENU_ENABLE_THIRD_PARTY: boolean;
   export const RENDER_PAGE_DESCRIPTIONS: boolean;
   export const LINK_GROUP_TITLES_TO_OVERVIEW_PAGES: boolean;
   export const FONTS: {
@@ -63,7 +65,10 @@ declare module 'virtual:stl-docs-virtual-module' {
   };
   export const RENDER_CREDITS: boolean;
   export const SITE_TITLE: string;
-  export const ENABLE_AI_CHAT: boolean;
+}
+
+declare module 'virtual:stl-docs-ai-chat' {
+  export const AI_CHAT_HANDLER: import('./stl-docs/chat/docs-chat-handler').DocsChatHandler | undefined;
 }
 
 declare module 'virtual:stl-docs-ai-chat-examples' {

package/stl-docs/chat/stainless-handler/index.ts

@@ -1,126 +0,0 @@
-import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
-import { JSONParser } from '@streamparser/json-whatwg';
-import {
-  type RequestBody,
-  responseChunk,
-  type FeedbackRequestBody,
-  feedbackResponseBody,
-  type MetadataRequestBody,
-  metadataResponseBody,
-} from '../schemas';
-import { streamAsyncIterator } from '../stream-util';
-import { DocsChatHandler } from '../docs-chat-handler';
-
-const API_URL = new URL('https://app.stainless.com/api/');
-const CHAT_ENDPOINT = new URL('ai/get-agentic-help', API_URL);
-
-const FEEDBACK_ENDPOINT = (spanId: string) => new URL(`ai/agentic-help/${spanId}/score`, API_URL);
-const METADATA_ENDPOINT = (spanId: string) => new URL(`ai/agentic-help/${spanId}/metadata`, API_URL);
-
-/**
- * Identifier for tracking unique users in braintrust
- */
-function getClientId() {
-  let clientId = localStorage.getItem('stainless-client-id');
-  if (!clientId) {
-    clientId = crypto.randomUUID();
-    localStorage.setItem('stainless-client-id', clientId);
-  }
-  return clientId;
-}
-
-/** Context on what the user is currently viewing to pass to the agent */
-function getPageContext({ siteTitle }: { siteTitle: string | undefined }) {
-  const { href } = window.location;
-  const markdownUrl = `${href.replace(/\/$/, '')}/index.md`;
-  const pageTitle = document.querySelector('h1')?.textContent;
-  return [
-    `The user is viewing a documentation page${siteTitle ? ` for ${siteTitle}` : ''}.`,
-    `- Content URL: ${markdownUrl}`,
-    pageTitle && `- Page title: "${pageTitle}"`,
-    // TODO: include stainless path here? does the agent know how to use it?
-    // TODO: pass more of the page content into context without the agent having to retrieve it
-  ]
-    .filter(Boolean)
-    .join('\n');
-}
-
-export class StainlessHandler implements DocsChatHandler {
-  constructor(
-    private language: DocsLanguage,
-    private siteTitle: string | undefined,
-    private project: string,
-  ) {}
-  /**
-   * Stream chat response from the server
-   */
-  async *generateResponse(
-    {
-      query,
-      priorMessages,
-    }: {
-      query: string;
-      priorMessages: NonNullable<RequestBody['additionalContext']>['prior_messages'];
-    },
-    abortSignal: AbortSignal,
-  ) {
-    const res = await fetch(CHAT_ENDPOINT, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        query,
-        sdk: { project: this.project, language: this.language },
-        stream: true,
-        additionalContext: {
-          prior_messages: priorMessages,
-          intent: getPageContext({ siteTitle: this.siteTitle }),
-        },
-        browser_id: getClientId(),
-      } satisfies RequestBody),
-
-      signal: abortSignal,
-    });
-
-    if (!res.ok || !res.body) throw new Error(`Chat request failed with status ${res.status}`);
-
-    const parser = new JSONParser({ separator: '\n', paths: ['$'] });
-    for await (const chunk of streamAsyncIterator(res.body.pipeThrough(parser))) {
-      const chunkParsed = responseChunk.safeParse(chunk.value);
-      if (chunkParsed.success) yield chunkParsed.data;
-    }
-  }
-
-  /**
-   * Attach a score to a response
-   */
-  async onRate(spanId: string, score: 0 | 1) {
-    const res = await fetch(FEEDBACK_ENDPOINT(spanId), {
-      method: 'PUT',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ score } satisfies FeedbackRequestBody),
-    });
-
-    if (!res.ok) throw new Error(`Feedback request failed with status ${res.status}`);
-    return feedbackResponseBody.parse(await res.json());
-  }
-
-  /**
-   * Attach metadata to a response
-   */
-  async onAssignMetadata(spanId: string, metadata: Record<string, string>) {
-    const res = await fetch(METADATA_ENDPOINT(spanId), {
-      method: 'PUT',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ metadata } satisfies MetadataRequestBody),
-    });
-
-    if (!res.ok) throw new Error(`Metadata request failed with status ${res.status}`);
-    return metadataResponseBody.parse(await res.json());
-  }
-}

package/stl-docs/chat/stream-util.ts

@@ -1,16 +0,0 @@
-/*
- * https://jakearchibald.com/2017/async-iterators-and-generators/#making-streams-iterate
- * safari does not yet support consuming ReadableStream as AsyncIterable
- */
-export async function* streamAsyncIterator<T>(stream: ReadableStream<T>) {
-  const reader = stream.getReader();
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) return;
-      yield value;
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}

package/stl-docs/proseSearchIndexing.ts

@@ -1,218 +0,0 @@
-import type { AstroIntegration } from 'astro';
-import { readFile } from 'fs/promises';
-import { getProsePages } from '../shared/getProsePages';
-import { getSharedLogger } from '../shared/getSharedLogger';
-import { bold } from '../shared/terminalUtils';
-import * as cheerio from 'cheerio';
-import { buildProseIndex } from '@stainless-api/docs-search/providers/algolia';
-
-class SectionContext {
-  headers: { level: number; text: string }[] = [];
-  headerId: string | undefined;
-  headerTag: string | undefined;
-  headerText: string | undefined;
-  hasContent = false;
-
-  get(): string | undefined {
-    if (this.headers.length === 0) return;
-    return this.headers.map((h) => h.text).join(' > ');
-  }
-
-  header({ id, tag, text }: { id: string; tag: string; text: string }) {
-    const level = getHeaderLevel(tag);
-    if (level > 0) {
-      while (this.headers.length > 0 && this.headers[this.headers.length - 1]!.level >= level) {
-        this.headers.pop();
-      }
-      this.headers.push({ level, text });
-    }
-    this.headerId = id;
-    this.headerTag = tag;
-    this.headerText = text;
-    this.hasContent = false;
-  }
-}
-
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/`/g, '')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '');
-}
-
-function getHeaderLevel(tag: string): number {
-  const match = tag.match(/^h(\d)$/);
-  return match ? parseInt(match[1]!, 10) : 0;
-}
-
-// Chunking configuration
-// We target 64-256 tokens per chunk, using ~1.3 tokens/word for English text
-const TOKENS_PER_WORD = 1.3;
-const MIN_TOKENS = 64;
-const MAX_TOKENS = 256;
-const MIN_WORDS = Math.floor(MIN_TOKENS / TOKENS_PER_WORD); // ~49 words
-const MAX_WORDS = Math.floor(MAX_TOKENS / TOKENS_PER_WORD); // ~197 words
-const SENTENCE_BREAK_WORDS = Math.floor((MAX_TOKENS * 0.875) / TOKENS_PER_WORD); // ~172 words
-
-/**
- * Chunks text content into segments of 64-256 tokens using word-based boundaries.
- * Prefers breaking at sentence endings for natural chunk boundaries.
- */
-function chunkTextByWords(text: string): string[] {
-  const words = text.split(/\s+/).filter((w) => w.length > 0);
-
-  if (words.length <= MAX_WORDS) {
-    return words.length > 0 ? [words.join(' ')] : [];
-  }
-
-  const chunks: string[] = [];
-  let currentChunk: string[] = [];
-
-  for (const word of words) {
-    currentChunk.push(word);
-
-    // Force break at max words
-    if (currentChunk.length >= MAX_WORDS) {
-      chunks.push(currentChunk.join(' '));
-      currentChunk = [];
-      continue;
-    }
-
-    // Prefer breaking at sentence boundaries after threshold
-    if (currentChunk.length >= SENTENCE_BREAK_WORDS && /[.!?]["']?$/.test(word)) {
-      chunks.push(currentChunk.join(' '));
-      currentChunk = [];
-    }
-  }
-
-  if (currentChunk.length > 0) {
-    if (currentChunk.length < MIN_WORDS && chunks.length > 0) {
-      const lastChunk = chunks[chunks.length - 1]!;
-      const mergedWords = lastChunk.split(/\s+/).length + currentChunk.length;
-      if (mergedWords <= MAX_WORDS) {
-        chunks[chunks.length - 1] = lastChunk + ' ' + currentChunk.join(' ');
-      } else {
-        chunks.push(currentChunk.join(' '));
-      }
-    } else {
-      chunks.push(currentChunk.join(' '));
-    }
-  }
-
-  return chunks;
-}
-
-type IndexEntry = {
-  chunk: { id: string; index: number; total: number };
-  id: string;
-  tag: string;
-  content: string;
-  language?: string;
-  sectionContext?: string;
-};
-
-const DEFAULT_ROOT = 'main';
-const DEFAULT_PATTERN = 'h1, h2, h3, h4, h5, h6, p, li, pre code';
-
-/**
- * Indexes HTML content for search, with section context and code language extraction.
- *
- * Features:
- * - Tracks header hierarchy to prepend section context (e.g., "Guide > Setup: ...")
- * - Extracts language metadata from code blocks (class="language-js")
- * - Uses word-based chunking with sentence boundary detection
- */
-function* indexHTML(content: string, root = DEFAULT_ROOT, pattern = DEFAULT_PATTERN): Generator<IndexEntry> {
-  const $ = cheerio.load(content);
-  const matches = $(root).find(pattern);
-
-  const ctx = new SectionContext();
-
-  for (const match of matches) {
-    const tagName = match.tagName.toLowerCase();
-    const rawText = $(match).text().trim();
-
-    if (getHeaderLevel(tagName) > 0) {
-      ctx.header({ id: $(match).attr('id') ?? slugify(rawText), tag: tagName, text: rawText });
-      continue;
-    }
-
-    // Check if this is a code block and extract language
-    const isCode = tagName === 'code' && $(match).parent().is('pre');
-    let language: string | undefined;
-    if (isCode) {
-      const classes = $(match).attr('class') || '';
-      const langMatch = classes.match(/(?:language-|lang-)([a-zA-Z0-9+-]+)/);
-      language = langMatch ? langMatch[1] : undefined;
-    }
-
-    // Build content with section context
-    const sectionContext = ctx.get();
-    const chunks = chunkTextByWords(rawText);
-    const chunkId = crypto.randomUUID();
-
-    for (const [chunkN, chunkText] of chunks.entries()) {
-      yield {
-        id: ctx.headerId ?? $(match).attr('id') ?? chunkId,
-        tag: isCode ? 'code' : tagName,
-        content: chunkText,
-        ...(sectionContext ? { sectionContext } : {}),
-        ...(language && { language }),
-        chunk: {
-          id: chunkId,
-          index: chunkN,
-          total: chunks.length,
-        },
-      };
-      ctx.hasContent = true;
-    }
-  }
-}
-
-export function stainlessDocsAlgoliaProseIndexing({
-  apiReferenceBasePath,
-}: {
-  apiReferenceBasePath: string | null;
-}): AstroIntegration {
-  return {
-    name: 'stl-docs-prose-indexing',
-    hooks: {
-      'astro:build:done': async ({ logger: localLogger, dir }) => {
-        const logger = getSharedLogger({ fallback: localLogger });
-        const outputBasePath = dir.pathname;
-
-        const {
-          PUBLIC_ALGOLIA_APP_ID: appId,
-          PUBLIC_ALGOLIA_INDEX: indexName,
-          PRIVATE_ALGOLIA_WRITE_KEY: algoliaWriteKey,
-        } = process.env;
-
-        if (!appId || !indexName || !algoliaWriteKey) {
-          logger.info('Skipping algolia indexing due to missing environment variables');
-          return;
-        }
-
-        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
-        logger.info(bold(`Indexing ${pagesToRender.length} prose pages for algolia search`));
-
-        const objects = [];
-        for (const absHtmlPath of pagesToRender) {
-          const content = await readFile(absHtmlPath, 'utf-8');
-          const idx = indexHTML(content);
-          for (const entry of idx)
-            objects.push({
-              ...entry,
-              source: absHtmlPath.slice(outputBasePath.length),
-            });
-        }
-
-        try {
-          await buildProseIndex(appId, `${indexName}-prose`, algoliaWriteKey, objects);
-        } catch (err) {
-          logger.error(`Failed to index prose content: ${err}`);
-        }
-      },
-    },
-  };
-}