@stainless-api/docs-ai-chat 0.1.0-beta.9 → 1.0.0-beta.36

package/CHANGELOG.md

@@ -1,86 +1,97 @@
 # @stainless-api/docs-ai-chat
 
-## 0.1.0-beta.9
+## 1.0.0-beta.36
 
 ### Patch Changes
 
-- 827e203: allow http as fallback now that API supports it
-- 6340cae: fix steelie http fallback
+- Updated dependencies [cd578b7]
+  - @stainless-api/docs-ui@0.1.0-beta.71
 
-## 0.1.0-beta.8
+## 0.1.0-beta.35
 
-### Minor Changes
+### Patch Changes
+
+- Updated dependencies [93c8f94]
+  - @stainless-api/docs-ui@0.1.0-beta.70
+
+## 0.1.0-beta.34
+
+### Patch Changes
+
+- Updated dependencies [61ba36f]
+  - @stainless-api/docs-ui@0.1.0-beta.69
 
-- 883ad46: Add UI for providing feedback on chat responses
+## 0.1.0-beta.33
 
 ### Patch Changes
 
-- Updated dependencies [af54129]
-  - @stainless-api/docs@0.1.0-beta.66
+- Updated dependencies [a3f1ede]
+  - @stainless-api/docs-ui@0.1.0-beta.68
 
-## 0.1.0-beta.7
+## 0.1.0-beta.32
 
 ### Patch Changes
 
-- Updated dependencies [22a19ed]
-  - @stainless-api/docs@0.1.0-beta.65
+- @stainless-api/ai-chat@0.1.0-beta.5
+- @stainless-api/docs-ui@0.1.0-beta.67
 
-## 0.1.0-beta.6
+## 0.1.0-beta.31
 
 ### Patch Changes
 
-- Updated dependencies
-  - @stainless-api/docs@0.1.0-beta.64
+- Updated dependencies [65a1c9b]
+- Updated dependencies [4f1cee7]
+- Updated dependencies [4c72a83]
+- Updated dependencies [068469b]
+  - @stainless-api/docs-ui@0.1.0-beta.66
 
-## 0.1.0-beta.5
+## 0.1.0-beta.30
 
 ### Patch Changes
 
-- Updated dependencies [d2e3686]
-- Updated dependencies [5d6e5fa]
-  - @stainless-api/docs@0.1.0-beta.63
-  - @stainless-api/ui-primitives@0.1.0-beta.39
-  - @stainless-api/docs-ui@0.1.0-beta.52
+- Updated dependencies [b62eb05]
+  - @stainless-api/docs-ui@0.1.0-beta.65
+  - @stainless-api/ai-chat@0.1.0-beta.4
 
-## 0.1.0-beta.4
+## 0.1.0-beta.29
 
 ### Patch Changes
 
-- Updated dependencies [3c4a030]
-- Updated dependencies [cd86726]
-- Updated dependencies [aa9d333]
-- Updated dependencies [07a2c87]
-  - @stainless-api/docs@0.1.0-beta.62
-  - @stainless-api/docs-ui@0.1.0-beta.51
-  - @stainless-api/ui-primitives@0.1.0-beta.38
+- Updated dependencies [52ece13]
+- Updated dependencies [3411ffe]
+- Updated dependencies [7439be7]
+  - @stainless-api/ai-chat@0.1.0-beta.3
+  - @stainless-api/docs-ui@0.1.0-beta.64
 
-## 0.1.0-beta.3
+## 0.1.0-beta.28
 
 ### Patch Changes
 
-- 77c0d47: steelie: submit on enter
+- Updated dependencies [274cefc]
+  - @stainless-api/docs-ui@0.1.0-beta.63
 
-## 0.1.0-beta.2
+## 0.1.0-beta.27
 
 ### Patch Changes
 
-- a1502cf: fix: close AIChat when clicking on SVG elements outside its bounds
-- 88a9894: patch vite optimizeDeps for docs-ai-chat
-- Updated dependencies [2a79bae]
-- Updated dependencies [88a9894]
-  - @stainless-api/ui-primitives@0.1.0-beta.38
-  - @stainless-api/docs@0.1.0-beta.61
-  - @stainless-api/docs-ui@0.1.0-beta.51
+- Updated dependencies [6ef241e]
+- Updated dependencies [d3a85b5]
+- Updated dependencies [d3a85b5]
+- Updated dependencies [2dcb5fb]
+  - @stainless-api/docs-ui@0.1.0-beta.62
 
-## 0.1.0-beta.1
+## 0.1.0-beta.26
+
+### Patch Changes
 
-### Minor Changes
+- Updated dependencies [7155fae]
+  - @stainless-api/ai-chat@0.1.0-beta.2
+  - @stainless-api/docs-ui@0.1.0-beta.61
 
-- 2d00f0d: first version of docs-ai-chat
+## 0.1.0-beta.25
 
 ### Patch Changes
 
-- Updated dependencies [2d00f0d]
-  - @stainless-api/docs@0.1.0-beta.60
-  - @stainless-api/docs-ui@0.1.0-beta.50
-  - @stainless-api/ui-primitives@0.1.0-beta.37
+- 5c257e2: separate steelie into separate packages
+- Updated dependencies [9dda4cf]
+  - @stainless-api/ai-chat@0.1.0-beta.1

package/eslint.config.js

@@ -1,2 +1,2 @@
-import { config } from '@stainless/eslint-config/react-internal';
+import { config } from '@stainless/eslint-config/react';
 export default config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs-ai-chat",
-  "version": "0.1.0-beta.9",
+  "version": "1.0.0-beta.36",
   "publishConfig": {
     "access": "public"
   },
@@ -8,25 +8,16 @@
   "peerDependencies": {
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
-    "@stainless-api/docs-ui": "0.1.0-beta.52",
-    "@stainless-api/ui-primitives": "0.1.0-beta.39",
-    "@stainless-api/docs": "0.1.0-beta.66"
+    "@stainless-api/docs-ui": "0.1.0-beta.71"
   },
   "dependencies": {
     "@streamparser/json-whatwg": "^0.0.22",
-    "clsx": "^2.1.1",
-    "lucide-react": "^0.562.0",
-    "motion": "^12.24.7",
-    "react": "^19.2.3",
-    "react-markdown": "^10.1.0",
-    "react-syntax-highlighter": "^16.1.0",
-    "remend": "^1.0.1",
-    "zod": "^4.3.5"
+    "zod": "^4.3.5",
+    "@stainless-api/ai-chat": "0.1.0-beta.5"
   },
   "devDependencies": {
-    "@types/react": "19.2.7",
+    "@types/react": "19.2.10",
     "@types/react-dom": "^19.2.3",
-    "@types/react-syntax-highlighter": "^15.5.13",
     "typescript": "5.9.3",
     "@stainless/eslint-config": "0.1.0-beta.1"
   },
@@ -34,8 +25,8 @@
     "./plugin": {
       "import": "./plugin.tsx"
     },
-    "./src/AiChat.tsx": {
-      "import": "./src/AiChat.tsx"
+    "./src/DocsChat.tsx": {
+      "import": "./src/DocsChat.tsx"
     }
   },
   "scripts": {

package/plugin.tsx

@@ -1,3 +1,3 @@
-export default function aiChatPlugin() {
-  return { chatComponentPath: '@stainless-api/docs-ai-chat/src/AiChat.tsx' };
+export default function docsChatPlugin() {
+  return { chatComponentPath: '@stainless-api/docs-ai-chat/src/DocsChat.tsx' };
 }

package/src/DocsChat.tsx

@@ -0,0 +1,42 @@
+import AiChat from '@stainless-api/ai-chat/src/AiChat.tsx';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { setResponseMetadata, submitResponseFeedback } from './api';
+import { useChat } from './hook';
+
+export default function DocsChat({
+  projectId,
+  language,
+  siteTitle,
+}: {
+  projectId: string;
+  language: DocsLanguage | undefined;
+  siteTitle: string | undefined;
+}) {
+  const { chatMessages, sendMessage } = useChat({
+    projectId,
+    language: language ?? 'http',
+    siteTitle,
+  });
+
+  const rateMessage = async (spanId: string, rating: 'up' | 'down'): Promise<boolean> => {
+    try {
+      const { success } = await submitResponseFeedback(spanId, { up: 1 as const, down: 0 as const }[rating]);
+      return success;
+    } catch {
+      return false;
+    }
+  };
+
+  const onCopyMessage = (spanId: string) => {
+    setResponseMetadata(spanId, { copied_to_clipboard: 'true' }).catch(() => {});
+  };
+
+  return (
+    <AiChat
+      chatMessages={chatMessages}
+      sendMessage={sendMessage}
+      rateMessage={rateMessage}
+      onCopyMessage={onCopyMessage}
+    />
+  );
+}

package/src/api/client-id.ts

@@ -0,0 +1,11 @@
+/**
+ * Identifier for tracking unique users in braintrust
+ */
+export function getClientId() {
+  let clientId = localStorage.getItem('stainless-client-id');
+  if (!clientId) {
+    clientId = crypto.randomUUID();
+    localStorage.setItem('stainless-client-id', clientId);
+  }
+  return clientId;
+}

package/src/api/index.ts

@@ -1,12 +1,37 @@
 import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import { JSONParser } from '@streamparser/json-whatwg';
-import { type RequestBody, responseChunk, type FeedbackRequestBody, feedbackResponseBody } from './schemas';
+import {
+  type RequestBody,
+  responseChunk,
+  type FeedbackRequestBody,
+  feedbackResponseBody,
+  type MetadataRequestBody,
+  metadataResponseBody,
+} from './schemas';
 import { streamAsyncIterator } from './util';
+import { getClientId } from './client-id';
 
 export const API_URL = new URL('https://app.stainless.com/api/');
 export const CHAT_ENDPOINT = new URL('ai/get-agentic-help', API_URL);
 
 export const FEEDBACK_ENDPOINT = (spanId: string) => new URL(`ai/agentic-help/${spanId}/score`, API_URL);
+export const METADATA_ENDPOINT = (spanId: string) => new URL(`ai/agentic-help/${spanId}/metadata`, API_URL);
+
+/** 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');
+}
 
 /**
  * Stream chat response from the server
@@ -16,12 +41,14 @@ export async function* getChatResponse(
     query,
     project,
     language,
-    priorMessages,
+    sessionId,
+    siteTitle,
   }: {
     query: string;
     project: string;
     language: DocsLanguage;
-    priorMessages: NonNullable<RequestBody['additionalContext']>['prior_messages'];
+    sessionId: string | undefined;
+    siteTitle: string | undefined;
   },
   abortSignal: AbortSignal,
 ) {
@@ -34,7 +61,11 @@ export async function* getChatResponse(
       query,
       sdk: { project, language },
       stream: true,
-      additionalContext: { prior_messages: priorMessages },
+      session_id: sessionId,
+      additionalContext: {
+        intent: getPageContext({ siteTitle }),
+      },
+      browser_id: getClientId(),
     } satisfies RequestBody),
 
     signal: abortSignal,
@@ -64,3 +95,19 @@ export async function submitResponseFeedback(spanId: string, score: 0 | 1) {
   if (!res.ok) throw new Error(`Feedback request failed with status ${res.status}`);
   return feedbackResponseBody.parse(await res.json());
 }
+
+/**
+ * Attach a score to a response
+ */
+export async function setResponseMetadata(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/src/api/schemas.ts

@@ -14,20 +14,16 @@ export const requestBody = z.object({
       maxTokens: z.number().optional(),
     })
     .optional(),
+  session_id: z.string().optional(),
   additionalContext: z
     .object({
-      prior_messages: z.array(
-        z.object({
-          role: z.enum(['user', 'assistant']),
-          content: z.string(),
-        }),
-      ),
       code: z.string().optional(),
       intent: z.string().optional(),
       lsp: z.string().optional(),
       errors: z.string().optional(),
     })
     .optional(),
+  browser_id: z.string().optional(),
 });
 export type RequestBody = z.input<typeof requestBody>;
 
@@ -50,9 +46,17 @@ export const responseChunk = z.discriminatedUnion('type', [
     type: z.literal('done'),
     span_id: z.string(),
   }),
+  z.object({
+    type: z.literal('start_session'),
+    session_id: z.string(),
+  }),
 ]);
 export type ResponseChunk = z.infer<typeof responseChunk>;
 
 export const feedbackRequestBody = z.object({ score: z.number().min(0).max(1) });
 export type FeedbackRequestBody = z.infer<typeof feedbackRequestBody>;
 export const feedbackResponseBody = z.object({ success: z.boolean() });
+
+export const metadataRequestBody = z.object({ metadata: z.record(z.string(), z.string()) });
+export type MetadataRequestBody = z.infer<typeof metadataRequestBody>;
+export const metadataResponseBody = z.object({ success: z.boolean() });

package/src/hook.ts

@@ -1,39 +1,14 @@
+import type {
+  AssistantTextMessage,
+  AssistantToolCallMessage,
+  ChatMessage,
+  UserMessage,
+} from '@stainless-api/ai-chat/src/types';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import { useCallback, useEffect, useReducer, useRef } from 'react';
 import { getChatResponse } from './api';
-import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { ResponseChunk } from './api/schemas';
 
-// Base
-type BaseMessage = { id: string };
-type BaseTextMessage = BaseMessage & { content: string };
-// User
-type UserMessage = BaseTextMessage & { role: 'user' };
-// Assistant
-type BaseAssistantMessage = BaseMessage & {
-  role: 'assistant';
-  respondingTo: UserMessage['id'];
-  messageType: ResponseChunk['type'];
-};
-type AssistantTextMessage = (BaseAssistantMessage & BaseTextMessage) & {
-  messageType: Extract<BaseAssistantMessage['messageType'], 'text'>;
-  isComplete: boolean;
-};
-type AssistantToolCallMessage = BaseAssistantMessage & {
-  messageType: Extract<BaseAssistantMessage['messageType'], 'tool_use'>;
-  toolName: string;
-  input: Record<string, unknown> | undefined;
-};
-type AssistantDoneMessage = BaseAssistantMessage & {
-  messageType: Extract<BaseAssistantMessage['messageType'], 'done'>;
-  spanId: string;
-};
-// All
-export type ChatMessage =
-  | UserMessage
-  | AssistantTextMessage
-  | AssistantToolCallMessage
-  | AssistantDoneMessage;
-
 //
 // Reducer
 //
@@ -63,7 +38,8 @@ type ChatReducerAction =
   | { type: 'completeMessage'; id: string }
   | { type: 'addAssistantToolCall'; message: Omit<AssistantToolCallMessage, 'role' | 'id'> }
   // a response potentially contains multiple messages / tool calls
-  | { type: 'completeResponse'; respondingTo: UserMessage['id']; spanId: string };
+  | { type: 'completeResponse'; respondingTo: UserMessage['id']; spanId: string }
+  | { type: 'addError'; respondingTo: UserMessage['id']; errorMessage: string };
 
 function chatReducer(state: ChatMessage[], action: ChatReducerAction) {
   if (action.type === 'addUserMessage') {
@@ -118,6 +94,16 @@ function chatReducer(state: ChatMessage[], action: ChatReducerAction) {
     } satisfies Extract<ChatMessage, { role: 'assistant' }>);
   }
 
+  if (action.type === 'addError') {
+    return spliceNewMessage(state, {
+      role: 'assistant',
+      id: crypto.randomUUID(),
+      messageType: 'error',
+      respondingTo: action.respondingTo,
+      errorMessage: action.errorMessage,
+    });
+  }
+
   return state;
 }
 
@@ -125,7 +111,15 @@ function chatReducer(state: ChatMessage[], action: ChatReducerAction) {
 // Consumable hook
 //
 
-export function useChat({ projectId, language }: { projectId: string; language: DocsLanguage }) {
+export function useChat({
+  projectId,
+  language,
+  siteTitle,
+}: {
+  projectId: string;
+  language: DocsLanguage;
+  siteTitle: string | undefined;
+}) {
   // Used to clean up stray streaming requests on unmount (prevent setState on unmounted component)
   const abortController = useRef(new AbortController());
   useEffect(() => {
@@ -136,6 +130,7 @@ export function useChat({ projectId, language }: { projectId: string; language:
     return () => ac.abort('Component unmounted');
   }, []);
 
+  const sessionId = useRef<string | undefined>(undefined);
   const [chatMessages, dispatch] = useReducer(chatReducer, []);
 
   /** Send a message and stream back the response in chat */
@@ -147,68 +142,78 @@ export function useChat({ projectId, language }: { projectId: string; language:
       let currentResponseId = crypto.randomUUID(); // for streaming text messages
       let lastChunkType: ResponseChunk['type'] | undefined = undefined;
 
-      for await (const chunk of getChatResponse(
-        {
-          query: question,
-          project: projectId,
-          language,
-          priorMessages: chatMessages.filter(
-            (msg) => msg.role === 'user' || (msg.role === 'assistant' && msg.messageType === 'text'),
-          ),
-        },
-        abortController.current.signal,
-      )) {
-        if (abortController.current.signal.aborted) break;
-
-        // mark complete when text messages finish streaming
-        if (lastChunkType === 'text' && chunk.type !== 'text') {
-          dispatch({ type: 'completeMessage', id: currentResponseId });
-        }
+      try {
+        for await (const chunk of getChatResponse(
+          {
+            query: question,
+            project: projectId,
+            language,
+            sessionId: sessionId.current,
+            siteTitle,
+          },
+          abortController.current.signal,
+        )) {
+          if (abortController.current.signal.aborted) break;
+
+          // store session id at start of session
+          if (chunk.type === 'start_session') {
+            sessionId.current = chunk.session_id;
+          }
 
-        if (chunk.type === 'done') {
-          dispatch({ type: 'completeResponse', respondingTo: userMessageId, spanId: chunk.span_id });
-          // stop reading from the stream on done
-          break;
-        }
+          // mark complete when text messages finish streaming
+          if (lastChunkType === 'text' && chunk.type !== 'text') {
+            dispatch({ type: 'completeMessage', id: currentResponseId });
+          }
+
+          if (chunk.type === 'done') {
+            dispatch({ type: 'completeResponse', respondingTo: userMessageId, spanId: chunk.span_id });
+            // stop reading from the stream on done
+            break;
+          }
+
+          if (chunk.type === 'text') {
+            if (lastChunkType !== 'text') {
+              // start a new text message
+              currentResponseId = crypto.randomUUID();
+              dispatch({
+                type: 'beginAssistantMessage',
+                message: {
+                  content: chunk.text,
+                  id: currentResponseId,
+                  messageType: chunk.type,
+                  respondingTo: userMessageId,
+                },
+              });
+            } else {
+              // continue the current message with the new content
+              dispatch({ type: 'streamMessage', id: currentResponseId, newContent: chunk.text });
+            }
+          }
 
-        if (chunk.type === 'text') {
-          if (lastChunkType !== 'text') {
-            // start a new text message
-            currentResponseId = crypto.randomUUID();
+          if (chunk.type === 'tool_use') {
             dispatch({
-              type: 'beginAssistantMessage',
+              type: 'addAssistantToolCall',
               message: {
-                content: chunk.text,
-                id: currentResponseId,
-                messageType: chunk.type,
                 respondingTo: userMessageId,
+                messageType: chunk.type,
+                toolName: chunk.name,
+                input: chunk.input,
               },
             });
-          } else {
-            // continue the current message with the new content
-            dispatch({ type: 'streamMessage', id: currentResponseId, newContent: chunk.text });
           }
-        }
 
-        if (chunk.type === 'tool_use') {
-          dispatch({
-            type: 'addAssistantToolCall',
-            message: {
-              respondingTo: userMessageId,
-              messageType: chunk.type,
-              toolName: chunk.name,
-              input: chunk.input,
-            },
-          });
+          lastChunkType = chunk.type;
         }
-
-        lastChunkType = chunk.type;
+      } catch {
+        dispatch({
+          type: 'addError',
+          respondingTo: userMessageId,
+          errorMessage: 'Something went wrong. Please try again.',
+        });
       }
     },
-    [language, projectId, chatMessages],
+    [language, projectId, siteTitle],
   );
 
-  // TODO: error handling
-
   return { chatMessages, sendMessage };
 }

package/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "jsx": "react-jsx"
   },
-  "include": ["src", "*.d.ts", "plugin.tsx"]
+  "include": ["src", "*.d.ts", "plugin.tsx", "*.config.*"]
 }

package/ambient-modules.d.ts

@@ -1,7 +0,0 @@
-import 'react';
-
-declare module 'react' {
-  interface CSSProperties {
-    [key: `--${string}`]: string | number;
-  }
-}