@stainless-api/docs-ai-chat 0.1.0-beta.6 → 0.1.0-beta.60

package/CHANGELOG.md

@@ -1,61 +1,292 @@
 # @stainless-api/docs-ai-chat
 
-## 0.1.0-beta.6
+## 0.1.0-beta.60
 
 ### Patch Changes
 
-- Updated dependencies
-  - @stainless-api/docs@0.1.0-beta.64
+- Updated dependencies [005419c]
+  - @stainless-api/docs-ui@0.1.0-beta.89
 
-## 0.1.0-beta.5
+## 0.1.0-beta.59
 
 ### 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 [af5a5d7]
+  - @stainless-api/docs-ui@0.1.0-beta.88
 
-## 0.1.0-beta.4
+## 0.1.0-beta.58
+
+### Minor Changes
+
+- f22893c: Add interactive examples to ai chat
+
+### Patch Changes
+
+- Updated dependencies [f22893c]
+  - @stainless-api/ai-chat@0.1.0-beta.13
+
+## 0.1.0-beta.57
+
+### Patch Changes
+
+- Updated dependencies [7701d8f]
+- Updated dependencies [5460e81]
+  - @stainless-api/docs-ui@0.1.0-beta.87
+
+## 0.1.0-beta.56
+
+### Patch Changes
+
+- Updated dependencies [d096f7d]
+  - @stainless-api/ai-chat@0.1.0-beta.12
+
+## 0.1.0-beta.55
+
+### Patch Changes
+
+- Updated dependencies [848cff4]
+- Updated dependencies [ea2b90c]
+  - @stainless-api/docs-ui@0.1.0-beta.86
+  - @stainless-api/ai-chat@0.1.0-beta.11
+
+## 0.1.0-beta.54
+
+### Patch Changes
+
+- Updated dependencies [93a3767]
+  - @stainless-api/docs-ui@0.1.0-beta.85
+
+## 0.1.0-beta.53
+
+### Patch Changes
+
+- Updated dependencies [438a593]
+  - @stainless-api/docs-ui@0.1.0-beta.84
+
+## 0.1.0-beta.52
+
+### Patch Changes
+
+- Updated dependencies [1c38511]
+  - @stainless-api/docs-ui@0.1.0-beta.83
+
+## 0.1.0-beta.51
 
 ### 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 [37cc2ac]
+  - @stainless-api/docs-ui@0.1.0-beta.82
 
-## 0.1.0-beta.3
+## 0.1.0-beta.50
 
 ### Patch Changes
 
-- 77c0d47: steelie: submit on enter
+- Updated dependencies [134885b]
+- Updated dependencies [5ba9135]
+- Updated dependencies [df0c958]
+- Updated dependencies [e641d33]
+  - @stainless-api/docs-ui@0.1.0-beta.81
 
-## 0.1.0-beta.2
+## 0.1.0-beta.49
 
 ### 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 [05cd046]
+  - @stainless-api/docs-ui@0.1.0-beta.80
 
-## 0.1.0-beta.1
+## 0.1.0-beta.48
+
+### Patch Changes
+
+- 8838d9f: remember presentation when window shrinks
+- Updated dependencies [8838d9f]
+  - @stainless-api/ai-chat@0.1.0-beta.10
+
+## 0.1.0-beta.47
+
+### Minor Changes
+
+- a8ed299: Adds the ability for AI chat to move into a sidebar “panel” position.
+
+### Patch Changes
+
+- Updated dependencies [5b3b798]
+- Updated dependencies [a8ed299]
+  - @stainless-api/ai-chat@0.1.0-beta.9
+
+## 0.1.0-beta.46
 
 ### Minor Changes
 
-- 2d00f0d: first version of docs-ai-chat
+- 9d24589: Steelie empty state
+- 5263b85: Loading state for ai chat
+
+### Patch Changes
+
+- 9d24589: Various steelie UI fixes
+- Updated dependencies [9d24589]
+- Updated dependencies [9d24589]
+- Updated dependencies [5263b85]
+  - @stainless-api/ai-chat@0.1.0-beta.8
+
+## 0.1.0-beta.45
+
+### Patch Changes
+
+- Updated dependencies [6d9933d]
+  - @stainless-api/docs-ui@0.1.0-beta.79
+  - @stainless-api/ai-chat@0.1.0-beta.7
+
+## 0.1.0-beta.44
+
+### Patch Changes
+
+- Updated dependencies [54add64]
+  - @stainless-api/docs-ui@0.1.0-beta.78
+
+## 0.1.0-beta.43
+
+### Patch Changes
+
+- Updated dependencies [21e50d3]
+  - @stainless-api/docs-ui@0.1.0-beta.77
+
+## 0.1.0-beta.42
+
+### Patch Changes
+
+- Updated dependencies [95fe66c]
+- Updated dependencies [5701494]
+  - @stainless-api/docs-ui@0.1.0-beta.76
+  - @stainless-api/ai-chat@0.1.0-beta.6
+
+## 0.1.0-beta.41
+
+### Patch Changes
+
+- 6e762e2: fix steelie for multi-turn conversations
+
+## 0.1.0-beta.40
+
+### Patch Changes
+
+- Updated dependencies [2919b0a]
+- Updated dependencies [e005e5c]
+  - @stainless-api/docs-ui@0.1.0-beta.75
+
+## 0.1.0-beta.39
+
+### Patch Changes
+
+- Updated dependencies [415629f]
+  - @stainless-api/docs-ui@0.1.0-beta.74
+
+## 0.1.0-beta.38
+
+### Patch Changes
+
+- Updated dependencies [5c36876]
+  - @stainless-api/docs-ui@0.1.0-beta.73
+
+## 0.1.0-beta.37
+
+### Patch Changes
+
+- Updated dependencies [6b86a8b]
+  - @stainless-api/docs-ui@0.1.0-beta.72
+
+## 0.1.0-beta.36
+
+### Patch Changes
+
+- Updated dependencies [cd578b7]
+  - @stainless-api/docs-ui@0.1.0-beta.71
+
+## 0.1.0-beta.35
+
+### 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
+
+## 0.1.0-beta.33
+
+### Patch Changes
+
+- Updated dependencies [a3f1ede]
+  - @stainless-api/docs-ui@0.1.0-beta.68
+
+## 0.1.0-beta.32
+
+### Patch Changes
+
+- @stainless-api/ai-chat@0.1.0-beta.5
+- @stainless-api/docs-ui@0.1.0-beta.67
+
+## 0.1.0-beta.31
+
+### Patch Changes
+
+- 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.30
+
+### Patch Changes
+
+- 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.29
+
+### Patch Changes
+
+- 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.28
+
+### Patch Changes
+
+- Updated dependencies [274cefc]
+  - @stainless-api/docs-ui@0.1.0-beta.63
+
+## 0.1.0-beta.27
+
+### Patch Changes
+
+- 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.26
+
+### Patch Changes
+
+- Updated dependencies [7155fae]
+  - @stainless-api/ai-chat@0.1.0-beta.2
+  - @stainless-api/docs-ui@0.1.0-beta.61
+
+## 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/ambient.d.ts

@@ -2,3 +2,9 @@ declare module '*.module.css' {
   const classes: { [key: string]: string };
   export default classes;
 }
+
+declare module 'virtual:stl-docs-ai-chat-examples' {
+  import type { ExamplePrompt } from '@stainless-api/ai-chat/src/types';
+
+  export const examples: ExamplePrompt[] | undefined;
+}

package/eslint.config.ts

@@ -0,0 +1,2 @@
+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.6",
+  "version": "0.1.0-beta.60",
   "publishConfig": {
     "access": "public"
   },
@@ -8,25 +8,16 @@
   "peerDependencies": {
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
-    "@stainless-api/docs": "0.1.0-beta.64",
-    "@stainless-api/docs-ui": "0.1.0-beta.52",
-    "@stainless-api/ui-primitives": "0.1.0-beta.39"
+    "@stainless-api/docs-ui": "0.1.0-beta.89"
   },
   "dependencies": {
     "@streamparser/json-whatwg": "^0.0.22",
-    "clsx": "^2.1.1",
-    "lucide-react": "^0.561.0",
-    "motion": "^12.23.25",
-    "react": "^19.2.3",
-    "react-markdown": "^10.1.0",
-    "react-syntax-highlighter": "^16.1.0",
-    "remend": "^1.0.1",
-    "zod": "^4.1.13"
+    "zod": "^4.3.6",
+    "@stainless-api/ai-chat": "0.1.0-beta.13"
   },
   "devDependencies": {
-    "@types/react": "19.2.7",
+    "@types/react": "19.2.14",
     "@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,12 +25,12 @@
     "./plugin": {
       "import": "./plugin.tsx"
     },
-    "./src/AiChat.tsx": {
-      "import": "./src/AiChat.tsx"
+    "./src/DocsChat.tsx": {
+      "import": "./src/DocsChat.tsx"
     }
   },
   "scripts": {
-    "lint": "eslint .",
+    "lint": "eslint --flag unstable_native_nodejs_ts_config .",
     "check:types": "tsc --noEmit"
   }
 }

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,60 @@
+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 { useSyncExternalStore } from 'react';
+import { useChat } from './hook';
+
+const examplesPromise = import('virtual:stl-docs-ai-chat-examples')
+  .then((mod) => mod.examples)
+  .catch(() => undefined);
+
+function onCopyMessage(spanId: string) {
+  setResponseMetadata(spanId, { copied_to_clipboard: 'true' }).catch(() => {});
+}
+
+async function rateMessage(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;
+  }
+}
+
+export default function DocsChat({
+  projectId,
+  language,
+  siteTitle,
+}: {
+  projectId: string;
+  language: DocsLanguage | undefined;
+  siteTitle: string | undefined;
+}) {
+  const { chatMessages, sendMessage } = useChat({
+    projectId,
+    language: language ?? 'http',
+    siteTitle,
+  });
+
+  // panel mode is supported only on larger viewports
+  const supportsPanel = useSyncExternalStore(
+    (cb) => {
+      window.addEventListener('resize', cb);
+      return () => window.removeEventListener('resize', cb);
+    },
+    () => window.innerWidth >= 968,
+    () => false,
+  );
+
+  return (
+    <AiChat
+      chatMessages={chatMessages}
+      sendMessage={sendMessage}
+      rateMessage={rateMessage}
+      onCopyMessage={onCopyMessage}
+      siteTitle={siteTitle}
+      promptExamples={examplesPromise}
+      supportsPanel={supportsPanel}
+    />
+  );
+}

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,9 +1,37 @@
 import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import { JSONParser } from '@streamparser/json-whatwg';
-import { type RequestBody, responseChunk } 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 CHAT_ENDPOINT = 'https://app.stainless.com/api/ai/get-agentic-help';
+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
@@ -14,15 +42,17 @@ export async function* getChatResponse(
     project,
     language,
     priorMessages,
+    siteTitle,
   }: {
     query: string;
     project: string;
     language: DocsLanguage;
     priorMessages: NonNullable<RequestBody['additionalContext']>['prior_messages'];
+    siteTitle: string | undefined;
   },
   abortSignal: AbortSignal,
 ) {
-  const req = await fetch(CHAT_ENDPOINT, {
+  const res = await fetch(CHAT_ENDPOINT, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
@@ -31,17 +61,53 @@ export async function* getChatResponse(
       query,
       sdk: { project, language },
       stream: true,
-      additionalContext: { prior_messages: priorMessages },
+      additionalContext: {
+        prior_messages: priorMessages,
+        intent: getPageContext({ siteTitle }),
+      },
+      browser_id: getClientId(),
     } satisfies RequestBody),
 
     signal: abortSignal,
   });
 
-  if (!req.ok || !req.body) throw new Error(`Chat request failed with status ${req.status}`);
+  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(req.body.pipeThrough(parser))) {
+  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
+ */
+export async function submitResponseFeedback(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 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,6 +14,7 @@ export const requestBody = z.object({
       maxTokens: z.number().optional(),
     })
     .optional(),
+  session_id: z.string().optional(),
   additionalContext: z
     .object({
       prior_messages: z.array(
@@ -28,6 +29,7 @@ export const requestBody = z.object({
       errors: z.string().optional(),
     })
     .optional(),
+  browser_id: z.string().optional(),
 });
 export type RequestBody = z.input<typeof requestBody>;
 
@@ -48,6 +50,19 @@ export const responseChunk = z.discriminatedUnion('type', [
   }),
   z.object({
     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() });