@botpress/adk 1.17.0 → 1.18.0-beta.2

package/dist/templates/knowledge-assistant/README.md

@@ -0,0 +1,66 @@
+# {{projectName}}
+
+A RAG-powered knowledge assistant built with Botpress ADK. This agent answers questions using your documents, with source citations for every response.
+
+## How It Works
+
+1. **Knowledge Base**: Documents in `src/knowledge/` are indexed for semantic search
+2. **Conversations**: When a user asks a question, the AI searches the knowledge base for relevant passages
+3. **Citations**: Responses include references to the source documents used
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   {{packageManager}} install
+   ```
+
+2. Add your documents to `src/knowledge/` (markdown, PDF, or text files)
+
+3. Start development server:
+
+   ```bash
+   adk dev
+   ```
+
+4. Deploy your agent:
+   ```bash
+   adk deploy
+   ```
+
+## Adding Documents
+
+Place your documents in `src/knowledge/`. Supported formats:
+
+- Markdown (`.md`)
+- PDF (`.pdf`)
+- Text (`.txt`)
+
+The knowledge base automatically indexes all supported files. After adding new documents, run `adk kb sync` or restart `adk dev` to re-index.
+
+## Project Structure
+
+- `src/knowledge/docs.ts` - Knowledge base definition
+- `src/knowledge/*.md` - Your source documents
+- `src/conversations/index.ts` - Conversation handler with RAG execution
+- `src/actions/` - Add custom actions (e.g. programmatic KB search for API access)
+- `src/tables/` - Data storage (extend as needed)
+- `src/triggers/` - Event subscriptions (extend as needed)
+- `src/workflows/` - Long-running processes (extend as needed)
+
+## How Citations Work
+
+The conversation handler passes the knowledge base to `execute()`. The AI automatically searches relevant documents when answering questions and cites its sources. This is handled by the Botpress runtime -- no manual citation logic is required.
+
+## Customization
+
+- **Model**: Change `defaultModels` in `agent.config.ts` to use a different LLM
+- **Instructions**: Edit the `instructions` in `src/conversations/index.ts` to change the agent's personality
+- **Knowledge sources**: Add website crawling or table-based sources in `src/knowledge/docs.ts`
+- **Tools**: Convert the search action to a tool with `.asTool()` for more control
+
+## Learn More
+
+- [ADK Documentation](https://botpress.com/docs/adk)
+- [Botpress Platform](https://botpress.com)

package/dist/templates/knowledge-assistant/agent.config.ts

@@ -0,0 +1,26 @@
+import { z, defineConfig } from '@botpress/runtime'
+
+export default defineConfig({
+  name: '{{projectName}}',
+  description: 'A RAG-powered knowledge assistant that answers questions using your documents',
+
+  defaultModels: {
+    autonomous: 'openai:gpt-4.1-mini-2025-04-14',
+    zai: 'openai:gpt-4.1-2025-04-14',
+  },
+
+  // Per-bot persistent state
+  bot: {
+    state: z.object({}),
+  },
+
+  // Per-user persistent state
+  user: {
+    state: z.object({}),
+  },
+
+  // Integrations extend your agent with actions, channels, and events.
+  dependencies: {
+    integrations: {},
+  },
+})

package/dist/templates/knowledge-assistant/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "A RAG-powered knowledge assistant built with Botpress ADK",
+  "type": "module",
+  "scripts": {
+    "dev": "adk dev",
+    "build": "adk build",
+    "deploy": "adk deploy"
+  },
+  "dependencies": {
+    "@botpress/runtime": "^{{runtimeVersion}}"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/dist/templates/knowledge-assistant/src/actions/index.ts

@@ -0,0 +1,19 @@
+// import { Action, z } from '@botpress/runtime'
+//
+// /**
+//  * A strongly-typed callable function — use `new Action(...)` (it's a class constructor).
+//  * Handler always receives `{ input, client }` as props, not the input fields directly.
+//  * Can be converted to an AI tool via `.asTool()` and passed to `execute()`.
+//  */
+// export default new Action({
+//   name: 'myAction',
+//   input: z.object({
+//     message: z.string().describe('The message to process'),
+//   }),
+//   output: z.object({
+//     result: z.string().describe('The processed result'),
+//   }),
+//   handler: async ({ input }) => {
+//     return { result: `Processed: ${input.message}` }
+//   },
+// })

package/dist/templates/knowledge-assistant/src/actions/search-docs.ts

@@ -0,0 +1,50 @@
+import { Action, z, context } from '@botpress/runtime'
+import { DocsKB } from '../knowledge/docs'
+
+/**
+ * Search the knowledge base programmatically.
+ *
+ * This action provides API-level access to the documentation search,
+ * useful for integrations, workflows, or external systems that need
+ * to query the knowledge base outside of a conversation.
+ */
+export const searchDocs = new Action({
+  name: 'searchDocs',
+  description: 'Search the documentation knowledge base',
+
+  input: z.object({
+    query: z.string().describe('The search query'),
+    limit: z.number().min(1).max(20).default(5).describe('Maximum number of results to return'),
+  }),
+
+  output: z.object({
+    results: z.array(
+      z.object({
+        content: z.string().describe('The matched passage content'),
+        source: z.string().describe('The source file path'),
+        score: z.number().describe('Relevance score'),
+      })
+    ),
+  }),
+
+  async handler({ input }) {
+    const client = context.get('client')
+
+    const { passages } = await client.searchFiles({
+      query: input.query,
+      tags: {
+        source: 'knowledge-base',
+        kbName: [DocsKB.name],
+      },
+      limit: input.limit,
+    })
+
+    return {
+      results: passages.map((p) => ({
+        content: p.content,
+        source: p.file.key,
+        score: p.score,
+      })),
+    }
+  },
+})

package/dist/templates/knowledge-assistant/src/conversations/index.ts

@@ -0,0 +1,33 @@
+import { Conversation } from '@botpress/runtime'
+import { DocsKB } from '../knowledge/docs'
+
+/**
+ * Main conversation handler for the knowledge assistant.
+ *
+ * Uses execute() with the DocsKB knowledge base. The AI automatically
+ * gets a search tool for the KB — no custom action needed.
+ *
+ * Handles all channels (chat, webchat, etc.) via the wildcard channel.
+ */
+export default new Conversation({
+  channel: '*',
+
+  async handler({ execute }) {
+    await execute({
+      instructions: `You are a company knowledge assistant. You answer employee questions using the company documentation.
+
+Lead with example questions, to assist the user in asking good questions. For example:
+- "What is the company's remote work policy?"
+- "How do I request time off?"
+- "What are the steps to set up my email on a new device?"
+Rules:
+- Search the knowledge base for every question. Do not guess or use general knowledge.
+- If the answer is in the docs, quote the relevant policy or section.
+- If the docs don't cover it, say "I don't have information about that in our docs" and suggest who to ask (HR, manager, IT, etc).
+- Be direct. Lead with the answer, then provide context.
+- Use short paragraphs. Bullet points for lists.`,
+
+      knowledge: [DocsKB],
+    })
+  },
+})

package/dist/templates/knowledge-assistant/src/knowledge/docs.ts

@@ -0,0 +1,23 @@
+import { Knowledge, DataSource } from '@botpress/runtime'
+
+/**
+ * Knowledge base that indexes all markdown files in the src/knowledge/ directory.
+ *
+ * Add your documents (markdown, PDF, text) to this folder and they will be
+ * automatically indexed for semantic search. The AI uses this knowledge base
+ * to answer questions with accurate, source-cited responses.
+ *
+ * Sync your knowledge base:
+ *   adk kb sync      (manual sync)
+ *   adk dev          (auto-syncs on startup and file changes)
+ */
+const docsSource = DataSource.Directory.fromPath('src/knowledge', {
+  id: 'docs',
+  filter: (filePath) => filePath.endsWith('.md') || filePath.endsWith('.pdf') || filePath.endsWith('.txt'),
+})
+
+export const DocsKB = new Knowledge({
+  name: 'docsKB',
+  description: 'Documentation and reference materials for answering user questions',
+  sources: [docsSource],
+})

package/dist/templates/knowledge-assistant/src/knowledge/getting-started.md

@@ -0,0 +1,49 @@
+# Company Handbook
+
+Welcome to Acme Corp! This document covers our policies, benefits, and day-to-day operations.
+
+> **Note:** This is sample content. Replace it with your actual company docs, product documentation, or any knowledge you want your assistant to answer questions about.
+
+## Working Hours
+
+Our standard working hours are 9 AM to 5 PM in your local timezone. We offer flexible scheduling — as long as you're available for core hours (11 AM to 3 PM) and attend your team's standups, you can adjust your start and end times.
+
+## Time Off Policy
+
+- **PTO:** 20 days per year, accruing monthly
+- **Sick leave:** Unlimited, no questions asked for the first 3 days. Beyond that, a doctor's note is appreciated but not required.
+- **Holidays:** We follow the US federal holiday calendar. If you're outside the US, you can swap US holidays for your local ones.
+- **Parental leave:** 16 weeks paid for all parents, regardless of gender.
+
+## Expense Policy
+
+- **Software and tools:** Pre-approved up to $100/month. Anything over needs manager approval.
+- **Books and courses:** Fully covered, no cap. Submit receipts through Expensify.
+- **Travel:** Book economy for flights under 5 hours, business class for longer. Hotels up to $250/night.
+- **Meals:** $30/day when traveling. Team dinners covered fully with VP approval.
+
+## Engineering Practices
+
+### Code Review
+
+Every PR needs at least one approval before merging. For changes touching auth, payments, or data deletion, two approvals are required. Reviewers should respond within 24 hours.
+
+### Incident Response
+
+1. **Severity 1 (service down):** Page the on-call engineer via PagerDuty. All hands until resolved.
+2. **Severity 2 (degraded):** Notify #incidents in Slack. On-call investigates, escalates if not resolved in 1 hour.
+3. **Severity 3 (minor bug):** File a ticket, fix in next sprint.
+
+Post-incident reviews happen within 48 hours. No blame, just learnings.
+
+### Deployment
+
+We deploy to production twice daily (11 AM and 4 PM UTC). Feature flags are required for anything user-facing. Rollbacks are one-click via the deploy dashboard.
+
+## Benefits
+
+- **Health insurance:** 100% covered for employees, 80% for dependents
+- **401k:** 4% match, vests immediately
+- **Home office:** $1,500 one-time setup budget for new hires
+- **Wellness:** $100/month for gym, therapy, or wellness apps
+- **Learning:** Conference budget of $2,000/year plus 3 days off to attend

package/dist/templates/knowledge-assistant/src/tables/index.ts

@@ -0,0 +1,21 @@
+// import { Table, z } from '@botpress/runtime'
+//
+// /**
+//  * Example: Track search queries and feedback to improve the knowledge base over time.
+//  *
+//  * Table names must end with "Table" (e.g. QueriesTable, FeedbackTable).
+//  * Mark string columns as `{ searchable: true, schema: z.string() }` to enable semantic search.
+//  * @reserved id, createdAt, updatedAt — auto-managed by the system, do not define them.
+//  */
+// export const QueriesTable = new Table({
+//   name: 'queriesTable',
+//   description: 'Tracks user search queries and their feedback',
+//   columns: {
+//     query: {
+//       searchable: true,
+//       schema: z.string().describe('The user search query'),
+//     },
+//     resultCount: z.number().describe('Number of results returned'),
+//     helpful: z.boolean().optional().describe('Whether the user found the answer helpful'),
+//   },
+// })

package/dist/templates/knowledge-assistant/src/triggers/index.ts

@@ -0,0 +1,17 @@
+// import { Trigger } from '@botpress/runtime'
+//
+// /**
+//  * Example: Track when users start conversations to monitor KB assistant usage.
+//  *
+//  * Bot events:    'register', 'message.created', 'conversation.started', 'conversation.ended',
+//  *                'user.created', 'workflow.started', 'workflow.completed', 'workflow.failed'
+//  * Run `adk info <integration>` to see all events for an integration.
+//  */
+// export default new Trigger({
+//   name: 'onConversationStarted',
+//   description: 'Logs when a new knowledge assistant conversation begins',
+//   events: ['conversation.started'],
+//   handler: async ({ event }) => {
+//     console.log(`New conversation started: ${event.payload.conversationId}`)
+//   },
+// })

package/dist/templates/knowledge-assistant/src/workflows/index.ts

@@ -0,0 +1,28 @@
+// import { Workflow, z } from '@botpress/runtime'
+// import { DocsKB } from '../knowledge/docs'
+//
+// /**
+//  * Example: A research workflow that searches the knowledge base and produces a summary.
+//  *
+//  * Each `step()` call is checkpointed — safe to retry on failure.
+//  * Start from a trigger or conversation via `ResearchWorkflow.start({ input })`.
+//  */
+// export const ResearchWorkflow = new Workflow({
+//   name: 'research',
+//   input: z.object({
+//     topic: z.string().describe('The topic to research'),
+//   }),
+//   output: z.object({
+//     summary: z.string().describe('A summary of findings from the knowledge base'),
+//   }),
+//   handler: async ({ input, step, execute }) => {
+//     const summary = await step('research', async () => {
+//       const result = await execute({
+//         instructions: `Research the following topic using the knowledge base and provide a concise summary: ${input.topic}`,
+//         knowledge: [DocsKB],
+//       })
+//       return result
+//     })
+//     return { summary }
+//   },
+// })

package/dist/templates/knowledge-assistant/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleDetection": "force",
+    "resolveJsonModule": true,
+    "paths": {
+      "@botpress/runtime/_types/*": ["./.adk/*-types"]
+    }
+  },
+  "include": ["src/**/*", ".adk/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/slack-triage/README.md

@@ -0,0 +1,74 @@
+# {{projectName}}
+
+A Slack triage bot built with the Botpress ADK. It monitors channels for help requests, classifies them using AI, and routes them to the right person or channel based on configurable routing rules.
+
+## How It Works
+
+1. **Trigger**: A new message arrives in a monitored Slack channel
+2. **Classify**: The `classify-request` action uses Zai to categorize the request (bug, feature_request, question, ops_issue)
+3. **Route**: The `triage-flow` workflow looks up routing rules from the `RoutingRulesTable` and posts a summary to the appropriate channel or person
+4. **Respond**: The Slack DM conversation handler answers follow-up questions about triage status
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   {{packageManager}} install
+   ```
+
+2. Configure Slack:
+   - Create a Slack app at https://api.slack.com/apps
+   - Add the bot to your workspace
+   - Run `adk dev` and configure the Slack integration in the Botpress dashboard
+
+3. Seed routing rules:
+   After your first `adk dev`, add rows to the `RoutingRulesTable` via the Botpress dashboard or a script:
+
+   ```
+   | category        | assignee       | slackChannel      | priority |
+   |-----------------|----------------|-------------------|----------|
+   | bug             | @oncall-eng    | #bugs             | high     |
+   | feature_request | @product-team  | #feature_requests | medium   |
+   | question        | @support-team  | #help-desk        | low      |
+   | ops_issue       | @devops        | #ops-alerts       | high     |
+   ```
+
+4. Start development server:
+
+   ```bash
+   adk dev
+   ```
+
+5. Deploy your agent:
+   ```bash
+   adk deploy
+   ```
+
+## Project Structure
+
+- `src/actions/classify-request.ts` - AI-powered request classification
+- `src/workflows/triage-flow.ts` - Multi-step triage workflow (classify, lookup, route)
+- `src/conversations/slack-dm.ts` - Handles Slack channel messages with AI
+- `src/tables/routing-rules.ts` - Configurable routing rules
+- `src/triggers/new-message.ts` - Fires on new Slack messages
+- `src/knowledge/team-directory.md` - Team directory for AI context
+
+## Customization
+
+### Adding Categories
+
+Edit `src/actions/classify-request.ts` to add new categories to the `category` enum and update the Zai label definitions.
+
+### Changing Routing Logic
+
+Edit `src/workflows/triage-flow.ts` to customize how requests are routed. You can add steps for priority escalation, duplicate detection, or SLA tracking.
+
+### Adding Channels
+
+Create new conversation handlers in `src/conversations/` for other Slack channels or platforms (e.g., `slack-channel.ts` for public channel responses).
+
+## Learn More
+
+- [ADK Documentation](https://botpress.com/docs/adk)
+- [Botpress Platform](https://botpress.com)

package/dist/templates/slack-triage/agent.config.ts

@@ -0,0 +1,35 @@
+import { z, defineConfig } from '@botpress/runtime'
+
+export default defineConfig({
+  name: '{{projectName}}',
+  description: 'Slack triage bot - monitors channels, classifies help requests, and routes them to the right person',
+
+  defaultModels: {
+    autonomous: 'openai:gpt-4.1-mini-2025-04-14', // Model used by execute() in conversations/workflows
+    zai: 'openai:gpt-4.1-2025-04-14', // Model used by Zai (extract, check, label, etc.)
+  },
+
+  // Per-bot persistent state - tracks triage statistics across all conversations.
+  bot: {
+    state: z.object({
+      totalTriaged: z.number().default(0).describe('Total requests triaged'),
+      lastTriagedAt: z.string().optional().describe('ISO timestamp of last triage'),
+    }),
+  },
+
+  // Per-user persistent state - remembers routing preferences per user.
+  user: {
+    state: z.object({
+      preferredCategory: z.string().optional().describe('Category this user most often submits'),
+      requestCount: z.number().default(0).describe('Number of requests from this user'),
+    }),
+  },
+
+  // Integrations extend your agent with actions, channels, and events.
+  // Browse available integrations:  adk search <name>  |  adk list --available
+  // Install one:                    adk add <integration>  (e.g. adk add browser)
+  // See actions/events/channels:    adk info <integration>
+  dependencies: {
+    integrations: {},
+  },
+})

package/dist/templates/slack-triage/evals/triage-basic.eval.ts

@@ -0,0 +1,55 @@
+/**
+ * Eval: triage-basic
+ *
+ * Verifies that the triage bot correctly classifies common request types.
+ *
+ * Evals use the Eval class from @botpress/adk. Each eval defines a simulated
+ * conversation with assertions on the bot's responses and tool usage.
+ *
+ * Run evals with: adk eval
+ * Run a specific eval: adk eval --name triage-basic
+ */
+import { Eval } from '@botpress/adk'
+
+export default new Eval({
+  name: 'triage-basic',
+  description: 'Verify the bot classifies bug reports, feature requests, and questions correctly',
+  tags: ['triage', 'classification'],
+  type: 'regression',
+
+  conversation: [
+    {
+      user: 'The login page is showing a 500 error whenever I try to sign in with Google SSO',
+      assert: {
+        response: [
+          {
+            llm_judge:
+              'Response acknowledges this is a bug or error report and indicates it will be triaged or routed to the appropriate team',
+          },
+        ],
+      },
+    },
+    {
+      user: 'It would be great if we could export dashboard data to CSV',
+      assert: {
+        response: [
+          {
+            llm_judge:
+              'Response recognizes this as a feature request and indicates it will be forwarded to the product team or logged appropriately',
+          },
+        ],
+      },
+    },
+    {
+      user: 'How do I reset my password?',
+      assert: {
+        response: [
+          {
+            llm_judge:
+              'Response treats this as a general question and either answers it directly or indicates it will be routed to support',
+          },
+        ],
+      },
+    },
+  ],
+})

package/dist/templates/slack-triage/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "A Slack triage bot built with the ADK - classifies help requests and routes them",
+  "type": "module",
+  "scripts": {
+    "dev": "adk dev",
+    "build": "adk build",
+    "deploy": "adk deploy"
+  },
+  "dependencies": {
+    "@botpress/runtime": "^{{runtimeVersion}}"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/dist/templates/slack-triage/src/actions/classify-request.ts

@@ -0,0 +1,65 @@
+import { Action, z, adk } from '@botpress/runtime'
+
+/**
+ * Classifies an incoming help request into a category using Zai.
+ *
+ * Supported categories:
+ *   - bug:             Something is broken or not working as expected
+ *   - feature_request: A request for new functionality
+ *   - question:        A general question or "how do I..." inquiry
+ *   - ops_issue:       Infrastructure, deployment, or operational problem
+ *
+ * Customize: Add new categories by extending the enum and the label definitions below.
+ */
+export const classifyRequest = new Action({
+  name: 'classifyRequest',
+  description: 'Classify a help request into a category using AI',
+
+  input: z.object({
+    message: z.string().describe('The raw help request message text'),
+  }),
+
+  output: z.object({
+    category: z.enum(['bug', 'feature_request', 'question', 'ops_issue']).describe('The classified category'),
+    confidence: z.string().describe('How confident the classification is: high, medium, or low'),
+    summary: z.string().describe('A one-sentence summary of the request'),
+  }),
+
+  handler: async ({ input }) => {
+    // Use Zai label() with .result() to get confidence scores per category.
+    // Each label is evaluated independently with a 5-tier confidence scale.
+    const { output: labels } = await adk.zai
+      .label(input.message, {
+        bug: 'reports a bug, error, crash, or something not working as expected',
+        feature_request: 'requests a new feature, enhancement, or improvement to existing functionality',
+        question: 'asks a general question, seeks guidance, or wants to know how to do something',
+        ops_issue: 'reports an infrastructure, deployment, uptime, or operational problem',
+      })
+      .result()
+
+    // Pick the category with the highest confidence that matched (value: true).
+    type Category = 'bug' | 'feature_request' | 'question' | 'ops_issue'
+    const categories: Category[] = ['bug', 'feature_request', 'question', 'ops_issue']
+
+    const best = categories
+      .filter((c) => labels[c].value)
+      .sort((a, b) => labels[b].confidence - labels[a].confidence)[0]
+
+    const category: Category = best ?? 'question'
+    const confidence = best ? (labels[best].confidence >= 0.8 ? 'high' : 'medium') : 'low'
+
+    // Use Zai extract() to generate a concise summary of the request.
+    const extracted = await adk.zai.extract(
+      input.message,
+      z.object({
+        summary: z.string().describe('A single concise sentence summarizing the help request'),
+      })
+    )
+
+    return {
+      category,
+      confidence,
+      summary: extracted.summary,
+    }
+  },
+})