beddel 0.2.3 → 1.0.0

package/docs/architecture/core-workflows.md

@@ -0,0 +1,236 @@
+# Core Workflows
+
+## Consumer Setup Flow
+
+Setting up Beddel in a Next.js application:
+
+### 1. Install Package
+
+```bash
+npm install beddel
+# or
+pnpm add beddel
+```
+
+### 2. Create API Route
+
+```typescript
+// app/api/beddel/chat/route.ts
+import { createBeddelHandler } from 'beddel/server';
+
+export const POST = createBeddelHandler({
+  agentsPath: 'src/agents'  // Optional, default: 'src/agents'
+});
+```
+
+### 3. Create YAML Agent
+
+```yaml
+# src/agents/assistant.yaml
+metadata:
+  name: "Streaming Assistant"
+  version: "1.0.0"
+
+workflow:
+  - id: "chat-interaction"
+    type: "llm"
+    config:
+      model: "gemini-2.0-flash-exp"
+      stream: true
+      system: "You are a helpful and concise assistant."
+      messages: "$input.messages"
+```
+
+### 4. (Optional) Register Custom Extensions
+
+```typescript
+// app/api/beddel/chat/route.ts
+import { createBeddelHandler } from 'beddel/server';
+import { registerTool, registerCallback } from 'beddel';
+import { z } from 'zod';
+
+// Register custom tool
+registerTool('myTool', {
+  description: 'My custom tool',
+  parameters: z.object({ input: z.string() }),
+  execute: async ({ input }) => ({ result: input.toUpperCase() }),
+});
+
+// Register lifecycle callback
+registerCallback('saveConversation', async ({ text, usage }) => {
+  await db.saveMessage(text, usage);
+});
+
+export const POST = createBeddelHandler();
+```
+
+---
+
+## YAML Structure
+
+YAML files define a **Pipeline** of sequential steps:
+
+```yaml
+metadata:
+  name: "Agent Name"
+  version: "1.0.0"
+
+workflow:
+  - id: "step-1"
+    type: "llm"           # Primitive type
+    config:
+      model: "gemini-2.0-flash-exp"
+      stream: true        # true = streaming, false = blocking
+      system: "System prompt"
+      messages: "$input.messages"
+      tools:              # Optional: tools for function calling
+        - name: "calculator"
+      onFinish: "callbackName"   # Optional: lifecycle hook
+    result: "stepOutput"  # Optional: variable name for result
+
+  - id: "step-2"
+    type: "output-generator"
+    config:
+      template:
+        status: "completed"
+        tokens: "$stepOutput.usage"
+```
+
+### Variable Resolution Patterns
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `$input.*` | Access request input data | `$input.messages` |
+| `$stepResult.varName.*` | Access step result by result name | `$stepResult.llmOutput.text` |
+| `$varName.*` | Legacy: direct variable access | `$llmOutput.usage` |
+
+---
+
+## Streaming Chat Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (useChat)
+    participant API as POST /api/beddel/chat
+    participant Loader as YAML Loader
+    participant Executor as WorkflowExecutor
+    participant LLM as llmPrimitive
+    participant SDK as Vercel AI SDK
+
+    Client->>API: { agentId, messages: UIMessage[] }
+    API->>Loader: loadYaml(src/agents/{agentId}.yaml)
+    Loader-->>API: ParsedYaml
+    API->>Executor: new WorkflowExecutor(yaml)
+    API->>Executor: execute({ messages })
+    
+    loop For each step in workflow
+        Executor->>Executor: Get handler from registry
+        Executor->>LLM: handler(config, context)
+        
+        alt stream: true
+            LLM->>LLM: convertToModelMessages(UIMessage[])
+            LLM->>SDK: streamText({ messages: ModelMessage[] })
+            SDK-->>LLM: StreamResult
+            LLM->>LLM: result.toUIMessageStreamResponse()
+            LLM-->>Executor: Response (stream)
+            Note over Executor: Break loop immediately
+            Executor-->>API: Response
+            API-->>Client: UI Message Stream
+        else stream: false
+            LLM->>LLM: convertToModelMessages(UIMessage[])
+            LLM->>SDK: generateText({ messages: ModelMessage[] })
+            SDK-->>LLM: TextResult
+            LLM-->>Executor: { text, usage }
+            Executor->>Executor: Store in context.variables
+        end
+    end
+```
+
+### AI SDK v6 Message Format
+
+The LLM primitive handles message format conversion automatically:
+
+| Source | Format | Example |
+|--------|--------|---------|
+| Frontend (`useChat`) | `UIMessage[]` | `{ role: "user", parts: [{ type: "text", text: "Hello" }] }` |
+| Backend (`streamText`) | `ModelMessage[]` | `{ role: "user", content: "Hello" }` |
+
+- `convertToModelMessages()` converts `UIMessage[]` → `ModelMessage[]`
+- `toUIMessageStreamResponse()` returns the correct stream format for `useChat`
+
+## Tool Loop Flow
+
+When tools are defined, the LLM may invoke them in a multi-step loop:
+
+```mermaid
+sequenceDiagram
+    participant LLM as llmPrimitive
+    participant SDK as streamText
+    participant Tools as Tool Registry
+    participant Calc as calculator
+
+    LLM->>SDK: streamText({ stopWhen: stepCountIs(5), tools })
+    
+    loop Until stopWhen condition met
+        SDK->>SDK: LLM generates response
+        
+        alt Tool call requested
+            SDK->>Tools: Lookup tool by name
+            Tools->>Calc: execute({ expression })
+            Calc-->>SDK: { result }
+            SDK->>SDK: Continue with tool result
+        else No tool call
+            Note over SDK: Break loop
+        end
+    end
+    
+    SDK-->>LLM: Final StreamResult
+```
+
+## Variable Resolution Flow
+
+How variables like `$input.messages` are resolved:
+
+```mermaid
+sequenceDiagram
+    participant Config as Step Config
+    participant Resolver as Variable Resolver
+    participant Context as ExecutionContext
+
+    Config->>Resolver: "$input.messages"
+    Resolver->>Context: context.input.messages
+    Context-->>Resolver: Message[]
+    Resolver-->>Config: Resolved value
+    
+    Config->>Resolver: "$llmOutput.text"
+    Resolver->>Context: context.variables.get("llmOutput").text
+    Context-->>Resolver: "Hello!"
+    Resolver-->>Config: Resolved value
+```
+
+## onFinish Lifecycle Hook Flow
+
+How `onFinish` executes after streaming completes (Option B: direct callbacks):
+
+```mermaid
+sequenceDiagram
+    participant LLM as llmPrimitive
+    participant SDK as streamText
+    participant Registry as callbackRegistry
+    participant Callback as persistConversation
+
+    LLM->>SDK: streamText({ onFinish, onError })
+    SDK->>SDK: Stream tokens to client
+    
+    Note over SDK: Stream completes
+    
+    SDK->>LLM: onFinish({ text, usage, totalUsage, steps })
+    LLM->>LLM: config.onFinish = "persistConversation"
+    LLM->>Registry: callbackRegistry["persistConversation"]
+    Registry-->>LLM: callback function
+    LLM->>Callback: callback({ text, usage, totalUsage, steps })
+    Callback->>Callback: Save to database
+    Callback-->>LLM: Done
+    
+    Note over LLM: Response already sent to client
+```

package/docs/architecture/high-level-architecture.md

@@ -0,0 +1,76 @@
+# High Level Architecture
+
+## Technical Summary
+
+Beddel Protocol is a **Sequential Pipeline Executor** that parses YAML workflow definitions and executes steps sequentially. The architecture prioritizes streaming-first LLM responses, secure configuration parsing, and an extensible primitive system. Core patterns include the Expansion Pack Pattern for primitive registration and the early-return pattern for streaming responses.
+
+### Pipeline Pattern Definition
+
+Unlike traditional "agent wrappers", Beddel is a **declarative pipeline executor**:
+
+| Concept | Definition |
+|---------|------------|
+| **Workflow** | A linear list of steps defined in YAML |
+| **Agent** | Just one step type (`llm`) within the workflow |
+| **Streaming** | Native `streamText` support, returns `Response` immediately |
+| **Primitive** | A handler function for a step type (llm, output-generator, call-agent) |
+
+---
+
+## High Level Overview
+
+1. **Architectural Style:** Sequential Pipeline (not microservices)
+2. **Repository Structure:** Monorepo package (`packages/beddel/`)
+3. **Service Architecture:** Stateless executor with no external database dependencies
+4. **Primary Data Flow:**
+   - Client sends `{ agentId, messages }` to REST endpoint
+   - `createBeddelHandler` loads YAML via `loadYaml`
+   - `WorkflowExecutor` iterates over workflow steps
+   - First step returning a `Response` breaks the loop and returns to client
+5. **Key Decision:** REST-only API (no GraphQL) for streaming compatibility
+
+---
+
+## High Level Project Diagram
+
+```mermaid
+graph TD
+    Client["Client (useChat/fetch)"] --> API["POST /api/beddel/chat"]
+    API --> Handler["createBeddelHandler"]
+    Handler --> Loader["YAML Loader (FAILSAFE)"]
+    Loader --> Executor["WorkflowExecutor"]
+    Executor --> LLM["llm Primitive"]
+    Executor --> Output["output-generator Primitive"]
+    Executor --> CallAgent["call-agent (placeholder)"]
+    LLM --> SDK["Vercel AI SDK (streamText/generateText)"]
+    SDK --> Provider["@ai-sdk/google (Gemini)"]
+    LLM --> Tools["Tool Registry"]
+    
+    subgraph "Expansion Pack Pattern"
+        PrimitiveRegistry["handlerRegistry"]
+        ToolRegistry["toolRegistry"]
+        CallbackRegistry["callbackRegistry"]
+    end
+    
+    Executor --> PrimitiveRegistry
+    LLM --> ToolRegistry
+    LLM --> CallbackRegistry
+```
+
+---
+
+## Architectural and Design Patterns
+
+- **Sequential Pipeline Pattern:** Workflow steps execute in order; first `Response` return breaks the loop — *Rationale:* Enables streaming without blocking subsequent steps
+
+- **Expansion Pack Pattern:** Primitives, tools, and callbacks are registered in extensible maps — *Rationale:* Inspired by BMAD-METHOD™, allows community extensions without core changes
+  - `registerPrimitive(type, handler)` — Add custom step types
+  - `registerTool(name, impl)` — Add custom LLM tools
+  - `registerCallback(name, fn)` — Add lifecycle hooks
+
+- **Early Return Pattern:** When `llmPrimitive` returns `Response`, executor immediately returns to client — *Rationale:* Prevents buffering of streaming responses
+
+- **Registry Pattern:** Primitives, tools, and callbacks use lookup maps — *Rationale:* Decouples YAML definitions from implementation details
+
+- **Bundle Separation Pattern:** Three entry points (`beddel`, `beddel/server`, `beddel/client`) — *Rationale:* Prevents Node.js dependencies from leaking into client bundles
+

package/docs/architecture/index.md

@@ -0,0 +1,31 @@
+# Beddel Protocol - Architecture Document
+
+> **Version:** 1.0.0  
+> **Scope:** Streaming Pipeline Edition — Core architecture for declarative workflow execution
+
+---
+
+## Sections
+
+- [High Level Architecture](./high-level-architecture.md)
+- [Tech Stack](./tech-stack.md)
+- [Components](./components.md)
+- [Source Tree](./source-tree.md)
+- [Core Workflows](./core-workflows.md)
+- [API Reference](./api-reference.md)
+
+---
+
+## Introduction
+
+This document outlines the architecture for **Beddel Protocol**, a declarative agent execution engine built on Vercel AI SDK Core. Its primary goal is to serve as the guiding architectural blueprint for AI-driven development.
+
+**Starter Template:** N/A — This is a new package, not based on an existing template.
+
+---
+
+## Change Log
+
+| Date       | Version | Description                        | Author |
+|------------|---------|-------------------------------------|--------|
+| 2024-12-23 | 1.0.0   | Initial Architecture for Beddel Protocol | BMad Master |

package/docs/architecture/source-tree.md

@@ -0,0 +1,92 @@
+# Source Tree
+
+```
+packages/beddel/
+├── src/
+│   ├── index.ts                  # Main server exports (Node.js deps)
+│   ├── server.ts                 # Server handler barrel export
+│   ├── client.ts                 # Client exports (types only, browser-safe)
+│   ├── core/
+│   │   ├── parser.ts             # YAML parsing (FAILSAFE_SCHEMA)
+│   │   ├── workflow.ts           # WorkflowExecutor class
+│   │   └── variable-resolver.ts  # $variable.path resolution
+│   ├── primitives/
+│   │   ├── index.ts              # Handler registry (handlerRegistry)
+│   │   ├── llm.ts                # streamText/generateText wrapper
+│   │   └── output.ts             # JSON transform primitive
+│   ├── server/
+│   │   └── handler.ts            # createBeddelHandler factory
+│   ├── tools/
+│   │   └── index.ts              # Tool registry (calculator, getCurrentTime)
+│   └── types/
+│       └── index.ts              # Type definitions (PrimitiveHandler, ExecutionContext, etc.)
+├── examples/
+│   └── agents/
+│       └── assistant.yaml        # Sample streaming assistant agent
+├── docs/
+│   ├── prd/                      # Sharded PRD documents
+│   │   ├── index.md
+│   │   ├── goals-context.md
+│   │   ├── requirements.md
+│   │   ├── technical-assumptions.md
+│   │   └── epic-list.md
+│   └── architecture/             # Sharded Architecture documents
+│       ├── index.md
+│       ├── high-level-architecture.md
+│       ├── tech-stack.md
+│       ├── components.md
+│       ├── source-tree.md
+│       ├── core-workflows.md
+│       └── api-reference.md
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## Bundle Separation
+
+Beddel exports three distinct bundles to support different runtime environments:
+
+| Import Path | Entry File | Contents | Use Case |
+|-------------|------------|----------|----------|
+| `beddel` | `index.ts` | Full API: `loadYaml`, `WorkflowExecutor`, `handlerRegistry`, `toolRegistry`, `registerPrimitive`, `registerTool` | Internal Beddel usage, custom handlers |
+| `beddel/server` | `server.ts` | `createBeddelHandler`, `BeddelHandlerOptions` | Next.js API Routes (Consumer) |
+| `beddel/client` | `client.ts` | Types only: `ParsedYaml`, `ExecutionContext`, `PrimitiveHandler`, etc. | Client Components, type-checking |
+
+> [!IMPORTANT]
+> The `beddel` and `beddel/server` entry points use Node.js APIs (`fs/promises`).  
+> **Never import these in client/browser code.** Use `beddel/client` for type imports.
+
+---
+
+## package.json exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    }
+  }
+}
+```
+
+---
+
+## Notes
+
+- **Consumer application** places YAML agents in `src/agents/` (configurable via `agentsPath`)
+- **API route** lives in `app/api/beddel/chat/route.ts` using `createBeddelHandler`
+- **`call-agent` primitive** is registered as a placeholder — implementation coming soon
+- **No test folder shown** — tests should be co-located or in `__tests__/` per project preference
+

package/docs/architecture/tech-stack.md

@@ -0,0 +1,25 @@
+# Tech Stack
+
+## Technology Stack Table
+
+| Category       | Technology           | Version | Purpose                              | Rationale                                    |
+|----------------|----------------------|---------|--------------------------------------|----------------------------------------------|
+| **Language**   | TypeScript           | 5.x     | Primary development language         | Strict typing, excellent tooling             |
+| **Runtime**    | Node.js / Edge       | 20+     | JavaScript runtime                   | Next.js App Router Edge compatibility        |
+| **AI Core**    | `ai`                 | 6.x     | Vercel AI SDK Core                   | Native `streamText`/`generateText` support   |
+| **AI Provider**| `@ai-sdk/google`     | 3.x     | Google Gemini integration            | Default LLM provider (requires v3+ for AI SDK 6.x) |
+| **Validation** | `zod`                | 3.x     | Schema validation for tools          | Type-safe runtime validation                 |
+| **YAML Parser**| `js-yaml`            | 4.x     | Secure YAML parsing                  | FAILSAFE_SCHEMA prevents code execution      |
+| **Framework**  | Next.js App Router   | 14+     | API route hosting                    | Required by consumers, not bundled           |
+
+## Cloud Infrastructure
+
+- **Provider:** N/A — Beddel is a library, not a deployed service
+- **Key Services:** Consumer's responsibility
+- **Deployment Regions:** Consumer's responsibility
+
+## Notes
+
+- Beddel Protocol is a **package**, not a standalone application
+- Next.js dependency is for consumers, not bundled in the package
+- The package exposes TypeScript modules for consumption in Edge or Node.js environments

package/docs/prd/epic-list.md

@@ -0,0 +1,101 @@
+# Epic List
+
+## Epic 1: Foundation & Core
+
+Establish project structure, secure YAML parsing, and the core `WorkflowExecutor` that drives all pipeline execution.
+
+### Story 1.1: Clean Setup
+
+As a developer, I want a properly configured TypeScript package, so that I can build with strict type safety.
+
+**Acceptance Criteria:**
+1. Package includes: `ai`, `@ai-sdk/google`, `zod`, `js-yaml`
+2. `tsconfig.json` configured with strict mode
+3. No GraphQL dependencies in the package
+
+### Story 1.2: Secure Parser
+
+As a security-conscious developer, I want YAML parsing that prevents code execution, so that user-defined configurations are safe.
+
+**Acceptance Criteria:**
+1. `loadYaml` function uses `FAILSAFE_SCHEMA` from js-yaml
+2. Functions and class instances are rejected by the parser
+3. Parser returns typed `ParsedYaml` object
+
+### Story 1.3: Workflow Executor
+
+As a workflow author, I want steps to execute sequentially, so that I can compose complex pipelines.
+
+**Acceptance Criteria:**
+1. `WorkflowExecutor` iterates over `yaml.workflow` steps
+2. If a handler returns a `Response` instance, execution stops and returns immediately
+3. Step results are stored in `context.variables` for use by subsequent steps
+
+---
+
+## Epic 2: Primitive Handlers
+
+Implement the three core primitives that power the pipeline: `llm`, `output-generator`, and `call-agent`.
+
+### Story 2.1: Handler & Tool Registries
+
+As a package author, I want extensible registries for primitives and tools, so that the system supports the Expansion Pack Pattern.
+
+**Acceptance Criteria:**
+1. `primitiveRegistry: Record<string, PrimitiveHandler>` exists in `src/primitives/index.ts`
+2. `toolRegistry: Record<string, ToolImplementation>` exists in `src/tools/index.ts`
+3. MVP includes `calculator` and `getCurrentTime` sample tools
+
+### Story 2.2: LLM Primitive
+
+As a workflow author, I want to call LLMs from YAML steps, so that I can define AI behavior declaratively.
+
+**Acceptance Criteria:**
+1. `stream: true` uses `streamText` and returns `result.toUIMessageStreamResponse()`
+2. `stream: false` uses `generateText` and returns JSON object
+3. `config.tools` maps to Vercel AI SDK `tools` via `mapTools()` function
+4. `stopWhen: stepCountIs(5)` is set when tools are present (enabling tool loops)
+5. Uses `convertToModelMessages()` for `UIMessage[]` → `ModelMessage[]` conversion (AI SDK v6)
+
+### Story 2.3: Output Primitive
+
+As a workflow author, I want to transform variables into structured output, so that I can format responses without LLM calls.
+
+**Acceptance Criteria:**
+1. Variable resolution supports `$input.*` and `$stepResult.*` syntax
+2. Template is a pure JSON transform (no LLM invocation)
+3. Returns the transformed object for next step consumption
+
+### Story 2.4: Lifecycle Hooks
+
+As a workflow author, I want callbacks to execute after streaming completes, so that I can persist conversations and log usage.
+
+**Acceptance Criteria:**
+1. `onFinish` callback executes after stream completes with `{ text, usage, totalUsage, steps }` payload
+2. `onError` callback executes when stream errors with `{ error }` payload
+3. Callbacks are registered via `callbackRegistry: Record<string, CallbackFn>`
+4. YAML references callback by name string (e.g., `onFinish: "persistConversation"`)
+
+---
+
+## Epic 3: API & Integration
+
+Expose the workflow engine via a REST endpoint and provide a sample agent for testing.
+
+### Story 3.1: API Route
+
+As a frontend developer, I want a REST endpoint for chat, so that I can use `useChat` or standard fetch calls.
+
+**Acceptance Criteria:**
+1. `POST /api/beddel/chat` accepts `{ agentId, messages }`
+2. Loads YAML from `src/agents/{agentId}.yaml`
+3. Returns streaming `Response` or JSON based on workflow output
+
+### Story 3.2: Sample Assistant
+
+As a developer onboarding to Beddel, I want a working example agent, so that I can understand the YAML structure.
+
+**Acceptance Criteria:**
+1. `src/agents/assistant.yaml` is provided with streaming enabled
+2. Includes at least one tool definition (`calculator`)
+3. curl command successfully receives streamed response

package/docs/prd/goals-context.md

@@ -0,0 +1,23 @@
+# Goals and Background Context
+
+## Goals
+
+- Provide a **declarative agent execution engine** built on Vercel AI SDK Core
+- Enable **native streaming** for real-time chat responses at the Edge
+- Allow developers to define agent workflows via **YAML configurations** instead of hardcoded logic
+- Establish an **extensible primitive system** following the Expansion Pack Pattern
+- Deliver a **lean, secure parser** that prevents arbitrary code execution
+
+## Background Context
+
+Beddel Protocol represents a fundamental shift in architecture: from an "agent wrapper" approach to a **Sequential Pipeline Executor**. This redesign addresses the need for streaming-first chat interactions while maintaining the declarative configuration philosophy that makes Beddel accessible to developers.
+
+The core problem being solved is the latency in LLM-powered applications where responses are delivered only after full processing. By leveraging Vercel AI SDK's `streamText` capability, Beddel Protocol enables instant, token-by-token response delivery.
+
+### Key Concepts
+
+| Concept      | Definition                                    |
+|--------------|-----------------------------------------------|
+| **Workflow** | A linear list of steps executed sequentially  |
+| **Agent**    | Just one step type (`llm`) within the workflow |
+| **Streaming**| Native `streamText` support at the Edge       |

package/docs/prd/index.md

@@ -0,0 +1,21 @@
+# Beddel Protocol - Product Requirements Document (PRD)
+
+> **Version:** 1.0.0  
+> **Scope:** Streaming Pipeline Edition — First release of the package
+
+---
+
+## Sections
+
+- [Goals and Background Context](./goals-context.md)
+- [Requirements](./requirements.md)
+- [Technical Assumptions](./technical-assumptions.md)
+- [Epic List](./epic-list.md)
+
+---
+
+## Change Log
+
+| Date       | Version | Description              | Author |
+|------------|---------|--------------------------|--------|
+| 2024-12-23 | 1.0.0   | Initial PRD for Beddel Protocol | BMad Master |

package/docs/prd/requirements.md

@@ -0,0 +1,25 @@
+# Requirements
+
+## Functional Requirements
+
+- **FR1:** The system MUST parse YAML workflow definitions using a secure schema (FAILSAFE_SCHEMA)
+- **FR2:** The system MUST execute workflow steps sequentially via `WorkflowExecutor`
+- **FR3:** The `llm` primitive MUST support dual-mode operation:
+  - `stream: true` → returns `Response` from `streamText`
+  - `stream: false` → returns JSON object from `generateText`
+- **FR4:** The executor MUST immediately return a `Response` when a primitive returns a stream
+- **FR5:** The system MUST resolve variables using `$input.*` and `$stepResult.*` syntax
+- **FR6:** The `output-generator` primitive MUST perform deterministic JSON transformation without LLM calls
+- **FR7:** The `call-agent` primitive MUST allow recursive invocation of other YAML workflow files
+- **FR8:** The system MUST expose a REST endpoint (`POST /api/beddel/chat`) for chat interactions
+- **FR9:** The system MUST support tool definitions in YAML with automatic mapping to Vercel AI SDK `tools` object
+- **FR10:** The tool registry MUST contain sample implementations: `calculator`, `getCurrentTime`
+- **FR11:** The `llmPrimitive` MUST support `onFinish` and `onError` callbacks for post-stream logic
+
+## Non-Functional Requirements
+
+- **NFR1:** YAML parser MUST use `FAILSAFE_SCHEMA` to prevent function instantiation
+- **NFR2:** Tool parameters MUST be validated using Zod schemas
+- **NFR3:** The package MUST be compatible with Edge runtime (Next.js App Router)
+- **NFR4:** Streaming responses MUST follow Vercel AI SDK Data Stream protocol
+- **NFR5:** Configuration MUST be strict TypeScript (`tsconfig.json` strict mode)

package/docs/prd/technical-assumptions.md

@@ -0,0 +1,35 @@
+# Technical Assumptions
+
+## Repository Structure
+
+- **Structure:** Monorepo package (`packages/beddel/`)
+- **Package Manager:** npm or pnpm (workspace-compatible)
+
+## Service Architecture
+
+- **Pattern:** Sequential Pipeline Executor (not microservices)
+- **Runtime:** Node.js / Edge (Next.js App Router)
+- **No GraphQL for chat:** REST-only for streaming compatibility
+
+## Technology Stack
+
+| Category     | Technology          | Purpose                              |
+|--------------|---------------------|--------------------------------------|
+| AI Core      | `ai` (6.x)          | Vercel AI SDK Core for LLM calls     |
+| AI Provider  | `@ai-sdk/google`    | Google Gemini integration            |
+| Validation   | `zod`               | Schema validation for tools          |
+| YAML Parser  | `js-yaml`           | Secure YAML parsing (FAILSAFE)       |
+| Runtime      | Next.js App Router  | Edge-compatible API routes           |
+
+## Testing Requirements
+
+- **Unit Tests:** Required for core modules (parser, workflow, primitives)
+- **Integration Tests:** Required for API route with mock LLM responses
+- **Manual Verification:** curl command to test streaming responses
+
+## Additional Technical Assumptions
+
+- Environment variable `GEMINI_API_KEY` is required for LLM calls
+- TypeScript strict mode is mandatory
+- No database dependencies (stateless execution)
+- Tool implementations are synchronous or return Promises