SmythOS Studio: Open-Source Visual AI Agent Builder and deployable runtime stack from SmythOS. Start with an intuitive drag-and-drop workspace, extend with custom code, and deploy your agents anywhere — local, cloud, or edge — with full governance and control.
JavaScript a2aagentic-aiai-agentsdevtoolsmcp-clientn8n-alternativeno-codeopen-sourceorchestrationsmythosvisual-builder
Remove ARCHITECTURE.md, index.ts, and MIGRATION.md Files from AI Chat Feature
Salman-Ahamed730a0afd80d4
diff --git a/packages/app/src/react/features/ai-chat/ARCHITECTURE.md b/packages/app/src/react/features/ai-chat/ARCHITECTURE.mddeleted file mode 100644index 049b16ec..00000000--- a/packages/app/src/react/features/ai-chat/ARCHITECTURE.md+++ /dev/null@@ -1,488 +0,0 @@-# AI Chat System Architecture--Professional, production-ready chat system with modern React patterns and complete TypeScript support.--## 🏗️ Architecture Overview--```-┌─────────────────────────────────────────────────────────────┐-│ React Components │-│ (Your UI Implementation) │-└───────────────────────┬─────────────────────────────────────┘- │- │ uses- ▼-┌─────────────────────────────────────────────────────────────┐-│ useChat Hook │-│ ┌──────────────────────────────────────────────────────┐ │-│ │ • Message State Management │ │-│ │ • File Upload Orchestration │ │-│ │ • Retry Logic │ │-│ │ • Error Handling │ │-│ └──────────────────────────────────────────────────────┘ │-└───────────────────────┬─────────────────────────────────────┘- │- │ uses- ▼-┌─────────────────────────────────────────────────────────────┐-│ useChatStream Hook │-│ ┌──────────────────────────────────────────────────────┐ │-│ │ • Stream Lifecycle Management │ │-│ │ • Abort Control │ │-│ │ • Error State Management │ │-│ └──────────────────────────────────────────────────────┘ │-└───────────────────────┬─────────────────────────────────────┘- │- │ uses- ▼-┌─────────────────────────────────────────────────────────────┐-│ ChatAPIClient │-│ ┌──────────────────────────────────────────────────────┐ │-│ │ • HTTP Streaming │ │-│ │ • Chunk Processing │ │-│ │ • File Upload │ │-│ │ • Error Handling │ │-│ └──────────────────────────────────────────────────────┘ │-└───────────────────────┬─────────────────────────────────────┘- │- │ uses- ▼-┌─────────────────────────────────────────────────────────────┐-│ Stream Utilities │-│ ┌──────────────────────────────────────────────────────┐ │-│ │ • splitJSONStream() │ │-│ │ • extractFunctionName() │ │-│ │ • formatFunctionName() │ │-│ │ • formatStatusMessage() │ │-│ │ • ThinkingMessageManager │ │-│ └──────────────────────────────────────────────────────┘ │-└─────────────────────────────────────────────────────────────┘-```--## 📁 File Structure--```-ai-chat/-├── types/-│ └── chat.types.ts # Complete TypeScript definitions-│ ├── IChatMessage # Message structure-│ ├── IChatStreamChunk # Stream response format-│ ├── IChatStreamConfig # Stream configuration-│ ├── IChatStreamCallbacks # Event callbacks-│ ├── IChatError # Error structure-│ ├── IUseChatReturn # Hook return type-│ └── ... (more types)-│-├── clients/-│ └── chat-api.client.ts # API Client-│ ├── ChatAPIClient # Main client class-│ ├── streamChat() # Stream chat method-│ ├── uploadFile() # File upload method-│ └── chatAPI # Singleton instance-│-├── hooks/-│ ├── use-chat.ts # Main chat hook-│ │ ├── useChat() # Complete chat management-│ │ ├── sendMessage() # Send messages-│ │ ├── retryLastMessage() # Retry logic-│ │ └── stopGenerating() # Abort control-│ │-│ └── use-chat-stream.ts # Stream management hook-│ ├── useChatStream() # Stream lifecycle-│ ├── startStream() # Start streaming-│ └── abortStream() # Abort stream-│-├── utils/-│ └── stream.utils.ts # Stream utilities-│ ├── splitJSONStream() # Parse JSON chunks-│ ├── extractFunctionName() # Extract function names-│ ├── formatFunctionName() # Format for display-│ ├── formatStatusMessage() # Format status-│ ├── processStreamChunk() # Process chunks-│ └── ThinkingMessageManager # Thinking messages-│-├── examples/-│ └── usage-example.tsx # Complete usage examples-│-├── components/ # (Your existing components)-├── index.ts # Main exports-├── README.md # Documentation-├── MIGRATION.md # Migration guide-└── ARCHITECTURE.md # This file-```--## 🔄 Data Flow--### 1. Sending a Message--```-User Input- │- ▼-useChat.sendMessage(message, files?)- │- ├──► Upload files (if present)- │ │- │ └──► ChatAPIClient.uploadFile()- │ │- │ └──► Returns: IChatFileAttachment[]- │- ├──► Add user message to state- │- ├──► Add empty AI message (for streaming)- │- └──► useChatStream.startStream()- │- └──► ChatAPIClient.streamChat()- │- ├──► HTTP POST /api/page/chat/stream- │- └──► Process stream chunks- │- ├──► Content chunks → Update AI message- ├──► Thinking updates → Update thinking message- ├──► Function calls → Log/notify- ├──► Debug info → Log/notify- └──► Errors → Display error-```--### 2. Stream Processing--```-HTTP Response Stream- │- ▼-ReadableStream<Uint8Array>- │- ▼-TextDecoder- │- ▼-Accumulated String Buffer- │- ▼-splitJSONStream(buffer)- │- ▼-IChatStreamChunk[]- │- ▼-processStreamChunk(chunk)- │- ├──► hasContent? → onContent(content)- ├──► hasThinking? → onThinking(message, type)- ├──► hasFunctionCall? → onToolCall(name, args)- ├──► hasDebug? → onDebug(chunk)- └──► hasError? → onError(error)-```--### 3. Error Handling Flow--```-Error Occurs- │- ├──► DOMException (AbortError)- │ └──► IChatError { type: 'abort_error', isAborted: true }- │- ├──► TypeError (Network)- │ └──► IChatError { type: 'network_error' }- │- ├──► HTTP Error- │ └──► IChatError { type: 'stream_error' }- │- └──► Generic Error- └──► IChatError { type: 'system_error' }- │- └──► useChatStream.error state- │- └──► useChat.error state- │- └──► Component error display-```--## 🧩 Component Integration--### Basic Integration--```typescript-import { useChat } from '@react/features/ai-chat';--const ChatComponent = () => {- const chat = useChat({- agentId: 'agent-123',- chatId: 'chat-456',- });-- return (- <>- {chat.messages.map((msg) => <Message key={msg.id} {...msg} />)}- <Input onSend={chat.sendMessage} disabled={chat.isGenerating} />- {chat.error && <Error error={chat.error} onRetry={chat.retryLastMessage} />}- </>- );-};-```--### Advanced Integration with Custom Client--```typescript-import { createChatClient, useChat } from '@react/features/ai-chat';--// Create custom client-const client = createChatClient({- baseUrl: '/custom/api',- timeout: 60000,- defaultHeaders: {- Authorization: 'Bearer token',- },-});--const AdvancedChat = () => {- const chat = useChat({- agentId: 'agent-123',- chatId: 'chat-456',- client, // Use custom client- headers: {- 'X-Session-Id': sessionId,- },- });-- // ... component implementation-};-```--## 🎯 Design Principles--### 1. Separation of Concerns--- **Types**: Pure type definitions (no logic)-- **Utilities**: Pure functions (no state)-- **Client**: HTTP logic only (no React)-- **Hooks**: React state management (no HTTP details)-- **Components**: UI only (no business logic)--### 2. Single Responsibility--- Each module has one clear purpose-- Easy to test in isolation-- Easy to replace/extend--### 3. Composition Over Inheritance--- Hooks compose other hooks-- Client uses utilities-- Components use hooks--### 4. Dependency Injection--- Custom client can be injected-- Custom headers supported-- Callbacks for extensibility--### 5. Progressive Enhancement--- Basic usage is simple-- Advanced features available when needed-- Gradual complexity increase--## 🔒 Type Safety--### Strict TypeScript Rules--```typescript-// ✅ Good - Fully typed-const message: IChatMessage = {- id: 1,- message: 'Hello',- type: 'user',- me: true,- timestamp: Date.now(),-};--// ❌ Bad - Avoided 'any'-const message: any = { ... };--// ✅ Good - Proper error typing-const error: IChatError = {- message: 'Error',- type: 'system_error',-};--// ❌ Bad - Unknown error-throw new Error('error');-```--### Type Guards--```typescript-// Type narrowing with discriminated unions-if (message.type === 'user') {- // TypeScript knows this is a user message-}--if (error.isAborted) {- // TypeScript knows this is an aborted error-}-```--## ⚡ Performance Considerations--### 1. Memo/Callback Optimization--```typescript-// All hook functions are wrapped in useCallback-const sendMessage = useCallback(async (...) => {- // Stable reference across renders-}, [dependencies]);-```--### 2. Ref Usage for Non-Reactive Data--```typescript-// Avoid unnecessary re-renders-const currentMessageRef = useRef('');-const lastUserMessageRef = useRef(null);-```--### 3. Minimal State Updates--```typescript-// Only update state when necessary-if (content !== previousContent) {- setMessage(content);-}-```--### 4. Stream Buffer Management--```typescript-// Clear buffer after processing to prevent memory leaks-if (chunks.length > 0) {- accumulatedData = '';-}-```--## 🧪 Testing Strategy--### Unit Tests--```typescript-// Test utilities in isolation-describe('splitJSONStream', () => {- it('should parse multiple JSON objects', () => {- const result = splitJSONStream('{"a":1}{"b":2}');- expect(result).toEqual([{ a: 1 }, { b: 2 }]);- });-});-```--### Integration Tests--```typescript-// Test hook behavior-import { renderHook } from '@testing-library/react';--describe('useChat', () => {- it('should send message and update state', async () => {- const { result } = renderHook(() => useChat({ ... }));- await act(() => result.current.sendMessage('Hello'));- expect(result.current.messages).toHaveLength(2);- });-});-```--### E2E Tests--```typescript-// Test complete flow with real API-describe('Chat Flow', () => {- it('should complete full conversation', async () => {- // Mount component- // Send message- // Verify response- // Verify state- });-});-```--## 📊 State Management--### Hook State--```typescript-useChat() manages:- - messages[] // All messages- - isGenerating // AI responding- - isProcessing // Uploading files- - error // Current error- - lastUserMessage // For retry--useChatStream() manages:- - isStreaming // Stream active- - error // Stream error-```--### Ref State (Non-Reactive)--```typescript--lastUserMessageRef - // Retry data- currentAIMessageRef - // Current accumulation- abortControllerRef; // Abort control-```--## 🔌 Extension Points--### 1. Custom API Client--```typescript-class CustomChatClient extends ChatAPIClient {- async streamChat(...) {- // Custom implementation- }-}-```--### 2. Custom Stream Processing--```typescript-const customProcessor = (chunk: IChatStreamChunk) => {- // Custom processing logic- return processStreamChunk(chunk);-};-```--### 3. Custom Error Handling--```typescript-const { error } = useChat({- onError: (err) => {- // Custom error handling- logToSentry(err);- notifyUser(err);- },-});-```--### 4. Custom Thinking Messages--```typescript-const thinkingManager = createThinkingManager();-thinkingManager.start('custom', callback, 'CustomMessage');-```--## 📚 Related Documentation--- [README.md](./README.md) - Feature documentation-- [MIGRATION.md](./MIGRATION.md) - Migration guide-- [usage-example.tsx](./examples/usage-example.tsx) - Usage examples-- [chat.types.ts](./types/chat.types.ts) - Type definitions--## 🤝 Contributing--When extending this system:--1. **Follow TypeScript strict mode** - No `any`, no `!`, no casting-2. **Add JSDoc comments** - Document all public APIs-3. **Write tests** - Unit + integration tests required-4. **Update documentation** - Keep docs in sync with code-5. **Follow patterns** - Use established patterns consistentlydiff --git a/packages/app/src/react/features/ai-chat/MIGRATION.md b/packages/app/src/react/features/ai-chat/MIGRATION.mddeleted file mode 100644index fa8edad7..00000000--- a/packages/app/src/react/features/ai-chat/MIGRATION.md+++ /dev/null@@ -1,462 +0,0 @@-# Migration Guide: Old Chat System → New Professional Chat System--This guide helps you migrate from the existing chat implementation to the new professional system.--## 🎯 Key Improvements--| Feature | Old Implementation | New Implementation |-| -------------------- | ---------------------------------- | ------------------------------------ |-| **Type Safety** | Partial typing with `any` types | Complete TypeScript types |-| **Architecture** | Utils-based functional approach | Modern hook-based architecture |-| **Error Handling** | Basic error callbacks | Comprehensive error types & handling |-| **State Management** | Manual state in components | Built-in state management in hooks |-| **Streaming** | Manual stream processing | Automatic stream handling |-| **File Uploads** | External handling | Integrated file upload support |-| **Abort Control** | Manual abort controller management | Built-in abort control |-| **Retry Logic** | Manual implementation needed | Built-in retry functionality |--## 📝 Migration Steps--### Step 1: Update Imports--**Before:**--```typescript-import { chatUtils } from '@src/react/features/ai-chat/utils';-```--**After:**--```typescript-import { useChat } from '@react/features/ai-chat';-```--### Step 2: Replace Component Implementation--#### Old Implementation--```typescript-import React, { useState, useRef } from 'react';-import { chatUtils } from './utils';--const ChatComponent = ({ agentId, chatId }) => {- const [messages, setMessages] = useState([]);- const [isGenerating, setIsGenerating] = useState(false);- const abortControllerRef = useRef(null);-- const sendMessage = async (message) => {- abortControllerRef.current = new AbortController();-- try {- setIsGenerating(true);-- await chatUtils.generateResponse({- agentId,- chatId,- query: message,- signal: abortControllerRef.current.signal,- onResponse: (value, errorInfo) => {- // Handle response- setMessages(prev => [...prev, { content: value, isError: errorInfo?.isError }]);- },- onStart: () => {- console.log('Started');- },- onEnd: () => {- setIsGenerating(false);- },- onThinking: (thinking) => {- console.log('Thinking:', thinking.message);- },- });- } catch (error) {- console.error('Error:', error);- setIsGenerating(false);- }- };-- const stopGenerating = () => {- if (abortControllerRef.current) {- abortControllerRef.current.abort();- }- };-- return (- <div>- {/* UI implementation */}- </div>- );-};-```--#### New Implementation--```typescript-import React, { useState } from 'react';-import { useChat } from '@react/features/ai-chat';--const ChatComponent = ({ agentId, chatId }) => {- const [inputValue, setInputValue] = useState('');-- const {- messages,- isGenerating,- sendMessage,- stopGenerating,- clearMessages,- error,- retryLastMessage,- } = useChat({- agentId,- chatId,- onChatComplete: (message) => {- console.log('Chat completed:', message);- },- onError: (err) => {- console.error('Error:', err);- },- });-- const handleSend = async () => {- await sendMessage(inputValue);- setInputValue('');- };-- return (- <div>- {/* Simplified UI implementation */}- {messages.map((msg) => (- <div key={msg.id}>{msg.message}</div>- ))}-- <input- value={inputValue}- onChange={(e) => setInputValue(e.target.value)}- />-- <button onClick={handleSend} disabled={isGenerating}>- Send- </button>-- {isGenerating && (- <button onClick={stopGenerating}>Stop</button>- )}-- {error && (- <div>- Error: {error.message}- <button onClick={retryLastMessage}>Retry</button>- </div>- )}- </div>- );-};-```--### Step 3: Update Message Handling--#### Old Message Format--```typescript-const userMessage = {- me: true,- message: 'Hello',- type: 'user',- files: attachedFiles,-};--const aiMessage = {- me: false,- message: '',- type: 'system',- isReplying: true,-};-```--#### New Message Format (Typed)--```typescript-import type { IChatMessage } from '@react/features/ai-chat';--const userMessage: IChatMessage = {- id: Date.now(),- message: 'Hello',- type: 'user',- me: true,- timestamp: Date.now(),- files: attachedFiles,-};--const aiMessage: IChatMessage = {- id: Date.now(),- message: '',- type: 'system',- me: false,- isReplying: true,- timestamp: Date.now(),-};-```--### Step 4: Update Stream Processing--#### Old Stream Processing--```typescript-// Manual stream processing in chatUtils.generateResponse-let message = '';-const jsonObjects = chatUtils.splitDataToJSONObjects(accumulatedData);--for (const jsonObject of jsonObjects) {- if (jsonObject.content) {- message += jsonObject.content;- input.onResponse(message);- }-- if (jsonObject.debug) {- // Manual debug handling- }-}-```--#### New Stream Processing (Automatic)--```typescript-// Automatically handled by useChat hook-const { sendMessage } = useChat({- agentId,- chatId,- onChatComplete: (finalMessage) => {- // All streaming handled automatically- console.log('Final message:', finalMessage);- },-});--// Just send the message - streaming is automatic-await sendMessage('Hello');-```--### Step 5: Update Thinking Messages--#### Old Thinking Management--```typescript-// Manual thinking manager-const thinkingManager = chatUtils.thinkingManager;--thinkingManager.start('function', onThinking, 'getUserData');-thinkingManager.updateStatus('Processing...');-thinkingManager.stop();-```--#### New Thinking Management (Automatic)--```typescript-// Automatically handled in the hook-const { messages } = useChat({ agentId, chatId });--// Access thinking message from message object-messages.map((msg) => (- <div>- {msg.thinkingMessage && <div>{msg.thinkingMessage}</div>}- {msg.message}- </div>-));-```--### Step 6: Update File Upload Handling--#### Old File Upload--```typescript-// Manual file upload and attachment handling-const uploadFile = async (file) => {- const formData = new FormData();- formData.append('file', file);-- const response = await fetch('/api/upload', {- method: 'POST',- body: formData,- });-- const data = await response.json();- return data.url;-};--const handleSend = async (message, files) => {- const uploadedUrls = await Promise.all(files.map(uploadFile));-- await chatUtils.generateResponse({- // ...config- attachments: uploadedUrls.map((url, i) => ({- url,- name: files[i].name,- type: files[i].type,- })),- });-};-```--#### New File Upload (Integrated)--```typescript-// File upload handled automatically-const { sendMessage } = useChat({ agentId, chatId });--const handleSend = async (message, files) => {- // Just pass the files - upload is automatic- await sendMessage(message, files);-};-```--### Step 7: Update Error Handling--#### Old Error Handling--```typescript-try {- await chatUtils.generateResponse({- // ...config- onResponse: (value, errorInfo) => {- if (errorInfo?.isError) {- console.error('Stream error:', value);- }- },- });-} catch (error) {- if (error.name === 'AbortError') {- console.log('Aborted');- } else {- console.error('Error:', error.message);- }-}-```--#### New Error Handling (Typed)--```typescript-import type { IChatError } from '@react/features/ai-chat';--const { error, clearError } = useChat({- agentId,- chatId,- onError: (err: Error) => {- console.error('Error occurred:', err);- },-});--// Display error with type information-{error && (- <div>- <p>Error Type: {error.type}</p>- <p>Message: {error.message}</p>- {error.isAborted && <p>Request was cancelled</p>}- <button onClick={clearError}>Dismiss</button>- </div>-)}-```--## 🔄 API Compatibility Matrix--| Old API | New API | Notes |-| ------------------------------------------ | ------------------------- | --------------------------- |-| `chatUtils.generateResponse()` | `useChat().sendMessage()` | Hook-based, automatic state |-| `chatUtils.splitDataToJSONObjects()` | `splitJSONStream()` | Improved parsing, exported |-| `chatUtils.extractFunctionNameFromDebug()` | `extractFunctionName()` | Renamed for clarity |-| `chatUtils.formatFunctionNameForDisplay()` | `formatFunctionName()` | Renamed for brevity |-| `chatUtils.thinkingManager` | `createThinkingManager()` | Factory function |-| `chatUtils.getChatStreamURL()` | Built into API client | No longer needed |--## 🎨 Component Migration Examples--### Example 1: Simple Chat--**Before:**--```typescript-const SimpleChat = ({ agentId }) => {- const [messages, setMessages] = useState([]);- // ... 50+ lines of state management-};-```--**After:**--```typescript-const SimpleChat = ({ agentId }) => {- const chat = useChat({ agentId, chatId: 'chat-1' });- // All state managed by hook-};-```--### Example 2: Chat with Retry--**Before:**--```typescript-// Manual retry implementation-const [lastMessage, setLastMessage] = useState('');--const retry = () => {- sendMessage(lastMessage);-};-```--**After:**--```typescript-const { retryLastMessage } = useChat({ agentId, chatId });--// One line retry-<button onClick={retryLastMessage}>Retry</button>-```--### Example 3: Chat with Files--**Before:**--```typescript-// ~100 lines of file handling code-```--**After:**--```typescript-const { sendMessage } = useChat({ agentId, chatId });-await sendMessage('Message', [file1, file2]);-```--## 🚀 Benefits After Migration--✅ **90% less boilerplate code**-✅ **Complete type safety**-✅ **Automatic error handling**-✅ **Built-in retry logic**-✅ **Integrated file uploads**-✅ **Better testing support**-✅ **Cleaner component code**-✅ **Professional architecture**--## 📚 Next Steps--1. ✅ Update imports to use new system-2. ✅ Replace `chatUtils.generateResponse` with `useChat`-3. ✅ Update type definitions-4. ✅ Test chat functionality-5. ✅ Test file uploads-6. ✅ Test error handling-7. ✅ Test retry functionality-8. ✅ Remove old utils (optional - can keep for backwards compatibility)--## 🆘 Need Help?--- See `README.md` for complete documentation-- See `examples/usage-example.tsx` for practical examples-- Check type definitions in `types/chat.types.ts`-- Review API client code in `clients/chat-api.client.ts`--## 🔗 Related Documentation--- [README.md](./README.md) - Complete feature documentation-- [usage-example.tsx](./examples/usage-example.tsx) - Working examples-- [chat.types.ts](./types/chat.types.ts) - Type definitions-- [ChatService.class.ts](../../../../../../../../sre-embodiment-server/src/modules/chat/services/ChatService.class.ts) - Backend implementationdiff --git a/packages/app/src/react/features/ai-chat/index.ts b/packages/app/src/react/features/ai-chat/index.tsdeleted file mode 100644index 9576a0cd..00000000--- a/packages/app/src/react/features/ai-chat/index.ts+++ /dev/null@@ -1,30 +0,0 @@-/**- * AI Chat Feature - Main Export Index- * Professional chat system with streaming support, type safety, and modern React patterns- */--// === Type Definitions ===-export * from './types/chat.types';--// === API Client ===-export { chatAPI, ChatAPIClient, createChatClient } from './clients/chat-api.client';--// === React Hooks ===-export {- useAgentChatContext,- type IUseAgentChatContextConfig,- type IUseAgentChatContextReturn,-} from './hooks/use-agent-chat-context';-export { useChat } from './hooks/use-chat';-export { useChatStream } from './hooks/use-chat-stream';--// === Utilities ===-export {- createThinkingManager,- extractFunctionName,- formatFunctionName,- formatStatusMessage,- processStreamChunk,- splitJSONStream,- ThinkingMessageManager,-} from './utils/stream.utils';