@aleph-alpha/chat-kit 5.11.0 → 5.12.0

package/src/components/composed/CkConversation/CkConversation.stories.ts

@@ -1,3 +1,5 @@
+import type { CkCitationSource } from '../../base/CkCitation';
+import { CkMarkdownRenderer } from '../../base/CkMarkdownRenderer';
 import { CkCopyMessageButton } from '../../base/CkCopyMessageButton';
 import { CkFeedbackButton } from '../../base/CkFeedbackButton';
 import type { CkFeedbackValue } from '../../base/CkFeedbackButton';
@@ -65,6 +67,53 @@ const markdownContent = [
   '| Feedback Integration | Planned | High |',
 ].join('\n');
 
+const citedAnswer = [
+  'Based on a review of internal documents, the rollout produced two measurable effects:',
+  '',
+  '- **Adoption:** Departments that received customized training saw a **25% higher adoption rate** of the new tools than those with generic training.[1]',
+  '- **Rework:** A lack of initial stakeholder engagement led to significant process rework during the first wave.[2]',
+  '',
+  'Both findings are consistent across the quarterly reviews.[1][2]',
+].join('\n');
+
+/** One entry per `[n]` reference in `citedAnswer`, keyed by `index`. */
+const citations: CkCitationSource[] = [
+  {
+    index: 1,
+    fileName: 'Q2_Business_Plan.pdf',
+    snippet:
+      'Departments that received customized training saw a 25% higher adoption rate of the new tools compared to those with generic training.',
+    locationLabel: 'Page 3',
+    url: '/api/v1/search-stores/ss_abc/files/file_123/public-urls',
+  },
+  {
+    index: 2,
+    fileName: 'Goal-planning-26.pdf',
+    snippet:
+      'Early stakeholder involvement remains the single strongest predictor of a rollout that does not require process rework.',
+    locationLabel: 'Page 12',
+  },
+];
+
+const citedMessages: BaseMessage[] = [
+  {
+    id: 'c1',
+    role: 'user',
+    content: [
+      text('What did we learn from the Digital Transformation rollout?'),
+    ],
+    createdAt: now,
+    status: 'completed',
+  },
+  {
+    id: 'c2',
+    role: 'assistant',
+    content: [text(citedAnswer)],
+    createdAt: now,
+    status: 'completed',
+  },
+];
+
 const sampleMessages: BaseMessage[] = [
   {
     id: '1',
@@ -384,6 +433,51 @@ function getMessageText(message: BaseMessage): string {
   </CkConversation>
 </template>`;
 
+const withCitationsTemplateSource = `<script setup lang="ts">
+import { CkConversation, CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+import type { BaseMessage, CkCitationSource } from '@aleph-alpha/chat-kit';
+
+const messages: BaseMessage[] = [/* ... */];
+
+// One entry per \`[n]\` reference in the answer, keyed by \`index\`. Keep the
+// array reference stable so the markdown processor isn't rebuilt on every
+// render.
+const citations: CkCitationSource[] = [
+  {
+    index: 1,
+    fileName: 'Q2_Business_Plan.pdf',
+    snippet: 'Departments that received customized training saw a 25% higher adoption rate.',
+    locationLabel: 'Page 3',
+    url: '/api/v1/search-stores/ss_abc/files/file_123/public-urls',
+  },
+];
+
+function getMessageText(message: BaseMessage): string {
+  return message.content
+    .filter((c) => c.type === 'text')
+    .map((c) => c.text)
+    .join('');
+}
+
+// The card's external-link action is only a request — the host performs the
+// (often auth-proxied) navigation.
+function openSource(url: string): void {
+  window.open(url, '_blank', 'noopener');
+}
+</script>
+
+<template>
+  <CkConversation :messages="messages" agent-avatar-fallback="AI" style="height: 100%;">
+    <template #agent-message-content="{ message }">
+      <CkMarkdownRenderer
+        :content="getMessageText(message)"
+        :citations="citations"
+        @open-source="openSource"
+      />
+    </template>
+  </CkConversation>
+</template>`;
+
 const streamingSimulationTemplateSource = `<script setup lang="ts">
 import { CkConversation } from '@aleph-alpha/chat-kit';
 import type { BaseMessage } from '@aleph-alpha/chat-kit';
@@ -910,6 +1004,48 @@ export const WithCustomAgentContent: Story = {
   },
 };
 
+/**
+ * Citations are opt-in: override `#agent-message-content` and hand the message's
+ * sources to `CkMarkdownRenderer`. Every `[n]` in the answer whose number
+ * matches a source's `index` becomes a marker that reveals the source on hover
+ * or keyboard activation; unmatched markers stay plain text. `open-source` is
+ * re-emitted for the host to perform the (often auth-proxied) navigation — the
+ * second source here has no `url`, so its card omits the action.
+ *
+ * The footer copy button is unaffected: it copies the message text, so the
+ * `[n]` references travel with a pasted answer.
+ */
+export const WithCitations: Story = {
+  render: () => ({
+    components: { CkConversation, CkMarkdownRenderer },
+    setup() {
+      function openSource(url: string) {
+        window.open(url, '_blank', 'noopener');
+      }
+      return {
+        messages: citedMessages,
+        citations,
+        getMessageText,
+        openSource,
+      };
+    },
+    template: `
+      <CkConversation :messages="messages" agent-avatar-fallback="AI" style="height: 100%;">
+        <template #agent-message-content="{ message }">
+          <CkMarkdownRenderer
+            :content="getMessageText(message)"
+            :citations="citations"
+            @open-source="openSource"
+          />
+        </template>
+      </CkConversation>
+    `,
+  }),
+  parameters: {
+    docs: { source: { code: withCitationsTemplateSource } },
+  },
+};
+
 /**
  * End-to-end streaming scenario: appending a new user message and then
  * streaming an assistant reply chunk-by-chunk. Use as a reference for wiring

package/src/components/index.ts

@@ -4,6 +4,7 @@ export {
   CkAgentMessageHeader,
   CkHeaderActivityButton,
   CkCitation,
+  CkCitationLabel,
   CkCitationCard,
   CkConversationLayout,
   CkCopyMessageButton,
@@ -34,6 +35,7 @@ export type {
   CkCitationProps,
   CkCitationEmits,
   CkCitationSource,
+  CkCitationLabelProps,
   CkCitationCardProps,
   CkCitationCardEmits,
   CkConversationLayoutProps,

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   CkAgentMessageHeader,
   CkHeaderActivityButton,
   CkCitation,
+  CkCitationLabel,
   CkCitationCard,
   CkConversation,
   CkConversationLayout,
@@ -106,6 +107,7 @@ export type {
   CkCitationProps,
   CkCitationEmits,
   CkCitationSource,
+  CkCitationLabelProps,
   CkCitationCardProps,
   CkCitationCardEmits,
   CkConversationLayoutProps,

package/src/types.ts

@@ -68,6 +68,36 @@ export type MessageContent =
   | MessageToolContent
   | MessageReasoningContent;
 
+declare global {
+  /**
+   * Extension point for {@link MessageMetadata}. Consumers declare their
+   * well-known metadata keys here and get them typed on every message,
+   * without chat-kit knowing what any of them mean:
+   *
+   * ```ts
+   * // app/src/types/chat-kit.d.ts
+   * declare global {
+   *   interface ChatKitMessageMetadata {
+   *     responseId?: string;
+   *     citations?: CitationManifest;
+   *   }
+   * }
+   * export {};
+   * ```
+   *
+   * Declare every key **optional**: chat-kit itself never populates them, and
+   * a message can reach a consumer before its host has stamped anything (mid
+   * stream, or on an optimistic node).
+   *
+   * This is a `declare global` interface rather than a module augmentation
+   * because `MessageMetadata` is re-exported through the package barrel —
+   * `declare module '@aleph-alpha/chat-kit'` does not merge across a
+   * re-export, and would silently type nothing.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface ChatKitMessageMetadata {}
+}
+
 /**
  * Open-ended metadata bag carried alongside a message. chat-kit is
  * intentionally agnostic about its contents — adapter authors
@@ -75,11 +105,11 @@ export type MessageContent =
  * through the tree → linear path projection, but never inspect it.
  *
  * Consumers attach their own well-known keys (attachments, citations,
- * ratings, …) and define their own typed projections at the read site
- * rather than extending this base type. That keeps the handler API stable
- * even as the shape of what gets stored on a message evolves.
+ * ratings, …). Declaring them on {@link ChatKitMessageMetadata} types those
+ * reads everywhere; the retained index signature keeps any other key legal,
+ * so the handler API stays stable as the stored shape evolves.
  */
-export type MessageMetadata = Record<string, unknown>;
+export type MessageMetadata = ChatKitMessageMetadata & Record<string, unknown>;
 
 export interface BaseMessage {
   id: string;