@limo-labs/deity 0.2.0-alpha.0 → 0.2.0

package/README.md

@@ -1,18 +1,23 @@
 # @limo-labs/deity
 
-> **Declarative AI Agent Framework** — Build type-safe AI agents with JSX/TSX syntax
+> **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 using familiar JSX/TSX syntax. Write agents like React components, with full TypeScript support and zero runtime overhead.
+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/)
 
 ## ✨ Features
 
-- 🎨 **JSX/TSX Syntax** - Write agents with familiar React-like syntax
+- 🎨 **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 from reusable components
+- 🔧 **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
@@ -36,9 +41,9 @@ pnpm add @limo-labs/deity zod
 
 ## 🚀 Quick Start
 
-### 1. Configure TypeScript
+### 1. Configure TypeScript (Optional - For JSX/TSX Agent Syntax)
 
-Add JSX support to your `tsconfig.json`:
+If you want to use **JSX/TSX tags** for Agent definitions (`.tsx` files), add JSX support to your `tsconfig.json`:
 
 ```json
 {
@@ -49,7 +54,11 @@ Add JSX support to your `tsconfig.json`:
 }
 ```
 
-### 2. Create Your First Agent
+**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';
@@ -65,7 +74,7 @@ const OutputSchema = z.object({
   keyPoints: z.array(z.string())
 });
 
-// Create agent using JSX
+// Create agent using JSX tags (requires .tsx file)
 const SummarizerAgent = (
   <Agent id="summarizer" input={InputSchema} output={OutputSchema}>
     <Prompt>
@@ -291,6 +300,48 @@ const CodeAnalyzer = (
 );
 ```
 
+### 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
@@ -520,10 +571,66 @@ 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
@@ -563,10 +670,10 @@ MIT © [Limo Labs](https://github.com/limo-labs)
 
 ## 🔗 Links
 
-- [GitHub](https://github.com/limo-labs/deity)
+- [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/deity/issues)
+- [Issues](https://github.com/Limo-Labs/Limo-Deity/issues)
 - [Changelog](./CHANGELOG.md)
 
 ---