Chat SDK

Le ChatSDK est le composant principal du SDK EKB Content Creator qui vous permet de créer des applications d'IA conversationnelle en toute simplicité. Il fournit une gestion complète des chats, un traitement des messages, des réponses en streaming et une intégration avec la base de connaissances. Dans cet article, vous apprendrez à installer le SDK et à vous lancer rapidement avec notre exemple « Quick Start ». Vous pouvez explorer les diverses options de configuration, en savoir plus sur l'authentification et les méthodes principales que vous pouvez utiliser avec ce SDK. Vous découvrirez également des exemples de cas d'usage.

Installation

npm install @odin-ai-staging/sdk

Quick Start

import { ChatSDK } from '@odin-ai-staging/sdk';

// Initialize the SDK
const chatSDK = new ChatSDK({
  baseUrl: 'https://your-api-endpoint.com/',
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

// Create a chat and send a message
async function quickExample() {
  // Create a new chat
  const chat = await chatSDK.createChat('My First Chat');
  
  // Send a message
  const response = await chatSDK.sendMessage('Hello, how can you help me?', {
    chatId: chat.chat_id
  });
  
  console.log('AI Response:', response.message);
}

Configuration

ChatSDKConfig Interface

interface ChatSDKConfig {
  baseUrl: string;          // API endpoint URL
  projectId: string;        // Your project identifier
  apiKey?: string;          // API key for authentication
  apiSecret?: string;       // API secret for authentication
  accessToken?: string;     // Access token for web app usage
}

Configuration Options

baseUrl: L'URL de base de votre point de terminaison API
projectId: Votre identifiant de projet unique
apiKey & apiSecret: Pour l'authentification côté serveur
accessToken: Pour l'authentification côté client (applications web)

Authentication

Le ChatSDK supporte deux méthodes d'authentification :

API Key Authentication (Côté serveur)

const chatSDK = new ChatSDK({
  baseUrl: 'https://api.example.com/',
  projectId: 'proj_123',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

Access Token Authentication (Côté client)

const chatSDK = new ChatSDK({
  baseUrl: 'https://api.example.com/',
  projectId: 'proj_123',
  accessToken: 'your-access-token'
});

Core Methods

Chat Management

`createChat(name?, documentKeys?)`

Crée une nouvelle conversation de chat.

async createChat(
  name?: string,           // Optional chat name (defaults to "Untitled")
  documentKeys?: string[]  // Optional document keys for knowledge base context
): Promise<CreateChatResponse>

Exemple :

// Create a basic chat
const chat = await chatSDK.createChat('Customer Support Chat');

// Create a chat with knowledge base context
const chatWithDocs = await chatSDK.createChat(
  'Product Documentation Chat',
  ['doc_key_1', 'doc_key_2']
);

`listChats(cursor?, limit?)`

Récupère une liste paginée de chats dans le projet.

async listChats(
  cursor?: number,  // Optional cursor for pagination
  limit?: number    // Number of chats to return (default: 30, max: 100)
): Promise<ListChatsResponse>

Exemple :

// Get first 10 chats
const chats = await chatSDK.listChats(undefined, 10);

// Get next page using cursor
if (chats.next_cursor) {
  const nextPage = await chatSDK.listChats(chats.next_cursor, 10);
}

`getChatHistory(chatId)`

Récupère un chat avec son historique de messages complet.

async getChatHistory(chatId: string): Promise<ChatHistoryResponse>

Exemple :

const chatHistory = await chatSDK.getChatHistory('chat_123');
console.log('Messages:', chatHistory.messages);

`deleteChat(chatId)`

Supprime un chat et tous ses messages de manière permanente.

async deleteChat(chatId: string): Promise<void>

Exemple :

await chatSDK.deleteChat('chat_123');

`updateChatName(chatId, newName)`

Met à jour le nom d'affichage d'un chat existant.

async updateChatName(chatId: string, newName: string): Promise<void>

Exemple :

await chatSDK.updateChatName('chat_123', 'Updated Chat Name');

Message Handling

`sendMessage(message, options?)`

Envoie un message et reçoit la réponse de l'IA.

async sendMessage(
  message: string,
  options?: SendMessageOptions
): Promise<SendMessageResponse>

SendMessageOptions:

interface SendMessageOptions {
  chatId?: string;          // Target chat ID
  agentType?: AgentType;    // Type of AI agent to use
  agentId?: string;         // Specific agent ID
  documentKeys?: string[];  // Knowledge base documents
  images?: File[];          // Image attachments
  metadata?: Record<string, any>;  // Custom metadata
  modelName?: ModelName;    // AI model to use
  useKnowledgebase?: boolean;      // Enable knowledge base
  isTest?: boolean;         // Test mode flag
  googleSearch?: boolean;   // Enable web search
  formatInstructions?: string;     // Response format guidance
  ignoreChatHistory?: boolean;     // Ignore conversation history
  exampleJson?: string;     // Example JSON for structured responses
  skipStream?: boolean;     // Disable streaming
}

Exemple :

// Basic message
const response = await chatSDK.sendMessage('What is artificial intelligence?', {
  chatId: 'chat_123'
});

// Advanced message with options
const advancedResponse = await chatSDK.sendMessage(
  'Analyze this data and provide insights',
  {
    chatId: 'chat_123',
    modelName: 'gpt-4o',
    useKnowledgebase: true,
    googleSearch: true,
    formatInstructions: 'Provide response in bullet points'
  }
);

`sendFeedback(messageId, chatId, feedback)`

Fournit des retours sur une réponse d'IA.

async sendFeedback(
  messageId: string,
  chatId: string,
  feedback: boolean  // true = thumbs up, false = thumbs down
): Promise<void>

Exemple :

// Positive feedback
await chatSDK.sendFeedback('msg_123', 'chat_123', true);

// Negative feedback
await chatSDK.sendFeedback('msg_123', 'chat_123', false);

Streaming Support

`sendMessageStream(message, options)`

Envoie un message avec une réponse en streaming en temps réel.

async sendMessageStream(
  message: string,
  options: SendMessageOptions & StreamCallbacks
): Promise<void>

StreamCallbacks:

interface StreamCallbacks {
  onChunk?: (chunk: string) => void;           // Text chunks
  onMessageObject?: (messageObject: any) => void;  // Structured data
  onComplete?: (message: Message) => void;     // Final message
  onError?: (error: Error) => void;           // Error handler
  onChatNameUpdate?: (chatName: string) => void;   // Chat name changes
  onDocumentChunk?: (chunk: string) => void;  // Document processing updates
  onMessageEnd?: () => void;                  // Stream completion
}

Exemple :

await chatSDK.sendMessageStream(
  'Tell me about machine learning',
  {
    chatId: 'chat_123',
    onChunk: (chunk) => {
      // Display text as it streams in
      console.log('Chunk:', chunk);
      updateUI(chunk);
    },
    onComplete: (message) => {
      console.log('Complete message:', message);
      finalizeUI(message);
    },
    onError: (error) => {
      console.error('Stream error:', error);
      showError(error.message);
    }
  }
);

Error Handling

Le SDK lance des objets APIError pour les défaillances liées à l'API :

interface APIError {
  message: string;  // Error description
  status: number;   // HTTP status code
  detail?: string;  // Additional error details
}

Exemple :

try {
  const response = await chatSDK.sendMessage('Hello');
} catch (error) {
  if (error instanceof APIError) {
    console.error(`API Error ${error.status}: ${error.message}`);
    if (error.detail) {
      console.error('Details:', error.detail);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Examples

Basic Chat Application

Dans cet exemple, vous apprendrez comment créer une application de chat basique à l'aide du SDK EKB avec des échanges de messages simples et non diffusés. Vous commencez par créer une classe SimpleChatApp qui initialise le ChatSDK avec vos credentials API extraits des variables d'environnement (URL de base, ID de projet, clé API et secret). La classe suit votre session de chat actuelle avec currentChatId et fournit trois méthodes principales : startNewChat() crée une nouvelle conversation de chat avec un nom personnalisé, sendMessage() envoie un message à l'IA et retourne la réponse complète (créant automatiquement un nouveau chat s'il n'en existe pas), et getChatList() récupère toutes vos conversations de chat existantes. Contrairement aux implémentations en streaming, cette approche attend la réponse complète de l'IA avant de l'afficher, ce qui la rend parfaite pour les cas d'usage simples où vous n'avez pas besoin de mises à jour en temps réel token par token. L'exemple utilise le modèle GPT-4o-mini et inclut la gestion des erreurs tout au long, avec journalisation en console pour vous aider à suivre le flux de la conversation—vous donnant une base directe pour créer une fonctionnalité de chatbot basique sans la complexité des callbacks de streaming.

import { ChatSDK } from '@odin-ai-staging/sdk';

class SimpleChatApp {
  private chatSDK: ChatSDK;
  private currentChatId?: string;

  constructor() {
    this.chatSDK = new ChatSDK({
      baseUrl: process.env.API_BASE_URL,
      projectId: process.env.PROJECT_ID,
      apiKey: process.env.API_KEY,
      apiSecret: process.env.API_SECRET
    });
  }

  async startNewChat(name: string = 'New Chat') {
    try {
      const chat = await this.chatSDK.createChat(name);
      this.currentChatId = chat.chat_id;
      console.log(`Created chat: ${chat.name} (${chat.chat_id})`);
      return chat;
    } catch (error) {
      console.error('Failed to create chat:', error);
      throw error;
    }
  }

  async sendMessage(message: string) {
    if (!this.currentChatId) {
      await this.startNewChat();
    }

    try {
      const response = await this.chatSDK.sendMessage(message, {
        chatId: this.currentChatId,
        modelName: 'gpt-4o-mini'
      });

      console.log('User:', message);
      console.log('AI:', response.message);
      
      return response;
    } catch (error) {
      console.error('Failed to send message:', error);
      throw error;
    }
  }

  async getChatList() {
    try {
      const chats = await this.chatSDK.listChats();
      return chats.chats;
    } catch (error) {
      console.error('Failed to get chat list:', error);
      throw error;
    }
  }
}

// Usage
const app = new SimpleChatApp();
await app.sendMessage('Hello, how are you?');

Streaming Chat with Real-time Updates

Dans cet exemple, vous apprendrez comment créer une interface de chat en streaming qui se connecte à l'API EKB et affiche les réponses de l'IA en temps réel. Vous commencez par créer une classe StreamingChat qui initialise le ChatSDK avec vos credentials API et une référence à un élément HTML où les messages apparaîtront. Lorsque vous envoyez un message à l'aide de sendStreamingMessage(), vous configurerez des gestionnaires de callbacks qui traitent la réponse en streaming au fur et à mesure qu'elle arrive : le callback onChunk ajoute chaque morceau de texte à votre UI immédiatement (créant cet effet « saisie » caractéristique), tandis que onMessageObject vous permet de gérer du contenu riche comme les images. Vous implémenterez également la gestion des erreurs avec onError, mettrez à jour le titre de votre chat avec onChatNameUpdate, et utiliserez onComplete pour ajouter des boutons de retours pouce vers le haut/bas une fois que le message a fini de diffuser. Cet exemple vous montre comment afficher des images dynamiquement, collecter les retours des utilisateurs sur les réponses de l'IA, et configurer le chat pour utiliser GPT-4o avec l'intégration de la Base de Connaissances—vous donnant tout ce dont vous avez besoin pour créer une interface de type ChatGPT avec des réponses en streaming en temps réel et des fonctionnalités interactives.

import { ChatSDK, StreamCallbacks } from '@odin-ai-staging/sdk';

class StreamingChat {
  private chatSDK: ChatSDK;
  private messageElement: HTMLElement;

  constructor(messageElement: HTMLElement) {
    this.messageElement = messageElement;
    this.chatSDK = new ChatSDK({
      baseUrl: 'https://your-api.com/',
      projectId: 'your-project-id',
      accessToken: 'your-access-token'
    });
  }

  async sendStreamingMessage(message: string, chatId: string) {
    // Clear previous content
    this.messageElement.innerHTML = '';

    const callbacks: StreamCallbacks = {
      onChunk: (chunk: string) => {
        // Append each chunk to the UI
        this.messageElement.innerHTML += chunk;
        this.messageElement.scrollIntoView();
      },

      onMessageObject: (messageObj: any) => {
        // Handle structured data like images, cards, etc.
        if (messageObj.image_urls) {
          this.displayImages(messageObj.image_urls);
        }
      },

      onComplete: (message: any) => {
        console.log('Message complete:', message);
        // Add final styling, enable feedback buttons, etc.
        this.finalizeMessage(message);
      },

      onError: (error: Error) => {
        console.error('Streaming error:', error);
        this.messageElement.innerHTML = `Error: ${error.message}`;
      },

      onChatNameUpdate: (chatName: string) => {
        // Update chat title in UI
        document.title = chatName;
      }
    };

    try {
      await this.chatSDK.sendMessageStream(message, {
        chatId,
        modelName: 'gpt-4o',
        useKnowledgebase: true,
        ...callbacks
      });
    } catch (error) {
      console.error('Failed to send streaming message:', error);
    }
  }

  private displayImages(imageUrls: string[]) {
    imageUrls.forEach(url => {
      const img = document.createElement('img');
      img.src = url;
      img.style.maxWidth = '100%';
      this.messageElement.appendChild(img);
    });
  }

  private finalizeMessage(message: any) {
    // Add feedback buttons
    const feedbackDiv = document.createElement('div');
    feedbackDiv.innerHTML = `
      <button onclick="this.provideFeedback('${message.id}', true)">👍</button>
      <button onclick="this.provideFeedback('${message.id}', false)">👎</button>
    `;
    this.messageElement.appendChild(feedbackDiv);
  }

  async provideFeedback(messageId: string, isPositive: boolean) {
    try {
      await this.chatSDK.sendFeedback(messageId, 'chat_id', isPositive);
      console.log('Feedback sent successfully');
    } catch (error) {
      console.error('Failed to send feedback:', error);
    }
  }
}

Knowledge Base Integration

Dans cet exemple, vous découvrirez comment créer une application de chat alimentée par la Base de Connaissances qui peut répondre aux questions en fonction de documents spécifiques que vous téléchargez dans votre Base de Connaissances. La classe KnowledgeBasedChat initialise le ChatSDK avec vos credentials API à partir des variables d'environnement, puis utilise deux méthodes principales pour interagir avec vos documents : createDocumentChat() configure une nouvelle session de chat liée à des documents spécifiques en passant un tableau de documentKeys (identifiants uniques pour vos documents téléchargés), et askDocumentQuestion() envoie des questions à l'IA avec les fonctionnalités de la Base de Connaissances activées. Lorsque vous posez des questions, vous configurerez le chat pour utiliser useKnowledgebase: true et spécifier agentType: 'document_agent' pour vous assurer que l'IA récupère les informations pertinentes de vos documents, tandis que formatInstructions indique à l'IA d'inclure les citations de ses sources. La réponse inclut une propriété sources qui vous montre quels documents l'IA a référencés lors de la génération de sa réponse, ce qui la rend parfaite pour construire des systèmes Q&A de documents, des assistants de recherche, ou toute application où vous avez besoin de réponses d'IA ancrées dans du contenu spécifique plutôt que dans des connaissances générales. Cela permet une transparence totale dans la façon dont l'IA est arrivée à ses réponses.

import { ChatSDK } from '@odin-ai-staging/sdk';

class KnowledgeBasedChat {
  private chatSDK: ChatSDK;

  constructor() {
    this.chatSDK = new ChatSDK({
      baseUrl: process.env.API_BASE_URL,
      projectId: process.env.PROJECT_ID,
      apiKey: process.env.API_KEY,
      apiSecret: process.env.API_SECRET
    });
  }

  async createDocumentChat(documentKeys: string[], chatName?: string) {
    try {
      const chat = await this.chatSDK.createChat(
        chatName || 'Document Q&A',
        documentKeys
      );
      
      console.log(`Created document chat with ${documentKeys.length} documents`);
      return chat;
    } catch (error) {
      console.error('Failed to create document chat:', error);
      throw error;
    }
  }

  async askDocumentQuestion(question: string, chatId: string, documentKeys?: string[]) {
    try {
      const response = await this.chatSDK.sendMessage(question, {
        chatId,
        documentKeys,
        useKnowledgebase: true,
        agentType: 'document_agent',
        formatInstructions: 'Provide citations for your sources'
      });

      // Display sources if available
      if (response.message.sources) {
        console.log('Sources:', response.message.sources);
      }

      return response;
    } catch (error) {
      console.error('Failed to ask document question:', error);
      throw error;
    }
  }
}

// Usage
const kbChat = new KnowledgeBasedChat();
const chat = await kbChat.createDocumentChat(['doc_1', 'doc_2'], 'Product FAQ');
const answer = await kbChat.askDocumentQuestion(
  'What are the key features of the product?',
  chat.chat_id
);

Best Practices

Error Handling

Implémentez toujours une gestion appropriée des erreurs pour toutes les méthodes du SDK :

try {
  const response = await chatSDK.sendMessage(message, options);
  // Handle success
} catch (error) {
  if (error instanceof APIError) {
    // Handle API errors
    console.error(`API Error: ${error.message}`);
  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}

Streaming for Better UX

Utilisez le streaming pour les réponses plus longues afin de fournir des retours en temps réel :

// Instead of waiting for complete response
const response = await chatSDK.sendMessage(longQuery);

// Use streaming for better user experience
await chatSDK.sendMessageStream(longQuery, {
  onChunk: (chunk) => updateUI(chunk),
  onComplete: (message) => finalizeUI(message)
});

Optimize API Calls

Réutilisez les ID de chat au lieu de créer de nouveaux chats pour chaque message
Utilisez la pagination pour les listes de chats
Implémentez la mise en cache pour les données fréquemment consultées

class OptimizedChatManager {
  private chatCache = new Map<string, any>();
  private currentChatId?: string;

  async getOrCreateChat(name?: string) {
    if (this.currentChatId) {
      return this.currentChatId;
    }

    const chat = await this.chatSDK.createChat(name);
    this.currentChatId = chat.chat_id;
    return this.currentChatId;
  }

  async getCachedChatHistory(chatId: string) {
    if (this.chatCache.has(chatId)) {
      return this.chatCache.get(chatId);
    }

    const history = await this.chatSDK.getChatHistory(chatId);
    this.chatCache.set(chatId, history);
    return history;
  }
}

Configuration Management

Stockez la configuration de manière sécurisée et utilisez les variables d'environnement :

// Good: Use environment variables
const chatSDK = new ChatSDK({
  baseUrl: process.env.ODIN_API_BASE_URL,
  projectId: process.env.ODIN_PROJECT_ID,
  apiKey: process.env.ODIN_API_KEY,
  apiSecret: process.env.ODIN_API_SECRET
});

// Bad: Hardcode credentials
const chatSDK = new ChatSDK({
  baseUrl: 'https://api.example.com',
  projectId: 'hardcoded-project-id',
  apiKey: 'hardcoded-api-key',
  apiSecret: 'hardcoded-secret'
});

Memory Management

Nettoyez les ressources et évitez les fuites mémoire :

class ChatApplication {
  private activeStreams = new Set<AbortController>();

  async sendStreamingMessage(message: string, options: any) {
    const controller = new AbortController();
    this.activeStreams.add(controller);

    try {
      await this.chatSDK.sendMessageStream(message, {
        ...options,
        signal: controller.signal  // If supported
      });
    } finally {
      this.activeStreams.delete(controller);
    }
  }

  cleanup() {
    // Cancel all active streams
    this.activeStreams.forEach(controller => controller.abort());
    this.activeStreams.clear();
  }
}

Installation​

Quick Start​

Configuration​

ChatSDKConfig Interface​

Configuration Options​

Authentication​

API Key Authentication (Côté serveur)​

Access Token Authentication (Côté client)​

Core Methods​

Chat Management​

createChat(name?, documentKeys?)​

listChats(cursor?, limit?)​

getChatHistory(chatId)​

deleteChat(chatId)​

updateChatName(chatId, newName)​

Message Handling​

sendMessage(message, options?)​

sendFeedback(messageId, chatId, feedback)​

Streaming Support​

sendMessageStream(message, options)​

Error Handling​

Examples​

Basic Chat Application​

Streaming Chat with Real-time Updates​

Knowledge Base Integration​

Best Practices​

Error Handling​

Streaming for Better UX​

Optimize API Calls​

Configuration Management​

Memory Management​

Installation

Quick Start

Configuration

ChatSDKConfig Interface

Configuration Options

Authentication

API Key Authentication (Côté serveur)

Access Token Authentication (Côté client)

Core Methods

Chat Management

`createChat(name?, documentKeys?)`

`listChats(cursor?, limit?)`

`getChatHistory(chatId)`

`deleteChat(chatId)`

`updateChatName(chatId, newName)`

Message Handling

`sendMessage(message, options?)`

`sendFeedback(messageId, chatId, feedback)`

Streaming Support

`sendMessageStream(message, options)`

Error Handling

Examples

Basic Chat Application

Streaming Chat with Real-time Updates

Knowledge Base Integration

Best Practices

Error Handling

Streaming for Better UX

Optimize API Calls

Configuration Management

Memory Management