Nancy Brain

南希大脑

将任何GitHub存储库变成AI代理的可搜索知识库。

从您正在使用的任何软件包中加载完整的源代码、文档、示例和笔记本。Nancy Brain为AI助手提供即时访问：

• 完整源代码 -实际的Python类、方法、实现细节
• 实时文档 -教程，API文档，使用示例
• 实例 -Jupyter笔记本、测试用例、配置文件
• 智能称重 -加强重要文档，跨课程持续学习

人工智能现在可以用你关心的存储库中的实际代码回答诸如“我如何初始化这个类？”或“给我看一个拟合光曲线的例子”之类的问题。

🚀 快速开始

# Install anywhere
pip install nancy-brain

# Initialize a new project
nancy-brain init my-ai-project
cd my-ai-project

# Add some repositories  
nancy-brain add-repo https://github.com/scikit-learn/scikit-learn.git

# Build the knowledge base
nancy-brain build

# Search it!
nancy-brain search "machine learning algorithms"

# Or launch the web interface
nancy-brain ui

🌐 Web管理界面

启动可视化管理界面，便于知识库管理：

nancy-brain ui

特征：

• 🔍 实时搜索 -用即时结果测试您的知识库
• 📚 仓库管理 -使用可视化表单添加/删除GitHub存储库
• 📄 物品管理 -添加/删除带有可视化表单的PDF文章
• 🏗️ 构建控制 -使用选项构建触发器知识库
• 📊 系统状态 -检查嵌入、配置和运行状况

非常适合非技术用户和快速原型制作！

🖥️ 命令行界面

nancy-brain init 
        # Initialize new project
nancy-brain add-repo         # Add GitHub repositories  
nancy-brain add-article    # Add PDF articles
nancy-brain add-new-user  
  # Create login credentials
nancy-brain build                 # Build knowledge base
nancy-brain build --repo    # Build a single named repository only
nancy-brain search "query"        # Search knowledge base
nancy-brain serve                 # Start HTTP API server
nancy-brain ui                    # Launch web admin interface
nancy-brain import-bibtex -f refs.bib    # Import articles from a BibTeX file
nancy-brain import-ads --library "Name"  # Import articles from an ADS library
nancy-brain import-env -f environment.yml  # Add GitHub repos from a conda env

分块

Nancy Brain使用 chunky-files 用于分块存储库的包。在运行构建之前，使用环境变量配置块边界：

要以编程方式调整每个文件的块，请提供自定义 ChunkerConfig 通过构建管道。对于高级语义分块器（Tree sitter、特定于语言的拆分），请安装extra： pip install chunky-files[tree].

可选：文档摘要（本地或Anthropic）

选择在构建过程中生成文档级摘要和建议的搜索权重：

export ENABLE_DOC_SUMMARIES=true   # or pass --summaries on the build command

强制本地摘要：

export NB_USE_LOCAL_SUMMARY=true
nancy-brain build --summaries

使用人择摘要：

export NB_USE_LOCAL_SUMMARY=false
export ANTHROPIC_API_KEY="sk-ant-..."
nancy-brain build --summaries

NB_USE_LOCAL_SUMMARY=true 强制执行本地摘要，即使 ANTHROPIC_API_KEY 已设置。 摘要缓存在 knowledge_base/cache/summaries/ 使用文档内容哈希，因此仅重新运行 重新计算更改的文件。建议的重量写在 knowledge_base/embeddings/auto_model_weights.json 在合并到您的活动之前进行审核 model_weights.yml.

技术架构

一个轻量级的检索增强生成（RAG）知识库，具有：

• 嵌入+搜索管道（基于txtai/FAISS）
• HTTP API连接器（FastAPI）
• 模型上下文协议（MCP）服务器连接器（用于搜索/检索/树/权重的工具）
• 动态加权系统（扩展/路径权重+运行时文档首选项）

旨在为Slack、IDE、Claude Desktop、自定义GPT和任何支持MCP的客户端上的AI助手提供动力。

______________________________________________________________________

1.安装和快速设置

用户（推荐）

# Install the package
pip install nancy-brain

# Initialize a new project
nancy-brain init my-knowledge-base
cd my-knowledge-base

# Add repositories and build
nancy-brain add-repo https://github.com/your-org/repo.git
nancy-brain add-article "https://arxiv.org/pdf/paper.pdf" "paper_name" --description "Important paper"
nancy-brain build

# Launch web interface
nancy-brain ui

对于开发者

# Clone and install in development mode
git clone 
cd nancy-brain
pip install -e ."[dev]"

# Test installation
pytest -q
nancy-brain --help

开发人员注意：构建管道现在需要 docutils 和 pylatexenc 可靠地转换 重新结构化文本(.rst)LaTeX(.tex)将文件转换为纯文本。这些包括在项目的 依赖关系(pyproject.toml)所以 pip install -e ."[dev]" 将自动安装它们。如果你 如果希望在您的环境中手动安装它们，请运行：

pip install docutils pylatexenc

开发人员说明（CLI和测试）： CLI命令和 RAGService 避免导入繁重的ML库（例如 txtai 和 torch)at 模块导入时间。服务推迟初始化嵌入 Search 直到嵌入索引为 存在或命令明确需要它。这使得运行CLI帮助和大多数单元测试快速安全 在最小的环境中。如果测试需要功能 Search，嘲笑 rag_core.search （插入a 虚拟模块进入 sys.modules['rag_core.search'])在实例化之前 RAGService.

______________________________________________________________________

2.项目布局（核心部分）

nancy_brain/                    # Main Python package
├── cli.py                      # Command line interface
├── admin_ui.py                 # Streamlit web admin interface
└── __init__.py                 # Package initialization

connectors/http_api/app.py      # FastAPI app
connectors/mcp_server/          # MCP server implementation
rag_core/                       # Core service, search, registry, store, types
scripts/                        # KB build & management scripts
config/repositories.yml         # Source repository list (input KB)
config/weights.yaml             # Extension + path weighting config
config/model_weights.yaml       # (Optional) static per-doc multipliers

______________________________________________________________________

3.配置

3.1存储库(config/repositories.yml)

结构（类别映射到存储库列表）：

:
  - name: repoA
    url: https://github.com/org/repoA.git
  - name: repoB
    url: https://github.com/org/repoB.git
    ref: v2.1.0  # optional: pin to branch, tag, or full commit SHA

类别成为知识库中的路径前缀（例如。 cat1/repoA/...).

3.2重量配置(config/weights.yaml)

• extensions：按文件扩展名（.py、.md等）排列的基数乘数
• path_includes：如果子字符串出现在doc_id中，则乘法应用乘数。

3.3模型重量(config/model_weights.yaml)

可选的静态文档乘数（传统/种子）。运行时更新通过 /weight 端点或MCP set_weight 工具覆盖或增加内存权重。

3.4环境变量

您可以导出（或放入）的常见旋钮 config/.env)要调整构建和管理UI：

提示：首先构建下载抱抱脸模型；集 NB_TEXT_EMBEDDING_MODEL 转到本地路径（或快速运行 `python -

该命令引导身份验证表（如果不存在），使用哈希值对密码进行哈希运算 `passlib`，并将记录保存在配置的SQLite文件中。\
点 `NB_USERS_DB` 如果需要集中式用户存储，请在运行命令之前将其复制到共享路径。

______________________________________________________________________

## 4.建立知识库

嵌入必须在有意义的搜索之前构建。

### 使用CLI（推荐）

Basic build (repositories only)

nancy-brain build

Build a single named repository only (fast iteration)

nancy-brain build --repo MulensModel

Build with PDF articles (if configured)

nancy-brain build --articles-config config/articles.yml

Force update all repositories

nancy-brain build --force-update

Or use the web interface

nancy-brain ui # Go to "Build Knowledge Base" page

### 直接使用Python脚本

conda activate nancy-brain cd src/nancy-brain

Basic build (repositories only)

python scripts/build_knowledge_base.py \ --config config/repositories.yml \ --embeddings-path knowledge_base/embeddings

Full build including optional PDF articles (if config/articles.yml exists)

python scripts/build_knowledge_base.py \ --config config/repositories.yml \ --articles-config config/articles.yml \ --base-path knowledge_base/raw \ --embeddings-path knowledge_base/embeddings \ --force-update \ --dirty

You can run without the dirty tag to automatically

remove source material after indexing is complete

跑 `python scripts/build_knowledge_base.py -h` 对于所有选项。

### 4.1 PDF文章（可选快速设置）

1. 创建 `config/articles.yml` （示例）：

journal_articles: - name: Paczynski_1986_ApJ_304_1 url: https://ui.adsabs.harvard.edu/link_gateway/1986ApJ...304....1P/PUB_PDF description: Paczynski (1986) – Gravitational microlensing

2. 安装Java（用于Tika PDF提取）-macOS：

brew install openjdk export JAVA_HOME="/opt/homebrew/opt/openjdk" export PATH="$JAVA_HOME/bin:$PATH"

3. （仅可选回退）如果跳过Java，请安装轻量级PDF库：

pip install PyPDF2 pdfplumber

4. 使用文章构建（显式）：

python scripts/build_knowledge_base.py --config config/repositories.yml --articles-config config/articles.yml

5. 保留原始PDF以供检查：添加 `--dirty`.

笔记：

- 如果Java/Tika不可用，脚本会尝试回退提取（需要PyPDF2/pdfplumber或fitz）。
- 清理会删除原始PDF，除非 `--dirty` 提供。
- 文章文档的索引位于 `journal_articles//`.

关键标志：

- `--config` 存储库的路径YAML（was——旧文档中的存储库）
- `--articles-config` 可选的PDF文章YAML
- `--base-path` 原始存储库/PDF所在的位置（默认知识库/raw）
- `--embeddings-path` 输出索引目录
- `--force-update` 重新提取存储库/重新下载PDF
- `--category ` 限制为一个类别
- `--dry-run` 显示动作而不执行
- `--dirty` 保留原始源（跳过清理）

这将：

1. 克隆/更新以下列出的存储库 `knowledge_base/raw//`
1. （可选）将PDF下载到类别目录中
1. 转换笔记本（\*.ipynb->\*.nb.txt）（如果nb4llm可用）
1. 提取和规范化文本+（可选）PDF文本
1. 在以下位置构建/更新嵌入索引 `knowledge_base/embeddings` （以及 `code_index` 如果启用了双嵌入）

当存储库或文章发生更改时重新运行。

______________________________________________________________________

## 5.运行服务

### Web管理界面（建议用于入门）

nancy-brain ui

Opens Streamlit interface at http://localhost:8501

Features: search, repo management, build control, status

### HTTP API服务器

Using CLI

nancy-brain serve

Or directly with uvicorn

uvicorn connectors.http_api.app:app --host 0.0.0.0 --port 8000

### MCP服务器（用于AI助手）

Run MCP stdio server

python run_mcp_server.py

以编程方式初始化服务（示例模式）：

from pathlib import Path from connectors.http_api.app import initialize_rag_service initialize_rag_service( config_path=Path('config/repositories.yml'), embeddings_path=Path('knowledge_base/embeddings'), weights_path=Path('config/weights.yaml'), use_dual_embedding=True )

然后，FastAPI依赖层将为请求提供服务。

### 命令行搜索

Quick search from command line

nancy-brain search "machine learning algorithms" --limit 5

Search with custom paths

nancy-brain search "neural networks" \ --embeddings-path custom/embeddings \ --config custom/repositories.yml

### 5.1端点（承载认证占位符）

|方法|路径|描述|
|--------|------|-------------|
|得到| `/health` |服务状态|
|得到| `/version` |索引/构建元|
|得到| `/search?query=...&limit=N` |搜索文档|
|职位| `/retrieve` |检索通道（doc_id+行范围）|
|职位| `/retrieve/batch` |批量检索|
|得到| `/tree?prefix=...` |列出KB树|
|职位| `/weight` |设置运行时文档权重|

例子：

curl -H "Authorization: Bearer TEST" 'http://localhost:8000/search?query=light%20curve&limit=5'

## 管理员UI身份验证

Streamlit管理UI支持HTTP API身份验证（推荐）和
为地方发展提供便利和不安全的旁路。

- 要使用HTTP API进行身份验证，请确保API正在运行并设置 `NB_API_URL` 如果不使用默认值：

export NB_API_URL="http://localhost:8000" streamlit run nancy_brain/admin_ui.py

- 对于没有API的本地开发，启用不安全的旁路（仅在本地使用）：

export NB_ALLOW_INSECURE=true streamlit run nancy_brain/admin_ui.py

管理UI将访问令牌和刷新令牌存储在 `st.session_state` 对于当前Streamlit会话。

设置文档权重（典型提升系数为0.5-2.0）：

curl -X POST -H 'Authorization: Bearer TEST' \ -H 'Content-Type: application/json' \ -d '{"doc_id":"cat1/repoA/path/file.py","multiplier":2.0}' \ http://localhost:8000/weight

______________________________________________________________________

## 6.MCP服务器

运行MCP stdio服务器：

python run_mcp_server.py

暴露的工具（操作名称）：

- `search` （查询、限制）
- `retrieve` （doc_id，开始，结束）
- `retrieve_batch`
- `tree` （前缀、深度）
- `set_weight` （doc_id，乘数）
- `status` / `version`

### 6.1 VS代码集成

1. 安装模型上下文协议客户端扩展（例如“MCP Explorer”或同等产品）。
1. 添加一个指向脚本stdio传输的服务器条目。配置代码片段示例：

{ "mcpServers": { "nancy-brain": { "command": "python", "args": ["/absolute/path/to/src/nancy-brain/run_mcp_server.py"], "env": { "PYTHONPATH": "/absolute/path/to/src/nancy-brain" } } } }

*具体的曼巴环境示例：*

{ "servers": { "nancy-brain": { "type": "stdio", "command": "/Users/malpas.1/.local/share/mamba/envs/nancy-brain/bin/python", "args": [ "/Users/malpas.1/Code/slack-bot/src/nancy-brain/run_mcp_server.py" ], "env": { "PYTHONPATH": "/Users/malpas.1/Code/slack-bot/src/nancy-brain", "KMP_DUPLICATE_LIB_OK": "TRUE" } } }, "inputs": [] }

3. 重新加载VS代码。供应商应列出工具；调用 `search` 测试。

### 6.2克劳德桌面

Claude在其设置文件中支持MCP配置。添加一个类似于上面的条目（command+args）。重新启动克劳德桌面；工具出现在提示工具菜单中。

______________________________________________________________________

## 7.用例和示例

### 对于研究人员

Add astronomy packages

nancy-brain add-repo https://github.com/astropy/astropy.git nancy-brain add-repo https://github.com/rpoleski/MulensModel.git

Add key research papers

nancy-brain add-article \ "https://ui.adsabs.harvard.edu/link_gateway/1986ApJ...304....1P/PUB_PDF" \ "Paczynski_1986_microlensing" \ --category "foundational_papers" \ --description "Paczynski (1986) - Gravitational microlensing by the galactic halo"

nancy-brain build

AI can now answer: "How do I model a microlensing event?"

nancy-brain search "microlensing model fit"

### 面向ML工程师

Add ML frameworks

nancy-brain add-repo https://github.com/scikit-learn/scikit-learn.git nancy-brain add-repo https://github.com/pytorch/pytorch.git nancy-brain build

AI can now answer: "Show me gradient descent implementation"

nancy-brain search "gradient descent optimizer"

### 对于团队

Launch web interface for non-technical users

nancy-brain ui

Point team to http://localhost:8501

They can search, add repos, manage articles, trigger builds visually

Repository Management tab: Add GitHub repos

Articles tab: Add PDF papers and documents

______________________________________________________________________

## 8.松弛机器人（南希）

面向Slack的助手位于此子模块之外（请参阅父存储库）。高级步骤：

1. 确保HTTP API运行且可访问（或将服务直接嵌入到机器人程序进程中）。
1. Bot接收用户消息->构造查询->调用 `/search` 并选择 `/retrieve` 为了上下文。
1. Bot在发送回之前会编写包含源引用（doc_id和GitHub URL）的答案。
1. 可选：自适应调用 `/weight` 当反馈指示应增强或减弱源时。

检查根级别 `nancy_bot.py` 或Slack集成文档(`SLACK.md`)有关令牌设置和事件订阅的详细信息。

______________________________________________________________________

## 9.自定义GPT（OpenAI操作/函数调用）

定义映射到HTTP端点的OpenAI工具规范：

- `searchDocuments(query, limit)` ->获取/搜索
- `retrievePassage(doc_id, start, end)` ->POST/检索
- `listTree(prefix, depth)` ->GET/树
- `setWeight(doc_id, multiplier)` ->POST/重量

使用API网关或直接URL。包括身份验证头。提供与请求/响应模型匹配的JSON模式。

______________________________________________________________________

## 10.动态称重流程

1. 嵌入的基础分数（双重或单一）。
1. 扩展倍数（来自weights.yaml）。
1. 路径乘数（累积）。
1. 模型权重（静态配置+运行时覆盖，通过 `/weight`).
1. 调整后的分数=基数\*扩展权重\*模型权重（以及任何折叠到扩展权重步长中的路径乘数）。

运行时 `/weight` 在后续搜索中立即生效。

______________________________________________________________________

## 11.更新/重建

|操作|命令|
|--------|---------|
|拉取回购更新| `nancy-brain build --force-update` 或重新运行构建脚本|
|更改扩展权重|编辑 `config/weights.yaml` （运行时不需要重新启动？如果缓存，则重新启动或重建）|
|更改嵌入模型|删除/重命名现有模型 `knowledge_base/embeddings` 并使用新的环境变量进行重建|

______________________________________________________________________

## 12.部署说明

- 容器化：使用烘焙的预构建嵌入构建映像或挂载持久卷。
- 健康探头： `/health` （一旦rag_service初始化，返回200）否则503。
- 并发：FastAPI异步安全；权重更新是简单的dict写入（低争用）。对于重载，如果出现种族，请考虑锁。
- 运行时权重的持久性：当前在内存中；如果需要，手动持久化（扩展 `set_weight`).

______________________________________________________________________

## 13.故障排除

|症状|原因|修复|
|---------|-------|-----|
|503 RAG服务未初始化| `initialize_rag_service` 未调用/路径错误|使用正确的嵌入路径调用初始化器|
|空搜索结果|嵌入未构建/路径错误|重新运行 `nancy-brain build`，验证索引目录|
|macOS OpenMP崩溃| MKL/libomp重复| `KMP_DUPLICATE_LIB_OK=TRUE` 已经提前设置|
|MCP工具不可见|路径错误或Python |在MCP配置中使用绝对路径|
|找不到CLI命令|未安装包| `pip install nancy-brain` |

启用调试日志记录：

export LOG_LEVEL=DEBUG

（添加逻辑或运行 `uvicorn --log-level debug`)

______________________________________________________________________

## 14.发展与贡献

Clone and set up development environment

git clone cd nancy-brain pip install -e ."[dev]"

Run tests

pytest

Run linting

black nancy_brain/ flake8 nancy_brain/

Test CLI locally

nancy-brain --help

### 释放

Nancy Brain使用自动版本控制和PyPI发布：

Bump patch version (0.1.0 → 0.1.1)

./release.sh patch

Bump minor version (0.1.0 → 0.2.0)

./release.sh minor

Bump major version (0.1.0 → 1.0.0)

./release.sh major

这会自动：

1. 更新中的版本号 `pyproject.toml` 和 `nancy_brain/__init__.py`
1. 创建git commit和标签
1. 推送到GitHub，通过GitHub操作触发PyPI发布

手动版本管理：

See current version and bump options

bump-my-version show-bump

Dry run (see what would change)

bump-my-version bump --dry-run patch

______________________________________________________________________

## 15.路线图（可选）

- 运行时权重的持久层
- 附加检索过滤器（例如语义重排序）
- 身份验证插件/令牌验证
- VS代码扩展
- 包发布到PyPI

______________________________________________________________________

## 16.许可证

请参阅父存储库许可证。

______________________________________________________________________

## 17.最小验证脚本

After build & run

curl -H 'Authorization: Bearer TEST' 'http://localhost:8000/health'

期望JSON具有状态+trace_id。

______________________________________________________________________

快乐搜索。

](https://github.com/amberlee2427/nancy-brain/blob/main/LICENSE) ](https://github.com/amberlee2427/nancy-brain/issues) ](https://github.com/amberlee2427/nancy-brain/releases) ](https://github.com/amberlee2427/nancy-brain/actions/workflows/ci.yml) [![docs status](https://github.com/amberlee2427/nancy-brain/actions/workflows/docs.yml/badge.svg)](https://github.com/amberlee2427/nancy-brain/actions/workflows/docs.yml)