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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @stainless-api/docs-ai-chat
 
+## 0.1.0-beta.8
+
+### Minor Changes
+
+- 883ad46: Add UI for providing feedback on chat responses
+
+### Patch Changes
+
+- Updated dependencies [af54129]
+  - @stainless-api/docs@0.1.0-beta.66
+
+## 0.1.0-beta.7
+
+### Patch Changes
+
+- Updated dependencies [22a19ed]
+  - @stainless-api/docs@0.1.0-beta.65
+
 ## 0.1.0-beta.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs-ai-chat",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.8",
   "publishConfig": {
     "access": "public"
   },
@@ -8,20 +8,20 @@
   "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": "0.1.0-beta.66",
+    "@stainless-api/ui-primitives": "0.1.0-beta.39",
+    "@stainless-api/docs-ui": "0.1.0-beta.52"
   },
   "dependencies": {
     "@streamparser/json-whatwg": "^0.0.22",
     "clsx": "^2.1.1",
-    "lucide-react": "^0.561.0",
-    "motion": "^12.23.25",
+    "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.1.13"
+    "zod": "^4.3.5"
   },
   "devDependencies": {
     "@types/react": "19.2.7",

package/src/AiChat.module.css

@@ -219,3 +219,21 @@
     }
   }
 }
+
+.feedback-buttons {
+  display: flex;
+  gap: 0.15rem;
+  margin-top: -0.25rem;
+
+  button:global(.stl-ui-button.stl-ui-button--ghost) {
+    svg {
+      opacity: var(--stl-opacity-level-040);
+    }
+    &:hover,
+    &.active {
+      svg {
+        opacity: var(--stl-opacity-level-080);
+      }
+    }
+  }
+}

package/src/AiChat.tsx

@@ -30,9 +30,8 @@ export default function DocsChat({
     const ac = new AbortController();
     // “focus” in/out with click
     window.addEventListener('click', (e) => {
-      if (!(e.target instanceof Element)) return;
-      if (baseRef.current?.contains(e.target)) { setFocused(true); }
-      else { setFocused(false); }
+      if (!(e.target instanceof Element) || !baseRef.current || !document.contains(e.target)) return;
+      setFocused(baseRef.current.contains(e.target));
     }, { signal: ac.signal });
     // leave with escape
     document.addEventListener('keydown', (e) => {
@@ -45,8 +44,8 @@ export default function DocsChat({
     // record focus state when our chat elements receive focus
     // unfocus when another element outside of our component gets focus (incl. by keyboard)
     document.addEventListener('focusin', (e) => {
-      if (!(e.target instanceof HTMLElement) || !baseRef.current) return;
-      setFocused(baseRef.current.contains(e.target) ?? false);
+      if (!(e.target instanceof Element) || !baseRef.current || !document.contains(e.target)) return;
+      setFocused(baseRef.current.contains(e.target));
     }, { signal: ac.signal });
     return () => ac.abort();
   }, []);

package/src/api/index.ts

@@ -1,9 +1,12 @@
 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 } from './schemas';
 import { streamAsyncIterator } from './util';
 
-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);
 
 /**
  * Stream chat response from the server
@@ -22,7 +25,7 @@ export async function* getChatResponse(
   },
   abortSignal: AbortSignal,
 ) {
-  const req = await fetch(CHAT_ENDPOINT, {
+  const res = await fetch(CHAT_ENDPOINT, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
@@ -37,11 +40,27 @@ export async function* getChatResponse(
     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());
+}

package/src/api/schemas.ts

@@ -48,6 +48,11 @@ export const responseChunk = z.discriminatedUnion('type', [
   }),
   z.object({
     type: z.literal('done'),
+    span_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() });

package/src/components/ChatLog.tsx

@@ -1,6 +1,7 @@
 import type { ChatMessage } from '../hook';
 import Message from './ChatMessage';
 import ToolCall from './ToolCall';
+import MessageFeedbackButtons from './MessageFeedback';
 
 import { motion } from 'motion/react';
 
@@ -36,6 +37,25 @@ export default function ChatLog({ messages }: { messages: ChatMessage[] }) {
         if (msg.role === 'assistant' && msg.messageType === 'tool_use') {
           return <ToolCall key={msg.id} message={msg} />;
         }
+
+        if (msg.role === 'assistant' && msg.messageType === 'done') {
+          return (
+            <MessageFeedbackButtons
+              key={msg.id}
+              spanId={msg.spanId}
+              // all “text” responses to the given message
+              messages={messages.flatMap((msg2) =>
+                msg2.role === 'assistant' &&
+                msg2.respondingTo === msg.respondingTo &&
+                msg2.messageType === 'text'
+                  ? msg2
+                  : [],
+              )}
+            />
+          );
+        }
+
+        return null;
       })}
     </motion.ul>
   );

package/src/components/MessageFeedback.tsx

@@ -0,0 +1,100 @@
+import { useState, useCallback, useOptimistic, startTransition } from 'react';
+import { motion } from 'motion/react';
+import { ThumbsUpIcon, ThumbsDownIcon, CopyIcon, CheckIcon } from 'lucide-react';
+import { Button } from '@stainless-api/docs/components';
+import { submitResponseFeedback } from '../api';
+
+import type { ChatMessage } from '../hook';
+
+import styles from '../AiChat.module.css';
+import clsx from 'clsx';
+
+type AssistantMessage = Extract<ChatMessage, { role: 'assistant'; messageType: 'text' }>;
+
+export default function MessageFeedbackButtons({
+  spanId,
+  messages,
+}: {
+  spanId: string;
+  messages: AssistantMessage[];
+}) {
+  // Copy response as markdown
+  const [copied, setCopied] = useState(false);
+  const copyMarkdown = useCallback(() => {
+    const combinedText = messages.map((msg) => msg.content).join('\n\n');
+    navigator.clipboard
+      .writeText(combinedText)
+      .then(() => {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      })
+      .catch(() => {
+        setCopied(false);
+      });
+  }, [messages]);
+
+  // Provide message rating
+  const [rating, setRating] = useState<'up' | 'down' | null>(null);
+  const [optimisticRating, setOptimisticRating] = useOptimistic(
+    rating,
+    (current, newRating: NonNullable<typeof rating>) => newRating,
+  );
+  const rateMessage = useCallback(
+    (rating: 'up' | 'down') => {
+      startTransition(async () => {
+        setOptimisticRating(rating);
+        const { success } = await submitResponseFeedback(
+          spanId,
+          { up: 1 as const, down: 0 as const }[rating],
+        ).catch(() => ({ success: false }));
+        if (success) setRating(rating);
+      });
+    },
+    [spanId, setOptimisticRating],
+  );
+
+  return (
+    <motion.li
+      layout="position"
+      data-message-role="assistant"
+      className={clsx(styles['chat-message'], styles['feedback-buttons'])}
+    >
+      <Button
+        type="button"
+        variant="ghost"
+        size="sm"
+        onClick={() => rateMessage('up')}
+        className={clsx(optimisticRating === 'up' && styles.active)}
+      >
+        <Button.Icon icon={ThumbsUpIcon} aria-label="Thumbs up" size={15} />
+      </Button>
+
+      <Button
+        type="button"
+        variant="ghost"
+        size="sm"
+        onClick={() => rateMessage('down')}
+        className={clsx(optimisticRating === 'down' && styles.active)}
+      >
+        <Button.Icon icon={ThumbsDownIcon} aria-label="Thumbs down" size={15} />
+      </Button>
+
+      {messages.length > 0 && messages.some((msg) => msg.content.trim().length) && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={copyMarkdown}
+          className={clsx(copied && styles.active)}
+        >
+          <Button.Icon
+            // TODO: nicer cross-fade transition
+            icon={copied ? CheckIcon : CopyIcon}
+            aria-label={copied ? 'Copied' : 'Copy response'}
+            size={15}
+          />
+        </Button>
+      )}
+    </motion.li>
+  );
+}

package/src/hook.ts

@@ -23,8 +23,16 @@ type AssistantToolCallMessage = BaseAssistantMessage & {
   toolName: string;
   input: Record<string, unknown> | undefined;
 };
+type AssistantDoneMessage = BaseAssistantMessage & {
+  messageType: Extract<BaseAssistantMessage['messageType'], 'done'>;
+  spanId: string;
+};
 // All
-export type ChatMessage = UserMessage | AssistantTextMessage | AssistantToolCallMessage;
+export type ChatMessage =
+  | UserMessage
+  | AssistantTextMessage
+  | AssistantToolCallMessage
+  | AssistantDoneMessage;
 
 //
 // Reducer
@@ -53,7 +61,9 @@ type ChatReducerAction =
   | { type: 'beginAssistantMessage'; message: Omit<AssistantTextMessage, 'role' | 'isComplete'> }
   | { type: 'streamMessage'; id: string; newContent: string }
   | { type: 'completeMessage'; id: string }
-  | { type: 'addAssistantToolCall'; message: Omit<AssistantToolCallMessage, 'role' | 'id'> };
+  | { type: 'addAssistantToolCall'; message: Omit<AssistantToolCallMessage, 'role' | 'id'> }
+  // a response potentially contains multiple messages / tool calls
+  | { type: 'completeResponse'; respondingTo: UserMessage['id']; spanId: string };
 
 function chatReducer(state: ChatMessage[], action: ChatReducerAction) {
   if (action.type === 'addUserMessage') {
@@ -98,6 +108,16 @@ function chatReducer(state: ChatMessage[], action: ChatReducerAction) {
     });
   }
 
+  if (action.type === 'completeResponse') {
+    return spliceNewMessage(state, {
+      role: 'assistant',
+      id: crypto.randomUUID(),
+      messageType: 'done',
+      respondingTo: action.respondingTo,
+      spanId: action.spanId,
+    } satisfies Extract<ChatMessage, { role: 'assistant' }>);
+  }
+
   return state;
 }
 
@@ -145,9 +165,11 @@ export function useChat({ projectId, language }: { projectId: string; language:
           dispatch({ type: 'completeMessage', id: currentResponseId });
         }
 
-        // stop reading from the stream on done
-        // TODO: record 'done' in the state so that we can render feedback buttons
-        if (chunk.type === 'done') break;
+        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') {