nbrag 0.2.0__tar.gz

nbrag-0.2.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# RAG data (user-generated, not tracked)
+rag_db/
+*.sqlite3
+
+# Test data
+tests/test_data/
+
+# Auto-generated docs (by nb_ai_context)
+*_all_docs_and_codes.md
+
+# Distribution
+*.tar.gz

nbrag-0.2.0/AGENTS.md

@@ -0,0 +1,130 @@
+# nbrag — AI Agent 指令
+
+## 项目概览
+
+Agentic RAG MCP Server。Python 3.11+，FastMCP，ChromaDB，SiliconFlow Embedding/Rerank。
+
+架构：4 个核心模块，扁平包布局（无 `src/` 目录）。
+
+| 模块 | 职责 |
+|------|------|
+| `nbrag/server.py` | 12 个 MCP 工具，CLI 入口 (`main()`) |
+| `nbrag/core.py` | Embedding/Rerank API 调用，ChromaDB CRUD，文件导入 |
+| `nbrag/chunker.py` | 文本切分，行号计算，Python AST 作用域解析 |
+| `nbrag/config.py` | 配置加载：CLI > 环境变量 > YAML > 默认值 |
+
+## 构建与测试
+
+```bash
+# 开发模式安装
+pip install -e ".[dev]"
+
+# 启动 MCP 服务（stdio 模式）
+python -m nbrag
+
+# 启动 MCP 服务（HTTP 模式）
+python -m nbrag --transport streamable-http --port 9101
+
+# 类型检查
+mypy nbrag/
+
+# 运行测试
+python -m pytest tests/ -x -v
+```
+
+## 代码规范
+
+### 必须
+
+- 数据导入函数使用 `ingest_` 前缀（不用 `import_`，避免与 Python 关键字混淆）。
+- `core.py` 所有公开函数必须有文档字符串。
+- MCP 工具描述必须用英文（AI 解析英文工具文档更准确）。
+- MCP 工具文档字符串必须包含"后续工具"或"典型工作流"提示。
+- 配置优先级：CLI 参数 > 环境变量 > YAML 文件 > 硬编码默认值。
+- 存入 ChromaDB metadata 前，文件路径必须通过 `_normalize_path()` 统一格式。
+- `chunker.py` 不允许依赖 ChromaDB 或 config 模块 —— 它只做文本处理。
+
+### 禁止
+
+- 禁止硬编码 API 密钥或敏感信息。
+- 禁止使用 `import_` 作为函数前缀（用 `ingest_` 代替）。
+- 禁止在文档字符串或 README 中使用 funboost 专属示例 —— 使用通用示例。
+- 禁止向 `FastMCP()` 构造函数传 `port` 参数 —— 用 `mcp.settings.port` 动态设置。
+- 禁止创建大而全的 MCP 工具加 `mode` 参数 —— 每个工具职责单一。
+- 禁止从 `learn_agent` 导入任何内容 —— 本项目完全独立。
+
+### 风格
+
+- 可使用 Python 3.11+ 语法（match/case、`Self` 类型等）。
+- 文档字符串：模块级用中文，MCP 工具描述用英文。
+- 配置结构用 `dataclass`（不用 Pydantic，保持简洁）。
+- MCP 工具参数用 `pydantic.Field`（FastMCP 要求）。
+
+## 架构决策
+
+### 双存储
+
+ChromaDB 存向量化 chunks（有 overlap），用于语义搜索。
+`raw_files/` 存原始文件快照（无 overlap），用于精确行号读取。
+两者缺一不可，不要移除任何一个。
+
+### 12 个工具，不是 3 个
+
+每个 MCP 工具职责单一、参数最少。
+一个大而全的 `rag_query(mode=...)` 会导致 AI 在参数选择上产生幻觉。
+新增工具时遵循同样的模式：清晰的命名、聚焦的功能、文档字符串中的工作流提示。
+
+### AST 作用域注入
+
+Python 文件的 chunk 在 embedding 前注入 `[File:] [Scope:] [Sig:] [Lines:]` 头部。
+这显著提升了代码查询的搜索精度。
+逻辑在 `chunker.py` 中 —— 不要混入 `core.py`。
+
+### Metadata 字段
+
+每个 chunk 在 ChromaDB 中存储 8 个 metadata 字段：
+`source`、`filename`、`doc_id`、`chunk_index`、`total_chunks`、`line_start`、`line_end`、`scope`。
+
+不要删除或重命名这些字段 —— 下游工具依赖它们。
+
+## 文件组织
+
+```
+nbrag/          # 包根目录
+  __init__.py            # 仅版本号
+  __main__.py            # python -m 入口
+  config.py              # dataclass 配置 + YAML 加载
+  chunker.py             # 文本切分 + AST（无存储依赖）
+  core.py                # ChromaDB + Embedding + Rerank + ingest
+  server.py              # 12 个 MCP 工具 + CLI main()
+scripts/                 # 用户便捷脚本（不属于包）
+  start_http_rag_mcp.py  # 快速启动 HTTP 服务
+  ingest_project.py      # 批量导入模板
+  ingest_funboost.py     # 示例：导入 funboost 项目
+```
+
+## 新增 MCP 工具步骤
+
+1. 在 `core.py` 实现核心逻辑（返回 dict，不返回格式化字符串）。
+2. 在 `server.py` 添加 MCP 包装器，使用 `@mcp.tool()` 装饰器。
+3. 所有参数使用 `pydantic.Field`，写清晰的 `description`。
+4. 文档字符串中包含工作流提示：下一步该调用什么工具。
+5. 更新 `README.md` 中的工具表格。
+6. 如果架构有变化，同步更新本文件的模块表格。
+
+## 依赖
+
+| 包 | 用途 | 版本 |
+|----|------|------|
+| `mcp` | FastMCP 服务框架 | >=1.0.0 |
+| `httpx` | Embedding/Rerank HTTP 客户端 | >=0.24.0 |
+| `chromadb` | 本地向量数据库 | >=0.4.0 |
+| `langchain-text-splitters` | 代码感知文本切分 | >=0.2.0 |
+| `pydantic` | MCP 工具参数校验 | >=2.0.0 |
+| `pyyaml` | YAML 配置文件解析 | >=6.0 |
+
+不要添加重型依赖（torch、transformers 等）—— embedding 通过 API 调用完成。
+
+## python 解释器要求
+
+ai运行此项目脚本时候使用我本地的python解释器 D:/ProgramData/miniconda3/envs/py312/python.exe d:/codes/nbrag/scripts/start_http_rag_mcp.py

nbrag-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ydf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nbrag-0.2.0/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: nbrag
+Version: 0.2.0
+Summary: Agentic RAG MCP Server — 12 tools for AI-driven multi-round code retrieval that outperforms naive single-shot RAG
+Project-URL: Homepage, https://github.com/ydf0509/nbrag
+Project-URL: Repository, https://github.com/ydf0509/nbrag
+Author-email: ydf <ydf0509@sohu.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic-rag,ai-agent,chromadb,code-search,embedding,mcp,mcp-server,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: langchain-text-splitters>=0.2.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# nbrag
+
+**Agentic RAG MCP Server** — 基于 MCP 协议的智能知识库，可导入代码、文档、小说等任意文本，尤其对 Python 项目有奇效（AST 自动解析 class/function 作用域，搜索精准度远超普通 RAG）。支持接入任何 MCP 兼容的 AI 产品：Cursor、OpenCode、Claude Code、Cherry Studio、Open WebUI、Dify、Cline 等，也可嵌入用户自己开发的具备 ReAct Loop 的 Agent 程序。
+
+AI Agent 自主决定何时搜、搜什么、搜几次。12 个精心设计的互补 MCP 工具，吊打传统一轮检索的 Naive RAG。
+
+## 为什么不是 Naive RAG？
+
+| | Naive RAG | **Agentic RAG (本项目)** |
+|---|-----------|----------------------|
+| 检索触发 | 每次提问自动检索 top-5 注入 | AI 自主决定是否检索、用哪个工具 |
+| 检索轮次 | 1 次 | 多轮（实测 m 次搜索 + n 次文件读取） |
+| 查询构造 | 用户原文 | AI 重写查询、组合多种检索策略 |
+| 工具种类 | 仅语义搜索 | 语义 + grep + AST 符号定位 + 原文读取 |
+| 分析深度 | 浅层描述 | 完整的跨文件调用链图 |
+| 准确度 | 浅层匹配，容易遗漏 | **显著优于 Naive RAG**，跨文件关联更完整 |
+
+核心观点：**检索不是管道，是 Agent 的一种能力。**
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+# 方式 A: uvx (推荐，零安装)
+uvx nbrag
+
+# 方式 B: pip
+pip install nbrag
+```
+
+### 2. 配置 API Key
+
+```bash
+# SiliconFlow 免费 API Key (https://siliconflow.cn)
+export NBRAG_API_KEY=sk-xxx
+```
+
+### 3. 在 Cursor / Claude Desktop 中配置 MCP
+
+有三种配置方式，选一种即可：
+
+#### 方式 A: uvx 启动（推荐，零安装）
+
+```json
+{
+  "mcpServers": {
+    "rag": {
+      "command": "uvx",
+      "args": ["nbrag"],
+      "env": {
+        "NBRAG_API_KEY": "sk-xxx"
+      }
+    }
+  }
+}
+```
+
+#### 方式 B: python 命令启动
+
+```json
+{
+  "mcpServers": {
+    "rag": {
+      "command": "python",
+      "args": ["-m", "nbrag"],
+      "env": {
+        "NBRAG_API_KEY": "sk-xxx"
+      }
+    }
+  }
+}
+```
+
+#### 方式 C: HTTP 模式（推荐多项目共享）
+
+> **为什么选 HTTP？** stdio 模式下每个 IDE 窗口会各起一个独立进程。如果你同时打开了几十个项目，
+> 就是几十个 Python 进程 + 几十份 ChromaDB 内存。HTTP 模式只跑一个服务进程，所有 IDE 共享同一个端口，
+> 省内存，也避免多进程并发写同一个 ChromaDB 数据库的锁冲突。
+
+先启动服务：
+
+```bash
+# uvx 方式
+uvx nbrag --transport streamable-http --port 9101
+
+# 或 python 方式
+python -m nbrag --transport streamable-http --port 9101
+```
+
+再配置客户端：
+
+```json
+{
+  "mcpServers": {
+    "rag": {
+      "type": "http",
+      "url": "http://localhost:9101/mcp"
+    }
+  }
+}
+```
+
+### 4. 导入知识库
+
+#### 方式 A: 让 AI 自动导入
+
+告诉 AI：
+
+> "帮我把 D:/codes/my_project 导入到 myproject 知识库，然后搜索 XXX"
+
+AI 会自动调用 `nbrag_add_document` 导入，再用 `nbrag_search` + `nbrag_grep` + `nbrag_find_definition` 多轮检索回答你的问题。
+
+#### 方式 B: 手动脚本导入（推荐大项目）
+
+手动导入更灵活——可以精确指定目录、过滤文件后缀、控制 chunk 参数：
+
+```python
+from nbrag.core import batch_ingest
+
+batch_ingest(
+    paths=[
+        "D:/codes/my_project/src",     # 只导入 src 目录
+        "D:/codes/my_project/docs",    # 加上文档目录
+    ],
+    collection_name="my_project",
+    file_extensions=[".py", ".md"],    # 只要 Python 和 Markdown 文件
+    delete_first=True,                 # 清空旧数据重新导入
+    verbose=True,
+)
+```
+
+参见 `scripts/ingest_project.py` 获取完整示例。
+
+## 12 个工具
+
+| 类别 | 工具 | 功能 |
+|------|------|------|
+| **导入** | `nbrag_add_document` | 导入文件/目录（自动分块 + Embedding + 缓存原文） |
+| **语义检索** | `nbrag_search` | 向量搜索 + Rerank 精排 |
+| **语义检索** | `nbrag_search_and_fetch` | 搜索 + 自动取源码（省一次 round-trip） |
+| **精确检索** | `nbrag_grep` | 关键词/正则搜索（和语义搜索互补） |
+| **精确检索** | `nbrag_find_definition` | AST 精确定位 class/function 完整定义 |
+| **上下文扩展** | `nbrag_get_file_chunks` | 按 chunk 分页浏览文件 |
+| **上下文扩展** | `nbrag_get_raw_file` | 读取无 overlap 的原始文件 |
+| **上下文扩展** | `nbrag_get_adjacent_chunks` | 获取相邻 chunks |
+| **上下文扩展** | `nbrag_get_chunks_by_lines` | 按行号范围取 chunks |
+| **管理** | `nbrag_list` | 列出知识库所有文档 |
+| **管理** | `nbrag_delete` | 删除指定文档 |
+| **管理** | `nbrag_stats` | 知识库统计信息 |
+
+### Skill 指南（教 AI 打组合拳）
+
+12 个工具暴露给 AI 后，AI 只知道"能调什么"，不知道"按什么顺序调"。
+项目附带一个 `skills/rag-workflow/SKILL.md` 文件，把最佳检索流程写成 AI 能读懂的指南。
+
+**使用方法**：复制到你项目的 Skills 目录，AI 就自动学会多轮检索策略。
+
+```bash
+# Cursor
+cp -r skills/rag-workflow/ .cursor/skills/
+
+# Claude Code
+cp -r skills/rag-workflow/ .claude/skills/
+
+# nb_agent
+cp -r skills/rag-workflow/ .nb_agent/skills/
+
+# OpenAI Codex / Gemini CLI（跨平台标准）
+cp -r skills/rag-workflow/ .agents/skills/
+```
+
+Skill 内容包括：发现（nbrag_stats）→ 检索（4 种策略选择）→ 深入（4 种上下文获取方式）→ 多轮重试策略。
+
+### AI 推荐的深度分析工作流
+
+```
+1. nbrag_search → 找到相关文件和大致位置
+2. nbrag_grep → 精确定位类名/方法名/常量（语义搜索漏掉的）
+3. nbrag_find_definition → 获取完整的类/函数定义源码
+4. nbrag_get_raw_file → 读取完整源码验证细节
+5. 跨文件追踪：发现未知符号时重复 2-4 步
+```
+
+## 向量数据库 Metadata 字段
+
+每个 chunk 入库时除了 embedding 向量，还存储了丰富的 metadata。这是很多 RAG 方案忽略的关键设计——有了 metadata，才能实现按文件过滤、按行号定位、按作用域追踪等高级能力。
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `source` | str | `D:/codes/myproject/core.py` | 文件绝对路径（跨平台统一格式） |
+| `filename` | str | `core.py` | 文件名（方便 `filter_filename` 过滤） |
+| `doc_id` | str | `a1b2c3d4e5f6` | 路径 MD5 前 12 位（文件唯一标识） |
+| `chunk_index` | int | `3` | 当前 chunk 在文件中的序号（0-based） |
+| `total_chunks` | int | `15` | 该文件的总 chunk 数 |
+| `line_start` | int | `45` | chunk 对应的起始行号（1-based） |
+| `line_end` | int | `78` | chunk 对应的结束行号 |
+| `scope` | str | `MyClass.my_method` | Python AST 解析的作用域（非 Python 文件为空） |
+
+**chunk 头部注入示例**（embedding 前自动添加，提升搜索精度）：
+
+```
+# [File: D:/codes/myproject/core.py] [Class: class MyClass(Base)] [Method: process] [Sig: def process(self, data: dict)] [Lines: 45-78]
+```
+
+有了这些 metadata + 头部注入，`nbrag_search` 搜 "process 方法" 就能精准命中 `MyClass.process`，而不是随机匹配到别的 "process" 字符串。
+
+## 配置
+
+### 环境变量
+
+| 变量 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `NBRAG_API_KEY` | **是** | | Embedding/Rerank API Key |
+| `NBRAG_BASE_URL` | 否 | `https://api.siliconflow.cn/v1` | API Base URL |
+| `NBRAG_EMBEDDING_MODEL` | 否 | `BAAI/bge-m3` | Embedding 模型 |
+| `NBRAG_RERANK_MODEL` | 否 | `BAAI/bge-reranker-v2-m3` | Rerank 模型 |
+| `NBRAG_DB_PATH` | 否 | `./rag_db` | ChromaDB 存储路径 |
+| `NBRAG_CHUNK_SIZE` | 否 | `1500` | 分块大小 |
+| `NBRAG_CHUNK_OVERLAP` | 否 | `200` | 分块重叠 |
+
+### 配置文件 (可选)
+
+支持 YAML 配置文件，自动搜索顺序：
+1. `./nbrag_config.yaml`
+2. `~/.config/nbrag/config.yaml`
+
+```yaml
+embedding:
+  api_key: ${NBRAG_API_KEY}
+  base_url: https://api.siliconflow.cn/v1
+  model: BAAI/bge-m3
+
+rerank:
+  model: BAAI/bge-reranker-v2-m3
+
+storage:
+  db_path: ./rag_db
+
+chunking:
+  chunk_size: 1500
+  chunk_overlap: 200
+```
+
+### CLI 参数
+
+```bash
+nbrag --help
+nbrag --transport stdio              # 默认
+nbrag --transport streamable-http    # HTTP 模式
+nbrag --api-key sk-xxx              # 直接传 API Key
+nbrag --db-path /data/rag           # 指定存储路径
+nbrag --config ./my_config.yaml     # 指定配置文件
+```
+
+## 设计决策
+
+### 为什么 chunk_size = 1500？
+
+BGE-M3 的最佳召回区间是 700-3000 字符。如果 chunk_size 设太小（如 500），一个 8000 字符的大类会被切成 40+ 块，语义搜索碎片化严重、召回率下降。1500 是实测平衡点，大多数函数/类能完整落入 1-2 个 chunk 内。
+
+即使 chunk 切分不完美，Agentic RAG 也不会像 Naive RAG 那样只用碎片凑答案。AI 会自主判断当前 chunk 信息不足，然后调用 `nbrag_get_raw_file` 读完整源码、用 `nbrag_find_definition` 精确定位类/函数定义、用 `nbrag_grep` 全文搜索关键词，多轮组合直到信息充分。这正是 "检索是 Agent 的能力" 而非固定管道的意义。
+
+### 为什么双存储？
+
+- **ChromaDB**：存向量 chunks（有 overlap），用于语义搜索
+- **raw_files/**：存原始文件快照（无 overlap），用于精确行号读取
+
+AI 经常需要看完整源码，如果只有 chunks 会有 overlap 重复，浪费 token 还容易困惑。
+
+### 为什么 AST scope 注入？
+
+每个 chunk 的 embedding 前注入 `[File: path] [Scope: MyClass.my_method] [Sig: def my_method(self, x)]`。
+这样搜索 "process 方法" 时更容易命中 `class DataProcessor` 下的 `def process(self, data)`，而不是随机匹配到别的 "process" 字符串。
+
+### 为什么 12 个工具而不是 3 个？
+
+MCP 工具设计原则：**职责单一、参数最少、docstring 引导下一步**。
+
+一个大而全的 `rag_query(mode="search|grep|raw|...")` 会导致 AI 幻觉——它不知道该传什么参数。
+拆成 12 个小工具后，每个工具参数清晰，AI 的调用准确率大幅提升。
+
+## 技术栈
+
+| 组件 | 选择 |
+|------|------|
+| Embedding | SiliconFlow BGE-M3（免费、中文最强之一） |
+| Rerank | SiliconFlow BGE-Reranker-v2-m3（免费） |
+| 向量数据库 | ChromaDB（本地持久化，无需外部服务） |
+| 分块 | LangChain TextSplitter + 自研 AST 增强 |
+| MCP | FastMCP (Python) |
+| 传输 | stdio / streamable-http / SSE |
+
+## License
+
+MIT