From 271d4232f06c756836f1b49167d5b7268137326d Mon Sep 17 00:00:00 2001 From: Mike Christensen Date: Wed, 14 Jan 2026 18:01:19 +0000 Subject: [PATCH] ait/features: misc. fixes to citations docs --- src/data/nav/aitransport.ts | 2 +- .../features/advanced/citations.mdx | 339 ------------------ .../features/messaging/citations.mdx | 259 +++++++++++++ .../token-streaming/message-per-response.mdx | 4 +- .../anthropic-message-per-response.mdx | 2 +- .../openai-message-per-response.mdx | 2 +- 6 files changed, 264 insertions(+), 344 deletions(-) delete mode 100644 src/pages/docs/ai-transport/features/advanced/citations.mdx create mode 100644 src/pages/docs/ai-transport/features/messaging/citations.mdx diff --git a/src/data/nav/aitransport.ts b/src/data/nav/aitransport.ts index 94409a7b78..e049109ea2 100644 --- a/src/data/nav/aitransport.ts +++ b/src/data/nav/aitransport.ts @@ -78,7 +78,7 @@ export default { }, { name: 'Citations', - link: '/docs/ai-transport/features/advanced/citations', + link: '/docs/ai-transport/features/messaging/citations', }, ], }, diff --git a/src/pages/docs/ai-transport/features/advanced/citations.mdx b/src/pages/docs/ai-transport/features/advanced/citations.mdx deleted file mode 100644 index 6007d504f4..0000000000 --- a/src/pages/docs/ai-transport/features/advanced/citations.mdx +++ /dev/null @@ -1,339 +0,0 @@ ---- -title: "Citations" -meta_description: "Attach source citations to AI responses using message annotations" -meta_keywords: "citations, references, RAG, retrieval augmented generation, source attribution, message annotations, AI transparency, source tracking, annotation summaries, model-agnostic, LLM-neutral" ---- - -AI agents often draw information from external sources such as documents, web pages, or databases. Citations to those sources enable users to verify information, explore sources in detail, and understand where responses came from. Ably's [message annotations](/docs/messages/annotations) provide a model-agnostic, structured way to attach source citations to AI responses without modifying the response content. It enable clients to append information to existing messages on a channel. - -This pattern works with both single message publishing and the [message-per-response](/docs/ai-transport/message-per-response) approach using message appends. - -## Why citations matter - -Citations serve several critical purposes in AI applications: - -**Transparency**: Users can verify claims and understand the basis for AI responses. This builds trust and allows users to fact-check information independently. - -**Source exploration**: Citations enable users to dive deeper into topics by accessing original sources. This is particularly valuable for research, learning, and decision-making workflows. - -**Attribution**: Proper attribution respects content creators and helps users understand which sources informed the AI's response. - -**Audit trails**: For enterprise applications, citations provide an audit trail showing which information sources were consulted during AI interactions. - -## How it works - -Citations use Ably's [message annotations](/docs/messages/annotations) feature to attach source metadata to AI response messages without modifying the response content. - -The annotation publishing workflow: - -1. **Publish response**: Agent publishes an AI response as a single message or builds it incrementally using [message appends](/docs/ai-transport/message-per-response) -2. **Publish citation annotations**: Agent publishes one or more citation annotations, each referencing the response message serial -3. **Aggregate summaries**: Ably automatically aggregates annotations and generates summaries showing total counts and groupings (e.g., by domain) -4. **Subscribe citations**: Clients receive citation summaries automatically and can optionally subscribe to individual annotation events for detailed citation data as part of the realtime stream. Alternatively, clients can obtain annotations for a given message via the REST API. - -Annotations are associated with a message's `serial` identifier. This works with: - -- **Single message publish**: Complete response published as one message -- **Message appends**: Response built incrementally by appending tokens to a single message (see [message-per-response](/docs/ai-transport/message-per-response)) - -## Setup - -Message annotations require the "Message annotations, updates, deletes, and appends" [channel rule](/docs/channels#rules) enabled for your channel or [namespace](/docs/channels#namespaces). This rule automatically enables message persistence. - -To enable the channel rule: - -1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app. -2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar. -3. Choose "Add new rule". -4. Enter a channel name or namespace pattern (e.g. `ai:*` for all channels starting with `ai:`). -5. Select the "Message annotations, updates, and deletes" rule from the list. -6. Click "Create channel rule". - -The examples in this guide use the `ai:` namespace prefix, which assumes you have configured the rule for `ai:*`. - -## Citation data model - -### Annotation type - -Use the `citations:multiple.v1` annotation type for citation features. It provides: - -- **Automatic grouping**: Citations are grouped by the `name` field (for example, grouping by domain) -- **Count aggregation**: Ably counts how many citations come from each source -- **Efficient summaries**: Clients receive grouped summaries without processing individual events - -### Citation payload - -Each citation is proposed to be carried in the Ably annotation `data` field and should include, for example: - - -```json -{ - "url": "https://example.com/article", - "title": "Example Article Title", - "startOffset": 120, - "endOffset": 180, - "snippet": "Optional short excerpt from source" -} -``` - - -**Field descriptions**: - -- `url`: The source URL (required) -- `title`: Human-readable source title (required) -- `startOffset`: Character position in the LLM generated response where this citation begins to apply, enabling clients to associate citations with specific portions of the response text (optional) -- `endOffset`: Character position where the citation’s applicability ends, used together with `startOffset` to define a citation range (optional) -- `snippet`: Short excerpt from the source content, intended for preview, tooltip, or summary displays without requiring a full page fetch (optional) - -Character offsets allow UIs to attach inline citation markers to specific portions of the response text. - -## Publishing citations from agents - -Agents publish citations as annotation messages that reference the `serial` of the response message they relate to. This allows clients to associate citations with the correct response message. - -Citations can be published once the response has been sent, or progressively during streaming if citation data becomes available earlier. For incremental streaming using message appends, see [message-per-response](/docs/ai-transport/message-per-response). - -### Publishing a single citation - - -```javascript -const channel = ably.channels.get('ai:{{RANDOM_CHANNEL_NAME}}'); - -// Publish the AI response -const responseText = "The James Webb Space Telescope launched in December 2021."; -const { serials: [messageSerial] } = await channel.publish('ai-response', { - data: responseText -}); - -// Publish a citation annotation -await channel.annotations.publish(messageSerial, { - type: 'citations:multiple.v1', - name: 'science.nasa.gov', - data: { - url: 'https://science.nasa.gov/mission/webb/', - title: 'Webb Mission Overview - NASA Science', - startOffset: 0, - endOffset: 56, - snippet: 'The James Webb Space Telescope launched on December 25, 2021 from Europe\'s Spaceport in French Guiana.' - } -}); -``` - - -### Publishing multiple citations - - -```javascript -const channel = ably.channels.get('ai:{{RANDOM_CHANNEL_NAME}}'); - -// Publish multiple citations -async function publishCitations(messageSerial, sources) { - for (const source of sources) { - await channel.annotations.publish(messageSerial, { - type: 'citations:multiple.v1', - name: new URL(source.url).hostname, - data: { - url: source.url, - title: source.title, - startOffset: source.startOffset, - endOffset: source.endOffset, - snippet: source.snippet - } - }); - } -} - -// Publish response with citations -async function publishResponseWithCitations() { - // Publish the AI response - const responseText = "The James Webb Space Telescope launched in December 2021 and captured its first images in July 2022."; - const { serials: [messageSerial] } = await channel.publish('ai-response', { - data: responseText - }); - - // Define citation sources - const sources = [ - { - url: 'https://science.nasa.gov/mission/webb/', - title: 'Webb Mission Overview - NASA Science', - startOffset: 0, - endOffset: 56, - snippet: 'The James Webb Space Telescope launched on December 25, 2021 from Europe\'s Spaceport in French Guiana.' - }, - { - url: 'https://en.wikipedia.org/wiki/James_Webb_Space_Telescope', - title: 'James Webb Space Telescope - Wikipedia', - startOffset: 61, - endOffset: 107, - snippet: 'The telescope captured its first images in July 2022, revealing unprecedented detail...' - } - ]; - - // Publish citations - await publishCitations(messageSerial, sources); - - return messageSerial; -} -``` - - -## Subscribing citations for clients - -Clients subscribe citations from Ably in two ways: - -1. **Summary view** (default): Aggregate counts from Ably `message.summary` events -2. **Raw view** (on demand): Individual citation details from Ably annotation events - -### Summary view - -Subscribe to Ably channels normally to receive automatic annotation summaries: - - -```javascript -const channel = ably.channels.get('ai:{{RANDOM_CHANNEL_NAME}}'); - -// Track responses -const responses = new Map(); - -// Subscribe to receive messages and summaries -await channel.subscribe((message) => { - switch (message.action) { - case 'message.create': - // New response started - responses.set(message.serial, message.data); - break; - - case 'message.summary': - // Citation summary - const citations = message.annotations?.summary?.['citations:multiple.v1']; - if (citations) { - console.log('Citation summary:', citations); - } - break; - } -}); -``` - - -**Citation summary structure:** - -The summary is included in an `annotations.summary` field within the message and is an object whose keys are the annotation types and whose values describe the annotation summary for that type. - - -```json -{ - "citations:multiple.v1": { - "science.nasa.gov": { - "total": 1, - "clientIds": { - "test-publisher": 1 - }, - "totalUnidentified": 0, - "totalClientIds": 1, - "clipped": false - }, - "en.wikipedia.org": { - "total": 1, - "clientIds": { - "test-publisher": 1 - }, - "totalUnidentified": 0, - "totalClientIds": 1, - "clipped": false - } - } -} -``` - - -**Key fields:** -- `total`: Total count of annotations for this group -- `clientIds`: Breakdown showing which clients published annotations -- `clipped`: Whether the summary was truncated due to size limits - -Ably summary view provides: - -- **Total citation count**: Sum of all citation counts across groups -- **Group breakdown**: Count of citations per group (e.g., per domain) -- **Efficient updates**: Ably summaries update automatically as citations are added - -### Raw view - -To access individual citation details from Ably, subscribe to annotation events: - - -```javascript -// Enable ANNOTATION_SUBSCRIBE mode -const channel = ably.channels.get('ai:{{RANDOM_CHANNEL_NAME}}', { - modes: ['ANNOTATION_SUBSCRIBE'] -}); - -// Subscribe to annotation events -await channel.annotations.subscribe((annotation) => { - if (annotation.action === 'annotation.create' && - annotation.type === 'citations:multiple.v1') { - const citation = annotation.data; - if (citation) { - console.log('Citation data:', citation); - } - } -}); -``` - - -**Example raw annotation structure:** - -When you subscribe to raw annotations, each annotation event has the following structure: - - -```json -{ - "action": "annotation.create", - "clientId": "test-publisher", - "type": "citations:multiple.v1", - "serial": "01767705527528-000@108rFDTSQBxhtu98297114:000", - "messageSerial": "01767638186693-000@108SP4XcgBxfMO07491612:000", - "connectionId": "Y8CqupU0-E", - "name": "en.wikipedia.org", - "count": 1, - "encoding": null, - "data": { - "url": "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope", - "title": "James Webb Space Telescope - Wikipedia", - "startOffset": 61, - "endOffset": 107, - "snippet": "The telescope captured its first images in July 2022, revealing unprecedented detail of the early universe." - }, - "timestamp": 1767705527528, - "id": "Y8CqupU0-E:1:0" -} -``` - - -**Key fields in raw annotations:** - -- `action`: Always `"annotation.create"` for new annotations -- `type`: The annotation `type` (`citations:multiple.v1`) -- `messageSerial`: The `serial` of the message this citation is attached to -- `name`: The grouping key (e.g., domain name) -- `data`: Your citation payload with URL, title, offsets, snippet -- `clientId`: The client that published the annotation - -Ably raw citations provide: - -- **Full citation metadata**: All fields from the citation data payload -- **Character offsets**: For placing inline citation markers -- **Group name**: The `name` field used for grouping (e.g., domain) -- **Individual events**: Each citation arrives as a separate Ably event - - - -## Related topics - -- [Message annotations](/docs/messages/annotations) - Core Ably feature for attaching metadata to messages -- [Message per response](/docs/ai-transport/message-per-response) - Streaming pattern using Ably message appends -- [Token streaming](/docs/ai-transport/token-streaming) - Alternative approach with granular Ably history diff --git a/src/pages/docs/ai-transport/features/messaging/citations.mdx b/src/pages/docs/ai-transport/features/messaging/citations.mdx new file mode 100644 index 0000000000..d44f85e614 --- /dev/null +++ b/src/pages/docs/ai-transport/features/messaging/citations.mdx @@ -0,0 +1,259 @@ +--- +title: "Citations" +meta_description: "Attach source citations to AI responses using message annotations" +meta_keywords: "citations, references, source attribution, message annotations, AI transparency, source tracking, annotation summaries" +--- + +AI agents often draw information from external sources such as documents, web pages, or databases. Citations to those sources enable users to verify information, explore sources in detail, and understand where responses came from. Ably's [message annotations](/docs/messages/annotations) provide a model-agnostic, structured way to attach source citations to AI responses without modifying the response content. It enables clients to append information to existing messages on a channel. + +This pattern works when publishing complete responses as messages on a channel or when streaming responses using the [message-per-response](/docs/ai-transport/message-per-response) pattern. + +## Why citations matter + +Including citations on AI responses provides: + +- Transparency: Users can verify claims and understand the basis for AI responses. This builds trust and allows users to fact-check information independently. +- Source exploration: Citations enable users to dive deeper into topics by accessing original sources. This is particularly valuable for research, learning, and decision-making workflows. +- Attribution: Proper attribution respects content creators and helps users understand which sources informed the AI's response. +- Audit trails: For enterprise applications, citations provide explicit traceability between LLM responses and the information sources that were consulted when generating them. + +## How it works + +Use [message annotations](/docs/messages/annotations) to attach source metadata to AI response messages without modifying the response content: + +1. The agent publishes an AI response as a single message, or builds it incrementally using [message appends](/docs/ai-transport/message-per-response). +2. The agent publishes one or more annotations to attach citations to the response message, each referencing the response message [`serial`](/docs/messages#properties). +3. Ably automatically aggregates annotations and generates summaries showing total counts and groupings (for example, by source domain name). +4. Clients receive citation summaries automatically and can optionally subscribe to individual annotation events for detailed citation data as part of the realtime stream. Alternatively, clients can obtain annotations for a given message via the REST API. + +## Enable message annotations + +Message append functionality requires "Message annotations, updates, deletes and appends" to be enabled in a [channel rule](/docs/channels#rules) associated with the channel. + + + +To enable the channel rule: + +1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app. +2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar. +3. Choose "Add new rule". +4. Enter a channel name or namespace pattern (e.g. `ai` for all channels starting with `ai:`). +5. Select the "Message annotations, updates, deletes and appends" option from the list. +6. Click "Create channel rule". + +The examples in this guide use the `ai:` namespace prefix, which assumes you have configured the rule for `ai`. + + + +## Citation data model + +Citations are implemented using [message annotations](/docs/messages/annotations). Each citation includes an annotation `type` that determines how citations are aggregated into summaries, and a `data` payload containing the citation details. + +### Annotation type + +[Annotation types](/docs/messages/annotations#annotation-types) determine how annotations are processed and aggregated into summaries. The type is a string of the format `namespace:summarization_method`: + +- `namespace` is a string that logically groups related annotations. For example, use `citations` for AI response citations. +- `summarization_method` specifies how annotations are aggregated to produce summaries. + +Use the [`multiple.v1`](/docs/messages/annotations#multiple) summarization method for AI response citations. This is well suited for citations because: + +- AI responses often reference the same source multiple times, and `multiple.v1` counts each citation separately. +- Citations can be grouped by source using the `name` field (for example, by domain name), so clients can display "3 citations from wikipedia.org, 2 from nasa.gov". + +The examples below use the annotation type `citations:multiple.v1`. + +### Annotation data + +The annotation `data` field can contain any structured data relevant to your citation use case. For example, a citation for a web search result might include: + + +```json +{ + "url": "https://example.com/article", + "title": "Example Article Title", + "startOffset": 120, + "endOffset": 180, + "snippet": "Short excerpt from source" +} +``` + + +In this example: + +- `url` is the source URL. +- `title` is the title of the web page. +- `startOffset` is the character position in the response where this citation begins. +- `endOffset` is the character position in the response where the citation ends. +- `snippet` is a short excerpt from the source content for preview displays. + +Including character offsets in annotation data allow UIs to attach inline citation markers to specific portions of the response text. + + + +## Publishing citations + +Agents create citations by publishing [message annotations](/docs/messages/annotations) that reference the [`serial`](/docs/messages#properties) of the response message: + + +```javascript +const channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}"); + +// Publish the AI response message +const response = "The James Webb Space Telescope launched in December 2021 and its first images were released in July 2022."; +const { serials: [msgSerial] } = await channel.publish("response", response); + +// Add citations by annotating the response message +await channel.annotations.publish(msgSerial, { + type: "citations:multiple.v1", + name: "science.nasa.gov", + data: { + url: "https://science.nasa.gov/mission/webb/", + title: "James Webb Space Telescope - NASA Science", + startOffset: 43, + endOffset: 56, + snippet: "Webb launched on Dec. 25th 2021" + } +}); +await channel.annotations.publish(msgSerial, { + type: "citations:multiple.v1", + name: "en.wikipedia.org", + data: { + url: "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope", + title: "James Webb Space Telescope - Wikipedia", + startOffset: 95, + endOffset: 104, + snippet: "The telescope's first image was released to the public on 11 July 2022." + } +}); +``` + + + + + + +## Subscribing to summaries + + +Clients can display a summary of the citations attached to a response by using [annotation summaries](/docs/messages/annotations#annotation-summaries). Clients receive realtime updates to annotation summaries automatically when subscribing to a channel, which are [delivered as messages](/docs/messages/annotations#subscribe) with an `action` of `message.summary`. When using [`multiple.v1`](/docs/messages/annotations#multiple) summarization, counts are grouped by the annotation `name`. + + + +In the example below, the `name` is set to the domain name of the citation source, so summaries show counts per domain: + + +```javascript +const channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}"); + +await channel.subscribe((message) => { + if (message.action === "message.summary") { + const citations = message.annotations.summary["citations:multiple.v1"]; + if (citations) { + console.log("Citation summary:", citations); + } + } +}); +``` + + +The `multiple.v1` summary groups counts by the annotation `name`, with totals and per-client breakdowns for each group: + + +```json +{ + "citations:multiple.v1": { + "science.nasa.gov": { + "total": 1, + "clientIds": { + "research-agent": 1 + }, + "totalUnidentified": 0, + "totalClientIds": 1, + "clipped": false + }, + "en.wikipedia.org": { + "total": 1, + "clientIds": { + "research-agent": 1 + }, + "totalUnidentified": 0, + "totalClientIds": 1, + "clipped": false + } + } +} +``` + + +When agents publish citations with a [`clientId`](/docs/auth/identified-clients), summaries include a per-client count showing how many citations each agent contributed. Citations published by [unidentified](/docs/auth/identified-clients#unidentified) clients are counted in the `totalUnidentified` field. + + + +## Subscribing to individual citations + +To access the full citation data, subscribe to [individual annotation events](/docs/messages/annotations#individual-annotations): + + +```javascript +const channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}", { + modes: ["ANNOTATION_SUBSCRIBE"] +}); + +await channel.annotations.subscribe((annotation) => { + if (annotation.action === "annotation.create" && + annotation.type === "citations:multiple.v1") { + const { url, title } = annotation.data; + console.log(`Citation: ${title} (${url})`); + // Output: Citation: James Webb Space Telescope - Wikipedia (https://en.wikipedia.org/wiki/James_Webb_Space_Telescope) + } +}); +``` + + +Each annotation event includes the `messageSerial` of the response message it is attached to, the `name` used for grouping in summaries, and the full citation `data` payload. This data can be used to render clickable source links or attach inline citation markers to specific portions of the response text: + + +```json +{ + "action": "annotation.create", + "clientId": "research-agent", + "type": "citations:multiple.v1", + "messageSerial": "01767638186693-000@108SP4XcgBxfMO07491612:000", + "name": "en.wikipedia.org", + "data": { + "url": "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope", + "title": "James Webb Space Telescope - Wikipedia", + "startOffset": 95, + "endOffset": 104, + "snippet": "The telescope's first image was released to the public on 11 July 2022." + } +} +``` + + + + +## Retrieving citations on demand + +Annotations can also be retrieved via the [REST API](/docs/api/rest-api#annotations-list) without maintaining a realtime subscription. + + diff --git a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx b/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx index a501f562a6..5b4f09934b 100644 --- a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx +++ b/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx @@ -33,11 +33,11 @@ To enable the channel rule: 1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app. 2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar. 3. Choose "Add new rule". -4. Enter a channel name or namespace pattern (e.g. `ai:*` for all channels starting with `ai:`). +4. Enter a channel name or namespace pattern (e.g. `ai` for all channels starting with `ai:`). 5. Select the "Message annotations, updates, deletes and appends" option from the list. 6. Click "Create channel rule". -The examples on this page use the `ai:` namespace prefix, which assumes you have configured the rule for `ai:*`. +The examples on this page use the `ai:` namespace prefix, which assumes you have configured the rule for `ai`. ## Publishing tokens diff --git a/src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx b/src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx index e88dc48e3d..7cc7579371 100644 --- a/src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx +++ b/src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx @@ -65,7 +65,7 @@ To enable the channel rule: 1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app. 2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar. 3. Choose "Add new rule". -4. Enter a channel name or namespace pattern (e.g. `ai:*` for all channels starting with `ai:`). +4. Enter a channel name or namespace pattern (e.g. `ai` for all channels starting with `ai:`). 5. Select the "Message annotations, updates, deletes and appends" option from the list. 6. Click "Create channel rule". diff --git a/src/pages/docs/guides/ai-transport/openai-message-per-response.mdx b/src/pages/docs/guides/ai-transport/openai-message-per-response.mdx index 18f91cb653..76e0ed6a2b 100644 --- a/src/pages/docs/guides/ai-transport/openai-message-per-response.mdx +++ b/src/pages/docs/guides/ai-transport/openai-message-per-response.mdx @@ -65,7 +65,7 @@ To enable the channel rule: 1. Go to the [Ably dashboard](https://www.ably.com/dashboard) and select your app. 2. Navigate to the "Configuration" > "Rules" section from the left-hand navigation bar. 3. Choose "Add new rule". -4. Enter a channel name or namespace pattern (e.g. `ai:*` for all channels starting with `ai:`). +4. Enter a channel name or namespace pattern (e.g. `ai` for all channels starting with `ai:`). 5. Select the "Message annotations, updates, deletes and appends" option from the list. 6. Click "Create channel rule".