@limo-labs/deity 0.1.3-alpha.4 → 0.2.0

package/README.md

@@ -1,533 +1,681 @@
-# @limo-labs/deity 4.0
+# @limo-labs/deity
 
-> **高性能 AI 代理编排框架** — 类型安全的工作流运行时，支持对话、内存和会话管理
+> **Declarative AI Agent Framework** — Build type-safe AI agents with JSX/TSX syntax for agents and declarative API for workflows
 
-Deity 4.0 是一个完整的 AI 代理开发框架，提供**确定性执行**、**自动重试**、**对话管理**、**内存管理**和**会话持久化**能力。专为构建长期运行的、有状态的 AI 应用而设计。
+Deity is a declarative framework for building AI agents. **Agents** use familiar JSX/TSX syntax like React components. **Workflows** use declarative function composition. Full TypeScript support and zero runtime overhead.
+
+**Important Distinction:**
+- **Agent Definition:** Uses true JSX/TSX tags (`<Agent>`, `<Prompt>`) in `.tsx` files
+- **Workflow Definition:** Uses function calls (`Workflow()`, `Sequence()`) in `.ts` files
 
 [![npm version](https://img.shields.io/npm/v/@limo-labs/deity.svg)](https://www.npmjs.com/package/@limo-labs/deity)
-[![License](https://img.shields.io/npm/l/@limo-labs/deity.svg)](https://github.com/limo-labs/deity/blob/main/LICENSE)
+[![License](https://img.shields.io/npm/l/@limo-labs/deity.svg)](https://github.com/Limo-Labs/Limo-Deity/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-## ✨ 特性亮点
-
-### 🚀 极致性能
-- **678,532 组件/秒** 吞吐量
-- **< 10ms p99** 延迟
-- **< 15KB** 每次执行内存占用
-- **无内存泄漏** 验证通过
-- **线性扩展** O(n) 性能增长
-
-### 🎯 核心功能
-- ✅ **类型安全** - 完整的 TypeScript 类型支持 + Zod 验证
-- ✅ **工作流编排** - 顺序、条件、循环、并行节点
-- ✅ **自动重试** - 验证失败自动重试 + LLM 反馈
-- ✅ **对话管理** - 自动修剪、角色索引、token 预算
-- ✅ **内存管理** - 分层内存（核心/详细）、自动优先级
-- ✅ **会话持久化** - 自动保存/恢复、灾难恢复
-- ✅ **UI 集成** - 实时进度更新、事件驱动
-- ✅ **工具调用** - 自动工具执行循环
-- ✅ **统计跟踪** - 执行时间、token 使用、重试次数
-
-### 🔧 开发体验
-- 🎨 **直观的 API** - 简洁的函数式接口
-- 📝 **完整的文档** - API 文档 + 使用示例
-- 🧪 **305 个测试** - 100% 通过率
-- 📊 **性能基准** - 27 个基准测试验证
-- 🔍 **详细的跟踪** - 完整的执行日志
-
-## 📦 安装
+## ✨ Features
+
+- 🎨 **JSX/TSX Syntax for Agents** - Write agents with familiar React-like JSX tags (`.tsx` files)
+- 📦 **Declarative Workflow API** - Compose workflows with function calls (`.ts` files)
+- 🔒 **Type Safe** - Full TypeScript support with Zod schema validation
+- 🔧 **Declarative** - Compose agents and workflows from reusable components
+- 🚀 **Zero Runtime Overhead** - Compiles to lightweight AST nodes
+- 🎯 **LLM Agnostic** - Works with any LLM adapter
+- 🔁 **Auto Retry** - Built-in retry logic with LLM feedback
+- ✅ **Output Validation** - Declarative validation rules
+- 🛠️ **Tool Support** - Native tool calling integration
+- 📊 **Observability** - Built-in execution tracing
+
+## 📦 Installation
 
 ```bash
-npm install @limo-labs/deity
+npm install @limo-labs/deity zod
 ```
 
 ```bash
-yarn add @limo-labs/deity
+yarn add @limo-labs/deity zod
 ```
 
 ```bash
-pnpm add @limo-labs/deity
+pnpm add @limo-labs/deity zod
 ```
 
-## 🚀 快速开始
+## 🚀 Quick Start
 
-### 基础组件执行
+### 1. Configure TypeScript (Optional - For JSX/TSX Agent Syntax)
 
-```typescript
-import { z } from 'zod';
-import { executeComponent, createEnhancedContext, InMemoryStore, InMemoryTrace } from '@limo-labs/deity';
-import type { AgentComponent, LLMAdapter } from '@limo-labs/deity';
-
-// 定义组件
-const summarizer: AgentComponent<{ text: string }, { summary: string }> = {
-  id: 'summarizer',
-  inputSchema: z.object({ text: z.string() }),
-  outputSchema: z.object({ summary: z.string() }),
-
-  buildPrompt(ctx) {
-    return [
-      { role: 'system', content: 'You are a summarization expert.' },
-      { role: 'user', content: `Summarize: ${ctx.inputs.text}` }
-    ];
-  },
-
-  validate(output) {
-    if (output.summary.length < 10) {
-      return { valid: false, errors: ['Summary too short'] };
-    }
-    return { valid: true };
-  },
+If you want to use **JSX/TSX tags** for Agent definitions (`.tsx` files), add JSX support to your `tsconfig.json`:
 
-  retry: {
-    maxAttempts: 3,
-    feedbackOnError: true
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@limo-labs/deity"
   }
-};
-
-// 创建上下文
-const ctx = await createEnhancedContext({
-  inputs: { text: 'Long article text...' },
-  store: new InMemoryStore(),
-  trace: new InMemoryTrace()
-});
-
-// 执行组件
-const result = await executeComponent(summarizer, ctx, llmAdapter);
-console.log(result.output.summary);
+}
 ```
 
-### 多步工作流
+**Note:** Workflow definitions use function calls and work in regular `.ts` files without JSX configuration.
 
-```typescript
-import { runWorkflow, createStepNode, createSequenceNode } from '@limo-labs/deity';
-import type { WorkflowConfig } from '@limo-labs/deity';
-
-// 定义步骤
-const step1: AgentComponent = {
-  id: 'analyze',
-  inputSchema: z.object({ code: z.string() }),
-  outputSchema: z.object({ issues: z.array(z.string()) }),
-  buildPrompt: (ctx) => [
-    { role: 'user', content: `Analyze this code: ${ctx.inputs.code}` }
-  ],
-  validate: () => ({ valid: true })
-};
-
-const step2: AgentComponent = {
-  id: 'fix',
-  inputSchema: z.object({}),
-  outputSchema: z.object({ fixes: z.array(z.string()) }),
-  buildPrompt: (ctx) => {
-    const analysis = ctx.getOutput<{ issues: string[] }>('analyze');
-    return [
-      { role: 'user', content: `Fix these issues: ${analysis.issues.join(', ')}` }
-    ];
-  },
-  validate: () => ({ valid: true })
-};
-
-// 配置工作流
-const config: WorkflowConfig = {
-  name: 'code-fix-workflow',
-  graph: createSequenceNode([
-    createStepNode(step1),
-    createStepNode(step2)
-  ]),
-  defaultModel: { adapter: llmAdapter }
-};
-
-// 运行工作流
-const result = await runWorkflow(config, { code: 'function test() { ... }' });
-console.log(result.fixes);
-```
+### 2. Create Your First Agent (Using JSX/TSX Tags)
 
-### 对话管理
+**File:** `agent.tsx` (note the `.tsx` extension for JSX support)
 
-```typescript
-import { createEnhancedContext } from '@limo-labs/deity';
+```tsx
+import { Agent, Prompt, System, User, Result } from '@limo-labs/deity';
+import { z } from 'zod';
 
-// 启用对话
-const ctx = await createEnhancedContext({
-  inputs: {},
-  store: new InMemoryStore(),
-  trace: new InMemoryTrace(),
-  enableConversation: {
-    maxTokens: 4000,
-    pruneWhenFull: true
-  }
+// Define schemas
+const InputSchema = z.object({
+  topic: z.string()
 });
 
-// 使用对话
-const conv = ctx.requireConversation();
-
-conv.addMessage({ role: 'user', content: 'Hello!' });
-conv.addMessage({ role: 'assistant', content: 'Hi there!' });
-
-// 获取历史
-const history = conv.getHistory();
-
-// 按角色过滤
-const userMessages = conv.getMessages('user');
+const OutputSchema = z.object({
+  summary: z.string(),
+  keyPoints: z.array(z.string())
+});
 
-// 自动修剪（当达到 token 限制）
-// 自动保留最新消息，删除旧消息
+// Create agent using JSX tags (requires .tsx file)
+const SummarizerAgent = (
+  <Agent id="summarizer" input={InputSchema} output={OutputSchema}>
+    <Prompt>
+      <System>You are a summarization expert.</System>
+      <User>{(ctx: any): string => `Summarize this topic: ${ctx.inputs.topic}`}</User>
+    </Prompt>
+    <Result>
+      {(ctx: any, llmResult: any) => {
+        // Extract output from LLM response
+        const content = llmResult.response.content;
+        return JSON.parse(content);
+      }}
+    </Result>
+  </Agent>
+);
 ```
 
-### 内存管理
+### 3. Execute the Agent
 
 ```typescript
-import { createEnhancedContext } from '@limo-labs/deity';
+import { compileAgent, executeComponent, createEnhancedContext } from '@limo-labs/deity';
 
-// 启用内存
+// Compile JSX to executable component
+const component = compileAgent(SummarizerAgent);
+
+// Create execution context
 const ctx = await createEnhancedContext({
-  inputs: {},
-  store: new InMemoryStore(),
-  trace: new InMemoryTrace(),
-  enableMemory: {
-    coreBudget: {
-      maxItems: 10,
-      maxTotalSize: 8192
-    }
-  }
+  inputs: { topic: 'Climate change' }
 });
 
-// 使用内存
-const memory = ctx.requireMemory();
+// Execute
+const result = await executeComponent(component, ctx, llmAdapter);
+console.log(result.output.summary);
+```
 
-// 简单存储
-await memory.set('user_name', 'Alice');
-const name = await memory.get('user_name');
+## 📖 Core Concepts
 
-// 添加核心记忆
-await memory.addCoreMemory({
-  id: 'core1',
-  content: 'User prefers concise responses',
-  importance: 9,
-  tags: ['preference']
-});
+### Components
 
-// 加载工作内存
-const relevant = memory.loadWorkingMemory({
-  currentTask: 'response-generation',
-  keywords: ['preference'],
-  maxItems: 5
-});
-```
+Deity provides declarative components for building agents:
 
-### UI 集成
+- **`<Agent>`** - Root component defining the agent
+- **`<Prompt>`** - Prompt construction
+- **`<System>`** - System message
+- **`<User>`** - User message
+- **`<Result>`** - Output extraction
+- **`<Validate>`** - Output validation
+- **`<Retry>`** - Retry configuration
+- **`<Observe>`** - LLM loop observation
 
-```typescript
-import { createUIBridge, runWorkflow } from '@limo-labs/deity';
+### Agent Component
 
-// 创建 UI 桥接
-const ui = createUIBridge();
+The `<Agent>` component is the root of every agent:
 
-// 订阅事件
-ui.on('step:start', (update) => {
-  console.log(`🔄 ${update.name}`);
-});
+```tsx
+<Agent
+  id="unique-id"
+  input={InputSchema}
+  output={OutputSchema}
+  loopConfig={{ maxToolRounds: 10, timeout: 30000 }}
+  tools={[...]}
+>
+  {/* Children components */}
+</Agent>
+```
 
-ui.on('step:progress', (update) => {
-  console.log(`  ${update.progress}% - ${update.message}`);
-});
+**Props:**
+- `id` (required) - Unique agent identifier
+- `input` (required) - Zod schema for input validation
+- `output` (required) - Zod schema for output validation
+- `loopConfig` (optional) - LLM loop configuration
+- `loopValidator` (optional) - Custom loop validator
+- `tools` (optional) - Tool definitions
+
+### Prompt Component
+
+The `<Prompt>` component defines how to build the LLM prompt:
+
+```tsx
+<Prompt>
+  <System>
+    {async (): Promise<string> => {
+      // Load prompt from file or construct dynamically
+      return await loadPromptTemplate();
+    }}
+  </System>
+  <User>
+    {(ctx: any): string => `Process: ${ctx.inputs.task}`}
+  </User>
+</Prompt>
+```
 
-ui.on('step:complete', (update) => {
-  console.log(`✅ ${update.name} completed`);
-});
+### Result Component
 
-// 运行工作流（自动发送 UI 更新）
-const config: WorkflowConfig = {
-  name: 'my-workflow',
-  graph: createSequenceNode([...]),
-  defaultModel: { adapter: llmAdapter },
-  enhancements: { ui }
-};
+The `<Result>` component extracts structured output:
 
-await runWorkflow(config, {});
+```tsx
+<Result>
+  {(ctx: any, llmResult: any): OutputType => {
+    // Extract from tool calls
+    const toolCall = llmResult.response.toolCalls?.find(
+      tc => tc.name === 'submit_result'
+    );
+
+    if (toolCall) {
+      return JSON.parse(toolCall.arguments);
+    }
+
+    // Or extract from text content
+    const match = llmResult.response.content.match(/```json\n(.*?)\n```/s);
+    return JSON.parse(match[1]);
+  }}
+</Result>
 ```
 
-## 📚 核心概念
+### Validate Component
+
+The `<Validate>` component defines validation rules:
+
+```tsx
+<Validate>
+  {(output: any, ctx: any) => ({
+    rules: [
+      {
+        check: output.summary.length >= 100,
+        error: 'Summary must be at least 100 characters'
+      },
+      {
+        check: output.keyPoints.length >= 3,
+        error: 'Must have at least 3 key points'
+      }
+    ]
+  })}
+</Validate>
+```
 
-### AgentComponent（代理组件）
+### Retry Component
 
-组件是 Deity 的基本执行单元：
+The `<Retry>` component configures retry behavior:
 
-```typescript
-interface AgentComponent<I, O> {
-  id: string;                                    // 唯一标识符
-  inputSchema: ZodSchema<I>;                     // 输入验证
-  outputSchema: ZodSchema<O>;                    // 输出验证
-  buildPrompt(ctx: ExecutionContext<I>): Message[];  // 构建提示
-  validate(output: O, ctx: ExecutionContext<I>): ValidationResult;  // 语义验证
-  tools?: Tool[];                                // 可选工具
-  retry?: RetryConfig;                           // 重试配置
-  model?: ModelConfig;                           // 模型覆盖
-}
+```tsx
+<Retry
+  maxAttempts={3}
+  feedbackOnError={true}
+  retryOnToolError={true}
+/>
 ```
 
-### ExecutionContext（执行上下文）
+## 🎯 Examples
+
+### Simple Summarizer
+
+```tsx
+const Summarizer = (
+  <Agent id="summarizer" input={InputSchema} output={OutputSchema}>
+    <Prompt>
+      <System>You are a summarization expert.</System>
+      <User>{(ctx: any): string => `Summarize: ${ctx.inputs.text}`}</User>
+    </Prompt>
+    <Result>
+      {(ctx: any, llmResult: any) => ({
+        summary: llmResult.response.content
+      })}
+    </Result>
+    <Validate>
+      {(output: any) => ({
+        rules: [
+          {
+            check: output.summary.length >= 50,
+            error: 'Summary too short'
+          }
+        ]
+      })}
+    </Validate>
+    <Retry maxAttempts={2} feedbackOnError={true} />
+  </Agent>
+);
+```
 
-上下文提供对所有功能的访问：
+### Code Analyzer with Tools
+
+```tsx
+import { createMemoryTools } from '@limo-labs/deity';
+
+const CodeAnalyzer = (
+  <Agent
+    id="analyzer"
+    input={z.object({ repoPath: z.string() })}
+    output={z.object({ findings: z.array(z.any()) })}
+    tools={[
+      ...createMemoryTools(),
+      {
+        name: 'read_file',
+        description: 'Read file contents',
+        inputSchema: z.object({ path: z.string() }),
+        async execute(input) {
+          return { content: await fs.readFile(input.path, 'utf-8') };
+        }
+      }
+    ]}
+  >
+    <Prompt>
+      <System>
+        {async (): Promise<string> => {
+          return await fs.readFile('./prompts/analyzer.md', 'utf-8');
+        }}
+      </System>
+      <User>
+        {(ctx: any): string => `Analyze repository at: ${ctx.inputs.repoPath}`}
+      </User>
+    </Prompt>
+    <Result>
+      {(ctx: any, llmResult: any) => {
+        // Count memory_store tool calls to verify analysis
+        const findings = llmResult.response.toolCalls
+          ?.filter((tc: any) => tc.name === 'memory_store')
+          .map((tc: any) => JSON.parse(tc.arguments));
+
+        return { findings };
+      }}
+    </Result>
+  </Agent>
+);
+```
 
-```typescript
-interface ExecutionContext<I> {
-  // 基础
-  inputs: I;
-  getOutput<T>(componentId: string): T;
-
-  // 可选增强
-  conversation?: ConversationManager;
-  memory?: LimoMemoryManager;
-  session?: SessionStore;
-  ui?: UIUpdateBridge;
-
-  // 存储和跟踪
-  store: StateStore;
-  trace: TraceLogger;
-  stats: ExecutionStats;
-}
+### Dynamic Tool Factory (NEW in 4.0)
+
+**Tool Factory Pattern** - Create tools dynamically based on execution context:
+
+```tsx
+import { createMemoryTools } from '@limo-labs/deity';
+
+const DynamicAgent = (
+  <Agent
+    id="dynamic"
+    input={z.object({ enableMemory: z.boolean() })}
+    output={z.object({ result: z.string() })}
+    tools={(ctx) => {
+      // Static tools always available
+      const staticTools = [
+        {
+          name: 'read_file',
+          description: 'Read file',
+          inputSchema: z.object({ path: z.string() }),
+          async execute(input) {
+            return await fs.readFile(input.path, 'utf-8');
+          }
+        }
+      ];
+
+      // Add memory tools conditionally
+      const memoryTools = ctx.memory ? createMemoryTools(ctx) : [];
+
+      return [...staticTools, ...memoryTools];
+    }}
+  >
+    {/* ... */}
+  </Agent>
+);
 ```
 
-### 工作流图
+**Key Benefits:**
+- ✅ Tools can access ExecutionContext at creation time
+- ✅ Conditional tool inclusion based on context state
+- ✅ Enables Deity's memory tools in TSX workflows
+- ✅ Backward compatible with static tool arrays
+
+### Multi-Step Workflow
+
+```tsx
+const MultiStepAgent = (
+  <Agent id="multi-step" input={InputSchema} output={OutputSchema}>
+    <Prompt>
+      <System>
+        {async (): Promise<string> => {
+          const step = ctx.inputs.currentStep;
+          return await loadStepPrompt(step);
+        }}
+      </System>
+      <User>{(ctx: any): string => buildStepMessage(ctx)}</User>
+    </Prompt>
+    <Observe>
+      {(llmResult: any) => ({
+        toolCallCount: llmResult.response.toolCalls?.length || 0,
+        roundsExecuted: llmResult.rounds
+      })}
+    </Observe>
+    <Result>
+      {(ctx: any, llmResult: any, observed: any) => {
+        console.log(`Executed ${observed.roundsExecuted} rounds`);
+        return extractStepOutput(llmResult);
+      }}
+    </Result>
+  </Agent>
+);
+```
 
-使用节点构建复杂的工作流：
+## 🔧 Advanced Features
 
-```typescript
-// 顺序执行
-createSequenceNode([step1, step2, step3])
+### Loop Validation
 
-// 条件执行
-createConditionalNode(
-  (ctx) => ctx.getOutput('check').needsMore,
-  trueBranch,
-  falseBranch
-)
+Use `loopValidator` to validate during LLM execution loops:
 
-// 循环执行
-createLoopNode(step, iterations)
+```typescript
+import type { Validator, LLMLoopState, ExecutionContext } from '@limo-labs/deity';
+
+class CustomValidator implements Validator {
+  async validate(
+    ctx: ExecutionContext,
+    loopState: LLMLoopState
+  ): Promise<ValidationResult> {
+    // Check if required tool was called
+    const requiredTool = loopState.toolCallsThisRound.find(
+      tc => tc.name === 'submit_plan'
+    );
+
+    if (!requiredTool) {
+      return {
+        valid: false,
+        feedback: 'You must call submit_plan tool to complete this task'
+      };
+    }
 
-// 并行执行
-createParallelNode([branch1, branch2])
+    return { valid: true };
+  }
+}
+
+const agent = (
+  <Agent
+    id="planner"
+    input={InputSchema}
+    output={OutputSchema}
+    loopValidator={new CustomValidator()}
+  >
+    {/* ... */}
+  </Agent>
+);
 ```
 
-## 📖 文档
+### Loop Configuration
+
+Configure LLM execution loop behavior:
+
+```tsx
+<Agent
+  id="agent"
+  input={InputSchema}
+  output={OutputSchema}
+  loopConfig={{
+    maxToolRounds: 15,   // Max tool execution rounds
+    timeout: 180000      // 3 minute timeout
+  }}
+>
+  {/* ... */}
+</Agent>
+```
 
-- [API 文档](./docs/API.md) - 完整的 API 参考
-- [使用示例](./docs/EXAMPLES.md) - 实际使用案例
-- [迁移指南](./docs/MIGRATION.md) - 从 3.x 迁移
-- [最佳实践](./docs/BEST_PRACTICES.md) - 设计模式和建议
-- [性能报告](./PHASE_9_PERFORMANCE_REPORT.md) - 基准测试结果
+### Dynamic Prompts
 
-## 🏗️ 架构
+Load prompts from files or construct dynamically:
 
-Deity 4.0 采用模块化架构：
+```tsx
+<System>
+  {async (ctx: any): Promise<string> => {
+    // Load from file
+    const template = await fs.readFile('./prompts/system.md', 'utf-8');
 
-```
-┌─────────────────────────────────────────┐
-│           Workflow Runner               │
-│  (executeComponent, runWorkflow)        │
-└─────────────────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────┐
-│         Execution Context               │
-│  ┌──────────┬──────────┬──────────┐    │
-│  │Conversation│Memory  │ Session  │    │
-│  │ Manager   │Manager │  Store   │    │
-│  └──────────┴──────────┴──────────┘    │
-│  ┌──────────┬──────────┬──────────┐    │
-│  │   UI     │  Stats   │  Trace   │    │
-│  │  Bridge  │ Tracker  │  Logger  │    │
-│  └──────────┴──────────┴──────────┘    │
-└─────────────────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────┐
-│           LLM Adapter                   │
-│  (OpenAI, Anthropic, etc.)              │
-└─────────────────────────────────────────┘
+    // Inject dynamic content
+    return template.replace('{{language}}', ctx.inputs.language);
+  }}
+</System>
 ```
 
-### 模块说明
+## 🎨 Component Composition
 
-- **Runtime** - 工作流执行引擎
-- **Context** - 执行上下文和状态管理
-- **Conversation** - 对话历史管理
-- **Memory** - 分层内存系统
-- **Session** - 持久化和恢复
-- **UI** - 实时进度更新
-- **Core** - 核心类型和工具
+Agents can be composed from reusable functions:
 
-## 🎯 性能
+```typescript
+// Reusable prompt builders
+function buildSystemPrompt(role: string) {
+  return async (): Promise<string> => {
+    return `You are a ${role}.`;
+  };
+}
 
-基于 27 个基准测试的实际测试结果：
+function buildUserPrompt(template: string) {
+  return (ctx: any): string => {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => ctx.inputs[key]);
+  };
+}
 
-| 指标 | 性能 |
-|------|------|
-| **吞吐量** | 678,532 组件/秒 |
-| **延迟 (p99)** | < 10ms |
-| **内存/执行** | < 15KB |
-| **扩展性** | O(n) 线性 |
-| **内存泄漏** | 无 (-5.3% growth) |
+// Reusable result extractors
+function extractJSONFromToolCall(toolName: string) {
+  return (ctx: any, llmResult: any) => {
+    const toolCall = llmResult.response.toolCalls?.find(
+      (tc: any) => tc.name === toolName
+    );
+    return JSON.parse(toolCall.arguments);
+  };
+}
 
-详见 [性能报告](./PHASE_9_PERFORMANCE_REPORT.md)。
+// Compose agent
+const agent = (
+  <Agent id="composer" input={InputSchema} output={OutputSchema}>
+    <Prompt>
+      <System>{buildSystemPrompt('expert')}</System>
+      <User>{buildUserPrompt('Process {{task}}')}</User>
+    </Prompt>
+    <Result>{extractJSONFromToolCall('submit')}</Result>
+  </Agent>
+);
+```
 
-## 🧪 测试
+## 📚 Utilities
 
-Deity 4.0 拥有全面的测试覆盖：
+### Tool Result Extraction
 
-- **305 个单元测试** - 100% 通过率
-- **27 个性能基准** - 所有目标达成
-- **85%+ 代码覆盖率** - 核心模块
+```typescript
+import { extractLastToolResult, extractAllToolResults, countToolCalls } from '@limo-labs/deity';
 
-```bash
-# 运行所有测试
-npm test
+// Extract single tool result
+const result = extractLastToolResult(llmResult, 'tool_name', {
+  unwrap: true,
+  required: true
+});
 
-# 运行基准测试
-npm test -- src/v4/__tests__/benchmark/
+// Extract all results from a tool
+const allResults = extractAllToolResults(llmResult, 'memory_store');
 
-# 生成覆盖率报告
-npm test -- --coverage
+// Count tool calls
+const count = countToolCalls(llmResult, 'memory_store', (result) => {
+  return result?.success === true;
+});
 ```
 
-## 📝 使用场景
-
-### 1. 代码分析代理
+### Memory Tools
 
 ```typescript
-// 索引 → 分析 → 报告生成
-const workflow = createSequenceNode([
-  createStepNode(indexRepo),
-  createStepNode(analyzeCode),
-  createStepNode(generateReport)
-]);
+import { createMemoryTools } from '@limo-labs/deity';
+
+const agent = (
+  <Agent
+    id="agent"
+    input={InputSchema}
+    output={OutputSchema}
+    tools={createMemoryTools()}
+  >
+    {/* Agent can now use memory_store, memory_recall, etc. */}
+  </Agent>
+);
 ```
 
-### 2. 对话式助手
+## 🏗️ Architecture
 
-```typescript
-// 启用对话和内存
-const ctx = await createEnhancedContext({
-  inputs: {},
-  enableConversation: true,
-  enableMemory: true
-});
-
-// 组件可以访问对话历史和记忆
 ```
+┌─────────────────────────────────────────┐
+│         JSX/TSX Components              │
+│  <Agent>, <Prompt>, <Result>, etc.     │
+└─────────────────────────────────────────┘
+                  ↓ compileAgent()
+┌─────────────────────────────────────────┐
+│           AST Nodes                     │
+│  AgentNode, PromptNode, ResultNode      │
+└─────────────────────────────────────────┘
+                  ↓ executeComponent()
+┌─────────────────────────────────────────┐
+│        Execution Engine                 │
+│  - Build Prompt                         │
+│  - Call LLM Loop                        │
+│  - Extract Output                       │
+│  - Validate                             │
+│  - Retry if needed                      │
+└─────────────────────────────────────────┘
+```
+
+## 🧪 Testing
 
-### 3. 长期运行任务
+Deity includes utilities for testing agents:
 
 ```typescript
-// 启用会话持久化
-const ctx = await createEnhancedContext({
-  inputs: {},
-  enableSession: { directory: './.deity-sessions' }
+import { testFullAgent } from '@limo-labs/deity';
+
+const result = await testFullAgent(agent, {
+  inputs: { task: 'test' },
+  mockLLMResponse: {
+    content: '{"result": "success"}',
+    toolCalls: []
+  }
 });
 
-// 自动保存进度，支持崩溃恢复
+expect(result.output).toEqual({ result: 'success' });
 ```
 
-### 4. 实时 UI 反馈
+## 📖 Documentation
 
-```typescript
-// UI 事件驱动的进度更新
-ui.on('step:progress', (update) => {
-  updateProgressBar(update.progress);
-});
-```
+- [API Reference](./docs/API.md) - Full API documentation
+- [**Declarative Workflow Guide**](./docs/TSX_WORKFLOW.md) - **NEW: Build workflows with declarative API**
+- [Workflow Quick Reference](./docs/TSX_WORKFLOW_QUICK_REF.md) - Quick syntax reference
+- [Migration Guide](./docs/MIGRATION.md) - Migrating from imperative API
+- [Best Practices](./docs/BEST_PRACTICES.md) - Design patterns and tips
+- [Examples](./docs/EXAMPLES.md) - Real-world examples
 
-## 🔧 高级功能
+## 🔀 Declarative Workflows (NEW in 4.0)
 
-### 工具调用
+Deity 4.0 introduces **Declarative Workflow API** - build complex multi-agent workflows with function composition:
+
+**Note:** Despite the name "TSX Workflow", these use **function calls** (`.ts` files), not JSX tags. Only Agent definitions support true JSX/TSX syntax.
 
 ```typescript
-const component: AgentComponent = {
-  id: 'search',
-  tools: [{
-    name: 'search_code',
-    description: 'Search codebase',
-    inputSchema: z.object({ query: z.string() }),
-    async execute(input) {
-      return { results: await searchCode(input.query) };
-    }
-  }],
-  // ...
-};
-```
+import { Workflow, Sequence, Parallel, Conditional, runTSXWorkflow } from '@limo-labs/deity';
 
-### 自定义重试策略
+const workflow = Workflow({
+  name: 'code-analysis',
+  defaultModel: { adapter: llmAdapter },
+  children: Sequence({
+    children: [
+      // Step 1: Classify code
+      ClassifierAgent,
+
+      // Step 2: Branch based on complexity
+      Conditional({
+        condition: (ctx) => ctx.getOutput('classifier').isComplex,
+        children: [
+          // Complex: parallel deep analysis
+          Parallel({
+            children: [
+              SecurityAnalyzer,
+              PerformanceAnalyzer,
+              QualityAnalyzer,
+            ],
+          }),
+          // Simple: quick summary
+          QuickSummary,
+        ],
+      }),
+
+      // Step 3: Generate report
+      ReportGenerator,
+    ],
+  }),
+});
 
-```typescript
-const component: AgentComponent = {
-  id: 'component',
-  retry: {
-    maxAttempts: 5,
-    feedbackOnError: true,
-    backoff: 'exponential'
-  },
-  validate(output, ctx) {
-    // 自定义验证逻辑
-    if (output.quality < 0.8) {
-      return {
-        valid: false,
-        errors: ['Quality too low'],
-        feedback: 'Please improve quality by focusing on...'
-      };
-    }
-    return { valid: true };
-  }
-};
+// Execute
+const result = await runTSXWorkflow(workflow, { code: '...' });
 ```
 
-### 条件工作流
+### Workflow Components
 
-```typescript
-const workflow = createSequenceNode([
-  createStepNode(checkComponent),
-  createConditionalNode(
-    (ctx) => ctx.getOutput('check').needsProcessing,
-    createStepNode(processComponent),
-    createStepNode(skipComponent)
-  )
-]);
-```
+- **`Sequence`** - Execute children in order (function call)
+- **`Parallel`** - Execute children concurrently (function call)
+- **`Conditional`** - Branch based on condition (function call)
+- **`Loop`** - Execute child N times (function call)
+- **`ForEach`** - Execute child for each item in array (function call)
+
+**[➡️ Full TSX Workflow Guide](./docs/TSX_WORKFLOW.md)**
+
+## 🔗 Integration
+
+### LLM Adapters
 
-### 循环工作流
+Deity works with any LLM adapter that implements the `LLMAdapter` interface:
 
 ```typescript
-const workflow = createLoopNode(
-  createStepNode(iterativeComponent),
-  10  // 迭代 10 次
-);
+interface LLMAdapter {
+  generate(
+    messages: Message[],
+    tools?: Tool[],
+    config?: GenerationConfig,
+    ctx?: ExecutionContext
+  ): Promise<LLMResponse>;
+}
 ```
 
-## 🌟 与 Deity 3.x 的区别
+Example adapters:
+- `@limo-labs/deity-adapter-openai` - OpenAI GPT models
+- `@limo-labs/deity-adapter-anthropic` - Claude models
+- `@limo-labs/deity-adapter-copilot` - GitHub Copilot SDK
+
+### Framework Integration
 
-| 特性 | Deity 3.x | Deity 4.0 |
-|------|-----------|-----------|
-| **对话管理** | ❌ | ✅ 自动修剪 + 索引 |
-| **内存管理** | ❌ | ✅ 分层内存系统 |
-| **会话持久化** | ❌ | ✅ 自动保存/恢复 |
-| **UI 集成** | ❌ | ✅ 事件驱动更新 |
-| **性能** | ~100 ops/sec | 678,532 ops/sec |
-| **类型安全** | ✅ | ✅ 增强 |
-| **工作流节点** | 基础 | ✅ 条件/循环/并行 |
+- **Express/Fastify** - Use as API handlers
+- **Next.js** - Server actions and API routes
+- **Electron** - Desktop app agents
+- **CLI Tools** - Command-line AI agents
 
-## 🤝 贡献
+## 🤝 Contributing
 
-欢迎贡献！请查看 [贡献指南](./CONTRIBUTING.md)。
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-## 📄 许可证
+## 📄 License
 
 MIT © [Limo Labs](https://github.com/limo-labs)
 
-## 🔗 链接
+## 🔗 Links
 
-- [GitHub](https://github.com/limo-labs/deity)
-- [文档](https://deity.limo.run)
-- [问题反馈](https://github.com/limo-labs/deity/issues)
-- [更新日志](./CHANGELOG.md)
+- [GitHub](https://github.com/Limo-Labs/Limo-Deity)
+- [npm](https://www.npmjs.com/package/@limo-labs/deity)
+- [Documentation](https://deity.limo.run)
+- [Issues](https://github.com/Limo-Labs/Limo-Deity/issues)
+- [Changelog](./CHANGELOG.md)
 
 ---
 
-**由 Limo Labs 用 ❤️ 构建**
+**Built with ❤️ by Limo Labs**