✨ feat(web): improve deep research report rendering

[LinMoQC]

• Render [证据：强/中/弱] as styled color-coded badges via token pre-processing
• Add Mermaid diagram support in document viewer
• Hide "all sources" section when citation table is present
• Adjust evidence badge sizing for better readability

Made-with: Cursor

Summary

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactor / code cleanup
• CI / tooling

Related issue

Closes #

Changes

How to test

Screenshots (if applicable)

Checklist

• My code follows the project's coding conventions
• I have run ./lyra lint and there are no type errors
• I have added/updated tests for the changed functionality
• I have updated the documentation if behavior changed
• The PR title follows Conventional Commits format (feat:, fix:, etc.)
• I have read the CONTRIBUTING.md

Summary by CodeRabbit

• New Features

  • Deep research clarifying questions and UI flow
  • LiteLLM provider support and selectable LLM provider
  • Separate embedding and reranker configuration + test endpoints
  • Mermaid diagram rendering and evidence badges in reports
  • Custom model entry, embedding/reranker test tools, and UI enhancements
  • Streaming performance metrics (TTFT, TPS) surfaced per message

• Bug Fixes

  • Improved PDF extraction with OCR fallback
  • Enhanced retrieval: query variants, hybrid scoring, deduplication, optional reranking
  • Embedding request caching (optional) and faster failure behavior

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lyra-note-web	Ready	Preview, Comment	Mar 22, 2026 6:55pm

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9b242fed-ec82-41f6-9c37-ae79d1b17c97

📥 Commits

Reviewing files that changed from the base of the PR and between 28dd7ea and a58832c.

📒 Files selected for processing (3)

• apps/api/app/agents/rag/retrieval.py
• apps/web/src/features/chat/chat-message-bubble.tsx
• apps/web/src/features/chat/mermaid-block.tsx

---

📝 Walkthrough

Walkthrough

Adds LiteLLM support, a cross-encoder reranker, embedding caching, enhanced RAG ingestion/retrieval (OCR, metadata, semantic chunking), clarifying-question flow for deep research, streaming speed metrics, UI/config expansions, and related schema/migration updates.

Changes

Cohort / File(s)	Summary
Database / Model apps/api/alembic/versions/029_message_speed.py, apps/api/app/models.py	Adds nullable JSONB speed column to messages and ORM Message.speed.
LLM Provider & Factory apps/api/app/providers/litellm_provider.py, apps/api/app/providers/llm.py, apps/api/app/providers/provider_factory.py, apps/api/app/config.py	Introduces LiteLLM provider and client wrapper; expands llm_provider config to include litellm.
Reranker Provider apps/api/app/providers/reranker.py, apps/api/app/config.py	New async reranker client calling /rerank; uses reranker-specific settings with fallbacks.
Embedding Provider & Cache apps/api/app/providers/embedding.py, apps/api/app/config.py	Adds Redis-backed per-query embedding cache with TTL and embedding-specific API key/base URL overrides; enforces fast-fail timeouts.
RAG Ingestion apps/api/app/agents/rag/ingestion.py, apps/api/requirements.txt	Switches PDF extraction to pymupdf + pytesseract OCR fallback; extracts structured metadata and produces metadata-attached chunks; prefers LangChain SemanticChunker with fallback.
RAG Retrieval apps/api/app/agents/rag/retrieval.py, apps/api/app/agents/core/tools.py, apps/api/app/agents/core/react_agent.py	Adds query-variant generation, hybrid FTS+vector merge with recency, supplemental FTS-only fetch, MMR diversity filtering, optional cross-encoder reranking, and history parameter.
Agent Core & Engine apps/api/app/agents/core/brain.py, apps/api/app/agents/core/engine.py	Fast-path decision to RAG when no tools; new _build_context for deduplication/truncation of tool results.
Deep Research & Clarification apps/api/app/agents/research/deep_research.py, apps/api/app/agents/research/task_manager.py, apps/api/app/domains/ai/routers/research.py, apps/api/app/domains/ai/schemas.py	Adds clarifying-question generation, new schemas/endpoints, passes clarification_context through planning and task start.
Setup / Config APIs apps/api/app/domains/config/router.py, apps/api/app/domains/config/schemas.py, apps/api/app/domains/setup/router.py, apps/api/app/domains/setup/schemas.py	Adds embedding/reranker fields, connectivity test endpoints for embedding and reranker, updates LLM test to support LiteLLM.
Conversation Service & Stream apps/api/app/services/conversation_service.py, apps/api/app/agents/core/tools.py, apps/api/app/agents/core/react_agent.py	Captures streaming speed events, stores speed metrics on assistant messages; passes conversation history into tool context.
Web — Deep Research & Clarification UI apps/web/src/features/chat/clarifying-panel.tsx, apps/web/src/features/chat/use-deep-research.ts, apps/web/src/features/chat/chat-view.tsx, apps/web/src/services/ai-service.ts	New ClarifyingPanel UI, fetch clarifying questions endpoint, state for clarifying flow, submitClarifications handler integrated into deep research start.
Web — Mermaid & Chat Stream apps/web/src/features/chat/mermaid-block.tsx, apps/web/src/features/chat/chat-message-bubble.tsx, apps/web/src/features/chat/use-chat-stream.ts, apps/web/src/features/chat/dr-document-viewer.tsx	Extracts Mermaid rendering to MermaidBlock with zoom; token-draining queue for streaming; speed event handling and TTFT display updates; evidence badges in reports.
Web — Settings & Setup UI apps/web/src/app/setup/page.tsx, apps/web/src/components/settings/sections/ai-config-section.tsx, apps/web/src/components/settings/settings-primitives.tsx, apps/web/src/lib/constants.ts, apps/web/messages/*.json	Adds llm_provider, embedding/reranker credential fields, per-module test buttons, custom-model select control, reranker constants, and localization updates.
Web — API Surface / Types apps/web/src/lib/api-routes.ts, apps/web/src/schemas/chat-api.ts, apps/web/src/schemas/setup-schemas.ts, apps/web/src/services/config-service.ts, apps/web/src/services/auth-service.ts, apps/web/src/store/use-deep-research-store.ts	New routes for clarify/embedding/reranker tests; message schema includes speed; setup schemas and service payloads extended for provider/credential overrides.
Misc / Dev apps/api/requirements.txt, apps/web/src/app/globals.css, apps/web/src/app/providers.tsx, apps/web/src/features/chat/choice-cards.tsx, apps/web/src/features/chat/chat-helpers.tsx, .vscode/settings.json, packages/cli/src/commands/local.js	Adds dependencies (litellm, pymupdf, pytesseract, langchain-experimental), CSS animations, removes LazyMotion strict, choice-card UI tweaks, maps speed client-side, VSCode setting to ignore git limit warnings, CLI label text changes.

Sequence Diagram(s)

sequenceDiagram
    participant User as User
    participant Frontend as Frontend (Web)
    participant Backend as Backend API
    participant LLM as LLM Provider

    User->>Frontend: Request deep research
    Frontend->>Backend: POST /ai/deep-research/clarify
    Backend->>LLM: Generate clarifying questions
    LLM-->>Backend: Clarifying questions
    Backend-->>Frontend: ClarifyResponse
    Frontend->>User: Render ClarifyingPanel
    User->>Frontend: Submit answers
    Frontend->>Backend: POST /ai/deep-research (with clarification_context)
    Backend->>Backend: _plan(..., clarification_context)
    Backend->>LLM: Generate research plan (with clarified prefs)
    LLM-->>Backend: Research plan
    Backend-->>Frontend: Research started / progress

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• Refactor/backend architecture #17 — Large coordinated changes to agents, retrieval/ingestion, and provider abstractions; overlaps in RAG and provider work.
• Feat/lobehub inspired optimization #16 — Related modifications to agent execution layer and message schema changes impacting similar files.

Poem

🐰 I hopped through models, light and bright,

Litellm hummed into the night,
Rerankers sorted, chunks aligned,
Clarify first, then seek and find,
Tokens raced — I tracked their flight.

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title focuses on 'improve deep research report rendering', which is only one aspect of this large changeset that spans backend RAG optimization, LLM provider abstraction, reranking, embeddings caching, research clarification flow, and multiple UI improvements across setup and chat components.	Consider a more comprehensive title reflecting the major scope: something like 'feat: RAG optimization with reranker, embeddings cache, query variants, and deep research clarifications' would better capture the full changeset extent.
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.90% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/rag-optimization

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

CodeRabbit can use OpenGrep to find security vulnerabilities and bugs across 17+ programming languages.

OpenGrep is compatible with Semgrep configurations. Add an opengrep.yml or semgrep.yml configuration file to your project to enable OpenGrep analysis.