@limo-labs/deity 0.2.1 → 0.2.2

package/README.md

@@ -1,681 +0,0 @@
-# @limo-labs/deity
-
-> **Declarative AI Agent Framework** — Build type-safe AI agents with JSX/TSX syntax for agents and declarative API for workflows
-
-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/Limo-Deity/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-
-## ✨ 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 zod
-```
-
-```bash
-yarn add @limo-labs/deity zod
-```
-
-```bash
-pnpm add @limo-labs/deity zod
-```
-
-## 🚀 Quick Start
-
-### 1. Configure TypeScript (Optional - For JSX/TSX Agent Syntax)
-
-If you want to use **JSX/TSX tags** for Agent definitions (`.tsx` files), add JSX support to your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "@limo-labs/deity"
-  }
-}
-```
-
-**Note:** Workflow definitions use function calls and work in regular `.ts` files without JSX configuration.
-
-### 2. Create Your First Agent (Using JSX/TSX Tags)
-
-**File:** `agent.tsx` (note the `.tsx` extension for JSX support)
-
-```tsx
-import { Agent, Prompt, System, User, Result } from '@limo-labs/deity';
-import { z } from 'zod';
-
-// Define schemas
-const InputSchema = z.object({
-  topic: z.string()
-});
-
-const OutputSchema = z.object({
-  summary: z.string(),
-  keyPoints: z.array(z.string())
-});
-
-// 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 { compileAgent, executeComponent, createEnhancedContext } from '@limo-labs/deity';
-
-// Compile JSX to executable component
-const component = compileAgent(SummarizerAgent);
-
-// Create execution context
-const ctx = await createEnhancedContext({
-  inputs: { topic: 'Climate change' }
-});
-
-// Execute
-const result = await executeComponent(component, ctx, llmAdapter);
-console.log(result.output.summary);
-```
-
-## 📖 Core Concepts
-
-### Components
-
-Deity provides declarative components for building agents:
-
-- **`<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
-
-### Agent Component
-
-The `<Agent>` component is the root of every agent:
-
-```tsx
-<Agent
-  id="unique-id"
-  input={InputSchema}
-  output={OutputSchema}
-  loopConfig={{ maxToolRounds: 10, timeout: 30000 }}
-  tools={[...]}
->
-  {/* Children components */}
-</Agent>
-```
-
-**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>
-```
-
-### Result Component
-
-The `<Result>` component extracts structured output:
-
-```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>
-```
-
-### Retry Component
-
-The `<Retry>` component configures retry behavior:
-
-```tsx
-<Retry
-  maxAttempts={3}
-  feedbackOnError={true}
-  retryOnToolError={true}
-/>
-```
-
-## 🎯 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>
-);
-```
-
-### 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
-
-### Loop Validation
-
-Use `loopValidator` to validate during LLM execution loops:
-
-```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'
-      };
-    }
-
-    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>
-```
-
-### Dynamic Prompts
-
-Load prompts from files or construct dynamically:
-
-```tsx
-<System>
-  {async (ctx: any): Promise<string> => {
-    // Load from file
-    const template = await fs.readFile('./prompts/system.md', 'utf-8');
-
-    // Inject dynamic content
-    return template.replace('{{language}}', ctx.inputs.language);
-  }}
-</System>
-```
-
-## 🎨 Component Composition
-
-Agents can be composed from reusable functions:
-
-```typescript
-// Reusable prompt builders
-function buildSystemPrompt(role: string) {
-  return async (): Promise<string> => {
-    return `You are a ${role}.`;
-  };
-}
-
-function buildUserPrompt(template: string) {
-  return (ctx: any): string => {
-    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => ctx.inputs[key]);
-  };
-}
-
-// 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);
-  };
-}
-
-// 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
-
-### Tool Result Extraction
-
-```typescript
-import { extractLastToolResult, extractAllToolResults, countToolCalls } from '@limo-labs/deity';
-
-// Extract single tool result
-const result = extractLastToolResult(llmResult, 'tool_name', {
-  unwrap: true,
-  required: true
-});
-
-// Extract all results from a tool
-const allResults = extractAllToolResults(llmResult, 'memory_store');
-
-// Count tool calls
-const count = countToolCalls(llmResult, 'memory_store', (result) => {
-  return result?.success === true;
-});
-```
-
-### Memory Tools
-
-```typescript
-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>
-);
-```
-
-## 🏗️ Architecture
-
-```
-┌─────────────────────────────────────────┐
-│         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
-
-Deity includes utilities for testing agents:
-
-```typescript
-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' });
-```
-
-## 📖 Documentation
-
-- [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
-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,
-    ],
-  }),
-});
-
-// Execute
-const result = await runTSXWorkflow(workflow, { code: '...' });
-```
-
-### Workflow Components
-
-- **`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
-interface LLMAdapter {
-  generate(
-    messages: Message[],
-    tools?: Tool[],
-    config?: GenerationConfig,
-    ctx?: ExecutionContext
-  ): Promise<LLMResponse>;
-}
-```
-
-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
-
-- **Express/Fastify** - Use as API handlers
-- **Next.js** - Server actions and API routes
-- **Electron** - Desktop app agents
-- **CLI Tools** - Command-line AI agents
-
-## 🤝 Contributing
-
-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/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)
-
----
-
-**Built with ❤️ by Limo Labs**