@ariaflowagents/config 0.4.0 → 0.4.2

package/README.md

@@ -1,50 +1,477 @@
-# @ariaflowagents/config
+# AriaFlow Config Guide
 
-Config loader for AriaFlow projects. This package parses `ariaflow.json(c)` and `.ariaflow/*` directories to produce ready-to-run agent configs.
+A comprehensive guide to creating and managing AriaFlow agent configurations.
 
-## Usage
+## Overview
 
-```ts
-import 'dotenv/config';
-import { openai } from '@ai-sdk/openai';
-import { createRuntimeFromConfig, loadAriaflowConfig } from '@ariaflowagents/config';
+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
 
-const loaded = await loadAriaflowConfig({
-  cwd: process.cwd(),
-  modelRegistry: {
-    default: openai('gpt-4o-mini') as any,
-    'openai:gpt-4o-mini': openai('gpt-4o-mini') as any,
+## 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
+```
 
-const runtime = createRuntimeFromConfig(loaded);
+## Tools
 
-for await (const part of runtime.stream({ input: 'Hello!' })) {
-  if (part.type === 'text-delta') process.stdout.write(part.text);
+### 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"
+    }
+  }
 }
 ```
 
-## Config Locations (Precedence)
+Tool implementation (`tools/search/index.ts`):
 
-1. Global: `~/.config/ariaflow/ariaflow.json(c)`
-2. Custom: `ARIAFLOW_CONFIG`
-3. Project: `ariaflow.json(c)` at git root
-4. `.ariaflow/` directories (agents/flows/tools/skills)
-5. Inline: `ARIAFLOW_CONFIG_CONTENT`
+```typescript
+import type { ToolDefinition } from '@ariaflowagents/core';
 
-## Folder Layout
+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;
 ```
-.ariaflow/
-  agent/
-  flow/
-  tools/
-  skill/
-  prompts/
+
+### Skill Loader
+
+Load skills from a directory:
+
+```jsonc
+{
+  "tools": {
+    "skill": {
+      "type": "skill-loader",
+      "paths": ["./skill"]
+    }
+  }
+}
 ```
 
-## Notes
-- Models are resolved via `modelRegistry`.
-- Tools can be loaded from `.ariaflow/tools/*/tool.json` and config entries.
-- Skill loading is opt-in via a `skill-loader` tool config.
+## 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/dist/loader.d.ts

@@ -1,6 +1,6 @@
 import { type HarnessConfig, type Runtime } from '@ariaflowagents/core';
 import type { LoadedConfig, LoadOptions } from './types.js';
-type WarningType = 'invalid_frontmatter' | 'missing_prompt' | 'name_mismatch' | 'missing_ref' | 'invalid_tool_entry' | 'duplicate_agent' | 'duplicate_flow' | 'unresolved_flow_ref' | 'tool_not_found';
+type WarningType = 'invalid_frontmatter' | 'missing_prompt' | 'missing_template' | 'name_mismatch' | 'missing_ref' | 'invalid_tool_entry' | 'duplicate_agent' | 'duplicate_flow' | 'unresolved_flow_ref' | 'tool_not_found';
 interface ConfigWarning {
     type: WarningType;
     file: string;

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAWA,OAAO,EAKL,KAAK,aAAa,EAElB,KAAK,OAAO,EAEb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAIV,YAAY,EACZ,WAAW,EAMZ,MAAM,YAAY,CAAC;AA0CpB,KAAK,WAAW,GACZ,qBAAqB,GACrB,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,oBAAoB,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,UAAU,aAAa;IACrB,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAorBD,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CA4PzF;AAED,wBAAsB,4BAA4B,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC;IACrF,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC,CA+QD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAanH;AAyFD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,gBAAgB,GAAG,cAAc,CAAC,CAAM,GACzF,OAAO,CAST"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAWA,OAAO,EAQL,KAAK,aAAa,EAElB,KAAK,OAAO,EAGb,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAIV,YAAY,EACZ,WAAW,EAMZ,MAAM,YAAY,CAAC;AA0CpB,KAAK,WAAW,GACZ,qBAAqB,GACrB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,aAAa,GACb,oBAAoB,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,UAAU,aAAa;IACrB,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AA0yBD,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CA4PzF;AAED,wBAAsB,4BAA4B,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC;IACrF,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC,CA+QD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAanH;AA0FD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,gBAAgB,GAAG,cAAc,CAAC,CAAM,GACzF,OAAO,CAST"}

package/dist/loader.js

@@ -9,7 +9,8 @@ import { parse as parseJsonc } from 'jsonc-parser';
 import { minimatch } from 'minimatch';
 import { tool as aiTool } from 'ai';
 import { z } from 'zod';
-import { createRuntime, } from '@ariaflowagents/core';
+import { createRuntime, getTemplate, } from '@ariaflowagents/core';
+import { PromptTemplateBuilder } from '@ariaflowagents/core';
 let _warnings = [];
 let _logger = null;
 let _silent = false;
@@ -307,6 +308,115 @@ async function resolvePrompt(value, baseDir) {
         }
         return readFile(resolvedPath, 'utf8');
     }
+    // Handle template references
+    if (typeof value === 'object' && value !== null && 'template' in value) {
+        const templateRef = value;
+        const template = getTemplate(templateRef.template);
+        if (!template) {
+            warn('missing_template', templateRef.template, `Template "${templateRef.template}" not found`);
+            return null;
+        }
+        // Create builder from template
+        const builder = new PromptTemplateBuilder({
+            id: template.id,
+            name: template.name,
+            description: template.description,
+        });
+        // Apply customizations
+        if (templateRef.customize) {
+            if (templateRef.customize.personality) {
+                builder.personality(templateRef.customize.personality);
+            }
+            if (templateRef.customize.goal) {
+                builder.goal(templateRef.customize.goal);
+            }
+            if (templateRef.customize.guardrails) {
+                builder.guardrails(templateRef.customize.guardrails);
+            }
+            if (templateRef.customize.tone) {
+                builder.tone(templateRef.customize.tone);
+            }
+            if (templateRef.customize.tools) {
+                builder.tools(templateRef.customize.tools);
+            }
+            if (templateRef.customize.errorHandling) {
+                builder.errorHandling(templateRef.customize.errorHandling);
+            }
+            if (templateRef.customize.characterNormalization) {
+                builder.characterNormalization(templateRef.customize.characterNormalization);
+            }
+            if (templateRef.customize.voiceRules) {
+                builder.voiceRules(templateRef.customize.voiceRules);
+            }
+            if (templateRef.customize.glossary) {
+                builder.glossary(templateRef.customize.glossary);
+            }
+            if (templateRef.customize.systemReminder) {
+                builder.custom('System Reminder', templateRef.customize.systemReminder);
+            }
+        }
+        // Add additional sections
+        if (templateRef.addSections) {
+            templateRef.addSections.forEach((section) => {
+                if (section.type === 'custom') {
+                    builder.custom(section.type, section.content, section.priority);
+                }
+                else {
+                    // Use the method name directly
+                    const methodName = section.type;
+                    if (typeof builder[methodName] === 'function') {
+                        builder[methodName](section.content);
+                    }
+                    else {
+                        builder.custom(section.type, section.content, section.priority);
+                    }
+                }
+            });
+        }
+        // Add glossary
+        if (templateRef.glossary) {
+            builder.glossary(templateRef.glossary.map((g) => ({
+                name: g.name,
+                description: g.description,
+                synonyms: g.synonyms,
+                category: g.category,
+            })));
+        }
+        // Add voice rules
+        if (templateRef.voiceRules) {
+            builder.voiceRules(templateRef.voiceRules);
+        }
+        // Set today date flag
+        if (templateRef.injectTodayDate !== undefined) {
+            builder.injectTodayDate(templateRef.injectTodayDate);
+        }
+        // Build and return
+        const finalTemplate = builder.build();
+        const promptBuilder = new (await import('@ariaflowagents/core')).PromptBuilder(finalTemplate);
+        return promptBuilder.build();
+    }
+    // Handle inline template definitions
+    if (typeof value === 'object' && value !== null && 'id' in value && 'sections' in value) {
+        const inlineTemplate = value;
+        const builder = new PromptTemplateBuilder({
+            id: inlineTemplate.id,
+            name: inlineTemplate.name,
+            description: inlineTemplate.description,
+        });
+        // Add sections
+        inlineTemplate.sections.forEach((section) => {
+            if (section.type === 'custom') {
+                builder.custom(section.type, section.content, section.priority);
+            }
+            else {
+                builder[section.type]?.(section.content);
+            }
+        });
+        // Build and return
+        const finalTemplate = builder.build();
+        const promptBuilder = new (await import('@ariaflowagents/core')).PromptBuilder(finalTemplate);
+        return promptBuilder.build();
+    }
     return null;
 }
 async function loadFlowFiles(root, sources) {
@@ -1026,7 +1136,7 @@ export function printLoadSummary(summary) {
     }
     console.log(`   • ${summary.durationMs}ms`);
 }
-async function normalizeAgentInput(id, input, baseDir, flows, flowMeta) {
+async function normalizeAgentInput(id, input, baseDir, flows, flowMeta, toolRegistry) {
     const type = (input.type ?? 'llm');
     const name = input.name ?? id;
     const description = input.description;