Docs/knowledge demo example#156
Conversation
Replace OpenRAG with a built-in knowledge engine supporting: - Vector store abstraction (SQLite default, Milvus, PGVector) - Docling document parsing (PDF, DOCX, HTML, etc.) - Session-scoped and agent-scoped document management - Knowledge MCP server, REST routes, and frontend panels - Configurable RAG profiles (speed/standard/balanced/max_quality) - Backward-compatible deprecation of OpenRAGClient Includes rebuilt frontend bundles reflecting knowledge UI additions.
Merge main into knowledge feature branch to incorporate: - Out-of-the-box agents (demo_docs, demo_health, oak_health) - Authorization flow improvements - Agent name customization - FastMCP security bump - Docker/deployment updates - Frontend dist relocation to src/cuga/frontend/dist Knowledge features preserved and integrated with new demo presets.
…eddings sentence-transformers/torch were removed from the project in favor of fastembed. Switch knowledge engine to FastEmbedEmbeddings to match.
…he with policies Replace langchain-community FastEmbedEmbeddings with a thin adapter that uses fastembed.TextEmbedding directly and reuses the model cache from embedding_service. Keeps langchain-community for SQLiteVec and Ollama.
…ai/ollama) - fastembed: default, uses fastembed.TextEmbedding directly - openai: requires api_key (config or env), supports custom base_url - ollama: supports custom base_url, defaults to localhost:11434 - Remove huggingface as provider (auto-migrated to fastembed) - Add api_key and base_url config fields for embeddings - Clear error messages when config is missing
…i, ollama Four distinct providers, each logically correct: - fastembed: default, lightweight local embeddings (installed with cuga) - huggingface: sentence-transformers (optional dep, clear install instructions) - openai: API-based, requires api_key config or OPENAI_API_KEY env var - ollama: local server, configurable base_url
Create the converter once (lazy) and pass it to DoclingLoader, avoiding model weight reloads on every document ingestion.
…d, knowledge agent ID - Replace Debug (bug) icon with Settings icon for Configuration section - Fix conversation history not loading when clicking previous sessions (pass selectedThreadId to CarbonChat so threadId changes trigger history reload, and keep isReadonly=true so homescreen doesn't override loaded history) - Fix knowledge documents not showing (setKnowledgeAgentId was using display name instead of actual agent ID) - Fix "body stream already read" error (manageRes.json() was called twice) - Restyle right panel section switcher with grounded tab-strip borders
…ead of ~/.cuga/ Move vector DB, metadata, uploaded files, session state, and auth token from ~/.cuga/ (shared home dir) to <cwd>/.cuga/ (per-project isolation), matching how policies already use <cwd>/.cuga/. Also fix test_defaults assertion for embedding_provider (fastembed not auto).
…gine start - Add `cuga start demo_knowledge` CLI mode (knowledge enabled from startup) - Add `cuga start demo_knowledge --reset` to wipe all knowledge data - Add `cuga stop demo_knowledge` handler - Default knowledge to disabled (knowledge_settings.toml, KnowledgeConfig dataclass) - Knowledge engine can be started on-demand via POST /api/knowledge/enable (called when user toggles knowledge ON in the manage UI) - Extract initialize_knowledge_engine() as reusable async function on app_state (full init: engine + session provider + MCP server + token + warmup) - Fix demo restart bug: no longer wipes knowledge data on every demo start (only wipes when --reset explicitly passed) - Fix reset: delete WAL sidecar files, check flock before deleting, log warnings instead of silently swallowing errors - Warn when --reset passed to non-knowledge demos - Fix Dynaconf caching: force enabled=true in saved config for demo_knowledge (env var set after settings import is not picked up by Dynaconf cache)
…agent into feat/knowledge-engine
[skip ci]
[skip ci]
# Conflicts: # .gitignore # .secrets.baseline # pyproject.toml # src/cuga/backend/cuga_graph/nodes/chat/chat_agent/chat_agent.py # src/cuga/backend/cuga_graph/nodes/cuga_lite/cuga_lite_graph.py # src/cuga/config.py # src/cuga/frontend/dist/index.html # uv.lock
Adds a new example under docs/examples/knowledge_demo/ that demonstrates the knowledge engine end-to-end with an HR Benefits Assistant scenario: - 4 agent-level sample docs (handbook, health plan, PTO, 401(k)) - 3 session-level sample docs (one employee's enrollment, PTO balance, pay stub) that exercise cross-scope RAG reasoning - main.py showing the programmatic SDK surface (agent.knowledge.ingest/search + agent.invoke) - README covering both Path A (SDK) and Path B (cuga start demo_knowledge) - pyproject.toml + .python-version + .env.example matching the cuga_as_mcp / cuga_with_runtime_tools example convention Also fixes a blocking bug in src/cuga/backend/knowledge/client.py: get_langchain_tools() generated tool functions that didn't accept the `thread_id` kwarg that cuga_lite_graph injects at runtime, which made any SDK-mode knowledge use via agent.invoke() crash with TypeError. Adding **_ to the 7 tool wrappers absorbs the injected kwarg while keeping the JSON schema (and thus the LLM-facing API) unchanged. Root README.md gets two new links to the example (Knowledge Base section + Additional Resources list). .gitignore adds the local-only demo_knowledge_docs/ scratch folder. Verified end-to-end: - 69/69 knowledge unit tests pass - Path A clean run answers "40 hours (5 days)" for PTO carryover, session search returns sarah_chen_pto_balance.md as top hit - Path B: cuga start demo_knowledge boots, /api/knowledge/health reports healthy+ready, HTTP upload + search both succeed
Merge
|
…xample # Conflicts: # .gitignore # src/cuga/backend/cuga_graph/nodes/cuga_lite/cuga_lite_graph.py
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThis PR adds a runnable HR Benefits Assistant knowledge-engine demo to ChangesKnowledge Demo: HR Benefits Assistant
Estimated Code Review Effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/cuga/backend/knowledge/client.py (1)
1-1:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRun
ruff formatto fix the formatting issue.The pipeline failure indicates this file needs formatting. Run
ruff format src/cuga/backend/knowledge/client.pyto resolve the issue.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/cuga/backend/knowledge/client.py` at line 1, Run the code formatter on the impacted module to fix styling errors: execute `ruff format src/cuga/backend/knowledge/client.py`, review the resulting changes in src/cuga/backend/knowledge/client.py, and commit the formatted file so the pipeline passes; if you prefer, add ruff to pre-commit to prevent future failures.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.gitignore:
- Line 91: Remove the unrelated .gitignore entry for
"docs/examples/demo_apps/file_system/build/" (it does not belong to the
knowledge demo changes); either delete that line from .gitignore or move it into
a separate maintenance PR so only files related to
"docs/examples/knowledge_demo/" remain in this PR.
- Around line 100-101: Remove the stale .gitignore entry "demo_knowledge_docs/"
since the project uses "docs/examples/knowledge_demo/" for the knowledge demo;
edit the .gitignore and delete the line containing demo_knowledge_docs/ so it no
longer ignores that directory name.
In `@docs/examples/knowledge_demo/main.py`:
- Line 1: Run the Python formatter ruff on the example to fix the formatting
issues: execute the command suggested (ruff format
docs/examples/knowledge_demo/main.py) or run ruff format on the repository/that
file, then stage the formatted changes; this will correct the formatting problem
reported by the pipeline.
In
`@docs/examples/knowledge_demo/sample_data/session_level/sarah_chen_benefits_enrollment.md`:
- Line 50: Update the vesting sentence for past-tense consistency: locate the
"Vesting Status:" line (the sentence starting "reaches 3-year cliff on
2025-03-14") and change "reaches" to "reached" so it reads that the 3-year cliff
was reached on 2025-03-14, matching the NOTE that the cliff is already past and
employer match is 100% vested.
In
`@docs/examples/knowledge_demo/sample_data/session_level/sarah_chen_pto_balance.md`:
- Line 14: The PTO used year-to-date value in the table row "| PTO used
year-to-date | 32.00 | 4.00 |" is inconsistent with the usage history (total
40.00 hours); update that row to 40.00 (5.00 days) and then recalculate and
update the related "current balance" values accordingly (use accrual 53.33 +
carried 40.00 - used 40.00 = 53.33 hours). Also apply the same corrections to
the other occurrences referenced in the comment (the block covering the repeated
summary lines around the same table) so all instances match the corrected 40.00
used and recalculated balance.
- Line 22: Update the "Projected end-of-year balance if no further PTO is used"
line (the text starting "Projected end-of-year balance if no further PTO is
used: **...**") to reflect the correct math: use Carryover 40 + Annual accrual
160 − Used YTD 32 = 168 hours (21 days); if you adopt Used YTD = 40 then show
160 hours (20 days); ensure the displayed hours and days match the chosen used
value and the inline calculation in the markdown is adjusted accordingly.
- Line 6: The displayed tenure line "**Tenure:** 3 years, 11 months (hire date:
March 14, 2022)" is wrong; update it to reflect the correct tenure of "4 years,
1 month (hire date: March 14, 2022)" and then review any derived values that
depend on tenure (accrual bracket logic or summary lines in this document) to
ensure those values are updated consistently; locate the tenure string in the
file (the "**Tenure:** ..." line) and adjust the text and any related accrual
descriptions accordingly.
- Around line 43-45: Update the recommendation narrative in the session_level
PTO markdown so the usage and projection reflect 40 hours used in 4 months:
change "32 hours used in 4 months" to "40 hours used in 4 months" and update the
projected annual pace from "96 hours (12 days)" to "120 hours (15 days)"; ensure
the surrounding sentence about exceeding the 40-hour carryover cap still reads
correctly given the new projection.
In `@pyproject.toml`:
- Line 49: Remove the unrelated core dependency addition "openlit>=1.40.1" from
pyproject.toml: revert the change that adds that package to the main
dependencies and either drop it entirely (since observability extra already
requires openlit>=1.40.3) or move it into the observability extra with the
correct minimum version (>=1.40.3) in a separate PR with justification; ensure
no other code references assume openlit is a core dependency.
---
Outside diff comments:
In `@src/cuga/backend/knowledge/client.py`:
- Line 1: Run the code formatter on the impacted module to fix styling errors:
execute `ruff format src/cuga/backend/knowledge/client.py`, review the resulting
changes in src/cuga/backend/knowledge/client.py, and commit the formatted file
so the pipeline passes; if you prefer, add ruff to pre-commit to prevent future
failures.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 89a0a67d-5161-46b2-9806-4aa325ec9580
⛔ Files ignored due to path filters (1)
src/cuga/frontend/dist/main.d324b2cb4c846b9d6a2c.jsis excluded by!**/dist/**
📒 Files selected for processing (16)
.gitignoreREADME.mddocs/examples/knowledge_demo/.env.exampledocs/examples/knowledge_demo/.python-versiondocs/examples/knowledge_demo/README.mddocs/examples/knowledge_demo/main.pydocs/examples/knowledge_demo/pyproject.tomldocs/examples/knowledge_demo/sample_data/agent_level/01_employee_handbook.mddocs/examples/knowledge_demo/sample_data/agent_level/02_health_insurance_plan.mddocs/examples/knowledge_demo/sample_data/agent_level/03_pto_policy.mddocs/examples/knowledge_demo/sample_data/agent_level/04_retirement_401k_plan.mddocs/examples/knowledge_demo/sample_data/session_level/sarah_chen_benefits_enrollment.mddocs/examples/knowledge_demo/sample_data/session_level/sarah_chen_paystub_march_2026.mddocs/examples/knowledge_demo/sample_data/session_level/sarah_chen_pto_balance.mdpyproject.tomlsrc/cuga/backend/knowledge/client.py
| deployment/helm/*.env | ||
| !deployment/helm/openshift.example.env | ||
| KNOWLEDGE_PIPELINE.md | ||
| docs/examples/demo_apps/file_system/build/ |
There was a problem hiding this comment.
Revert unrelated .gitignore entry.
The reviewer identified this line as unrelated to the knowledge demo PR. The path docs/examples/demo_apps/file_system/build/ does not match the new demo at docs/examples/knowledge_demo/ and should be dropped or moved to a separate maintenance PR.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.gitignore at line 91, Remove the unrelated .gitignore entry for
"docs/examples/demo_apps/file_system/build/" (it does not belong to the
knowledge demo changes); either delete that line from .gitignore or move it into
a separate maintenance PR so only files related to
"docs/examples/knowledge_demo/" remain in this PR.
| # Knowledge demo docs (local only) | ||
| demo_knowledge_docs/ |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for references to demo_knowledge_docs
rg -n 'demo_knowledge_docs' --type-add 'config:*.{toml,yaml,yml,json}' --type config --type py --type mdRepository: cuga-project/cuga-agent
Length of output: 49
🏁 Script executed:
#!/bin/bash
# Broader search for demo_knowledge_docs in all files
rg -n 'demo_knowledge_docs' --no-headingRepository: cuga-project/cuga-agent
Length of output: 49
🏁 Script executed:
#!/bin/bash
# Check if README exists and search for demo-related content
if [ -f "README.md" ]; then
echo "=== README.md content related to demo ==="
cat README.md | grep -i demo -C 3
fiRepository: cuga-project/cuga-agent
Length of output: 8263
🏁 Script executed:
#!/bin/bash
# Check for shell scripts that might create demo_knowledge_docs
find . -name "*.sh" -type f | head -20Repository: cuga-project/cuga-agent
Length of output: 767
🏁 Script executed:
#!/bin/bash
# Check the .gitignore file itself to see context around line 100-101
if [ -f ".gitignore" ]; then
echo "=== .gitignore around lines 100-101 ==="
sed -n '95,105p' .gitignore
fiRepository: cuga-project/cuga-agent
Length of output: 403
Remove the demo_knowledge_docs/ entry from .gitignore.
The directory demo_knowledge_docs/ is not referenced anywhere in the codebase. The actual knowledge demo uses docs/examples/knowledge_demo/ as documented in the README (cuga start demo_knowledge). This .gitignore entry appears to be a leftover from an earlier iteration and should be removed.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.gitignore around lines 100 - 101, Remove the stale .gitignore entry
"demo_knowledge_docs/" since the project uses "docs/examples/knowledge_demo/"
for the knowledge demo; edit the .gitignore and delete the line containing
demo_knowledge_docs/ so it no longer ignores that directory name.
|
|
||
| **Traditional 401(k) Contribution:** 8% of eligible compensation | ||
| **Roth 401(k) Contribution:** 0% | ||
| **Vesting Status:** Not yet fully vested — reaches 3-year cliff on 2025-03-14. **NOTE:** already past cliff; employer match is 100% vested as of March 14, 2025. |
There was a problem hiding this comment.
Fix past-tense inconsistency in vesting note.
The text says "reaches 3-year cliff on 2025-03-14" but the context date is April 2026, so the cliff was reached in the past. Change "reaches" to "reached" for consistency with the NOTE that says "already past cliff."
📝 Proposed fix
-**Vesting Status:** Not yet fully vested — reaches 3-year cliff on 2025-03-14. **NOTE:** already past cliff; employer match is 100% vested as of March 14, 2025.
+**Vesting Status:** Fully vested — reached 3-year cliff on March 14, 2025. Employer match is 100% vested as of March 14, 2025.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **Vesting Status:** Not yet fully vested — reaches 3-year cliff on 2025-03-14. **NOTE:** already past cliff; employer match is 100% vested as of March 14, 2025. | |
| **Vesting Status:** Fully vested — reached 3-year cliff on March 14, 2025. Employer match is 100% vested as of March 14, 2025. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/examples/knowledge_demo/sample_data/session_level/sarah_chen_benefits_enrollment.md`
at line 50, Update the vesting sentence for past-tense consistency: locate the
"Vesting Status:" line (the sentence starting "reaches 3-year cliff on
2025-03-14") and change "reaches" to "reached" so it reads that the 3-year cliff
was reached on 2025-03-14, matching the NOTE that the cliff is already past and
employer match is 100% vested.
| **Employee:** Sarah Chen | ||
| **Employee ID:** E-48271 | ||
| **Report Date:** April 10, 2026 | ||
| **Tenure:** 3 years, 11 months (hire date: March 14, 2022) |
There was a problem hiding this comment.
Tenure calculation is incorrect.
The hire date is March 14, 2022, and the report date is April 10, 2026. The time elapsed is approximately 4 years and 1 month, not 3 years and 11 months as stated. This error propagates into the accrual bracket logic and could cause confusion during the demo.
📅 Proposed fix
-**Tenure:** 3 years, 11 months (hire date: March 14, 2022)
+**Tenure:** 4 years, 1 month (hire date: March 14, 2022)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **Tenure:** 3 years, 11 months (hire date: March 14, 2022) | |
| **Tenure:** 4 years, 1 month (hire date: March 14, 2022) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/examples/knowledge_demo/sample_data/session_level/sarah_chen_pto_balance.md`
at line 6, The displayed tenure line "**Tenure:** 3 years, 11 months (hire date:
March 14, 2022)" is wrong; update it to reflect the correct tenure of "4 years,
1 month (hire date: March 14, 2022)" and then review any derived values that
depend on tenure (accrual bracket logic or summary lines in this document) to
ensure those values are updated consistently; locate the tenure string in the
file (the "**Tenure:** ..." line) and adjust the text and any related accrual
descriptions accordingly.
| |---|---|---| | ||
| | PTO accrued year-to-date (Jan–Apr) | 53.33 | 6.67 | | ||
| | PTO carried over from 2025 | 40.00 | 5.00 | | ||
| | PTO used year-to-date | 32.00 | 4.00 | |
There was a problem hiding this comment.
PTO used year-to-date does not match the usage history.
Line 14 states 32.00 hours (4.00 days) used year-to-date, but the usage history table shows:
- Jan 19-20: 2 days = 16 hours
- Feb 13: 1 day = 8 hours
- Mar 30-31: 2 days = 16 hours
- Total: 5 days = 40 hours
This 8-hour discrepancy will cause the current PTO balance calculation to be incorrect and lead to inconsistent agent responses when queried about Sarah's PTO usage.
🔢 Proposed fix
Update the used YTD to match the usage history:
-| PTO used year-to-date | 32.00 | 4.00 |
+| PTO used year-to-date | 40.00 | 5.00 |And recalculate the current balance:
-| **Current PTO balance** | **61.33** | **7.67** |
+| **Current PTO balance** | **53.33** | **6.67** |(Calculation: 53.33 accrued + 40.00 carried over - 40.00 used = 53.33 hours)
Also applies to: 29-33
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/examples/knowledge_demo/sample_data/session_level/sarah_chen_pto_balance.md`
at line 14, The PTO used year-to-date value in the table row "| PTO used
year-to-date | 32.00 | 4.00 |" is inconsistent with the usage history (total
40.00 hours); update that row to 40.00 (5.00 days) and then recalculate and
update the related "current balance" values accordingly (use accrual 53.33 +
carried 40.00 - used 40.00 = 53.33 hours). Also apply the same corrections to
the other occurrences referenced in the comment (the block covering the repeated
summary lines around the same table) so all instances match the corrected 40.00
used and recalculated balance.
| Based on tenure (3–5 years bracket): **13.33 hours per month** (160 hours / 20 days annually) | ||
|
|
||
| Next accrual: April 30, 2026 (+13.33 hours) | ||
| Projected end-of-year balance if no further PTO is used: **181.33 hours (22.67 days)** |
There was a problem hiding this comment.
Projected end-of-year balance calculation appears incorrect.
The projected balance of 181.33 hours does not align with the stated accrual rate and usage:
- Carryover from 2025: 40 hours
- Annual accrual (12 months × 13.33): 160 hours
- Used YTD: 32 hours (or 40 hours per usage history)
- Expected projection (no further use): 40 + 160 - 32 = 168 hours (or 160 hours if using 40)
The stated 181.33 hours is approximately 13-21 hours too high, which will mislead demo users about carryover risk.
🧮 Proposed fix
Assuming the corrected used amount is 40 hours:
-Projected end-of-year balance if no further PTO is used: **181.33 hours (22.67 days)**
+Projected end-of-year balance if no further PTO is used: **160.00 hours (20.00 days)**📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Projected end-of-year balance if no further PTO is used: **181.33 hours (22.67 days)** | |
| Projected end-of-year balance if no further PTO is used: **160.00 hours (20.00 days)** |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/examples/knowledge_demo/sample_data/session_level/sarah_chen_pto_balance.md`
at line 22, Update the "Projected end-of-year balance if no further PTO is used"
line (the text starting "Projected end-of-year balance if no further PTO is
used: **...**") to reflect the correct math: use Carryover 40 + Annual accrual
160 − Used YTD 32 = 168 hours (21 days); if you adopt Used YTD = 40 then show
160 hours (20 days); ensure the displayed hours and days match the chosen used
value and the inline calculation in the markdown is adjusted accordingly.
| At current pace (32 hours used in 4 months), Sarah is on track to use approximately | ||
| 96 hours (12 days) of PTO in 2026. She will still exceed the 40-hour carryover cap | ||
| at year-end unless she plans additional time off. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win
Recommendation narrative is inconsistent with corrected usage data.
If the PTO used YTD is corrected to 40 hours (5 days) instead of 32 hours, the pace calculation and recommendation should be updated accordingly. Currently it states "32 hours used in 4 months" and projects 96 hours (12 days) annually, which would be low.
📝 Proposed fix
-At current pace (32 hours used in 4 months), Sarah is on track to use approximately
-96 hours (12 days) of PTO in 2026. She will still exceed the 40-hour carryover cap
-at year-end unless she plans additional time off.
+At current pace (40 hours used in 4 months), Sarah is on track to use approximately
+120 hours (15 days) of PTO in 2026. She will still exceed the 40-hour carryover cap
+at year-end unless she plans additional time off.(Calculation: 40 hours in 4 months × 12 months / 4 months = 120 hours = 15 days)
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| At current pace (32 hours used in 4 months), Sarah is on track to use approximately | |
| 96 hours (12 days) of PTO in 2026. She will still exceed the 40-hour carryover cap | |
| at year-end unless she plans additional time off. | |
| At current pace (40 hours used in 4 months), Sarah is on track to use approximately | |
| 120 hours (15 days) of PTO in 2026. She will still exceed the 40-hour carryover cap | |
| at year-end unless she plans additional time off. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/examples/knowledge_demo/sample_data/session_level/sarah_chen_pto_balance.md`
around lines 43 - 45, Update the recommendation narrative in the session_level
PTO markdown so the usage and projection reflect 40 hours used in 4 months:
change "32 hours used in 4 months" to "40 hours used in 4 months" and update the
projected annual pace from "96 hours (12 days)" to "120 hours (15 days)"; ensure
the surrounding sentence about exceeding the 40-hour carryover cap still reads
correctly given the new projection.
| "cryptography>=46.0.7", | ||
| "hvac>=2.0.0", | ||
| "boto3>=1.34.0", | ||
| "openlit>=1.40.1", |
There was a problem hiding this comment.
Remove unrelated dependency addition.
The reviewer explicitly flagged this change: openlit>=1.40.1 is being added to core dependencies, but on main it is handled optionally via the observability extra (which already requires >=1.40.3). This change is unrelated to the knowledge demo and should be dropped or moved to a separate PR with clear rationale for why OpenLit must become a core dependency.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pyproject.toml` at line 49, Remove the unrelated core dependency addition
"openlit>=1.40.1" from pyproject.toml: revert the change that adds that package
to the main dependencies and either drop it entirely (since observability extra
already requires openlit>=1.40.3) or move it into the observability extra with
the correct minimum version (>=1.40.3) in a separate PR with justification;
ensure no other code references assume openlit is a core dependency.
…tures - Add Knowledge (RAG) row to the "Why CUGA?" capabilities table, matching the brief mechanism · pointers style of neighboring rows - Add a Knowledge engine bullet under Key Features & Capabilities that calls out Docling-backed ingestion and the two scopes: agent-level (permanent) and session-level (per-thread)
2 participants
Summary
This PR adds a new hands-on example under
docs/examples/knowledge_demo/that demonstrates CUGA's knowledge engine end to end through a realistic HR Benefits Assistant scenario.It also fixes a blocking bug that prevented knowledge usage in SDK mode.
Why
The repo already documents the knowledge engine at a reference level in
KNOWLEDGE_PIPELINE.mdand the rootREADME.mdunder the Knowledge Base section, but it does not include a walkable example that shows the difference between agent-level and session-level knowledge in practice.That distinction is one of the most compelling parts of the feature, yet developers browsing
docs/examples/did not have a concrete example they could copy when integrating knowledge into their own agents.What is included
This PR adds a fictional HR Benefits Assistant for Acme Corp.
Agent-level documents
Persistent, shared across conversations:
employee_handbook.mdhealth_insurance_plan.mdpto_policy.md401k_plan.mdSession-level documents
Ephemeral, per-conversation documents for a single employee, Sarah Chen:
benefits_enrollment.mdpto_balance.mdmarch_2026_pay_stub.mdAll numbers in the example, including IRS limits, accrual rates, and premiums, are realistic for 2026 so the agent's answers are easy to verify.
Integration paths shown in the example
Both paths are documented in the example
README.md.Path A: SDK (
main.py)Demonstrates the full programmatic surface using:
CugaAgent(enable_knowledge=True)agent.knowledge.ingest(...)agent.knowledge.search(...)agent.invoke(...)Path B: UI (
cuga start demo_knowledge)Demonstrates the UI flow:
Demo prompts included
The example
README.mdincludes prompts that exercise different retrieval scopes:"What's the vacation carryover limit?"Agent-level only
"How many PTO days do I have left?"Session-level only
"Based on my pay stub and HSA enrollment, am I on track to max out my HSA?"Combines agent-level IRS limit and employer contribution rules with Sarah's YTD payroll deductions
"Will I have enough PTO for a 10-day July vacation?"Combines policy with Sarah's personal balance and accrual rate
Conventions
The example follows the same conventions as:
docs/examples/cuga_as_mcp/docs/examples/cuga_with_runtime_tools/Specifically:
cuga.env.exampleuv run --project ../../../ main.pyBug fix included
Problem
KnowledgeClient.get_langchain_tools()generated 7 tool wrapper functions whose signatures did not accept athread_idkeyword argument.At runtime,
cuga_lite_graph.pyinjectsthread_id, which caused SDK-mode calls toagent.invoke()with knowledge enabled to crash with: