Upload folder using huggingface_hub

.env.example

@@ -0,0 +1,47 @@
+# ============ LLM/VLM 服务 ============
+DEFAULT_PROVIDER=local
+LLM_PROVIDERS__LOCAL__API_BASE=http://192.168.1.100:8009/v1
+LLM_PROVIDERS__LOCAL__API_KEY=not-needed
+LLM_PROVIDERS__LOCAL__MODEL=your-chat-model
+LLM_PROVIDERS__LOCAL__VISION_MODEL=your-vision-model
+LLM_PROVIDERS__LOCAL__MAX_TOKENS=4096
+LLM_PROVIDERS__LOCAL__TEMPERATURE=0.7
+
+# ============ Embedding 服务 ============
+EMBEDDING__PROVIDER=local
+EMBEDDING__API_BASE=http://192.168.1.100:8010/v1
+EMBEDDING__API_KEY=not-needed
+EMBEDDING__MODEL=AXERA-TECH/jina-embeddings-v5-omni-nano-retrieval-AX650-P128-CTX2047
+EMBEDDING__MODEL_TYPE=multimodal
+EMBEDDING__DIM=768
+EMBEDDING__BATCH_SIZE=4
+
+# Milvus Lite 的向量维度必须与 Embedding 输出一致
+MILVUS__DIM=768
+
+# ============ 可选：SenseVoice STT ============
+VOICE__STT_PROVIDER=sensevoice
+VOICE__STT_MODEL=sensevoice
+VOICE__STT_API_BASE=http://192.168.1.100:8011
+VOICE__STT_LANGUAGE=auto
+VOICE__SAMPLE_RATE=16000
+
+# ============ 可选：Kokoro TTS ============
+VOICE__TTS_PROVIDER=kokoro
+VOICE__TTS_MODEL=kokoro
+VOICE__TTS_API_BASE=http://192.168.1.100:8012
+VOICE__TTS_LANGUAGE=zh
+VOICE__TTS_VOICE=zf_xiaoyi
+VOICE__TTS_SPEED=1.0
+VOICE__TTS_RESPONSE_FORMAT=wav
+
+# ============ 可选：PaddleOCR-VL ============
+OCR__ENABLED=true
+OCR__API_BASE=http://192.168.1.100:8013/v1
+OCR__MODEL=PaddlePaddle/PaddleOCR-VL
+OCR__API_KEY=not-needed
+OCR__MAX_PAGES=50
+
+# ============ Agentic RAG Web 服务 ============
+API__HOST=0.0.0.0
+API__PORT=8007

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+data/agentic_rag.db-wal filter=lfs diff=lfs merge=lfs -text
+frontend/node_modules/@oxlint/binding-linux-x64-gnu/oxlint.linux-x64-gnu.node filter=lfs diff=lfs merge=lfs -text
+frontend/node_modules/@rolldown/binding-linux-x64-gnu/rolldown-binding.linux-x64-gnu.node filter=lfs diff=lfs merge=lfs -text
+frontend/node_modules/lightningcss-linux-x64-gnu/lightningcss.linux-x64-gnu.node filter=lfs diff=lfs merge=lfs -text
+image-1.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.env
+.venv/
+venv/
+*.db
+workspace/
+data/user/
+.DS_Store
+.pytest_cache/
+.coverage
+htmlcov/
+uphg.py

README.md

@@ -0,0 +1,779 @@
+# Agentic RAG 智能问答系统
+
+<p align="center"><b>ReAct Agent 驱动</b> | <b>多模态知识库</b> | <b>MCP 工具扩展</b> | <b>边缘/本地部署</b></p>
+
+---
+
+基于 **ReAct Agent** 的多模态检索增强生成（RAG）系统，支持文本、图片、音频、视频的统一入库与跨模态检索，提供智能问答、工具调用、MCP 扩展、流式对话、语音交互等完整能力。支持 OpenAI / 本地 OpenAI-compatible 模型，可灵活部署在云端或边缘设备上。
+
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688.svg)](https://fastapi.tiangolo.com/)
+[![React 19](https://img.shields.io/badge/React-19-61DAFB.svg)](https://react.dev/)
+[![Milvus Lite](https://img.shields.io/badge/Vector%20Store-Milvus%20Lite-orange.svg)](https://milvus.io/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
+
+> 当前版本：`0.1.0`。部分能力还需要进一步开发验证。
+>
+---
+
+![alt text](image.png)
+
+![alt text](image-1.png)
+
+---
+
+## 目录
+
+- [项目背景](#项目背景)
+- [核心特性](#核心特性)
+- [系统架构](#系统架构)
+- [快速开始](#快速开始)
+- [使用方式](#使用方式)
+- [其他功能](#其他功能)
+  - [多模态知识库](#多模态知识库)
+  - [MCP 工具扩展](#mcp-工具扩展)
+  - [语音与消息网关](#语音与消息网关)
+  - [功能状态](#功能状态)
+- [AX8850 运行示例](#ax8850-运行示例)
+
+
+---
+
+## 项目背景
+
+### 为什么需要 Agentic RAG？
+
+传统 RAG 系统只能被动检索，而现实场景中的问题往往需要多步推理、工具调用和动态决策：
+
+- **静态检索局限** — 一次性检索难以回答需要多轮推理的复杂问题。
+- **模态割裂** — 文本、图片、音视频分散存储，无法统一检索，大量非文本信息被浪费。
+- **工具孤岛** — 检索、计算、外部 API 等能力各自独立，Agent 无法根据上下文自主选择工具。
+- **部署复杂** — 多数方案依赖云端服务，存在隐私泄露风险和高昂调用成本。
+
+### 本项目的解决思路
+
+本项目将 **ReAct Agent** 与 **多模态 RAG** 深度融合，让 Agent 能够"思考→行动→观察→再思考"，在推理过程中自主决定何时检索知识库、何时调用外部工具、何时生成最终答案：
+
+- 🧠 **Agent 驱动检索** — Agent 根据问题复杂度自主决定检索策略，支持多轮推理和工具链调用。
+- 🔗 **MCP 生态接入** — 通过 Model Context Protocol 接入外部工具，Agent 能力可无限扩展。
+- 🎨 **多模态统一** — 文本、图片、音频、视频统一向量空间，跨模态语义检索。
+- 🏠 **本地优先** — 支持本地 LLM / Embedding 服务，数据不出设备，隐私安全可控。
+
+### 应用场景
+
+| 领域 | 典型场景 | 核心价值 |
+|------|----------|----------|
+| 🏢 **企业知识管理** | 智能客服、内部培训、文档问答 | 多轮对话理解上下文，自动调用内部工具查询数据 |
+| 🔬 **研发辅助** | 代码库问答、技术文档检索、API 集成 | Agent 自主检索代码示例、调用调试工具、生成修复建议 |
+| 📚 **教育科研** | 文献综述、课件问答、实验数据分析 | 跨文献多轮推理，自动提取关键信息并生成综述 |
+| 🎬 **内容创作** | 素材检索、脚本生成、多模态内容理解 | 以文搜图/以图搜视频，Agent 辅助创作全流程 |
+| 🏥 **专业领域** | 医疗文献问答、法律条文检索、金融报告分析 | 严格的数据隐私要求下本地运行，专业工具链集成 |
+
+---
+
+## 核心特性
+
+### 🚀 功能特性
+
+- **ReAct Agent 引擎** — 支持 `Thought → Action → Observation → Final Answer` 循环，以及原生 Function Calling，Agent 可自主规划多步推理。
+- **多模式智能路由** — 按查询意图动态装配工具集（知识库检索、联网搜索、媒体理解及 MCP 扩展工具），Agent 每轮推理均可自主调用工具。
+- **四模态统一检索** — 文本、图片、音频、视频在同一向量空间中表示，支持以文搜图、以图搜视频等跨模态查询。
+- **混合检索策略** — 支持 `naive` 纯向量检索和 `hybrid` 向量 + 知识图谱混合检索，提升召回准确率。
+- **流式对话体验** — REST SSE 与 WebSocket 双通道流式输出，实时展示 Agent 思考过程和工具调用。
+- **多入口灵活接入** — Web UI、REST API、WebSocket、CLI、异步 Python SDK，满足不同场景需求。
+
+### 🔧 技术特性
+
+- **MCP 工具扩展** — 启动时自动连接外部 MCP Server，将工具注册到 Agent，实现能力热插拔。
+- **多提供商 LLM** — 内置 OpenAI、以及任意 OpenAI-compatible 本地服务适配。
+- **模块化架构** — Agent 引擎、知识管线、向量存储、LLM 服务、记忆系统分层��耦，可独立替换升级。
+- **本地数据持久化** — SQLite 会话存储、Milvus Lite 向量库、JSON 知识图谱，零外部依赖即可运行。
+- **可配置预处理** — 文本分块大小、图片处理策略、音频切片参数等均可通过环境变量调节。
+
+---
+
+## 系统架构
+
+### 整体架构
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                    接入层 (Entry Points)                     │
+│   Web UI  │  REST API  │  WebSocket  │  CLI  │  Python SDK  │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Agent 路由与引擎层                         │
+│         AgentRouter (模式路由)  +  ReActEngine (推理循环)     │
+│              ↓ Thought → Action → Observation ↑             │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+           ┌───────────────┼───────────────┐
+           ▼               ▼               ▼
+      ┌─────────┐    ┌──────────┐    ┌──────────┐
+      │ RAG 工具 │    │ MCP 工具 │    │ 媒体工具  │
+      │(知识库) │    │(外部扩展)│    │(语音/图像)│
+      └────┬────┘    └──────────┘    └──────────┘
+           │
+           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    知识管线 (Knowledge Pipeline)             │
+│   Parse → Process → Embed → Milvus Lite                     │
+│              └────────→ Knowledge Graph (可选)               │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│                      数据持久化层                            │
+│   SQLite (会话/消息)  │  Milvus Lite (向量)  │  JSON (KG)    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 知识管线流程
+
+```text
+原始输入 (文本/图片/音频/视频/PDF/Office)
+        │
+        ▼
+┌───────────────┐
+│  统一解析层    │  → ContentList (统一内容表示)
+│  Parse        │
+└───────┬───────┘
+        │
+        ▼
+┌───────────────┐
+│  模态处理层    │  → 文本分块 / 图片处理 / 音频切片 / 视频帧提取
+│  Process      │
+└───────┬───────┘
+        │
+        ▼
+┌───────────────┐     ┌───────────────┐
+│  向量化层      │ ──→ │  知识图谱层    │ (可选，enable_kg=true)
+│  Embed        │     │  KG Builder   │
+└───────┬───────┘     └───────────────┘
+        │
+        ▼
+┌───────────────┐
+│  向量存储层    │  → Milvus Lite (本地持久化)
+│  Vector Store │
+└───────────────┘
+```
+
+### Agent 推理流程
+
+```text
+用户问题
+    │
+    ▼
+┌─────────────┐
+│  AgentRouter│  
+└──────┬──────┘
+       │
+       ▼
+┌────────────────────────────────────────┐
+│           ReAct 推理循环                │
+│  ┌─────────┐   ┌─────────┐   ┌────────┐ │
+│  │ Thought │ → │ Action  │ → │Observe │ │
+│  │ (思考)   │   │ (行���)   │   │ (观察)  │ │
+│  └─────────┘   └─────────┘   └────────┘ │
+│       ↑                           │      │
+│       └───────────────────────────┘      │
+│              (最多 N 轮)                  │
+└────────────────────────────────────────┘
+       │
+       ▼
+┌─────────────┐
+│ Final Answer │  → 生成最终回答，附来源引用
+└─────────────┘
+```
+
+
+
+### 项目结构
+
+```text
+Agentic_RAG/
+├── agentic_rag/                 # 后端核心代码
+│   ├── agent/                   # ReAct 引擎、Prompt 模板、模式路由
+│   ├── config/                  # Pydantic Settings、默认配置
+│   ├── core/                    # MCP 客户端、多模态处理、STT/TTS
+│   ├── data/                    # 数据模型、SQLite Repository
+│   ├── entrypoints/             # 接入层
+│   │   ├── rest/                # FastAPI REST API
+│   │   ├── websocket/           # WebSocket 服务
+│   │   ├── cli/                 # 命令行接口
+│   │   ├── sdk/                 # Python SDK
+│   │   └── gateway/             # 消息平台网关
+│   ├── orchestration/           # L1 工具、L2 能力编排
+│   ├── runtime/                 # 运行时上下文、流总线、轮次协调
+│   ├── services/                # LLM、知识管线、记忆、会话、向量存储
+│   └── utils/                   # 通用工具
+├── frontend/                    # React 19 + Vite 8 前端
+│   ├── src/
+│   └── vite.config.js
+├── static/                      # 前端构建产物（生产模式）
+├── tests/                       # 测试
+│   ├── unit/                    # 单元测试
+│   ├── integration/             # 集成测试
+│   └── dir/                     # 测试数据
+├── scripts/                     # 辅助脚本（预留）
+├── data/                        # SQLite 运行时数据
+├── workspace/                   # 上传文件、向量库、知识图谱
+├── .env                         # 环境变量配置（由 .env.example 复制）
+├── .env.example                 # 环境变量模板
+├── mcp_servers.json             # MCP 配置（JSON）
+├── mcp_servers.yaml             # MCP 配置（YAML）
+├── pyproject.toml               # Python 项目配置
+└── README.md
+```
+
+---
+
+## 快速开始
+
+### 1. 环境要求
+
+- **Python** 3.10+
+- **Node.js** 18+（构建 Web UI 需要；生产环境直接使用已构建的 `static/` 产物时可省略）
+
+
+### 2. 安装
+
+```bash
+git clone <repository-url>
+cd Agentic_RAG
+
+python -m venv .venv
+source .venv/bin/activate        # Linux/macOS
+# .venv\Scripts\activate         # Windows PowerShell
+
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+
+# 完整安装：Anthropic、语音、视频、文档解析和消息网关
+# pip install -e ".[dev,anthropic,voice,media,documents,gateways]"
+
+# 可选：PDF/Office 完整解析
+pip install pymupdf              # PDF 文本提取及 OCR 页面渲染
+# 或按 Docling 官方说明安装 docling
+```
+
+
+### 3. 配置环境变量
+
+从模板创建 `.env` 文件：
+
+```bash
+cp .env.example .env
+```
+
+然后按需修改（配置使用**无前缀变量名**）：
+
+```bash
+# ============ LLM 配置 ============
+DEFAULT_PROVIDER=local
+
+LLM_PROVIDERS__LOCAL__API_BASE=http://localhost:8009/v1
+LLM_PROVIDERS__LOCAL__MODEL=your-chat-model
+LLM_PROVIDERS__LOCAL__API_KEY=not-needed
+LLM_PROVIDERS__LOCAL__VISION_MODEL=your-vision-model
+
+# ============ Embedding 配置 ============
+EMBEDDING__PROVIDER=local
+EMBEDDING__API_BASE=http://localhost:8010/v1
+EMBEDDING__API_KEY=not-needed
+EMBEDDING__MODEL=your-embedding-model
+EMBEDDING__DIM=768
+EMBEDDING__BATCH_SIZE=4
+
+# ============ 向量库配置 ============
+MILVUS__DIM=768
+
+# ============ API 服务配置 ============
+API__HOST=0.0.0.0
+API__PORT=8007
+```
+
+> ⚠️ `EMBEDDING__DIM` 与 `MILVUS__DIM` 必须一致。若需修改已创建集合的维度，请先备份并删除旧的 `workspace/milvus_lite.db`，再重新建库。
+
+**使用官方云服务：**
+
+```bash
+# OpenAI
+DEFAULT_PROVIDER=openai
+LLM_PROVIDERS__OPENAI__API_KEY=your-openai-api-key
+LLM_PROVIDERS__OPENAI__API_BASE=https://api.openai.com/v1
+LLM_PROVIDERS__OPENAI__MODEL=gpt-4o
+
+# Anthropic Claude（Embedding 仍需单独配置）
+DEFAULT_PROVIDER=claude
+LLM_PROVIDERS__CLAUDE__API_KEY=your-anthropic-api-key
+LLM_PROVIDERS__CLAUDE__API_BASE=https://api.anthropic.com
+LLM_PROVIDERS__CLAUDE__MODEL=your-claude-model
+```
+
+### 4. 构建前端
+
+```bash
+cd frontend
+npm run build
+cd ..
+```
+
+Vite 产���输出到 `static/`，FastAPI 挂载 `/static` 并在 `/` 返回 SPA 首页。生产环境只需构建一次；前端源码未改动时无需重复执行。
+
+### 5. 启动服务
+
+```bash
+# 生产模式
+python -m agentic_rag serve --host 0.0.0.0 --port 8007
+
+# 开发模式（自动重载）
+python -m agentic_rag serve --port 8007 --reload
+# 或
+uvicorn agentic_rag.entrypoints.rest.app:app --host 0.0.0.0 --port 8007 --reload
+```
+
+### 6. 验证运行
+
+```bash
+curl http://localhost:8007/health
+curl http://localhost:8007/ready
+```
+
+| 地址 | 说明 |
+|------|------|
+| `http://localhost:8007/` | Web UI 主界面 |
+| `http://localhost:8007/docs` | Swagger API 文档 |
+| `http://localhost:8007/health` | 进程健康检查 |
+| `http://localhost:8007/ready` | LLM 配置就绪检查 |
+
+✅ 打开 `http://localhost:8007/`，看到聊天界面即部署成功。若页面空白或报资源加载失败，通常是 `static/` 缺失或过期，请回到第 4 步重新执行 `npm run build`。
+
+---
+
+## 使用方式
+
+系统提供多种使用入口：**Web UI** 是浏览器中的完整交互界面，适合直接使用；CLI / REST API / WebSocket / Python SDK 面向脚本调用与二次开发。
+
+### Web UI
+
+```bash
+# 1. 构建前端（首次或前端有更新时执行）
+cd frontend && npm install && npm run build && cd ..
+
+# 2. 启动服务（后端托管 Web UI）
+python -m agentic_rag serve --port 8007
+```
+
+启动后在浏览器打开 `http://localhost:8007/`：
+
+- **对话交互** — 输入问题即开始问答，流式展示 Agent 的 Thought / Action / Observation 推理过程
+- **文件上传** — 上传文本、图片、音频、视频入库，对应 `/api/v1/rag/upload`
+- **会话管理** — 多会话切换，历史记录持久化在本地 SQLite
+
+
+### CLI 命令行
+
+```bash
+# 普通问答
+python -m agentic_rag chat "什么是 RAG？"
+
+# 自动路由或指定模式
+python -m agentic_rag chat --mode research "深入总结知识库中的检索方法"
+
+# 流式输出
+python -m agentic_rag chat --stream "解释 ReAct 的执行过程"
+
+# 指定已配置的 Provider
+python -m agentic_rag chat --provider local "你好"
+
+# 文本文件入库
+python -m agentic_rag ingest --file document.txt --source cli
+
+# 查看当前配置信息
+python -m agentic_rag info
+
+# 查看帮助
+python -m agentic_rag --help
+```
+
+### REST API
+
+#### 非流式聊天
+
+```bash
+curl -X POST http://localhost:8007/api/v1/chat \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"什么是 RAG？","mode":"auto"}'
+```
+
+#### SSE 流式聊天
+
+```bash
+curl -N -X POST http://localhost:8007/api/v1/chat/stream \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"检索知识库中的向量数据库资料","mode":"research"}'
+```
+
+主要事件类型：`text_delta`、`tool_call_start`、`tool_call_result`、`error`、`done`。
+
+#### 知识库检索
+
+```bash
+curl -X POST http://localhost:8007/api/v1/rag/search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"向量数据库","top_k":5,"mode":"hybrid"}'
+```
+
+#### 文本入库
+
+```bash
+curl -X POST http://localhost:8007/api/v1/rag/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{"content":"Milvus 是一个向量数据库。","source":"manual"}'
+```
+
+#### 文件/多模态上传
+
+```bash
+curl -X POST http://localhost:8007/api/v1/rag/upload \
+  -F 'file=@document.pdf' \
+  -F 'source=manual-upload' \
+  -F 'ingest_mode=multimodal' \
+  -F 'mm_method=pure' \
+  -F 'enable_kg=true'
+```
+
+支持的文件格式：
+- **文本/文档**：`.txt` `.md` `.json` `.yaml` `.csv` `.py` `.html` `.pdf` `.docx` 
+- **图片**：`.jpg` `.png` `.gif` `.webp` `.bmp` `.svg`
+- **视频**：`.mp4` `.avi` `.mov` `.mkv` `.webm`
+- **音频**：`.mp3` `.wav` `.m4a` `.ogg` `.flac`
+
+#### 会话管理
+
+```bash
+# 创建会话（user_id 是查询参数）
+curl -X POST 'http://localhost:8007/api/v1/session?user_id=user123'
+
+# 获取会话列表
+curl 'http://localhost:8007/api/v1/sessions?user_id=user123'
+
+# 获取会话消息
+curl http://localhost:8007/api/v1/session/<session_id>/messages
+
+# 删除会话
+curl -X DELETE http://localhost:8007/api/v1/session/<session_id>
+```
+
+
+### WebSocket
+
+```javascript
+const sessionId = crypto.randomUUID()
+const ws = new WebSocket(`ws://localhost:8007/ws/${sessionId}`)
+
+ws.addEventListener('open', () => {
+  ws.send(JSON.stringify({
+    type: 'chat',
+    payload: {
+      message: '检索知识库中的 ReAct 资料',
+      mode: 'research',
+    },
+  }))
+})
+
+ws.addEventListener('message', (event) => {
+  const message = JSON.parse(event.data)
+  console.log(message.type, message.data)
+})
+```
+
+### Python SDK
+
+```python
+import asyncio
+from agentic_rag.entrypoints.sdk.client import AgenticRAGClient
+
+
+async def main() -> None:
+    async with AgenticRAGClient("http://localhost:8007") as client:
+        # 非流式聊天
+        response = await client.chat("什么是 RAG？", mode="auto")
+        print(response["answer"])
+
+        # 流��聊天
+        async for event in client.chat_stream("检索知识库"):
+            print(event)
+
+        # 文本入库
+        result = await client.rag_ingest(
+            "这是一段需要写入知识库的文本。",
+            source="sdk",
+        )
+        print(result)
+
+
+asyncio.run(main())
+```
+
+---
+
+## 其他功能
+
+### 多模态知识库
+
+#### 入库模式
+
+`/api/v1/rag/upload` 参数说明：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `ingest_mode` | `multimodal` | `text` 跳过媒体项；`multimodal` 处理媒体项 |
+| `mm_method` | `pure` | `pure` / `caption` / `both` |
+| `chunk_size` | `512` | 文本分块字符数 |
+| `chunk_overlap` | `50` | 分块重叠字符数 |
+| `enable_kg` | `false` | 构建并持久化知识图谱 |
+
+`mm_method` 说明：
+- `pure` — 直接构造多模态 Embedding 输入；纯文本 Embedding API 会退化为占位文本
+- `caption` — 使用视觉模型生成图片描述，再对描述文本做 Embedding
+- `both` — 同时使用原始媒体和描述文本
+
+#### 本地数据
+
+运行时产生的数据文件：
+
+```text
+data/agentic_rag.db              # 会话与消息历史
+workspace/milvus_lite.db         # Milvus Lite 向量数据库
+workspace/knowledge_graph.json   # 知识图谱（启用 KG 时）
+workspace/uploads/               # 上传文件缓存
+```
+
+> 🔒 这些文件可能包含用户内容或模型数据，部署时请配置合适的访问控制、备份和清理策略。
+
+### MCP 工具扩展
+
+项目支持通过 Model Context Protocol (MCP) 接入外部工具，Agent 可自动发现并使用这些工具。
+
+#### 配置方式
+
+按优先级查找配置：
+
+1. `mcp_servers.json`
+2. `mcp_servers.yaml`
+3. MCP 环境变量
+
+推荐使用不含密钥的配置文件，通过环境变量提供凭据：
+
+```json
+{
+  "mcpServers": {
+    "example-search": {
+      "command": "npx",
+      "args": ["-y", "example-search-mcp"],
+      "disabled": false
+    }
+  }
+}
+```
+
+```bash
+export EXAMPLE_SEARCH_API_KEY='your-key'
+python -m agentic_rag serve
+```
+
+启动日志会显示每个 MCP Server 的连接结果。连接成功的工具会注册到工具中心，并在所有 Agent 模式中可用。
+
+> ⚠️ 不要把真实 API Key 提交到 Git。若密钥曾进入仓库历史，请立即撤销并轮换。
+
+### 语音与消息网关
+
+#### 语音 REST 接口
+
+```bash
+curl -N -X POST http://localhost:8007/api/v1/chat/voice \
+  -F 'audio=@recording.wav' \
+  -F 'sid=voice-demo' \
+  -F 'tts=true'
+```
+
+响应为 SSE，事件类型：`transcript`、`text_delta`、工具事件、`audio`、`error`、`done`。
+
+支持的配置：
+- **STT**：`sensevoice`、`whisper`、`openai`
+- **TTS**：`qwen`、`kokoro`、`edge`、`openai`
+
+#### 消息网关
+
+支持企业微信、QQ Bot、钉钉。总开关 `GATEWAY__ENABLED=true`，各平台需单独配置凭据。
+
+> 生产使用前请完成平台签名校验、回调地址、权限和消息发送链路测试。
+
+### 功能状态
+
+| 能力 | 状态 | 说明 |
+|------|:----:|------|
+| 非流式/流式聊天 | ✅ | REST、CLI；WebSocket 支持流式事件 |
+| `rag_search` | ✅ | Chat API 启动时自动注册 |
+| 文本与文件入库 | ✅ | REST 与 CLI 均有入口 |
+| 多模态上传 | ✅ | REST `/api/v1/rag/upload` |
+| `chat` / `research` 模式 | ✅ | 均可使用 RAG 与已连接的 MCP 工具 |
+| `rag` 模式 Agent 自主入库 | ⚠️ | 路由声明了 `rag_ingest`，但 Chat API 默认只注册 `rag_search` |
+| `media` 模式工具 | ⚠️ | 路由已定义，媒体工具未由 Chat API 默认注册 |
+| MCP | ⚠️ | 取决于本机命令、依赖、网络和环境变量 |
+| PDF/Office 解析 | ⚠️ | 需要 PaddleOCR-VL 服务、`pymupdf` 或 `docling` |
+| 语音对话 | ⚠️ | 需要可用的 STT/TTS 服务或本地模型 |
+| 消息平台网关 | ⚠️ | 企业微信、QQ Bot、钉钉需按平台配置与联调 |
+
+---
+
+## AX8850 运行示例
+
+本节介绍在爱芯（AXERA）AX650N/AX8850 边缘设备上的两种部署方式：
+
+- **分离部署**  — 仅模型推理服务运行在 NPU 设备上，通过 OpenAI 兼容接口对外提供；Agentic RAG 主机通过 HTTP 连接这些服务。
+- **全量部署** （本节默认方式）— 完整的 Agentic RAG 服务也运行在 NPU 设备上，推理与应用同机完成，数据不出设备。
+
+### 1. 下载模型与运行组件
+
+可从以下官方资源选择适配 AX650N/AX8850 的模型和运行组件：
+
+- [AXERA-TECH Hugging Face 模型仓库](https://huggingface.co/AXERA-TECH)
+- [AXERA-TECH/ax-llm](https://github.com/AXERA-TECH/ax-llm)（LLM/VLM/Embedding 推理及 OpenAI 兼容服务）
+- [AX650 Community Hub](https://github.com/AXERA-TECH/AX650-Community-Hub)（SDK、部署文档和模型示例）
+
+本项目至少需要以下两类模型：
+
+| 服务 | 用途 | 接口要求 | 示例端口 |
+|------|------|----------|---------:|
+| Chat LLM/VLM | 对话、Agent 推理、图片理解 | OpenAI 兼容 `/v1/chat/completions` | `8009` |
+| Embedding | 文本/图片/音视频向量化 | OpenAI 兼容 `/v1/embeddings` | `8010` |
+
+可选模型服务：
+
+| 服务 | 用途 | 接口要求 | 示例端口 |
+|------|------|----------|---------:|
+| [SenseVoice](https://huggingface.co/AXERA-TECH/SenseVoice_AgenticRAG) | 语音识别 | `/v1/audio/transcriptions` 或 `/asr` | `8011` |
+| [Kokoro TTS](https://modelscope.cn/models/AXERA-TECH/kokoro.axera) | 语音合成 | `POST /tts`，返回 WAV | `8012` |
+| PaddleOCR-VL | PDF/图片 OCR | OpenAI 兼容接口 | `8013` |
+
+### 2. 准备运行环境
+
+Agentic RAG 主机安装项目依赖。若启用语音、文档和媒体处理，建议安装完整可选依赖：
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[voice,documents,media]"
+
+# 压缩音频解码还需要系统提供 ffmpeg
+ffmpeg -version
+```
+
+如果只使用文本问答和 RAG，可直接执行：
+
+```bash
+pip install -e .
+```
+
+### 3. 启动模型服务
+
+以下命令在 **AX8850 设备**上执行。将模型目录替换为实际下载路径：
+
+```bash
+# LLM/VLM 模型
+axllm serve /path/to/llm-or-vlm-model --host 0.0.0.0 --port 8009
+
+# Embedding 模型
+axllm serve /path/to/embeddings-model --host 0.0.0.0 --port 8010
+
+# SenseVoice 模型
+python /path/to/SenseVoice/python/openai_server.py --port 8011
+
+# Kokoro 模型
+python /path/to/kokoro/kokoro_svr.py --port 8012
+```
+
+SenseVoice、Kokoro 和 PaddleOCR-VL 的启动命令以各自模型仓库为准。配置前应确认它们分别满足本项目使用的接口约定：
+
+- SenseVoice：优先支持 `POST /v1/audio/transcriptions`，也兼容 `POST /asr`
+- Kokoro：支持 `POST /tts`，接收 `text`、`language`、`voice`、`speed` 字段并返回音频字节
+- PaddleOCR-VL：提供 OpenAI 兼容的视觉模型接口
+
+### 4. 配置环境变量
+
+在项目根目录创建或修改 `.env`。以下示例假设所有模型服务都运行在 `192.168.1.100`：
+
+```bash
+# ============ LLM/VLM 服务 ============
+DEFAULT_PROVIDER=local
+LLM_PROVIDERS__LOCAL__API_BASE=http://192.168.1.100:8009/v1
+LLM_PROVIDERS__LOCAL__API_KEY=not-needed
+LLM_PROVIDERS__LOCAL__MODEL=your-chat-model
+LLM_PROVIDERS__LOCAL__VISION_MODEL=your-vision-model
+LLM_PROVIDERS__LOCAL__MAX_TOKENS=4096
+LLM_PROVIDERS__LOCAL__TEMPERATURE=0.7
+
+# ============ Embedding 服务 ============
+EMBEDDING__PROVIDER=local
+EMBEDDING__API_BASE=http://192.168.1.100:8010/v1
+EMBEDDING__API_KEY=not-needed
+EMBEDDING__MODEL=AXERA-TECH/jina-embeddings-v5-omni-nano-retrieval-AX650-P128-CTX2047
+EMBEDDING__MODEL_TYPE=multimodal
+EMBEDDING__DIM=768
+EMBEDDING__BATCH_SIZE=4
+
+# Milvus Lite 的向量维度必须与 Embedding 输出一致
+MILVUS__DIM=768
+
+# ============ 可选：SenseVoice STT ============
+VOICE__STT_PROVIDER=sensevoice
+VOICE__STT_MODEL=sensevoice
+VOICE__STT_API_BASE=http://192.168.1.100:8011
+VOICE__STT_LANGUAGE=auto
+VOICE__SAMPLE_RATE=16000
+
+# ============ 可选：Kokoro TTS ============
+VOICE__TTS_PROVIDER=kokoro
+VOICE__TTS_MODEL=kokoro
+VOICE__TTS_API_BASE=http://192.168.1.100:8012
+VOICE__TTS_LANGUAGE=zh
+VOICE__TTS_VOICE=zf_xiaoyi
+VOICE__TTS_SPEED=1.0
+VOICE__TTS_RESPONSE_FORMAT=wav
+
+# ============ 可选：PaddleOCR-VL ============
+OCR__ENABLED=true
+OCR__API_BASE=http://192.168.1.100:8013/v1
+OCR__MODEL=PaddlePaddle/PaddleOCR-VL
+OCR__API_KEY=not-needed
+OCR__MAX_PAGES=50
+
+# ============ Agentic RAG Web 服务 ============
+API__HOST=0.0.0.0
+API__PORT=8007
+```
+
+注意事项：
+
+1. `LLM_PROVIDERS__LOCAL__MODEL` 必须与模型服务实际暴露的模型名一致。这里使用已注册的 `local` Provider 连接 AX8850 上的 OpenAI 兼容服务，无需新增 Provider 类型。
+2. 纯文本模型不支持图片输入时，将 `VISION_MODEL` 配置为单独的 VLM；如果服务中没有视觉模型，请留空并避免使用图片理解功能。
+3. `EMBEDDING__DIM` 和 `MILVUS__DIM` 必须一致。更换向量维度后，需要备份并删除旧的 `workspace/milvus_lite.db`，再重新入库。
+4. 使用多模态 Embedding 时建议设置 `EMBEDDING__MODEL_TYPE=multimodal`。
+5. 如果 AX8850 上只启动了核心的 LLM 和 Embedding 服务，可删除或注释 STT、TTS、OCR 配置。
+
+### 5. 启动项目
+
+```bash
+# 首次运行或前端发生变化时构建 Web UI
+cd frontend && npm install && npm run build && cd ..
+
+# 启动后端及 Web UI
+python -m agentic_rag serve --host 0.0.0.0 --port 8007
+```
+
+---
+

agentic_rag/__init__.py

@@ -0,0 +1,3 @@
+"""Agentic RAG - Multi-modal ReAct-powered RAG System."""
+
+__version__ = "0.1.0"

agentic_rag/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m agentic_rag`."""
+
+from agentic_rag.entrypoints.cli.main import app
+
+if __name__ == "__main__":
+    app()

agentic_rag/agent/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/agent/react_engine.py

@@ -0,0 +1,608 @@
+"""ReAct Engine — the core Think → Act → Observe loop."""
+
+import asyncio
+import json
+import time
+import uuid
+from typing import AsyncIterator, Optional
+
+from agentic_rag.data.models import (
+    AgentEvent,
+    AgentEventType,
+    AgentInput,
+    AgentOutput,
+    LLMChunk,
+    LLMResponse,
+    Message,
+    ToolCall,
+    ToolCallResult,
+    ToolDefinition,
+)
+from agentic_rag.agent.react_parser import (
+    ReActStep,
+    extract_final_answer,
+    format_observation,
+    parse_react_output,
+)
+from agentic_rag.agent.react_prompt import build_react_prompt, build_tools_description
+from agentic_rag.services.llm.base import (
+    BaseLLMProvider,
+    ReasoningStreamFilter,
+    strip_reasoning,
+)
+
+
+class ReActEngine:
+    """ReAct (Reasoning + Acting) reasoning engine.
+
+    Executes the Think → Act → Observe loop that powers the agent.
+    """
+
+    def __init__(
+        self,
+        llm: BaseLLMProvider,
+        tools: list,
+        system_prompt_template: str,
+        max_iterations: int = 10,
+        stop_on_error: bool = False,
+        enable_native_tool_calls: bool = True,
+        require_tool_call: bool = False,
+    ):
+        """
+        Args:
+            llm: LLM provider for generation.
+            tools: List of BaseTool instances available to the agent.
+            system_prompt_template: Template string for the system prompt.
+            max_iterations: Maximum ReAct loop iterations.
+            stop_on_error: If True, stop on first tool error.
+            enable_native_tool_calls: If False, tools are NOT sent to the LLM
+                (pure ReAct text mode for models without function calling).
+            require_tool_call: If True, reject a final answer until at least one
+                available tool has completed successfully. Used for freshness-
+                sensitive queries where model memory is not acceptable evidence.
+        """
+        self.llm = llm
+        self.tools = tools
+        self.system_prompt_template = system_prompt_template
+        self.max_iterations = max_iterations
+        self.stop_on_error = stop_on_error
+        self.enable_native_tool_calls = enable_native_tool_calls
+        self.require_tool_call = require_tool_call
+        self._tool_map = {t.name: t for t in tools}
+
+    async def run(self, input: AgentInput, turn_id: str = "") -> AgentOutput:
+        """Execute the ReAct loop (non-streaming)."""
+        if not turn_id:
+            turn_id = uuid.uuid4().hex
+
+        messages = self._build_initial_messages(input)
+        tool_calls_made: list[ToolCallResult] = []
+        total_usage: dict[str, int] = {"prompt_tokens": 0, "completion_tokens": 0}
+        invalid_output_count = 0  # Track consecutive invalid outputs
+        max_invalid_attempts = 2  # Force final answer after 2 consecutive invalid outputs
+        executed_sigs: set[str] = set()  # (tool, args) dedupe — mirrors stream()
+
+        for iteration in range(self.max_iterations):
+            # Contract for the NEXT turn: a native function-call round ends with
+            # "continue", so if no new tool result was appended after this point
+            # the model must answer in text ReAct format (never emit format-only
+            # text alongside a function call, or the final tool result gets
+            # ignored and the last observation is lost).
+            n_msgs_before = len(messages)
+            messages.append(Message.user(
+                "【重要】如果你决定调用工具，请只发起工具调用，不要同时输出任何 Thought/Action 格式行；"
+                "如果你不调用工具，请按格式输出：Thought: ... Final Answer: ...（或 Thought/Action/Action Input 发起文本式工具调用）。"
+            ))
+            response = await self.llm.agenerate(messages, self._get_llm_tool_definitions())
+            if len(messages) > n_msgs_before:
+                messages.pop()  # remove the contract — don't pollute history
+
+            total_usage["prompt_tokens"] += response.usage.get("prompt_tokens", 0)
+            total_usage["completion_tokens"] += response.usage.get("completion_tokens", 0)
+
+            # Handle native tool calls (from providers that support function calling)
+            if response.tool_calls:
+                invalid_output_count = 0  # Reset on valid tool call
+                for tc in response.tool_calls:
+                    args = tc.arguments or {}
+                    if not args:
+                        messages.append(Message.tool(
+                            content=f"Error: '{tc.name}' 缺少参数",
+                            tool_call_id=tc.id,
+                        ))
+                        continue
+                    sig = (tc.name, json.dumps(args, sort_keys=True, ensure_ascii=False))
+                    if sig in executed_sigs:
+                        messages.append(Message.tool(
+                            content=f"Error: 禁止重复调用 '{tc.name}'（参数相同）。请基于已有 Observation 直��输出 Final Answer。",
+                            tool_call_id=tc.id,
+                        ))
+                        continue
+                    executed_sigs.add(sig)
+                    result = await self._execute_tool(tc.name, args)
+                    tool_calls_made.append(result)
+                    messages.append(Message.tool(
+                        content=str(result.result) if not result.error else f"Error: {result.error}",
+                        tool_call_id=tc.id,
+                    ))
+                continue
+
+            # Parse ReAct format output
+            step = parse_react_output(response.content, list(self._tool_map.keys()))
+
+            if step.is_final:
+                if self.require_tool_call and not self._has_successful_tool_result(tool_calls_made):
+                    invalid_output_count += 1
+                    messages.append(Message.assistant(strip_reasoning(response.content)))
+                    messages.append(Message.user(
+                        "该问题必须先调用可用的网络搜索工具并获得成功的 Observation。"
+                        "不得依据模型记忆直接回答，也不得自行生成引用。请立即调用工具。"
+                    ))
+                    continue
+                return AgentOutput(
+                    messages=messages,
+                    final_answer=step.final_answer,
+                    tool_calls_made=tool_calls_made,
+                    usage=total_usage,
+                    iterations=iteration + 1,
+                )
+
+            if step.action:
+                invalid_output_count = 0  # Reset on valid action
+                # Guard: skip if action_input is empty (broken parse)
+                if not step.action_input:
+                    messages.append(Message.user(
+                        f"'{step.action}' 需要参数，请在 Action Input 中提供 JSON。"
+                    ))
+                    continue
+                sig = (step.action, json.dumps(step.action_input, sort_keys=True, ensure_ascii=False))
+                if sig in executed_sigs:
+                    messages.append(Message.user(
+                        f"你已经用相同参数调用过 '{step.action}' 了。请基于已有 Observation 直接输出 Final Answer。"
+                    ))
+                    continue
+                executed_sigs.add(sig)
+                # Execute the tool
+                result = await self._execute_tool(step.action, step.action_input)
+                tool_calls_made.append(result)
+
+                # Format observation and append to messages
+                observation = format_observation(
+                    step.action,
+                    str(result.result) if result.result else "",
+                    result.error,
+                )
+                # Append the assistant's ReAct output + observation as a single message
+                messages.append(Message.assistant(response.content))
+                messages.append(Message.user(observation))
+            else:
+                # No valid action and no final answer — LLM output is unparseable
+                invalid_output_count += 1
+                if invalid_output_count >= max_invalid_attempts:
+                    if self.require_tool_call and not self._has_successful_tool_result(tool_calls_made):
+                        return AgentOutput(
+                            messages=messages,
+                            final_answer=self._live_search_failure_answer(),
+                            tool_calls_made=tool_calls_made,
+                            usage=total_usage,
+                            iterations=iteration + 1,
+                        )
+                    # Force exit after repeated invalid outputs to prevent infinite loop
+                    final = extract_final_answer(response.content)
+                    if not final:
+                        # Use accumulated content as fallback answer
+                        final = response.content.strip() or "抱歉，我暂时无法回答这个问题。"
+                    return AgentOutput(
+                        messages=messages,
+                        final_answer=final,
+                        tool_calls_made=tool_calls_made,
+                        usage=total_usage,
+                        iterations=iteration + 1,
+                    )
+                # Prompt LLM to continue with correct format
+                messages.append(Message.user(
+                    "你的输出格式不正确。请严格按照以下格式之一输出：\n"
+                    "1. 调用工具：Thought: ...\nAction: tool_name\nAction Input: {\"param\": \"value\"}\n"
+                    "2. 最终答案：Thought: ...\nFinal Answer: ..."
+                ))
+
+        # Max iterations reached
+        if self.require_tool_call and not self._has_successful_tool_result(tool_calls_made):
+            final = self._live_search_failure_answer()
+        else:
+            final = await self._force_final_answer(messages)
+        return AgentOutput(
+            messages=messages,
+            final_answer=final,
+            tool_calls_made=tool_calls_made,
+            usage=total_usage,
+            iterations=self.max_iterations,
+        )
+
+    async def stream(self, input: AgentInput, turn_id: str = "") -> AsyncIterator[AgentEvent]:
+        """Execute the ReAct loop with streaming events."""
+        if not turn_id:
+            turn_id = uuid.uuid4().hex
+
+        messages = self._build_initial_messages(input)
+        tool_calls_made: list[ToolCallResult] = []
+        invalid_output_count = 0  # Track consecutive invalid outputs
+        max_invalid_attempts = 2  # Force final answer after 2 consecutive invalid outputs
+        executed_sigs: set[tuple[str, str]] = set()
+
+        for iteration in range(self.max_iterations):
+            # Emit thought event
+            yield AgentEvent(
+                event_type=AgentEventType.THOUGHT,
+                data={"iteration": iteration},
+                turn_id=turn_id,
+            )
+
+            # Stream LLM generation — collect both text deltas AND native tool calls.
+            full_content = ""
+            # Native function-calling state (accumulated across streaming chunks)
+            native_tool_name = ""
+            native_tool_args = ""
+            has_native_tool_call = False
+            stream_error = None
+            # Incremental reasoning stripper — thinking models (<think> blocks)
+            # must not leak their reasoning to the UI or into the ReAct parser.
+            think_filter = ReasoningStreamFilter()
+            # Answer gating: only stream the actual answer text to the UI.
+            # "Thought:" lines and any pre-answer monologue are buffered and
+            # dropped — the final answer is extracted from full_content below.
+            pending_delta = ""
+            answer_streaming = False
+            try:
+                async for chunk in self.llm.agenerate_stream(messages, self._get_llm_tool_definitions()):
+                    if chunk.content_delta:
+                        delta = think_filter.feed(chunk.content_delta)
+                        full_content += delta
+                        # After tool call detection, further text is likely
+                        # post-tool narration — suppress to reduce noise.
+                        if not delta or has_native_tool_call:
+                            continue
+                        if answer_streaming:
+                            emit = delta
+                        else:
+                            pending_delta += delta
+                            if "Final Answer:" in pending_delta:
+                                emit = pending_delta.split("Final Answer:", 1)[1].lstrip()
+                                answer_streaming = True
+                            else:
+                                continue
+                        if emit:
+                            yield AgentEvent(
+                                event_type=AgentEventType.TEXT_DELTA,
+                                data={"content": emit},
+                                turn_id=turn_id,
+                            )
+                    # Collect native function-call deltas (Qwen / OpenAI function calling)
+                    if chunk.tool_call_delta:
+                        has_native_tool_call = True
+                        if chunk.tool_call_delta.get("name"):
+                            native_tool_name = chunk.tool_call_delta["name"]
+                        if chunk.tool_call_delta.get("arguments"):
+                            native_tool_args += chunk.tool_call_delta["arguments"]
+                # Flush text held back for partial-tag detection
+                tail = think_filter.flush()
+                if tail:
+                    full_content += tail
+                    if not has_native_tool_call:
+                        if answer_streaming:
+                            yield AgentEvent(
+                                event_type=AgentEventType.TEXT_DELTA,
+                                data={"content": tail},
+                                turn_id=turn_id,
+                            )
+                        else:
+                            pending_delta += tail
+                            if "Final Answer:" in pending_delta:
+                                emit = pending_delta.split("Final Answer:", 1)[1].lstrip()
+                                if emit:
+                                    answer_streaming = True
+                                    yield AgentEvent(
+                                        event_type=AgentEventType.TEXT_DELTA,
+                                        data={"content": emit},
+                                        turn_id=turn_id,
+                                    )
+            except Exception as e:
+                stream_error = str(e)
+                import sys
+                print(f"  [ReAct] ⚠ LLM stream error (iteration {iteration}): {e}", flush=True)
+                sys.stdout.flush()
+
+            # ── Handle stream error ──
+            if stream_error and not full_content.strip():
+                yield AgentEvent(
+                    event_type=AgentEventType.ERROR,
+                    data={"error": f"LLM stream failed: {stream_error}"},
+                    turn_id=turn_id,
+                )
+                yield AgentEvent(
+                    event_type=AgentEventType.DONE,
+                    data={"final_answer": f"抱歉，模型服务连接中断：{stream_error}，请稍后重试。"},
+                    turn_id=turn_id,
+                )
+                return
+
+            # ── Resolve action: native function calling takes priority ──
+            if has_native_tool_call and native_tool_name:
+                invalid_output_count = 0  # Reset on valid tool call
+                try:
+                    action_input = json.loads(native_tool_args) if native_tool_args else {}
+                except json.JSONDecodeError:
+                    action_input = {"query": native_tool_args} if native_tool_args else {}
+                sig = (native_tool_name, json.dumps(action_input, sort_keys=True, ensure_ascii=False))
+                if sig in executed_sigs:
+                    messages.append(Message.user(
+                        f"你已经用相同参数调用过 '{native_tool_name}'。请根据已有 Observation 输出 Final Answer。"
+                    ))
+                    continue
+                executed_sigs.add(sig)
+
+                yield AgentEvent(
+                    event_type=AgentEventType.TOOL_CALL_START,
+                    data={"tool": native_tool_name, "input": action_input},
+                    turn_id=turn_id,
+                )
+                result = await self._execute_tool(native_tool_name, action_input)
+                tool_calls_made.append(result)
+                yield AgentEvent(
+                    event_type=AgentEventType.TOOL_CALL_RESULT,
+                    data={
+                        "tool": native_tool_name,
+                        "success": not result.error,
+                        "result": str(result.result)[:500] if result.result else "",
+                        "error": result.error,
+                    },
+                    turn_id=turn_id,
+                )
+                observation = format_observation(
+                    native_tool_name,
+                    str(result.result) if result.result else "",
+                    result.error,
+                )
+                messages.append(Message.assistant(
+                    strip_reasoning(full_content).strip()
+                    or f"Thought: 调用 {native_tool_name}\nAction: {native_tool_name}\nAction Input: {json.dumps(action_input, ensure_ascii=False)}"
+                ))
+                messages.append(Message.user(observation))
+                continue
+
+            # ── Fallback: parse ReAct text format ──
+            step = parse_react_output(full_content, list(self._tool_map.keys()))
+
+            if step.is_final:
+                if self.require_tool_call and not self._has_successful_tool_result(tool_calls_made):
+                    invalid_output_count += 1
+                    messages.append(Message.assistant(strip_reasoning(full_content)))
+                    messages.append(Message.user(
+                        "该问题必须先调用可用的网络搜索工具并获得成功的 Observation。"
+                        "不得依据模型记忆直接回答，也不得自行生成引用。请立即调用工具。"
+                    ))
+                    continue
+                yield AgentEvent(
+                    event_type=AgentEventType.DONE,
+                    data={"final_answer": step.final_answer, "iterations": iteration + 1},
+                    turn_id=turn_id,
+                )
+                return
+
+            if step.action:
+                invalid_output_count = 0  # Reset on valid action
+                # Guard: if action_input is empty and the tool requires args, skip
+                if not step.action_input:
+                    messages.append(Message.user(
+                        f"'{step.action}' 需要参数，请在 Action Input 中提供 JSON。"
+                    ))
+                    continue
+                sig = (step.action, json.dumps(step.action_input, sort_keys=True, ensure_ascii=False))
+                if sig in executed_sigs:
+                    messages.append(Message.user(
+                        f"你已经用相同参数调用过 '{step.action}'。请根据已有 Observation 输出 Final Answer。"
+                    ))
+                    continue
+                executed_sigs.add(sig)
+
+                yield AgentEvent(
+                    event_type=AgentEventType.TOOL_CALL_START,
+                    data={"tool": step.action, "input": step.action_input},
+                    turn_id=turn_id,
+                )
+
+                result = await self._execute_tool(step.action, step.action_input)
+                tool_calls_made.append(result)
+
+                yield AgentEvent(
+                    event_type=AgentEventType.TOOL_CALL_RESULT,
+                    data={
+                        "tool": step.action,
+                        "success": not result.error,
+                        "result": str(result.result)[:500] if result.result else "",
+                        "error": result.error,
+                    },
+                    turn_id=turn_id,
+                )
+
+                observation = format_observation(
+                    step.action,
+                    str(result.result) if result.result else "",
+                    result.error,
+                )
+                messages.append(Message.assistant(strip_reasoning(full_content)))
+                messages.append(Message.user(observation))
+            else:
+                # No valid action and no final answer — LLM output is unparseable
+                invalid_output_count += 1
+                if invalid_output_count >= max_invalid_attempts:
+                    if self.require_tool_call and not self._has_successful_tool_result(tool_calls_made):
+                        yield AgentEvent(
+                            event_type=AgentEventType.DONE,
+                            data={"final_answer": self._live_search_failure_answer(),
+                                  "iterations": iteration + 1},
+                            turn_id=turn_id,
+                        )
+                        return
+                    # Force exit after repeated invalid outputs to prevent infinite loop
+                    final = extract_final_answer(full_content)
+                    if not final:
+                        final = await self._force_final_answer(messages)
+                        if not final or ("Thought:" in final and "Action" in final):
+                            final = full_content.strip()
+                    yield AgentEvent(
+                        event_type=AgentEventType.DONE,
+                        data={"final_answer": final or "抱歉，我暂时无法回答这个问题。",
+                              "iterations": iteration + 1},
+                        turn_id=turn_id,
+                    )
+                    return
+                messages.append(Message.user(
+                    "你的输出格式不正确。请严格按照以下格式之一输出：\n"
+                    "1. 调用工具：Thought: ...\nAction: tool_name\nAction Input: {\"param\": \"value\"}\n"
+                    "2. 最终答案：Thought: ...\nFinal Answer: ..."
+                ))
+
+        # Max iterations — force LLM to give a final answer with what it has
+        if self.require_tool_call and not self._has_successful_tool_result(tool_calls_made):
+            final = self._live_search_failure_answer()
+        else:
+            final = await self._force_final_answer(messages)
+        yield AgentEvent(
+            event_type=AgentEventType.DONE,
+            data={"final_answer": final or "Max iterations reached. Could not complete the task.",
+                  "iterations": self.max_iterations},
+            turn_id=turn_id,
+        )
+
+    def _build_initial_messages(self, input: AgentInput) -> list[Message]:
+        """Build the initial message list for the ReAct loop."""
+        tools_desc = build_tools_description(self._get_tool_definitions())
+        memory_context = self._format_messages(input.messages)
+
+        system_prompt = build_react_prompt(
+            tools_description=tools_desc,
+            memory_context=memory_context,
+        )
+
+        messages = [Message.system(system_prompt)]
+
+        # Check if input already has a multimodal user message
+        has_multimodal_query = any(
+            isinstance(m.content, list) and m.role.value == "user"
+            for m in input.messages
+        )
+
+        # Add conversation history (excluding system messages)
+        for msg in input.messages:
+            if msg.role.value != "system":
+                messages.append(msg)
+
+        # Add current query — skip if already included as multimodal message
+        if not has_multimodal_query:
+            query = input.query
+            if input.multimodal and input.multimodal.text:
+                query = input.multimodal.text
+            messages.append(Message.user(query))
+
+        return messages
+
+    async def _execute_tool(self, name: str, arguments: dict) -> ToolCallResult:
+        """Execute a tool by name with arguments.
+
+        Falls back to the global tool registry when the tool isn't in this
+        engine's filtered set: the model sometimes emits a tool it knows from
+        context (e.g. an MCP tool) that the router didn't hand it, and
+        answering "tool not found" wastes a turn when the tool actually
+        exists in the process.
+        """
+        call_id = f"call_{uuid.uuid4().hex[:12]}"
+
+        tool = self._tool_map.get(name)
+        if tool is None:
+            try:
+                from agentic_rag.orchestration.l1_tools.registry import get_tool_registry
+                tool = get_tool_registry().get(name)
+            except Exception:
+                tool = None
+        if tool is None:
+            return ToolCallResult(
+                call_id=call_id,
+                name=name,
+                result=None,
+                error=f"Tool '{name}' not found. Available: {list(self._tool_map.keys())}",
+            )
+
+        try:
+            # Add timeout to prevent hanging on slow tools
+            result = await asyncio.wait_for(tool.execute(**arguments), timeout=60.0)
+            return ToolCallResult(
+                call_id=call_id,
+                name=name,
+                result=result,
+            )
+        except asyncio.TimeoutError:
+            return ToolCallResult(
+                call_id=call_id,
+                name=name,
+                result=None,
+                error=f"Tool '{name}' execution timed out after 60 seconds",
+            )
+        except Exception as e:
+            return ToolCallResult(
+                call_id=call_id,
+                name=name,
+                result=None,
+                error=str(e),
+            )
+
+    @staticmethod
+    def _has_successful_tool_result(results: list[ToolCallResult]) -> bool:
+        """Return whether at least one tool produced usable evidence."""
+        return any(not result.error and result.result for result in results)
+
+    @staticmethod
+    def _live_search_failure_answer() -> str:
+        """Fail closed when fresh information could not be retrieved."""
+        return (
+            "当前问题需要实时网络信息，但本次未能获得有效的搜索结果，"
+            "因此无法可靠确认。请稍后重试；为避免误导，我不会使用模型记忆猜测答案或编造来源。"
+        )
+
+    def _get_tool_definitions(self) -> list[ToolDefinition]:
+        """Get all tool definitions for prompt construction and parsing."""
+        return [t.to_definition() for t in self.tools]
+
+    def _get_llm_tool_definitions(self) -> list[ToolDefinition]:
+        """Get definitions passed through the provider's native tools API."""
+        if not self.enable_native_tool_calls:
+            return []
+        return self._get_tool_definitions()
+
+    @staticmethod
+    def _format_messages(messages: list[Message]) -> str:
+        """Format conversation history for the prompt."""
+        if not messages:
+            return ""
+        lines = []
+        for msg in messages[-10:]:  # Last 10 messages
+            content = msg.content
+            if isinstance(content, list):
+                # Extract text parts for history summary
+                texts = [p.get("text", "") for p in content if isinstance(p, dict) and p.get("text")]
+                img_count = sum(1 for p in content if isinstance(p, dict) and p.get("type") == "image_url")
+                parts = texts
+                if img_count:
+                    parts.append(f"[{img_count} image(s)]")
+                content = " ".join(parts) if parts else "[multimodal content]"
+            lines.append(f"{msg.role.value}: {str(content)[:200]}")
+        return "\n".join(lines)
+
+    async def _force_final_answer(self, messages: list[Message]) -> str:
+        """Force the LLM to produce a final answer when max iterations are reached."""
+        messages.append(Message.user(
+            "已达到最大步数。请基于已有信息给出 Final Answer。"
+        ))
+        response = await self.llm.agenerate(messages)
+        final = extract_final_answer(response.content)
+        return final or response.content

agentic_rag/agent/react_parser.py

@@ -0,0 +1,208 @@
+"""Parser for ReAct outputs — extracts Thought, Action, and Final Answer."""
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ReActStep:
+    """A single step of the ReAct loop."""
+    thought: str = ""
+    action: str = ""
+    action_input: dict = None
+    is_final: bool = False
+    final_answer: str = ""
+    raw_text: str = ""
+
+    def __post_init__(self):
+        if self.action_input is None:
+            self.action_input = {}
+
+
+def parse_react_output(text: str, tool_names: list[str] | None = None) -> ReActStep:
+    """Parse the LLM output into a ReAct step.
+
+    Handles these patterns:
+    - Thought: ...
+    - Action: tool_name
+    - Action Input: {...}
+    OR
+    - Thought: ...
+    - Final Answer: ...
+    """
+    # Truncate repetitive output — if the model loops on the same sentence,
+    # cut at the first repetition to keep only useful content.
+    text = _trim_repetition(text)
+
+    # Strip any residual reasoning (<think> blocks) — reasoning text may
+    # contain rehearsed "Thought:/Action:" lines that must NOT be parsed as
+    # real actions. Providers normally strip this already; this is a safety net.
+    from agentic_rag.services.llm.base import strip_reasoning
+    text = strip_reasoning(text)
+
+    result = ReActStep(raw_text=text)
+
+    # Extract Thought
+    thought_match = re.search(r'Thought:\s*(.+?)(?=\n(?:Action|Final Answer)|$)', text, re.DOTALL)
+    if thought_match:
+        result.thought = thought_match.group(1).strip()
+
+    # Check for Final Answer first
+    final_match = re.search(r'Final Answer:\s*(.+)', text, re.DOTALL)
+    if final_match:
+        result.is_final = True
+        result.final_answer = final_match.group(1).strip()
+        return result
+
+    # Extract Action — handle Chinese-descriptive Action lines like:
+    #   Action: 使用 rag_search 搜索...
+    #   Action: 调用 mcp__tavily-mcp__tavily_search 查询...
+    action_match = re.search(r'Action:\s*(.+?)(?:\n|$)', text)
+    if action_match:
+        action_text = action_match.group(1).strip()
+        result.action = _resolve_tool_name(action_text, tool_names or [])
+        # Re-parse with stricter matching if failed
+        if not result.action:
+            action_match2 = re.search(r'Action:\s*(\S+)', text)
+            if action_match2:
+                result.action = _resolve_tool_name(action_match2.group(1).strip(), tool_names or [])
+
+    # Extract Action Input (try JSON first, then key=value)
+    action_input_match = re.search(r'Action Input:\s*(\{.+?\}|.+)', text, re.DOTALL)
+    if action_input_match:
+        input_str = action_input_match.group(1).strip()
+        result.action_input = parse_action_input(input_str)
+
+    return result
+
+
+def _trim_repetition(text: str) -> str:
+    """Detect and cut repetitive LLM output at the first repetition point.
+
+    When a model loops — e.g. "I will output the answer... I will output the answer..."
+    — truncate everything after the first occurrence of the repeated line.
+    """
+    lines = text.split("\n")
+    seen: set[str] = set()
+    clean_lines: list[str] = []
+
+    for line in lines:
+        stripped = line.strip()
+        # Skip empty lines in repetition check
+        if not stripped:
+            clean_lines.append(line)
+            continue
+        # Normalize for comparison
+        norm = stripped.lower().rstrip(".。！!?？,，")
+        if norm in seen:
+            # Found repetition — stop here
+            break
+        if len(norm) > 15:  # only track meaningful lines
+            seen.add(norm)
+        clean_lines.append(line)
+
+    return "\n".join(clean_lines)
+
+
+def _resolve_tool_name(action_text: str, tool_names: list[str]) -> str:
+    """Extract the actual tool name from an Action line that may contain Chinese description.
+
+    Example inputs → outputs:
+        "rag_search" → "rag_search"
+        "使用 rag_search 搜索" → "rag_search"
+        "调用 mcp__tavily-mcp__tavily_search 查询" → "mcp__tavily-mcp__tavily_search"
+        "搜索文档" → "" (no tool found)
+    """
+    # Already a clean single identifier
+    if re.match(r'^[a-zA-Z_][a-zA-Z0-9_\-/]*$', action_text):
+        if tool_names:
+            if action_text in tool_names:
+                return action_text
+            # Fuzzy: unique tool ending with the model's text
+            # ("tavily_search" → "mcp__tavily-mcp__tavily_search")
+            matches = [t for t in tool_names if t.endswith(action_text)]
+            if len(matches) == 1:
+                return matches[0]
+            return ""
+        return action_text
+
+    # Find tool-like patterns in the text: lowercase_with_underscores, possibly with __ or /
+    candidates = re.findall(r'[a-zA-Z_][a-zA-Z0-9_\-/]{2,}', action_text)
+    for c in candidates:
+        # Must contain underscore (real tools look like rag_search, mcp__xxx__yyy)
+        if '_' in c:
+            if tool_names:
+                if c in tool_names:
+                    return c
+            else:
+                return c
+
+    # Last resort: pick the first ascii word
+    for c in candidates:
+        if tool_names:
+            if c in tool_names:
+                return c
+        else:
+            return c
+
+    # Fuzzy match: unique tool whose name contains the model's text.
+    # Handles cases like "tavily_search" → "mcp__tavily-mcp__tavily_search".
+    # The model's text must be a real suffix/substring, and only ONE tool may
+    # match (otherwise it's ambiguous and we refuse to guess).
+    if tool_names and len(action_text) >= 4 and '_' in action_text:
+        matches = [t for t in tool_names if t.endswith(action_text) or t.split('__')[-1] == action_text]
+        if len(matches) == 1:
+            return matches[0]
+
+    return ""
+
+
+def parse_action_input(input_str: str) -> dict:
+    """Parse action input string into a dict. Tries JSON first, then key=value."""
+    # Try JSON
+    try:
+        return json.loads(input_str)
+    except json.JSONDecodeError:
+        pass
+
+    # Try to extract JSON from within the string
+    json_match = re.search(r'\{[^{}]*\}', input_str)
+    if json_match:
+        try:
+            return json.loads(json_match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    # Fallback: treat as raw string
+    if input_str:
+        return {"query": input_str}
+
+    return {}
+
+
+def extract_final_answer(text: str) -> Optional[str]:
+    """Extract the final answer from text if present."""
+    from agentic_rag.services.llm.base import strip_reasoning
+    text = strip_reasoning(text)
+    match = re.search(r'Final Answer:\s*(.+)', text, re.DOTALL)
+    if match:
+        return match.group(1).strip()
+    return None
+
+
+def is_final_answer(text: str) -> bool:
+    """Check if the text contains a Final Answer marker."""
+    return "Final Answer:" in text
+
+
+def format_observation(tool_name: str, result: str, error: Optional[str] = None) -> str:
+    """Format a tool execution result as an Observation."""
+    if error:
+        return f"Observation: Error executing '{tool_name}': {error}"
+    # Truncate very long results — keeps the ReAct prompt compact so the
+    # model has less material to over-analyze on the next turn.
+    if len(result) > 1500:
+        result = result[:1500] + "... (truncated)"
+    return f"Observation: {result}"

agentic_rag/agent/react_prompt.py

@@ -0,0 +1,76 @@
+"""ReAct prompt builder — delegates to centralized prompts module.
+
+v2: Compact tool descriptions, Chinese-first with English fallback.
+"""
+
+from agentic_rag.config.prompts import Prompts
+
+# Legacy alias — still used by router.py and react_engine.py
+SYSTEM_PROMPT = Prompts.react_system()
+
+
+def build_react_prompt(
+    tools_description: str,
+    memory_context: str = "",
+) -> str:
+    """Build the ReAct system prompt with tool descriptions and conversation history.
+
+    Uses the Chinese-first prompt by default. Call ``build_react_prompt_en()``
+    for the English variant.
+    """
+    return SYSTEM_PROMPT.format(
+        tools_description=tools_description,
+        memory_context=memory_context or "(无历史)",
+    )
+
+
+def build_react_prompt_en(
+    tools_description: str,
+    memory_context: str = "",
+) -> str:
+    """Build the English variant of the ReAct system prompt."""
+    return Prompts.react_system_en().format(
+        tools_description=tools_description,
+        memory_context=memory_context or "(no history)",
+    )
+
+
+def build_tools_description(tools) -> str:
+    """Build a compact text description of available tools.
+
+    Format (one line per tool + compact param list):
+        rag_search: 搜索知识库
+          query (required): 搜索关键词
+          top_k: 返回数量 [default: 5]
+    """
+    lines = []
+    for tool in tools:
+        # Handle both ToolDefinition/Pydantic model and plain dict
+        if hasattr(tool, 'name'):
+            name = tool.name
+            desc = tool.description
+            params = tool.parameters
+        else:
+            name = tool.get("name", "unknown")
+            desc = tool.get("description", "")
+            params = tool.get("parameters", {})
+
+        params_props = params.get("properties", {}) if isinstance(params, dict) else {}
+        if isinstance(params_props, dict) and params_props:
+            required_params = params.get("required", []) if isinstance(params, dict) else []
+            param_strs = []
+            for pname, pinfo in params_props.items():
+                req_mark = " (必填)" if pname in required_params else ""
+                pdesc = pinfo.get("description", "") if isinstance(pinfo, dict) else str(pinfo)
+                if isinstance(pinfo, dict) and "default" in pinfo:
+                    pdesc += f" [默认: {pinfo['default']}]"
+                if isinstance(pinfo, dict) and "enum" in pinfo:
+                    pdesc += f" (可选: {', '.join(str(v) for v in pinfo['enum'])})"
+                param_strs.append(f"  {pname}: {pdesc}{req_mark}")
+            params_block = "\n".join(param_strs)
+        else:
+            params_block = "  (无参数)"
+
+        lines.append(f"{name}: {desc}\n{params_block}")
+
+    return "\n".join(lines)

agentic_rag/agent/router.py

@@ -0,0 +1,135 @@
+"""Agent Router — lightweight query analysis to select the right tool set.
+
+With a single ReAct prompt, the router's job is simply to decide which tools
+to give the agent based on the query. The agent itself decides how to use them.
+"""
+
+import re
+
+from agentic_rag.agent.react_engine import ReActEngine
+from agentic_rag.agent.react_prompt import SYSTEM_PROMPT
+from agentic_rag.services.llm.base import BaseLLMProvider
+
+
+class AgentRouter:
+    """Routes queries by selecting the appropriate tool subset.
+
+    The core insight: one agent, one prompt, variable tool sets.
+    The ReAct engine decides which tool to invoke — the router just
+    provides the right tools for the job.
+    """
+
+    # Tool subsets for different query types.
+    # Web search is built-in (DuckDuckGo fallback); additional fetch and code
+    # execution tools are provided via MCP servers.
+    TOOL_SETS = {
+        "chat":     ["rag_search", "web_search"],
+        "rag":      ["rag_search", "rag_ingest"],
+        "research": ["rag_search", "web_search"],
+        "media":    ["image_understand", "audio_transcribe", "video_analyze"],
+        "meta":     [],  # No tools needed for meta questions about the agent itself
+    }
+
+    # Keyword hints for routing
+    MODE_HINTS = {
+        "rag": ["搜索", "查找", "检索", "知识库", "文档", "search", "find", "retrieve"],
+        "research": ["研究", "调查", "报告", "深入", "research", "investigate", "comprehensive"],
+        "media": ["图片", "图像", "视频", "音频", "语音", "image", "picture", "video", "audio"],
+        "meta": ["你是谁", "你是什么", "你能做什么", "你的功能", "自我介绍", "who are you", "what are you", "introduce yourself"],
+    }
+
+    def __init__(self, llm: BaseLLMProvider, tool_registry):
+        self.llm = llm
+        self.tool_registry = tool_registry
+        # Read native-tool-calling preference from the active LLM provider config
+        try:
+            from agentic_rag.config.settings import get_settings
+            settings = get_settings()
+            provider_cfg = settings.llm_providers.get(settings.default_provider)
+            self._native_tool_calls = provider_cfg.enable_native_tool_calls if provider_cfg else True
+        except Exception:
+            self._native_tool_calls = True
+
+    async def route(
+        self,
+        query: str,
+        has_media: bool = False,
+        preferred_mode: str | None = None,
+    ) -> ReActEngine:
+        """Route a query to a ReActEngine with the right tool set.
+
+        Args:
+            query: User's query text.
+            has_media: Whether media is attached to the input.
+            preferred_mode: Force a specific tool set.
+
+        Returns:
+            Configured ReActEngine ready to execute.
+        """
+        # Force media tools when media is present
+        if has_media:
+            mode = "media"
+        elif preferred_mode and preferred_mode in self.TOOL_SETS:
+            mode = preferred_mode
+        else:
+            mode = self._classify(query)
+
+        tool_names = self.TOOL_SETS.get(mode, self.TOOL_SETS["chat"])
+        tools = self.tool_registry.filter(tool_names)
+
+        # MCP tools (web search etc.) — available in all modes except meta.
+        # Meta questions about the agent itself don't need external tools.
+        if mode != "meta":
+            mcp_tools = self.tool_registry.get_mcp_tools()
+            seen = {t.name for t in tools}
+            for mt in mcp_tools:
+                if mt.name not in seen:
+                    tools.append(mt)
+
+        # Freshness-sensitive queries receive only tools that advertise a
+        # fresh-information capability. MCP tools are selected by semantic
+        # metadata rather than by a specific provider or server name.
+        requires_live_web = self._requires_live_web(query)
+        if requires_live_web:
+            live_search_tools = [
+                t for t in tools if t.has_capability("fresh_information")
+            ]
+            external_search_tools = [
+                t for t in live_search_tools if t.source == "mcp"
+            ]
+            # Prefer any external MCP search provider as a class; the built-in
+            # DDGS search remains a fallback only when no MCP search capability
+            # is connected. No provider or server name is hard-coded here.
+            tools = external_search_tools or live_search_tools
+
+        return ReActEngine(
+            llm=self.llm,
+            tools=tools,
+            system_prompt_template=SYSTEM_PROMPT,
+            max_iterations=8 if mode == "research" else 4,
+            enable_native_tool_calls=self._native_tool_calls,
+            require_tool_call=requires_live_web,
+        )
+
+    @staticmethod
+    def _requires_live_web(query: str) -> bool:
+        """Return True for queries whose answer depends on current events."""
+        query_lower = query.lower()
+        live_hints = (
+            "最新", "目前", "现在", "今日", "今天", "实时", "结果", "冠军",
+            "四强", "4强", "决赛", "半决赛", "排名", "比分", "现任",
+            "latest", "current", "today", "result", "winner", "semifinal",
+            "semi-final", "ranking", "score",
+        )
+        # A contemporary year is also a strong signal. This intentionally uses
+        # a broad lower bound so deployments don't need annual keyword updates.
+        has_recent_year = any(int(y) >= 2025 for y in re.findall(r"\b20\d{2}\b", query_lower))
+        return has_recent_year or any(hint in query_lower for hint in live_hints)
+
+    def _classify(self, query: str) -> str:
+        """Simple keyword-based classification."""
+        query_lower = query.lower()
+        for mode, keywords in self.MODE_HINTS.items():
+            if any(kw in query_lower for kw in keywords):
+                return mode
+        return "chat"

agentic_rag/config/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/config/defaults.yaml

@@ -0,0 +1,80 @@
+# Agentic RAG Default Configuration
+
+app_name: agentic_rag
+debug: false
+log_level: INFO
+
+default_provider: openai
+
+# LLM Providers
+llm_providers:
+  openai:
+    api_key: "${OPENAI_API_KEY}"
+    api_base: "https://api.openai.com/v1"
+    model: "gpt-4o"
+    max_tokens: 4096
+    temperature: 0.7
+    vision_model: "gpt-4o"
+
+  claude:
+    api_key: "${ANTHROPIC_API_KEY}"
+    api_base: "https://api.anthropic.com"
+    model: "claude-sonnet-4-20250514"
+    max_tokens: 4096
+    temperature: 0.7
+    vision_model: "claude-sonnet-4-20250514"
+
+  local:
+    api_key: ""
+    api_base: "http://localhost:11434/v1"
+    model: "llama3"
+    max_tokens: 4096
+    temperature: 0.7
+    vision_model: ""
+
+# Embedding Model (for RAG vector search)
+# Can use a different provider from the LLM
+embedding:
+  provider: "openai"                   # Which provider config to use for API key
+  model: "text-embedding-3-small"      # Embedding model name
+  dim: 1536                             # Vector dimension (must match Milvus)
+  api_key: ""                           # Override API key (empty = reuse provider's)
+  api_base: ""                          # Override API base (empty = reuse provider's)
+  batch_size: 100                       # Max texts per batch
+
+# Milvus
+milvus:
+  host: "localhost"
+  port: 19530
+  collection_prefix: "agentic_rag"
+  dim: 1536
+  index_type: "IVF_FLAT"
+  metric_type: "COSINE"
+
+# Memory
+memory:
+  short_term_max_tokens: 8000
+  long_term_top_k: 10
+  working_memory_max_keys: 50
+
+# Session
+session:
+  ttl_seconds: 3600
+  cleanup_interval_seconds: 300
+
+# API
+api:
+  host: "0.0.0.0"
+  port: 8000
+  cors_origins: ["*"]
+  rate_limit_per_minute: 60
+
+# Voice
+voice:
+  stt_model: "whisper-1"
+  tts_provider: "edge"
+  tts_voice: "zh-CN-XiaoxiaoNeural"
+  sample_rate: 16000
+
+# MCP Servers (external)
+mcp_servers: {}

agentic_rag/config/prompts.py

@@ -0,0 +1,231 @@
+"""Centralized prompts for Agentic RAG.
+
+All prompt text lives here so they can be reviewed, tuned, and versioned
+in one place.  Every consumer imports from this module instead of embedding
+prompt strings inline.
+
+Design principles (aligned with LangChain / Claude / NeMo best practices):
+- Strong directives: MUST / 禁止 over fuzzy "should"
+- Thought length cap: prevents verbose narration loops
+- Anti-repetition rules in prompt, not just post-processing
+- Few-shot examples for format grounding
+- Chinese-first output with English fallback
+
+Usage::
+
+    from agentic_rag.config.prompts import Prompts
+    prompt = Prompts.react_system().format(tools_description="...", memory_context="...")
+"""
+
+from datetime import datetime, timezone
+
+
+class Prompts:
+    """Namespace for all prompt templates used across the project."""
+
+    # ═══════════════════════════════════════════════════════════════
+    # ReAct Agent (agent/react_prompt.py)
+    # ═══════════════════════════════════════════════════════════════
+
+    @staticmethod
+    def react_system() -> str:
+        """ReAct system prompt — pure text mode, no function calling required.
+
+        The model MUST output ReAct text format. The react_parser.py parses
+        Thought/Action/Action Input markers. No native tool calling needed.
+
+        Key design:
+        - Opening instruction forces Thought: as the FIRST line.
+        - ≤20 char Thought cap with positive/negative examples.
+        - Few-shot example grounds the expected rhythm.
+        - "开始!" marker signals the model to start immediately.
+        """
+        _today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        return (
+            f"你是信息检索智能体。{_today}\n"
+            f"用中文回答，除非用户使用英文。\n\n"
+
+            f"## 输出格式（严格按此顺序）\n"
+            f"Thought: <动作，≤50字>\n"
+            f"Action: <工具名>\n"
+            f"Action Input: <JSON>\n"
+            f"[等待工具返回 Observation]\n"
+            f"... (可重复)\n"
+            f"Final Answer: <答案>\n\n"
+
+            f"## 示例\n"
+            f"用户: 什么是向量数据库？\n"
+            f"Thought: 查询知识库\n"
+            f"Action: rag_search\n"
+            f"Action Input: {{{{'query': '向量数据库'}}}}\n"
+            f"Observation: [R1] 向量数据库存储和检索向量嵌入...\n"
+            f"Thought: 信息充足\n"
+            f"Final Answer: 向量数据库通过ANN算法实现高维向量的相似性搜索。"
+            f"📚 参考来源\\n[R1] ...\n\n"
+            f"用户: 你是谁？\n"
+            f"Thought: 确认身份\n"
+            f"Final Answer: 我是信息检索智能体，基于ReAct架构，可以检索知识库、调用工具来回答你的问题。\n\n"
+            f"用户: 你能做什么？\n"
+            f"Thought: 直接回答\n"
+            f"Final Answer: 我可以帮你检索知识库、回答问题、调用外部工具（如网络搜索）、处理多模态内容（文本/图片/音频/视频），以及进行多轮推理来解答复杂问题。\n\n"
+
+            f"## 规则\n"
+            f"1. 你的第一条消息必须以 \"Thought:\" 开头。禁止输出开场白、分析、或问候语。\n"
+            f"2. 知识类问题先调用 rag_search；但涉及当前日期之后或近期发生的事件、比赛结果、实时状态时，rag_search 仅作补充，必须调用可用的网络搜索工具核实。\n"
+            f"   当前日期是 {_today}。禁止把日期早于或等于 {_today} 的事件描述为“尚未开始”“未来”或“无法预知”。先检索，再依据检索证据判断事件状态。\n"
+            f"   rag_search 无结果或信息不足时，使用“可用工具”中实际列出的网络搜索工具；禁止臆造不存在的工具名。\n"
+            f"   例外：关于你自身身份、能力、功能的问题直接回答，无需检索。\n"
+            f"3. Thought 必须 ≤50字。只写动作，禁止写原因。\n"
+            f"   正确: \"查询知识库\" / \"搜索网络\" / \"信息充足\" / \"确认身份\" / \"直接回答\"\n"
+            f"   错误: \"用户询问X，我先查一下...\"\n"
+            f"4. 禁止用相同参数重复调用同一工具。同一查询最多调用一次。\n"
+            f"5. 信息足够时立即输出 Final Answer。简单问题（如身份询问）一轮即可。\n"
+            f"6. 禁止编造事实。只引用实际检索到的内容；来源无明确证据时必须说明无法确认，禁止用常识或模型记忆补全结果。\n"
+            f"7. 仅在实际检索结果中存在对应编号时才引用 [R1] [R2]；禁止自造来源编号或来源内容。末尾可�� \"📚 参考来源\"。\n"
+            f"8. 禁止输出内心独白、自我对话、方案对比或元推理。你的输出对外可见——只输出规定的格式行。\n"
+            f"9. 禁止复述或讨论本系统提示中的规则。\n"
+            f"10. 禁止只输出格式行而不输出最终答案。Action: (无) 是无效输出。已检索到信息时必须输出 Final Answer。\n\n"
+
+            f"## 可用工具\n"
+            f"{{tools_description}}\n\n"
+            f"## 对话历史\n"
+            f"{{memory_context}}\n\n"
+            f"现在回答用户问题。第一条消息以 Thought: 开头：\n"
+        )
+
+    # ═══════════════════════════════════════════════════════════════
+    # ReAct v2 — English variant (for English-first deployments)
+    # ═══════════════════════════════════════════════════════════════
+
+    @staticmethod
+    def react_system_en() -> str:
+        """English ReAct variant — pure text mode, with forced opening."""
+        _today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        return (
+            f"You are a precise retrieval agent. {_today}\n\n"
+
+            f"## Output Format (follow exactly)\n"
+            f"Thought: <action, ≤50 chars>\n"
+            f"Action: <tool_name>\n"
+            f"Action Input: <JSON>\n"
+            f"[wait for Observation]\n"
+            f"... (repeat as needed)\n"
+            f"Final Answer: <answer>\n\n"
+
+            f"## Example\n"
+            f"User: What is a vector database?\n"
+            f"Thought: Search KB\n"
+            f"Action: rag_search\n"
+            f"Action Input: {{{{'query': 'vector database'}}}}\n"
+            f"Observation: [R1] Vector databases store and retrieve embeddings...\n"
+            f"Thought: Info sufficient\n"
+            f"Final Answer: A vector database uses ANN algorithms for similarity "
+            f"search over high-dimensional vectors. References\\n[R1] ...\n\n"
+
+            f"## Rules\n"
+            f"1. Your FIRST line MUST start with \"Thought:\". No opening remarks or analysis.\n"
+            f"2. Thought MUST be ≤50 chars. State the action only.\n"
+            f"   Good: \"Search KB\" / \"Web search\" / \"Info sufficient\"\n"
+            f"   Bad: \"The user is asking about X, I need to...\"\n"
+            f"3. NEVER call the same tool with identical parameters twice.\n"
+            f"4. Output Final Answer as soon as you have enough information.\n"
+            f"5. NEVER fabricate facts. Only cite what you actually retrieved.\n"
+            f"6. Cite sources as [R1] [R2], append \" References\".\n\n"
+
+            f"## Tools\n"
+            f"{{tools_description}}\n\n"
+            f"## History\n"
+            f"{{memory_context}}\n\n"
+            f"Answer the user now. Start with Thought: on the first line:\n"
+        )
+
+    # ═══════════════════════════════════════════════════════════════
+    # Knowledge Graph — Entity Extraction (graph/builder.py)
+    # ═══════════════════════════════════════════════════════════════
+
+    KG_ENTITY_EXTRACTION = """从技术文本中提取实体和关系。只输出 JSON，禁止输出思考过程或解释。
+
+## 实体类型
+TECHNOLOGY  — 技术/框架/语言/工具
+ALGORITHM  — 算法/方法
+COMPONENT  — 组件/模块/接口
+CONCEPT    — 技术概念/设计模式
+PROTOCOL   — 协议/规范
+PARAMETER  — 配置参数/性能指标
+STANDARD   — 标准/规范
+PRODUCT    — 产品/系统/平台
+ORGANIZATION — 组织/公司/团队
+
+## 关系类型
+depends_on/uses | part_of/contains | implements/provides | configures/controls | compatible_with/integrates
+
+## 规则
+- 3-8 个实体，2-6 个关系
+- entity name 用原文术语
+- 只输出 JSON
+
+```json
+{{
+  "entities": [{{"name": "Kubernetes", "type": "TECHNOLOGY", "description": "容器编排平台"}}],
+  "relationships": [{{"source": "Kubernetes", "target": "Docker", "keywords": "使用,管理", "description": "K8s管理Docker容器"}}]
+}}
+```
+
+文本: {text}
+JSON:"""
+
+    # ═══════════════════════════════════════════════════════════════
+    # Multimodal Processors (processors/image_processor.py,
+    #                        processors/multimodal_processors.py)
+    # ═══════════════════════════════════════════════════════════════
+
+    IMAGE_CAPTION = (
+        "Describe this image concisely: key objects, text, context, and notable visual elements. "
+        "Keep within 3-5 sentences."
+    )
+
+    TABLE_ANALYSIS = (
+        "Analyze this table concisely. State: (1) what data it contains, "
+        "(2) 1-2 key trends, (3) any outliers or important values. "
+        "Table:\n{table_content}"
+    )
+
+    LATEX_TO_PLAIN_TEXT = (
+        "Convert this LaTeX formula to a plain-English description "
+        "that a non-expert can understand:\n\n{latex}"
+    )
+
+    VIDEO_KEYFRAME_DESCRIPTION = "Describe keyframe {frame_num} of this video."
+
+    # ═══════════════════════════════════════════════════════════════
+    # Pipeline — RAG query & media captioning (pipeline.py)
+    # ═══════════════════════════════════════════════════════════════
+
+    RAG_QUERY_ANSWER = (
+        "Answer the question using the provided context. Cite sources as [Source N]. "
+        "If the context is insufficient, say so directly — do not guess.\n\n"
+        "Context:\n{context}\n\n"
+        "Question: {question}\n\n"
+        "Answer:"
+    )
+
+    MEDIA_CAPTION_ZH = (
+        "用中文简洁描述此内容。包括关键对象、场景、文字和整体语境。3-5句话。"
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Backward-compatible aliases (for gradual migration)
+# ═══════════════════════════════════════════════════════════════════
+
+# ReAct prompt — keep the old API working
+SYSTEM_PROMPT = None  # set below after class definition
+
+
+def _init_legacy_aliases():
+    """Populate module-level aliases so existing imports still work."""
+    global SYSTEM_PROMPT
+    SYSTEM_PROMPT = Prompts.react_system()
+
+
+_init_legacy_aliases()

agentic_rag/config/settings.py

@@ -0,0 +1,364 @@
+"""Configuration management with Pydantic Settings."""
+
+import os
+import re
+from pathlib import Path
+
+# Mute gRPC "too_many_pings" noise from Milvus Lite.
+# Must be set BEFORE any pymilvus import — settings.py is loaded first.
+os.environ.setdefault("GRPC_VERBOSITY", "ERROR")
+os.environ.setdefault("GRPC_TRACE", "none")
+os.environ.setdefault("GRPC_KEEPALIVE_TIME_MS", "60000")
+from typing import Optional
+
+import yaml
+from pydantic import BaseModel, Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+_PREFIX = ""
+
+
+class LLMProviderConfig(BaseSettings):
+    """Configuration for a single LLM provider."""
+    api_key: str = ""
+    api_base: str = ""
+    model: str = ""
+    max_tokens: int = 4096  # output limit per LLM call
+    temperature: float = 0.7
+    frequency_penalty: float = 0.3   # discourage token repetition (0-2)
+    presence_penalty: float = 0.3    # discourage topic looping (0-2)
+    vision_model: str = ""  # Model for vision tasks
+    enable_native_tool_calls: bool = True  # False → pure ReAct text mode
+
+
+class EmbeddingConfig(BaseModel):
+    """Dedicated embedding model configuration.
+
+    Separated from LLM because:
+    - Embedding may use a different provider (e.g., Claude for LLM + OpenAI for embeddings)
+    - Self-hosted embedding services have their own API endpoint
+    - The dimension must match the vector store schema
+    """
+    provider: str = "openai"                # Which LLM provider config to reuse, or "custom"
+    model: str = "text-embedding-3-small"   # Embedding model name
+    model_type: str = "text"                # "text" | "clip" | "multimodal"
+    dim: int = 1536                          # Vector dimension (1536 for text-embedding-3-small)
+    api_key: str = ""                        # Override API key (uses LLM provider's key if empty)
+    api_base: str = ""                       # Override API base (uses LLM provider's base if empty)
+    batch_size: int = 100                    # Max texts per embedding request
+
+
+class MilvusConfig(BaseSettings):
+    """Milvus vector database configuration."""
+    host: str = "localhost"
+    port: int = 19530
+    collection_prefix: str = "agentic_rag"
+    dim: int = 1536
+    index_type: str = "IVF_FLAT"
+    metric_type: str = "COSINE"
+
+
+class MemoryConfig(BaseSettings):
+    """Memory configuration."""
+    short_term_max_tokens: int = 8000
+    long_term_top_k: int = 10
+    working_memory_max_keys: int = 50
+
+
+class SessionConfig(BaseSettings):
+    """Session configuration."""
+    ttl_seconds: int = 3600
+    cleanup_interval_seconds: int = 300
+
+
+class APIConfig(BaseSettings):
+    """API server configuration."""
+    host: str = "0.0.0.0"
+    port: int = 8000
+    cors_origins: list[str] = ["*"]
+    rate_limit_per_minute: int = 60
+
+
+class OCRConfig(BaseSettings):
+    """PaddleOCR-VL / vLLM OCR configuration."""
+    enabled: bool = True
+    api_base: str = "http://localhost:8000/v1"
+    model: str = "PaddlePaddle/PaddleOCR-VL"
+    api_key: str = "not-needed"
+    max_pages: int = 50  # max pages to OCR per document
+
+
+class WeChatWorkGatewayConfig(BaseSettings):
+    """企业微信自建应用 gateway configuration.
+
+    Reference: https://developer.work.weixin.qq.com/document/path/90238
+    """
+    enabled: bool = False
+    corp_id: str = ""           # 企业ID (myCorpId)
+    token: str = ""             # 回调 Token
+    encoding_aes_key: str = ""  # 回调 EncodingAESKey (43 chars)
+    agent_id: str = ""          # 应用 AgentId
+    secret: str = ""            # 应用 Secret (用于获取 access_token 推送消息)
+    webhook_path: str = "/gateway/wechat_work"
+
+
+class QQBotGatewayConfig(BaseSettings):
+    """QQ Bot (官方) gateway configuration.
+
+    沙箱模式: wss://sandbox.api.sgroup.qq.com/websocket
+    正式环境: wss://api.sgroup.qq.com/websocket
+    """
+    enabled: bool = False
+    app_id: str = ""            # BotAppID
+    app_secret: str = ""        # BotSecret (用于获取 access_token)
+    sandbox: bool = True        # True=沙箱环境, False=正式环境
+    webhook_path: str = "/gateway/qqbot"  # 用于查看 Bot 状态
+
+
+class DingTalkGatewayConfig(BaseSettings):
+    """钉钉 bot gateway configuration."""
+    enabled: bool = False
+    app_key: str = ""
+    app_secret: str = ""
+    webhook_path: str = "/gateway/dingtalk"
+
+
+class GatewayConfig(BaseSettings):
+    """Messaging platform gateway configuration."""
+    enabled: bool = False
+    response_mode: str = "sync"    # "sync" = reply in webhook response; "async" = push via API
+    max_reply_length: int = 2000
+    wechat_work: WeChatWorkGatewayConfig = Field(default_factory=WeChatWorkGatewayConfig)
+    dingtalk: DingTalkGatewayConfig = Field(default_factory=DingTalkGatewayConfig)
+    qqbot: QQBotGatewayConfig = Field(default_factory=QQBotGatewayConfig)
+
+
+class VoiceConfig(BaseSettings):
+    """Voice/STT/TTS configuration."""
+    # STT (Speech-to-Text)
+    stt_provider: str = "sensevoice"   # "sensevoice" | "whisper" | "openai"
+    stt_model: str = "sensevoice"      # sensevoice | base | small | whisper-1
+    stt_api_base: str = "http://localhost:8000"  # ASR server URL (POST /asr)
+    stt_api_key: str = ""
+    stt_language: str = "auto"         # auto | zh | en | ja | ko | yue
+    # TTS (Text-to-Speech)
+    tts_provider: str = "qwen"         # "qwen" | "kokoro" | "edge" | "openai"
+    tts_model: str = "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign"
+    tts_api_base: str = "http://localhost:8091"
+    tts_api_key: str = "EMPTY"
+    tts_task_type: str = "VoiceDesign"  # VoiceDesign | CustomVoice | Base (qwen)
+    tts_instructions: str = "A clear, professional voice in Chinese"  # qwen
+    tts_language: str = "Chinese"       # qwen language / kokoro lang code (zh/en/ja)
+    tts_speaker: str = ""               # qwen CustomVoice speaker
+    tts_voice: str = "zh-CN-XiaoxiaoNeural"  # Edge-TTS fallback / kokoro voice (zf_xiaoyi)
+    tts_speed: float = 1.0             # kokoro playback speed
+    tts_response_format: str = "wav"    # wav | mp3 | flac | pcm
+    sample_rate: int = 16000
+
+
+def _parse_llm_providers_from_env() -> dict[str, LLMProviderConfig]:
+    """Manually extract LLM provider configs from environment + .env file.
+
+    pydantic-settings cannot auto-populate ``dict[str, Model]`` from env vars
+    because the dict keys are dynamic.  We scan for the pattern::
+
+        RAG__LLM_PROVIDERS__<NAME>__<FIELD>=<value>
+
+    in both ``os.environ`` AND the ``.env`` file (since pydantic-settings reads
+    ``.env`` internally but does NOT export into ``os.environ``).
+    """
+    providers: dict[str, dict] = {}
+    pattern = re.compile(rf"^{re.escape(_PREFIX)}_?LLM_PROVIDERS__([A-Z0-9]+)__([A-Z_]+)$")
+
+    def _collect(source: dict[str, str]) -> None:
+        for key, value in source.items():
+            m = pattern.match(key)
+            if not m:
+                continue
+            provider_name = m.group(1).lower()
+            field_name = m.group(2).lower()
+            providers.setdefault(provider_name, {})[field_name] = value
+
+    # 1. os.environ (exported vars + python-dotenv if loaded externally)
+    _collect(dict(os.environ))
+
+    # 2. .env file (pydantic-settings reads it internally; we must too)
+    env_path = Path(".env")
+    if env_path.exists():
+        env_vars = _parse_dotenv(env_path)
+        _collect(env_vars)
+
+    return {name: LLMProviderConfig(**fields) for name, fields in providers.items()}
+
+
+def _parse_mcp_servers_from_env() -> dict[str, dict]:
+    """Extract MCP server configs.
+
+    Priority:
+    1. ``mcp_servers.json`` — standard MCP config (like Claude Code)
+    2. ``mcp_servers.yaml`` — YAML alternative
+    3. Environment variables: ``RAG__MCP_SERVERS__<NAME>__<FIELD>=<value>``
+    """
+    # 1. Try JSON config (standard MCP format)
+    json_path = Path("mcp_servers.json")
+    if json_path.exists():
+        try:
+            import json as _json
+            with open(json_path) as f:
+                data = _json.load(f)
+            servers_raw = data.get("mcpServers", {})
+            result: dict[str, dict] = {}
+            for name, cfg in servers_raw.items():
+                if cfg.get("disabled", False):
+                    continue
+                args = cfg.get("args", [])
+                # args can be a list or string
+                if isinstance(args, list):
+                    args = " ".join(args)
+                result[name.lower()] = {
+                    "command": cfg.get("command", ""),
+                    "args": args,
+                }
+                # Preserve the standard MCP nested env mapping. The startup
+                # code merges it with the process environment before spawning
+                # the server; flattening these keys loses credentials such as
+                # TAVILY_API_KEY because startup only reads config["env"].
+                env = cfg.get("env", {})
+                if isinstance(env, dict) and env:
+                    result[name.lower()]["env"] = {
+                        str(k): str(v) for k, v in env.items() if v
+                    }
+            if result:
+                return result
+        except Exception:
+            pass
+
+    # 2. Try YAML config
+    yaml_path = Path("mcp_servers.yaml")
+    if yaml_path.exists():
+        try:
+            import yaml as _yaml
+            with open(yaml_path) as f:
+                data = _yaml.safe_load(f) or {}
+            if isinstance(data, dict) and "servers" in data:
+                return {k.lower(): v for k, v in data["servers"].items()}
+        except Exception:
+            pass
+
+    # 3. Fallback: env vars
+    servers: dict[str, dict] = {}
+    pattern = re.compile(rf"^{re.escape(_PREFIX)}_?MCP_SERVERS__([A-Z0-9]+)__([A-Z_]+)$")
+
+    def _collect(source: dict[str, str]) -> None:
+        for key, value in source.items():
+            m = pattern.match(key)
+            if not m:
+                continue
+            server_name = m.group(1).lower()
+            field_name = m.group(2).lower()
+            servers.setdefault(server_name, {})[field_name] = value
+
+    _collect(dict(os.environ))
+    env_path = Path(".env")
+    if env_path.exists():
+        _collect(_parse_dotenv(env_path))
+
+    return servers
+
+
+def _parse_dotenv(path: Path) -> dict[str, str]:
+    """Parse a .env file into a dict (without touching os.environ)."""
+    result: dict[str, str] = {}
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "=" in line:
+                k, v = line.split("=", 1)
+                result[k.strip()] = v.strip()
+    return result
+
+
+class Settings(BaseSettings):
+    """Root settings for Agentic RAG."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+        env_prefix="",
+        extra="ignore",
+    )
+
+    # App
+    app_name: str = "agentic_rag"
+    debug: bool = False
+    log_level: str = "INFO"
+
+    # LLM
+    default_provider: str = "openai"
+    llm_providers: dict[str, LLMProviderConfig] = Field(default_factory=dict)
+
+    # Embedding (dedicated config — may differ from LLM provider)
+    embedding: EmbeddingConfig = Field(default_factory=EmbeddingConfig)
+
+    # Services
+    milvus: MilvusConfig = Field(default_factory=MilvusConfig)
+    memory: MemoryConfig = Field(default_factory=MemoryConfig)
+    session: SessionConfig = Field(default_factory=SessionConfig)
+    api: APIConfig = Field(default_factory=APIConfig)
+    ocr: OCRConfig = Field(default_factory=OCRConfig)
+    voice: VoiceConfig = Field(default_factory=VoiceConfig)
+
+    # Database
+    db_path: str = "data/agentic_rag.db"
+
+    # Gateway (messaging platforms)
+    gateway: GatewayConfig = Field(default_factory=GatewayConfig)
+
+    # MCP
+    mcp_servers: dict[str, dict] = Field(default_factory=dict)
+
+    # Workspace
+    workspace_dir: str = "workspace"
+
+    @model_validator(mode="after")
+    def _inject_dict_fields(self):
+        """Populate dict fields from env vars (pydantic-settings can't do dynamic keys)."""
+        if not self.llm_providers:
+            self.llm_providers = _parse_llm_providers_from_env()
+        if not self.mcp_servers:
+            self.mcp_servers = _parse_mcp_servers_from_env()
+        return self
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str | Path) -> "Settings":
+        """Load settings from a YAML file, then overlay env vars."""
+        path = Path(yaml_path)
+        if path.exists():
+            with open(path) as f:
+                data = yaml.safe_load(f) or {}
+        else:
+            data = {}
+        return cls(**data)
+
+
+# Global settings instance (initialized at startup)
+_settings: Optional[Settings] = None
+
+
+def get_settings() -> Settings:
+    """Get the global settings instance."""
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings
+
+
+def init_settings(**kwargs) -> Settings:
+    """Initialize settings (called at app startup)."""
+    global _settings
+    _settings = Settings(**kwargs)
+    return _settings

agentic_rag/core/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/core/mcp/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/core/mcp/client.py

@@ -0,0 +1,214 @@
+"""MCP (Model Context Protocol) Client.
+
+Connects to external MCP servers and exposes their tools to the agent.
+"""
+
+import asyncio
+import json
+from typing import Any, Optional
+
+from agentic_rag.orchestration.l1_tools.base import BaseTool
+
+
+class MCPTool(BaseTool):
+    """Proxy tool that wraps an MCP server tool."""
+
+    _CAPABILITY_HINTS = {
+        "web_search": (
+            "search", "web", "internet", "browser", "browse", "news",
+            "搜索", "网页", "网络", "新闻",
+        ),
+        "fresh_information": (
+            "search", "web", "internet", "browser", "browse", "news",
+            "current", "latest", "real-time", "realtime", "搜索", "网页",
+            "网络", "新闻", "最新", "实时",
+        ),
+    }
+
+    def __init__(self, name: str, description: str, parameters_schema: dict,
+                 server_name: str, client: "MCPClient"):
+        self.name = f"mcp__{server_name}__{name}"
+        self.description = f"[MCP/{server_name}] {description}"
+        self.parameters_schema = parameters_schema
+        self.capabilities = self._infer_capabilities(name, description)
+        self.source = "mcp"
+        self._original_name = name
+        self._client = client
+        self.requires_confirmation = False
+
+    @classmethod
+    def _infer_capabilities(cls, name: str, description: str) -> frozenset[str]:
+        """Infer semantic capabilities from MCP tool metadata."""
+        metadata = f"{name} {description}".lower()
+        return frozenset(
+            capability
+            for capability, hints in cls._CAPABILITY_HINTS.items()
+            if any(hint in metadata for hint in hints)
+        )
+
+    async def execute(self, **kwargs) -> Any:
+        """Execute the MCP tool via the connected client."""
+        return await self._client.call_tool(self._original_name, kwargs)
+
+
+class MCPClient:
+    """MCP Client for connecting to external MCP servers.
+
+    Supports stdio transport (subprocess-based) for connecting to MCP servers.
+    """
+
+    def __init__(self):
+        self._connections: dict[str, dict] = {}  # server_name -> {process, tools}
+
+    @property
+    def connected_servers(self) -> list[str]:
+        return list(self._connections.keys())
+
+    async def connect_stdio(self, server_name: str, command: str,
+                             args: list[str] | None = None,
+                             env: dict[str, str] | None = None) -> list[MCPTool]:
+        """Connect to an MCP server via stdio subprocess.
+
+        Args:
+            server_name: Logical name for this server.
+            command: Command to launch the MCP server.
+            args: Arguments for the command.
+            env: Environment variables.
+
+        Returns:
+            List of MCPTool instances exposed by the server.
+        """
+        proc = await asyncio.create_subprocess_exec(
+            command, *(args or []),
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+
+        # Initialize MCP session
+        init_request = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "agentic_rag", "version": "0.1.0"},
+            },
+        }
+        await self._send_request(proc, init_request)
+
+        # Discover tools
+        tools_request = {
+            "jsonrpc": "2.0",
+            "id": 2,
+            "method": "tools/list",
+            "params": {},
+        }
+        response = await self._send_request(proc, tools_request)
+
+        tools = []
+        for tool_def in response.get("result", {}).get("tools", []):
+            tool = MCPTool(
+                name=tool_def["name"],
+                description=tool_def.get("description", ""),
+                parameters_schema=tool_def.get("inputSchema", {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                }),
+                server_name=server_name,
+                client=self,
+            )
+            tools.append(tool)
+
+        self._connections[server_name] = {
+            "process": proc,
+            "tools": {t._original_name: t for t in tools},
+            "next_id": 3,
+        }
+
+        return tools
+
+    async def call_tool(self, name: str, arguments: dict) -> str:
+        """Call an MCP tool by name.
+
+        Finds the correct connection by iterating over connected servers.
+        """
+        for server_name, conn in self._connections.items():
+            if name in conn["tools"]:
+                request = {
+                    "jsonrpc": "2.0",
+                    "id": conn["next_id"],
+                    "method": "tools/call",
+                    "params": {"name": name, "arguments": arguments},
+                }
+                conn["next_id"] += 1
+                response = await self._send_request(conn["process"], request)
+
+                content = response.get("result", {}).get("content", [])
+                if content:
+                    return "\n".join(
+                        c.get("text", str(c)) for c in content
+                        if isinstance(c, dict)
+                    )
+                return json.dumps(response.get("result", {}))
+
+        return f"MCP tool '{name}' not found on any connected server."
+
+    async def list_resources(self, server_name: str) -> list[dict]:
+        """List resources from an MCP server."""
+        conn = self._connections.get(server_name)
+        if not conn:
+            return []
+
+        request = {
+            "jsonrpc": "2.0",
+            "id": conn["next_id"],
+            "method": "resources/list",
+            "params": {},
+        }
+        conn["next_id"] += 1
+        response = await self._send_request(conn["process"], request)
+        return response.get("result", {}).get("resources", [])
+
+    async def read_resource(self, server_name: str, uri: str) -> Any:
+        """Read a resource from an MCP server."""
+        conn = self._connections.get(server_name)
+        if not conn:
+            return f"MCP server '{server_name}' not connected."
+
+        request = {
+            "jsonrpc": "2.0",
+            "id": conn["next_id"],
+            "method": "resources/read",
+            "params": {"uri": uri},
+        }
+        conn["next_id"] += 1
+        response = await self._send_request(conn["process"], request)
+        return response.get("result", {})
+
+    async def disconnect(self, server_name: str) -> None:
+        """Disconnect from an MCP server."""
+        conn = self._connections.pop(server_name, None)
+        if conn:
+            proc = conn["process"]
+            proc.stdin.close()
+            await proc.wait()
+
+    async def disconnect_all(self) -> None:
+        """Disconnect from all MCP servers."""
+        for name in list(self._connections.keys()):
+            await self.disconnect(name)
+
+    async def _send_request(self, proc: asyncio.subprocess.Process, request: dict) -> dict:
+        """Send a JSON-RPC request and receive the response."""
+        msg = json.dumps(request) + "\n"
+        proc.stdin.write(msg.encode())
+        await proc.stdin.drain()
+
+        line = await asyncio.wait_for(proc.stdout.readline(), timeout=30.0)
+        if line:
+            return json.loads(line.decode())
+        return {"error": "No response from MCP server"}

agentic_rag/core/mcp/server.py

@@ -0,0 +1,129 @@
+"""MCP (Model Context Protocol) Server.
+
+Exposes this system's tools and resources to external MCP clients via stdio.
+"""
+
+import asyncio
+import json
+import sys
+from typing import Any
+
+
+class MCPServer:
+    """Expose Agentic RAG tools as an MCP server.
+
+    Runs as a stdio-based JSON-RPC server that external MCP clients can connect to.
+    """
+
+    def __init__(self, tool_registry=None, name: str = "agentic_rag",
+                 version: str = "0.1.0"):
+        self.name = name
+        self.version = version
+        self.tool_registry = tool_registry
+        self._running = False
+
+    async def run_stdio(self) -> None:
+        """Run the MCP server over stdio (stdin/stdout).
+
+        Reads JSON-RPC requests from stdin and writes responses to stdout.
+        """
+        self._running = True
+        reader = asyncio.StreamReader()
+        protocol = asyncio.StreamReaderProtocol(reader)
+        await asyncio.get_event_loop().connect_read_pipe(lambda: protocol, sys.stdin)
+
+        while self._running:
+            try:
+                line = await asyncio.wait_for(reader.readline(), timeout=300.0)
+                if not line:
+                    break
+
+                request = json.loads(line.decode())
+                response = await self._handle_request(request)
+                sys.stdout.write(json.dumps(response) + "\n")
+                sys.stdout.flush()
+
+            except asyncio.TimeoutError:
+                break
+            except json.JSONDecodeError:
+                continue
+            except Exception as e:
+                error_response = {
+                    "jsonrpc": "2.0",
+                    "id": request.get("id") if "request" in dir() else None,
+                    "error": {"code": -32603, "message": str(e)},
+                }
+                sys.stdout.write(json.dumps(error_response) + "\n")
+                sys.stdout.flush()
+
+    async def _handle_request(self, request: dict) -> dict:
+        """Handle a single JSON-RPC request."""
+        method = request.get("method", "")
+        req_id = request.get("id")
+
+        handlers = {
+            "initialize": self._handle_initialize,
+            "tools/list": self._handle_tools_list,
+            "tools/call": self._handle_tools_call,
+            "resources/list": self._handle_resources_list,
+        }
+
+        handler = handlers.get(method)
+        if handler:
+            result = await handler(request.get("params", {}))
+            return {"jsonrpc": "2.0", "id": req_id, "result": result}
+        else:
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "error": {"code": -32601, "message": f"Method not found: {method}"},
+            }
+
+    async def _handle_initialize(self, params: dict) -> dict:
+        return {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": self.name, "version": self.version},
+        }
+
+    async def _handle_tools_list(self, params: dict) -> dict:
+        tools = self.tool_registry.get_all() if self.tool_registry else []
+        return {
+            "tools": [
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "inputSchema": t.parameters_schema,
+                }
+                for t in tools
+            ]
+        }
+
+    async def _handle_tools_call(self, params: dict) -> dict:
+        tool_name = params.get("name", "")
+        arguments = params.get("arguments", {})
+
+        tool = self.tool_registry.get(tool_name) if self.tool_registry else None
+        if tool is None:
+            return {
+                "content": [{"type": "text", "text": f"Tool not found: {tool_name}"}],
+                "isError": True,
+            }
+
+        try:
+            result = await tool.execute(**arguments)
+            return {
+                "content": [{"type": "text", "text": str(result)}],
+            }
+        except Exception as e:
+            return {
+                "content": [{"type": "text", "text": f"Error: {e}"}],
+                "isError": True,
+            }
+
+    async def _handle_resources_list(self, params: dict) -> dict:
+        return {"resources": []}
+
+    def stop(self) -> None:
+        """Stop the MCP server."""
+        self._running = False

agentic_rag/core/multimodal/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/core/multimodal/audio.py

@@ -0,0 +1,58 @@
+"""Audio transcription using Whisper."""
+
+from pathlib import Path
+from typing import Optional
+
+
+class AudioProcessor:
+    """Transcribe audio to text using Whisper."""
+
+    def __init__(self, model_name: str = "base"):
+        self.model_name = model_name
+        self._model = None
+
+    def _load_model(self):
+        """Lazy-load the Whisper model."""
+        if self._model is None:
+            import whisper
+            self._model = whisper.load_model(self.model_name)
+        return self._model
+
+    async def transcribe(self, audio_path: str | Path) -> str:
+        """Transcribe an audio file to text.
+
+        Args:
+            audio_path: Path to the audio file (mp3, wav, m4a, etc.)
+
+        Returns:
+            Transcribed text.
+        """
+        path = Path(audio_path)
+        if not path.exists():
+            return f"[Audio not found: {audio_path}]"
+
+        try:
+            model = self._load_model()
+            result = model.transcribe(str(path))
+            return result["text"]
+        except ImportError:
+            return "[Whisper not installed. Run: pip install openai-whisper]"
+        except Exception as e:
+            return f"[Transcription error: {e}]"
+
+    async def transcribe_bytes(self, audio_bytes: bytes, sample_rate: int = 16000) -> str:
+        """Transcribe raw audio bytes."""
+        import tempfile
+        import wave
+
+        try:
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+                with wave.open(f, "wb") as wf:
+                    wf.setnchannels(1)
+                    wf.setsampwidth(2)
+                    wf.setframerate(sample_rate)
+                    wf.writeframes(audio_bytes)
+                f.flush()
+                return await self.transcribe(f.name)
+        except Exception as e:
+            return f"[Transcription error: {e}]"

agentic_rag/core/multimodal/image.py

@@ -0,0 +1,78 @@
+"""Image understanding via Vision LLM."""
+
+import base64
+from pathlib import Path
+from typing import Optional
+
+from agentic_rag.data.models import Message
+
+
+class ImageProcessor:
+    """Process and understand images using Vision LLM."""
+
+    MIME_MAP = {
+        ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+        ".png": "image/png", ".gif": "image/gif",
+        ".webp": "image/webp", ".bmp": "image/bmp",
+    }
+
+    def __init__(self, llm=None):
+        """llm must be a vision-capable BaseLLMProvider."""
+        self.llm = llm
+
+    async def describe(self, image: str | Path, question: str = "Describe this image in detail.") -> str:
+        """Analyze an image and return a description.
+
+        Args:
+            image: Path to image file, URL, or base64 data URI.
+            question: What to ask about the image.
+
+        Returns:
+            Text description of the image.
+        """
+        if self.llm is None:
+            return "[Vision LLM not configured]"
+
+        image_url = self._resolve_image(image)
+        if image_url.startswith("ERROR:"):
+            return image_url
+
+        content = [
+            {"type": "text", "text": question},
+            {"type": "image_url", "image_url": {"url": image_url}},
+        ]
+
+        response = await self.llm.agenerate([Message(role="user", content=content)])
+        return response.content
+
+    def _resolve_image(self, image: str | Path) -> str:
+        """Resolve image to a base64 data URI or HTTP URL."""
+        img_str = str(image)
+
+        # Already a data URI or HTTP URL
+        if img_str.startswith(("data:", "http://", "https://")):
+            return img_str
+
+        # Local file path
+        path = Path(img_str)
+        if not path.exists():
+            return f"ERROR: Image not found: {img_str}"
+
+        ext = path.suffix.lower()
+        mime = self.MIME_MAP.get(ext, "image/png")
+        data = base64.b64encode(path.read_bytes()).decode()
+        return f"data:{mime};base64,{data}"
+
+    async def compare(self, image1: str, image2: str, question: str = "Compare these two images.") -> str:
+        """Compare two images."""
+        url1 = self._resolve_image(image1)
+        url2 = self._resolve_image(image2)
+
+        content = [
+            {"type": "text", "text": question},
+            {"type": "image_url", "image_url": {"url": url1}},
+            {"type": "image_url", "image_url": {"url": url2}},
+        ]
+
+        response = await self.llm.agenerate([Message(role="user", content=content)])
+        return response.content

agentic_rag/core/multimodal/video.py

@@ -0,0 +1,80 @@
+"""Video processing — keyframe extraction and analysis."""
+
+import base64
+from pathlib import Path
+from typing import Optional
+
+
+class VideoProcessor:
+    """Extract keyframes from video and describe them using Vision LLM."""
+
+    def __init__(self, llm=None):
+        """llm must be a vision-capable BaseLLMProvider."""
+        self.llm = llm
+
+    async def analyze(self, video_path: str | Path, max_frames: int = 5,
+                       question: str = "Describe what is happening in this video frame.") -> str:
+        """Extract keyframes from a video and describe each frame.
+
+        Args:
+            video_path: Path to video file.
+            max_frames: Maximum number of keyframes to extract.
+            question: Question to ask about each frame.
+
+        Returns:
+            Combined description of all keyframes.
+        """
+        path = Path(video_path)
+        if not path.exists():
+            return f"[Video not found: {video_path}]"
+
+        try:
+            import cv2
+        except ImportError:
+            return "[OpenCV not installed. Run: pip install opencv-python]"
+
+        cap = cv2.VideoCapture(str(path))
+        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        duration = total_frames / fps if fps > 0 else 0
+
+        frames_b64 = self._extract_keyframes(cap, total_frames, max_frames)
+        cap.release()
+
+        if not frames_b64:
+            return "[No frames extracted from video]"
+
+        results = [f"Video Info: {duration:.1f}s, {total_frames} frames, {fps:.1f} fps"]
+
+        if self.llm and self.llm.supports_vision:
+            from agentic_rag.data.models import Message
+
+            for i, frame_b64 in enumerate(frames_b64):
+                content = [
+                    {"type": "text", "text": f"Frame {i+1}/{len(frames_b64)}: {question}"},
+                    {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{frame_b64}"}},
+                ]
+                response = await self.llm.agenerate([Message(role="user", content=content)])
+                results.append(f"Frame {i+1}: {response.content[:300]}")
+        else:
+            results.append(f"[{len(frames_b64)} keyframes extracted but no Vision LLM configured for analysis]")
+
+        return "\n\n".join(results)
+
+    def _extract_keyframes(self, cap, total_frames: int, max_frames: int) -> list[str]:
+        """Extract evenly-spaced keyframes as base64 strings."""
+        import cv2
+
+        frames = []
+        interval = max(1, total_frames // max_frames)
+
+        for i in range(0, total_frames, interval):
+            cap.set(cv2.CAP_PROP_POS_FRAMES, i)
+            ret, frame = cap.read()
+            if ret:
+                _, buffer = cv2.imencode(".jpg", frame)
+                frames.append(base64.b64encode(buffer).decode())
+            if len(frames) >= max_frames:
+                break
+
+        return frames

agentic_rag/core/voice/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/core/voice/stt.py

@@ -0,0 +1,287 @@
+"""Speech-to-Text service.
+
+Primary: SenseVoice-compatible local ASR server (/asr endpoint).
+Fallback: OpenAI Whisper API or local Whisper model.
+"""
+
+import io
+import re
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+
+class STTService:
+    """Speech-to-Text via ASR server (SenseVoice) with Whisper fallback."""
+
+    def __init__(
+        self,
+        provider: str = "sensevoice",
+        model: str = "sensevoice",
+        api_base: str = "http://localhost:8000",
+        api_key: str = "",
+        language: str = "auto",
+        sample_rate: int = 16000,
+    ):
+        self.provider = provider          # "sensevoice" | "whisper" | "openai"
+        self.model = model
+        self.api_base = api_base.rstrip("/")
+        self.api_key = api_key
+        self.language = language           # auto | zh | en | ja | ko | yue
+        self.sample_rate = sample_rate
+        self._local_model = None
+
+    # ── Public API ──────────────────────────────────────────
+
+    async def transcribe_file(self, file_path: str | Path) -> str:
+        """Transcribe an audio file."""
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Audio file not found: {file_path}")
+
+        if self.provider == "sensevoice":
+            return await self._transcribe_sensevoice_file(path)
+        elif self.provider == "openai":
+            return await self._transcribe_openai(path)
+        else:
+            return await self._transcribe_local(path)
+
+    async def transcribe_bytes(
+        self, audio_data: bytes, language: str | None = None
+    ) -> str:
+        """Transcribe raw audio bytes (any format ffmpeg supports)."""
+        lang = language or self.language
+
+        if self.provider == "sensevoice":
+            waveform = self._decode_to_float32(audio_data)
+            if waveform is not None:
+                return await self._call_asr(waveform, lang)
+            return ""
+
+        # Whisper fallback — write to temp WAV
+        suffix = ".wav" if audio_data[:4] == b"RIFF" else ".webm"
+        with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as f:
+            f.write(audio_data)
+            return await self.transcribe_file(f.name)
+
+    async def transcribe_ndarray(
+        self, audio: np.ndarray, language: str | None = None
+    ) -> str:
+        """Transcribe a numpy array (float32 or int16)."""
+        lang = language or self.language
+
+        if self.provider == "sensevoice":
+            waveform = audio.astype(np.float32)
+            if waveform.max() > 1.5:
+                waveform = waveform / 32768.0
+            return await self._call_asr(waveform, lang)
+
+        # Whisper fallback
+        if audio.dtype != np.int16:
+            audio = np.clip(audio * 32767, -32768, 32767).astype(np.int16)
+        import wave
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+            with wave.open(f, "wb") as wf:
+                wf.setnchannels(1)
+                wf.setsampwidth(2)
+                wf.setframerate(self.sample_rate)
+                wf.writeframes(audio.tobytes())
+            return await self.transcribe_file(f.name)
+
+    # ── SenseVoice ASR server ───────────────────────────────
+
+    async def _transcribe_sensevoice_file(self, path: Path) -> str:
+        """Transcribe via SenseVoice ASR server."""
+        import librosa
+        waveform, sr = librosa.load(str(path), sr=self.sample_rate, mono=True)
+        return await self._call_asr(waveform.astype(np.float32), self.language)
+
+    async def _call_asr(
+        self, waveform: np.ndarray, language: str | None = None
+    ) -> str:
+        """Send audio to ASR server.
+
+        Primary: POST /v1/audio/transcriptions (OpenAI-compatible, openai_server.py).
+        Fallback: POST /asr (float32 JSON, legacy server.py).
+        """
+        lang = language or self.language
+
+        # 1) OpenAI-compatible (standard)
+        result = await self._try_openai_asr(waveform, lang)
+        if result:
+            return result
+
+        # 2) Legacy /asr fallback
+        result = await self._try_native_asr(waveform, lang)
+        return result or ""
+
+    async def _try_native_asr(
+        self, waveform: np.ndarray, lang: str
+    ) -> str | None:
+        """Try POST /asr with float32 JSON (server.py). Returns None on 404."""
+        import aiohttp
+
+        asr_url = f"{self.api_base}/asr"
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    asr_url,
+                    json={
+                        "audio_data": waveform.tolist(),
+                        "sample_rate": self.sample_rate,
+                        "language": lang,
+                    },
+                    timeout=aiohttp.ClientTimeout(total=300),
+                ) as resp:
+                    if resp.status == 404:
+                        return None  # Signal fallback
+                    if resp.status != 200:
+                        text = await resp.text()
+                        print(f"  [STT] ASR error {resp.status}: {text[:200]}", flush=True)
+                        return ""
+                    result = await resp.json()
+                    text = result.get("text", "")
+                    return self._clean_sensevoice(text)
+        except Exception as e:
+            print(f"  [STT] ASR connection error: {e}", flush=True)
+            return ""
+        return None
+
+    async def _try_openai_asr(
+        self, waveform: np.ndarray, lang: str
+    ) -> str:
+        """Try POST /v1/audio/transcriptions with WAV file upload (openai_server.py)."""
+        import aiohttp
+        import io
+        import soundfile as sf
+
+        transcribe_url = f"{self.api_base}/v1/audio/transcriptions"
+        try:
+            # Write float32 waveform to WAV in memory
+            wav_buf = io.BytesIO()
+            sf.write(wav_buf, waveform.astype(np.float32), self.sample_rate, format="WAV")
+            wav_buf.seek(0)
+
+            form = aiohttp.FormData()
+            form.add_field("file", wav_buf.read(),
+                           filename="audio.wav",
+                           content_type="audio/wav")
+            form.add_field("language", lang)
+            form.add_field("response_format", "json")
+
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    transcribe_url,
+                    data=form,
+                    timeout=aiohttp.ClientTimeout(total=300),
+                ) as resp:
+                    if resp.status != 200:
+                        text = await resp.text()
+                        print(f"  [STT] OpenAI ASR error {resp.status}: {text[:200]}", flush=True)
+                        return ""
+                    result = await resp.json()
+                    text = result.get("text", "")
+                    return self._clean_sensevoice(text)
+        except Exception as e:
+            print(f"  [STT] OpenAI ASR error: {e}", flush=True)
+            return ""
+
+    @staticmethod
+    def _clean_sensevoice(text: str) -> str:
+        """Remove SenseVoice special tokens like <|zh|>, <|emotion|>."""
+        text = re.sub(r'<\|[^|]*\|>', '', text)
+        text = re.sub(r'\s+', ' ', text).strip()
+        return text
+
+    # ── Local Whisper ───────────────────────────────────────
+
+    async def _transcribe_local(self, path: Path) -> str:
+        """Transcribe using local Whisper model."""
+        if self._local_model is None:
+            import whisper
+            self._local_model = whisper.load_model(self.model or "base")
+        result = self._local_model.transcribe(str(path))
+        return result["text"].strip()
+
+    # ── OpenAI Whisper API ──────────────────────────────────
+
+    async def _transcribe_openai(self, path: Path) -> str:
+        """Transcribe using OpenAI Whisper API."""
+        from openai import AsyncOpenAI
+
+        client = AsyncOpenAI(
+            api_key=self.api_key or "not-needed",
+            base_url=self.api_base or "https://api.openai.com/v1",
+        )
+        with open(path, "rb") as audio_file:
+            transcript = await client.audio.transcriptions.create(
+                model="whisper-1",
+                file=audio_file,
+            )
+        return transcript.text.strip()
+
+    # ── Audio decoding ──────────────────────────────────────
+
+    @staticmethod
+    def _decode_to_float32(audio_data: bytes) -> np.ndarray | None:
+        """Decode audio bytes to float32 numpy array in [-1, 1]."""
+        # WAV → soundfile
+        if audio_data[:4] == b"RIFF":
+            try:
+                import soundfile as sf
+                wav_buf = io.BytesIO(audio_data)
+                waveform, _ = sf.read(wav_buf, dtype="float32")
+                if waveform.ndim > 1:
+                    waveform = waveform.mean(axis=1)
+                return waveform.astype(np.float32)
+            except Exception:
+                pass
+
+        # Compressed → pydub (ffmpeg)
+        try:
+            from pydub import AudioSegment
+            import soundfile as sf
+
+            suffix = _detect_suffix(audio_data)
+            with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+                tmp.write(audio_data)
+                tmp_path = tmp.name
+            try:
+                audio = AudioSegment.from_file(tmp_path)
+                audio = audio.set_channels(1).set_frame_rate(16000)
+                wav_buf = io.BytesIO()
+                audio.export(wav_buf, format="wav")
+                wav_buf.seek(0)
+                waveform, _ = sf.read(wav_buf, dtype="float32")
+                if waveform.ndim > 1:
+                    waveform = waveform.mean(axis=1)
+                return waveform.astype(np.float32)
+            finally:
+                Path(tmp_path).unlink(missing_ok=True)
+        except ImportError:
+            pass
+        except Exception:
+            pass
+
+        # Raw int16 PCM (last resort)
+        try:
+            arr = np.frombuffer(audio_data, dtype=np.int16).astype(np.float32)
+            return arr / 32768.0
+        except Exception:
+            return None
+
+
+def _detect_suffix(data: bytes) -> str:
+    """Guess file extension from magic bytes."""
+    if data[:4] == b"RIFF":
+        return ".wav"
+    if data[:3] == b"ID3":
+        return ".mp3"
+    if data[:4] == b"fLaC":
+        return ".flac"
+    if data[:4] == b"OggS":
+        return ".ogg"
+    if data[:4] == b"\x1a\x45\xdf\xa3":
+        return ".webm"
+    return ".webm"

agentic_rag/core/voice/tts.py

@@ -0,0 +1,277 @@
+"""Text-to-Speech service.
+
+Primary: Qwen3-TTS via OpenAI-compatible /v1/audio/speech API.
+  - VoiceDesign: generate voice from text description (instructions)
+  - CustomVoice: use predefined speaker names
+  - Base: voice cloning from reference audio
+Fallback: Edge-TTS (free, good quality for Chinese).
+"""
+
+import asyncio
+import io
+import tempfile
+import time
+from pathlib import Path
+
+
+class TTSService:
+    """Text-to-Speech via Qwen3-TTS / Kokoro with Edge-TTS fallback."""
+
+    def __init__(
+        self,
+        provider: str = "qwen",
+        model: str = "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
+        api_base: str = "http://0.0.0.0:8091",
+        api_key: str = "EMPTY",
+        task_type: str = "VoiceDesign",
+        instructions: str = "A clear, professional voice in Chinese",
+        language: str = "Chinese",
+        speaker: str = "",
+        voice: str = "zh-CN-XiaoxiaoNeural",  # Edge-TTS fallback / kokoro voice
+        speed: float = 1.0,                    # kokoro playback speed
+        response_format: str = "wav",
+        max_new_tokens: int = 0,
+    ):
+        self.provider = provider          # "qwen" | "kokoro" | "edge" | "openai"
+        self.model = model
+        self.api_base = api_base.rstrip("/")
+        self.api_key = api_key
+        self.task_type = task_type        # VoiceDesign | CustomVoice | Base (qwen)
+        self.instructions = instructions  # Voice description (qwen)
+        self.language = language           # Chinese | zh | en | ja (qwen/kokoro)
+        self.speaker = speaker            # Speaker name (qwen CustomVoice)
+        self.voice = voice                # Edge-TTS / kokoro voice name
+        self.speed = speed                # kokoro speed
+        self.response_format = response_format  # wav | mp3 | flac | pcm
+        self.max_new_tokens = max_new_tokens
+
+    # ── Text cleaning ───────────────────────────────────────
+
+    @staticmethod
+    def _clean_for_tts(text: str) -> str:
+        """Strip Markdown, URLs, emoji, and formatting for TTS."""
+        import re
+
+        # Remove URLs
+        text = re.sub(r'https?://\S+', '', text)
+        # Remove Markdown images/links: ![alt](url) and [text](url)
+        text = re.sub(r'!\[.*?\]\(.*?\)', '', text)
+        text = re.sub(r'\[([^\]]*)\]\(.*?\)', r'\1', text)
+        # Remove Markdown formatting markers
+        text = re.sub(r'\*{1,3}([^*]+)\*{1,3}', r'\1', text)  # **bold**, *italic*
+        text = re.sub(r'#{1,6}\s*', '', text)                   # headers
+        text = re.sub(r'`{1,3}[^`]*`{1,3}', '', text)          # inline code / code blocks
+        text = re.sub(r'^[-*+]\s+', '', text, flags=re.MULTILINE)  # list markers
+        text = re.sub(r'^\d+\.\s+', '', text, flags=re.MULTILINE)  # numbered lists
+        # Remove reference markers like [R1], [R3]
+        text = re.sub(r'\[R\d+\]', '', text)
+        # Remove emoji and other non-speech symbols
+        text = re.sub(r'[^一-鿿　-〿＀-￯a-zA-Z0-9\s.,!?;:，。！？；：、""\'\'（）【】《》…\-\']+', ' ', text)
+        # Collapse whitespace
+        text = re.sub(r'\s+', ' ', text).strip()
+        # Remove leading/trailing punctuation-only lines
+        text = re.sub(r'^[,.!?;:，。！？；：、\s]+$', '', text, flags=re.MULTILINE)
+        return text.strip()
+
+    # ── Public API ──────────────────────────────────────────
+
+    async def synthesize(self, text: str) -> bytes:
+        """Convert text to speech, returning raw audio bytes."""
+        if not text.strip():
+            return b""
+
+        # Clean text before TTS (strip Markdown/URLs/emoji)
+        clean_text = self._clean_for_tts(text)
+        if not clean_text:
+            return b""
+
+        if self.provider == "qwen":
+            result = await self._synthesize_qwen(clean_text)
+            if result:
+                return result
+            print(f"  [TTS] Qwen3-TTS failed, falling back to Edge-TTS", flush=True)
+            return await self._synthesize_edge(clean_text)
+        elif self.provider == "kokoro":
+            result = await self._synthesize_kokoro(clean_text)
+            if result:
+                return result
+            print(f"  [TTS] Kokoro failed, falling back to Edge-TTS", flush=True)
+            return await self._synthesize_edge(clean_text)
+        elif self.provider == "openai":
+            return await self._synthesize_openai(text)
+        else:
+            return await self._synthesize_edge(text)
+
+    async def synthesize_to_file(
+        self, text: str, output_path: str | Path
+    ) -> Path:
+        """Synthesize speech and save to a file."""
+        audio_bytes = await self.synthesize(text)
+        path = Path(output_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(audio_bytes)
+        return path
+
+    # ── Qwen3-TTS (VoiceDesign) ���────────────────────────────
+
+    async def _synthesize_qwen(self, text: str) -> bytes:
+        """Synthesize via Qwen3-TTS OpenAI-compatible /v1/audio/speech."""
+        import aiohttp
+
+        payload = {
+            "model": self.model,
+            "input": text,
+            "response_format": self.response_format,
+        }
+        if self.task_type:
+            payload["task_type"] = self.task_type
+        if self.speaker:
+            payload["voice"] = self.speaker
+        if self.instructions:
+            payload["instructions"] = self.instructions
+        if self.language:
+            payload["language"] = self.language
+        if self.max_new_tokens > 0:
+            payload["max_new_tokens"] = self.max_new_tokens
+
+        api_url = f"{self.api_base}/v1/audio/speech"
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        }
+
+        for attempt in range(3):
+            try:
+                async with aiohttp.ClientSession() as session:
+                    async with session.post(
+                        api_url,
+                        json=payload,
+                        headers=headers,
+                        timeout=aiohttp.ClientTimeout(total=120),
+                    ) as resp:
+                        if resp.status != 200:
+                            err = await _read_error(resp)
+                            print(f"  [TTS] Qwen error (attempt {attempt+1}/3): "
+                                  f"{resp.status} {err[:100]}", flush=True)
+                            if attempt < 2:
+                                await asyncio.sleep(2 ** attempt)
+                            continue
+                        return await resp.read()
+            except Exception as e:
+                print(f"  [TTS] Qwen request error (attempt {attempt+1}/3): {e}",
+                      flush=True)
+                if attempt < 2:
+                    await asyncio.sleep(2 ** attempt)
+
+        return b""
+
+    # ── Edge-TTS (fallback) ─────────────────────────────────
+
+    async def _synthesize_edge(self, text: str) -> bytes:
+        """Synthesize using Edge-TTS (free, good Chinese quality)."""
+        try:
+            import edge_tts
+            communicate = edge_tts.Communicate(text, self.voice)
+            with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
+                temp_path = f.name
+            await communicate.save(temp_path)
+            data = Path(temp_path).read_bytes()
+            Path(temp_path).unlink(missing_ok=True)
+            return data
+        except ImportError:
+            print(f"  [TTS] edge-tts not installed", flush=True)
+            return b""
+        except Exception as e:
+            print(f"  [TTS] Edge-TTS error: {e}", flush=True)
+            return b""
+
+    # ── Kokoro TTS (Axera NPU) ────────────────────────────
+
+    async def _synthesize_kokoro(self, text: str) -> bytes:
+        """Synthesize via Kokoro TTS server (POST /tts → WAV bytes).
+
+        API: POST /tts with form/JSON body
+          text/sentence: text to speak
+          language/lang: zh | en | ja
+          voice: voice name (e.g., zf_xiaoyi, zf_xiaoxiao)
+          speed: playback speed (default 1.0)
+        Returns: WAV audio bytes
+        """
+        import aiohttp
+
+        # Map internal language codes to Kokoro codes
+        lang_map = {
+            "zh": "zh", "chinese": "zh",
+            "en": "en", "english": "en",
+            "ja": "ja", "japanese": "ja",
+            "auto": "zh",
+        }
+        kokoro_lang = lang_map.get(
+            (self.language or "zh").lower(), "zh"
+        )
+
+        payload = {
+            "text": text,
+            "language": kokoro_lang,
+            "voice": self.voice or "zf_xiaoyi",
+            "speed": str(self.speed),
+        }
+
+        api_url = f"{self.api_base}/tts"
+
+        for attempt in range(3):
+            try:
+                async with aiohttp.ClientSession() as session:
+                    async with session.post(
+                        api_url,
+                        data=payload,
+                        timeout=aiohttp.ClientTimeout(total=120),
+                    ) as resp:
+                        if resp.status != 200:
+                            err_body = await resp.text()
+                            print(
+                                f"  [TTS] Kokoro error (attempt {attempt+1}/3): "
+                                f"{resp.status} {err_body[:200]}", flush=True,
+                            )
+                            if attempt < 2:
+                                await asyncio.sleep(2 ** attempt)
+                            continue
+                        return await resp.read()
+            except Exception as e:
+                print(
+                    f"  [TTS] Kokoro request error (attempt {attempt+1}/3): {e}",
+                    flush=True,
+                )
+                if attempt < 2:
+                    await asyncio.sleep(2 ** attempt)
+
+        return b""
+
+    # ── OpenAI TTS ──────────────────────────────────────────
+
+    async def _synthesize_openai(self, text: str) -> bytes:
+        """Synthesize using OpenAI TTS API."""
+        from openai import AsyncOpenAI
+
+        client = AsyncOpenAI(
+            api_key=self.api_key or "not-needed",
+            base_url=self.api_base or "https://api.openai.com/v1",
+        )
+        response = await client.audio.speech.create(
+            model="tts-1",
+            voice="alloy",
+            input=text,
+        )
+        return response.content
+
+
+async def _read_error(resp) -> str:
+    """Extract error detail from a failed TTS response."""
+    try:
+        data = await resp.json()
+        return str(data.get("detail", data.get("error", str(data))))[:200]
+    except Exception:
+        try:
+            return (await resp.text())[:200]
+        except Exception:
+            return str(resp.status)

agentic_rag/data/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/data/db/__init__.py

@@ -0,0 +1,183 @@
+"""Database layer — SQLite-backed persistence for sessions, documents, and metadata.
+
+Replaces the in-memory dicts used during early development with a proper
+persistent store.  Uses aiosqlite for async access so it integrates cleanly
+with the FastAPI / asyncio stack.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+
+# ═══════════════════════════════════════════════════════════════
+# Connection management
+# ═══════════════════════════════════════════════════════════════
+
+class Database:
+    """Thin wrapper around a SQLite connection with schema management."""
+
+    def __init__(self, db_path: str | Path = "data/agentic_rag.db"):
+        self._path = Path(db_path)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn: Optional[sqlite3.Connection] = None
+
+    # ── Lifecycle ─────────────────────────────────
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = sqlite3.connect(str(self._path))
+            self._conn.row_factory = sqlite3.Row
+            self._conn.execute("PRAGMA journal_mode=WAL")
+            self._conn.execute("PRAGMA foreign_keys=ON")
+        return self._conn
+
+    def close(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    # ── Schema ────────────────────────────────────
+
+    SCHEMA_VERSION = 1
+
+    def init_schema(self) -> None:
+        """Create tables if they don't exist (idempotent)."""
+        c = self.conn
+        c.executescript("""
+            -- Schema versioning
+            CREATE TABLE IF NOT EXISTS _schema (
+                version     INTEGER PRIMARY KEY,
+                applied_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+            );
+
+            -- Sessions (chat conversation containers)
+            CREATE TABLE IF NOT EXISTS sessions (
+                id          TEXT PRIMARY KEY,
+                user_id     TEXT    NOT NULL DEFAULT 'default',
+                title       TEXT    NOT NULL DEFAULT '',
+                metadata    TEXT    NOT NULL DEFAULT '{}',
+                created_at  TEXT    NOT NULL DEFAULT (datetime('now')),
+                updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+            );
+
+            -- Messages within a session
+            CREATE TABLE IF NOT EXISTS messages (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id  TEXT    NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+                role        TEXT    NOT NULL,  -- 'system' | 'user' | 'assistant' | 'tool'
+                content     TEXT    NOT NULL DEFAULT '',
+                tool_calls  TEXT    NOT NULL DEFAULT '[]',
+                tool_call_id TEXT   DEFAULT NULL,
+                created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+            );
+            CREATE INDEX IF NOT EXISTS idx_messages_session
+                ON messages(session_id, id);
+
+            -- Documents ingested into the knowledge base
+            CREATE TABLE IF NOT EXISTS documents (
+                id          TEXT PRIMARY KEY,
+                source      TEXT    NOT NULL DEFAULT '',
+                source_type TEXT    NOT NULL DEFAULT 'text',
+                content_preview TEXT NOT NULL DEFAULT '',
+                item_count  INTEGER NOT NULL DEFAULT 0,
+                metadata    TEXT    NOT NULL DEFAULT '{}',
+                created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+            );
+
+            -- Content items (individual chunks / images / tables)
+            CREATE TABLE IF NOT EXISTS content_items (
+                id          TEXT PRIMARY KEY,
+                doc_id      TEXT    NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+                type        TEXT    NOT NULL DEFAULT 'text',
+                text        TEXT    NOT NULL DEFAULT '',
+                img_path    TEXT    NOT NULL DEFAULT '',
+                table_body  TEXT    NOT NULL DEFAULT '',
+                page_idx    INTEGER NOT NULL DEFAULT 0,
+                metadata    TEXT    NOT NULL DEFAULT '{}',
+                created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+            );
+            CREATE INDEX IF NOT EXISTS idx_content_doc
+                ON content_items(doc_id);
+            CREATE INDEX IF NOT EXISTS idx_content_type
+                ON content_items(type);
+
+            -- Platform-to-session bindings (for messaging gateway)
+            CREATE TABLE IF NOT EXISTS platform_sessions (
+                platform         TEXT NOT NULL,
+                platform_user_id TEXT NOT NULL,
+                chat_id          TEXT NOT NULL DEFAULT '',
+                session_id       TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+                created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+                PRIMARY KEY (platform, platform_user_id, chat_id)
+            );
+
+            -- Key-value store for application config / cache
+            CREATE TABLE IF NOT EXISTS kv_store (
+                key         TEXT PRIMARY KEY,
+                value       TEXT    NOT NULL DEFAULT '',
+                updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+            );
+        """)
+
+        # Record schema version
+        existing = c.execute(
+            "SELECT version FROM _schema WHERE version = ?",
+            (self.SCHEMA_VERSION,),
+        ).fetchone()
+        if not existing:
+            c.execute(
+                "INSERT INTO _schema (version) VALUES (?)",
+                (self.SCHEMA_VERSION,),
+            )
+            c.commit()
+
+    # ── Raw SQL helpers ───────────────────────────
+
+    def execute(self, sql: str, params: tuple = ()) -> sqlite3.Cursor:
+        return self.conn.execute(sql, params)
+
+    def executemany(self, sql: str, params_list: list[tuple]) -> sqlite3.Cursor:
+        return self.conn.executemany(sql, params_list)
+
+    def commit(self) -> None:
+        self.conn.commit()
+
+    def fetchone(self, sql: str, params: tuple = ()) -> Optional[sqlite3.Row]:
+        return self.conn.execute(sql, params).fetchone()
+
+    def fetchall(self, sql: str, params: tuple = ()) -> list[sqlite3.Row]:
+        return self.conn.execute(sql, params).fetchall()
+
+
+# ═══════════════════════════════════════════════════════════════
+# Global instance
+# ═══════════════════════════════════════════════════════════════
+
+_db: Optional[Database] = None
+
+
+def get_db(db_path: str | Path = "") -> Database:
+    """Get or create the global database instance."""
+    global _db
+    if _db is None:
+        path = db_path or "data/agentic_rag.db"
+        try:
+            from agentic_rag.config.settings import get_settings
+            path = get_settings().db_path
+        except Exception:
+            pass
+        _db = Database(path)
+        _db.init_schema()
+    return _db
+
+
+def init_db(db_path: str | Path = "") -> Database:
+    """Explicitly initialise the database (call at app startup)."""
+    global _db
+    _db = Database(db_path or "data/agentic_rag.db")
+    _db.init_schema()
+    return _db

agentic_rag/data/db/session_repo.py

@@ -0,0 +1,165 @@
+"""Session repository — persistence layer for chat sessions."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from agentic_rag.data.db import get_db
+
+
+class SessionRepo:
+    """CRUD operations for sessions."""
+
+    def __init__(self) -> None:
+        self._db = get_db()
+
+    # ── Session CRUD ──────────────────────────────
+
+    def create(self, user_id: str = "default", title: str = "") -> dict:
+        sid = uuid.uuid4().hex
+        return self.create_with_id(sid, user_id, title)
+
+    def create_with_id(self, sid: str, user_id: str = "default", title: str = "") -> dict:
+        now = _now()
+        self._db.execute(
+            "INSERT INTO sessions (id, user_id, title, created_at, updated_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (sid, user_id, title, now, now),
+        )
+        self._db.commit()
+        return {"id": sid, "user_id": user_id, "title": title,
+                "created_at": now, "updated_at": now}
+
+    def get(self, session_id: str) -> Optional[dict]:
+        row = self._db.fetchone(
+            "SELECT * FROM sessions WHERE id = ?", (session_id,),
+        )
+        return dict(row) if row else None
+
+    def list(self, user_id: str = "default", limit: int = 50) -> list[dict]:
+        rows = self._db.fetchall(
+            "SELECT * FROM sessions WHERE user_id = ? "
+            "ORDER BY updated_at DESC LIMIT ?",
+            (user_id, limit),
+        )
+        return [dict(r) for r in rows]
+
+    def update(self, session_id: str, **fields) -> bool:
+        if not fields:
+            return False
+        sets = [f"{k} = ?" for k in fields]
+        values = list(fields.values())
+        values.append(_now())
+        values.append(session_id)
+        self._db.execute(
+            f"UPDATE sessions SET {', '.join(sets)}, updated_at = ? "
+            f"WHERE id = ?",
+            tuple(values),
+        )
+        self._db.commit()
+        return True
+
+    def delete(self, session_id: str) -> bool:
+        self._db.execute("DELETE FROM platform_sessions WHERE session_id = ?", (session_id,))
+        self._db.execute("DELETE FROM messages WHERE session_id = ?", (session_id,))
+        self._db.execute("DELETE FROM sessions WHERE id = ?", (session_id,))
+        self._db.commit()
+        return True
+
+    def delete_all(self, user_id: str = "default") -> int:
+        """Delete all sessions and messages for a user. Returns count of deleted sessions."""
+        sessions = self._db.fetchall(
+            "SELECT id FROM sessions WHERE user_id = ?", (user_id,),
+        )
+        count = len(sessions)
+        for s in sessions:
+            self._db.execute("DELETE FROM platform_sessions WHERE session_id = ?", (s["id"],))
+            self._db.execute("DELETE FROM messages WHERE session_id = ?", (s["id"],))
+        self._db.execute("DELETE FROM sessions WHERE user_id = ?", (user_id,))
+        self._db.commit()
+        return count
+
+    # ── Platform Session Binding ──────────────────
+
+    def get_platform_session(
+        self, platform: str, platform_user_id: str, chat_id: str = ""
+    ) -> Optional[str]:
+        """Get the internal session_id for a platform user+chat combination."""
+        row = self._db.fetchone(
+            "SELECT session_id FROM platform_sessions "
+            "WHERE platform = ? AND platform_user_id = ? AND chat_id = ?",
+            (platform, platform_user_id, chat_id),
+        )
+        return row["session_id"] if row else None
+
+    def clear_messages(self, session_id: str) -> int:
+        """Delete all messages from a session, keep the session. Returns count of deleted messages."""
+        cursor = self._db.execute(
+            "SELECT COUNT(*) as cnt FROM messages WHERE session_id = ?",
+            (session_id,),
+        )
+        count = cursor.fetchone()["cnt"]
+        self._db.execute("DELETE FROM messages WHERE session_id = ?", (session_id,))
+        self._db.commit()
+        return count
+
+    def bind_platform_session(
+        self, platform: str, platform_user_id: str,
+        chat_id: str, session_id: str,
+    ) -> None:
+        """Bind a platform user+chat to an internal session (idempotent upsert)."""
+        self._db.execute(
+            "INSERT OR REPLACE INTO platform_sessions "
+            "(platform, platform_user_id, chat_id, session_id) "
+            "VALUES (?, ?, ?, ?)",
+            (platform, platform_user_id, chat_id, session_id),
+        )
+        self._db.commit()
+        """Delete all sessions and messages for a user. Returns count of deleted sessions."""
+        sessions = self._db.fetchall(
+            "SELECT id FROM sessions WHERE user_id = ?", (user_id,),
+        )
+        count = len(sessions)
+        for s in sessions:
+            self._db.execute("DELETE FROM messages WHERE session_id = ?", (s["id"],))
+        self._db.execute("DELETE FROM sessions WHERE user_id = ?", (user_id,))
+        self._db.commit()
+        return count
+
+    # ── Messages ──────────────────────────────────
+
+    def add_message(self, session_id: str, role: str, content: str,
+                    tool_calls: list | None = None,
+                    tool_call_id: str | None = None) -> int:
+        self._db.execute(
+            "UPDATE sessions SET updated_at = ? WHERE id = ?",
+            (_now(), session_id),
+        )
+        cursor = self._db.execute(
+            "INSERT INTO messages (session_id, role, content, tool_calls, tool_call_id) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (session_id, role, content,
+             json.dumps(tool_calls or []),
+             tool_call_id),
+        )
+        self._db.commit()
+        return cursor.lastrowid
+
+    def get_messages(self, session_id: str, limit: int = 50) -> list[dict]:
+        rows = self._db.fetchall(
+            "SELECT * FROM messages WHERE session_id = ? "
+            "ORDER BY id ASC LIMIT ?",
+            (session_id, limit),
+        )
+        return [dict(r) for r in rows]
+
+
+# ═══════════════════════════════════════════════════════════════
+# Helpers
+# ═══════════════════════════════════════════════════════════════
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

agentic_rag/data/models.py

@@ -0,0 +1,185 @@
+"""Core domain models for Agentic RAG."""
+
+import time
+import uuid
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+# ──────────────────────────────────────────────
+# Message & Conversation Models
+# ──────────────────────────────────────────────
+
+class MessageRole(str, Enum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+class ToolCall(BaseModel):
+    """A tool call made by the LLM."""
+    id: str = Field(default_factory=lambda: f"call_{uuid.uuid4().hex[:12]}")
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolCallResult(BaseModel):
+    """Result of a tool call."""
+    call_id: str
+    name: str
+    result: Any
+    error: Optional[str] = None
+
+
+class Message(BaseModel):
+    """A single message in a conversation."""
+    role: MessageRole
+    content: str | list[dict[str, Any]]  # text or multimodal content
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    tool_call_id: Optional[str] = None
+    timestamp: float = Field(default_factory=time.time)
+
+    @classmethod
+    def system(cls, content: str) -> "Message":
+        return cls(role=MessageRole.SYSTEM, content=content)
+
+    @classmethod
+    def user(cls, content: str) -> "Message":
+        return cls(role=MessageRole.USER, content=content)
+
+    @classmethod
+    def assistant(cls, content: str, tool_calls: list[ToolCall] | None = None) -> "Message":
+        return cls(role=MessageRole.ASSISTANT, content=content,
+                   tool_calls=tool_calls or [])
+
+    @classmethod
+    def tool(cls, content: str, tool_call_id: str) -> "Message":
+        return cls(role=MessageRole.TOOL, content=content, tool_call_id=tool_call_id)
+
+
+# ──────────────────────────────────────────────
+# LLM Models
+# ──────────────────────────────────────────────
+
+class ToolDefinition(BaseModel):
+    """Tool definition for LLM function calling."""
+    name: str
+    description: str
+    parameters: dict[str, Any]  # JSON Schema
+
+
+class LLMResponse(BaseModel):
+    """Response from an LLM provider."""
+    content: str
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    stop_reason: Optional[str] = None
+    usage: dict[str, int] = Field(default_factory=dict)
+
+
+class LLMChunk(BaseModel):
+    """Streaming chunk from an LLM provider."""
+    content_delta: str = ""
+    tool_call_delta: Optional[dict] = None
+    stop_reason: Optional[str] = None
+
+
+# ──────────────────────────────────────────────
+# Multimodal Input Models
+# ──────────────────────────────────────────────
+
+class MediaType(str, Enum):
+    IMAGE = "image"
+    VIDEO = "video"
+    AUDIO = "audio"
+    TEXT = "text"
+
+
+class MultimodalInput(BaseModel):
+    """User input that may contain multiple modalities."""
+    text: Optional[str] = None
+    images: list[str] = Field(default_factory=list)    # base64 or file paths
+    audio: Optional[str] = None                         # base64 or file path
+    video: Optional[str] = None                         # file path
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProcessedContent(BaseModel):
+    """Content after multimodal processing."""
+    text: str
+    source_types: list[MediaType] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+# ──────────────────────────────────────────────
+# Agent Models
+# ──────────────────────────────────────────────
+
+class AgentEventType(str, Enum):
+    THOUGHT = "thought"
+    ACTION = "action"
+    OBSERVATION = "observation"
+    TEXT_DELTA = "text_delta"
+    TOOL_CALL_START = "tool_call_start"
+    TOOL_CALL_RESULT = "tool_call_result"
+    ERROR = "error"
+    DONE = "done"
+
+
+class AgentEvent(BaseModel):
+    """An event emitted during agent execution."""
+    event_type: AgentEventType
+    data: dict[str, Any] = Field(default_factory=dict)
+    turn_id: str = ""
+    timestamp: float = Field(default_factory=time.time)
+
+
+class AgentInput(BaseModel):
+    """Input to an agent."""
+    messages: list[Message] = Field(default_factory=list)
+    query: str = ""
+    multimodal: Optional[MultimodalInput] = None
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentOutput(BaseModel):
+    """Output from an agent."""
+    messages: list[Message] = Field(default_factory=list)
+    final_answer: str = ""
+    tool_calls_made: list[ToolCallResult] = Field(default_factory=list)
+    usage: dict[str, int] = Field(default_factory=dict)
+    iterations: int = 0
+
+
+# ──────────────────────────────────────────────
+# RAG Models
+# ──────────────────────────────────────────────
+
+class Document(BaseModel):
+    """A document in the knowledge base."""
+    id: str = Field(default_factory=lambda: uuid.uuid4().hex)
+    text: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    embedding: list[float] = Field(default_factory=list)
+
+
+class RetrievalResult(BaseModel):
+    """Result of a retrieval operation."""
+    documents: list[Document] = Field(default_factory=list)
+    scores: list[float] = Field(default_factory=list)
+    query: str = ""
+
+
+# ──────────────────────────────────────────────
+# Session Models
+# ──────────────────────────────────────────────
+
+class Session(BaseModel):
+    """A user session."""
+    id: str = Field(default_factory=lambda: uuid.uuid4().hex)
+    user_id: str = "default"
+    created_at: float = Field(default_factory=time.time)
+    expires_at: float = Field(default_factory=lambda: time.time() + 3600)
+    metadata: dict[str, Any] = Field(default_factory=dict)

agentic_rag/data/schemas/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/entrypoints/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/entrypoints/cli/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/entrypoints/cli/main.py

@@ -0,0 +1,130 @@
+"""CLI entry point for Agentic RAG."""
+
+import asyncio
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+app = typer.Typer(help="Agentic RAG — Multi-modal ReAct-powered RAG System")
+console = Console()
+
+
+@app.command()
+def chat(
+    message: str = typer.Argument(..., help="Your message/question"),
+    mode: str = typer.Option("auto", help="Agent mode: auto, chat, rag, research, media"),
+    stream: bool = typer.Option(False, "--stream", "-s", help="Stream the response"),
+    provider: str = typer.Option("", help="LLM provider to use"),
+):
+    """Send a message to the agent."""
+    from agentic_rag.services.llm.factory import get_llm
+    from agentic_rag.orchestration.l1_tools.registry import get_tool_registry
+    from agentic_rag.agent.router import AgentRouter
+    from agentic_rag.data.models import AgentInput
+
+    async def _run():
+        llm = get_llm(provider) if provider else get_llm()
+        tool_registry = get_tool_registry()
+        _register_tools(tool_registry)
+
+        router = AgentRouter(llm, tool_registry)
+        engine = await router.route(query=message, preferred_mode=mode if mode != "auto" else None)
+
+        if stream:
+            input_data = AgentInput(query=message)
+            async for event in engine.stream(input_data):
+                if event.event_type.value == "text_delta":
+                    console.print(event.data.get("content", ""), end="")
+                elif event.event_type.value == "tool_call_start":
+                    console.print(f"\n[dim]🔧 {event.data['tool']}...[/dim]")
+                elif event.event_type.value == "tool_call_result":
+                    status = "✓" if event.data.get("success") else "✗"
+                    console.print(f"[dim]   {status} Done[/dim]")
+            console.print()
+        else:
+            with console.status("[bold green]Thinking..."):
+                input_data = AgentInput(query=message)
+                output = await engine.run(input_data)
+
+            console.print(Panel(Markdown(output.final_answer), title="Answer"))
+            if output.tool_calls_made:
+                console.print(f"[dim]Tools used: {len(output.tool_calls_made)}, Iterations: {output.iterations}[/dim]")
+
+    asyncio.run(_run())
+
+
+@app.command()
+def serve(
+    host: str = typer.Option("0.0.0.0", help="Host to bind"),
+    port: int = typer.Option(8000, help="Port to bind"),
+    reload: bool = typer.Option(False, help="Enable auto-reload"),
+):
+    """Start the API server."""
+    import uvicorn
+    console.print(f"[bold green]Starting Agentic RAG server on {host}:{port}[/bold green]")
+    uvicorn.run(
+        "agentic_rag.entrypoints.rest.app:app",
+        host=host,
+        port=port,
+        reload=reload,
+        log_level="info",
+    )
+
+
+@app.command()
+def ingest(
+    file: str = typer.Option(..., "--file", "-f", help="File to ingest"),
+    source: str = typer.Option("cli", help="Source identifier"),
+):
+    """Ingest a document into the knowledge base."""
+    from agentic_rag.orchestration.l1_tools.rag_tools import RAGIngestTool
+
+    async def _run():
+        path = Path(file)
+        if not path.exists():
+            console.print(f"[red]File not found: {file}[/red]")
+            sys.exit(1)
+
+        content = path.read_text()
+        tool = RAGIngestTool()
+        result = await tool.execute(content=content, source=source)
+        console.print(f"[green]{result}[/green]")
+
+    asyncio.run(_run())
+
+
+@app.command()
+def info():
+    """Show system information."""
+    from agentic_rag import __version__
+    from agentic_rag.config.settings import get_settings
+
+    settings = get_settings()
+
+    console.print(Panel(f"Agentic RAG v{__version__}", title="System Info"))
+    console.print(f"Default LLM Provider: {settings.default_provider}")
+    for name, cfg in settings.llm_providers.items():
+        console.print(f"  {name}: {cfg.model} @ {cfg.api_base}")
+    console.print(f"Milvus: {settings.milvus.host}:{settings.milvus.port}")
+    console.print(f"Embedding: {settings.embedding.model} (dim={settings.embedding.dim})")
+
+
+def _register_tools(registry):
+    """Register built-in tools."""
+    if registry.tool_count == 0:
+        from agentic_rag.orchestration.l1_tools.rag_tools import RAGSearchTool
+        from agentic_rag.orchestration.l1_tools.web_tools import WebFetchTool, WebSearchTool
+        from agentic_rag.orchestration.l1_tools.code_tools import CodeExecuteTool
+
+        registry.register(RAGSearchTool())
+        registry.register(WebSearchTool())
+        registry.register(WebFetchTool())
+        registry.register(CodeExecuteTool())
+
+
+if __name__ == "__main__":
+    app()

agentic_rag/entrypoints/gateway/__init__.py

@@ -0,0 +1,22 @@
+"""Gateway adaptors for messaging platforms (WeChat Work, DingTalk, Feishu).
+
+Each platform sub-package implements a webhook endpoint that:
+1. Verifies the incoming request signature
+2. Parses the platform-specific message format
+3. Routes the query to the Agentic RAG engine
+4. Returns a formatted response
+"""
+
+from agentic_rag.entrypoints.gateway.base import (
+    BasePlatformAdaptor,
+    PlatformMessage,
+    PlatformResponse,
+)
+from agentic_rag.entrypoints.gateway.session import PlatformSessionMap
+
+__all__ = [
+    "BasePlatformAdaptor",
+    "PlatformMessage",
+    "PlatformResponse",
+    "PlatformSessionMap",
+]

agentic_rag/entrypoints/gateway/base.py

@@ -0,0 +1,206 @@
+"""Base adaptor interface and shared models for messaging platform gateways."""
+
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from fastapi import Request, Response
+
+if TYPE_CHECKING:
+    from agentic_rag.data.models import AgentOutput
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Normalized Message / Response Models
+# ═══════════════════════════════════════════════════════════════════
+
+@dataclass
+class PlatformMessage:
+    """Normalized inbound message from any messaging platform."""
+
+    platform: str                     # "wechat_work" | "dingtalk" | "feishu"
+    sender_id: str                    # Platform-specific user ID
+    sender_name: str = ""             # Display name (optional)
+    chat_id: str = ""                 # Group chat ID or individual chat ID
+    chat_type: str = "single"         # "single" | "group"
+    text: str = ""                    # Extracted text content
+    msg_type: str = "text"            # "text" | "image" | "voice" | "event"
+    raw_payload: dict[str, Any] = field(default_factory=dict)  # Original platform payload
+    reply_token: str = ""             # Token/URL needed to send a reply
+
+
+@dataclass
+class PlatformResponse:
+    """Normalized outbound response to be sent back to a platform."""
+
+    content: str                      # Formatted reply text
+    msg_type: str = "text"            # "text" | "markdown" | "news" | "image"
+    status_code: int = 200
+    extra: dict[str, Any] = field(default_factory=dict)  # Platform-specific extras (at_list, buttons, etc.)
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Base Adaptor (Template Method)
+# ═══════════════════════════════════════════════════════════════════
+
+class BasePlatformAdaptor(ABC):
+    """Template-method adaptor for a messaging platform.
+
+    Subclasses override the platform-specific steps; the pipeline
+    (verify → parse → route → format) is shared.
+    """
+
+    platform_name: str = ""
+
+    def __init__(self, config: Any) -> None:
+        self.config = config
+
+    # ── Template method ──────────────────────────────────────
+
+    async def process(self, request: Request) -> Response:
+        """Full pipeline: verify → parse → run agent → format → respond."""
+        # 1. Verify
+        if not await self.verify_request(request):
+            return Response(status_code=403, content="Signature verification failed")
+
+        # 2. Parse
+        msg = await self.parse_message(request)
+
+        # Skip non-text messages gracefully
+        if msg.msg_type not in ("text",):
+            return Response(status_code=200, content=self._empty_ack())
+
+        if not msg.text.strip():
+            return Response(status_code=200, content=self._empty_ack())
+
+        # 3. Quick ACK if async mode
+        try:
+            from agentic_rag.config.settings import get_settings
+            response_mode = get_settings().gateway.response_mode
+        except Exception:
+            response_mode = "sync"
+
+        # 4. Run agent (may be long)
+        if response_mode == "async":
+            # Fire-and-forget: return 200 immediately, push result later
+            import asyncio
+            asyncio.create_task(self._process_async(msg))
+            return Response(status_code=200, content=self._empty_ack())
+
+        # 5. Sync: run agent inline and return result
+        output = await self._run_agent(msg)
+        presp = await self.format_response(output, msg)
+        return await self._build_http_response(presp)
+
+    # ── Steps subclasses must implement ──────────────────────
+
+    @abstractmethod
+    async def verify_request(self, request: Request) -> bool:
+        """Verify the incoming webhook signature/token."""
+        ...
+
+    @abstractmethod
+    async def parse_message(self, request: Request) -> PlatformMessage:
+        """Parse the platform-specific payload into a PlatformMessage."""
+        ...
+
+    @abstractmethod
+    async def format_response(
+        self, output: "AgentOutput", msg: PlatformMessage
+    ) -> PlatformResponse:
+        """Convert AgentOutput to a platform-compatible response."""
+        ...
+
+    @abstractmethod
+    async def _build_http_response(self, presp: PlatformResponse) -> Response:
+        """Build the HTTP response object for this platform."""
+        ...
+
+    @abstractmethod
+    async def push_message(self, msg: PlatformMessage, text: str) -> None:
+        """Send a message to the platform's push API (used in async mode)."""
+        ...
+
+    # ── Shared agent invocation ──────────────────────────────
+
+    async def _run_agent(self, msg: PlatformMessage) -> "AgentOutput":
+        """Route the message to the RAG agent engine and return the result."""
+        from agentic_rag.services.llm.factory import get_llm
+        from agentic_rag.orchestration.l1_tools.registry import get_tool_registry
+        from agentic_rag.agent.router import AgentRouter
+        from agentic_rag.data.models import AgentInput
+
+        # Resolve session
+        sid = await self._resolve_session(msg)
+
+        llm = get_llm()
+        registry = get_tool_registry()
+
+        # Register RAG search tool if not present
+        from agentic_rag.orchestration.l1_tools.rag_tools import RAGSearchTool
+        try:
+            registry.get("rag_search")
+        except Exception:
+            registry.register(RAGSearchTool())
+
+        router = AgentRouter(llm, registry)
+        engine = await router.route(query=msg.text)
+
+        input_data = AgentInput(
+            query=msg.text,
+            parameters={"session_id": sid, "platform": msg.platform},
+        )
+
+        return await engine.run(input_data, turn_id=uuid.uuid4().hex)
+
+    async def _resolve_session(self, msg: PlatformMessage) -> str:
+        """Map (platform, sender_id, chat_id) → internal session_id."""
+        from agentic_rag.entrypoints.gateway.session import get_platform_session_map
+        session_map = get_platform_session_map()
+        return session_map.get_or_create(
+            platform=msg.platform,
+            user_id=msg.sender_id,
+            chat_id=msg.chat_id,
+        )
+
+    async def _process_async(self, msg: PlatformMessage) -> None:
+        """Background: run agent and push result to platform."""
+        try:
+            output = await self._run_agent(msg)
+            presp = await self.format_response(output, msg)
+            await self.push_message(msg, presp.content)
+        except Exception:
+            import sys
+            print(f"  [Gateway/{self.platform_name}] ⚠ Async process failed", flush=True)
+            sys.stdout.flush()
+
+    def _empty_ack(self) -> str:
+        return ""
+
+    # ── Content helpers ──────────────────────────────────────
+
+    def _chunk_text(self, text: str, max_len: int | None = None) -> list[str]:
+        """Split long text into platform-friendly chunks."""
+        if max_len is None:
+            try:
+                from agentic_rag.config.settings import get_settings
+                max_len = get_settings().gateway.max_reply_length
+            except Exception:
+                max_len = 2000
+        chunks = []
+        while len(text) > max_len:
+            split_at = text.rfind("\n", 0, max_len)
+            if split_at < max_len // 2:
+                split_at = text.rfind("。", 0, max_len)
+            if split_at < max_len // 2:
+                split_at = text.rfind(". ", 0, max_len)
+            if split_at < max_len // 2:
+                split_at = max_len
+            chunks.append(text[: split_at + 1])
+            text = text[split_at + 1 :].lstrip()
+        if text.strip():
+            chunks.append(text)
+        return chunks

agentic_rag/entrypoints/gateway/dingtalk/__init__.py

@@ -0,0 +1,191 @@
+"""钉钉 (DingTalk) bot gateway adaptor."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Optional
+
+import httpx
+from fastapi import APIRouter, Request, Response
+
+from agentic_rag.entrypoints.gateway.base import (
+    BasePlatformAdaptor,
+    PlatformMessage,
+    PlatformResponse,
+)
+
+router = APIRouter()
+
+
+# ═══════════════════════════════════════════════════════════════
+# DingTalk Adaptor
+# ═══════════════════════════════════════════════════════════════
+
+class DingTalkAdaptor(BasePlatformAdaptor):
+    """钉钉 bot webhook adaptor.
+
+    Reference: https://open.dingtalk.com/document/orgapp/receive-messages
+    """
+
+    platform_name = "dingtalk"
+
+    # ── Verify ────────────────────────────────────────────────
+
+    async def verify_request(self, request: Request) -> bool:
+        """Verify DingTalk HMAC-SHA256 signature."""
+        timestamp = request.headers.get("timestamp", "")
+        sign = request.headers.get("sign", "")
+        if not timestamp or not sign:
+            return False
+
+        secret = getattr(self.config, "app_secret", "")
+        if not secret:
+            return True  # No secret configured — skip verification
+
+        expected = self._hmac_sign(timestamp, secret)
+        return sign == expected
+
+    @staticmethod
+    def _hmac_sign(timestamp: str, secret: str) -> str:
+        """Compute DingTalk HMAC-SHA256 signature."""
+        raw = f"{timestamp}\n{secret}"
+        mac = hmac.new(
+            secret.encode("utf-8"),
+            raw.encode("utf-8"),
+            hashlib.sha256,
+        )
+        return base64.b64encode(mac.digest()).decode()
+
+    # ── Parse ─────────────────────────────────────────────────
+
+    async def parse_message(self, request: Request) -> PlatformMessage:
+        """Parse DingTalk robot callback JSON body."""
+        try:
+            body = await request.json()
+        except Exception:
+            return PlatformMessage(platform="dingtalk", sender_id="", msg_type="unknown")
+
+        msg_type = body.get("msgtype", "unknown")
+        sender_id = body.get("senderStaffId", body.get("senderId", ""))
+        sender_name = body.get("senderNick", "")
+        conversation_id = body.get("conversationId", "")
+        chat_type = body.get("conversationType", "1")  # 1=single, 2=group
+        session_webhook = body.get("sessionWebhook", "")
+
+        # Extract text
+        text = ""
+        if msg_type == "text":
+            text = body.get("text", {}).get("content", "")
+        elif msg_type == "image":
+            text = "[图片消息]"
+
+        return PlatformMessage(
+            platform="dingtalk",
+            sender_id=str(sender_id),
+            sender_name=sender_name,
+            chat_id=conversation_id,
+            chat_type="group" if str(chat_type) == "2" else "single",
+            text=text,
+            msg_type=msg_type,
+            raw_payload=body,
+            reply_token=session_webhook,
+        )
+
+    # ── Format Response ───────────────────────────────────────
+
+    async def format_response(
+        self, output, msg: PlatformMessage
+    ) -> PlatformResponse:
+        """Convert agent output to DingTalk markdown."""
+        from agentic_rag.config.settings import get_settings
+        max_len = get_settings().gateway.max_reply_length
+
+        answer = output.final_answer or "抱歉，我暂时无法回答这个问题。"
+
+        # Truncate if too long
+        if len(answer) > max_len:
+            chunks = self._chunk_text(answer, max_len)
+            # Return first chunk; rest sent via push if needed
+            answer = chunks[0]
+            if len(chunks) > 1:
+                answer += f"\n\n...（共 {len(chunks)} 段，第 1 段）"
+
+        return PlatformResponse(
+            content=answer,
+            msg_type="text",
+        )
+
+    # ── HTTP Response ─────────────────────────────────────────
+
+    async def _build_http_response(self, presp: PlatformResponse) -> Response:
+        """Build DingTalk-compatible JSON response."""
+        return Response(
+            content=json.dumps(
+                {"msgtype": "text", "text": {"content": presp.content}},
+                ensure_ascii=False,
+            ),
+            media_type="application/json",
+            status_code=presp.status_code,
+        )
+
+    # ── Push (async mode) ─────────────────────────────────────
+
+    async def push_message(self, msg: PlatformMessage, text: str) -> None:
+        """Send message back via DingTalk sessionWebhook."""
+        webhook_url = msg.reply_token
+        if not webhook_url:
+            return
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                await client.post(
+                    webhook_url,
+                    json={"msgtype": "text", "text": {"content": text}},
+                )
+        except Exception:
+            import sys
+            print(f"  [DingTalk] ⚠ Push to webhook failed", flush=True)
+            sys.stdout.flush()
+
+
+# ── Global adaptor instance (lazy) ──────────────────────────────
+
+_adaptor: Optional[DingTalkAdaptor] = None
+
+
+def _get_adaptor() -> DingTalkAdaptor:
+    global _adaptor
+    if _adaptor is None:
+        from agentic_rag.config.settings import get_settings
+        _adaptor = DingTalkAdaptor(get_settings().gateway.dingtalk)
+    return _adaptor
+
+
+# ═══════════════════════════════════════════════════════════════
+# Webhook Endpoints
+# ═══════════════════════════════════════════════════════════════
+
+@router.post("/gateway/dingtalk")
+async def dingtalk_callback(request: Request):
+    """Receive DingTalk robot callback messages.
+
+    DingTalk POSTs JSON with headers:
+    - timestamp: Unix timestamp string
+    - sign: HMAC-SHA256(timestamp + "\\n" + app_secret)
+
+    Body (text message):
+    {
+        "conversationId": "...",
+        "senderId": "...",
+        "senderNick": "张三",
+        "msgtype": "text",
+        "text": {"content": "hello"},
+        "sessionWebhook": "https://oapi.dingtalk.com/robot/..."
+    }
+    """
+    adaptor = _get_adaptor()
+    return await adaptor.process(request)

agentic_rag/entrypoints/gateway/qqbot/__init__.py

@@ -0,0 +1,372 @@
+"""QQ Bot (官方) gateway adaptor.
+
+QQ Bot 使用 WebSocket 接收事件 + REST API 发送消息，不需要公网 webhook。
+
+沙箱注册: https://q.qq.com
+文档: https://bot.q.qq.com/wiki
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from typing import Optional
+
+import httpx
+import websockets
+from fastapi import APIRouter
+
+from agentic_rag.entrypoints.gateway.session import get_platform_session_map
+
+router = APIRouter()
+
+# QQ Bot 事件类型
+EVENT_C2C_MESSAGE = "C2C_MESSAGE_CREATE"        # 单聊消息
+EVENT_GROUP_AT = "GROUP_AT_MESSAGE_CREATE"       # 群聊 @消息
+EVENT_READY = "READY"                             # 连接就绪
+OPCODE_DISPATCH = 0                               # 服务端推送事件
+OPCODE_HEARTBEAT = 1                              # 心跳
+OPCODE_IDENTIFY = 2                               # 鉴权
+OPCODE_RECONNECT = 7                              # 服务端要求重连
+OPCODE_HELLO = 10                                 # 服务端下发心跳周期
+
+
+# ═══════════════════════════════════════════════════════════════
+# QQ Bot Client
+# ═══════════════════════════════════════════════════════════════
+
+class QQBotClient:
+    """QQ Bot WebSocket 客户端。
+
+    在后台运行，维护与 QQ 服务器的长连接，接收消息并调用 Agent。
+
+    使用方式:
+        client = QQBotClient(config)
+        asyncio.create_task(client.run())
+    """
+
+    def __init__(self, config) -> None:
+        self.config = config
+        self._ws_url = (
+            "wss://sandbox.api.sgroup.qq.com/websocket"
+            if config.sandbox
+            else "wss://api.sgroup.qq.com/websocket"
+        )
+        self._http_base = (
+            "https://sandbox.api.sgroup.qq.com"
+            if config.sandbox
+            else "https://api.sgroup.qq.com"
+        )
+        self._app_id = config.app_id
+        self._app_secret = config.app_secret
+        self._access_token: str = ""
+        self._session_id: str = ""
+        self._seq: int = 0
+        self._running = False
+
+    # ── Lifecycle ──────────────────────────────────────────────
+
+    async def run(self) -> None:
+        """主循环: 连接 → 处理事件 → 断线重连"""
+        self._running = True
+        backoff = 1
+
+        while self._running:
+            try:
+                await self._connect()
+                backoff = 1  # 成功连接后重置退避
+            except Exception as e:
+                import sys
+                print(f"  [QQBot] ⚠ Connection lost: {e}  (retry in {backoff}s)", flush=True)
+                sys.stdout.flush()
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, 60)
+
+    async def stop(self) -> None:
+        """停止客户端"""
+        self._running = False
+
+    # ── Connection ─────────────────────────────────────────────
+
+    async def _connect(self) -> None:
+        """建立 WebSocket 连接并进入事件循环"""
+        if not await self._get_token():
+            return
+
+        print(f"  [QQBot] Connecting to {self._ws_url}...", flush=True)
+
+        async with websockets.connect(self._ws_url, ping_interval=None) as ws:
+            # 等待服务端 Hello
+            hello = json.loads(await ws.recv())
+            if hello.get("op") != OPCODE_HELLO:
+                raise RuntimeError(f"Expected Hello, got op={hello.get('op')}")
+
+            heartbeat_interval = hello["d"]["heartbeat_interval"]  # ms
+            print(f"  [QQBot] Connected, heartbeat={heartbeat_interval}ms", flush=True)
+
+            # 发送鉴权
+            await self._identify(ws)
+
+            # 等待 Ready
+            await self._wait_ready(ws)
+
+            # 启动心跳
+            heartbeat_task = asyncio.create_task(
+                self._heartbeat_loop(ws, heartbeat_interval)
+            )
+
+            try:
+                # 事件循环
+                await self._event_loop(ws)
+            finally:
+                heartbeat_task.cancel()
+
+    async def _identify(self, ws) -> None:
+        """发送鉴权帧"""
+        payload = {
+            "op": OPCODE_IDENTIFY,
+            "d": {
+                "token": f"QQBot {self._access_token}",
+                "intents": (1 << 25) | (1 << 0),  # C2C | GUILDS (群@)
+                "shard": [0, 1],
+                "properties": {},
+            },
+        }
+        await ws.send(json.dumps(payload))
+        print("  [QQBot] Identify sent", flush=True)
+
+    async def _wait_ready(self, ws) -> None:
+        """等待 Ready 事件（含 session_id）"""
+        while True:
+            raw = await ws.recv()
+            msg = json.loads(raw)
+            if msg.get("t") == EVENT_READY:
+                self._session_id = msg["d"].get("session_id", "")
+                user = msg["d"].get("user", {})
+                print(
+                    f"  [QQBot] READY — bot: {user.get('username', '?')}#{user.get('id', '?')}",
+                    flush=True,
+                )
+                return
+
+    # ── Event Loop ─────────────────────────────────────────────
+
+    async def _event_loop(self, ws) -> None:
+        """接收并处理事件"""
+        async for raw in ws:
+            msg = json.loads(raw)
+            op = msg.get("op")
+            self._seq = msg.get("s", self._seq)
+
+            if op == OPCODE_RECONNECT:
+                print("  [QQBot] Server requested reconnect", flush=True)
+                return
+
+            if op == OPCODE_DISPATCH:
+                event_type = msg.get("t", "")
+                event_data = msg.get("d", {})
+                asyncio.create_task(self._handle_event(event_type, event_data))
+
+    async def _heartbeat_loop(self, ws, interval_ms: int) -> None:
+        """定时发送心跳"""
+        interval_s = interval_ms / 1000.0 * 0.8  # 留点余量
+        while True:
+            await asyncio.sleep(interval_s)
+            try:
+                await ws.send(json.dumps({"op": OPCODE_HEARTBEAT, "d": self._seq}))
+            except Exception:
+                break
+
+    # ── Token ──────────────────────────────────────────────────
+
+    async def _get_token(self) -> bool:
+        """获取 access_token"""
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                resp = await client.post(
+                    "https://bots.qq.com/app/getAppAccessToken",
+                    json={
+                        "appId": self._app_id,
+                        "clientSecret": self._app_secret,
+                    },
+                )
+                data = resp.json()
+                self._access_token = data.get("access_token", "")
+                if self._access_token:
+                    print(f"  [QQBot] Token OK ({len(self._access_token)} chars)", flush=True)
+                    return True
+                print(f"  [QQBot] Token failed: {data}", flush=True)
+                return False
+        except Exception as e:
+            print(f"  [QQBot] Token error: {e}", flush=True)
+            return False
+
+    # ── Event Handling ─────────────────────────────────────────
+
+    async def _handle_event(self, event_type: str, data: dict) -> None:
+        """处理 QQ 事件"""
+        if event_type == EVENT_C2C_MESSAGE:
+            await self._on_private_message(data)
+        elif event_type == EVENT_GROUP_AT:
+            await self._on_group_at(data)
+
+    async def _on_private_message(self, data: dict) -> None:
+        """处理单聊消息"""
+        author = data.get("author", {})
+        user_id = author.get("id", "")
+        content = data.get("content", "").strip()
+        msg_id = data.get("id", "")
+
+        if not content or not user_id:
+            return
+
+        # 去掉命令前缀 "/" 和 @ 的干扰
+        content = content.lstrip("/").strip()
+
+        print(f"  [QQBot] 📩 C2C: {user_id} → {content[:50]}", flush=True)
+        await self._process_message(user_id, f"qq:{user_id}", content, msg_id)
+
+    async def _on_group_at(self, data: dict) -> None:
+        """处理群聊 @消息"""
+        author = data.get("author", {})
+        user_id = author.get("id", "")
+        group_id = data.get("group_openid", data.get("group_id", ""))
+        content = data.get("content", "").strip()
+        msg_id = data.get("id", "")
+
+        if not content or not user_id:
+            return
+
+        # 内容中可能包含 @机器人 的 mention，去掉
+        # QQ 消息格式可能是: "<@!bot_id> 内容" 或直接是纯文本
+        import re
+        content = re.sub(r"<@!\d+>", "", content).strip()
+
+        if not content:
+            return
+
+        print(f"  [QQBot] 📩 Group@: {user_id} in {group_id} → {content[:50]}", flush=True)
+        await self._process_message(user_id, f"qq:group:{group_id}:{user_id}", content, msg_id)
+
+    async def _process_message(
+        self, user_id: str, session_key: str, text: str, msg_id: str = ""
+    ) -> None:
+        """调用 Agent Engine 并回复"""
+        try:
+            # 解析 session
+            session_map = get_platform_session_map()
+            sid = session_map.get_or_create(platform="qqbot", user_id=session_key)
+
+            # 调用 Agent
+            output = await self._run_agent(sid, text)
+
+            # 回复
+            answer = output.final_answer or "抱歉，我暂时无法回答。"
+            # 限制长度
+            if len(answer) > 2000:
+                answer = answer[:1950] + "\n\n...（内容过长已截断）"
+
+            await self._send_reply(user_id, answer, msg_id)
+        except Exception as e:
+            import sys
+            print(f"  [QQBot] ⚠ Process error: {e}", flush=True)
+            sys.stdout.flush()
+            await self._send_reply(user_id, "处理消息时出错了，请稍后重试。", msg_id)
+
+    async def _run_agent(self, session_id: str, query: str):
+        """调用 ReAct Agent Engine"""
+        from agentic_rag.services.llm.factory import get_llm
+        from agentic_rag.orchestration.l1_tools.registry import get_tool_registry
+        from agentic_rag.agent.router import AgentRouter
+        from agentic_rag.data.models import AgentInput
+
+        llm = get_llm()
+        registry = get_tool_registry()
+
+        from agentic_rag.orchestration.l1_tools.rag_tools import RAGSearchTool
+        try:
+            registry.get("rag_search")
+        except Exception:
+            registry.register(RAGSearchTool())
+
+        router = AgentRouter(llm, registry)
+        engine = await router.route(query=query)
+
+        input_data = AgentInput(
+            query=query,
+            parameters={"session_id": session_id, "platform": "qqbot"},
+        )
+
+        return await engine.run(input_data, turn_id=uuid.uuid4().hex)
+
+    async def _send_reply(self, user_id: str, text: str, msg_id: str = "") -> None:
+        """通过 REST API 发送回复"""
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                resp = await client.post(
+                    f"{self._http_base}/v2/users/{user_id}/messages",
+                    headers={
+                        "Authorization": f"QQBot {self._access_token}",
+                        "Content-Type": "application/json",
+                    },
+                    json={
+                        "content": text,
+                        "msg_type": 0,  # 文本消息
+                        "msg_id": msg_id,
+                    },
+                )
+                if resp.status_code != 200:
+                    print(f"  [QQBot] ⚠ Reply failed ({resp.status_code}): {resp.text[:100]}", flush=True)
+        except Exception as e:
+            print(f"  [QQBot] ⚠ Reply error: {e}", flush=True)
+
+
+# ═══════════════════════════════════════════════════════════════
+# Global client instance
+# ═══════════════════════════════════════════════════════════════
+
+_client: Optional[QQBotClient] = None
+
+
+async def start_qqbot() -> None:
+    """在 app 启动时启动 QQ Bot 客户端"""
+    from agentic_rag.config.settings import get_settings
+
+    settings = get_settings()
+    cfg = settings.gateway.qqbot
+    if not cfg.enabled:
+        return
+
+    global _client
+    if _client is not None:
+        return
+
+    _client = QQBotClient(cfg)
+    asyncio.create_task(_client.run())
+    print(f"  [QQBot] Started {'(sandbox)' if cfg.sandbox else '(production)'}", flush=True)
+
+
+async def stop_qqbot() -> None:
+    """在 app 关闭时停止 QQ Bot"""
+    global _client
+    if _client:
+        await _client.stop()
+        _client = None
+
+
+# ═══════════════════════════════════════════════════════════════
+# Status endpoint
+# ═══════════════════════════════════════════════════════════════
+
+@router.get("/gateway/qqbot/status")
+async def qqbot_status():
+    """查看 QQ Bot 连接状态"""
+    global _client
+    if _client is None:
+        return {"status": "disabled"}
+    return {
+        "status": "running" if _client._running else "stopped",
+        "session_id": _client._session_id,
+        "sandbox": _client.config.sandbox,
+    }

agentic_rag/entrypoints/gateway/router.py

@@ -0,0 +1,30 @@
+"""Aggregated FastAPI router that mounts all enabled platform webhook routers."""
+
+from fastapi import APIRouter
+
+
+def get_gateway_router() -> APIRouter:
+    """Build a single APIRouter that mounts all enabled platform webhook routers."""
+    from agentic_rag.config.settings import get_settings
+
+    settings = get_settings()
+    gw = settings.gateway
+
+    if not gw.enabled:
+        return APIRouter()
+
+    router = APIRouter(prefix="", tags=["Gateway"])
+
+    if gw.wechat_work.enabled:
+        from agentic_rag.entrypoints.gateway.wechat_work import router as wx_router
+        router.include_router(wx_router)
+
+    if gw.dingtalk.enabled:
+        from agentic_rag.entrypoints.gateway.dingtalk import router as dd_router
+        router.include_router(dd_router)
+
+    if gw.qqbot.enabled:
+        from agentic_rag.entrypoints.gateway.qqbot import router as qq_router
+        router.include_router(qq_router)
+
+    return router

agentic_rag/entrypoints/gateway/session.py

@@ -0,0 +1,89 @@
+"""Platform session mapping — binds (platform, user_id, chat_id) → internal session_id.
+
+Uses an in-memory LRU cache for hot-path lookups, backed by SQLite for persistence.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Optional
+
+from agentic_rag.data.db.session_repo import SessionRepo
+
+
+class PlatformSessionMap:
+    """Maps (platform, platform_user_id, chat_id) → internal session_id."""
+
+    def __init__(self, max_cache_size: int = 1000) -> None:
+        self._cache: OrderedDict[tuple[str, str, str], str] = OrderedDict()
+        self._max_cache = max_cache_size
+
+    # ── Public API ──────────────────────────────────────────
+
+    def get_or_create(self, platform: str, user_id: str, chat_id: str = "") -> str:
+        """Look up an existing session or create a new one."""
+        cache_key = (platform, user_id, chat_id)
+
+        # 1. Cache hit
+        if cache_key in self._cache:
+            self._cache.move_to_end(cache_key)
+            return self._cache[cache_key]
+
+        # 2. DB lookup
+        sid = self._db_get(platform, user_id, chat_id)
+        if sid:
+            self._set_cache(cache_key, sid)
+            return sid
+
+        # 3. Create new session
+        repo = SessionRepo()
+        display_name = f"{platform}:{user_id}"
+        if chat_id:
+            display_name += f":{chat_id}"
+        session = repo.create(user_id=display_name)
+        sid = session["id"]
+        self._db_set(platform, user_id, chat_id, sid)
+
+        self._set_cache(cache_key, sid)
+        return sid
+
+    def invalidate(self, platform: str, user_id: str, chat_id: str = "") -> None:
+        """Remove a cached mapping (on session deletion, etc.)."""
+        cache_key = (platform, user_id, chat_id)
+        self._cache.pop(cache_key, None)
+
+    # ── Internal cache helpers ───────────────────────────────
+
+    def _set_cache(self, key: tuple[str, str, str], sid: str) -> None:
+        if len(self._cache) >= self._max_cache:
+            self._cache.popitem(last=False)  # evict oldest
+        self._cache[key] = sid
+
+    # ── DB helpers (delegated to SessionRepo) ────────────────
+
+    @staticmethod
+    def _db_get(platform: str, user_id: str, chat_id: str) -> Optional[str]:
+        try:
+            return SessionRepo().get_platform_session(platform, user_id, chat_id)
+        except Exception:
+            return None
+
+    @staticmethod
+    def _db_set(platform: str, user_id: str, chat_id: str, session_id: str) -> None:
+        try:
+            SessionRepo().bind_platform_session(platform, user_id, chat_id, session_id)
+        except Exception:
+            pass
+
+
+# ── Singleton ──────────────────────────────────────────────────
+
+_platform_session_map: Optional[PlatformSessionMap] = None
+
+
+def get_platform_session_map() -> PlatformSessionMap:
+    """Get the global PlatformSessionMap singleton."""
+    global _platform_session_map
+    if _platform_session_map is None:
+        _platform_session_map = PlatformSessionMap()
+    return _platform_session_map

agentic_rag/entrypoints/gateway/wechat_work/__init__.py

@@ -0,0 +1,359 @@
+"""企业微信 (WeChat Work) 自建应用 gateway adaptor.
+
+Reference: https://developer.work.weixin.qq.com/document/path/90238
+"""
+
+from __future__ import annotations
+
+import json
+import time as time_module
+import xml.etree.ElementTree as ET
+from typing import Optional
+
+import httpx
+from fastapi import APIRouter, Query, Request, Response
+
+from agentic_rag.entrypoints.gateway.base import (
+    BasePlatformAdaptor,
+    PlatformMessage,
+    PlatformResponse,
+)
+
+router = APIRouter()
+
+
+# ═══════════════════════════════════════════════════════════════
+# Token Manager (for active push)
+# ═══════════════════════════════════════════════════════════════
+
+class WeChatTokenManager:
+    """Cache and refresh WeChat Work access_token.
+
+    Token expires in 7200s; we refresh at half-life.
+    Ref: https://developer.work.weixin.qq.com/document/path/91039
+    """
+
+    def __init__(self, corp_id: str, secret: str) -> None:
+        self._corp_id = corp_id
+        self._secret = secret
+        self._token: str = ""
+        self._expires_at: float = 0.0
+
+    async def get_token(self) -> str:
+        """Get a valid access_token, refreshing if needed."""
+        if self._token and time_module.time() < self._expires_at - 300:
+            return self._token
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                resp = await client.get(
+                    "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
+                    params={
+                        "corpid": self._corp_id,
+                        "corpsecret": self._secret,
+                    },
+                )
+                data = resp.json()
+                if data.get("errcode") == 0:
+                    self._token = data["access_token"]
+                    self._expires_at = time_module.time() + data.get("expires_in", 7200)
+                    return self._token
+        except Exception:
+            pass
+        return self._token
+
+
+# ═══════════════════════════════════════════════════════════════
+# Adaptor
+# ═══════════════════════════════════════════════════════════════
+
+class WeChatWorkAdaptor(BasePlatformAdaptor):
+    """企业微信自建应用 adaptor."""
+
+    platform_name = "wechat_work"
+
+    def __init__(self, config) -> None:
+        super().__init__(config)
+        from agentic_rag.entrypoints.gateway.wechat_work.crypto import WeChatCrypto
+        self._crypto = WeChatCrypto(
+            token=config.token,
+            encoding_aes_key=config.encoding_aes_key,
+            corp_id=config.corp_id,
+        )
+        self._token_mgr: Optional[WeChatTokenManager] = None
+        if config.secret:
+            self._token_mgr = WeChatTokenManager(config.corp_id, config.secret)
+
+    # ── URL Verification (GET) ────────────────────────────────
+
+    async def verify_url(
+        self, msg_signature: str, timestamp: str, nonce: str, echostr: str
+    ) -> str:
+        """Handle URL verification challenge from WeChat Work.
+
+        Returns the decrypted echostr string (plain text), or raises ValueError.
+        """
+        if not self._crypto.verify_signature(msg_signature, timestamp, nonce, echostr):
+            raise ValueError("Signature verification failed")
+        return self._crypto.decrypt(echostr)
+
+    # ── Verify (POST) ─────────────────────────────────────────
+
+    async def verify_request(self, request: Request) -> bool:
+        """Verify WeChat Work callback signature."""
+        msg_signature = request.query_params.get("msg_signature", "")
+        timestamp = request.query_params.get("timestamp", "")
+        nonce = request.query_params.get("nonce", "")
+
+        if not msg_signature or not timestamp or not nonce:
+            return False
+
+        # Read body and verify; body is encrypted XML
+        try:
+            body = (await request.body()).decode("utf-8")
+        except Exception:
+            return False
+
+        # Extract <Encrypt> from XML for signature
+        try:
+            root = ET.fromstring(body)
+            encrypt_text = root.findtext("Encrypt", "")
+        except Exception:
+            encrypt_text = body
+
+        return self._crypto.verify_signature(
+            msg_signature, timestamp, nonce, encrypt_text
+        )
+
+    # ── Parse ─────────────────────────────��───────────────────
+
+    async def parse_message(self, request: Request) -> PlatformMessage:
+        """Decrypt and parse WeChat Work callback XML."""
+        msg_signature = request.query_params.get("msg_signature", "")
+        timestamp = request.query_params.get("timestamp", "")
+        nonce = request.query_params.get("nonce", "")
+
+        body = (await request.body()).decode("utf-8")
+
+        # Extract and decrypt
+        try:
+            root = ET.fromstring(body)
+            encrypt_text = root.findtext("Encrypt", "")
+        except ET.ParseError:
+            return PlatformMessage(platform="wechat_work", sender_id="", msg_type="unknown")
+
+        if not encrypt_text:
+            return PlatformMessage(platform="wechat_work", sender_id="", msg_type="unknown")
+
+        plain_xml = self._crypto.decrypt(encrypt_text)
+
+        # Parse decrypted XML
+        try:
+            msg_root = ET.fromstring(plain_xml)
+        except ET.ParseError:
+            return PlatformMessage(platform="wechat_work", sender_id="", msg_type="unknown")
+
+        msg_type = msg_root.findtext("MsgType", "unknown")
+        sender_id = msg_root.findtext("FromUserName", "")
+        agent_id = msg_root.findtext("AgentID", "")
+        create_time = msg_root.findtext("CreateTime", "")
+
+        text = ""
+        if msg_type == "text":
+            text = msg_root.findtext("Content", "")
+        elif msg_type == "image":
+            text = "[图片消息]"
+        elif msg_type == "voice":
+            recognition = msg_root.findtext("Recognition", "")  # 语音识别结果
+            text = recognition or "[语音消息]"
+        elif msg_type == "event":
+            event_type = msg_root.findtext("Event", "")
+            if event_type == "click":
+                event_key = msg_root.findtext("EventKey", "")
+                text = event_key  # 菜单点击
+            elif event_type == "subscribe":
+                text = "hello"  # 关注事件 → 触发欢迎语
+
+        return PlatformMessage(
+            platform="wechat_work",
+            sender_id=sender_id,
+            sender_name="",
+            chat_id=sender_id,  # WeChat Work 单聊; 群聊场景有 ChatId
+            chat_type="single",
+            text=text,
+            msg_type=msg_type,
+            raw_payload={
+                "agent_id": agent_id,
+                "create_time": create_time,
+                "msg_type": msg_type,
+                "plain_xml": plain_xml,
+            },
+            reply_token=json.dumps({
+                "to_user": sender_id,
+                "agent_id": agent_id,
+            }),
+        )
+
+    # ── Format ────────────────────────────────────────────────
+
+    async def format_response(
+        self, output, msg: PlatformMessage
+    ) -> PlatformResponse:
+        """Convert agent output to WeChat Work text response."""
+        from agentic_rag.config.settings import get_settings
+        max_len = get_settings().gateway.max_reply_length
+
+        answer = output.final_answer or "抱歉，我暂时无法回答这个问题。"
+
+        # WeChat Work text limit is 2048 chars
+        effective_max = min(max_len, 2048)
+        if len(answer) > effective_max:
+            chunks = self._chunk_text(answer, effective_max)
+            answer = chunks[0]
+            if len(chunks) > 1:
+                answer += f"\n\n...（共 {len(chunks)} 段，第 1 段）"
+
+        # Remove markdown that WeChat Work doesn't support
+        answer = self._strip_markdown(answer)
+
+        return PlatformResponse(
+            content=answer,
+            msg_type="text",
+            extra=msg.raw_payload,
+        )
+
+    # ── Build HTTP Response (encrypted XML) ──────────────────
+
+    async def _build_http_response(self, presp: PlatformResponse) -> Response:
+        """Build encrypted XML response for WeChat Work."""
+        to_user = presp.extra.get("to_user", "")
+        agent_id = presp.extra.get("agent_id", "")
+        agent_id_from_cfg = getattr(self.config, "agent_id", "")
+
+        # Build plain text reply XML
+        create_time = str(int(time_module.time()))
+        reply_xml = (
+            "<xml>"
+            f"<ToUserName><![CDATA[{to_user}]]></ToUserName>"
+            f"<FromUserName><![CDATA[{agent_id or agent_id_from_cfg}]]></FromUserName>"
+            f"<CreateTime>{create_time}</CreateTime>"
+            "<MsgType><![CDATA[text]]></MsgType>"
+            f"<Content><![CDATA[{presp.content}]]></Content>"
+            "</xml>"
+        )
+
+        # Encrypt
+        encrypted = self._crypto.encrypt(reply_xml)
+        sig, ts, nonce = self._crypto.build_response_signature(encrypted)
+
+        # Wrap in encrypted XML envelope
+        response_xml = (
+            "<xml>"
+            f"<Encrypt><![CDATA[{encrypted}]]></Encrypt>"
+            f"<MsgSignature><![CDATA[{sig}]]></MsgSignature>"
+            f"<TimeStamp>{ts}</TimeStamp>"
+            f"<Nonce><![CDATA[{nonce}]]></Nonce>"
+            "</xml>"
+        )
+
+        return Response(content=response_xml, media_type="application/xml")
+
+    # ── Push (async mode via WeChat API) ──────────────────────
+
+    async def push_message(self, msg: PlatformMessage, text: str) -> None:
+        """Send message via WeChat Work API (POST /cgi-bin/message/send)."""
+        if not self._token_mgr:
+            return
+
+        to_user = msg.sender_id
+        agent_id = getattr(self.config, "agent_id", "")
+        token = await self._token_mgr.get_token()
+        if not token:
+            return
+
+        text = self._strip_markdown(text)
+
+        body = {
+            "touser": to_user,
+            "msgtype": "text",
+            "agentid": int(agent_id) if agent_id.isdigit() else agent_id,
+            "text": {"content": text},
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                await client.post(
+                    f"https://qyapi.weixin.qq.com/cgi-bin/message/send"
+                    f"?access_token={token}",
+                    json=body,
+                )
+        except Exception:
+            import sys
+            print(f"  [WeChatWork] ⚠ Push message failed", flush=True)
+            sys.stdout.flush()
+
+    # ── Helpers ───────────────────────────────────────────────
+
+    @staticmethod
+    def _strip_markdown(text: str) -> str:
+        """Remove unsupported markdown for WeChat Work text messages."""
+        import re
+        # Bold → plain
+        text = re.sub(r"\*\*(.+?)\*\*", r"\1", text)
+        # Code blocks → plain
+        text = re.sub(r"```[\s\S]*?```", "", text)
+        text = re.sub(r"`([^`]+)`", r"\1", text)
+        # Headers → plain
+        text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)
+        # Horizontal rules → remove
+        text = re.sub(r"^-{3,}$", "", text, flags=re.MULTILINE)
+        # Links → text only
+        text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+        return text
+
+
+# ── Global adaptor instance ────────────────────────────────────
+
+_adaptor: Optional[WeChatWorkAdaptor] = None
+
+
+def _get_adaptor() -> WeChatWorkAdaptor:
+    global _adaptor
+    if _adaptor is None:
+        from agentic_rag.config.settings import get_settings
+        _adaptor = WeChatWorkAdaptor(get_settings().gateway.wechat_work)
+    return _adaptor
+
+
+# ═══════════════════════════════════════════════════════════════
+# Webhook Endpoints
+# ═══════════════════════════════════════════════════════════════
+
+@router.get("/gateway/wechat_work")
+async def wechat_work_verify(
+    msg_signature: str = Query(...),
+    timestamp: str = Query(...),
+    nonce: str = Query(...),
+    echostr: str = Query(...),
+):
+    """URL verification — WeChat Work server sends a GET with echostr challenge.
+
+    Must return the decrypted echostr as plain text (not JSON, not XML).
+    """
+    adaptor = _get_adaptor()
+    try:
+        decrypted = await adaptor.verify_url(msg_signature, timestamp, nonce, echostr)
+        return Response(content=decrypted, media_type="text/plain")
+    except ValueError:
+        return Response(status_code=403, content="Verification failed")
+
+
+@router.post("/gateway/wechat_work")
+async def wechat_work_callback(request: Request):
+    """Receive WeChat Work callback messages (encrypted XML).
+
+    Query params: msg_signature, timestamp, nonce
+    Body: encrypted XML with <Encrypt>...</Encrypt>
+    """
+    adaptor = _get_adaptor()
+    return await adaptor.process(request)

agentic_rag/entrypoints/gateway/wechat_work/crypto.py

@@ -0,0 +1,113 @@
+"""WeChat Work message encryption/decryption (AES-256-CBC + SHA1).
+
+Reference: https://developer.work.weixin.qq.com/document/path/90968
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import random
+import struct
+import time
+
+
+class WeChatCrypto:
+    """Handle WeChat Work callback message encryption and signature verification.
+
+    The EncodingAESKey is a 43-char Base64 string that decodes to a 32-byte AES key.
+    Messages use AES-256-CBC with the AES key as IV (first 16 bytes of key).
+    """
+
+    BLOCK_SIZE = 32
+
+    def __init__(self, token: str, encoding_aes_key: str, corp_id: str) -> None:
+        self.token = token
+        self.corp_id = corp_id
+        # EncodingAESKey is 43-char Base64 → 32-byte AES key (add padding '=' for decoding)
+        self.aes_key = base64.b64decode(encoding_aes_key + "=")
+
+    # ── Signature Verification ─────────────────────────────────
+
+    def verify_signature(
+        self, msg_signature: str, timestamp: str, nonce: str, echostr: str
+    ) -> bool:
+        """Verify callback signature from WeChat Work server."""
+        expected = self._sha1(timestamp, nonce, echostr)
+        return msg_signature == expected
+
+    # ── Message Decryption ─────────────────────────────────────
+
+    def decrypt(self, ciphertext: str) -> str:
+        """Decrypt an encrypted message XML from WeChat Work.
+
+        Returns the plain text XML string.
+        """
+        raw = base64.b64decode(ciphertext)
+        plain = self._aes_decrypt(raw)
+
+        # Strip PKCS#7 padding
+        pad = plain[-1]
+        plain = plain[:-pad]
+
+        # Parse: random(16) + msg_len(4, big-endian) + msg + corp_id
+        msg_len = struct.unpack("!I", plain[16:20])[0]
+        msg = plain[20 : 20 + msg_len].decode("utf-8")
+        received_corp_id = plain[20 + msg_len :].decode("utf-8")
+
+        if received_corp_id != self.corp_id:
+            raise ValueError(
+                f"Corp ID mismatch: expected {self.corp_id!r}, got {received_corp_id!r}"
+            )
+        return msg
+
+    # ── Message Encryption ─────────────────────────────────────
+
+    def encrypt(self, plain_text: str) -> str:
+        """Encrypt a reply message for WeChat Work.
+
+        Returns base64-encoded ciphertext.
+        """
+        random_bytes = bytes(random.getrandbits(8) for _ in range(16))
+        text_bytes = plain_text.encode("utf-8")
+        corp_bytes = self.corp_id.encode("utf-8")
+        msg_len = struct.pack("!I", len(text_bytes))
+
+        raw = random_bytes + msg_len + text_bytes + corp_bytes
+
+        # PKCS#7 padding to 32-byte block
+        pad = self.BLOCK_SIZE - len(raw) % self.BLOCK_SIZE
+        raw += bytes([pad] * pad)
+
+        encrypted = self._aes_encrypt(raw)
+        return base64.b64encode(encrypted).decode()
+
+    # ── Signature Generation (for responses) ───────────────────
+
+    def build_response_signature(self, encrypted_msg: str) -> str:
+        """Build msg_signature for an encrypted response."""
+        ts = str(int(time.time()))
+        nonce = self._random_nonce()
+        sig = self._sha1(ts, nonce, encrypted_msg)
+        return sig, ts, nonce
+
+    # ── Internal helpers ───────────────────────────────────────
+
+    def _sha1(self, timestamp: str, nonce: str, msg: str) -> str:
+        """SHA1 of sorted [token, timestamp, nonce, msg]."""
+        params = sorted([self.token, timestamp, nonce, msg])
+        return hashlib.sha1("".join(params).encode("utf-8")).hexdigest()
+
+    def _aes_decrypt(self, data: bytes) -> bytes:
+        from Crypto.Cipher import AES
+        cipher = AES.new(self.aes_key, AES.MODE_CBC, iv=self.aes_key[:16])
+        return cipher.decrypt(data)
+
+    def _aes_encrypt(self, data: bytes) -> bytes:
+        from Crypto.Cipher import AES
+        cipher = AES.new(self.aes_key, AES.MODE_CBC, iv=self.aes_key[:16])
+        return cipher.encrypt(data)
+
+    @staticmethod
+    def _random_nonce() -> str:
+        return "".join(random.choices("abcdefghijklmnopqrstuvwxyz0123456789", k=16))

agentic_rag/entrypoints/rest/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/entrypoints/rest/app.py

@@ -0,0 +1,170 @@
+"""FastAPI application — the main REST entry point."""
+
+import time
+import uuid
+from pathlib import Path
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from agentic_rag.config.settings import get_settings
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan — startup and shutdown."""
+    settings = get_settings()
+    print(f"[{settings.app_name}] Starting on {settings.api.host}:{settings.api.port}")
+
+    # Initialize database
+    try:
+        from agentic_rag.data.db import init_db
+        init_db(settings.db_path)
+        print(f"[{settings.app_name}] Database ready ({settings.db_path})")
+    except Exception as e:
+        print(f"[{settings.app_name}] ⚠ Database unavailable: {e}")
+
+    # Connect MCP servers FIRST (before gRPC/Milvus to avoid fork conflicts)
+    mcp_servers = settings.mcp_servers
+    if mcp_servers:
+        from agentic_rag.core.mcp.client import MCPClient
+        from agentic_rag.orchestration.l1_tools.registry import get_tool_registry
+        mcp_client = MCPClient()
+        registry = get_tool_registry()
+        for name, config in mcp_servers.items():
+            try:
+                cmd = config.get("command", "")
+                args_raw = config.get("args", "")
+                # args can be a JSON array or space-separated string
+                if isinstance(args_raw, list):
+                    arg_list = args_raw
+                else:
+                    arg_list = args_raw.split() if args_raw else []
+                # Merge MCP env with current process env (needs PATH etc.)
+                import os as _os
+                env = dict(_os.environ)
+                nested_env = config.get("env", {})
+                if isinstance(nested_env, dict):
+                    env.update({str(k).upper(): str(v) for k, v in nested_env.items() if v})
+                tools = await mcp_client.connect_stdio(
+                    server_name=name, command=cmd,
+                    args=arg_list, env=env if env else None,
+                )
+                for tool in tools:
+                    registry.register_mcp(tool, name)
+                print(f"[{settings.app_name}] MCP/{name} connected — {len(tools)} tools "
+                      f"({cmd} {' '.join(arg_list[:2])}...)")
+            except Exception as e:
+                print(f"[{settings.app_name}] ⚠ MCP/{name} failed: {e}")
+
+    # Initialize knowledge pipeline AFTER MCP (avoids gRPC fork conflicts)
+    try:
+        from agentic_rag.services.knowledge.pipeline import init_knowledge_pipeline
+        init_knowledge_pipeline()
+        print(f"[{settings.app_name}] Knowledge pipeline ready  "
+              f"(embedding={settings.embedding.model}, dim={settings.embedding.dim})")
+    except Exception as e:
+        print(f"[{settings.app_name}] ⚠ Knowledge pipeline unavailable: {e}")
+
+    # Start QQ Bot (WebSocket client — not a webhook)
+    if settings.gateway.qqbot.enabled:
+        from agentic_rag.entrypoints.gateway.qqbot import start_qqbot
+        await start_qqbot()
+
+    yield
+
+    # Shutdown: stop QQ Bot
+    if settings.gateway.qqbot.enabled:
+        from agentic_rag.entrypoints.gateway.qqbot import stop_qqbot
+        await stop_qqbot()
+
+    try:
+        from agentic_rag.data.db import _db
+        if _db:
+            _db.close()
+    except Exception:
+        pass
+    print(f"[{settings.app_name}] Shutting down")
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    settings = get_settings()
+
+    app = FastAPI(
+        title=settings.app_name,
+        version="0.1.0",
+        description="Agentic RAG — Multi-modal, ReAct-powered, MCP-enabled RAG System",
+        lifespan=lifespan,
+    )
+
+    # CORS
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.api.cors_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Request ID middleware
+    @app.middleware("http")
+    async def add_request_id(request: Request, call_next):
+        request_id = request.headers.get("X-Request-ID", uuid.uuid4().hex[:12])
+        request.state.request_id = request_id
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request_id
+        return response
+
+    # Register routes
+    from agentic_rag.entrypoints.rest.routes import chat, health, mcp, rag, session, settings
+    app.include_router(health.router, tags=["Health"])
+    app.include_router(chat.router, prefix="/api/v1", tags=["Chat"])
+    app.include_router(rag.router, prefix="/api/v1", tags=["RAG"])
+    app.include_router(session.router, prefix="/api/v1", tags=["Session"])
+    app.include_router(mcp.router, prefix="/api/v1", tags=["MCP"])
+    app.include_router(settings.router, prefix="/api/v1", tags=["Settings"])
+
+    # Gateway routes (messaging platform webhooks)
+    if get_settings().gateway.enabled:
+        from agentic_rag.entrypoints.gateway.router import get_gateway_router
+        gateway_router = get_gateway_router()
+        if gateway_router.routes:
+            app.include_router(gateway_router)
+
+    # WebSocket routes
+    try:
+        from agentic_rag.entrypoints.websocket.handler import router as ws_router
+        app.include_router(ws_router, tags=["WebSocket"])
+    except ImportError:
+        pass
+
+    # Static files & SPA fallback
+    static_dir = Path(__file__).resolve().parent.parent.parent.parent / "static"
+    if static_dir.exists():
+        app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+        @app.get("/", include_in_schema=False)
+        async def spa_root():
+            return FileResponse(str(static_dir / "index.html"))
+
+    # Global exception handler
+    @app.exception_handler(Exception)
+    async def global_exception_handler(request: Request, exc: Exception):
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": str(exc),
+                "type": type(exc).__name__,
+                "request_id": getattr(request.state, "request_id", "unknown"),
+                "timestamp": time.time(),
+            },
+        )
+
+    return app
+
+
+app = create_app()

agentic_rag/entrypoints/rest/routes/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG module."""

agentic_rag/entrypoints/rest/routes/chat.py

@@ -0,0 +1,447 @@
+"""Chat endpoints — the primary agent interaction interface."""
+
+import uuid
+from typing import Optional
+
+from fastapi import APIRouter, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+try:
+    from sse_starlette.sse import EventSourceResponse
+except ImportError:
+    EventSourceResponse = None
+
+from agentic_rag.data.models import AgentEvent, AgentInput
+from agentic_rag.services.llm.factory import get_llm
+from agentic_rag.orchestration.l1_tools.registry import get_tool_registry
+from agentic_rag.agent.router import AgentRouter
+
+router = APIRouter()
+
+
+class ChatRequest(BaseModel):
+    """Chat request body."""
+    message: str
+    session_id: Optional[str] = None
+    mode: Optional[str] = None  # "chat", "rag", "research", "media"
+    stream: bool = False
+    images: list[str] = Field(default_factory=list)  # image paths for vision
+
+
+class ChatResponse(BaseModel):
+    """Chat response body."""
+    answer: str
+    session_id: str
+    mode: str
+    tool_calls: list = Field(default_factory=list)
+
+
+def _build_input(query: str, images: list[str]) -> AgentInput:
+    """Build agent input — embeds images directly if LLM supports vision.
+
+    ``images`` can be:
+    - File paths (``/tmp/photo.jpg``) — read from disk and base64-encode
+    - Data URIs (``data:image/jpeg;base64,...``) — used as-is
+    """
+    from agentic_rag.data.models import AgentInput, Message, MessageRole
+    import base64
+    from pathlib import Path as _Path
+
+    if not images:
+        return AgentInput(query=query)
+
+    # Check if current LLM supports vision
+    try:
+        from agentic_rag.services.llm.factory import get_llm
+        llm = get_llm()
+    except Exception:
+        llm = None
+
+    if not getattr(llm, 'supports_vision', False):
+        return AgentInput(query=f"{query}\n\n[Attached: {len(images)} image(s)]")
+
+    # Vision LLM — embed images directly in multimodal message
+    content = [{"type": "text", "text": query}]
+    for img in images:
+        if img.startswith("data:"):
+            # Already a data URI — use directly
+            content.append({
+                "type": "image_url",
+                "image_url": {"url": img},
+            })
+        else:
+            # File path — read and encode
+            p = _Path(img)
+            if p.exists():
+                b64 = base64.b64encode(p.read_bytes()).decode()
+                ext = p.suffix.lower()
+                mime_map = {".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+                            ".png": "image/png", ".webp": "image/webp",
+                            ".gif": "image/gif", ".bmp": "image/bmp"}
+                mime = mime_map.get(ext, "image/png")
+                content.append({
+                    "type": "image_url",
+                    "image_url": {"url": f"data:{mime};base64,{b64}"},
+                })
+
+    msg = Message(role=MessageRole.USER, content=content)
+    return AgentInput(query=query, messages=[msg])
+
+
+@router.post("/chat", response_model=ChatResponse)
+async def chat(req: ChatRequest, request: Request):
+    """Send a message and get a response (non-streaming)."""
+    try:
+        llm = get_llm()
+    except ValueError as e:
+        raise HTTPException(status_code=503, detail=str(e))
+
+    sid = req.session_id or uuid.uuid4().hex
+    tool_registry = get_tool_registry()
+
+    # Initialize built-in tools if needed
+    _ensure_tools_registered(tool_registry)
+
+    router = AgentRouter(llm, tool_registry)
+    input_data = _build_input(req.message, req.images) if req.images else AgentInput(
+        query=req.message, parameters={"session_id": sid})
+    input_data.parameters["sid"] = sid
+
+    engine = await router.route(
+        query=input_data.query,
+        preferred_mode=req.mode,
+    )
+    output = await engine.run(input_data, turn_id=uuid.uuid4().hex)
+
+    return ChatResponse(
+        answer=output.final_answer,
+        session_id=sid,
+        mode=req.mode or "auto",
+        tool_calls=[tc.model_dump() for tc in output.tool_calls_made],
+    )
+
+
+@router.post("/chat/stream")
+async def chat_stream(req: ChatRequest, request: Request):
+    """Send a message and stream the response via SSE."""
+    try:
+        llm = get_llm()
+    except ValueError as e:
+        raise HTTPException(status_code=503, detail=str(e))
+
+    sid = req.session_id or uuid.uuid4().hex
+    tool_registry = get_tool_registry()
+    _ensure_tools_registered(tool_registry)
+
+    # Load conversation history from DB & save user message
+    from agentic_rag.data.models import Message as MsgModel, MessageRole
+    from agentic_rag.data.db.session_repo import SessionRepo
+    repo = SessionRepo()
+    history_messages = []
+    try:
+        session = repo.get(sid)
+        if not session:
+            # Session was deleted (e.g., user cleared messages) — re-create it
+            repo.create_with_id(sid, user_id="web_ui")
+            print(f"  [chat] Session {sid[:12]} re-created (was deleted)", flush=True)
+        else:
+            repo.add_message(sid, role="user", content=req.message)
+            print(f"  [chat] ✓ User message saved to session {sid[:12]}...", flush=True)
+            # Load conversation history; trim to stay within ~8000 chars (~5K tokens)
+            db_msgs = repo.get_messages(sid, limit=10)
+            if db_msgs and db_msgs[-1].get("role") == "user":
+                db_msgs = db_msgs[:-1]  # drop current query, passed separately
+
+            total_chars = 0
+            for m in reversed(db_msgs):  # newest first, accumulate until limit
+                role = m.get("role", "user")
+                content = m.get("content", "")
+                if role == "system":
+                    continue
+                if len(content) > 2000:
+                    content = content[:2000] + "..."
+                if total_chars + len(content) > 8000:
+                    break  # stop adding older messages
+                total_chars += len(content)
+                try:
+                    r = MessageRole(role)
+                except ValueError:
+                    r = MessageRole.USER
+                history_messages.insert(0, MsgModel(role=r, content=content))
+    except Exception as e:
+        print(f"  [chat] ⚠ History load failed: {e}", flush=True)
+
+    router = AgentRouter(llm, tool_registry)
+    input_data = _build_input(req.message, req.images) if req.images else AgentInput(
+        query=req.message, messages=history_messages, parameters={"session_id": sid})
+    input_data.parameters["sid"] = sid
+
+    engine = await router.route(
+        query=input_data.query,
+        preferred_mode=req.mode,
+    )
+
+    async def event_generator():
+        full_text_parts = []
+        final_answer = ""
+        in_think = False          # <think> tag state
+        _prefinal_buf = ""        # buffer for Thought/Action text before Final Answer
+        _line_freq: dict[str, int] = {}  # detect repetitive lines
+        _suppress_thought = False  # stop forwarding when thought loops
+        _done_emitted = False     # track if engine already emitted done
+
+        try:
+            async for event in engine.stream(input_data, turn_id=uuid.uuid4().hex):
+                payload = event.data if hasattr(event, 'data') else {}
+                if event.event_type.value == "done":
+                    final_answer = payload.get("final_answer", "")
+                    _done_emitted = True
+                elif event.event_type.value == "text_delta":
+                    chunk = payload.get("content", "") or payload.get("delta", "")
+                    if chunk:
+                        # Strip <think>...</think> tags
+                        cleaned = chunk
+                        while "<think>" in cleaned or "</think>" in cleaned or in_think:
+                            if in_think:
+                                end = cleaned.find("</think>")
+                                if end >= 0:
+                                    cleaned = cleaned[end + 8:]
+                                    in_think = False
+                                else:
+                                    cleaned = ""
+                                    break
+                            else:
+                                start = cleaned.find("<think>")
+                                if start >= 0:
+                                    in_think = True
+                                    cleaned = cleaned[:start]
+                                else:
+                                    break
+                        if not cleaned:
+                            continue
+
+                        # Detect "Final Answer:" — flush only answer from here on
+                        if "Final Answer:" in _prefinal_buf + cleaned:
+                            idx = (_prefinal_buf + cleaned).find("Final Answer:") + len("Final Answer:")
+                            combined = _prefinal_buf + cleaned
+                            after = combined[idx:].strip()
+                            _prefinal_buf = ""
+                            if after:
+                                full_text_parts.append(after)
+                                payload["content"] = after
+                                yield {
+                                    "event": "text_delta",
+                                    "data": event.model_dump_json() if hasattr(event, 'model_dump_json') else "{}",
+                                }
+                            continue  # skip bottom yield — already emitted Final Answer
+
+                        # Still in Thought phase — detect repetitive looping
+                        if not _suppress_thought:
+                            _prefinal_buf += cleaned
+
+                            # Check for repetition: same meaningful line appearing 3+ times
+                            lines = _prefinal_buf.split("\n")
+                            for line in lines[-3:]:  # check recent lines only
+                                norm = line.strip().lower().rstrip(".。!！?？,，")
+                                if len(norm) > 12:
+                                    _line_freq[norm] = _line_freq.get(norm, 0) + 1
+                                    if _line_freq[norm] >= 3:
+                                        _suppress_thought = True
+                                        break
+
+                            if not _suppress_thought:
+                                # Also suppress if thought is >2000 chars — clearly looping
+                                if len(_prefinal_buf) > 2000:
+                                    _suppress_thought = True
+
+                            if not _suppress_thought:
+                                full_text_parts.append(cleaned)
+                                payload["content"] = cleaned
+                            else:
+                                continue  # skip yield — suppressing verbose thought
+                elif event.event_type.value == "error":
+                    pass
+                yield {
+                    "event": event.event_type.value,
+                    "data": event.model_dump_json() if hasattr(event, 'model_dump_json') else "{}",
+                }
+        except Exception as e:
+            import sys
+            print(f"  [chat] ⚠ Event generator crashed: {e}", flush=True)
+            sys.stdout.flush()
+            yield {
+                "event": "error",
+                "data": f'{{"error": "Stream crashed: {e}"}}',
+            }
+
+        # Use final_answer (already clean) if available, else concatenated deltas
+        response_text = final_answer.strip() or "".join(full_text_parts).strip()
+        if response_text:
+            import sys
+            print(f"  [chat] Saving assistant message ({len(response_text)} chars) to session {sid[:12]}...", flush=True)
+            try:
+                repo.add_message(sid, role="assistant", content=response_text)
+                print(f"  [chat] ✓ Assistant message saved", flush=True)
+            except Exception as e:
+                print(f"  [chat] ⚠ Failed to save assistant message: {e}", flush=True)
+        else:
+            print(f"  [chat] ⚠ No assistant text collected (final_answer={bool(final_answer)}, deltas={len(full_text_parts)})", flush=True)
+
+        # Only emit done if engine didn't already emit one
+        if not _done_emitted:
+            yield {"event": "done", "data": "{}"}
+
+    if EventSourceResponse is None:
+        raise HTTPException(status_code=501, detail="SSE streaming not available. Install sse-starlette.")
+    return EventSourceResponse(event_generator())
+
+
+class VoiceRequest(BaseModel):
+    """Voice chat request — audio in, audio out (base64, kept for WS compat)."""
+    audio: str = ""
+    sid: str = ""
+    mode: str = ""
+    tts: bool = True
+
+
+@router.post("/chat/voice")
+async def chat_voice(
+    audio: UploadFile | None = File(None),
+    sid: str = Form(""),
+    mode: str = Form(""),
+    tts: bool = Form(True),
+):
+    """Voice chat with SSE streaming: audio → STT → Agent stream → TTS.
+
+    SSE events: transcript | text_delta | tool_* | audio | done
+    """
+    import base64, sys, json as _json
+
+    if audio is None:
+        raise HTTPException(status_code=400, detail="No audio file provided")
+    audio_bytes = await audio.read()
+    if not audio_bytes:
+        raise HTTPException(status_code=400, detail="Empty audio file")
+
+    from agentic_rag.config.settings import get_settings
+    vs = get_settings().voice
+    from agentic_rag.core.voice.stt import STTService
+    stt_svc = STTService(
+        provider=vs.stt_provider, model=vs.stt_model,
+        api_base=vs.stt_api_base, api_key=vs.stt_api_key,
+        language=vs.stt_language, sample_rate=vs.sample_rate,
+    )
+
+    def _sse(event: str, data: dict) -> dict:
+        return {"event": event, "data": _json.dumps(data, ensure_ascii=False)}
+
+    async def _generator():
+        # Step 1: STT — yield transcript immediately
+        transcript = await stt_svc.transcribe_bytes(audio_bytes)
+        if not transcript.strip():
+            yield _sse("error", {"error": "No speech detected"})
+            yield _sse("done", {})
+            return
+        print(f"  [Voice] STT: \"{transcript[:80]}...\"", flush=True)
+        yield _sse("transcript", {"text": transcript})
+
+        # Step 2: Agent — stream response
+        sid_val = sid or uuid.uuid4().hex
+        try:
+            llm = get_llm()
+        except ValueError as e:
+            yield _sse("error", {"error": str(e)})
+            yield _sse("done", {})
+            return
+
+        tool_registry = get_tool_registry()
+        _ensure_tools_registered(tool_registry)
+
+        from agentic_rag.data.db.session_repo import SessionRepo
+        repo = SessionRepo()
+        try:
+            if not repo.get(sid_val):
+                repo.add_message(sid_val, role="user", content=f"[Voice] {transcript}")
+        except Exception:
+            pass
+
+        agent_router = AgentRouter(llm, tool_registry)
+        input_data = AgentInput(query=transcript, parameters={"session_id": sid_val})
+        engine = await agent_router.route(query=transcript, preferred_mode=mode)
+
+        full_answer = ""
+        async for event in engine.stream(input_data, turn_id=uuid.uuid4().hex):
+            evt_type = event.event_type.value
+            payload = event.data if hasattr(event, 'data') else {}
+            if evt_type == "text_delta":
+                chunk = payload.get("content", "") or payload.get("delta", "")
+                if chunk:
+                    import re
+                    chunk = re.sub(r'<think>[\s\S]*?</think>', '', chunk)
+                    if chunk.strip():
+                        full_answer += chunk
+                        yield _sse("text_delta", {"content": chunk})
+            elif evt_type == "done":
+                ans = payload.get("final_answer", "")
+                if ans:
+                    full_answer = ans
+            elif evt_type in ("tool_call_start", "tool_call_result", "error"):
+                yield _sse(evt_type, payload)
+
+        print(f"  [Voice] Answer: \"{full_answer[:80]}...\"", flush=True)
+
+        # Save assistant message
+        if full_answer.strip():
+            try:
+                repo.add_message(sid_val, role="assistant", content=full_answer)
+            except Exception:
+                pass
+
+        # Step 3: TTS
+        if tts and full_answer.strip():
+            print("  [Voice] Synthesizing TTS...", flush=True)
+            from agentic_rag.core.voice.tts import TTSService
+            tts_svc = TTSService(
+                provider=vs.tts_provider, model=vs.tts_model,
+                api_base=vs.tts_api_base, api_key=vs.tts_api_key,
+                task_type=vs.tts_task_type, instructions=vs.tts_instructions,
+                language=vs.tts_language, speaker=vs.tts_speaker,
+                voice=vs.tts_voice, speed=vs.tts_speed,
+                response_format=vs.tts_response_format,
+            )
+            audio_out = await tts_svc.synthesize(full_answer)
+            if audio_out:
+                audio_b64 = base64.b64encode(audio_out).decode()
+                print(f"  [Voice] TTS: {len(audio_out)} bytes", flush=True)
+                yield _sse("audio", {"audio": audio_b64, "format": vs.tts_response_format})
+                yield _sse("done", {"final_answer": full_answer, "session_id": sid_val})
+                return
+        yield _sse("audio", {})
+        yield _sse("done", {"final_answer": full_answer, "session_id": sid_val})
+
+    if EventSourceResponse is None:
+        raise HTTPException(status_code=501, detail="SSE streaming not available. Install sse-starlette.")
+    return EventSourceResponse(_generator())
+
+
+
+
+def _ensure_tools_registered(registry):
+    """Register built-in tools (idempotent — skips already-registered names).
+
+    ``web_search`` is registered as a built-in fallback (DuckDuckGo) even
+    though web search is primarily expected via MCP: prompt rule 2 tells the
+    model to use 网络搜索 when rag_search comes up empty, and without a
+    tool literally named ``web_search`` the model emits an Action for a
+    non-existent tool and the turn stalls.
+    """
+    from agentic_rag.orchestration.l1_tools.rag_tools import RAGSearchTool
+    from agentic_rag.orchestration.l1_tools.web_tools import WebSearchTool
+    _register_if_missing(registry, RAGSearchTool())
+    _register_if_missing(registry, WebSearchTool())
+
+
+def _register_if_missing(registry, tool):
+    """Register a tool only if its name isn't already taken."""
+    if tool.name not in registry.list_names():
+        registry.register(tool)

agentic_rag/entrypoints/rest/routes/health.py

@@ -0,0 +1,23 @@
+"""Health check endpoints."""
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/health")
+async def health_check():
+    """Basic health check."""
+    return {"status": "ok", "service": "agentic_rag"}
+
+
+@router.get("/ready")
+async def readiness_check():
+    """Readiness check — verifies LLM connectivity."""
+    from agentic_rag.services.llm.factory import get_llm
+    try:
+        llm = get_llm()
+        provider_info = {"provider": llm.provider_name, "model": llm.model_name}
+        return {"status": "ready", "llm": provider_info}
+    except Exception as e:
+        return {"status": "not_ready", "error": str(e)}

agentic_rag/entrypoints/rest/routes/mcp.py

@@ -0,0 +1,73 @@
+"""MCP server configuration management endpoints."""
+
+import json
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+router = APIRouter()
+
+MCP_CONFIG_PATH = Path("mcp_servers.json")
+
+
+def _read_config() -> dict:
+    """Read current MCP config from JSON file."""
+    if MCP_CONFIG_PATH.exists():
+        try:
+            return json.loads(MCP_CONFIG_PATH.read_text())
+        except json.JSONDecodeError:
+            pass
+    return {"mcpServers": {}}
+
+
+def _write_config(data: dict) -> None:
+    """Write MCP config to JSON file."""
+    MCP_CONFIG_PATH.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+class MCPServerEntry(BaseModel):
+    """A single MCP server config entry."""
+    command: str = ""
+    args: list[str] = []
+    env: dict[str, str] = {}
+    disabled: bool = False
+
+
+class MCPServersUpdate(BaseModel):
+    """Full MCP servers config update."""
+    servers: dict[str, MCPServerEntry]
+
+
+@router.get("/mcp/servers")
+async def get_mcp_servers():
+    """Return the current MCP server configuration."""
+    config = _read_config()
+    return {"servers": config.get("mcpServers", {})}
+
+
+@router.put("/mcp/servers")
+async def update_mcp_servers(data: MCPServersUpdate):
+    """Replace the entire MCP server configuration and write to disk."""
+    config = {"mcpServers": {}}
+    for name, entry in data.servers.items():
+        config["mcpServers"][name] = {
+            "command": entry.command,
+            "args": entry.args if isinstance(entry.args, list) else entry.args.split(),
+            "env": entry.env or {},
+            "disabled": entry.disabled,
+        }
+    _write_config(config)
+    return {"status": "saved", "servers": len(config["mcpServers"])}
+
+
+@router.delete("/mcp/servers/{name}")
+async def delete_mcp_server(name: str):
+    """Delete a single MCP server from the config."""
+    config = _read_config()
+    servers = config.get("mcpServers", {})
+    if name not in servers:
+        raise HTTPException(status_code=404, detail=f"MCP server '{name}' not found")
+    del servers[name]
+    _write_config(config)
+    return {"status": "deleted", "name": name}

agentic_rag/entrypoints/rest/routes/rag.py

@@ -0,0 +1,558 @@
+"""RAG endpoints — knowledge base query, ingestion, and file upload."""
+
+import os
+import uuid
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+def _parse_doc_id(result: str) -> str:
+    """Extract the UUID document ID from an ingestion result message.
+
+    The RAGIngestTool returns a multi-line string like::
+
+        Content ingested successfully.
+        Document ID: abc123-def456-...
+        Source: upload
+
+    We only want the UUID, not the trailing "Source: ..." text.
+    """
+    if "ID:" in result:
+        # Grab the line containing "ID:" and extract the UUID
+        for line in result.split("\n"):
+            if "ID:" in line:
+                return line.split("ID:")[-1].strip()
+    return "unknown"
+
+
+@router.get("/rag/stats")
+async def rag_stats():
+    """Return knowledge base statistics."""
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+    pipe = get_knowledge_pipeline()
+    vs_stats = {}
+    if pipe.vector_store and hasattr(pipe.vector_store, 'stats'):
+        try:
+            vs_stats = pipe.vector_store.stats()
+        except Exception:
+            pass
+
+    # Count from Milvus (persistent) + pipeline (in-memory)
+    chunk_count = 0
+    doc_count = len(pipe._documents)
+    try:
+        from pymilvus import MilvusClient
+        from agentic_rag.config.settings import get_settings
+        ws = get_settings().workspace_dir
+        mc = MilvusClient(f"{ws}/milvus_lite.db")
+        if "knowledge" in (mc.list_collections() or []):
+            mc.load_collection("knowledge")
+            # Count chunks
+            res = mc.query("knowledge", filter="id != ''", output_fields=["id", "source"])
+            chunk_count = len(res) if res else 0
+            # Count distinct documents (by source field)
+            if res:
+                sources = set(r.get("source", "") for r in res if r.get("source"))
+                doc_count = max(doc_count, len(sources))
+    except Exception:
+        pass
+
+    kg_stats = pipe.graph.stats() if pipe.graph else {}
+    return {
+        "chunks": chunk_count,
+        "documents": doc_count,
+        "graph": kg_stats,
+        "vector_store": vs_stats,
+    }
+
+
+@router.get("/rag/documents")
+async def rag_documents():
+    """List all indexed documents with metadata (server-side, browser-agnostic)."""
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+    pipe = get_knowledge_pipeline()
+    return {"documents": pipe.list_files()}
+
+
+@router.get("/rag/graph")
+async def rag_graph():
+    """Return the full knowledge graph (entities + relations) for visualization."""
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+    pipe = get_knowledge_pipeline()
+
+    if not pipe.graph:
+        return {"entities": [], "relations": [], "stats": {"entities": 0, "relations": 0}}
+
+    graph_dict = pipe.graph.to_dict()
+    return {
+        "entities": [
+            {
+                "id": eid,
+                "name": ent["name"][:80],
+                "type": ent["type"],
+                "content_type": ent.get("content_type", ""),
+                "text_preview": ent.get("content_text", "")[:120],
+            }
+            for eid, ent in graph_dict.get("entities", {}).items()
+        ],
+        "relations": [
+            {
+                "source": r["source"][:12],
+                "target": r["target"][:12],
+                "type": r["type"],
+                "weight": round(r.get("weight", 1.0), 2),
+            }
+            for r in graph_dict.get("relations", [])
+        ],
+        "stats": pipe.graph.stats(),
+    }
+
+
+class RAGSearchRequest(BaseModel):
+    """Raw RAG search request — no LLM generation."""
+    query: str
+    top_k: int = 10
+    mode: str = "hybrid"
+    modality_filter: list[str] = None
+
+
+class RAGQueryRequest(BaseModel):
+    """RAG query request."""
+    query: str
+    top_k: int = 5
+    include_raw_docs: bool = False
+
+
+class RAGQueryResponse(BaseModel):
+    """RAG query response."""
+    answer: str
+    sources: list[dict] = []
+
+
+class RAGIngestRequest(BaseModel):
+    """Document ingestion request."""
+    content: str
+    source: str = "api"
+    metadata: dict = {}
+
+
+class RAGIngestResponse(BaseModel):
+    """Document ingestion response."""
+    doc_id: str
+    status: str
+
+
+@router.post("/rag/search")
+async def rag_search(req: RAGSearchRequest):
+    """Search the knowledge base — returns raw chunks, no LLM generation."""
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+    from agentic_rag.services.knowledge.content_list import ContentType
+    pipe = get_knowledge_pipeline()
+    # Parse modality filter
+    mf = None
+    if req.modality_filter:
+        mf = [ContentType(t) for t in req.modality_filter if t in ContentType.__members__.values()]
+        mf = mf or None
+    results = await pipe.retrieve(query=req.query, top_k=req.top_k, mode=req.mode, modality_filter=mf)
+    # Resolve doc_id → display name
+    doc_names = {}
+    for r in results:
+        meta = r.content_item.metadata or {}
+        did = meta.get("source", "")  # Milvus "source" field = doc_id
+        if did and did not in doc_names and len(did) > 20:
+            cl = pipe._documents.get(did)
+            raw = cl.source if cl else did[:12]
+            # Show filename only, not full path
+            doc_names[did] = raw.split("/")[-1] if "/" in raw else raw
+
+    # Filter out very low-score results (embedding noise)
+    MIN_SCORE = 0.25
+    filtered = [r for r in results if r.score >= MIN_SCORE]
+    if not filtered:
+        filtered = results[:3]  # always return at least top 3
+
+    return {
+        "query": req.query,
+        "results": [
+            {
+                "content": r.content_item.to_searchable_text() or r.content_item.text or "",
+                "content_type": r.content_item.type.value,
+                "score": r.score,
+                "source": r.source,
+                "document": doc_names.get(r.content_item.metadata.get("source", ""), ""),
+                "image_path": r.content_item.img_path or "",
+                "video_path": r.content_item.video_path or "",
+                "audio_path": r.content_item.audio_path or "",
+                "table_body": r.content_item.table_body or "",
+                "page_idx": r.content_item.page_idx,
+            }
+            for r in filtered
+        ],
+    }
+
+
+@router.post("/rag/query", response_model=RAGQueryResponse)
+async def rag_query(req: RAGQueryRequest):
+    """Query the knowledge base with RAG."""
+    from agentic_rag.orchestration.l1_tools.rag_tools import RAGSearchTool
+    from agentic_rag.services.llm.factory import get_llm
+    from agentic_rag.data.models import Message
+
+    llm = get_llm()
+    tool = RAGSearchTool()
+    results = await tool.execute(query=req.query, top_k=req.top_k)
+
+    # Generate answer from retrieved context
+    messages = [
+        Message.system("Answer the user's question using the provided context. Cite sources when possible."),
+        Message.user(f"Context:\n{results}\n\nQuestion: {req.query}"),
+    ]
+    response = await llm.agenerate(messages)
+
+    return RAGQueryResponse(
+        answer=response.content,
+        sources=[{"content": results}],
+    )
+
+
+@router.get("/rag/file/{file_path:path}")
+async def serve_kb_file(file_path: str):
+    """Serve a file from the knowledge base (for image/video preview)."""
+    from pathlib import Path as _Path
+    from fastapi.responses import FileResponse
+    p = _Path(file_path)
+    if not p.is_absolute():
+        p = _Path.cwd() / file_path
+    if not p.exists():
+        raise HTTPException(status_code=404, detail=f"File not found: {file_path}")
+    return FileResponse(str(p))
+
+
+@router.get("/rag/document/{doc_id}")
+async def get_document(doc_id: str):
+    """Get the content of an indexed document for preview."""
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+    pipe = get_knowledge_pipeline()
+
+    # Try in-memory first
+    cl = pipe._documents.get(doc_id)
+    if cl:
+        items = []
+        for item in cl.items:
+            items.append({
+                "text": item.to_searchable_text() or item.text or "",
+                "type": item.type.value,
+                "page_idx": item.page_idx,
+                "image_path": item.img_path or "",
+                "video_path": item.video_path or "",
+                "audio_path": item.audio_path or "",
+                "table_body": item.table_body or "",
+            })
+        return {"doc_id": doc_id, "source": cl.source, "items": items}
+
+    # Fallback: query Milvus by source (works after server restart)
+    items = []
+    try:
+        from agentic_rag.config.settings import get_settings
+        from pymilvus import MilvusClient
+        ws = get_settings().workspace_dir
+        mc = MilvusClient(f"{ws}/milvus_lite.db")
+        if "knowledge" in (mc.list_collections() or []):
+            mc.load_collection("knowledge")
+            res = mc.query("knowledge", filter=f'source == "{doc_id}"', output_fields=["text", "content_type", "image_path", "video_path", "audio_path", "table_body"], limit=100)
+            for r in res:
+                items.append({
+                    "text": r.get("text", ""),
+                    "type": r.get("content_type", "text"),
+                    "image_path": r.get("image_path", ""),
+                    "video_path": r.get("video_path", ""),
+                    "audio_path": r.get("audio_path", ""),
+                    "table_body": r.get("table_body", ""),
+                })
+    except Exception as e:
+        print(f"  [rag] document query error: {e}", flush=True)
+
+    if not items:
+        raise HTTPException(status_code=404, detail=f"Document {doc_id} not found")
+    return {"doc_id": doc_id, "items": items}
+
+
+@router.delete("/rag/document/{doc_id}")
+async def delete_document(doc_id: str):
+    """Delete an indexed document and all its chunks from the knowledge base."""
+    deleted_chunks = 0
+    try:
+        from agentic_rag.config.settings import get_settings
+        from pymilvus import MilvusClient
+        ws = get_settings().workspace_dir
+        mc = MilvusClient(f"{ws}/milvus_lite.db")
+        if "knowledge" in (mc.list_collections() or []):
+            mc.load_collection("knowledge")
+            res = mc.query("knowledge", filter=f'source == "{doc_id}"', output_fields=["id"], limit=1000)
+            ids = [r["id"] for r in res]
+            if ids:
+                mc.delete("knowledge", ids=ids)
+                deleted_chunks = len(ids)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Deletion failed: {e}")
+
+    # Also remove from in-memory pipeline
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+    pipe = get_knowledge_pipeline()
+    pipe._documents.pop(doc_id, None)
+
+    return {"doc_id": doc_id, "deleted_chunks": deleted_chunks, "status": "deleted"}
+
+
+@router.post("/rag/clear")
+async def clear_knowledge_base():
+    """Clear ALL documents and chunks from the knowledge base."""
+    from agentic_rag.config.settings import get_settings
+    from pymilvus import MilvusClient
+    ws = get_settings().workspace_dir
+    mc = MilvusClient(f"{ws}/milvus_lite.db")
+    if "knowledge" in (mc.list_collections() or []):
+        mc.drop_collection("knowledge")
+    from pymilvus import DataType
+    dim = get_settings().embedding.dim
+    schema = mc.create_schema(enable_dynamic_field=True)
+    schema.add_field("id", DataType.VARCHAR, max_length=64, is_primary=True)
+    schema.add_field("vector", DataType.FLOAT_VECTOR, dim=dim)
+    mc.create_collection("knowledge", schema=schema, dimension=dim)
+    mc.load_collection("knowledge")
+
+    # Clear in-memory state
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+    from agentic_rag.services.knowledge.graph.index import KnowledgeGraph
+    pipe = get_knowledge_pipeline()
+    pipe._documents.clear()
+    pipe._content_cache.clear()
+    pipe._file_registry.clear()
+    # Reset knowledge graph
+    pipe.graph = KnowledgeGraph()
+    # Delete persisted graph file
+    import os
+    gpath = pipe._graph_path
+    if os.path.exists(gpath):
+        os.remove(gpath)
+
+    return {"status": "cleared", "message": "All knowledge base data has been removed."}
+
+
+@router.post("/rag/ingest", response_model=RAGIngestResponse)
+async def rag_ingest(req: RAGIngestRequest):
+    """Ingest a document into the knowledge base."""
+    from agentic_rag.orchestration.l1_tools.rag_tools import RAGIngestTool
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+
+    tool = RAGIngestTool()
+    result = await tool.execute(content=req.content, source=req.source)
+
+    doc_id = _parse_doc_id(result)
+    # Register for cross-browser document listing
+    pipe = get_knowledge_pipeline()
+    pipe.register_file(doc_id, req.source or "text_ingest", len(req.content), "text")
+
+    return RAGIngestResponse(
+        doc_id=doc_id,
+        status="success",
+    )
+
+
+# ── File Upload ─────────────────────────────────────────────────
+
+MIME_TO_CATEGORY = {
+    # Text / documents
+    "text/plain": "text",
+    "text/markdown": "text",
+    "text/csv": "text",
+    "text/html": "text",
+    "application/json": "text",
+    "application/pdf": "text",
+    "application/x-yaml": "text",
+    # Images
+    "image/jpeg": "image",
+    "image/png": "image",
+    "image/gif": "image",
+    "image/webp": "image",
+    "image/bmp": "image",
+    "image/svg+xml": "image",
+    # Video
+    "video/mp4": "video",
+    "video/avi": "video",
+    "video/quicktime": "video",
+    "video/x-matroska": "video",
+    "video/webm": "video",
+    # Audio
+    "audio/mpeg": "audio",
+    "audio/wav": "audio",
+    "audio/mp4": "audio",
+    "audio/ogg": "audio",
+    "audio/flac": "audio",
+    "audio/x-m4a": "audio",
+}
+
+EXT_TO_CATEGORY = {
+    ".txt": "text", ".md": "text", ".markdown": "text",
+    ".json": "text", ".yaml": "text", ".yml": "text",
+    ".csv": "text", ".py": "text", ".html": "text",
+    ".pdf": "text", ".docx": "text", ".doc": "text",
+    ".jpg": "image", ".jpeg": "image", ".png": "image",
+    ".gif": "image", ".webp": "image", ".bmp": "image", ".svg": "image",
+    ".mp4": "video", ".avi": "video", ".mov": "video",
+    ".mkv": "video", ".webm": "video",
+    ".mp3": "audio", ".wav": "audio", ".m4a": "audio",
+    ".ogg": "audio", ".flac": "audio",
+}
+
+
+@router.post("/rag/upload")
+async def rag_upload(
+    file: UploadFile = File(...),
+    source: str = Form("web_ui"),
+    ingest_mode: str = Form("multimodal"),
+    mm_method: str = Form("pure"),
+    chunk_size: int = Form(512),
+    chunk_overlap: int = Form(50),
+    enable_kg: bool = Form(False),
+):
+    """Upload a file for ingestion into the knowledge base.
+
+    Supports text files (.txt, .md, .pdf, .json, .yaml, .csv),
+    images (.jpg, .png, .gif, .webp), video (.mp4, .avi, .mov),
+    and audio (.mp3, .wav, .m4a).
+    """
+    import sys
+    print(f"  [Upload] received: {file.filename} ({file.content_type}), source={source}, "
+          f"chunk={chunk_size}/{chunk_overlap}, kg={enable_kg}", flush=True)
+
+    # Detect content category
+    mime = file.content_type or ""
+    ext = Path(file.filename or "").suffix.lower()
+
+    category = MIME_TO_CATEGORY.get(mime) or EXT_TO_CATEGORY.get(ext)
+    if category is None:
+        # Fallback: try to read as text
+        category = "text"
+
+    # Save file to workspace temp directory
+    from agentic_rag.config.settings import get_settings
+    settings = get_settings()
+    workspace = Path(settings.workspace_dir) / "uploads"
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    safe_name = f"{uuid.uuid4().hex}_{file.filename or 'upload'}"
+    file_path = workspace / safe_name
+
+    try:
+        content_bytes = await file.read()
+        file_path.write_bytes(content_bytes)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to save file: {e}")
+
+    file_size = len(content_bytes)
+
+    # Ingest based on category
+    from agentic_rag.orchestration.l1_tools.rag_tools import RAGIngestTool, RAGMultiModalIngestTool
+    from agentic_rag.services.knowledge.pipeline import get_knowledge_pipeline
+
+    try:
+        # Apply per-request pipeline settings
+        pipeline = get_knowledge_pipeline()
+        # Ensure bool conversion (FastAPI Form may deliver "true"/"false" strings)
+        kg_enabled = enable_kg if isinstance(enable_kg, bool) else str(enable_kg).lower() in ("true", "1", "yes", "on")
+        pipeline.ingest_mode = ingest_mode
+        pipeline.mm_method = mm_method
+        pipeline.enable_kg = kg_enabled
+        pipeline.extract_entities = kg_enabled  # semantic extraction follows KG toggle
+        pipeline.chunk_size = int(chunk_size)
+        pipeline.chunk_overlap = int(chunk_overlap)
+        # Ensure LLM function is available for semantic extraction
+        if pipeline.extract_entities and pipeline.llm_func is None:
+            from agentic_rag.services.knowledge.pipeline import _create_kg_llm_func
+            pipeline.llm_func = _create_kg_llm_func()
+        # Reset processors so chunk settings take effect
+        pipeline._processors = {}
+
+        print(f"  [Upload] pipeline config: mode={ingest_mode}/{mm_method}, "
+              f"chunk={pipeline.chunk_size}/{pipeline.chunk_overlap}, "
+              f"kg={pipeline.enable_kg}, extract_entities={pipeline.extract_entities}, "
+              f"llm={'OK' if pipeline.llm_func else 'MISSING'}", flush=True)
+
+        if category == "text":
+            # PDF / docx / office files → parse via pipeline (supports docling + fallback)
+            if ext in (".pdf", ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls"):
+                print(f"  [Upload] parsing document via pipeline: {ext}", flush=True)
+                doc_id = await pipeline.ingest(source=str(file_path), source_type=ext.lstrip("."))
+                # Override stored source with original filename for display
+                cl = pipeline._documents.get(doc_id)
+                if cl:
+                    cl.source = file.filename or str(file_path)
+                result = f"Content ingested successfully.\nDocument ID: {doc_id}\nSource: {source}"
+            else:
+                # Plain text files — pass pipeline explicitly so KG settings take effect
+                try:
+                    text_content = content_bytes.decode("utf-8")
+                except UnicodeDecodeError:
+                    text_content = content_bytes.decode("latin-1", errors="replace")
+
+                print(f"  [Upload] text content: {len(text_content)} chars, "
+                      f"first 80: {text_content[:80].replace(chr(10),' ')}", flush=True)
+
+                tool = RAGIngestTool(pipeline=pipeline)
+                result = await tool.execute(
+                    content=text_content,
+                    source=source or file.filename or "upload",
+                    content_type="text",
+                )
+            print(f"  [Upload] result: {str(result)[:120]}", flush=True)
+            print(f"  [Upload] KG after ingest: entities={pipeline.graph.entity_count if pipeline.graph else 0}", flush=True)
+
+        elif category == "image":
+            tool = RAGMultiModalIngestTool(pipeline=pipeline)
+            result = await tool.execute(
+                images=[str(file_path)],
+                source=source or file.filename or "upload",
+            )
+
+        elif category == "video":
+            tool = RAGMultiModalIngestTool(pipeline=pipeline)
+            result = await tool.execute(
+                videos=[str(file_path)],
+                source=source or file.filename or "upload",
+            )
+
+        elif category == "audio":
+            tool = RAGMultiModalIngestTool(pipeline=pipeline)
+            result = await tool.execute(
+                audio_files=[str(file_path)],
+                source=source or file.filename or "upload",
+            )
+        else:
+            raise HTTPException(status_code=400, detail=f"Unsupported file category: {category}")
+
+        doc_id = _parse_doc_id(str(result))
+
+        # Register file metadata for cross-browser document listing
+        pipeline.register_file(doc_id, file.filename or "unknown", file_size, category)
+
+        return {
+            "doc_id": doc_id,
+            "filename": file.filename,
+            "content_type": category,
+            "size": file_size,
+            "status": "success",
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        # Cleanup temp file on failure
+        if file_path.exists():
+            file_path.unlink()
+        raise HTTPException(status_code=500, detail=f"Ingestion failed: {e}")

agentic_rag/entrypoints/rest/routes/session.py

@@ -0,0 +1,82 @@
+"""Session management endpoints — backed by SQLite via SessionRepo."""
+
+from fastapi import APIRouter, HTTPException
+
+from agentic_rag.data.db.session_repo import SessionRepo
+
+router = APIRouter()
+
+
+def _repo() -> SessionRepo:
+    return SessionRepo()
+
+
+@router.post("/session")
+async def create_session(user_id: str = "default"):
+    """Create a new session."""
+    session = _repo().create(user_id=user_id)
+    return {"session_id": session["id"], "user_id": session["user_id"]}
+
+
+@router.get("/session/{session_id}")
+async def get_session(session_id: str):
+    """Get session details."""
+    session = _repo().get(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return session
+
+
+@router.put("/session/{session_id}")
+async def update_session(session_id: str, title: str = None):
+    """Update session metadata (e.g., title)."""
+    fields = {}
+    if title is not None:
+        fields["title"] = title
+    if not fields:
+        raise HTTPException(status_code=400, detail="No fields to update")
+    ok = _repo().update(session_id, **fields)
+    if not ok:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return {"status": "updated"}
+
+
+@router.get("/sessions")
+async def list_sessions(user_id: str = "default"):
+    """List sessions for a user."""
+    return {"sessions": _repo().list(user_id=user_id)}
+
+
+@router.delete("/sessions")
+async def delete_all_sessions(user_id: str = "default"):
+    """Delete ALL sessions and messages for a user."""
+    count = _repo().delete_all(user_id=user_id)
+    return {"status": "deleted", "count": count}
+
+
+@router.delete("/session/{session_id}/messages")
+async def clear_session_messages(session_id: str):
+    """Clear all messages in a session (keep the session itself)."""
+    session = _repo().get(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    count = _repo().clear_messages(session_id)
+    return {"status": "cleared", "count": count}
+
+
+@router.delete("/session/{session_id}")
+async def delete_session(session_id: str):
+    """Delete a session and its messages."""
+    ok = _repo().delete(session_id)
+    if not ok:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return {"status": "deleted"}
+
+
+@router.get("/session/{session_id}/messages")
+async def get_messages(session_id: str):
+    """Get all messages for a session."""
+    session = _repo().get(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return {"messages": _repo().get_messages(session_id)}