Metadata-Version: 2.5
Name: igrep2
Version: 0.1.143
Summary: Agent-first semantic grep — filesystem-native retrieval
Project-URL: Documentation, https://github.com/piboye/igrep/blob/main/docs/README.md
Project-URL: Repository, https://github.com/piboye/igrep
License-Expression: MIT
License-File: LICENSE
Requires-Python: <3.15,>=3.14
Requires-Dist: aiohttp>=3.13.0
Requires-Dist: bm25s>=0.2.0
Requires-Dist: charset-normalizer>=3.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: html2text>=2024.2.26
Requires-Dist: httpx2>=2.5.0
Requires-Dist: httpx[socks]>=0.27.0
Requires-Dist: huggingface-hub>=0.20.0
Requires-Dist: lsprotocol>=2025.0.0
Requires-Dist: ltp-extension>=0.1.13
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp<3,>=2.1.1
Requires-Dist: nltk>=3.9.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: openai>=1.107.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: orjson>=3.11.8
Requires-Dist: oslex>=2.0.0
Requires-Dist: overrides>=7.7.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: prompt-toolkit>=3.0.40
Requires-Dist: psutil>=5.9.0
Requires-Dist: pygls>=2.1.1
Requires-Dist: pymupdf>=1.28.2
Requires-Dist: pyright>=1.1.408
Requires-Dist: python-docx>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-pptx>=0.6.23
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rjieba>=0.1.13
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: tree-sitter-language-pack>=0.13
Requires-Dist: uvicorn>=0.41.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: websockets>=13.0
Requires-Dist: xxhash>=3.5.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: lsp
Provides-Extra: markitdown
Requires-Dist: markitdown>=0.1.0; extra == 'markitdown'
Provides-Extra: mlx
Description-Content-Type: text/markdown

# igrep

面向 Agent 的 filesystem-native retrieval kernel。

`igrep` 直接在本地代码和文档上做自然语言检索，不需要预建向量索引；返回可定位到文件和行号的证据，也可以继续生成带引用的研究回答。CLI、MCP、Web 管理台和编辑器集成复用同一套检索语义。

```bash
igrep search "鉴权失败后在哪里重试" ~/code/my-project
igrep ask "这个项目如何加载配置？" ~/code/my-project
```

## 它解决什么问题

- **代码与文档检索**：自然语言查询、文件类型和 glob 过滤、git diff 范围、结构化输出。
- **无需向量索引**：文本和代码直接搜索；PDF、Office 文档和图片按需预处理成隐藏 sidecar。
- **Agent 原生接入**：编码 Agent 的默认 MCP `code` 配置只提供 semantic search；显式 `full` 可追加符号候选和 LSP 精确导航，并为主流编码 Agent 提供一键配置。
- **多种证据源**：本地文件、公开 Web、单个公开文档、内部搜索源和已授权网站各自保持清晰边界。
- **Local-first**：可使用 Apple Silicon 上的本地 oMLX，也可连接自管或云端的 OpenAI-compatible 服务。

igrep 不是通用 RAG 平台。`igrep search` 是主入口；`ask`、`dig` 和 `chat` 在检索证据之上工作；`serve` 是本机管理与 host 层，不改变检索语义。

## 安装

公开 distribution 是 `igrep2`，安装后的命令和 import 仍是 `igrep`。当前版本需要 Python 3.14。

推荐使用隔离的 uv tool 环境：

```bash
uv tool install --python 3.14 igrep2
igrep --version
```

也可以安装到已有的 Python 3.14 环境：

```bash
python3.14 -m pip install igrep2
```

组织可以用自己的 setup bundle 批量安装内部 source 插件与 Web provider 扩展；`igrep2` 本身不依赖任何此类 bundle。

升级已有安装：

```bash
igrep upgrade
```

## 选择 AI runtime

安装 CLI 后，选择一种运行方式：

| 场景 | 命令 | 说明 |
|---|---|---|
| 自管或外部端点 | `igrep setup` | 安装轻量系统依赖并创建通用配置模板，不安装本地模型 |
| 云端 OpenAI-compatible 服务 | `igrep setup` 后在 `~/.igreprc/.env` 配置 endpoint 与 API key | 变量见下文[配置](#配置) |
| Apple Silicon 全本地 | `igrep setup local` | 安装或复用 oMLX，下载默认模型并配置本地端点 |

完成后检查能力状态：

```bash
igrep doctor
```

`doctor` 默认只报告问题；在 CI 或安装脚本中需要非零退出码时使用 `igrep doctor --strict`。

## 5 分钟上手

### 搜本地代码和文档

```bash
# 当前目录
igrep search "配置在哪里加载"

# 指定目录和文件类型
igrep search "重试策略" ~/code/my-project --type py

# rg 风格 glob；可重复，! 表示排除
igrep search "鉴权逻辑" . -g 'src/**' -g '!**/test_*'

# 只搜相对 HEAD 的 git 变更文件
igrep search "可能破坏兼容性的改动" . --diff

# 供程序或 Agent 消费的单个 JSON document
igrep search "错误处理" . --format json

# 流式消费者使用一行一个结果的 JSONL
igrep search "错误处理" . --format jsonl
```

查询也可以来自 Unix pipe。结构化输入可显式指定 `text`、`jsonl`、`markdown`、`git` 或 `log`：

```bash
git diff | igrep search "潜在回归" --stdin-format git
```

### 选择检索强度

| 模式 | 适合场景 | 行为 |
|---|---|---|
| `fast` | 高频本地检索 | 本地关键词规划；不调用 LLM 做查询扩展，可使用已配置的 reranker |
| `normal` | 日常使用，默认值 | 增加有界的 query-time LLM 扩展和最终排序 |
| `ultra` | 多跳或复杂问题 | 增加第二轮证据反馈与 LLM 最终排序，成本和延迟更高；质量主要取决于最终排序用的模型，可用 `IGREP_NOINDEX_LLM_FINAL_SORT_MODEL` 单独指定 |

```bash
igrep search "请求从入口到持久化的完整流程" . --mode ultra
```

模式只调整质量、延迟和远端调用量，不改变输出协议。缺少可选后端时，对应通道关闭，基础文件检索仍保留。

### 搜索后继续研究

```bash
# 单次、有界、带引用的回答
igrep ask "配置优先级是什么？" .

# 分阶段深度研究，只把最终答案写到 stdout
igrep dig "一次搜索请求经过哪些模块？" .

# 交互式多轮 REPL
igrep chat
```

`ask` / `dig` 的 `--detail` 把紧凑进度写到 stderr，`--verbose` 输出调试
trace，`--json` 输出单个 JSON document。`chat` 是交互式终端，不是 JSON
接口；机器消费者应使用 `igrep chat <subcommand>` 或 `igrep ask --stream`。

## 多格式文件

代码、Markdown 和普通文本无需准备即可搜索。PDF、DOCX、PPTX、XLSX 等二进制文件需要先转换；图片内容需要 OCR/VLM augment：

```bash
igrep prepare ~/Documents      # convert + augment
igrep prepare --only convert ~/Documents    # 只做确定性格式转换，不调用 VLM/OCR
igrep prepare --only augment ~/Documents    # 只生成图片描述 sidecar
```

这些命令生成 dot-hidden `.igrep.md`、`.igrep.images/` 和 `.igrep.vision.md` 产物，不创建传统向量/FTS 索引，也不修改用户原始 Markdown。之后仍用普通的 `igrep search` 查询。

## 可选词法索引

普通本地搜索默认不需要索引。需要持久化词法索引时，使用统一的 `index` 生命周期命令；BM25、SQLite 和 Elasticsearch 都是实现细节：

```bash
IGREP_BM25_INDEX_BACKEND=sqlite igrep index build .
IGREP_BM25_INDEX_BACKEND=sqlite igrep index status .
```

命令边界见 [CLI 进程契约][cli-contract] §1.1，参数以 `igrep index --help` 为准。

## Web、内部源与网站源

这些入口与本地文件搜索相互独立，不做隐式联邦融合。

```bash
# 配置 SearXNG / Tavily / Serper / Exa 等 provider
igrep setup web-search
igrep web-search "Python 3.14 release notes"
igrep web-dig "比较 Python 3.13 与 3.14 的并发变化"

# 在调用方给定的一个公开文档内找证据
igrep page-search https://example.com/spec.pdf "timeout policy"

# 查看并使用已配置的内部只读 source
igrep source list
igrep isearch "支付失败如何重试" --source <installed-plugin-source>
```

`igrep isearch` 还支持单文件 Python 插件和 command-backed source。安装插件前必须用 3–5 条真实查询通过资质验证，完整协议见[内部搜索插件指南][plugin-guide]。

对于只有你登录后的 Chrome 才能搜到的网站（公司 wiki、内网工具、个人账号应用），
网站源借用你已登录的浏览器身份，把该站点自己的搜索变成 `isearch` 来源——
公开内容走 `web-search`，有 API/token 的系统写插件，只有这类站点用它：

```bash
igrep serve start
igrep setup chrome
igrep source site list
igrep isearch "query" --site <source-id>
```

网站源只重放用户审核并启用的搜索请求；运行时返回站点搜索结果，不跟随结果 URL
抓取正文，也不保存 cookie/token。完整上手流程见[网站搜索源指南][website-guide]。

**自动修复**：网站改版导致搜索失效时，失败信息会直接给出修复命令——

```bash
igrep source site repair <source-id> --queries 词1,词2,词3 --approve
```

igrep 用脱敏后的失败证据（字段名、路径候选，绝不含 cookie 和页面内容）让 AI
提出修复提案——本机装了 Codex CLI 就走它的禁网沙箱，否则走你已配置的 ask LLM
路由——再用你的 3–5 个真实搜索词重新验证、终审重放后才激活。AI 只出提案，不碰信任门。

## 接入编码 Agent

`igrep setup <platform>` 安装该宿主支持的最小原生接入面。MCP 类宿主可按
`--help` 使用 `--scope project`；OpenClaw、Hermes、Pi 和 DeepSeek Harness
使用各自的插件或包管理机制，不接受通用 `--scope`。

| 平台 | 默认接入面 | 命令 |
|---|---|---|
| Codex | MCP + skill/routing | `igrep setup codex` |
| Claude Code | MCP + skill/routing | `igrep setup claude-code` |
| CodeBuddy | MCP + skill/routing | `igrep setup codebuddy` |
| OpenCode | MCP + routing | `igrep setup opencode` |
| Cursor | MCP + rule | `igrep setup cursor` |
| Gemini CLI | MCP + routing | `igrep setup gemini` |
| GitHub Copilot CLI | MCP | `igrep setup copilot` |
| OpenClaw | additive search + web search | `igrep setup openclaw --flavor search` |
| Hermes | search/web/read plugin | `igrep setup hermes --enable-plugin` |
| Pi | memory extension | `igrep setup pi` |
| DeepSeek Harness | search + web search + memory | `igrep setup deepseek-harness` |

OpenClaw 只有在明确要替换其 memory slot 时才使用
`igrep setup openclaw --flavor memory`。Hermes 的 MemoryProvider 也是显式可选项：
`igrep setup hermes --with-memory-provider --activate-memory-provider`；已有其他
provider 时不会自动覆盖。

使用 MCP 的编码 Agent 默认使用窄的 `code` toolset，只包含：

- `semantic_search`：按自然语言意图检索代码和已准备的文档

精确符号导航是低频能力，仅在显式 `full` toolset 中提供
`symbol_suggest`、`lsp_locate`、`lsp_refs` 和 `lsp_callers`。安装、体检和
回报流程见 [Agent 安装指南][agent-install]。

## Agent 记忆

`igrep mem` 是给 Agent 宿主用的 file-backed 记忆：宿主把可见对话 `ingest` 进
`<workspace>/.igrep/mem`（增量、只追加，**不必每轮调**），`maintain` 抽取用户
profile 并顺带补齐没交过来的会话，session 开始用 `wake` 注入常驻 profile，
模型随时用 `recall` 按问题检索。

```bash
igrep mem ingest --workspace ~/agent-ws --transcript turns.jsonl --session-id s1
igrep mem maintain --workspace ~/agent-ws
igrep mem wake --workspace ~/agent-ws --format markdown
igrep mem recall "用户偏好什么 Python 工具" --workspace ~/agent-ws
```

workspace 目录就是隔离单元。一个 agent 服务很多人时不用自己管目录：用
`--store ROOT --user U [--tenant T]` 代替 `--workspace`，igrep 在 ROOT 下给每个
(tenant, user) 解析一个私有 workspace（哈希目录，读不建、写才建），`--rows -` 直接喂
对话行，`maintain --pending` 一次处理整个 store，`mem store list|purge|sweep` 做
枚举、删除与不活跃清理：

```bash
printf '%s\n' '{"role":"user","content":"以后回复用中文"}' \
  | igrep mem ingest --store /srv/mem --tenant acme --user alice --session-id s1 --rows -
igrep mem maintain --store /srv/mem --pending
igrep mem recall "回复语言偏好" --store /srv/mem --tenant acme --user alice
igrep mem store sweep --store /srv/mem --inactive-days 90          # 只报告；--apply 才删
```

OpenClaw / Hermes / Pi / DeepSeek Harness 的现成接入见上表；自己的宿主按
[记忆宿主接入指南][mem-host-guide]接入。

## 管理台与项目

```bash
igrep project add ~/code/my-project
igrep serve run
```

`serve` 是唯一管理入口，提供项目、搜索、聊天、后端状态和诊断界面。后台运行和 OS service 管理使用：

```bash
igrep serve start
igrep serve status
igrep serve stop
```

`serve status` 与 `doctor` 一样默认只报告；需要门禁语义时追加 `--strict`。

## 配置

配置优先级从高到低：

1. 当前进程的 `IGREP_*` 环境变量
2. `<project>/.igrep/.env`
3. `~/.igreprc/.env`
4. `OPENAI_*`（只作为 LLM fallback）
5. 代码默认值

连接自管端点的最小示例：

```bash
IGREP_EMBEDDING_URL=http://localhost:8000/v1
IGREP_EMBED_MODEL=your-embedding-model

IGREP_LLM_URL=http://localhost:8000/v1
IGREP_LLM_MODEL=your-chat-model

IGREP_RERANK_URL=http://localhost:8000/v1
IGREP_RERANK_MODEL=your-reranker
```

`OPENAI_API_KEY` 是启用 LLM fallback 的锚点；`OPENAI_BASE_URL` 和 `OPENAI_MODEL` 只随它一起生效。Embedding、rerank 和 OCR 不读取 `OPENAI_*`。显式设置空的 `IGREP_LLM_URL=` 可禁用该 fallback 与共享 LLM 路由；`igrep ask` / chat / Ultra 的 late selector / `mem maintain` 走 `IGREP_ASK_LLM_*` 路由，单独配置了 `IGREP_ASK_LLM_URL` 时不受影响，要全部禁用需同时设 `IGREP_ASK_LLM_URL=`。Ultra 的 planner 与其他检索 LLM 阶段保留在 shared 路由，最终排序对 ask 模型敏感（同一语料下 R@10 可差 8pp）；当 ask 路由的模型是为其他用途（如 `mem maintain`）选的，用 `IGREP_NOINDEX_LLM_FINAL_SORT_MODEL`（可配 `_URL` / `_API_KEY` / `_EXTRA_BODY`）只给最终排序换更强的模型。

凭证只放环境变量或 `.env`，不要写入 profile 或提交到仓库。`IGREP_API_KEY` 是全局 fallback；能力级 `IGREP_LLM_API_KEY`、`IGREP_EMBEDDING_API_KEY`、`IGREP_RERANK_API_KEY` 和 `IGREP_OCR_API_KEY` 可单独覆盖。完整配置契约见[本地服务协议][service-protocol]。

## 文档

- [文档导航][docs]
- [技术架构][architecture]
- [CLI 进程与机器输出契约][cli-contract]
- [管理生命周期规范][management]
- [HTTP OpenAPI][openapi]
- [Agent 安装指南][agent-install]
- [记忆宿主接入指南][mem-host-guide]

## License

MIT

[docs]: https://github.com/piboye/igrep/blob/main/docs/README.md
[architecture]: https://github.com/piboye/igrep/blob/main/docs/ARCHITECTURE.md
[cli-contract]: https://github.com/piboye/igrep/blob/main/docs/CLI_CONTRACT.md
[management]: https://github.com/piboye/igrep/blob/main/spec/management.md
[service-protocol]: https://github.com/piboye/igrep/blob/main/docs/LOCAL_SERVICE_PROTOCOL.md
[openapi]: https://github.com/piboye/igrep/blob/main/spec/openapi.yaml
[agent-install]: https://github.com/piboye/igrep/blob/main/docs/AGENT_INSTALL.md
[plugin-guide]: https://github.com/piboye/igrep/blob/main/docs/INTERNAL_SOURCE_DESIGN.md
[website-guide]: https://github.com/piboye/igrep/blob/main/docs/WEBSITE_SEARCH_SOURCE_GUIDE.md
[mem-host-guide]: https://github.com/piboye/igrep/blob/main/docs/MEM_HOST_GUIDE.md
