AIT-133 - citations feature documentation #3077
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
mschristensen
force-pushed
the
AIT-129-AIT-Docs-release-branch
branch
from
aebe2c1 to
ea0ac8d
Compare
|
This needs a rebase or a different base branch |
| 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 like documents, web pages, or databases. Citations 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. |
There was a problem hiding this comment.
| AI agents often draw information from external sources like documents, web pages, or databases. Citations 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. | |
| 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. |
|
|
||
| ## Setup <a id="setup"/> | ||
|
|
||
| Message annotations require the "Message annotations, updates, and deletes" [channel rule](/docs/channels#rules) enabled for your channel or [namespace](/docs/channels#namespaces). This rule automatically enables message persistence. |
| 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 | ||
|
|
||
| Annotations are associated with a message's serial identifier. This works with: |
There was a problem hiding this comment.
| Annotations are associated with a message's serial identifier. This works with: | |
| Annotations are associated with a message's `serial` identifier. This works with: |
|
|
||
| ### Citation payload <a id="citation-payload"/> | ||
|
|
||
| Each citation is carried in the Ably annotation `data` field and should include: |
There was a problem hiding this comment.
Are we proposing this as definitive structure, or is this just a suggestion?
There was a problem hiding this comment.
This is just a suggestion and not a definitive structure. I've updated the wording to reflect that, happy to get your thoughts.
| - `startOffset`: Character position in response where citation applies (optional) | ||
| - `endOffset`: End character position for citation range (optional) | ||
| - `snippet`: Short excerpt from the source (optional) | ||
| - `sourceId`: Stable identifier for deduplication (optional) |
There was a problem hiding this comment.
It's unclear what the purpose of this is
There was a problem hiding this comment.
I've reframed this to state the intent and why for each field, happy to get your thoughts.
|
|
||
| ## Publishing citations from agents <a id="publishing"/> | ||
|
|
||
| After publishing the response (or during streaming, if citations are available), publish citation annotations referencing the message serial. For incremental streaming using message appends, see [message-per-response](/docs/ai-transport/message-per-response). |
There was a problem hiding this comment.
I can't parse this sentence. And I don't understand the purpose of this paragraph
There was a problem hiding this comment.
Agree, I have reframed it now, happy to get your thoughts.
|
|
||
| - `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 |
There was a problem hiding this comment.
| - `messageSerial`: The serial of the message this citation is attached to | |
| - `messageSerial`: The `serial` of the message this citation is attached to |
| **Key fields in raw annotations:** | ||
|
|
||
| - `action`: Always `"annotation.create"` for new annotations | ||
| - `type`: The annotation type (`citations:multiple.v1`) |
There was a problem hiding this comment.
| - `type`: The annotation type (`citations:multiple.v1`) | |
| - `type`: The annotation `type` (`citations:multiple.v1`) |
| - **Individual events**: Each citation arrives as a separate Ably event | ||
|
|
||
| <Aside data-type="note"> | ||
| Use summary view by default for efficient rendering and subscribe to raw annotations only when users need detailed citation information. This minimizes overhead while providing full transparency when required. |
There was a problem hiding this comment.
Should there be a mention of obtaining annotation details via the REST API instead of realtime subscription?
There was a problem hiding this comment.
Good point, thanks for spotting this. I've added the details with a link to the REST API
mittulmadaan
force-pushed
the
AIT-133-feature-documention-citations
branch
from
a1346cc to
64bfda3
Compare
|
@paddybyers - thanks for reviewing this, I’ve addressed all the comments. Could you take another look when you have a moment? |
mschristensen
added
review-app
No description provided.