beddel 0.2.3 → 1.0.0

package/docs/architecture/api-reference.md

@@ -0,0 +1,307 @@
+# API Reference
+
+> **Beddel Protocol v1.0.0** — Complete API documentation for all public exports.
+
+---
+
+## Entry Points
+
+| Import Path | Purpose |
+|-------------|---------|
+| `beddel` | Full server API — core functions, registries, and extensibility |
+| `beddel/server` | Server handler factory for Next.js API routes |
+| `beddel/client` | Type-only exports for client-side usage |
+
+---
+
+## `beddel` (Main Entry)
+
+### Core Functions
+
+#### `loadYaml(path: string): Promise<ParsedYaml>`
+
+Load and parse a YAML workflow file securely using `FAILSAFE_SCHEMA`.
+
+```typescript
+import { loadYaml } from 'beddel';
+
+const yaml = await loadYaml('./src/agents/assistant.yaml');
+console.log(yaml.metadata.name); // "Streaming Assistant"
+```
+
+#### `resolveVariables(template: unknown, context: ExecutionContext): unknown`
+
+Resolve variable references (`$input.*`, `$stepResult.*`) in templates.
+
+```typescript
+import { resolveVariables } from 'beddel';
+
+const resolved = resolveVariables('$input.messages', context);
+```
+
+---
+
+### Classes
+
+#### `WorkflowExecutor`
+
+Sequential pipeline executor for YAML workflows.
+
+```typescript
+import { WorkflowExecutor, loadYaml } from 'beddel';
+
+const yaml = await loadYaml('./src/agents/assistant.yaml');
+const executor = new WorkflowExecutor(yaml);
+
+// Execute with input data
+const result = await executor.execute({ messages: [...] });
+
+if (result instanceof Response) {
+  return result; // Streaming response
+}
+return Response.json(result); // Blocking result
+```
+
+**Constructor:** `new WorkflowExecutor(yaml: ParsedYaml)`
+
+**Methods:**
+- `execute(input: unknown): Promise<Response | Record<string, unknown>>`
+
+---
+
+### Registries
+
+#### `handlerRegistry: Record<string, PrimitiveHandler>`
+
+Map of primitive step types to their handler functions.
+
+**Built-in handlers:**
+- `llm` — AI text generation (streaming/blocking)
+- `output-generator` — Deterministic JSON transform
+- `call-agent` — Sub-agent invocation (placeholder)
+
+#### `toolRegistry: Record<string, ToolImplementation>`
+
+Map of tool names to their implementations for LLM function calling.
+
+**Built-in tools:**
+- `calculator` — Evaluate mathematical expressions
+- `getCurrentTime` — Get current ISO timestamp
+
+---
+
+### Extensibility Functions
+
+#### `registerPrimitive(type: string, handler: PrimitiveHandler): void`
+
+Register a custom primitive handler.
+
+```typescript
+import { registerPrimitive } from 'beddel';
+
+registerPrimitive('http-fetch', async (config, context) => {
+  const response = await fetch(config.url);
+  return { data: await response.json() };
+});
+```
+
+#### `registerTool(name: string, implementation: ToolImplementation): void`
+
+Register a custom tool for LLM function calling.
+
+```typescript
+import { registerTool } from 'beddel';
+import { z } from 'zod';
+
+registerTool('weatherLookup', {
+  description: 'Get weather for a city',
+  parameters: z.object({ city: z.string() }),
+  execute: async ({ city }) => fetchWeather(city),
+});
+```
+
+#### `registerCallback(name: string, callback: CallbackFn): void`
+
+Register a lifecycle callback for streaming hooks.
+
+```typescript
+import { registerCallback } from 'beddel';
+
+registerCallback('persistConversation', async ({ text, usage }) => {
+  await db.saveMessage(text, usage);
+});
+```
+
+---
+
+## `beddel/server`
+
+### `createBeddelHandler(options?: BeddelHandlerOptions)`
+
+Factory function for creating Next.js API route handlers.
+
+```typescript
+// app/api/beddel/chat/route.ts
+import { createBeddelHandler } from 'beddel/server';
+
+export const POST = createBeddelHandler({
+  agentsPath: 'src/agents'  // Optional, default: 'src/agents'
+});
+```
+
+**Options:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `agentsPath` | `string` | `'src/agents'` | Directory containing YAML agent files |
+
+**Request Body:**
+
+The request body accepts messages in AI SDK v6 `UIMessage[]` format (from `useChat`):
+
+```json
+{
+  "agentId": "assistant",
+  "messages": [
+    {
+      "role": "user",
+      "parts": [{ "type": "text", "text": "Hello!" }]
+    }
+  ]
+}
+```
+
+> **AI SDK v6 Compatibility:** The handler automatically converts `UIMessage[]` (frontend format with `parts`) to `ModelMessage[]` (backend format with `content`) using `convertToModelMessages()`. The streaming response uses `toUIMessageStreamResponse()` for proper `useChat` integration.
+
+---
+
+## `beddel/client`
+
+Type-only exports safe for client-side bundles (no Node.js dependencies).
+
+### Types
+
+```typescript
+import type {
+  ParsedYaml,
+  WorkflowStep,
+  StepConfig,
+  YamlMetadata,
+  ExecutionContext,
+  PrimitiveHandler,
+} from 'beddel/client';
+```
+
+---
+
+## Type Definitions
+
+### `ParsedYaml`
+
+```typescript
+interface ParsedYaml {
+  metadata: YamlMetadata;
+  workflow: WorkflowStep[];
+}
+```
+
+### `YamlMetadata`
+
+```typescript
+interface YamlMetadata {
+  name: string;
+  version: string;
+}
+```
+
+### `WorkflowStep`
+
+```typescript
+interface WorkflowStep {
+  id: string;
+  type: string;  // 'llm' | 'output-generator' | 'call-agent' | custom
+  config: StepConfig;
+  result?: string;  // Variable name to store step result
+}
+```
+
+### `StepConfig`
+
+```typescript
+interface StepConfig {
+  [key: string]: unknown;  // Step-specific configuration
+}
+```
+
+### `ExecutionContext`
+
+```typescript
+interface ExecutionContext {
+  input: unknown;
+  variables: Map<string, unknown>;
+}
+```
+
+### `PrimitiveHandler`
+
+```typescript
+type PrimitiveHandler = (
+  config: StepConfig,
+  context: ExecutionContext
+) => Promise<Response | Record<string, unknown>>;
+```
+
+### `ToolImplementation`
+
+```typescript
+interface ToolImplementation {
+  description: string;
+  parameters: z.ZodSchema;
+  execute: (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+}
+```
+
+### `CallbackFn`
+
+```typescript
+type CallbackFn = (payload: Record<string, unknown>) => void | Promise<void>;
+```
+
+---
+
+## AI SDK v6 Compatibility
+
+Beddel is fully compatible with Vercel AI SDK v6 message formats:
+
+### Message Format Conversion
+
+| Source | Format | Structure |
+|--------|--------|-----------|
+| Frontend (`useChat`) | `UIMessage[]` | `{ role, parts: [{ type: "text", text }] }` |
+| Backend (`streamText`) | `ModelMessage[]` | `{ role, content }` |
+
+The LLM primitive automatically handles this conversion:
+
+```typescript
+// Internal conversion flow
+const rawMessages = resolveVariables(config.messages, context) as UIMessage[];
+const messages = await convertToModelMessages(rawMessages);
+```
+
+### Streaming Response
+
+For streaming mode, `toUIMessageStreamResponse()` returns the correct format for `useChat`:
+
+```typescript
+// Streaming mode returns UI-compatible stream
+return result.toUIMessageStreamResponse();
+```
+
+---
+
+## Change Log
+
+| Date | Version | Description |
+|------|---------|-------------|
+| 2024-12-24 | 1.0.0 | Initial API reference |
+| 2024-12-24 | 1.0.1 | AI SDK v6 compatibility: UIMessage/ModelMessage conversion |

package/docs/architecture/components.md

@@ -0,0 +1,246 @@
+# Components
+
+## Core Components
+
+### Parser (`src/core/parser.ts`)
+
+**Responsibility:** Load and parse YAML workflow definitions securely.
+
+**Key Interfaces:**
+- `loadYaml(path: string): Promise<ParsedYaml>`
+
+**Dependencies:** `js-yaml`
+
+**Technology Stack:** Uses `FAILSAFE_SCHEMA` to prevent function instantiation.
+
+---
+
+### WorkflowExecutor (`src/core/workflow.ts`)
+
+**Responsibility:** Execute workflow steps sequentially, managing context and variable storage.
+
+**Key Interfaces:**
+- `constructor(yaml: ParsedYaml)`
+- `execute(input: any): Promise<Response | Record<string, unknown>>`
+
+**Dependencies:** `handlerRegistry` (primitives)
+
+**Technology Stack:** Pure TypeScript, no external dependencies.
+
+---
+
+### Variable Resolver (`src/core/variable-resolver.ts`)
+
+**Responsibility:** Resolve `$input.*` and `$stepResult.*` variable references.
+
+**Key Interfaces:**
+- `resolveVariables(template: any, context: ExecutionContext): any`
+
+**Dependencies:** None
+
+**Technology Stack:** Pure TypeScript.
+
+---
+
+### Primitive Handler Registry (`src/primitives/index.ts`)
+
+**Responsibility:** Register and lookup primitive handlers by step type.
+
+**Key Interfaces:**
+- `handlerRegistry: Record<string, PrimitiveHandler>`
+- `registerPrimitive(type: string, handler: PrimitiveHandler): void`
+
+**Dependencies:** `llm`, `output-generator`, `call-agent` primitives
+
+**Technology Stack:** Registry pattern implementation.
+
+---
+
+### LLM Primitive (`src/primitives/llm.ts`)
+
+**Responsibility:** Execute LLM calls with dual-mode support (streaming/blocking) and lifecycle hooks.
+
+**Key Interfaces:**
+- `llmPrimitive(config: StepConfig, context: ExecutionContext): Promise<Response | object>`
+- `mapTools(toolDefinitions): ToolSet` - Maps YAML tool definitions to SDK tools
+- `registerCallback(name: string, fn: CallbackFn): void` - Register lifecycle callbacks
+- `callbackRegistry: Record<string, CallbackFn>` - Stores registered callbacks
+
+**Dependencies:** `ai`, `@ai-sdk/google`, `toolRegistry`, `callbackRegistry`
+
+**Technology Stack (AI SDK v6):**
+- `streamText()` for streaming mode → `result.toUIMessageStreamResponse()`
+- `generateText()` for blocking mode → `{ text, usage }`
+- `convertToModelMessages()` for UIMessage[] → ModelMessage[] conversion
+- `dynamicTool()` for registry-based tool creation
+- `stopWhen: stepCountIs(5)` for multi-step tool loops
+- `onFinish` / `onError` lifecycle callbacks
+
+**AI SDK v6 Message Format Compatibility:**
+- Frontend (`useChat`) sends `UIMessage[]` with `{ parts: [...] }` format
+- Backend (`streamText`/`generateText`) expects `ModelMessage[]` with `{ content: ... }`
+- `convertToModelMessages()` bridges this gap automatically
+- `toUIMessageStreamResponse()` returns the correct stream format for `useChat`
+
+---
+
+### Output Primitive (`src/primitives/output.ts`)
+
+**Responsibility:** Deterministic JSON transform using variable resolution.
+
+**Key Interfaces:**
+- `outputPrimitive(config: StepConfig, context: ExecutionContext): Promise<Record<string, unknown>>`
+
+**Dependencies:** `resolveVariables`
+
+**Technology Stack:** Pure TypeScript.
+
+---
+
+### Call Agent Primitive (Placeholder)
+
+**Responsibility:** Invoke another YAML workflow as a subroutine.
+
+**Status:** 🚧 Coming Soon — currently registered as placeholder handler.
+
+---
+
+### Tool Registry (`src/tools/index.ts`)
+
+**Responsibility:** Register and provide tool implementations for LLM primitives.
+
+**Key Interfaces:**
+- `toolRegistry: Record<string, ToolImplementation>`
+- `registerTool(name: string, implementation: ToolImplementation): void`
+- `ToolImplementation: { description, parameters (Zod), execute }`
+
+**Built-in Tools:**
+- `calculator` - Evaluate mathematical expressions
+- `getCurrentTime` - Get current ISO timestamp
+
+**Dependencies:** `zod`
+
+**Technology Stack:** Zod schemas for parameter validation.
+
+---
+
+### Server Handler (`src/server/handler.ts`)
+
+**Responsibility:** Factory for creating Next.js API route handlers.
+
+**Key Interfaces:**
+- `createBeddelHandler(options?: BeddelHandlerOptions): (request: NextRequest) => Promise<Response>`
+- `BeddelHandlerOptions: { agentsPath?: string }`
+
+**Dependencies:** `loadYaml`, `WorkflowExecutor`, `next/server`
+
+**Technology Stack:** Next.js App Router API Routes.
+
+**Usage:**
+```typescript
+// app/api/beddel/chat/route.ts
+import { createBeddelHandler } from 'beddel/server';
+
+export const POST = createBeddelHandler({
+  agentsPath: 'src/agents'  // Default: 'src/agents'
+});
+```
+
+---
+
+## Extensibility APIs
+
+Beddel follows the **Expansion Pack Pattern** for extensibility:
+
+### `registerPrimitive(type, handler)`
+
+Add custom step types to the workflow engine.
+
+```typescript
+import { registerPrimitive } from 'beddel';
+
+registerPrimitive('http-fetch', async (config, context) => {
+  const response = await fetch(config.url);
+  return { data: await response.json() };
+});
+```
+
+### `registerTool(name, implementation)`
+
+Add custom tools for LLM function calling.
+
+```typescript
+import { registerTool } from 'beddel';
+import { z } from 'zod';
+
+registerTool('weatherLookup', {
+  description: 'Get weather for a city',
+  parameters: z.object({ city: z.string() }),
+  execute: async ({ city }) => fetchWeather(city),
+});
+```
+
+### `registerCallback(name, fn)`
+
+Add lifecycle hooks for streaming completion.
+
+```typescript
+import { registerCallback } from 'beddel';
+
+registerCallback('persistConversation', async ({ text, usage }) => {
+  await db.saveMessage(text, usage);
+});
+```
+
+---
+
+## Component Diagram
+
+```mermaid
+graph TB
+    subgraph "Entry Points"
+        Index["index.ts"]
+        Server["server.ts"]
+        Client["client.ts (types)"]
+    end
+    
+    subgraph "Core"
+        Parser["parser.ts"]
+        Executor["workflow.ts"]
+        VarResolver["variable-resolver.ts"]
+    end
+    
+    subgraph "Primitives"
+        Registry["index.ts (handlerRegistry)"]
+        LLMPrim["llm.ts"]
+        OutputPrim["output.ts"]
+        CallAgent["call-agent (placeholder)"]
+    end
+    
+    subgraph "Tools"
+        ToolReg["index.ts (toolRegistry)"]
+        Calc["calculator"]
+        Time["getCurrentTime"]
+    end
+    
+    subgraph "Server"
+        Handler["handler.ts"]
+    end
+    
+    Index --> Parser
+    Index --> Executor
+    Index --> Registry
+    Index --> ToolReg
+    Server --> Handler
+    Handler --> Parser
+    Handler --> Executor
+    Executor --> Registry
+    Executor --> VarResolver
+    Registry --> LLMPrim
+    Registry --> OutputPrim
+    Registry --> CallAgent
+    LLMPrim --> ToolReg
+    ToolReg --> Calc
+    ToolReg --> Time
+```
+