@cohuman/chat-core

A comprehensive TypeScript library for building AI-powered chat applications with advanced features like tool calling, image generation, web search, and conversation management.

Features

• Multi-Model Support: Integrates with OpenRouter to support various AI models including DeepSeek, GLM, and Qwen
• Tool Calling: Built-in support for web search via Exa and system prompt modification
• Image Generation: Automatic image generation and prompt refinement capabilities
• Character Management: Create, update, and manage AI characters with custom system prompts and avatars
• Conversation Persistence: Full conversation history management with UI and model message tracking
• Streaming Responses: Real-time streaming of AI responses with tool execution
• TypeScript First: Fully typed API with comprehensive interfaces

Installation

npm install @cohuman/chat-core

Quick Start

import { ChatService, ChatServiceHooks } from "@cohuman/chat-core";

// Create hooks for persistence and messaging
const hooks: ChatServiceHooks = {
  sendMessage: (message) => {
    // Handle outgoing messages (streaming chunks, tool calls, etc.)
    console.log("Received message:", message);
  },
  onConversationCreated: async (conversation) => {
    // Persist new conversation
  },
  loadConversation: async (conversationId) => {
    // Load conversation from storage
    return null;
  },
  // ... other hooks
};

// Create chat service instance
const chatService = new ChatService({
  hooks,
  base_guidance_system_prompt: "You are a helpful AI assistant.",
  base_personality_system_prompt: "Be friendly and informative.",
});

// Handle a chat message
await chatService.handleChatMessage(
  "Hello, can you search for the latest news about AI?",
  undefined, // conversationId (will create new if not provided)
  true, // webSearchEnabled
  false, // imageGenerationEnabled
  "deepseek/deepseek-v3.2" // model
);

API Reference

ChatService

The main class for handling chat functionality.

Constructor

new ChatService(props: {
  hooks?: ChatServiceHooks;
  base_guidance_system_prompt?: string;
  base_personality_system_prompt?: string;
})

Methods

• handleChatMessage(message, conversationId?, webSearchEnabled?, imageGenerationEnabled?, model?, systemPrompt?): Send a chat message
• handleGetConversation(conversationId): Load and send conversation history
• handleRegenerate(conversationId, messageId, webSearchEnabled?, imageGenerationEnabled?, model?, newContent?): Regenerate response from a specific message
• handleStopGeneration(conversationId): Stop ongoing generation
• handleAuth(tenantId): Authenticate with tenant ID
• handleSaveCharacter(systemPrompt): Save a new character
• handleGetCharacters(): Get all characters for current tenant
• handleDeleteCharacter(characterId): Delete a character
• handleUpdateCharacter(characterId, name, systemPrompt, avatarBase64): Update a character

Message Types

Input Messages (ChatInputMessage)

• chat: Send a chat message with optional parameters
• auth: Authenticate with tenant ID
• get_conversation: Request conversation history
• regenerate: Regenerate response from specific message
• stop_generation: Stop ongoing generation
• save_character: Save new character
• get_characters: Get character list
• delete_character: Delete character
• update_character: Update character

Output Messages (ChatOutputMessage)

• chat_message_chunk: Streaming response chunk
• chat_loop_done: Generation completed with optional artifacts
• chat_history: Full conversation history
• chat_error: Error occurred
• generation_stopped: Generation was stopped
• auth_success: Authentication successful
• backend_capabilities: Available models
• conversation_list: List of conversations
• new_conversation: New conversation created
• character_saved: Character save result
• character_list: List of characters

UI Message Types

• UIUserMessage: User-sent message
• UIModelMessage: AI response message
• UIToolStartMessage: Tool execution started
• UIToolCompleteMessage: Tool execution completed
• UISystemMessage: System message
• UIGeneratedImageMessage: Generated image
• UIGeneratedImagePromptMessage: Image generation prompt

Hooks Interface (ChatServiceHooks)

Define callbacks for persistence, messaging, and lifecycle events:

interface ChatServiceHooks {
  sendMessage?: (message: ChatOutputMessage) => void;
  onConversationCreated?: (conv: ConversationData) => Promise<void>;
  onTitleChanged?: (convId: string, title: string) => Promise<void>;
  onCustomPersonalitySystemPromptChanged?: (
    convId: string,
    prompt: string
  ) => Promise<void>;
  onLastUpdatedChanged?: (convId: string, ts: number) => Promise<void>;
  onUIMessageAdded?: (
    convId: string,
    msg: UIMessage,
    order: number
  ) => Promise<void>;
  onUIMessagesTruncated?: (
    convId: string,
    messages: UIMessage[]
  ) => Promise<void>;
  onUIMessageUpdated?: (
    msgId: string,
    updates: Partial<UIMessage>
  ) => Promise<void>;
  onModelMessageAdded?: (
    convId: string,
    msg: ModelMessage,
    order: number
  ) => Promise<void>;
  onModelMessagesTruncated?: (
    convId: string,
    messages: ModelMessage[]
  ) => Promise<void>;
  loadConversation?: (convId: string) => Promise<LoadedConversation | null>;
  loadConversationList?: (tenantId: string) => Promise<ConversationSummary[]>;
  insertCharacter?: (
    tenantId: string,
    name: string,
    systemPrompt: string,
    avatarBase64: string
  ) => Promise<string>;
  deleteCharacter?: (characterId: string) => Promise<void>;
  updateCharacter?: (
    tenantId: string,
    characterId: string,
    name: string,
    systemPrompt: string,
    avatarBase64: string
  ) => Promise<void>;
  selectCharacters?: (tenantId: string) => Promise<Character[]>;
}

Supported Models

• deepseek/deepseek-v3.2: DeepSeek v3.2 (fast, good for general use)
• z-ai/glm-4.6: GLM 4.6 (excellent tool use capabilities)
• qwen/qwen3-235b-a22b-2507: Qwen 3.2 32B (high quality, good tool use)

Tools

Web Search (Exa)

Automatically searches the web for current information when webSearchEnabled is true.

Features:

• Searches the web using Exa's advanced search API
• Returns up to 5 relevant results with titles, URLs, and summaries
• Provides formatted text output for AI consumption
• Includes source artifacts for application use

Usage:

// Enable web search in chat message
await chatService.handleChatMessage(
  "What's the latest news about AI?",
  conversationId,
  true, // webSearchEnabled
  false, // imageGenerationEnabled
  "deepseek/deepseek-v3.2"
);

Tool Response Format:

• formattedText: Human-readable search results
• artifacts.sources: Array of search results with title, url, summary
• artifacts.searchQueries: Array of queries used

System Prompt Modification

Allows the AI to modify its own system prompt for better responses in specific conversations.

Image Generation

Generates images based on conversation context when imageGenerationEnabled is true.

Environment Variables

• OPENROUTER_API_KEY: Required for AI model access via OpenRouter
• EXA_API_KEY: Required for web search functionality using Exa

Building

npm run build

License

ISC