web-ai-service 1.0.1 → 1.0.2

package/README.md

@@ -284,96 +284,268 @@ stages:
 
 ## Node Types
 
+All nodes share these common properties:
+- **type** (required) - The node type: `llm`, `code`, `reduce`, `split`, or `passthrough`
+- **input** (required for most) - The input source: `$input`, `$input.field`, `stageName.nodeName`
+
 ### LLM Node
 
-Call an LLM provider:
+Calls an LLM provider with a prompt.
 
+**Required Properties:**
 ```yaml
 my_llm_node:
   type: llm
-  input: $input.text              # or reference: stageName.nodeName
-  provider: gemini                # gemini | openai | anthropic | grok
-  model: gemini-2.0-flash-lite
-  temperature: 0.7                # Optional (0.0-1.0)
-  maxTokens: 1024                 # Optional
-  systemMessages:
-    - file: prompt.txt
-      cache: true                 # Cache for performance
+  input: $input              # Input source
+  provider: gemini           # Provider name: gemini | openai | anthropic | grok
+  model: gemini-2.0-flash-lite  # Model identifier
+```
+
+**Optional Properties:**
+```yaml
+  temperature: 0.7           # Default: 1.0. Controls randomness (0.0-1.0)
+  maxTokens: 1024            # Default: provider default. Max output tokens
+  systemMessages:            # System prompts (optional)
+    - file: prompt.txt       # Load from file
+      cache: true            # Enable caching (default: false)
+    - text: "Direct prompt"  # Or use inline text
+  config:                    # Provider-specific config (optional)
+    topP: 0.9
+    topK: 40
 ```
 
 **Supported Providers & Models:**
 
-| Provider | Example Models |
-|----------|----------------|
-| `gemini` | `gemini-2.0-flash-lite`, `gemini-2.0-flash`, `gemini-1.5-pro` |
-| `openai` | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` |
-| `anthropic` | `claude-3-5-sonnet-latest`, `claude-3-haiku-20240307` |
-| `grok` | `grok-2`, `grok-2-mini` |
+| Provider | Example Models | Notes |
+|----------|----------------|-------|
+| `gemini` | `gemini-2.0-flash-lite`, `gemini-2.0-flash`, `gemini-1.5-pro` | Fast, cost-effective |
+| `openai` | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` | High quality |
+| `anthropic` | `claude-3-5-sonnet-latest`, `claude-3-haiku-20240307` | Long context |
+| `grok` | `grok-2`, `grok-2-mini` | xAI models |
+
+**Using LLM References (Alternative):**
+
+Define reusable LLM configurations:
+
+```yaml
+llm:
+  my-summarizer:
+    provider: gemini
+    model: gemini-2.0-flash-lite
+    temperature: 0.3
+
+nodes:
+  summarize:
+    type: llm
+    input: $input
+    llmRef: my-summarizer       # Reference the config
+    systemMessages:
+      - file: prompt.txt
+```
+
+---
 
 ### Code Node
 
-Execute custom TypeScript:
+Executes a custom TypeScript function.
 
+**Required Properties:**
 ```yaml
 my_code_node:
   type: code
   input: $input
-  file: my-processor.ts
+  file: my-processor.ts      # Relative to endpoint's codes/ folder
 ```
 
-The TypeScript file must export a default async function:
+**TypeScript Function Signature:**
+
+Your code file must export a default async function:
 
 ```typescript
 import type { NodeOutput } from '@workflow/types';
 
 export default async function(input: unknown): Promise<NodeOutput> {
     // Your logic here
+    const processed = /* ... */;
+    
     return { 
         type: 'json',    // 'string' | 'json' | 'number' | 'boolean' | 'array'
-        value: { processed: true } 
+        value: processed 
     };
 }
 ```
 
+**Notes:**
+- The `input` parameter is the **unwrapped value** from the previous node
+- Must return a `NodeOutput` object with `type` and `value`
+- Can import from `@code-plugins/*` for shared code
+- Can use any npm packages (run `npm run scan-deps` to auto-install)
+
+---
+
 ### Reduce Node
 
-Combine multiple node outputs:
+Combines multiple node outputs into a single JSON object.
 
+**Required Properties:**
 ```yaml
 merge_results:
   type: reduce
-  inputs:
+  inputs:                    # Array of node references
     - stageName.node1
     - stageName.node2
-  mapping:
+  mapping:                   # JSONPath mappings
     firstResult: $.0
     secondResult: $.1
+    nested:
+      data: $.0.someField
+```
+
+**How it Works:**
+- Takes outputs from multiple nodes specified in `inputs`
+- Uses JSONPath expressions in `mapping` to extract values
+- `$.0` refers to first input, `$.1` to second input, etc.
+- Returns a single `{ type: 'json', value: {...} }` object
+
+**Example:**
+
+If `node1` outputs `{ value: { count: 10 } }` and `node2` outputs `{ value: { total: 100 } }`:
+
+```yaml
+mapping:
+  count: $.0.count       # Gets 10 from first input
+  total: $.1.total       # Gets 100 from second input
+# Result: { count: 10, total: 100 }
 ```
 
+---
+
 ### Split Node
 
-Divide output into named parts:
+Divides a single output into multiple named outputs.
 
+**Required Properties:**
 ```yaml
 split_data:
   type: split
   input: stageName.nodeName
-  mapping:
-    header: $.header
+  mapping:                   # JSONPath expressions for each output
+    header: $.metadata.header
     body: $.content
-    footer: $.footer
+    footer: $.metadata.footer
+```
+
+**How it Works:**
+- Takes a single input (usually JSON)
+- Extracts multiple values using JSONPath
+- Creates named outputs accessible as `nodeId.outputName`
+
+**Example:**
+
+Input: `{ metadata: { header: 'Title' }, content: 'Body text' }`
+
+```yaml
+split_data:
+  type: split
+  input: previous.node
+  mapping:
+    title: $.metadata.header    # Accessible as split_data.title
+    text: $.content             # Accessible as split_data.text
+```
+
+Later nodes can reference:
+```yaml
+another_node:
+  type: code
+  input: split_data.title     # Gets 'Title'
 ```
 
+---
+
 ### Passthrough Node
 
-Pass input directly to output:
+Passes input directly to output unchanged (useful for routing).
 
+**Required Properties:**
 ```yaml
 forward:
   type: passthrough
   input: $input
 ```
 
+**Notes:**
+- No transformation applied
+- Preserves the input type
+- Useful for conditional routing or stage organization
+
+---
+
+## Input References
+
+All nodes (except `reduce`) use the `input` property to specify data source:
+
+| Reference Pattern | Description | Example |
+|-------------------|-------------|---------|
+| `$input` | Full request body | `input: $input` |
+| `$input.field` | Specific field from request | `input: $input.text` |
+| `$input.nested.field` | Nested field access | `input: $input.user.name` |
+| `stageName.nodeName` | Output from another node | `input: extract.parser` |
+| `nodeName.outputName` | Split node output | `input: splitter.header` |
+
+---
+
+## Workflow Structure
+
+Every workflow must follow these rules:
+
+**Single-Stage Workflows:**
+```yaml
+version: "1.0"
+stages:
+  - name: main              # Must be named 'main'
+    nodes:
+      my_node:              # Must have exactly 1 node
+        type: llm
+        input: $input       # Must use $input
+        # ... node config ...
+```
+
+**Multi-Stage Workflows:**
+```yaml
+version: "1.0"
+stages:
+  - name: preprocess        # First stage: any name
+    nodes:
+      validator:            # First node must use $input
+        type: code
+        input: $input
+        # ... config ...
+  
+  - name: process           # Middle stage(s): any name, multiple nodes OK
+    nodes:
+      analyze:
+        type: llm
+        input: preprocess.validator
+        # ... config ...
+      extract:
+        type: code
+        input: preprocess.validator
+        # ... config ...
+  
+  - name: postprocess       # Last stage: any name
+    nodes:
+      formatter:            # Must have exactly 1 node (exit node)
+        type: code
+        input: process.analyze
+        # ... config ...
+```
+
+**Rules:**
+- **First stage's first node** must use `$input` or `$input.field` as input
+- **Last stage** must have exactly 1 node (its output becomes the API response)
+- Middle stages can have any number of nodes
+- Stage names can be anything (no longer required to be "entry" and "exit")
+
 ---
 
 ## Using Plugins

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-ai-service",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "TypeScript-based Web AI Service that creates configurable AI-powered endpoints from YAML definitions",
   "main": "dist/engine/index.js",
   "bin": {
@@ -53,4 +53,4 @@
     "tsx": "^4.7.0",
     "typescript": "^5.3.3"
   }
-}
+}