@ariaflowagents/tools 0.4.4 → 0.4.7

package/guides/CAG.md

@@ -0,0 +1,44 @@
+# CAG Tools
+
+Two tools, split responsibilities:
+
+- **CAGTool** → retrieval only, returns chunks.
+- **CAGAnswerTool** → answer only, returns `{ type: 'final', text }`.
+
+## CAGTool (retrieve)
+
+Input
+
+```ts
+{ query: string; topK?: number; hint?: string }
+```
+
+Output
+
+```ts
+{ chunks: ChunkDef[] }
+```
+
+## CAGAnswerTool (answer)
+
+Input
+
+```ts
+{ query: string; chunks: ChunkDef[] }
+```
+
+Output
+
+```ts
+{ type: 'final'; text: string; reasons?: string[]; chunks: ChunkDef[] }
+```
+
+## Grounding Rules
+
+- Retriever selects from approved `KnowledgeSource` chunks only.
+- Answer tool uses only provided chunks.
+
+## Notes
+
+- Tool loop is handled by Runtime/FlowManager.
+- Auto-retrieve (always-on) is a runtime feature; it calls the retriever tool and injects context before the model runs.

package/guides/GETTING_STARTED.md

@@ -0,0 +1,63 @@
+# Getting Started (Tools)
+
+## Install
+
+```bash
+bun add @ariaflowagents/tools @ariaflowagents/rag @ariaflowagents/core ai @ai-sdk/openai
+```
+
+## Minimal Example
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { createStaticKnowledgeSource, createLLMRetriever } from '@ariaflowagents/rag';
+import { createCagTool, createCagAnswerTool } from '@ariaflowagents/tools';
+
+const supportSource = createStaticKnowledgeSource({
+  id: 'support-pack',
+  name: 'Support Pack',
+  content: 'Refunds: 30 days. Cancellations: anytime.',
+});
+
+const retriever = createLLMRetriever({
+  model: openai('gpt-4o-mini') as any,
+  topK: 4,
+});
+
+const cag = createCagTool({ sources: [supportSource], retriever });
+const cagAnswer = createCagAnswerTool({
+  generatorModel: openai('gpt-4o') as any,
+});
+
+const { chunks } = await cag.execute({ query: 'What is the refund policy?' });
+const result = await cagAnswer.execute({ query: 'What is the refund policy?', chunks });
+
+console.log(result.text);
+```
+
+## Example (runtime loop)
+
+Run the bundled example:
+
+```bash
+cd packages/ariaflow-tools/examples/auto-retrieve-runtime
+bunx tsx run.ts
+```
+
+## Example (auto-retrieve + triage)
+
+Structured triage + always-on retrieval.
+
+```bash
+cd packages/ariaflow-tools/examples/auto-retrieve-triage
+bunx tsx run.ts
+```
+
+## Example (enterprise SOP)
+
+Flow-based support SOP with validation + ticketing.
+
+```bash
+cd packages/ariaflow-tools/examples/enterprise-support-agent
+bunx tsx run.ts
+```

package/guides/README.md

@@ -0,0 +1,17 @@
+# AriaFlow Tools Guides
+
+Concise docs for tools in `@ariaflowagents/tools`.
+
+## Getting Started
+
+- **[Getting Started](./GETTING_STARTED.md)** - Create CAG tools and run the example
+- **Examples**:
+  - `packages/ariaflow-tools/examples/auto-retrieve-runtime/`
+  - `packages/ariaflow-tools/examples/auto-retrieve-triage/`
+  - `packages/ariaflow-tools/examples/enterprise-support-agent/`
+  - `packages/ariaflow-tools/examples/support-multi-packs/`
+  - `packages/ariaflow-tools/examples/ecommerce-multi-packs/`
+
+## Guides
+
+- **[CAG Tools](./CAG.md)** - Retrieve + answer tool split

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariaflowagents/tools",
-  "version": "0.4.4",
+  "version": "0.4.7",
   "description": "AriaFlow tools (CAG)",
   "type": "module",
   "main": "dist/index.js",
@@ -12,19 +12,19 @@
     }
   },
   "dependencies": {
-    "@ariaflowagents/core": "^0.4.4",
-    "@ariaflowagents/rag": "^0.4.4"
+    "@ariaflowagents/core": "^0.4.7",
+    "@ariaflowagents/rag": "^0.4.6"
   },
   "peerDependencies": {
-    "@ariaflowagents/core": "^0.4.4",
-    "@ariaflowagents/rag": "^0.4.4",
+    "@ariaflowagents/core": "^0.4.7",
+    "@ariaflowagents/rag": "^0.4.6",
     "ai": "^6.0.0",
     "zod": "^3.0.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.0",
-    "@ariaflowagents/core": "^0.4.4",
-    "@ariaflowagents/rag": "^0.4.4",
+    "@ariaflowagents/core": "^0.4.7",
+    "@ariaflowagents/rag": "^0.4.6",
     "@types/node": "^20.11.0",
     "ai": "^6.0.0",
     "typescript": "^5.3.0",
@@ -40,6 +40,7 @@
   },
   "files": [
     "dist",
+    "guides",
     "README.md"
   ]
 }