Web AI Service

A TypeScript-based workflow engine that creates dynamic API endpoints from YAML workflow definitions. Build powerful AI-powered APIs with LLM calls, custom code execution, and data transformations—all without writing server boilerplate.

Features

- 🚀 YAML-Based Configuration - Define API endpoints declaratively
- 🤖 Multi-LLM Support - Built-in support for Gemini, OpenAI, Anthropic, and Grok
- 📝 Custom Code Nodes - Execute TypeScript functions in your workflows
- ⚡ Parallel Execution - Run multiple nodes concurrently with error strategies
- 🔄 Data Transformation - Reduce, split, and map data with JSONPath
- ✅ Input Validation - JSON Schema validation on request inputs
- 🎯 Type-Safe - Full TypeScript support with strict typing
- 🌐 Auto-Routing - Endpoint folders automatically become API routes
- 🔌 Plugin System - Extensible with Supabase and custom plugins

---

Table of Contents

1. Quick Start
2. Project Structure
3. Creating Endpoints
4. Node Types
5. Using Plugins
6. Configuration
7. Commands Reference
8. Troubleshooting
9. Documentation

---

Quick Start

$3

The easiest way to start is with the scaffolder:

``bash
npx create-web-ai-service
`

You'll be prompted to:
1. Enter your project name - e.g., my-api
2. Select plugins - Choose from available plugins like Supabase

Or use command-line arguments for non-interactive setup:

`bash
npx create-web-ai-service my-api --plugins supabase
`

After scaffolding:

`bash
cd my-api
cp .env.example .env # Configure your API keys
npm run dev # Start the server
`

Your API is now running at http://localhost:3000!

$3

Add to an existing project:

`bash
npm install web-ai-service
`

$3

`bash
npm install -g web-ai-service
web-ai-service # Run from any directory with a src/endpoints folder
`

---

Project Structure

When you create a new project, you'll get this structure:

`
my-api/
├── src/
│ ├── endpoints/ # Your API endpoints
│ │ └── hello/ # Example: GET /hello
│ │ ├── GET.yaml # Workflow definition
│ │ ├── codes/ # TypeScript code nodes
│ │ │ └── format-greeting.ts
│ │ └── prompts/ # LLM system prompts
│ │ └── greeting-system.txt
│ │
│ └── plugins/ # Shared code modules
│ └── supabase.ts # (if selected during setup)
│
├── .env # Your API keys (gitignored)
├── .env.example # Template for environment variables
├── package.json
└── tsconfig.json
`

$3

| Concept | Description |
|---------|-------------|
| Endpoint | A folder in src/endpoints/ that becomes an API route |
| Workflow | A YAML file (e.g., POST.yaml, GET.yaml) defining the processing pipeline |
| Stage | A sequential step in the workflow containing one or more nodes |
| Node | An individual processing unit (LLM call, code execution, etc.) |

$3

| Folder Path | HTTP Method | API Route |
|-------------|-------------|-----------|
| src/endpoints/hello/GET.yaml | GET | /hello |
| src/endpoints/summarize/POST.yaml | POST | /summarize |
| src/endpoints/users/profile/GET.yaml | GET | /users/profile |

---

Creating Endpoints

$3

Create a POST endpoint at /summarize:

1. Create the folder structure:
`bash
mkdir -p src/endpoints/summarize/{codes,prompts}
`

2. Create the system prompt (src/endpoints/summarize/prompts/system.txt):
`text
You are a concise summarization assistant. Summarize the provided text clearly in 2-3 paragraphs.
`

3. Create the workflow (src/endpoints/summarize/POST.yaml):
`yaml
version: "1.0"

stages:
- name: main
nodes:
summarize:
type: llm
input: $input.text
provider: gemini
model: gemini-2.0-flash-lite
temperature: 0.3
maxTokens: 1024
systemMessages:
- file: system.txt
`

4. Test it:
`bash
curl -X POST http://localhost:3000/summarize \
-H "Content-Type: application/json" \
-d '{"text": "Long text to summarize..."}'
`

$3

Create a code node to validate inputs before processing:

src/endpoints/summarize/codes/validate.ts:
`typescript
import type { NodeOutput } from '@workflow/types';

interface SummarizeInput {
text?: string;
}

export default async function(input: unknown): Promise {
const body = input as SummarizeInput;

if (!body.text || typeof body.text !== 'string') {
throw new Error('Missing required field: text');
}

if (body.text.length < 10) {
throw new Error('Text must be at least 10 characters');
}

return { type: 'string', value: body.text };
}
`

Updated workflow with validation stage:
`yaml
version: "1.0"

stages:
- name: validate
nodes:
check_input:
type: code
input: $input
file: validate.ts

- name: summarize
nodes:
summary:
type: llm
input: validate.check_input # Reference previous node output
provider: gemini
model: gemini-2.0-flash-lite
systemMessages:
- file: system.txt
`

$3

Chain multiple processing stages:

`yaml
version: "1.0"

stages:
- name: extract
nodes:
parse_data:
type: code
input: $input
file: extract-data.ts

- name: analyze
nodes:
analyze_content:
type: llm
input: extract.parse_data
provider: gemini
model: gemini-2.0-flash-lite
systemMessages:
- file: analyzer-prompt.txt

- name: format
nodes:
format_response:
type: code
input: analyze.analyze_content
file: format-output.ts
`

$3

Run multiple LLM calls simultaneously within a stage:

`yaml
stages:
- name: parallel_analysis
nodes:
sentiment:
type: llm
input: $input.text
provider: gemini
model: gemini-2.0-flash-lite
systemMessages:
- file: sentiment-prompt.txt

keywords:
type: llm
input: $input.text
provider: openai
model: gpt-4o-mini
systemMessages:
- file: keywords-prompt.txt

- name: combine
nodes:
merge:
type: reduce
inputs:
- parallel_analysis.sentiment
- parallel_analysis.keywords
mapping:
sentiment: $.0
keywords: $.1
`

---

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

$3

Calls an LLM provider with a prompt.

Required Properties:
`yaml
my_llm_node:
type: llm
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 | 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
`

---

$3

Executes a custom TypeScript function.

Required Properties:
`yaml
my_code_node:
type: code
input: $input
file: my-processor.ts # Relative to endpoint's codes/ folder
`

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 {
// Your logic here
const processed = / ... /;

return {
type: 'json', // 'string' | 'json' | 'number' | 'boolean' | 'array'
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)

---

$3

Combines multiple node outputs into a single JSON object.

Required Properties:
`yaml
merge_results:
type: reduce
inputs: # Array of node references
- stageName.node1
- stageName.node2
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 }


`

---

$3

Divides a single output into multiple named outputs.

Required Properties:
`yaml
split_data:
type: split
input: stageName.nodeName
mapping: # JSONPath expressions for each output
header: $.metadata.header
body: $.content
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'
`

---

$3

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

$3

If you selected Supabase during project setup, you can use it in code nodes:

`typescript
import { supabase } from '@code-plugins/supabase.js';
import type { NodeOutput } from '@workflow/types';

export default async function(input: unknown): Promise {
const { data, error } = await supabase
.from('articles')
.select('*')
.limit(10);

if (error) {
throw new Error(Database error: ${error.message});
}

return { type: 'json', value: data };
}
`

Configure in .env:
`bash
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key # Optional
`

$3

Add files to src/plugins/ and import via @code-plugins/*:

`typescript
// src/plugins/my-helper.ts
export function formatDate(date: Date): string {
return date.toISOString().split('T')[0];
}

// In any code node:
import { formatDate } from '@code-plugins/my-helper.js';
`

---

Configuration

$3

| Variable | Default | Description |
|----------|---------|-------------|
| PORT | 3000 | Server port |
| LOG_LEVEL | info | Logging level (debug, info, warn, error) |
| LLM_TIMEOUT_MS | 30000 | LLM request timeout |

$3

You need at least one provider configured:

| Variable | Provider |
|----------|----------|
| GEMINI_API_KEY | Google Gemini |
| OPENAI_API_KEY | OpenAI |
| ANTHROPIC_API_KEY | Anthropic Claude |
| GROK_API_KEY | xAI Grok |

$3

| Variable | Plugin |
|----------|--------|
| SUPABASE_URL | Supabase |
| SUPABASE_ANON_KEY | Supabase |
| SUPABASE_SERVICE_KEY | Supabase (optional) |

---

Commands Reference

| Command | Description |
|---------|-------------|
| npm run dev | Start development server with hot reload |
| npm run build | Compile TypeScript to JavaScript |
| npm start | Start production server |
| npm run validate | Validate all workflows |
| npm run create-endpoint | Scaffold a new endpoint interactively |
| npm run scan-deps | Scan and install code node dependencies |
| npm run lint | Run ESLint |
| npm run format | Format code with Prettier |

---

Troubleshooting

| Error | Solution |
|-------|----------|
| "Provider not found" | Check provider is valid and API key is set in .env |
| "Code node file not found" | Verify file exists in codes/ folder with correct filename |
| "Cannot find module '@workflow/types'" | Run npm run build or restart TypeScript server |
| LLM Timeout | Increase LLM_TIMEOUT_MS in .env or use a faster model |
| "SUPABASE_URL required" | Add Supabase credentials to .env |

---

Documentation

For more detailed guides, see the docs/` folder:

- Getting Started - Complete setup walkthrough
- Creating Endpoints - Advanced endpoint patterns
- Using Plugins - Plugin configuration and custom plugins
- Configuration Reference - All environment options

License

ISC