@axiom-lattice/core 1.0.46 → 2.0.0

package/README.md

@@ -7,6 +7,8 @@
 - 模型格子管理 (ModelLatticeManager)
 - 工具格子管理 (ToolLatticeManager)
 - 代理格子管理 (AgentLatticeManager)
+- 记忆格子管理 (MemoryLatticeManager)
+- 流式缓冲管理 (ChunkBufferLatticeManager)
 - DeepAgent 实现
 - 工具类和辅助函数
 
@@ -30,11 +32,53 @@ pnpm test
 
 ## 使用示例
 
+### Model Lattice
+
 ```typescript
-import { ModelLatticeManager } from "lattice_core";
+import { ModelLatticeManager } from "@axiom-lattice/core";
 
 // 创建模型格子管理器
-const modelLattice = new ModelLatticeManager();
+const modelLattice = ModelLatticeManager.getInstance();
+```
+
+### ChunkBuffer - Streaming Chunk Management
+
+```typescript
+import { 
+  InMemoryChunkBuffer, 
+  registerChunkBuffer 
+} from "@axiom-lattice/core";
+
+// Create buffer with 30-minute TTL and optional periodic cleanup
+const buffer = new InMemoryChunkBuffer({
+  ttl: 30 * 60 * 1000,              // 30 minutes
+  cleanupInterval: 5 * 60 * 1000    // Clean every 5 minutes (optional)
+});
+
+// Register in Lattice system
+registerChunkBuffer('default', buffer);
+
+// Add chunks as they arrive
+await buffer.addChunk('thread-123', 'msg-1', 'Hello ');
+await buffer.addChunk('thread-123', 'msg-1', 'world!');
+await buffer.addChunk('thread-123', 'msg-2', ' How are you?');
+
+// Get accumulated content
+const content = await buffer.getAccumulatedContent('thread-123');
+// => "Hello world! How are you?"
+
+// Check thread status
+const isActive = await buffer.isThreadActive('thread-123'); // true
+
+// Explicitly complete the thread
+await buffer.completeThread('thread-123');
+
+// Get buffer statistics
+const stats = buffer.getStats();
+console.log(stats);
+
+// Cleanup
+buffer.dispose();
 ```
 
 ## 目录结构
@@ -43,5 +87,63 @@ const modelLattice = new ModelLatticeManager();
 - `src/model_lattice/`: 模型格子相关实现
 - `src/tool_lattice/`: 工具格子相关实现
 - `src/agent_lattice/`: 代理格子相关实现
+- `src/memory_lattice/`: 记忆格子相关实现
+- `src/chunk_buffer_lattice/`: 流式缓冲管理实现
 - `src/deep_agent/`: DeepAgent 实现
 - `src/util/`: 工具类和辅助函数
+
+## ChunkBuffer 详细说明
+
+ChunkBuffer 模块提供了一个高效的流式数据缓冲解决方案，用于管理按线程(thread)组织的消息块(chunk)。
+
+### 核心特性
+
+1. **Thread-based Organization**: 每个 thread 维护独立的 chunk 缓冲区
+2. **Sequential Chunk Storage**: Chunks 按到达顺序存储，无需唯一 ID
+3. **Explicit Status Management**: Thread 状态通过显式调用管理（active/completed/aborted）
+4. **Hybrid Cleanup Strategy**: 
+   - 懒清理(Lazy Cleanup): 访问时自动清除过期 thread
+   - 可选周期清理: 后台定时器定期清理过期 thread
+5. **TTL Auto-Extension**: 有新 chunk 加入时自动延长 TTL
+
+### API Overview
+
+```typescript
+// Core operations
+addChunk(threadId, messageId, content)      // Add chunk to thread
+getChunks(threadId)                         // Get all chunks for a thread
+getAccumulatedContent(threadId)             // Get concatenated content
+getChunksByMessageId(threadId, messageId)   // Get chunks for specific message
+
+// Thread status management
+completeThread(threadId)                    // Mark thread as completed
+abortThread(threadId)                       // Mark thread as aborted
+isThreadActive(threadId)                    // Check if thread is active
+getThreadStatus(threadId)                   // Get thread status
+
+// Thread lifecycle
+clearThread(threadId)                       // Remove specific thread
+cleanupExpiredThreads()                     // Manual cleanup of expired threads
+extendThreadTTL(threadId, additionalMs)     // Extend thread expiration time
+
+// Query operations
+getActiveThreads()                          // Get all active thread IDs
+getAllThreads()                             // Get all thread IDs
+getStats()                                  // Get buffer statistics
+```
+
+### Configuration Options
+
+```typescript
+interface ThreadBufferConfig {
+  ttl?: number;              // Time-to-live in ms (default: 1 hour)
+  cleanupInterval?: number;  // Optional periodic cleanup interval in ms
+}
+```
+
+### Use Cases
+
+- **Streaming AI Responses**: Buffer streaming responses from LLM models
+- **Real-time Data Processing**: Collect and organize real-time data streams
+- **Message Aggregation**: Aggregate fragmented messages by thread
+- **Temporary Cache**: Short-term caching with automatic expiration

package/dist/index.d.mts

@@ -5,7 +5,7 @@ import { BaseChatModel, BaseChatModelCallOptions } from '@langchain/core/languag
 import { BaseLanguageModelInput } from '@langchain/core/language_models/base';
 import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import { ChatResult } from '@langchain/core/outputs';
-import { LLMConfig, ToolConfig, ToolExecutor, AgentConfig, GraphBuildOptions } from '@axiom-lattice/protocols';
+import { LLMConfig, ToolConfig, ToolExecutor, AgentConfig, GraphBuildOptions, MessageChunk } from '@axiom-lattice/protocols';
 import * as protocols from '@axiom-lattice/protocols';
 export { protocols as Protocols };
 export { AgentConfig, AgentType, GraphBuildOptions, MemoryType } from '@axiom-lattice/protocols';
@@ -13,6 +13,7 @@ import * as _langchain_core_tools from '@langchain/core/tools';
 import { StructuredTool } from '@langchain/core/tools';
 import { CompiledStateGraph } from '@langchain/langgraph';
 import { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint';
+import { ReplaySubject } from 'rxjs';
 
 /**
  * BaseLatticeManager - 抽象基类，为各种Lattice管理器提供通用功能
@@ -442,4 +443,199 @@ declare class MemoryLatticeManager extends BaseLatticeManager {
 declare const getCheckpointSaver: (key: string) => BaseCheckpointSaver<number>;
 declare const registerCheckpointSaver: (key: string, saver: BaseCheckpointSaver) => void;
 
-export { type AgentClient, type AgentLattice, AgentLatticeManager, MemoryLatticeManager, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, type ToolDefinition, type ToolLattice, ToolLatticeManager, agentLatticeManager, getAgentClient, getAgentConfig, getAgentLattice, getAllAgentConfigs, getAllToolDefinitions, getCheckpointSaver, getModelLattice, getToolClient, getToolDefinition, getToolLattice, modelLatticeManager, registerAgentLattice, registerAgentLattices, registerCheckpointSaver, registerModelLattice, registerToolLattice, toolLatticeManager, validateAgentInput, validateToolInput };
+/**
+ * ChunkBuffer Types
+ *
+ * Defines types for managing streaming chunks organized by thread
+ */
+
+/**
+ * Represents a single chunk of data
+ * Chunks are identified by their position in the sequence (no unique ID)
+ */
+interface Chunk {
+    messageId: string;
+    content: MessageChunk;
+}
+/**
+ * Thread status - requires explicit state transitions
+ */
+declare enum ThreadStatus {
+    ACTIVE = "active",
+    COMPLETED = "completed",
+    ABORTED = "aborted"
+}
+/**
+ * Thread buffer configuration
+ */
+interface ThreadBufferConfig {
+    ttl?: number;
+    cleanupInterval?: number;
+}
+/**
+ * Thread buffer state
+ */
+interface ThreadBuffer {
+    threadId: string;
+    chunks$: ReplaySubject<MessageChunk>;
+    status: ThreadStatus;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number;
+}
+/**
+ * Buffer statistics
+ */
+interface BufferStats {
+    totalThreads: number;
+    activeThreads: number;
+    completedThreads: number;
+    abortedThreads: number;
+    config: Required<ThreadBufferConfig>;
+}
+
+/**
+ * ChunkBuffer Abstract Base Class
+ *
+ * Defines the interface for chunk buffer implementations
+ */
+
+declare abstract class ChunkBuffer {
+    /**
+     * Add a chunk to a thread (creates thread if not exists)
+     * Chunks are appended in order
+     */
+    abstract addChunk(threadId: string, content: MessageChunk): Promise<void>;
+    /**
+     * Mark thread as completed (explicit call)
+     */
+    abstract completeThread(threadId: string): Promise<void>;
+    /**
+     * Mark thread as aborted (explicit call)
+     */
+    abstract abortThread(threadId: string): Promise<void>;
+    /**
+     * Check if thread is still active
+     */
+    abstract isThreadActive(threadId: string): Promise<boolean>;
+    /**
+     * Get thread status (returns undefined if thread doesn't exist)
+     */
+    abstract getThreadStatus(threadId: string): Promise<ThreadStatus | undefined>;
+    /**
+     * Get thread buffer info including metadata
+     */
+    abstract getThreadBuffer(threadId: string): Promise<ThreadBuffer | undefined>;
+    /**
+     * Clear specific thread buffer
+     */
+    abstract clearThread(threadId: string): Promise<void>;
+    /**
+     * Get all active thread IDs
+     */
+    abstract getActiveThreads(): Promise<string[]>;
+    /**
+     * Get all thread IDs (regardless of status)
+     */
+    abstract getAllThreads(): Promise<string[]>;
+    /**
+     * Manually trigger cleanup of expired threads
+     * Returns number of threads cleaned up
+     */
+    abstract cleanupExpiredThreads(): Promise<number>;
+    /**
+     * Extend thread TTL (reset expiration time)
+     */
+    abstract extendThreadTTL(threadId: string, additionalMs?: number): Promise<void>;
+    /**
+     * Check if a thread exists (valid or expired)
+     */
+    abstract hasThread(threadId: string): Promise<boolean>;
+    abstract getNewChunksSinceContentIterator(threadId: string, messageId: string, knownContent: string): AsyncIterable<MessageChunk>;
+}
+
+/**
+ * InMemoryChunkBuffer
+ *
+ * In-memory implementation of ChunkBuffer with hybrid cleanup strategy:
+ * - Lazy cleanup: expired threads are removed on access
+ * - Optional periodic cleanup: background timer to clean expired threads
+ */
+
+declare class InMemoryChunkBuffer extends ChunkBuffer {
+    private buffers;
+    private config;
+    private cleanupTimer?;
+    constructor(config?: ThreadBufferConfig & {
+        maxChunks?: number;
+    });
+    /**
+     * Start automatic periodic cleanup timer
+     */
+    private startCleanupTimer;
+    /**
+     * Stop cleanup timer (for cleanup/shutdown)
+     */
+    stopCleanupTimer(): void;
+    /**
+     * Check if a buffer is expired (lazy cleanup helper)
+     */
+    private isExpired;
+    /**
+     * Get buffer if valid, perform lazy cleanup if expired
+     */
+    private getBufferIfValid;
+    /**
+     * Create or get thread buffer
+     */
+    private getOrCreateBuffer;
+    addChunk(threadId: string, content: MessageChunk): Promise<void>;
+    completeThread(threadId: string): Promise<void>;
+    abortThread(threadId: string): Promise<void>;
+    isThreadActive(threadId: string): Promise<boolean>;
+    getThreadStatus(threadId: string): Promise<ThreadStatus | undefined>;
+    getThreadBuffer(threadId: string): Promise<ThreadBuffer | undefined>;
+    clearThread(threadId: string): Promise<void>;
+    getActiveThreads(): Promise<string[]>;
+    getAllThreads(): Promise<string[]>;
+    hasThread(threadId: string): Promise<boolean>;
+    /**
+     * Cleanup expired threads based on TTL
+     * Returns number of threads cleaned up
+     */
+    cleanupExpiredThreads(): Promise<number>;
+    extendThreadTTL(threadId: string, additionalMs?: number): Promise<void>;
+    getNewChunksSinceContentIterator(threadId: string, messageId: string, knownContent: string): AsyncIterable<MessageChunk>;
+    getStats(): BufferStats;
+    dispose(): void;
+}
+
+/**
+ * ChunkBufferLatticeManager
+ *
+ * Manages ChunkBuffer instances following the Lattice pattern
+ */
+
+/**
+ * ChunkBuffer Lattice Manager
+ */
+declare class ChunkBufferLatticeManager extends BaseLatticeManager<ChunkBuffer> {
+    private static instance;
+    /**
+     * Private constructor for singleton pattern
+     */
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): ChunkBufferLatticeManager;
+    /**
+     * Get Lattice type identifier
+     */
+    protected getLatticeType(): string;
+}
+declare const getChunkBuffer: (key: string) => ChunkBuffer | undefined;
+declare const registerChunkBuffer: (key: string, buffer: ChunkBuffer) => void;
+declare const hasChunkBuffer: (key: string) => boolean;
+
+export { type AgentClient, type AgentLattice, AgentLatticeManager, type BufferStats, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, InMemoryChunkBuffer, MemoryLatticeManager, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, type ThreadBuffer, type ThreadBufferConfig, ThreadStatus, type ToolDefinition, type ToolLattice, ToolLatticeManager, agentLatticeManager, getAgentClient, getAgentConfig, getAgentLattice, getAllAgentConfigs, getAllToolDefinitions, getCheckpointSaver, getChunkBuffer, getModelLattice, getToolClient, getToolDefinition, getToolLattice, hasChunkBuffer, modelLatticeManager, registerAgentLattice, registerAgentLattices, registerCheckpointSaver, registerChunkBuffer, registerModelLattice, registerToolLattice, toolLatticeManager, validateAgentInput, validateToolInput };

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { BaseChatModel, BaseChatModelCallOptions } from '@langchain/core/languag
 import { BaseLanguageModelInput } from '@langchain/core/language_models/base';
 import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import { ChatResult } from '@langchain/core/outputs';
-import { LLMConfig, ToolConfig, ToolExecutor, AgentConfig, GraphBuildOptions } from '@axiom-lattice/protocols';
+import { LLMConfig, ToolConfig, ToolExecutor, AgentConfig, GraphBuildOptions, MessageChunk } from '@axiom-lattice/protocols';
 import * as protocols from '@axiom-lattice/protocols';
 export { protocols as Protocols };
 export { AgentConfig, AgentType, GraphBuildOptions, MemoryType } from '@axiom-lattice/protocols';
@@ -13,6 +13,7 @@ import * as _langchain_core_tools from '@langchain/core/tools';
 import { StructuredTool } from '@langchain/core/tools';
 import { CompiledStateGraph } from '@langchain/langgraph';
 import { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint';
+import { ReplaySubject } from 'rxjs';
 
 /**
  * BaseLatticeManager - 抽象基类，为各种Lattice管理器提供通用功能
@@ -442,4 +443,199 @@ declare class MemoryLatticeManager extends BaseLatticeManager {
 declare const getCheckpointSaver: (key: string) => BaseCheckpointSaver<number>;
 declare const registerCheckpointSaver: (key: string, saver: BaseCheckpointSaver) => void;
 
-export { type AgentClient, type AgentLattice, AgentLatticeManager, MemoryLatticeManager, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, type ToolDefinition, type ToolLattice, ToolLatticeManager, agentLatticeManager, getAgentClient, getAgentConfig, getAgentLattice, getAllAgentConfigs, getAllToolDefinitions, getCheckpointSaver, getModelLattice, getToolClient, getToolDefinition, getToolLattice, modelLatticeManager, registerAgentLattice, registerAgentLattices, registerCheckpointSaver, registerModelLattice, registerToolLattice, toolLatticeManager, validateAgentInput, validateToolInput };
+/**
+ * ChunkBuffer Types
+ *
+ * Defines types for managing streaming chunks organized by thread
+ */
+
+/**
+ * Represents a single chunk of data
+ * Chunks are identified by their position in the sequence (no unique ID)
+ */
+interface Chunk {
+    messageId: string;
+    content: MessageChunk;
+}
+/**
+ * Thread status - requires explicit state transitions
+ */
+declare enum ThreadStatus {
+    ACTIVE = "active",
+    COMPLETED = "completed",
+    ABORTED = "aborted"
+}
+/**
+ * Thread buffer configuration
+ */
+interface ThreadBufferConfig {
+    ttl?: number;
+    cleanupInterval?: number;
+}
+/**
+ * Thread buffer state
+ */
+interface ThreadBuffer {
+    threadId: string;
+    chunks$: ReplaySubject<MessageChunk>;
+    status: ThreadStatus;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number;
+}
+/**
+ * Buffer statistics
+ */
+interface BufferStats {
+    totalThreads: number;
+    activeThreads: number;
+    completedThreads: number;
+    abortedThreads: number;
+    config: Required<ThreadBufferConfig>;
+}
+
+/**
+ * ChunkBuffer Abstract Base Class
+ *
+ * Defines the interface for chunk buffer implementations
+ */
+
+declare abstract class ChunkBuffer {
+    /**
+     * Add a chunk to a thread (creates thread if not exists)
+     * Chunks are appended in order
+     */
+    abstract addChunk(threadId: string, content: MessageChunk): Promise<void>;
+    /**
+     * Mark thread as completed (explicit call)
+     */
+    abstract completeThread(threadId: string): Promise<void>;
+    /**
+     * Mark thread as aborted (explicit call)
+     */
+    abstract abortThread(threadId: string): Promise<void>;
+    /**
+     * Check if thread is still active
+     */
+    abstract isThreadActive(threadId: string): Promise<boolean>;
+    /**
+     * Get thread status (returns undefined if thread doesn't exist)
+     */
+    abstract getThreadStatus(threadId: string): Promise<ThreadStatus | undefined>;
+    /**
+     * Get thread buffer info including metadata
+     */
+    abstract getThreadBuffer(threadId: string): Promise<ThreadBuffer | undefined>;
+    /**
+     * Clear specific thread buffer
+     */
+    abstract clearThread(threadId: string): Promise<void>;
+    /**
+     * Get all active thread IDs
+     */
+    abstract getActiveThreads(): Promise<string[]>;
+    /**
+     * Get all thread IDs (regardless of status)
+     */
+    abstract getAllThreads(): Promise<string[]>;
+    /**
+     * Manually trigger cleanup of expired threads
+     * Returns number of threads cleaned up
+     */
+    abstract cleanupExpiredThreads(): Promise<number>;
+    /**
+     * Extend thread TTL (reset expiration time)
+     */
+    abstract extendThreadTTL(threadId: string, additionalMs?: number): Promise<void>;
+    /**
+     * Check if a thread exists (valid or expired)
+     */
+    abstract hasThread(threadId: string): Promise<boolean>;
+    abstract getNewChunksSinceContentIterator(threadId: string, messageId: string, knownContent: string): AsyncIterable<MessageChunk>;
+}
+
+/**
+ * InMemoryChunkBuffer
+ *
+ * In-memory implementation of ChunkBuffer with hybrid cleanup strategy:
+ * - Lazy cleanup: expired threads are removed on access
+ * - Optional periodic cleanup: background timer to clean expired threads
+ */
+
+declare class InMemoryChunkBuffer extends ChunkBuffer {
+    private buffers;
+    private config;
+    private cleanupTimer?;
+    constructor(config?: ThreadBufferConfig & {
+        maxChunks?: number;
+    });
+    /**
+     * Start automatic periodic cleanup timer
+     */
+    private startCleanupTimer;
+    /**
+     * Stop cleanup timer (for cleanup/shutdown)
+     */
+    stopCleanupTimer(): void;
+    /**
+     * Check if a buffer is expired (lazy cleanup helper)
+     */
+    private isExpired;
+    /**
+     * Get buffer if valid, perform lazy cleanup if expired
+     */
+    private getBufferIfValid;
+    /**
+     * Create or get thread buffer
+     */
+    private getOrCreateBuffer;
+    addChunk(threadId: string, content: MessageChunk): Promise<void>;
+    completeThread(threadId: string): Promise<void>;
+    abortThread(threadId: string): Promise<void>;
+    isThreadActive(threadId: string): Promise<boolean>;
+    getThreadStatus(threadId: string): Promise<ThreadStatus | undefined>;
+    getThreadBuffer(threadId: string): Promise<ThreadBuffer | undefined>;
+    clearThread(threadId: string): Promise<void>;
+    getActiveThreads(): Promise<string[]>;
+    getAllThreads(): Promise<string[]>;
+    hasThread(threadId: string): Promise<boolean>;
+    /**
+     * Cleanup expired threads based on TTL
+     * Returns number of threads cleaned up
+     */
+    cleanupExpiredThreads(): Promise<number>;
+    extendThreadTTL(threadId: string, additionalMs?: number): Promise<void>;
+    getNewChunksSinceContentIterator(threadId: string, messageId: string, knownContent: string): AsyncIterable<MessageChunk>;
+    getStats(): BufferStats;
+    dispose(): void;
+}
+
+/**
+ * ChunkBufferLatticeManager
+ *
+ * Manages ChunkBuffer instances following the Lattice pattern
+ */
+
+/**
+ * ChunkBuffer Lattice Manager
+ */
+declare class ChunkBufferLatticeManager extends BaseLatticeManager<ChunkBuffer> {
+    private static instance;
+    /**
+     * Private constructor for singleton pattern
+     */
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): ChunkBufferLatticeManager;
+    /**
+     * Get Lattice type identifier
+     */
+    protected getLatticeType(): string;
+}
+declare const getChunkBuffer: (key: string) => ChunkBuffer | undefined;
+declare const registerChunkBuffer: (key: string, buffer: ChunkBuffer) => void;
+declare const hasChunkBuffer: (key: string) => boolean;
+
+export { type AgentClient, type AgentLattice, AgentLatticeManager, type BufferStats, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, InMemoryChunkBuffer, MemoryLatticeManager, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, type ThreadBuffer, type ThreadBufferConfig, ThreadStatus, type ToolDefinition, type ToolLattice, ToolLatticeManager, agentLatticeManager, getAgentClient, getAgentConfig, getAgentLattice, getAllAgentConfigs, getAllToolDefinitions, getCheckpointSaver, getChunkBuffer, getModelLattice, getToolClient, getToolDefinition, getToolLattice, hasChunkBuffer, modelLatticeManager, registerAgentLattice, registerAgentLattices, registerCheckpointSaver, registerChunkBuffer, registerModelLattice, registerToolLattice, toolLatticeManager, validateAgentInput, validateToolInput };