js-agent-core 1.0.1

package/src/core/EventEmitter.ts

@@ -0,0 +1,35 @@
+import { IEventEmitter, AgentEventType } from '../interfaces/IAgentEvent.js';
+
+export class SimpleEventEmitter implements IEventEmitter {
+  private listeners: Map<AgentEventType, Set<(payload: any) => void>> = new Map();
+
+  on<T = any>(event: AgentEventType, listener: (payload: T) => void): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(listener);
+  }
+
+  off<T = any>(event: AgentEventType, listener: (payload: T) => void): void {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.delete(listener);
+      if (callbacks.size === 0) {
+        this.listeners.delete(event);
+      }
+    }
+  }
+
+  emit<T = any>(event: AgentEventType, payload: T): void {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.forEach(listener => {
+        try {
+          listener(payload);
+        } catch (error) {
+          console.error(`Error in event listener for ${event}:`, error);
+        }
+      });
+    }
+  }
+}

package/src/core/LocalEmbedder.ts

@@ -0,0 +1,68 @@
+import { IEmbedder } from '../interfaces/index.js';
+
+/**
+ * A lightweight, local embedder that uses @huggingface/transformers (formerly transformers.js).
+ * It supports dynamic loading to keep the core SDK lightweight.
+ */
+export class LocalEmbedder implements IEmbedder {
+  private modelName: string;
+  private extractor: any = null;
+  private isLoading: boolean = false;
+  private loadPromise: Promise<void> | null = null;
+
+  constructor(modelName: string = 'Xenova/all-MiniLM-L6-v2') {
+    this.modelName = modelName;
+  }
+
+  /**
+   * Lazy-loads the transformers library and the model.
+   */
+  private async loadModel(): Promise<void> {
+    if (this.extractor) return;
+    if (this.isLoading) return this.loadPromise!;
+
+    this.isLoading = true;
+    this.loadPromise = (async () => {
+      try {
+        // Dynamic import to avoid bundling @huggingface/transformers by default.
+        // @ts-ignore - optional dependency that might not be present at compile time
+        const { pipeline } = await import('@huggingface/transformers');
+        
+        this.extractor = await pipeline('feature-extraction', this.modelName, {
+          // Optimization for browser/Node environment if needed
+          // e.g., device: 'webgpu' or 'wasm'
+        });
+      } catch (error) {
+        this.isLoading = false;
+        throw new Error(`Failed to load local embedding model (${this.modelName}): ${error instanceof Error ? error.message : String(error)}. Please ensure '@huggingface/transformers' is installed.`);
+      } finally {
+        this.isLoading = false;
+      }
+    })();
+
+    return this.loadPromise;
+  }
+
+  /**
+   * Generates an embedding for the given text.
+   */
+  async embed(text: string): Promise<number[]> {
+    await this.loadModel();
+    
+    const output = await this.extractor(text, {
+      pooling: 'mean',
+      normalize: true,
+    });
+
+    // transformers.js output is a Tensor, we convert it to a regular array
+    return Array.from(output.data) as number[];
+  }
+
+  /**
+   * Clear the cached model from memory.
+   */
+  async dispose(): Promise<void> {
+    this.extractor = null;
+    this.loadPromise = null;
+  }
+}

package/src/core/LongTermMemory.ts

@@ -0,0 +1,146 @@
+import { ILongTermMemory, IVectorStore, ILLMProvider, LLMMessage, IEmbedder } from '../interfaces/index.js';
+import { AutoVectorStore } from './AutoVectorStore.js';
+
+export interface LongTermMemoryOptions {
+  provider: ILLMProvider;
+  vectorStore?: IVectorStore; // Make vectorStore optional
+  embedder?: IEmbedder;
+  topK?: number;
+  minScore?: number;
+  maxWindowSize?: number; // 添加滑动窗口大小限制
+}
+
+export class LongTermMemory implements ILongTermMemory {
+  private provider: ILLMProvider;
+  private vectorStore: IVectorStore;
+  private embedder?: IEmbedder;
+  private topK: number;
+  private minScore: number;
+  private maxWindowSize: number;
+  private history: LLMMessage[] = [];
+
+  constructor(options: LongTermMemoryOptions) {
+    this.provider = options.provider;
+    this.vectorStore = options.vectorStore || new AutoVectorStore();
+    this.embedder = options.embedder;
+    this.topK = options.topK || 3;
+    this.minScore = options.minScore || 0.7;
+    this.maxWindowSize = options.maxWindowSize || 20; // 默认保留最近 20 条消息
+  }
+
+  async add(message: LLMMessage): Promise<void> {
+    this.history.push(message);
+    
+    // 实现滑动窗口，保留最近的消息，但始终保留第一条系统提示词（如果有）
+    if (this.history.length > this.maxWindowSize) {
+      const systemMessage = this.history[0].role === 'system' ? this.history[0] : null;
+      this.history = this.history.slice(-this.maxWindowSize);
+      if (systemMessage && this.history[0] !== systemMessage) {
+        this.history[0] = systemMessage;
+      }
+    }
+    
+    // Auto-remember high-value user/assistant interactions
+    if (message.role === 'user' || message.role === 'assistant') {
+      if (this.isHighValueContent(message.content)) {
+        await this.remember(message.content);
+      }
+    }
+  }
+
+  /**
+   * 简单的启发式判断内容是否具有长期保存价值
+   */
+  private isHighValueContent(text: string): boolean {
+    if (!text) return false;
+    const trimmed = text.trim();
+    // 过滤掉太短的消息 (如 "ok", "yes", "thanks")
+    if (trimmed.length < 5) return false;
+    // 过滤掉纯语气词或无意义短语
+    const lowValueWords = [
+      'ok', 'yes', 'no', 'thanks', 'thank you', 'thanks a lot', 
+      'got it', 'understand', 'fine', 'good', 'nice', 'cool'
+    ];
+    if (lowValueWords.includes(trimmed.toLowerCase().replace(/[.!?,]/g, ''))) return false;
+    
+    return true;
+  }
+
+  async getHistory(): Promise<LLMMessage[]> {
+    return [...this.history];
+  }
+
+  async clear(): Promise<void> {
+    this.history = [];
+  }
+
+  async remember(text: string): Promise<void> {
+    let embeddings: number[][] | undefined;
+
+    if (this.embedder) {
+      const singleEmbedding = await this.embedder.embed(text);
+      embeddings = [singleEmbedding];
+    } else if (this.provider.embed) {
+      embeddings = await this.provider.embed(text);
+    } else {
+      // If no embedder or provider doesn't support embeddings, we can't do vector storage
+      return;
+    }
+
+    if (embeddings && embeddings.length > 0) {
+      await this.vectorStore.add(text, embeddings[0], { timestamp: Date.now() });
+    }
+  }
+
+  async recall(query: string): Promise<string[]> {
+    // 1. Vector Search (If embedder or provider supports embeddings)
+    let vectorResults: string[] = [];
+    let embeddings: number[][] | undefined;
+
+    if (this.embedder) {
+      const singleEmbedding = await this.embedder.embed(query);
+      embeddings = [singleEmbedding];
+    } else if (this.provider.embed) {
+      embeddings = await this.provider.embed(query);
+    }
+
+    if (embeddings && embeddings.length > 0) {
+      const results = await this.vectorStore.search(embeddings[0], this.topK);
+      vectorResults = results
+        .filter(r => r.score >= this.minScore)
+        .map(r => r.text);
+    }
+
+    // 2. Keyword Search (Hybrid) - Always available if vectorStore supports it
+    let keywordResults: string[] = [];
+    if (this.vectorStore.searchByKeyword) {
+      // 提取可能的关键字 (例如: 超过 3 个字符的单词，排除标点符号)
+      const keywords = query
+        .replace(/[.,\/#!$%\^&\*;:{}=\-_`~()]/g, "")
+        .split(/\s+/)
+        .filter(w => w.length > 3);
+      
+      for (const kw of keywords) {
+        const results = await this.vectorStore.searchByKeyword(kw, 2);
+        keywordResults.push(...results.map(r => r.text));
+      }
+      
+      // 也尝试全文匹配
+      if (query.length > 5) {
+        const results = await this.vectorStore.searchByKeyword(query, 2);
+        keywordResults.push(...results.map(r => r.text));
+      }
+    }
+
+    // 3. Fusion & Deduplication
+    const combined = [...new Set([...keywordResults, ...vectorResults])];
+    return combined.slice(0, this.topK * 2);
+  }
+
+  async getContext(input: string): Promise<string> {
+    const memories = await this.recall(input);
+    if (memories.length === 0) return '';
+    
+    return `Relevant context from memory (Hybrid Search):\n${memories.join('\n---\n')}`;
+  }
+}

package/src/core/MemoryVectorStore.ts

@@ -0,0 +1,54 @@
+import { IVectorStore } from '../interfaces/index.js';
+
+export class MemoryVectorStore implements IVectorStore {
+  private items: Array<{ text: string; embedding: number[]; metadata?: Record<string, any> }> = [];
+
+  async add(text: string, embedding: number[], metadata?: Record<string, any>): Promise<void> {
+    this.items.push({ text, embedding, metadata });
+  }
+
+  async search(queryEmbedding: number[], topK: number = 3): Promise<Array<{ text: string; score: number; metadata?: Record<string, any> }>> {
+    const scoredItems = this.items.map(item => ({
+      ...item,
+      score: this.cosineSimilarity(queryEmbedding, item.embedding)
+    }));
+
+    // Sort by score descending and take topK
+    return scoredItems
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK)
+      .map(({ text, score, metadata }) => ({ text, score, metadata }));
+  }
+
+  async searchByKeyword(keyword: string, topK: number = 3): Promise<Array<{ text: string; score: number; metadata?: Record<string, any> }>> {
+    const lowKeyword = keyword.toLowerCase();
+    
+    const results = this.items
+      .filter(item => item.text.toLowerCase().includes(lowKeyword))
+      .map(item => ({
+        text: item.text,
+        score: 1.0, // keyword matches are high priority
+        metadata: item.metadata
+      }))
+      .slice(0, topK);
+      
+    return results;
+  }
+
+  private cosineSimilarity(vecA: number[], vecB: number[]): number {
+    if (vecA.length !== vecB.length) return 0;
+    
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    
+    for (let i = 0; i < vecA.length; i++) {
+      dotProduct += vecA[i] * vecB[i];
+      normA += vecA[i] * vecA[i];
+      normB += vecB[i] * vecB[i];
+    }
+    
+    const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+    return magnitude === 0 ? 0 : dotProduct / magnitude;
+  }
+}

package/src/core/OpenAIProvider.ts

@@ -0,0 +1,274 @@
+import { ILLMProvider, LLMMessage, LLMOptions, LLMResponse } from '../interfaces/index.js';
+
+export class OpenAIProvider implements ILLMProvider {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor(options: { baseUrl?: string; apiKey?: string } = {}) {
+    this.baseUrl = options.baseUrl || 'https://api.openai.com/v1';
+    this.apiKey = options.apiKey || '';
+  }
+
+  private buildUrl(options: LLMOptions): string {
+    const url = new URL(`${this.baseUrl}/chat/completions`);
+    if (options.intent) {
+      url.searchParams.append('intent', options.intent);
+    }
+    return url.toString();
+  }
+
+  async generate(messages: LLMMessage[], options: LLMOptions): Promise<LLMResponse> {
+    const response = await fetch(this.buildUrl(options), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: options.model,
+        messages: messages.map(m => ({
+          role: m.role,
+          content: m.content,
+          name: m.name,
+          tool_call_id: m.tool_call_id,
+        })),
+        temperature: options.temperature ?? 0.7,
+        max_tokens: options.max_tokens,
+        tools: options.tools,
+        tool_choice: options.tools ? 'auto' : undefined,
+        stream: options.stream ?? false,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`OpenAI API error: ${response.status} ${errorText}`);
+    }
+
+    const data = await response.json();
+    const choice = data.choices[0];
+    const message = choice.message;
+
+    let toolCalls = message.tool_calls;
+
+    // Fallback: Parse tool calls from text content if standard tool_calls are missing
+    if ((!toolCalls || toolCalls.length === 0) && message.content) {
+      const toolCallMatch = message.content.match(/<tool_call>([\s\S]*?)<\/tool_call>/);
+      if (toolCallMatch) {
+        try {
+          const toolCallData = JSON.parse(toolCallMatch[1].trim());
+          toolCalls = [{
+            id: `call_${Date.now()}`,
+            type: 'function',
+            function: {
+              name: toolCallData.name,
+              arguments: JSON.stringify(toolCallData.arguments),
+            }
+          }];
+        } catch (e) {
+          // Silent catch or use agent.error event
+        }
+      }
+    }
+
+    return {
+      content: message.content || '',
+      toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined,
+    };
+  }
+
+  async stream(
+    messages: LLMMessage[],
+    options: LLMOptions,
+    onChunk: (chunk: { content?: string; toolCalls?: any[] }) => void
+  ): Promise<LLMResponse> {
+    const response = await fetch(this.buildUrl(options), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: options.model,
+        messages: messages.map(m => ({
+          role: m.role,
+          content: m.content,
+          name: m.name,
+          tool_call_id: m.tool_call_id,
+        })),
+        temperature: options.temperature ?? 0.7,
+        max_tokens: options.max_tokens,
+        tools: options.tools,
+        tool_choice: options.tools ? 'auto' : undefined,
+        stream: true,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`OpenAI API error: ${response.status} ${errorText}`);
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new Error('Response body is not readable');
+    }
+
+    const decoder = new TextDecoder();
+    let content = '';
+    let toolCalls: any[] = [];
+    let unfinishedLine = '';
+    let currentToolCallId = `call_${Date.now()}`;
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const chunk = unfinishedLine + decoder.decode(value, { stream: true });
+      const lines = chunk.split('\n');
+      unfinishedLine = lines.pop() || '';
+
+      for (const line of lines) {
+        const trimmedLine = line.trim();
+        if (!trimmedLine || trimmedLine === 'data: [DONE]') continue;
+
+        if (trimmedLine.startsWith('data: ')) {
+          try {
+            const data = JSON.parse(trimmedLine.slice(6));
+            const delta = data.choices[0]?.delta;
+
+            if (delta?.content) {
+              content += delta.content;
+              onChunk({ content: delta.content });
+
+              // 增量解析 fallback 模式下的 <tool_call>
+              if (content.includes('<tool_call>')) {
+                const toolCallMatch = content.match(/<tool_call>([\s\S]*?)<\/tool_call>/);
+                if (toolCallMatch) {
+                  // 如果匹配到了完整的标签，说明已经结束，不需要在这里额外处理
+                  // 这里的逻辑主要是为了能在流式过程中识别出工具调用
+                } else {
+                  // 如果只匹配到了开标签但没有闭标签，说明正在流式输出工具调用内容
+                  const startTag = content.indexOf('<tool_call>');
+                  const partialJson = content.slice(startTag + 11).trim();
+                  if (partialJson) {
+                    try {
+                      // 尝试解析部分 JSON，获取工具名
+                      const partialData = this.parsePartialJson(partialJson);
+                      if (partialData?.name) {
+                        onChunk({
+                          toolCalls: [{
+                            index: 0,
+                            id: currentToolCallId,
+                            function: { 
+                              name: partialData.name, 
+                              arguments: JSON.stringify(partialData.arguments || {}) 
+                            }
+                          }]
+                        });
+                      }
+                    } catch (e) {
+                      // 忽略部分解析错误
+                    }
+                  }
+                }
+              }
+            }
+
+            if (delta?.tool_calls) {
+              onChunk({ toolCalls: delta.tool_calls });
+              for (const tc of delta.tool_calls) {
+                if (tc.index === undefined) continue;
+                if (!toolCalls[tc.index]) {
+                  toolCalls[tc.index] = {
+                    id: tc.id,
+                    type: 'function',
+                    function: { name: '', arguments: '' }
+                  };
+                }
+                if (tc.id) toolCalls[tc.index].id = tc.id;
+                if (tc.function?.name) toolCalls[tc.index].function.name += tc.function.name;
+                if (tc.function?.arguments) toolCalls[tc.index].function.arguments += tc.function.arguments;
+              }
+            }
+          } catch (e) {
+            console.error('Error parsing SSE chunk:', e);
+          }
+        }
+      }
+    }
+
+    // Fallback: Parse tool calls from text content if standard tool_calls are missing
+    if ((toolCalls.length === 0) && content) {
+      const toolCallMatch = content.match(/<tool_call>([\s\S]*?)<\/tool_call>/);
+      if (toolCallMatch) {
+        try {
+          const toolCallData = JSON.parse(toolCallMatch[1].trim());
+          toolCalls = [{
+            id: currentToolCallId,
+            type: 'function',
+            function: {
+              name: toolCallData.name,
+              arguments: JSON.stringify(toolCallData.arguments),
+            }
+          }];
+        } catch (e) {
+          // Silent catch
+        }
+      }
+    }
+
+    return {
+      content,
+      toolCalls: toolCalls.length > 0 ? toolCalls.filter(Boolean) : undefined,
+    };
+  }
+
+  /**
+   * 简单解析部分 JSON，目前只支持提取 name 字段
+   */
+  private parsePartialJson(partialJson: string): any {
+    try {
+      // 如果 partialJson 看起来像完整的 JSON，直接解析
+      if (partialJson.endsWith('}')) {
+        return JSON.parse(partialJson);
+      }
+      
+      // 否则尝试用正则提取 "name": "..."
+      const nameMatch = partialJson.match(/"name"\s*:\s*"([^"]*)"/);
+      const argsMatch = partialJson.match(/"arguments"\s*:\s*(\{[\s\S]*)/);
+      
+      return {
+        name: nameMatch ? nameMatch[1] : undefined,
+        arguments: argsMatch ? argsMatch[1] : undefined
+      };
+    } catch (e) {
+      return null;
+    }
+  }
+
+  async embed(text: string | string[]): Promise<number[][]> {
+    const input = Array.isArray(text) ? text : [text];
+    const response = await fetch(`${this.baseUrl}/embeddings`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: 'text-embedding-3-small', // Default for OpenAI, might need config
+        input,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`OpenAI Embedding error: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    if (!data.data || !Array.isArray(data.data)) {
+      return [];
+    }
+    return data.data.map((item: any) => item.embedding);
+  }
+}

package/src/core/SimpleMemory.ts

@@ -0,0 +1,31 @@
+import { IMemory, LLMMessage } from '../interfaces/index.js';
+
+export class SimpleMemory implements IMemory {
+  private messages: LLMMessage[] = [];
+  private maxMessages: number;
+
+  constructor(options: { maxMessages?: number } = {}) {
+    this.maxMessages = options.maxMessages || 50;
+  }
+
+  async add(message: LLMMessage): Promise<void> {
+    this.messages.push(message);
+    if (this.messages.length > this.maxMessages) {
+      // Keep system prompt if it exists at index 0
+      const systemPrompt = this.messages[0].role === 'system' ? this.messages[0] : null;
+      if (systemPrompt) {
+        this.messages = [systemPrompt, ...this.messages.slice(-(this.maxMessages - 1))];
+      } else {
+        this.messages = this.messages.slice(-this.maxMessages);
+      }
+    }
+  }
+
+  async getHistory(): Promise<LLMMessage[]> {
+    return [...this.messages];
+  }
+
+  async clear(): Promise<void> {
+    this.messages = [];
+  }
+}