@botpress/adk-cli 1.19.0-beta.3 → 1.19.0-beta.5

package/dist/knowledge-bases-20rg8p5c.md

@@ -0,0 +1,456 @@
+# Knowledge Bases
+
+Knowledge Bases enable RAG (Retrieval Augmented Generation) by indexing documents, websites, and structured data for semantic search and AI-powered responses.
+
+## Basic Concepts
+
+### What are Knowledge Bases?
+
+- **RAG implementation**: Enhance AI responses with relevant context
+- **Multiple sources**: Index local files, websites, or table data
+- **Semantic search**: Find relevant information based on meaning
+- **Auto-chunking**: Documents are automatically split for optimal retrieval
+
+### File Location
+
+- **Location**: `src/knowledge/*.ts`
+- **Auto-registration**: Knowledge bases are automatically available to AI
+
+## Creating Knowledge Bases
+
+### Basic Structure
+
+```typescript
+import { Knowledge, DataSource } from "@botpress/runtime";
+
+// Define a data source
+const docsSource = DataSource.Directory.fromPath("src/knowledge/docs", {
+  id: "docs",
+  filter: (path) => path.endsWith(".md") || path.endsWith(".pdf"),
+});
+
+// Create knowledge base
+export const DocsKnowledgeBase = new Knowledge({
+  name: "docsKB",
+  description: "Documentation knowledge base",
+  sources: [docsSource],
+});
+```
+
+## Data Source Types
+
+### 1. Local Files (Directory)
+
+Index local markdown, PDF, and text files:
+
+```typescript
+const docsSource = DataSource.Directory.fromPath("src/knowledge", {
+  id: "docs",
+
+  // Filter specific file types
+  filter: (path) => {
+    return (
+      path.endsWith(".md") || path.endsWith(".pdf") || path.endsWith(".txt")
+    );
+  },
+});
+```
+
+**Note**: Local file sources are for development only and won't work in production.
+
+### 2. Website Crawling
+
+Index websites via sitemap or direct URLs:
+
+```typescript
+// From sitemap
+const websiteSource = DataSource.Website.fromSitemap(
+  "https://docs.example.com/sitemap.xml",
+  {
+    id: "website",
+    maxPages: 500, // Maximum pages to crawl (1-50000)
+    maxDepth: 3, // Maximum crawl depth (1-20)
+    fetch: "node:fetch", // Optional: 'node:fetch' or 'integration:browser'
+
+    // Filter pages
+    filter: (context) => {
+      // Skip archive pages
+      if (context.url.includes("/archive/")) {
+        return false;
+      }
+      // Only include documentation pages
+      return context.url.includes("/docs/");
+    },
+  },
+);
+
+// From direct URLs
+const urlsSource = DataSource.Website.fromUrls(
+  [
+    "https://example.com/page1",
+    "https://example.com/page2",
+    "https://example.com/page3",
+  ],
+  {
+    id: "specific_pages",
+  },
+);
+
+// From llms.txt (AI-friendly site manifest)
+const llmsTxtSource = DataSource.Website.fromLlmsTxt(
+  "https://example.com/llms.txt",
+  {
+    id: "llms_txt",
+    maxPages: 100,
+  },
+);
+```
+
+### 3. Table-Based
+
+Table-backed knowledge sources are not fully implemented yet. The shape below is useful as a forward-looking pattern, but today you should treat it as experimental and prefer directory- or website-backed sources for production workflows.
+
+```typescript
+import { FAQTable } from "../tables/FAQ";
+
+const tableSource = DataSource.Table.fromTable(FAQTable, {
+  id: "faq_kb",
+
+  // Transform row data into searchable text
+  transform: ({ row }) => {
+    return `Question: ${row.question}
+
+Answer: ${row.answer}
+
+Category: ${row.category}
+Tags: ${row.tags.join(", ")}`;
+  },
+
+  // Optional: Filter rows
+  filter: ({ row }) => {
+    return row.published === true;
+  },
+});
+```
+
+### 4. Multiple Sources
+
+Combine different source types:
+
+```typescript
+export const CombinedKnowledgeBase = new Knowledge({
+  name: "combinedKB",
+  description: "Knowledge from multiple sources",
+  sources: [
+    // Local documentation
+    DataSource.Directory.fromPath("src/knowledge/docs", {
+      id: "local_docs",
+    }),
+
+    // Website documentation
+    DataSource.Website.fromSitemap("https://docs.example.com/sitemap.xml", {
+      id: "online_docs",
+      maxPages: 100,
+    }),
+
+    // FAQ from database
+    DataSource.Table.fromTable(FAQTable, {
+      id: "faq",
+      transform: ({ row }) => `Q: ${row.question}\nA: ${row.answer}`,
+    }),
+  ],
+});
+```
+
+## Using Knowledge Bases
+
+### In Conversations
+
+Provide knowledge bases to AI during execution:
+
+```typescript
+import { Conversation } from "@botpress/runtime";
+import { DocsKnowledgeBase, FAQKnowledgeBase } from "../knowledge";
+
+export const Chat = new Conversation({
+  channel: "chat.channel",
+
+  async handler({ execute }) {
+    await execute({
+      instructions:
+        "You are a helpful assistant. Use the provided knowledge to answer questions accurately.",
+
+      // Add knowledge bases
+      knowledge: [DocsKnowledgeBase, FAQKnowledgeBase],
+
+      // Optional: Add tools that can search knowledge
+      tools: [searchTool],
+    });
+  },
+});
+```
+
+### In Workflows
+
+Knowledge bases work the same in workflows:
+
+```typescript
+import { Workflow } from "@botpress/runtime";
+import { DocsKnowledgeBase } from "../knowledge";
+
+export const ResearchWorkflow = new Workflow({
+  name: "research",
+
+  handler: async ({ input, execute }) => {
+    const result = await execute({
+      instructions: `Research the topic: ${input.topic}`,
+      knowledge: [DocsKnowledgeBase],
+      model: "openai:gpt-4o",
+    });
+
+    return { research: result };
+  },
+});
+```
+
+### Manual Search
+
+Search knowledge bases programmatically:
+
+```typescript
+import { context } from "@botpress/runtime";
+import { DocsKnowledgeBase } from "../knowledge";
+
+export const searchAction = new Action({
+  name: "searchDocs",
+  input: z.object({ query: z.string() }),
+
+  async handler({ input }) {
+    const client = context.get("client");
+
+    // Search knowledge base
+    const { passages } = await client.searchFiles({
+      query: input.query,
+      tags: {
+        source: "knowledge-base",
+        kbName: [DocsKnowledgeBase.name],
+      },
+      limit: 5,
+    });
+
+    return {
+      results: passages.map((p) => ({
+        content: p.content,
+        score: p.score,
+        source: p.file.key,
+      })),
+    };
+  },
+});
+```
+
+## Syncing Knowledge Bases
+
+As of ADK 1.9+, knowledge bases are synced using the `adk kb` command, which runs automatically during `adk dev` and `adk deploy`.
+
+### CLI Sync (Recommended)
+
+```bash
+# Interactive KB management
+adk kb
+
+# Non-interactive sync
+adk kb sync -y
+
+# Check sync status
+adk kb status
+```
+
+The KB sync:
+
+1. Detects all knowledge bases in your project
+2. Identifies sources (directories, websites, tables)
+3. Computes file hashes to detect changes
+4. Syncs only changed content to Botpress Cloud
+5. Handles orphaned sources (sources removed from code)
+
+### Automatic Sync
+
+KB sync runs automatically during:
+
+- `adk dev` - Syncs on startup and file changes
+- `adk deploy` - Syncs before deployment
+
+## Refreshing Knowledge Bases
+
+Refresh knowledge bases programmatically:
+
+```typescript
+// Smart refresh - only changed files (uses SHA256 hashing)
+await MyKnowledgeBase.refresh();
+
+// Force refresh - re-indexes everything
+await MyKnowledgeBase.refresh({ force: true });
+
+// Refresh specific source
+await MyKnowledgeBase.refreshSource("docs");
+```
+
+For scheduled or triggered refresh, use the same refresh methods in workflows, actions, or conversation handlers.
+
+## Citations and References
+
+Track knowledge sources used in responses:
+
+```typescript
+const citations = context.get("citations");
+
+// Register source when using knowledge passage
+const { tag } = citations.registerSource({
+  file: passage.file.key,
+  title: passage.file.tags.title,
+  url: passage.file.tags.url,
+});
+
+// Include citation tag in content
+const citedContent = `<${tag}>${passage.content}</${tag}>`;
+```
+
+For complete citation implementation examples, see the autonomous execution documentation.
+
+## Advanced Patterns
+
+### Dynamic Knowledge Sources
+
+Select knowledge bases based on user context:
+
+```typescript
+// Select knowledge based on user department
+const knowledgeBases = [GeneralKB];
+
+if (user.department === "engineering") {
+  knowledgeBases.push(EngineeringKB, TechnicalDocsKB);
+} else if (user.department === "sales") {
+  knowledgeBases.push(SalesKB, ProductKB);
+}
+
+// Pass to execute()
+await execute({
+  instructions: "Answer based on department-specific knowledge",
+  knowledge: knowledgeBases,
+});
+```
+
+### Content Transformation
+
+Enhance content with metadata before indexing (Table and Website sources support transform):
+
+```typescript
+// Table source with transformation
+const docsTableSource = DataSource.Table.fromTable(DocsTable, {
+  id: "docs_table",
+
+  // Filter specific rows
+  filter: ({ row }) => {
+    return row.status === "published" && !row.deprecated;
+  },
+
+  // Transform row data into searchable text with metadata
+  transform: ({ row }) => {
+    return `
+Title: ${row.title}
+Category: ${row.category}
+Tags: ${row.tags.join(", ")}
+Author: ${row.author}
+
+${row.content}`;
+  },
+});
+```
+
+**Note**: Directory sources only support `filter`, not `transform`. Use Table or Website sources for content transformation.
+
+### Multi-Language Support
+
+Create separate knowledge bases per language:
+
+```typescript
+export const EnglishKB = new Knowledge({
+  name: "englishKB",
+  sources: [DataSource.Directory.fromPath("src/knowledge/en", { id: "docs_en" })],
+});
+
+export const SpanishKB = new Knowledge({
+  name: "spanishKB",
+  sources: [DataSource.Directory.fromPath("src/knowledge/es", { id: "docs_es" })],
+});
+
+// Select based on user language
+const kb = userLanguage === "es" ? SpanishKB : EnglishKB;
+```
+
+## Best Practices
+
+### 1. Organize Content Logically
+
+```
+src/knowledge/
+├── docs/
+│   ├── getting-started/
+│   ├── api-reference/
+│   └── tutorials/
+├── policies/
+│   ├── privacy.md
+│   └── terms.md
+└── faqs/
+    ├── technical.md
+    └── billing.md
+```
+
+### 2. Use Clear Naming
+
+```typescript
+// ✅ Good
+export const TechnicalDocsKB = new Knowledge({ name: "technicalDocs" });
+export const CustomerFAQKB = new Knowledge({ name: "customerFAQ" });
+
+// ❌ Bad
+export const KB1 = new Knowledge({ name: "kb1" });
+export const Stuff = new Knowledge({ name: "stuff" });
+```
+
+### 3. Refresh Frequently-Changing Content
+
+Use `adk kb sync` during development, or call `refresh()` programmatically for dynamic content.
+
+### 4. Structure Content for Search
+
+Add summaries, keywords, and clear headings to improve retrieval quality.
+
+### 5. Monitor Search Performance
+
+Track search metrics (query, result count, duration) to identify slow queries or poor results.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Knowledge not found by AI**
+   - Verify knowledge base is included in `execute()` call
+   - Check that content has been indexed (`refresh()`)
+   - Ensure file types are supported
+
+2. **Poor search results**
+   - Review content structure and formatting
+   - Add metadata and keywords
+   - Adjust the `factor` parameter for ranking
+
+3. **Refresh not working**
+   - Check file permissions
+   - Verify source paths are correct
+   - Look for errors in transform functions
+
+4. **Large files causing issues**
+   - Files are automatically chunked, but very large files may need manual splitting
+   - Consider breaking into smaller documents
+   - Use filtering to exclude unnecessary content

package/dist/llm-debugging-76ng8rzm.md

@@ -0,0 +1,209 @@
+# LLM Behavior Debugging
+
+When the bot's code runs fine but the LLM makes bad decisions — wrong tools, fabricated data, refusals, or loops. These issues live in the model's reasoning, not in your runtime code.
+
+Always use `adk traces --format json` to inspect `think` and `tool_call` spans.
+
+---
+
+## 1. Wrong Tool Selected
+
+**Symptom:** The model picks a different tool than expected for the user's request.
+
+**How to diagnose:**
+
+```bash
+adk traces --format json
+```
+
+1. Find the `think` span before the `tool_call` — this shows the model's reasoning
+2. Compare the tool it chose vs the tool you expected
+3. Read both tools' `description` fields — is the wrong tool's description a better match for the input?
+
+**Common causes:**
+
+- Tool descriptions are too similar or ambiguous
+- The correct tool's description doesn't clearly cover the use case
+- Too many tools available — the model gets confused with a large tool set
+
+**Fixes:**
+
+- **Sharpen descriptions:** Make each tool's purpose unambiguous. Include what the tool does NOT do.
+- **Add negative examples:** "Do NOT use this tool for X — use Y instead."
+- **Reduce tool count:** If tools are rarely used, consider consolidating or removing them
+- **Last resort, use `confirm: true`:** Require user confirmation before executing, giving the user a chance to correct
+
+---
+
+## 2. Hallucinated Parameters
+
+**Symptom:** The model invokes the right tool but fills in parameter values that the user never provided.
+
+**How to diagnose:**
+
+```bash
+adk traces --format json
+```
+
+Check the `tool_call` span's `input` field against what the user actually said.
+
+**Common causes:**
+
+- Input schema is too loose (e.g., free-form `z.string()` where `z.enum()` would be better)
+- No validation in the handler — the hallucinated value passes through
+- The model infers values from context that don't exist
+
+**Fixes:**
+
+- **Tighten input schemas:** Use `z.enum()` for known values, add `.describe()` to clarify what each field expects
+- **Add handler validation:** Check that input values make sense before using them
+- **Last resort, require confirmation:** Set `confirm: true` on the tool so the user sees parameters before execution
+
+---
+
+## 3. Refusal
+
+**Symptom:** The model refuses to perform an action, saying it can't or shouldn't do something.
+
+**How to diagnose:**
+
+```bash
+adk traces --format json
+```
+
+Check `think` spans for safety-related reasoning. The model may cite content policy, uncertainty, or ethical concerns.
+
+**Common causes:**
+
+- The system prompt or instructions don't explicitly authorize the action
+- The tool description sounds potentially harmful or sensitive
+- The user's request is ambiguous and the model errs on the side of caution
+
+**Fixes:**
+
+- **Update instructions:** Explicitly authorize the actions in your conversation's `instructions` field
+- **Soften tool descriptions:** Remove language that sounds risky (e.g., "delete all" → "remove selected")
+- **Check `confirm` settings:** If `confirm: true` is set, the model knows the user will approve — make sure instructions reflect this
+
+---
+
+## 4. Token Limit Issues
+
+**Symptom:** The model's responses are truncated, it loses context from earlier in the conversation, or it starts repeating itself.
+
+**How to diagnose:**
+
+- Long conversations with many turns
+- Large tool outputs filling the context window
+- `adk traces --format json` may show degraded reasoning in later `think` spans
+
+**Common causes:**
+
+- Conversation history is too long — no pruning or summarization
+- Tool outputs are large (e.g., full database dumps, long API responses)
+- Model configuration doesn't match the conversation's needs
+
+**Fixes:**
+
+- **Check model configuration:** Verify model settings in `agent.config.ts` — consider using a model with a larger context window
+- **Trim tool outputs:** Return only what the model needs, not everything
+- **Summarize long conversations:** Use Zai to summarize earlier turns before they fill the window
+- **Use `maxIterations`:** Set a reasonable limit on agent iterations to prevent runaway conversations
+
+---
+
+## 5. Poor Extraction Quality
+
+**Symptom:** Using `adk.zai.extract()` or similar `zai` operations returns incorrect or incomplete structured data.
+
+**Common causes:**
+
+- Schema descriptions are vague — the model doesn't know what each field means
+- Input text is ambiguous or poorly formatted
+- Wrong model for the task — some models extract better than others
+
+**Fixes:**
+
+- **Improve schema descriptions:** Add `.describe()` to every field with clear, specific descriptions
+- **Provide examples:** Show the model what good output looks like
+- **Try a different model:** Some models handle extraction better; check model configuration
+- **Pre-process input:** Clean up or normalize the text before extraction
+- See the **Edge Cases & Gotchas** section in [zai-agent-reference.md](../../adk/references/zai-agent-reference.md) for common pitfalls like hallucinated fields and chunk-window issues
+
+---
+
+## 6. Looping
+
+**Symptom:** The model calls the same tool repeatedly, or cycles between tools without making progress.
+
+**How to diagnose:**
+
+```bash
+adk traces --format json
+```
+
+Look for repeated `tool_call` spans with the same `tool_name` in sequence.
+
+**Common causes:**
+
+- Tool output doesn't clearly indicate success or completion — the model retries
+- Instructions are ambiguous about when to stop
+- The tool fails silently (returns empty/null) and the model keeps trying
+- No iteration limit set
+
+**Fixes:**
+
+- **Improve tool output clarity:** Return clear success/failure messages that tell the model it's done
+- **Add `onBeforeTool` guardrail:** Detect repeated calls and abort
+
+  ```typescript
+  // Create per-conversation to avoid leaking state across turns
+  const makeLoopGuard = () => {
+    const seen = new Set<string>();
+    const onBeforeTool: Autonomous.Hooks["onBeforeTool"] = async ({ tool, input, controller }) => {
+      const key = `${tool.name}:${JSON.stringify(input)}`;
+      if (seen.has(key)) {
+        controller.abort("Already called this tool with these parameters");
+        return;
+      }
+      seen.add(key);
+    };
+    return { onBeforeTool };
+  };
+  ```
+
+- **Set `maxIterations`:** Limit how many tool calls the agent can make per turn
+- **Check instructions:** Add explicit stopping criteria ("after completing X, respond to the user")
+
+---
+
+## 7. Reading Model Reasoning
+
+The `think` span type captures the model's internal reasoning before it acts. This is the most valuable debugging tool for LLM behavior issues.
+
+**How to access:**
+
+```bash
+# Via CLI
+adk traces --format json
+# Look for spans with type "think" — the "content" field has the reasoning
+```
+
+**Via `onTrace` hook in code:**
+
+```typescript
+const onTrace: Autonomous.Hooks["onTrace"] = ({ trace }) => {
+  if (trace.type === "think") {
+    console.debug(`[MODEL REASONING] ${trace.content}`);
+  }
+};
+```
+
+**What to look for:**
+
+- Does the model correctly understand the user's intent?
+- Does it consider the right tools?
+- Does it have accurate context about the conversation state?
+- Is it making assumptions that aren't supported by the input?
+
+If the reasoning is wrong, the fix is usually in the instructions, tool descriptions, or the information available to the model — not in the code.