Package Exports
- @deepracticex/ai-chat
- @deepracticex/ai-chat/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@deepracticex/ai-chat) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
@deepracticex/ai-chat
Universal AI chat client with intelligent tool calling format adapter. Supports OpenAI, Claude, Kimi, and any OpenAI-compatible APIs with robust error handling.
đŻ Core Purpose
@deepracticex/ai-chat is designed with a clear focus on core AI interaction:
- AI Request Processing - Send messages to AI providers and handle responses
- Tool Calling Coordination - Manage tool calls and results with intelligent format adaptation
- Universal Compatibility - Works with OpenAI, Claude, Kimi, and any OpenAI-compatible APIs
- Robust Error Handling - Graceful fallback when tool calls fail to parse
đ Key Features (v0.4.0)
đ Universal Tool Calling Format Adapter
- Smart Format Detection: Automatically detects and adapts different AI service formats
- Multi-Strategy JSON Parsing: Handles malformed JSON, empty strings, special tokens
- Error Recovery: Falls back to empty parameters instead of crashing
- Extensible Design: Easy to add new AI service adapters
đŚ Supported AI Services
- â OpenAI (GPT-3.5, GPT-4, GPT-4o)
- â Kimi/Moonshot (with special handling for format quirks)
- â Claude (Anthropic)
- â Any OpenAI-compatible API (Ollama, LocalAI, etc.)
đĄď¸ Production-Ready
- TypeScript First: Full type safety and IntelliSense support
- Zero Breaking Changes: Drop-in replacement for existing code
- Performance Monitoring: Built-in adapter statistics and debugging
- Battle Tested: Handles edge cases from real-world usage
This package does NOT handle:
- â Model discovery and selection (use
model-managerpackages) - â Provider configuration management (use
config-manager) - â Conversation history management (use
context-manager) - â Message persistence (use
context-manager) - â Session state tracking (use
context-manager) - â Token calculation and cost estimation (use dedicated token calculation packages)
- â Specific tool implementations (use
mcp-clientor custom providers)
đ Quick Start
import { AIChat } from '@deepracticex/ai-chat'
// ⨠Simple and direct - specify exactly what you need
const aiChat = new AIChat({
baseUrl: 'https://api.openai.com/v1',
model: 'gpt-4',
apiKey: process.env.OPENAI_API_KEY
})
// đ Works with any OpenAI-compatible API
const claude = new AIChat({
baseUrl: 'https://api.anthropic.com/v1',
model: 'claude-3-sonnet-20240229',
apiKey: process.env.CLAUDE_API_KEY
})
const azure = new AIChat({
baseUrl: 'https://your-resource.openai.azure.com',
model: 'gpt-4',
apiKey: process.env.AZURE_OPENAI_KEY
})
const ollama = new AIChat({
baseUrl: 'http://localhost:11434',
model: 'llama3'
// No API key needed for local services
})
// đ Send streaming messages
for await (const chunk of aiChat.sendMessage(messages)) {
if (chunk.content) process.stdout.write(chunk.content)
if (chunk.done) break
}đ Core API
AIChat Class
class AIChat {
constructor(config: AIChatConfig)
// Send message and get complete response
sendMessage(
messages: Message[],
options?: ChatOptions
): Promise<ChatResponse>
// Send message and get streaming response
sendMessageStream(
messages: Message[],
options?: ChatOptions
): AsyncIterable<ChatStreamChunk>
}Simple Configuration
Direct and explicit configuration - no magic, no guessing:
interface AIChatConfig {
baseUrl: string // API service endpoint URL - always required
model: string // Model name - always required
apiKey?: string // API key - optional for local services
temperature?: number
maxTokens?: number
}
// â
Examples - Clear and explicit
{
baseUrl: 'https://api.openai.com/v1',
model: 'gpt-4',
apiKey: 'sk-...'
}
{
baseUrl: 'https://api.anthropic.com/v1',
model: 'claude-3-sonnet-20240229',
apiKey: 'sk-ant-...'
}
{
baseUrl: 'http://localhost:11434',
model: 'llama3'
// No API key needed for local Ollama
}đŻ Provider and Model Management
Models and providers are managed externally - use dedicated packages for configuration:
// â
Get configuration from external model management
import { getModelConfig } from '@deechat/model-manager'
const modelConfig = await getModelConfig({
task: 'coding',
preference: 'fastest'
})
const aiChat = new AIChat(modelConfig)
// modelConfig = {
// baseUrl: 'https://api.openai.com/v1',
// model: 'gpt-4-turbo',
// apiKey: '...'
// }
// â
Or use provider configuration helpers
import { openaiConfig, claudeConfig } from '@deechat/provider-configs'
const aiChat = new AIChat(
openaiConfig('gpt-4', { apiKey: process.env.OPENAI_KEY })
)Tool Integration
// Tools are provided as input, not discovered by this package
const response = await aiChat.sendMessage(messages, {
tools: [
{
name: "search_files",
description: "Search for files",
parameters: { /* JSON Schema */ }
}
],
onToolCall: async (call) => {
// Your tool execution logic here
// This could call mcp-client, local functions, etc.
return {
toolCallId: call.id,
result: await executeMyTool(call.name, call.arguments)
}
}
})đ Streaming Example
const stream = aiChat.sendMessageStream(messages, {
tools: myTools,
onToolCall: handleToolCall
})
for await (const chunk of stream) {
if (chunk.content) {
process.stdout.write(chunk.content)
}
if (chunk.toolCalls) {
console.log('AI wants to call tools:', chunk.toolCalls)
}
if (chunk.done) {
console.log('\nResponse complete!')
break
}
}đď¸ Architecture Integration
This package is designed to work alongside other focused packages:
// Example: Complete DeeChat integration
import { AIChat } from '@ai-chat/core'
import { ContextManager } from '@context-manager'
import { MCPClient } from '@mcp-client'
// Each package handles its own responsibility
const aiChat = new AIChat(aiConfig) // AI communication
const contextManager = new ContextManager() // History & state
const mcpClient = new MCPClient() // Tool implementation
// Compose them together
const sessionId = 'session-123'
const history = contextManager.getMessages(sessionId)
const response = await aiChat.sendMessage(
[...history, { role: 'user', content: userInput }],
{
tools: await mcpClient.getTools(),
onToolCall: (call) => mcpClient.executeTools(call)
}
)
// Update context with response
contextManager.addMessage(sessionId, response.message)đŻ Features
- Multiple AI Providers: OpenAI, Claude, Gemini support
- Streaming Responses: Real-time response streaming
- Tool Calling: Coordinate tool execution without managing tools
- TypeScript First: Full type safety and IntelliSense
- Lightweight: Focused scope, minimal dependencies
- Framework Agnostic: Works in any Node.js environment
đŚ Installation
npm install @ai-chat/core
# Peer dependencies (install the providers you need)
npm install openai anthropic # for AI providersđ Documentation
ć ¸ĺżć楣
- API 莞莥ć楣 - 诌çťç API 莞莥ĺçąťĺĺŽäš
- äş§ĺéćąć楣 - ĺŽć´çäş§ĺéćąĺç¨ćˇć äş
- ćść莞莥 - ććŻćśćĺ莞莥ĺłç
ĺźĺć楣
- ĺźĺćĺ - ĺźĺçŻĺ˘ćĺťşĺçźç č§č
- ćľčŻćĺ - ćľčŻççĽĺćľčŻç¨äžçźĺ
- ĺć´ćĽĺż - çćŹĺć´čްĺ˝
đ¤ Contributing
We welcome contributions! Please see our Contributing Guide.
đ License
MIT License - see LICENSE file for details.