Docs/knowledge demo example

[dolev31]

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.md and the root README.md under 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.md
• health_insurance_plan.md
• pto_policy.md
• 401k_plan.md

Session-level documents

Ephemeral, per-conversation documents for a single employee, Sarah Chen:

• benefits_enrollment.md
• pto_balance.md
• march_2026_pay_stub.md

All 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:

• upload agent-level docs through the manage page
• publish the agent
• attach session-level docs in chat
• run demo prompts that require cross-scope reasoning

Demo prompts included

The example README.md includes 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:

• path dependency on the root cuga
• shared lockfile usage
• .env.example
• uv run --project ../../../ main.py

Bug fix included

Problem

KnowledgeClient.get_langchain_tools() generated 7 tool wrapper functions whose signatures did not accept a thread_id keyword argument.

At runtime, cuga_lite_graph.py injects thread_id, which caused SDK-mode calls to agent.invoke() with knowledge enabled to crash with:

TypeError: knowledge_search_knowledge() got an unexpected keyword argument 'thread_id'

[sami-marreed]

Merge main and resolve conflicts (blocking)

Please merge or rebase onto the current main, resolve conflicts (this branch has historically overlapped .gitignore, pyproject.toml, cuga_lite_graph.py, client.py, lockfiles, etc.), then push so the PR is mergeable and CI reflects an integrated tree. GitHub currently shows the branch as conflicting with main.

---

Trim unrelated churn (high priority)

• pyproject.toml adds openlit>=1.40.1 to the core dependencies list. On main, OpenLit is already handled via optional observability / overrides — this looks out of scope for a docs + knowledge-tool wrapper fix. Unless there is an explicit decision to make OpenLit a default dependency, drop this hunk (or split to a separate PR with rationale).

• src/cuga/frontend/dist/main.*.js (~1 MB bundle) appears in the branch diff vs main. A knowledge demo + KnowledgeClient fix should normally not rebuild/commit frontend artifacts unless something here truly requires it — please remove unless tied to a concrete UI change for this PR.

• .gitignore adds docs/examples/demo_apps/file_system/build/ alongside demo_knowledge_docs/. The demo_apps path looks unrelated to the knowledge demo — consider dropping it or moving it to a separate maintenance PR.

• cuga_lite_graph.py diff vs main is only extra blank lines. Please revert that noise so history stays clean.

---

Code fix (KnowledgeClient.get_langchain_tools)

Adding **_: Any (with the NOTE comment) so injected kwargs like thread_id do not raise TypeError matches the described SDK/runtime mismatch — sensible given schema stability concerns.

---

Docs example

The docs/examples/knowledge_demo/ layout (agent vs session docs, dual paths SDK/UI, .env.example explaining Dynaconf) aligns well with the stated goals; once conflicts and unrelated files are cleaned up, this part should be straightforward to land.