@restnfeel/agentc-starter-kit

# Chatbot API Reference This document provides detailed API reference for the RAG Chatbot Library. ## Table of Contents - [ChatbotAPI](#chatbotapi) - [Types](#types) - [Hooks](#hooks) - [Components](#components) - [Error Handling](#error-handling) ## ChatbotAPI The main API class for interacting with the chatbot system. ### Constructor ```typescript const api = new ChatbotAPI(); ``` ### Methods #### initialize(config: ChatbotAPIConfig): Promise<ApiResponse<string>> Initializes the chatbot with the provided configuration. **Parameters:** - `config`: Configuration object containing LLM, vector store, and storage settings **Returns:** Promise resolving to success/error response **Example:** ```typescript const result = await api.initialize({ llm: { provider: "openai", model: "gpt-3.5-turbo", apiKey: "your-api-key", maxTokens: 1000, temperature: 0.7, }, vectorStore: { provider: "memory", dimensions: 1536, }, storage: { provider: "local", }, }); if (result.success) { console.log("Chatbot initialized successfully"); } else { console.error("Initialization failed:", result.error); } ``` #### sendMessage(content: string, conversationId?: string): Promise<ApiResponse<ConversationMessage>> Sends a message and gets an AI response. **Parameters:** - `content`: The message content to send - `conversationId`: Optional conversation ID (creates new conversation if not provided) **Returns:** Promise resolving to the AI response message **Example:** ```typescript const response = await api.sendMessage("Hello, how can you help me?"); console.log("AI Response:", response.data?.content); ``` #### uploadDocument(file: File, metadata?: Partial<Document['metadata']>): Promise<ApiResponse<Document>> Uploads and processes a document for the knowledge base. **Parameters:** - `file`: File object to upload - `metadata`: Optional metadata for the document **Returns:** Promise resolving to the processed document **Example:** ```typescript const file = new File(["Document content"], "document.txt", { type: "text/plain", }); const result = await api.uploadDocument(file, { title: "Important Document", tags: ["important", "reference"], }); if (result.success) { console.log("Document uploaded:", result.data?.id); } ``` #### deleteDocument(documentId: string): Promise<ApiResponse<void>> Deletes a document from the knowledge base. **Parameters:** - `documentId`: ID of the document to delete **Returns:** Promise resolving to success/error response #### getDocuments(limit?: number, offset?: number): Promise<ApiResponse<Document[]>> Retrieves a list of documents. **Parameters:** - `limit`: Maximum number of documents to return (default: 50) - `offset`: Number of documents to skip (default: 0) **Returns:** Promise resolving to array of documents #### searchSimilarDocuments(query: string, limit?: number): Promise<ApiResponse<Document[]>> Performs semantic search on the document knowledge base. **Parameters:** - `query`: Search query string - `limit`: Maximum number of results (default: 10) **Returns:** Promise resolving to array of relevant documents #### startConversation(title?: string): Promise<ApiResponse<Conversation>> Creates a new conversation. **Parameters:** - `title`: Optional title for the conversation **Returns:** Promise resolving to the new conversation #### getConversations(limit?: number): Promise<ApiResponse<Conversation[]>> Retrieves user's conversations. **Parameters:** - `limit`: Maximum number of conversations to return **Returns:** Promise resolving to array of conversations #### deleteConversation(conversationId: string): Promise<ApiResponse<void>> Deletes a conversation and all its messages. **Parameters:** - `conversationId`: ID of the conversation to delete **Returns:** Promise resolving to success/error response #### getConversationHistory(conversationId: string): Promise<ApiResponse<ConversationMessage[]>> Gets all messages in a conversation. **Parameters:** - `conversationId`: ID of the conversation **Returns:** Promise resolving to array of messages #### getConfiguration(): ChatbotAPIConfig | null Gets the current configuration. **Returns:** Current configuration object or null if not initialized #### updateConfiguration(config: Partial<ChatbotAPIConfig>): Promise<ApiResponse<string>> Updates the chatbot configuration. **Parameters:** - `config`: Partial configuration object with updates **Returns:** Promise resolving to success/error response ## Types ### ChatbotAPIConfig ```typescript interface ChatbotAPIConfig { llm?: LLMConfig; vectorStore?: VectorStoreConfig; storage?: StorageConfig; } ``` ### LLMConfig ```typescript interface LLMConfig { provider: LLMProvider; model: string; apiKey: string; maxTokens?: number; temperature?: number; systemPrompt?: string; } type LLMProvider = "openai" | "anthropic" | "azure" | "huggingface"; ``` ### VectorStoreConfig ```typescript interface VectorStoreConfig { dimensions: number; // Provider-specific configurations } ``` ### StorageConfig ```typescript interface StorageConfig { // Provider-specific configurations } ``` ### Document ```typescript interface Document { id: string; content: string; metadata: { title?: string; filename?: string; fileType?: string; fileSize?: number; uploadedAt?: Date; tags?: string[]; description?: string; }; embedding?: number[]; createdAt: Date; updatedAt: Date; } ``` ### Conversation ```typescript interface Conversation { id: string; title: string; messages: ConversationMessage[]; createdAt: Date; updatedAt: Date; } ``` ### ConversationMessage ```typescript interface ConversationMessage { id: string; role: "user" | "assistant" | "system"; content: string; timestamp: Date; metadata?: { sources?: Document[]; processingTime?: number; tokensUsed?: number; }; } ``` ### ApiResponse ```typescript interface ApiResponse<T = any> { success: boolean; data?: T; error?: string; details?: any; status?: number; timestamp?: string; } ``` ### ChatbotError ```typescript interface ChatbotError { code: string; message: string; details?: any; timestamp: Date; severity?: "low" | "medium" | "high" | "critical"; } ``` ## Hooks ### useChatbot Main hook providing access to chatbot functionality. ```typescript interface UseChatbotReturn { // State isInitialized: boolean; isProcessing: boolean; conversations: Conversation[]; currentConversation: Conversation | null; documents: Document[]; lastError: ChatbotError | null; // Actions initialize: (config?: ChatbotAPIConfig) => Promise<void>; sendMessage: ( content: string, conversationId?: string ) => Promise<ConversationMessage>; uploadDocument: ( file: File, metadata?: Partial<Document["metadata"]> ) => Promise<Document>; deleteDocument: (documentId: string) => Promise<void>; searchSimilarDocuments: ( query: string, limit?: number ) => Promise<Document[]>; startConversation: (title?: string) => Promise<Conversation>; selectConversation: (conversationId: string) => Promise<void>; deleteConversation: (conversationId: string) => Promise<void>; getConversationHistory: ( conversationId: string ) => Promise<ConversationMessage[]>; clearError: () => void; } ``` ### useDocuments Hook for document management. ```typescript interface UseDocumentsReturn { documents: Document[]; isLoading: boolean; uploadDocument: ( file: File, metadata?: Partial<Document["metadata"]> ) => Promise<Document>; deleteDocument: (documentId: string) => Promise<void>; getDocument: (documentId: string) => Document | undefined; searchDocuments: (query: string, limit?: number) => Promise<Document[]>; documentCount: number; } ``` ### useErrorHandler Hook for centralized error handling. ```typescript interface UseErrorHandlerReturn { error: ChatbotError | null; hasError: boolean; clearError: () => void; handleError: (error: Error | ChatbotError | string) => void; getErrorMessage: () => string | null; isErrorType: (code: string) => boolean; errorSeverity: "low" | "medium" | "high" | "critical" | null; } ``` ### useTheme Hook for theme management. ```typescript interface UseThemeReturn { theme: Theme; setTheme: (theme: Partial<Theme>) => void; toggleMode: () => void; resetTheme: () => void; } interface Theme { mode: "light" | "dark"; primaryColor: string; backgroundColor: string; textColor: string; borderColor: string; } ``` ### useI18n Hook for internationalization. ```typescript interface UseI18nReturn { language: SupportedLanguage; setLanguage: (language: SupportedLanguage) => void; t: (key: string, params?: Record<string, string>) => string; isRTL: boolean; } type SupportedLanguage = "en" | "ko" | "ja" | "zh"; ``` ## Components ### ChatbotProvider Context provider for the chatbot system. ```typescript interface ChatbotProviderProps { children: React.ReactNode; config?: ChatbotAPIConfig; onError?: (error: ChatbotError) => void; } ``` ### ChatbotWidget Main chatbot interface component. ```typescript interface ChatbotWidgetProps { theme?: Partial<Theme>; position?: "bottom-left" | "bottom-right" | "top-left" | "top-right"; showSuggestedQuestions?: boolean; placeholder?: string; maxHeight?: string; className?: string; } ``` ### RAGChat Full-featured chat interface. ```typescript interface RAGChatProps { conversationId?: string; showDocumentSearch?: boolean; showUpload?: boolean; maxHeight?: string; className?: string; onDocumentUpload?: (document: Document) => void; onMessageSent?: (message: ConversationMessage) => void; } ``` ### FloatingChatButton Floating action button for chat. ```typescript interface FloatingChatButtonProps { position?: "bottom-left" | "bottom-right" | "top-left" | "top-right"; size?: "sm" | "md" | "lg"; icon?: React.ReactNode; onClick?: () => void; className?: string; } ``` ## Error Handling ### Error Codes Common error codes returned by the API: - `INITIALIZATION_FAILED`: Failed to initialize the chatbot - `INVALID_CONFIG`: Invalid configuration provided - `LLM_ERROR`: Error from the language model - `VECTOR_STORE_ERROR`: Error from the vector store - `STORAGE_ERROR`: Error from the storage provider - `DOCUMENT_UPLOAD_FAILED`: Failed to upload document - `DOCUMENT_NOT_FOUND`: Requested document not found - `CONVERSATION_NOT_FOUND`: Requested conversation not found - `INVALID_FILE_TYPE`: Unsupported file type - `FILE_TOO_LARGE`: File exceeds size limit - `RATE_LIMIT_EXCEEDED`: API rate limit exceeded - `NETWORK_ERROR`: Network connection error - `UNAUTHORIZED`: Invalid API credentials ### Error Handling Best Practices 1. **Always check the success field** in API responses: ```typescript const result = await api.sendMessage("Hello"); if (!result.success) { console.error("Error:", result.error); return; } // Use result.data safely ``` 2. **Use the error handler hook** for centralized error management: ```typescript const { handleError, getErrorMessage } = useErrorHandler(); try { await api.uploadDocument(file); } catch (error) { handleError(error); } ``` 3. **Implement fallback UI** for error states: ```typescript if (hasError) { return ( <div className="error-state"> <p>{getErrorMessage()}</p> <button onClick={clearError}>Try Again</button> </div> ); } ``` 4. **Log errors** for debugging: ```typescript const config = { onError: (error: ChatbotError) => { console.error("Chatbot Error:", error); // Send to error tracking service }, }; ```