@serenity-star/sdk 2.6.0 → 2.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-star/sdk",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "description": "The Serenity Star JavaScript SDK provides a convenient way to interact with the Serenity Star API, enabling you to build custom applications.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/readme.md

@@ -36,7 +36,10 @@ The Serenity Star JS/TS SDK provides a comprehensive interface for interacting w
   - [Execute a chat completion](#execute-a-chat-completion)
   - [Stream responses with SSE](#stream-responses-with-sse-2)
 - [Shared Features](#shared-features)
+  - [Download Attached Files](#download-attached-files)
   - [Stop Streaming Response](#stop-streaming-response)
+  - [Citations](#citations)
+    - [Citations on stored messages](#citations-on-stored-messages)
   - [Upload Files (Volatile Knowledge)](#upload-files-volatile-knowledge)
   - [Audio Input](#audio-input)
     - [Send Audio Messages (Assistants/Copilots)](#send-audio-messages-assistantscopilots)
@@ -255,7 +258,7 @@ const conversation = await client.agents.assistants.getConversationById("<agent-
 
 console.log(
   conversation.id, // "<conversation-id>"
-  conversation.messages, // Array of messages
+  conversation.messages, // Array of messages (each may include a `citations` array — see Citations)
   conversation.open // Boolean that indicates if the conversation was closed or not
 );
 
@@ -312,8 +315,14 @@ const client = new SerenityClient({
 const conversation = await client.agents.assistants.createConversation("chef-assistant")
 	
 conversation
-	.on("content", (chunk) => {
+	.on("content", (chunk, citations) => {
 	  console.log(chunk) // Response chunk
+	  // `citations` is an optional array attached to some chunks.
+	  // Each citation's start_index / end_index are offsets into the FULL accumulated
+	  // message, not into this individual chunk.
+	  if (citations) {
+	    console.log(citations) // CitationRes[]
+	  }
 	})
 	.on("error", (error) => {
 	  // Handle stream errors here
@@ -327,10 +336,13 @@ console.log(
   response.content, // "Sure! Here is a recipe for parmesan chicken..."
   response.completion_usage, // { completion_tokens: 200, prompt_tokens: 30, total_tokens: 230 }
   response.executor_task_logs, // [ { description: 'Task 1', duration: 100 }, { description: 'Task 2', duration: 500 }],
+  response.citations, // CitationRes[] — full citation list for the final message
   response.instance_id, // instance id for the conversation
 )
 ```
 
+> **Citations:** When the agent grounds its answer in knowledge sources, citations are delivered both incrementally on `content` events (second argument) and as a consolidated `response.citations` array on the final result. See [Citations](#citations) for the full shape.
+
 ## Real time conversation
 
 ```tsx
@@ -832,6 +844,116 @@ const activity = client.agents.activities.create("translator-activity", {
 await activity.stream();
 ```
 
+## Citations
+
+When an agent grounds its response in knowledge sources (knowledge files or websites), it returns **citations** that map spans of the generated message back to the source passages they came from. Citations are available across all agent types that support knowledge grounding.
+
+Citations are delivered in three places:
+
+1. **Incrementally**, as the second argument of the `content` event during streaming.
+2. **Consolidated**, as the `citations` array on the final result (`response.citations`) — available for both streamed and non-streamed executions.
+3. **Persisted**, on each `Message` loaded from conversation history (`message.citations`) — see [Citations on stored messages](#citations-on-stored-messages) below.
+
+```tsx
+import SerenityClient from '@serenity-star/sdk';
+
+const client = new SerenityClient({
+  apiKey: '<SERENITY_API_KEY>',
+});
+
+const conversation = await client.agents.assistants.createConversation("policy-assistant");
+
+conversation.on("content", (chunk, citations) => {
+  process.stdout.write(chunk);
+
+  if (citations) {
+    for (const citation of citations) {
+      console.log(
+        citation.citation_index, // Display number rendered as the superscript (may repeat)
+        citation.start_index,    // Offset into the FULL accumulated message where the cited span starts
+        citation.end_index,      // Offset into the FULL accumulated message where the cited span ends
+        citation.relevance,      // Optional relevance score
+        citation.cited_text,     // Verbatim text of the source passage (shown in the hover card)
+        citation.source          // The cited source (see below), or null
+      );
+    }
+  }
+});
+
+const response = await conversation.streamMessage("Summarize our security and access-control requirements");
+
+// The final result carries the consolidated citation list
+for (const citation of response.citations ?? []) {
+  if (citation.source?.type === "knowledge_file") {
+    console.log(`[${citation.citation_index}] ${citation.source.file_name} (pages ${citation.source.page_range})`);
+  } else if (citation.source?.type === "knowledge_website") {
+    console.log(`[${citation.citation_index}] ${citation.source.website}`);
+  }
+}
+```
+
+> **Note:** `start_index` and `end_index` are offsets into the **full accumulated message**, not into the individual chunk delivered by a `content` event. Accumulate the chunks (or use `response.content`) before resolving these offsets.
+
+The `CitationRes`, `CitationResWithoutText`, and `CitationSource` types are exported from the package:
+
+```ts
+import type { CitationRes, CitationResWithoutText, CitationSource } from '@serenity-star/sdk';
+
+type CitationSource =
+  | {
+      type: "knowledge_file";
+      knowledge_file_version_id?: string;
+      section_id?: string;
+      file_name?: string;
+      page_range?: string;
+    }
+  | {
+      type: "knowledge_website";
+      knowledge_file_version_id?: string;
+      section_id?: string;
+      website: string;
+    };
+
+type CitationRes = {
+  cited_text: string;      // Verbatim text of the source passage (shown in the hover card)
+  citation_index: number;  // Display number rendered as the superscript; may repeat across citations
+  start_index: number;     // Offset into the FULL accumulated message where the cited span starts
+  end_index: number;       // Offset into the FULL accumulated message where the cited span ends
+  relevance?: number;
+  source: CitationSource | null;
+};
+
+// Same shape as CitationRes but without `cited_text`. Used for citations on
+// messages loaded from conversation history (see "Get conversation by id").
+type CitationResWithoutText = {
+  citation_index: number;
+  start_index: number;
+  end_index: number;
+  relevance?: number;
+  source: CitationSource | null;
+};
+```
+
+### Citations on stored messages
+
+Citations are also persisted on the conversation history. When you load past messages via [Get conversation by id](#get-conversation-by-id) (or read `conversation.messages`), each `Message` may carry a `citations` array of type `CitationResWithoutText[]` — the same shape as `CitationRes` but **without** the `cited_text` field (the verbatim passage is not stored alongside historical messages).
+
+```tsx
+const conversation = await client.agents.assistants.getConversationById("policy-assistant", "<conversation-id>");
+
+for (const message of conversation.messages) {
+  for (const citation of message.citations ?? []) {
+    console.log(
+      citation.citation_index, // Display number rendered as the superscript (may repeat)
+      citation.start_index,    // Offset into the message `value` where the cited span starts
+      citation.end_index,      // Offset into the message `value` where the cited span ends
+      citation.relevance,      // Optional relevance score
+      citation.source          // The cited source (knowledge_file / knowledge_website), or null
+    );
+  }
+}
+```
+
 ## Upload Files (Volatile Knowledge)
 
 Upload files to be used as context in your agent executions. This feature is available for all agent types: **Assistants**, **Copilots**, **Activities**, **Proxies**, and **Chat Completions**. Files are agent-scoped automatically and are included in the next message or execution.