feat: RAG knowledge base integration for Vix and Karen by deepmasq · Pull Request #254 · smallcloudai/flexus-client-kit

deepmasq · 2026-03-12T04:31:03Z

Summary

Phase 1: Add Knowledge Base RAG instructions to Vix (sales + marketing/default experts) and Karen (default + setup experts) prompts — teaches bots to use flexus_vector_search, get_knowledge, create_knowledge, and flexus_read_original
Phase 4a: Add knowledge_eds_ids setup field to Vix and Karen setup schemas for per-bot knowledge source scoping
Phase 4b: Add setup_after_install() to create a default knowledge EDS on bot install, and "Getting Started with Knowledge Base" prompt sections
Scenario support: ckit_scenario.py gains create_knowledge_eds option for test setup

Files changed (8)

vix_prompts.py, karen_prompts.py — RAG instructions + Getting Started sections
vix_install.py, karen_install.py — setup_after_install() function
setup_schema.json (vix, karen) — knowledge_eds_ids field
ckit_bot_install.py — post_install_create_knowledge_eds() helper
ckit_scenario.py — optional knowledge EDS creation in test setup

Companion PR

Backend: https://github.com/smallcloudai/flexus/pull/1571

Test plan

All Python files parse without syntax errors
Vix and Karen bots use RAG tools in conversations
Setup schema validates with new knowledge_eds_ids field
Full integration test: install bot → create knowledge EDS → upload docs → search

🤖 Generated with Claude Code

deepmasq · 2026-03-12T14:59:18Z

Code Review Fixes Applied (`753cbb6`)

Addressed findings from comprehensive code review across 5 files:

Critical

C4/M6: post_install_create_knowledge_eds now accepts optional persona_id and writes the EDS ID back to persona setup via persona_setup_set_key mutation. This closes the integration gap where knowledge EDS was created but never scoped to the bot.

Medium

M7: Added "no results" fallback guidance to all RAG prompt sections (Vix sales, marketing, nurturing + Karen default). Bots now say "I don't have that information yet" instead of hallucinating.
M8: Added flexus_read_original(doc_path="...") to Vix sales and marketing Knowledge Base sections (was already present in Karen).

Minor

m10: Added basic Knowledge Base section to Vix nurturing prompt (was missing entirely).
Updated setup_after_install in both Vix and Karen to pass persona_id through.

Note on C3 (setup_after_install never called)

The setup_after_install functions are defined but still not wired into the automatic install flow. This requires a backend change to call the post-install hook after bot_install_from_marketplace. For now, the function can be called manually after install, and the persona_id parameter ensures knowledge scoping works when it is called.

deepmasq · 2026-03-13T03:26:33Z

Code Review Fixes — `0801f12`

Addresses findings from the E2E test review:

Issue	Severity	Fix
C2: Knowledge scoping unused	Critical	Write-back `eds_id` to persona setup via `persona_setup_set_key` in post-install
M4: setup_after_install dead code	Major	Added `persona_id` param, documented as manual-use
M5: Missing persona_id in ckit_scenario	Major	Now passes `persona_id=self.persona.persona_id`
M6: Sales bot greeting regression	Major	Separate "Before First Message" section preserves policy doc + product loading

Also: knowledge scoping instructions added to all Vix and Karen expert prompts.

Tested: Full E2E with Whitfield corpus — bot correctly uses flexus_vector_search with scoped eds_id and flexus_read_original for aggregation queries. 100% accuracy across 8 verification questions.

Vix and Karen bots now include detailed instructions for using existing backend RAG cloud tools (flexus_vector_search, get_knowledge, create_knowledge). These tools were already available via the backend's cloud tool discovery but bots lacked prompt guidance on when/how to use them. - Vix: Added Knowledge Base section to sales and marketing/default experts - Karen: Enhanced minimal one-liner into full Knowledge Base section with all 4 RAG tools (search, read_original, get/create knowledge) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Phase 4 additions to RAG integration: - Add knowledge_eds_ids setup field to Vix and Karen setup schemas for per-bot knowledge source scoping - Add post_install_create_knowledge_eds() helper in ckit_bot_install to auto-create a default knowledge EDS on bot install - Add setup_after_install() to vix_install and karen_install - Add "Getting Started with Knowledge Base" prompt sections that guide users to upload docs, crawl websites, or teach the bot facts - Update ckit_scenario to optionally create knowledge EDS in test setup Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

When a cloudtool handler crashes, the error message was posted as a raw string but cloudtool_post_result expects JSON-encoded content (ftm_content is jsonb). This caused the error posting to also fail, leaving threads permanently stuck with no tool result. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- ckit_bot_install: post_install_create_knowledge_eds now writes eds_id back to persona setup via persona_setup_set_key, so vector search is automatically scoped to the bot's knowledge base - vix/karen install: pass persona_id through setup_after_install - vix prompts: add flexus_read_original to sales and marketing Knowledge Base sections, add "no results" fallback guidance to all three experts (sales, marketing, nurturing) - karen prompts: add "no results" fallback guidance Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- C2: Wire knowledge_eds_ids write-back into post-install flow (ckit_bot_install passes persona_id, writes eds_id to persona setup) - M4: Add persona_id parameter to setup_after_install in vix/karen with documentation that it must be called manually - M5: Pass persona_id in ckit_scenario post-install flow - M6: Preserve sales bot greeting context loading (separate "Before First Message" section for policy docs + products) while adding vector search for subsequent messages - Add knowledge scoping instructions to all Vix and Karen expert prompts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Auto-creating a knowledge EDS during bot install is too specific and unreliable. Users can set knowledge_eds_ids manually in persona setup when they want to scope vector search to specific data sources. Removes: - post_install_create_knowledge_eds from ckit_bot_install - setup_after_install from vix_install and karen_install - create_knowledge_eds parameter from ckit_scenario Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Inline "Getting Started" sections were duplicated across 5 prompt locations (Vix sales/marketing, Karen support/setup). Extracted to shared_skills/setting-up-external-knowledge-base/SKILL.md so bots fetch it on-demand instead of carrying it in every prompt. Updated Karen allowlist to include the shared skill. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove explicit tool call signatures from Knowledge Base sections. The LLM sees tool definitions at runtime — prescriptive call instructions are redundant and fragile. Keep behavioral guidance (search before answering, cite sources, don't fabricate) and knowledge scoping (knowledge_eds_ids). Addresses feedback: "actions are too specific and unreliable / unnecessary, Karen can use MCP for answers" Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

olegklimov · 2026-03-16T14:21:52Z

+If the user wants to add content from a website:
+
+```python
+crawl_website(url="https://example.com", depth=1, eds_name="Example Docs", rescan_period=86400)


eds_setup(op=help, args={"eds_type":"Web Crawler"})
eds_setup(op=create, args={"eds_name":"Claude Docs","eds_typ…)

olegklimov · 2026-03-16T14:22:12Z

+Users can upload PDFs, text files, Word documents, or other files through the Flexus web UI:
+
+1. Go to the bot's group page in Flexus
+2. Click the file upload area or drag files in


"Upload Documents" button

Address review feedback: - Replace crawl_website() with eds_setup() tool calls in shared skill - Fix UI instruction: "Upload Documents" button (not "file upload area") Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

humbertoyusta · 2026-03-17T10:10:53Z

+
+Search the knowledge base when you need specific company facts (e.g., product details for email personalization). If no results, use only policy documents and CRM data -- do not fabricate.
+
+If `knowledge_eds_ids` is set in your setup, pass it as `eds_id` to scope searches. If empty, search all workspace data sources.


Pass it as scopes

humbertoyusta · 2026-03-17T10:11:13Z

-```
+If search returns no results, do NOT guess or fabricate. Suggest uploading relevant docs or teaching you the fact.
+
+If `knowledge_eds_ids` is set in your setup, pass it as `eds_id` to scope searches. If empty, search all workspace data sources. If the knowledge base is empty, fetch the `setting-up-external-knowledge-base` skill.


pass it as scopes

humbertoyusta · 2026-03-17T10:20:13Z

+## Before Your First Message (Greeting)
+Before your first response in a new conversation:
+1. Load company context from policy documents (/company/summary, /company/sales-strategy)
+2. Load products from com_product table


We're removing always loading products, unless the model thinks it should based on user request

- Change knowledge_eds_ids parameter from `eds_id` to `scopes` in all vix prompts (sales, marketing, nurturing) and karen prompts - Sales bot: only load products on greeting when user's message relates to products/pricing, instead of always loading them Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

deepmasq changed the title ~~Add RAG Knowledge Base instructions to Vix and Karen prompts~~ feat: RAG knowledge base integration for Vix and Karen Mar 12, 2026

deepmasq requested a review from humbertoyusta March 12, 2026 11:41

Art Koval and others added 8 commits March 16, 2026 10:33

deepmasq force-pushed the feat/rag-prompts-vix-karen branch from 828f176 to ec21b35 Compare March 16, 2026 07:34

olegklimov reviewed Mar 16, 2026

View reviewed changes

humbertoyusta reviewed Mar 17, 2026

View reviewed changes

humbertoyusta approved these changes Mar 17, 2026

View reviewed changes

olegklimov merged commit 2ced772 into main Mar 23, 2026

olegklimov deleted the feat/rag-prompts-vix-karen branch March 23, 2026 11:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: RAG knowledge base integration for Vix and Karen#254

feat: RAG knowledge base integration for Vix and Karen#254
olegklimov merged 10 commits intomainfrom
feat/rag-prompts-vix-karen

deepmasq commented Mar 12, 2026 •

edited

Loading

Uh oh!

deepmasq commented Mar 12, 2026

Uh oh!

deepmasq commented Mar 13, 2026

Uh oh!

olegklimov Mar 16, 2026

Uh oh!

olegklimov Mar 16, 2026

Uh oh!

humbertoyusta Mar 17, 2026

Uh oh!

humbertoyusta Mar 17, 2026

Uh oh!

humbertoyusta Mar 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Search the knowledge base when you need specific company facts (e.g., product details for email personalization). If no results, use only policy documents and CRM data -- do not fabricate.

		If `knowledge_eds_ids` is set in your setup, pass it as `eds_id` to scope searches. If empty, search all workspace data sources.

Conversation

deepmasq commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Files changed (8)

Companion PR

Test plan

Uh oh!

deepmasq commented Mar 12, 2026

Code Review Fixes Applied (753cbb6)

Critical

Medium

Minor

Note on C3 (setup_after_install never called)

Uh oh!

deepmasq commented Mar 13, 2026

Code Review Fixes — 0801f12

Uh oh!

olegklimov Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

olegklimov Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

humbertoyusta Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

humbertoyusta Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

humbertoyusta Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

deepmasq commented Mar 12, 2026 •

edited

Loading

Code Review Fixes Applied (`753cbb6`)

Code Review Fixes — `0801f12`