@ariaflowagents/config 0.4.0 → 0.4.3

package/README.md

@@ -1,50 +1,517 @@
-# @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"
+  }
+}
+```
+
+### Auto Retrieve (always-on)
+
+Calls a retriever tool before every model run and injects the context.
+
+```jsonc
+{
+  "runtime": {
+    "autoRetrieve": {
+      "type": "tool",
+      "toolName": "cag_retrieve"
+    }
+  }
+}
+```
+
+### Structured Triage
+
+Force triage responses into a schema and route without leaking triage text.
+
+```jsonc
+{
+  "runtime": {
+    "triageMode": "structured",
+    "triageAgent": "triage"
+  }
+}
+```
+
+### Always Route Through Triage
+
+Useful when every user turn should be re-routed.
+
+```jsonc
+{
+  "runtime": {
+    "alwaysRouteThroughTriage": true
+  }
+}
+```
+
+## 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
 
-const runtime = createRuntimeFromConfig(loaded);
+Define reusable workflow patterns:
 
-for await (const part of runtime.stream({ input: 'Hello!' })) {
-  if (part.type === 'text-delta') process.stdout.write(part.text);
+```jsonc
+{
+  "flows": {
+    "booking-flow": {
+      "steps": [
+        {
+          "id": "collect-info",
+          "tool": "collect_info"
+        },
+        {
+          "id": "confirm",
+          "tool": "confirm_booking"
+        }
+      ]
+    }
+  }
 }
 ```
 
-## Config Locations (Precedence)
+## Providers
+
+Configure API providers:
 
-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`
+```jsonc
+{
+  "providers": {
+    "openai": {
+      "apiKey": "OPENAI_API_KEY",
+      "baseUrl": "https://api.openai.com/v1"
+    },
+    "anthropic": {
+      "apiKey": "ANTHROPIC_API_KEY"
+    }
+  }
+}
+```
 
-## Folder Layout
+## Loading Configuration
 
+### Basic Loading
+
+```typescript
+import { loadAriaflowConfig } from '@ariaflowagents/config';
+
+const config = await loadAriaflowConfig({
+  configPath: './ari aflow.jsonc'
+});
 ```
-.ariaflow/
-  agent/
-  flow/
-  tools/
-  skill/
-  prompts/
+
+### 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`);
 ```
 
-## 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.
+### 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,EAUL,KAAK,aAAa,EAElB,KAAK,OAAO,EAGb,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAKV,YAAY,EACZ,WAAW,EAMZ,MAAM,YAAY,CAAC;AA4CpB,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;AAq8BD,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CA6QzF;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,CAgSD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAanH;AA4FD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,gBAAgB,GAAG,cAAc,CAAC,CAAM,GACzF,OAAO,CAWT"}