my-ai-chat-framework 2.0.0 → 2.7.0

package/README.md

@@ -1,19 +1,62 @@
 
- **⚠️ Note**: This project is created for **learning purposes** and is **AI‑generated**. It is not intended for production use. No backward compatibility is guaranteed. Use at your own risk.
- 
 # 🤖 My AI Chat Framework
 
 A lightweight, modular AI chat framework with plugin system, unified message format, and tool calling support.
 
+> **⚠️ Note**: This project is created for **learning purposes** and is **AI‑generated**. It is not intended for production use. No backward compatibility is guaranteed. Use at your own risk.
+
 ## ✨ Features
 
-- **Lightweight Core** – Only ~300 lines, easy to understand and extend.
-- **Plugin System** – Add features like tool calling, reasoning, or custom adapters without touching the core.
+- **Lightweight Core** – ~300 lines, easy to understand and extend.
+- **Plugin System** – Add features (tool calling, reasoning, custom adapters) without touching the core.
 - **Unified Message Format** – Consistent data structure across all components.
-- **Multi‑Environment** – Builds ES module, UMD, and CommonJS formats for browser and Node.js.
+- **Multi‑Environment** – Builds ES module, UMD, and CommonJS for browser & Node.js.
 - **No External Dependencies** – Uses native `fetch` (Node 18+ & modern browsers).
 - **Tool Calling** – Built‑in plugin to handle function calls from AI models.
 - **Streaming** – Full support for real‑time responses.
+- **Flexible Configuration** – Supports both flat and nested `modelParams` structure.
+- **Event‑Driven** – Built‑in EventEmitter for `message`, `sending`, `error`, `stream-progress` events.
+- **Custom Error Classes** – `APIError`, `NetworkError`, `ConfigurationError`, `ParsingError` for fine‑grained error handling.
+
+---
+
+## 🧱 Architecture
+
+```
+src/
+├── index.js                  # Public entry point (re-exports)
+├── core/
+│   ├── ChatService.js        # Main service: config, send/stream, plugin hosting
+│   ├── MessageStore.js       # In-memory message list with CRUD helpers
+│   ├── EventEmitter.js       # Minimal pub/sub (on/off/emit)
+│   └── Errors.js             # Custom error classes
+├── adapters/
+│   └── openai.js             # OpenAI‑compatible API adapter (plugin pattern)
+├── plugins/
+│   └── tool-calling.js       # Tool calling plugin (auto‑detect & loop)
+└── utils/
+    ├── typeCheck.js          # Type checking helpers
+    └── url.js                # URL joining utility
+```
+
+**Data flow**:
+
+```
+User calls chat.send(input)
+  → ChatService._request()
+    → emits 'sending'
+    → MessageStore.add(userMsg)
+    → adapter.buildRequest(messages, config)   ← formats request body
+    → adapter.send(requestBody, config)         ← HTTP call (fetch)
+    → adapter.parseResponse(response)           ← normalize response
+    → MessageStore.add(assistantMsg)
+    → emits 'message'
+    → returns assistantMsg
+```
+
+With `toolCallingPlugin`, the flow loops: response → detect tool_calls → execute tools → add tool results → sendExisting → repeat (max 5 iterations).
+
+---
 
 ## 📦 Installation
 
@@ -21,72 +64,220 @@ A lightweight, modular AI chat framework with plugin system, unified message for
 npm install my-ai-chat-framework
 ```
 
+---
+
 ## 🚀 Quick Start
 
+### Basic Usage (Flat Configuration)
+
 ```javascript
 import { ChatService, openaiAdapter, toolCallingPlugin } from 'my-ai-chat-framework';
 
 const chat = new ChatService({
   apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',    // optional, defaults to OpenAI
   model: 'deepseek-chat',
-  apiUrl: 'https://api.deepseek.com/v1/chat/completions'
+  temperature: 0.7,
+  maxTokens: 2000
 });
 
 chat.use(openaiAdapter);
 chat.use(toolCallingPlugin);
 
-chat.registerTool('greet', 'Say hello', async (args) => {
-  return `Hello, ${args.name}!`;
+chat.on('message', msg => console.log(msg.content));
+await chat.send('Hello!');
+```
+
+### Using `modelParams` (Recommended for Many Parameters)
+
+```javascript
+const chat = new ChatService({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',
+  model: 'deepseek-chat',               // still at top level for convenience
+  modelParams: {                         // optional parameters grouped
+    temperature: 0.8,
+    maxTokens: 1500,
+    reasoningEffort: 'medium'           // for deepseek-reasoner
+  }
 });
+```
 
-chat.on('message', msg => console.log(msg.content));
+### Registering a Tool
+
+```javascript
+chat.registerTool('get_weather', 'Get current weather for a city',
+  async (args) => {
+    // args = { city: 'Beijing' }
+    return `Weather in ${args.city}: 22°C, sunny`;
+  },
+  {  // parameter schema (optional but recommended)
+    city: { type: 'string', description: 'City name', required: true }
+  }
+);
 
-await chat.send('Please greet Alice.');
+await chat.send('What\'s the weather in Beijing?');
+// → AI calls get_weather, framework executes it, AI responds with weather info
 ```
 
+---
+
 ## 🔌 Plugins & Adapters
 
-- **openaiAdapter** – Converts internal messages to OpenAI-compatible format.
-- **toolCallingPlugin** – Detects `tool_calls` in responses, executes tools, and continues the conversation.
+### openaiAdapter
+
+Converts internal messages to OpenAI‑compatible format. Supports:
+- `apiUrl` – full URL (highest priority)
+- `baseUrl` + `path` – base domain + API path
+- Defaults to `https://api.openai.com/v1/chat/completions`
+
+| Config field | Type | Default | Description |
+|-------------|------|---------|-------------|
+| `apiKey` | string | **required** | Bearer token for Authorization header |
+| `apiUrl` | string | – | Full request URL (overrides baseUrl+path) |
+| `baseUrl` | string | `https://api.openai.com` | API base domain |
+| `path` | string | `/v1/chat/completions` | API endpoint path |
+
+### toolCallingPlugin
+
+Detects `tool_calls` in assistant responses, executes registered tools, feeds results back, and continues the conversation (up to `maxIterations` = 5).
+
+- `chat.registerTool(name, description, executor, parameters?)` – register a tool
+- Automatically injects `tool` role messages into the conversation
+- Recovers from tool execution errors gracefully (logs error, returns error message to model)
+
+---
 
-You can easily create your own adapter for other APIs (Anthropic, Cohere, etc.) or plugins for logging, caching, etc.
+## 📡 Events (EventEmitter)
 
-## 📚 API
+`ChatService` extends `EventEmitter`. Subscribe with `chat.on(event, handler)`:
 
-### ChatService
+| Event | Payload | When |
+|-------|---------|------|
+| `sending` | `{ addUser, userInput, timestamp }` | Before each request |
+| `message` | `{ role, content, ... }` | Full assistant message received |
+| `stream-progress` | chunk object | Each streaming chunk arrives |
+| `error` | `{ error, timestamp }` | Any error during request |
 
-```typescript
-new ChatService(config: {
-  apiKey: string;
-  model?: string;
-  apiUrl?: string;
-  temperature?: number;
-  maxTokens?: number;
-})
+```javascript
+chat.on('sending', ({ userInput }) => console.log('Sending:', userInput));
+chat.on('message', msg => console.log('Got:', msg.content));
+chat.on('error', ({ error }) => console.error('Error:', error.message));
+
+// on() returns an unsubscribe function
+const unsubscribe = chat.on('message', handler);
+unsubscribe(); // stop listening
+```
+
+---
+
+## 🧩 ChatService API
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `chat.send(userInput)` | `Promise<Message>` | Send a message, get reply (non‑streaming) |
+| `chat.stream(userInput, onProgress, onDone)` | `Promise<Message>` | Send a message, get streaming reply |
+| `chat.sendExisting()` | `Promise<Message>` | Re‑send current messages without adding user input |
+| `chat.sendExistingStream(onProgress, onDone)` | `Promise<Message>` | Same as above, streaming |
+| `chat.use(plugin)` | `this` | Install a plugin/adapter |
+| `chat.setAdapter(adapter)` | `void` | Manually set the adapter |
+| `chat.on(event, handler)` | `unsubscribe function` | Subscribe to events |
+| `chat.registerTool(name, desc, fn, params?)` | `this` | Register a tool (requires toolCallingPlugin) |
+| `chat.messages` | `MessageStore` | Access the message store directly |
+
+---
+
+## 🗄️ MessageStore API
+
+| Method | Description |
+|--------|-------------|
+| `add(message)` | Add a raw message object |
+| `addUser(content, meta?)` | Add a user message |
+| `addAssistant(content, meta?)` | Add an assistant message |
+| `addSystem(content, meta?)` | Add a system message |
+| `addTool(content, toolCallId, meta?)` | Add a tool result message |
+| `getAll()` | Return a shallow copy of all messages |
+| `getLast()` | Return the last message (or null) |
+| `clear()` | Remove all messages |
+| `undoToLastAssistant()` | Remove messages after the last assistant message |
+
+**Message format**:
+
+```javascript
+{
+  id: string,           // auto‑generated if not provided
+  role: 'user' | 'assistant' | 'system' | 'tool',
+  content: string,
+  toolCalls?: Array,    // assistant messages with tool calls
+  toolCallId?: string,  // tool messages
+  reasoningContent?: string,  // deepseek-reasoner
+  timestamp?: number,
+  metadata?: any
+}
+```
+
+---
+
+## ❌ Error Handling
+
+The framework throws typed errors for different failure modes:
+
+| Error Class | `.name` | When |
+|------------|---------|------|
+| `APIError` | `'APIError'` | Non‑2xx HTTP responses (401, 429, 500, etc.) |
+| `NetworkError` | `'NetworkError'` | `fetch` failures, connection timeouts |
+| `ConfigurationError` | `'ConfigurationError'` | Missing required config |
+| `ParsingError` | `'ParsingError'` | Malformed API response |
+
+```javascript
+import { APIError, NetworkError, ConfigurationError, ParsingError } from 'my-ai-chat-framework';
+
+try {
+  await chat.send('Hello');
+} catch (error) {
+  if (error instanceof APIError) {
+    console.error(`API ${error.statusCode}: ${error.message}`);
+  } else if (error instanceof NetworkError) {
+    console.error('Network issue:', error.message);
+  }
+}
 ```
 
-- `use(plugin)` – Load a plugin.
-- `send(message)` – Send a message and wait for the complete response.
-- `stream(message, onProgress, onDone)` – Stream the response.
-- `registerTool(name, description, executor)` – Register a tool (only available after loading `toolCallingPlugin`).
+---
+
+## 📚 Configuration Reference
+
+`new ChatService(config)` accepts:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | **required** | Your API key |
+| `baseUrl` | string | `'https://api.openai.com'` | API base URL (used with `path`) |
+| `path` | string | `'/v1/chat/completions'` | API path (used with `baseUrl`) |
+| `apiUrl` | string | – | Full API URL (overrides `baseUrl`+`path`) |
+| `model` | string | **required** | Model name (e.g., `deepseek-chat`) |
+| `modelParams` | object | `{}` | Grouped model parameters (see below) |
+| `temperature` | number | `0.7` | Sampling temperature (0–2) |
+| `maxTokens` | number | `2000` | Max tokens to generate |
+| `reasoningEffort` | string | – | For `deepseek-reasoner`: `'low'`, `'medium'`, `'high'` |
+
+> Both flat and `modelParams` styles work. `modelParams` takes precedence over top‑level values.
 
-### MessageStore
+---
 
-- `add(message)` – Add a message (unified format).
-- `addUser(content, metadata)` – Convenience method.
-- `addAssistant(content, metadata)`
-- `addSystem(content, metadata)`
-- `addTool(content, toolCallId, metadata)`
-- `getAll()` – Get all messages.
-- `undoToLastAssistant()` – Rollback to the last assistant message.
+## 🧪 Testing
 
-### EventEmitter
+```bash
+# 1. Create a .env file with your API key
+echo "DEEPSEEK_API_KEY=sk-xxxxx" > .env
+
+# 2. Run the test
+npm test
+```
 
-- `on(event, handler)` – Subscribe to events.
-- `off(event, handler)` – Unsubscribe.
-- `emit(event, data)` – Emit an event.
+The test script (`test.js`) sends a simple message and logs the response.
 
-Events: `sending`, `message`, `stream-progress`, `error`, etc.
+---
 
 ## 🛠️ Development
 
@@ -94,14 +285,20 @@ Events: `sending`, `message`, `stream-progress`, `error`, etc.
 git clone https://github.com/your-username/my-ai-chat-framework.git
 cd my-ai-chat-framework
 npm install
-npm run build   # build the library
-npm test        # run the test script
+
+# Dev mode (watching)
+npm run dev
+
+# Build the library (ES + UMD + CJS)
+npm run build
+
+# Run tests
+npm test
 ```
 
+---
+
 ## 📄 License
 
 MIT
 
-## 🤝 Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.