Metadata-Version: 2.5
Name: igrep2
Version: 0.1.154
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: 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: ltp-extension>=0.1.13
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp<3,>=2.1.1
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: pathspec>=0.12.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: prompt-toolkit>=3.0.40
Requires-Dist: pymupdf>=1.28.2
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: rjieba>=0.1.13
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: tree-sitter-c-sharp>=0.23.5
Requires-Dist: tree-sitter-c>=0.24.2
Requires-Dist: tree-sitter-cpp>=0.23.4
Requires-Dist: tree-sitter-dart>=0.1.0
Requires-Dist: tree-sitter-elixir>=0.3.5
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-kotlin>=1.1.0
Requires-Dist: tree-sitter-lua>=0.5.0
Requires-Dist: tree-sitter-objc>=3.0.2
Requires-Dist: tree-sitter-php>=0.24.1
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-ruby>=0.23.1
Requires-Dist: tree-sitter-rust>=0.24.2
Requires-Dist: tree-sitter-scala>=0.26.2
Requires-Dist: tree-sitter-sql>=0.3.11
Requires-Dist: tree-sitter-swift>=0.7.3
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: tree-sitter-zig>=1.1.2
Requires-Dist: tree-sitter>=0.25.2
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: nltk>=3.9.0; 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: markitdown
Requires-Dist: markitdown>=0.1.0; extra == 'markitdown'
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 原生接入**：Claude Code 和 Codex 的默认 MCP `code` 配置只提供 semantic search，精确符号导航交给宿主自己的 `rg` 和原生 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。
发行包为按系统和 CPU 构建的原生 wheel，不发布核心实现源码或 sdist；必要的宿主接入脚本随包提供。
目标平台需要有对应 wheel；安装 igrep 核心无需 Nuitka 或 C 编译器，第三方依赖仍按各自的平台支持安装。
Linux amd64 发行包使用 manylinux / glibc，不覆盖 Alpine / musl。

推荐使用隔离的 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_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。`igrep index build` 一步完成：

```bash
igrep index build ~/Documents          # 转换后立即可搜；图片描述交给 igrep serve 后台完成（需 `igrep project add`）
igrep index build ~/Documents --full   # 同时在本进程完成 OCR/VLM 图片描述再返回
igrep prepare --only augment ~/Documents    # 单阶段：只生成图片描述 sidecar
```

转换和增强把 `.igrep.md`、`.igrep.images/` 和 `.igrep.vision.md` 产物写进源文件所在目录的隐藏容器 `.igrep.d/`（每个目录一个；需要时把 `.igrep.d/` 加进 `.gitignore`），不修改用户原始 Markdown。之后仍用普通的 `igrep search` 查询。

## 可选词法索引

`igrep index build` 默认在准备文档之后构建持久化词法 store 和全部词元统计（TF/DF/IDF），增量构建自动更新。普通本地搜索默认使用 rg；开启词法后端并由 `igrep serve` 维护新鲜度时，索引可为 rg 提名文件：

```bash
igrep index build .
igrep index status .
igrep index terms . --term retrieval --json
```

fast 稀疏扩词为实验选项，默认关闭。配置 `IGREP_SPARSE_URL`、`IGREP_SPARSE_MODEL` 与
`IGREP_SPARSE_TOKENIZER_PATH`，并设 `IGREP_FAST_SPARSE_EXPANSION=1`，可结合新鲜索引的统计筛选扩词。

命令边界见 [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 + 会话压缩 / 召回 | `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 时不会自动覆盖。

Claude Code 和 Codex 默认使用窄的 `code` toolset，只包含：

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

其余 MCP 宿主默认 `agent` toolset，在同一个 `semantic_search` 之上按配置追加
web 与 isearch；另有 `repo` 可显式选择。igrep 不提供符号 / LSP 导航：按名字查定义和
引用用宿主的 `rg`，按光标的语义导航用宿主原生 LSP。安装、体检和回报流程见
[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 open     # 在浏览器中打开 Web UI
igrep serve status
igrep serve stop
```

默认本机 Web UI 直接访问 `http://127.0.0.1:16800`，无需 token。对外监听时，Web UI 用 `igrep serve open` 登录；对外管理请求与 `/v1/*` 客户端仍使用 `~/.igreprc/control-token`（首次启动生成，仅属主可读）。`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_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
