create-web-ai-service 1.0.2 → 1.0.4

package/docs/configuration.md

@@ -0,0 +1,96 @@
+# Configuration Reference
+
+All configuration options for web-ai-service projects.
+
+## Environment Variables
+
+### Server
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | HTTP server port |
+| `LOG_LEVEL` | `info` | Logging level: `debug`, `info`, `warn`, `error` |
+
+### LLM Providers
+
+Configure API keys for the providers you want to use. You need at least one.
+
+| Variable | Description |
+|----------|-------------|
+| `GEMINI_API_KEY` | Google Gemini API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
+| `GROK_API_KEY` | xAI Grok API key |
+| `LLM_TIMEOUT_MS` | Request timeout (default: 30000) |
+
+### Supabase (Optional)
+
+| Variable | Description |
+|----------|-------------|
+| `SUPABASE_URL` | Your Supabase project URL |
+| `SUPABASE_ANON_KEY` | Public/anonymous key |
+| `SUPABASE_SERVICE_KEY` | Service role key (optional) |
+
+---
+
+## LLM Provider Options
+
+### Supported Providers
+
+| Provider | 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` |
+
+### Node Configuration
+
+```yaml
+nodes:
+  my_llm_node:
+    type: llm
+    input: $input
+    provider: gemini           # Required
+    model: gemini-2.0-flash-lite  # Required
+    temperature: 0.7           # Optional (0.0-1.0)
+    maxTokens: 1024            # Optional
+    systemMessages:            # Optional
+      - file: prompt.txt
+        cache: true            # Cache for performance
+```
+
+---
+
+## Workflow Structure
+
+```yaml
+version: "1.0"
+
+stages:
+  - name: stage_name
+    nodes:
+      node_name:
+        type: llm | code | reduce | split | passthrough
+        input: $input | stageName.nodeName
+        # ... type-specific options
+```
+
+### Input References
+
+| Pattern | Description |
+|---------|-------------|
+| `$input` | Full request body |
+| `$input.field` | Specific field from body |
+| `stage.node` | Output from previous node |
+
+---
+
+## File Paths
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/endpoints/` | API endpoint definitions |
+| `src/endpoints/*/codes/` | Code node TypeScript files |
+| `src/endpoints/*/prompts/` | LLM system prompt files |
+| `src/plugins/` | Shared plugin modules |

package/docs/creating-endpoints.md

@@ -0,0 +1,202 @@
+# Creating Endpoints
+
+Endpoints are the API routes of your web-ai-service project. Each endpoint is a folder containing a YAML workflow definition and optional code/prompt files.
+
+## Quick Example
+
+Create a POST endpoint at `/summarize`:
+
+```bash
+mkdir -p src/endpoints/summarize/prompts
+```
+
+### Step 1: 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
+```
+
+### Step 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.
+```
+
+### Step 3: Test
+
+```bash
+curl -X POST http://localhost:3000/summarize \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Long text to summarize..."}'
+```
+
+---
+
+## Adding Code Nodes
+
+Use code nodes for custom logic like validation, data transformation, or external API calls.
+
+### Example: Input Validation
+
+**`src/endpoints/summarize/codes/validate.ts`**:
+
+```typescript
+import type { NodeOutput } from '@workflow/types';
+
+export default async function(input: unknown): Promise<NodeOutput> {
+    const body = input as { text?: string };
+    
+    if (!body.text || body.text.length < 10) {
+        throw new Error('Text must be at least 10 characters');
+    }
+    
+    return { type: 'string', value: body.text };
+}
+```
+
+**Updated `POST.yaml`**:
+
+```yaml
+version: "1.0"
+
+stages:
+  - name: validate
+    nodes:
+      check_input:
+        type: code
+        input: $input
+        file: validate.ts
+
+  - name: process
+    nodes:
+      summarize:
+        type: llm
+        input: validate.check_input
+        provider: gemini
+        model: gemini-2.0-flash-lite
+        systemMessages:
+          - file: system.txt
+```
+
+---
+
+## Multi-Stage Workflows
+
+Chain multiple stages together. Each stage's output can be referenced by the next.
+
+### Example: Extract → Analyze → Format
+
+```yaml
+version: "1.0"
+
+stages:
+  - name: extract
+    nodes:
+      get_data:
+        type: code
+        input: $input
+        file: extract-data.ts
+
+  - name: analyze
+    nodes:
+      analyze_content:
+        type: llm
+        input: extract.get_data
+        provider: gemini
+        model: gemini-2.0-flash-lite
+        systemMessages:
+          - file: analyzer-prompt.txt
+
+  - name: format
+    nodes:
+      format_output:
+        type: code
+        input: analyze.analyze_content
+        file: format-response.ts
+```
+
+---
+
+## Parallel Execution
+
+Run multiple nodes in parallel within a single 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: gemini
+        model: gemini-2.0-flash-lite
+        systemMessages:
+          - file: keywords-prompt.txt
+
+  - name: combine
+    nodes:
+      merge_results:
+        type: reduce
+        inputs:
+          - parallel_analysis.sentiment
+          - parallel_analysis.keywords
+        mapping:
+          sentiment: $.0
+          keywords: $.1
+```
+
+---
+
+## Node Types Reference
+
+| Type | Purpose | Key Properties |
+|------|---------|----------------|
+| `llm` | Call LLM provider | `provider`, `model`, `systemMessages`, `temperature`, `maxTokens` |
+| `code` | Execute TypeScript | `file` |
+| `reduce` | Combine outputs | `inputs`, `mapping` |
+| `split` | Divide output | `mapping` |
+| `passthrough` | Pass input unchanged | – |
+
+---
+
+## Input References
+
+| Reference | Description |
+|-----------|-------------|
+| `$input` | Raw request body |
+| `$input.fieldName` | Specific field from request |
+| `stageName.nodeName` | Output from a previous node |
+
+---
+
+## Best Practices
+
+1. **Validate early** – Add a code node at the start to validate inputs
+2. **Keep prompts focused** – One task per LLM node
+3. **Use stages logically** – Group related operations
+4. **Error handling** – Throw descriptive errors in code nodes

package/docs/getting-started.md

@@ -0,0 +1,78 @@
+# Getting Started with Web AI Service
+
+This guide walks you through creating your first AI-powered API with web-ai-service.
+
+## Prerequisites
+
+- Node.js 18+
+- An LLM API key (Gemini, OpenAI, Anthropic, or Grok)
+
+## Installation
+
+### Create a New Project
+
+```bash
+npx create-web-ai-service my-api
+cd my-api
+```
+
+The CLI will prompt you to:
+1. Enter your project name
+2. Select plugins to install (e.g., Supabase)
+
+### Configure Environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and add your API keys:
+
+```bash
+# At minimum, add one LLM provider key
+GEMINI_API_KEY=your-gemini-api-key-here
+# or
+OPENAI_API_KEY=your-openai-api-key-here
+```
+
+### Start Development
+
+```bash
+npm run dev
+```
+
+Your API is now running at `http://localhost:3000`.
+
+## Test the Example Endpoint
+
+The scaffolder creates a `/hello` example endpoint. Test it:
+
+```bash
+# Basic request
+curl http://localhost:3000/hello
+
+# With a name parameter
+curl "http://localhost:3000/hello?name=Alice"
+```
+
+## Project Structure
+
+```
+my-api/
+├── src/
+│   ├── endpoints/          # API endpoint definitions
+│   │   └── hello/          # Example: GET /hello
+│   │       ├── GET.yaml    # Workflow definition
+│   │       ├── codes/      # TypeScript code nodes
+│   │       └── prompts/    # LLM system prompts
+│   └── plugins/            # Shared code modules
+├── .env                    # Environment config (gitignored)
+├── .env.example            # Template for .env
+└── package.json
+```
+
+## Next Steps
+
+- [Creating Endpoints](./creating-endpoints.md) - Learn to build custom endpoints
+- [Using Plugins](./using-plugins.md) - Configure database and auth plugins
+- [Configuration Reference](./configuration.md) - All environment options

package/docs/using-plugins.md

@@ -0,0 +1,127 @@
+# Using Plugins
+
+Plugins extend your web-ai-service project with additional capabilities like database access, authentication, and external services.
+
+## Available Plugins
+
+| Plugin | Description |
+|--------|-------------|
+| `supabase` | Database & Auth integration with Supabase |
+
+---
+
+## Supabase Plugin
+
+### Installation
+
+If you didn't select Supabase during project creation, add it manually:
+
+```bash
+npm install @supabase/supabase-js
+```
+
+Copy the plugin file from [the template](https://github.com/yourrepo/web-ai-service) or create your own.
+
+### Configuration
+
+Add these variables to your `.env` file:
+
+```bash
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your-supabase-anon-key
+SUPABASE_SERVICE_KEY=your-supabase-service-key  # Optional, for admin operations
+```
+
+### Usage in Code Nodes
+
+```typescript
+import { supabase } from '@code-plugins/supabase.js';
+import type { NodeOutput } from '@workflow/types';
+
+export default async function(input: unknown): Promise<NodeOutput> {
+    const { data, error } = await supabase
+        .from('articles')
+        .select('*')
+        .limit(10);
+    
+    if (error) {
+        throw new Error(`Database error: ${error.message}`);
+    }
+    
+    return { type: 'json', value: data };
+}
+```
+
+### Custom Clients
+
+Create a client with different credentials:
+
+```typescript
+import { getSupabaseClient } from '@code-plugins/supabase.js';
+
+// Use custom URL and key
+const customClient = getSupabaseClient(
+    'https://other-project.supabase.co',
+    'other-anon-key'
+);
+```
+
+---
+
+## Creating Custom Plugins
+
+Plugins are TypeScript modules in `src/plugins/`. Create your own:
+
+### Example: Redis Cache Plugin
+
+**`src/plugins/redis.ts`**:
+
+```typescript
+import Redis from 'ioredis';
+
+let client: Redis | null = null;
+
+function getRedisUrl(): string {
+    const url = process.env.REDIS_URL;
+    if (!url) {
+        throw new Error('REDIS_URL environment variable is required');
+    }
+    return url;
+}
+
+export function getRedisClient(): Redis {
+    if (!client) {
+        client = new Redis(getRedisUrl());
+    }
+    return client;
+}
+
+export const redis = new Proxy({} as Redis, {
+    get(_target, prop) {
+        return Reflect.get(getRedisClient(), prop);
+    },
+});
+```
+
+Add to `.env`:
+
+```bash
+REDIS_URL=redis://localhost:6379
+```
+
+Use in code nodes:
+
+```typescript
+import { redis } from '@code-plugins/redis.js';
+
+const cached = await redis.get('my-key');
+```
+
+---
+
+## Plugin Best Practices
+
+1. **Lazy initialization** – Don't connect until first use
+2. **Environment validation** – Throw clear errors for missing config
+3. **Singleton pattern** – Reuse connections across requests
+4. **Type exports** – Re-export useful types for consumers

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-web-ai-service",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "description": "CLI scaffolder for creating new web-ai-service projects",
     "type": "module",
     "main": "dist/index.js",
@@ -10,7 +10,8 @@
     "files": [
         "dist",
         "bin",
-        "templates"
+        "templates",
+        "docs"
     ],
     "scripts": {
         "build": "tsc",