@ariaflowagents/config 0.3.5 → 0.4.2

package/guide/README.md

@@ -0,0 +1,477 @@
+# AriaFlow Config Guide
+
+A comprehensive guide to creating and managing AriaFlow agent configurations.
+
+## Overview
+
+The AriaFlow Config package (`@ariaflowagents/config`) provides:
+- Configuration loading from `ari aflow.jsonc` files
+- Agent and flow definition parsing
+- Tool registration and loading
+- Runtime creation from config
+
+## Installation
+
+```bash
+npm install @ariaflowagents/config
+```
+
+## Configuration File
+
+### Basic Structure
+
+```jsonc
+{
+  "$schema": "https://ariaflow.ai/config.json",
+  "name": "my-agent",
+  "version": "1.0.0",
+  "runtime": {
+    "defaultAgent": "chat",
+    "defaultModel": "default"
+  },
+  "models": {
+    "default": "openai:gpt-4o-mini"
+  },
+  "agents": { /* ... */ },
+  "tools": { /* ... */ },
+  "providers": { /* ... */ }
+}
+```
+
+## Runtime Configuration
+
+### Default Agent & Model
+
+```jsonc
+{
+  "runtime": {
+    "defaultAgent": "chat",
+    "defaultModel": "default"
+  }
+}
+```
+
+### Model Registry
+
+Define available models with providers:
+
+```jsonc
+{
+  "models": {
+    "default": "openai:gpt-4o-mini",
+    "gpt-4": "openai:gpt-4",
+    "claude-3": "anthropic:claude-3-5-sonnet-20241022"
+  }
+}
+```
+
+## Agents
+
+Agents are the core components that handle user interactions.
+
+### LLM Agent
+
+```jsonc
+{
+  "agents": {
+    "chat": {
+      "type": "llm",
+      "description": "A helpful assistant",
+      "prompt": {
+        "inline": "You are a helpful assistant. Be concise."
+      },
+      "tools": ["search", "calculator"]
+    }
+  }
+}
+```
+
+### Triage Agent
+
+Routes users to specialized agents:
+
+```jsonc
+{
+  "agents": {
+    "triage": {
+      "type": "triage",
+      "description": "Routes customers to the right department",
+      "prompt": { "file": "./prompts/triage.md" },
+      "routes": [
+        {
+          "agentId": "sales",
+          "description": "Handles sales inquiries"
+        },
+        {
+          "agentId": "support",
+          "description": "Handles support issues"
+        }
+      ],
+      "defaultAgent": "sales"
+    }
+  }
+}
+```
+
+### Flow Agent
+
+Guided workflow agents:
+
+```jsonc
+{
+  "agents": {
+    "booking": {
+      "type": "flow",
+      "description": "Hotel booking flow",
+      "prompt": { "file": "./prompts/booking.md" },
+      "flowRef": "booking-flow",
+      "mode": "hybrid"
+    }
+  }
+}
+```
+
+### Inline Prompt
+
+For simple agents, use inline prompts:
+
+```jsonc
+{
+  "agents": {
+    "chat": {
+      "type": "llm",
+      "description": "A helpful assistant",
+      "prompt": {
+        "inline": "You are a helpful assistant. Be concise and friendly."
+      }
+    }
+  }
+}
+```
+
+### File-based Prompt
+
+For complex prompts, use external files:
+
+```jsonc
+{
+  "agents": {
+    "support": {
+      "type": "llm",
+      "description": "Customer support",
+      "prompt": { "file": "./prompts/support.md" }
+    }
+  }
+}
+```
+
+Create the prompt file:
+
+```markdown
+# System Prompt
+
+You are a customer support agent for our company.
+
+## Guidelines
+- Be empathetic and patient
+- Always verify customer identity before sharing sensitive info
+- Escalate complex issues to human agents
+
+## Tools Available
+- create_ticket: Create support tickets
+```
+
+## Tools
+
+### External Tools
+
+Define tools that agents can use:
+
+```jsonc
+{
+  "tools": {
+    "search": {
+      "type": "module",
+      "entry": "./tools/search/index.ts"
+    },
+    "calculator": {
+      "type": "module",
+      "entry": "./tools/calculator/index.ts"
+    }
+  }
+}
+```
+
+Tool implementation (`tools/search/index.ts`):
+
+```typescript
+import type { ToolDefinition } from '@ariaflowagents/core';
+
+export const tool: ToolDefinition = {
+  description: 'Search for information',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' }
+    },
+    required: ['query']
+  },
+  execute: async (input: unknown) => {
+    const { query } = input as { query: string };
+    // Implementation
+    return { results: [...] };
+  }
+};
+
+export default tool;
+```
+
+### Skill Loader
+
+Load skills from a directory:
+
+```jsonc
+{
+  "tools": {
+    "skill": {
+      "type": "skill-loader",
+      "paths": ["./skill"]
+    }
+  }
+}
+```
+
+## Flows
+
+Define reusable workflow patterns:
+
+```jsonc
+{
+  "flows": {
+    "booking-flow": {
+      "steps": [
+        {
+          "id": "collect-info",
+          "tool": "collect_info"
+        },
+        {
+          "id": "confirm",
+          "tool": "confirm_booking"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Providers
+
+Configure API providers:
+
+```jsonc
+{
+  "providers": {
+    "openai": {
+      "apiKey": "OPENAI_API_KEY",
+      "baseUrl": "https://api.openai.com/v1"
+    },
+    "anthropic": {
+      "apiKey": "ANTHROPIC_API_KEY"
+    }
+  }
+}
+```
+
+## Loading Configuration
+
+### Basic Loading
+
+```typescript
+import { loadAriaflowConfig } from '@ariaflowagents/config';
+
+const config = await loadAriaflowConfig({
+  configPath: './ari aflow.jsonc'
+});
+```
+
+### With Model Registry
+
+```typescript
+import { loadAriaflowConfigWithResult } from '@ariaflowagents/config';
+import { openai } from '@ai-sdk/openai';
+
+const model = openai('gpt-4o-mini') as any;
+
+const { config, summary, warnings } = await loadAriaflowConfigWithResult({
+  configPath: './ari aflow.jsonc',
+  modelRegistry: {
+    default: model,
+    'openai:gpt-4o-mini': model
+  }
+});
+
+console.log(`Loaded ${summary.agents} agents`);
+```
+
+### Create Runtime
+
+```typescript
+import { createRuntimeFromConfig } from '@ariaflowagents/config';
+
+const { config } = await loadAriaflowConfigWithResult({
+  configPath: './ari aflow.jsonc'
+});
+
+const runtime = createRuntimeFromConfig(config);
+```
+
+## Directory Structure
+
+```
+my-agent/
+├── ariaflow.jsonc              # Main configuration
+├── .ariaflow/
+│   ├── prompts/
+│   │   ├── system.md           # System prompts
+│   │   ├── chat.md             # Agent prompts
+│   │   └── triage.md           # Triage prompts
+│   ├── tools/
+│   │   ├── search/
+│   │   │   ├── index.ts        # Tool implementation
+│   │   │   └── tool.json       # Tool metadata
+│   │   └── calculator/
+│   │       ├── index.ts
+│   │       └── tool.json
+│   ├── skill/
+│   │   └── my-skill/
+│   │       └── SKILL.md
+│   └── flow/
+│       └── booking-flow.json   # Flow definitions
+└── package.json                # Optional: Tool dependencies
+```
+
+## Example: Complete Configuration
+
+```jsonc
+{
+  "$schema": "https://ariaflow.ai/config.json",
+  "name": "support-agent",
+  "version": "1.0.0",
+  "runtime": {
+    "defaultAgent": "triage",
+    "defaultModel": "gpt-4o-mini"
+  },
+  "models": {
+    "default": "openai:gpt-4o-mini",
+    "gpt-4": "openai:gpt-4"
+  },
+  "agents": {
+    "triage": {
+      "type": "triage",
+      "description": "Routes support requests",
+      "prompt": { "file": "./prompts/triage.md" },
+      "routes": [
+        { "agentId": "billing", "description": "Billing inquiries" },
+        { "agentId": "technical", "description": "Technical support" }
+      ],
+      "defaultAgent": "billing"
+    },
+    "billing": {
+      "type": "llm",
+      "description": "Handles billing questions",
+      "prompt": { "file": "./prompts/billing.md" },
+      "tools": ["create_ticket"]
+    },
+    "technical": {
+      "type": "llm",
+      "description": "Technical support",
+      "prompt": { "file": "./prompts/technical.md" },
+      "tools": ["diagnose", "create_ticket"]
+    }
+  },
+  "tools": {
+    "create_ticket": {
+      "type": "module",
+      "entry": "./tools/create_ticket/index.ts"
+    },
+    "diagnose": {
+      "type": "module",
+      "entry": "./tools/diagnose/index.ts"
+    }
+  },
+  "providers": {
+    "openai": {
+      "apiKey": "OPENAI_API_KEY"
+    }
+  }
+}
+```
+
+## Configuration Reference
+
+### Root Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `$schema` | string | No | JSON schema URI |
+| `name` | string | Yes | Agent name |
+| `version` | string | No | Version number |
+| `runtime` | object | Yes | Runtime configuration |
+| `models` | object | Yes | Model registry |
+| `agents` | object | Yes | Agent definitions |
+| `tools` | object | No | Tool definitions |
+| `providers` | object | No | Provider configurations |
+| `permissions` | object | No | Permission settings |
+
+### Runtime Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `defaultAgent` | string | Default agent ID |
+| `defaultModel` | string | Default model key |
+
+### Agent Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | string | Agent type: `llm`, `triage`, `flow` |
+| `description` | string | Agent description |
+| `prompt` | object | Prompt configuration |
+| `tools` | array | List of tool names |
+| `routes` | array | Triage routes (triage only) |
+| `defaultAgent` | string | Default route (triage only) |
+| `flowRef` | string | Flow reference (flow only) |
+| `mode` | string | Flow mode: `guided`, `hybrid` (flow only) |
+
+### Prompt Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `inline` | string | Inline prompt text |
+| `file` | string | Path to prompt file |
+
+## Best Practices
+
+1. **Use file-based prompts** for complex prompts (>100 lines)
+2. **Organize tools** in separate directories with `tool.json` metadata
+3. **Use triage agents** for multi-agent routing
+4. **Version your config** using semantic versioning
+5. **Test locally** using the Hono server before deployment
+6. **Use environment variables** for API keys
+
+## Integration with Hono Server
+
+```typescript
+import { loadAriaflowConfigWithResult, createRuntimeFromConfig } from '@ariaflowagents/config';
+import { createAriaChatRouter } from '@ariaflowagents/hono-server';
+
+const { config, summary } = await loadAriaflowConfigWithResult({
+  configPath: './ari aflow.jsonc',
+  modelRegistry: { default: model }
+});
+
+const runtime = createRuntimeFromConfig(config);
+
+const app = new Hono();
+app.route('/', createAriaChatRouter({ runtime }));
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariaflowagents/config",
-  "version": "0.3.5",
+  "version": "0.4.2",
   "description": "Config loader for AriaFlow (agents, flows, tools, skills)",
   "type": "module",
   "main": "dist/index.js",
@@ -21,14 +21,15 @@
     "gray-matter": "^4.0.3",
     "jsonc-parser": "^3.2.0",
     "minimatch": "^9.0.5",
-    "zod": "^3.23.8"
+    "zod": "^3.23.8",
+    "@ariaflowagents/core": "0.4.1"
   },
   "peerDependencies": {
     "@ariaflowagents/core": "^0.3.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.0",
-    "@ariaflowagents/core": "file:../ariaflow-core",
+    "@ariaflowagents/core": "0.4.1",
     "@types/node": "^20.11.0",
     "dotenv": "^16.4.0",
     "tsx": "^4.7.0",
@@ -47,6 +48,7 @@
   },
   "files": [
     "dist",
+    "guide",
     "README.md"
   ]
 }