@serenity-star/sdk 2.2.1 → 2.4.0

package/readme.md

@@ -12,9 +12,14 @@ The Serenity Star JS/TS SDK provides a comprehensive interface for interacting w
 - [Assistants / Copilots](#assistants--copilots)
   - [Start a new conversation with an Agent](#start-a-new-conversation-with-an-agent)
   - [Get conversation information](#get-conversation-information)
+  - [Get conversation by id](#get-conversation-by-id)
   - [Sending messages within a conversation](#sending-messages-within-a-conversation)
     - [Stream message with SSE](#stream-message-with-sse)
   - [Real time conversation](#real-time-conversation)
+  - [Message Feedback](#message-feedback)
+    - [Submit feedback](#submit-feedback)
+    - [Remove feedback](#remove-feedback)
+  - [Connector Status](#connector-status)
 - [Activities](#activities)
   - [Execute an activity](#execute-an-activity)
   - [Stream responses with SSE](#stream-responses-with-sse)
@@ -25,6 +30,12 @@ The Serenity Star JS/TS SDK provides a comprehensive interface for interacting w
 - [Chat Completions](#chat-completions)
   - [Execute a chat completion](#execute-a-chat-completion)
   - [Stream responses with SSE](#stream-responses-with-sse-2)
+- [Shared Features](#shared-features)
+  - [Upload Files (Volatile Knowledge)](#upload-files-volatile-knowledge)
+  - [Audio Input](#audio-input)
+    - [Send Audio Messages (Assistants/Copilots)](#send-audio-messages-assistantscopilots)
+    - [Execute with Audio (Activities/Proxies/Chat Completions)](#execute-with-audio-activitiesproxieschat-completions)
+    - [Audio Transcription Service](#audio-transcription-service)
 
 # Installation
 
@@ -38,8 +49,7 @@ npm install @serenity-star/sdk
 import SerenityClient from '@serenity-star/sdk';
 
 const client = new SerenityClient({
-  apiKey: '<SERENITY_API_KEY>',
-  apiVersion: 2 // Optional. 2 by default
+  apiKey: '<SERENITY_API_KEY>'
 });
 
 // Execute an activity agent
@@ -510,7 +520,6 @@ const client = new SerenityClient({
 const response = await client.agents.chatCompletions.execute("AgentCreator", {
   message: "Hello!!!"
 });
-
 console.log(
   response.content, // AI-generated response
   response.completion_usage, // { completion_tokens: 200, prompt_tokens: 30, total_tokens: 230 }
@@ -530,7 +539,7 @@ const response = await client.agents.chatCompletions.execute("Health-Coach", {
 
 console.log(
   response.content, // AI-generated response
-  response.completion_usage // { completion_tokens: 200, prompt_tokens: 30, total_tokens: 230 }
+  response.completion_usage, // { completion_tokens: 200, prompt_tokens: 30, total_tokens: 230 }
 );
 
 ```
@@ -567,6 +576,230 @@ const response = await chatCompletion.stream();
 // Access final response data
 console.log(
   response.content, // AI-generated response
-  response.completion_usage // { completion_tokens: 200, prompt_tokens: 30, total_tokens: 230 }
+  response.completion_usage, // { completion_tokens: 200, prompt_tokens: 30, total_tokens: 230 }
+);
+```
+
+---
+
+# Shared Features
+
+## 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 automatically included in the next message or execution.
+
+```tsx
+import SerenityClient from '@serenity-star/sdk';
+
+const client = new SerenityClient({
+  apiKey: '<SERENITY_API_KEY>',
+});
+
+// Works with any agent type (Assistant, Copilot, Activity, Proxy, Chat Completion)
+const conversation = await client.agents.assistants.createConversation("document-analyzer");
+
+// Upload a file (basic example)
+const file = new File(["content"], "document.pdf", { type: "application/pdf" });
+const uploadResult = await conversation.volatileKnowledge.upload(file);
+
+// Check if upload was successful
+if (uploadResult.success) {
+  console.log(
+    uploadResult.id,              // File ID
+    uploadResult.fileName,         // "document.pdf"
+    uploadResult.fileSize,         // Size in bytes
+    uploadResult.expirationDate,   // When the file will be deleted
+    uploadResult.status            // "analyzing", "invalid", "success", "error", or "expired"
+  );
+  
+  // Send a message or execute - the uploaded file will be automatically included
+  const response = await conversation.sendMessage("What are the main points in this document?");
+  console.log(response.content); // Analysis based on the uploaded file
+} else {
+  // Handle upload errors
+  console.error("Upload failed:", uploadResult.error);
+}
+
+// Upload with options
+const imageFile = new File(["image data"], "chart.png", { type: "image/png" });
+const uploadWithOptions = await conversation.volatileKnowledge.upload(imageFile, {
+  useVision: true,              // Enable vision for image files (automatically skips embeddings for images)
+  noExpiration: false,          // File will expire (default behavior)
+  expirationDays: 7,           // Custom expiration in days
+  locale: {
+    uploadFileErrorMessage: "Failed to upload file. Please try again." // You can optionally provide localized error messages
+  }
+});
+
+if (uploadWithOptions.success) {
+  // The file is now ready to be used in the next message/execution
+  const response = await conversation.sendMessage("Describe what you see in this chart");
+  console.log(response.content);
+}
+
+// Check file status by ID
+const fileStatus = await conversation.volatileKnowledge.getById(uploadResult.id);
+
+if (fileStatus.success) {
+  console.log(
+    fileStatus.status,           // "analyzing", "invalid", "success", "error", or "expired"
+    fileStatus.fileName,         // "document.pdf"
+    fileStatus.fileSize,         // Size in bytes
+    fileStatus.expirationDate    // When the file will be deleted
+  );
+} else {
+  console.error("Failed to fetch file status:", fileStatus.error);
+}
+
+// Remove a specific file from the queue
+const file1 = new File(["content 1"], "doc1.pdf", { type: "application/pdf" });
+const file2 = new File(["content 2"], "doc2.pdf", { type: "application/pdf" });
+
+const upload1 = await conversation.volatileKnowledge.upload(file1);
+const upload2 = await conversation.volatileKnowledge.upload(file2);
+
+if (upload1.success && upload2.success) {
+  // Remove only the first file
+  conversation.volatileKnowledge.removeById(upload1.id);
+  
+  // Now only file2 will be included in the next message/execution
+  const response = await conversation.sendMessage("Analyze these documents");
+  console.log(response.content);
+}
+
+// Clear all files from the queue
+await conversation.volatileKnowledge.upload(file1);
+await conversation.volatileKnowledge.upload(file2);
+
+// Clear all pending files
+conversation.volatileKnowledge.clear();
+
+// No files will be included in this message/execution
+const response = await conversation.sendMessage("Hello");
+```
+
+## Audio Input
+
+The SDK provides audio input capabilities across different agent types, allowing you to send audio messages and transcribe audio files.
+
+### Send Audio Messages (Assistants/Copilots)
+
+Send audio messages directly in conversations with assistants and copilots. The audio will be automatically transcribed and processed by the agent.
+
+```tsx
+import SerenityClient from '@serenity-star/sdk';
+
+const client = new SerenityClient({
+  apiKey: '<SERENITY_API_KEY>',
+});
+
+// Create conversation with an assistant
+const conversation = await client.agents.assistants.createConversation("chef-assistant");
+
+// Send an audio message (basic example)
+const audioBlob = new Blob([audioData], { type: 'audio/webm' });
+const response = await conversation.sendAudioMessage(audioBlob);
+
+console.log(
+  response.content,              // AI-generated response
+  response.completion_usage,     // Token usage information
+  response.executor_task_logs    // Task execution logs
 );
+
+// Send an audio message with options
+const responseWithOptions = await conversation.sendAudioMessage(audioBlob, {
+  inputParameters: {
+    cuisine: "italian"
+  },
+  volatileKnowledgeIds: ["knowledge-id-1"]
+});
+
+// Stream an audio message with SSE
+conversation
+  .on("content", (chunk) => {
+    console.log(chunk); // Response chunk
+  })
+  .on("error", (error) => {
+    console.error("Error:", error);
+  });
+
+const streamResponse = await conversation.streamAudioMessage(audioBlob);
+console.log(streamResponse.content); // Final response
+```
+
+### Execute with Audio (Activities/Proxies/Chat Completions)
+
+Execute activities, proxies, and chat completions with audio input. The audio will be processed and used as input for the agent execution.
+
+```tsx
+import SerenityClient from '@serenity-star/sdk';
+
+const client = new SerenityClient({
+  apiKey: '<SERENITY_API_KEY>',
+});
+
+// Example with Activity
+const activity = client.agents.activities.create("voice-analyzer");
+const audioBlob = new Blob([audioData], { type: 'audio/webm' });
+
+// Execute with audio
+const activityResponse = await activity.executeWithAudio(audioBlob);
+console.log(activityResponse.content);
+
+// Stream with audio
+activity
+  .on("content", (chunk) => console.log(chunk))
+  .on("error", (error) => console.error(error));
+
+const streamResponse = await activity.streamWithAudio(audioBlob);
+console.log(streamResponse.content);
+
+// Example with Proxy
+const proxy = client.agents.proxies.create("proxy-agent", {
+  model: "gpt-4o-mini-2024-07-18",
+  messages: [{ role: "user", content: "Analyze this audio" }]
+});
+
+const proxyResponse = await proxy.executeWithAudio(audioBlob);
+console.log(proxyResponse.content);
+
+// Example with Chat Completion
+const chatCompletion = client.agents.chatCompletions.create("audio-assistant", {
+  message: "Process this audio"
+});
+
+const chatResponse = await chatCompletion.executeWithAudio(audioBlob);
+console.log(chatResponse.content);
+```
+
+## Audio Transcription Service
+
+Use the dedicated audio transcription service to transcribe audio files independently from agent executions. The transcript can then be used as text input in conversations.
+
+```tsx
+import SerenityClient from '@serenity-star/sdk';
+
+const client = new SerenityClient({
+  apiKey: '<SERENITY_API_KEY>',
+});
+
+// Transcribe an audio file
+const audioFile = new File([audioBlob], "recording.mp3", { type: "audio/mpeg" });
+
+const result = await client.services.audio.transcribe(audioFile, {
+  modelId: '[YOUR_MODEL_ID]',           // Optional: Specify transcription model
+  prompt: 'This is a conversation about AI', // Optional: Provide context
+  userIdentifier: 'user123'              // Optional: User identifier
+});
+
+console.log('Transcript:', result.transcript);
+console.log('Language:', result.metadata?.language);
+console.log('Duration:', result.metadata?.duration, 'seconds');
+console.log('Total tokens:', result.tokenUsage?.totalTokens);
+console.log('Cost:', result.cost?.total, result.cost?.currency);
+
+// Use the transcript in a conversation
+const conversation = await client.agents.assistants.createConversation("chef-assistant");
+const response = await conversation.sendMessage(result.transcript);
+console.log(response.content); // AI response based on the transcribed audio
 ```