# Lattice Core

这是 Lattice 项目的核心库，提供了基于 LangGraph 的智能代理构建基础设施。

## 功能特点

- 模型格子管理 (ModelLatticeManager)
- 工具格子管理 (ToolLatticeManager)
- 代理格子管理 (AgentLatticeManager)
- 记忆格子管理 (MemoryLatticeManager)
- 流式缓冲管理 (ChunkBufferLatticeManager)
- DeepAgent 实现
- 工具类和辅助函数

## 安装

```bash
pnpm install
```

## 构建

```bash
pnpm build
```

## 测试

```bash
pnpm test
```

## 使用示例

### Model Lattice

```typescript
import { ModelLatticeManager } from "@axiom-lattice/core";

// 创建模型格子管理器
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();
```

## 目录结构

- `src/base/`: 基础类和接口
- `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
