Metadata-Version: 2.4
Name: godot-rag
Version: 4.7.0.post12
Summary: Hybrid RAG search for Godot documentation
Requires-Python: >=3.10
Requires-Dist: model2vec>=0.8.2
Requires-Dist: sqlite-vec>=0.1.9
Description-Content-Type: text/markdown

# Godot RAG

Hybrid RAG search for Godot documentation and addons. Search by type for precise results.

## Installation

```bash
uv pip install godot-rag
```

Or from wheel:

```bash
uv pip install godot_rag-4.7.0-py3-none-any.whl
```

## Usage

### Search by type

All search commands have long aliases: `search`, `search-class`, `search-tutorial`, `search-engine`, `search-addon`.

```bash
# Search class reference (API docs only)
godot-rag s-class "Node.add_child"
godot-rag s-class "Signal.emit" --limit 3

# Tutorials + getting started guides
godot-rag s-tutorial "how to use signals"
godot-rag s-tutorial "2D pathfinding" --limit 5

# Engine details (architecture, file formats, GDExtension, etc.)
godot-rag s-engine "GDExtension"
godot-rag s-engine "IDE debugging" --limit 3

# Addon docs and examples
godot-rag s-addon "state machine"
godot-rag s-addon "state machine" --addon statecharts
godot-rag s-addon "dialogue" --limit 3

# Search all docs (no type filter)
godot-rag s "Timer"

# Fuzzy symbol matching (camelCase/snake_case/dotted all work)
godot-rag s-class "addChild"          # matches add_child, _add_child
godot-rag s-class "Node.add_child"    # matches Node._add_child
godot-rag s-class "node_add_child"    # matches Node.addChild

# Disable graph expansion (only return direct matches)
godot-rag s-class "add_child" --no-expand
```

### Search addons

```bash
# Search all addon docs, examples, and API summaries
godot-rag s-addon "state machine"
godot-rag s-addon "dialogue balloon"
godot-rag s-addon "scene transition"

# Filter by specific addon
godot-rag s-addon "state" --addon statecharts
godot-rag s-addon "change_scene" --addon scene_manager
godot-rag s-addon "test" --addon gdUnit4

# Find API symbols
godot-rag s-addon "SceneManager" --addon scene_manager
godot-rag s-addon "change_scene" --addon scene_manager
godot-rag s-addon "scene_loaded" --addon scene_manager
godot-rag s-addon "BehaviorTree" --addon limboai
godot-rag s-addon "DialogueManager" --addon dialogue_manager

# Search example code
godot-rag s-addon "ninja_frog" --addon statecharts
godot-rag s-addon "verify_node_path" --addon doctor

# JSON output for AI agents
godot-rag s-addon "state machine" --addon statecharts --json
godot-rag s-addon "change_scene" --json
```

### List addons

```bash
# List all indexed addons with chunk counts
godot-rag addons

# JSON output
godot-rag addons --json
```

### Output format

```bash
# JSON output (for AI Agent)
godot-rag s-class "Vector3.normalized" --json
godot-rag s-addon "change_scene" --addon scene_manager --json

# Limit results
godot-rag s-tutorial "C# Variant" --limit 3

# Debug search metadata (shows search mode, vector availability, fallback reason)
godot-rag s-class "Node.add_child" --debug-search
godot-rag s-class "Node.add_child" --debug-search --json
```

JSON output includes graph relation info:

```json
{
  "score": 100.0,
  "symbol": "Node.add_child",
  "relation_type": "",
  "distance": 0,
  ...
},
{
  "score": 50.0,
  "symbol": "Node",
  "relation_type": "parent",
  "distance": 1,
  ...
}
```

- `relation_type`: `""` (direct match), `"parent"`, `"inherits"`, `"references"`, `"see_also"`
- `distance`: `0` (direct), `1` (graph-expanded)

### Database statistics

```bash
# Show database statistics (chunk counts, symbols, relations)
godot-rag stats

# JSON output
godot-rag stats --json
```

### Diagnostics

```bash
# Validate semantic search readiness (vector embeddings, model availability)
godot-rag diagnostics

# JSON output
godot-rag diagnostics --json

# Skip model availability check
godot-rag diagnostics --no-model
```

## Search Quality Evaluation

Run deterministic evaluator tests during development:

```bash
rtk uv run pytest -q rst2md/tests/test_search_eval.py rst2md/tests/test_search_eval_cli.py
```

Run the real-database gate when `godot_rag.db` is available:

```bash
rtk uv run godot-rag eval-search --db godot_rag.db --baseline docs/search-quality/baseline.json --compare-graph --diagnostic-limit 50
```

Reports include ranking metrics, failed-query diagnostics, and latency summaries.
Use `--p95-latency-threshold-ms` to fail on configured p95 latency regressions.

Write or refresh the reviewed baseline:

```bash
godot-rag eval-search \
  --db godot_rag/rag/godot_docs.sqlite \
  --baseline docs/search-quality/baseline.json \
  --write-baseline
```

Compare against the reviewed baseline:

```bash
godot-rag eval-search \
  --db godot_rag/rag/godot_docs.sqlite \
  --baseline docs/search-quality/baseline.json \
  --compare-graph \
  --diagnostic-limit 50
```

When `--diagnostic-limit` is set, failed queries include diagnostics showing whether expected targets exist in the database and where the best match appears inside the diagnostic window.

Use `--json` for machine-readable reports.

## Examples

```bash
# AI workflow: look up tutorial first, then API details
godot-rag s-tutorial "scene tree" --json
godot-rag s-class "Node.get_children" --json

# AI workflow: check addon docs and examples
godot-rag s-addon "state machine" --addon statecharts --json
godot-rag s-addon "dialogue balloon" --addon dialogue_manager --json

# Quick API lookup
godot-rag s-class "StringName.is_valid_filename"

# Broad search across all docs
godot-rag s "physics interpolation"
```

## RAG vs Non-RAG: Why It Matters

A hybrid RAG system (FTS5 + symbol index + vector semantic search) gives significantly better results than raw text search for AI-assisted documentation lookup. The system uses RRF (Reciprocal Rank Fusion) to combine lexical (FTS5) and semantic (vector) search results.

### Benchmark: Real Query Comparison

Tested on a database of **30,529 chunks** (28,231 Godot docs + 2,298 addon chunks across 9 addons).

| Metric | RAG (this tool) | grep (raw files) | Improvement |
|---|---|---|---|
| **Average latency** | 7.1 ms | 120 ms | **17× faster** |
| **Multi-word queries** | ✅ semantic ranking | ❌ exact match only | — |
| **API symbol lookup** | ✅ O(1) indexed | ❌ linear scan | — |
| **Result ranking** | ✅ BM25 relevance | ❌ no ranking | — |
| **Filters (addon/type)** | ✅ SQL WHERE | ❌ post-process | — |
| **Noise (test/assets)** | ✅ auto-excluded | ❌ manual filter | — |

### Query Hit Rate

| Query | RAG Results | grep Results | Notes |
|---|---|---|---|
| `change_scene` | ✅ 3 hits (12ms) | ✅ 13 files (152ms) | RAG: ranked, deduped |
| `SceneManager` | ✅ 3 hits (12ms) | ✅ 41 files (100ms) | grep: too many noise files |
| `SceneManager.change_scene` | ✅ 1 hit (12ms) | ❌ 0 files | **RAG: precise symbol hit** |
| `BehaviorTree` | ✅ 3 hits (12ms) | ✅ 2 files (96ms) | RAG: includes doc context |
| `DialogueManager` | ✅ 3 hits (13ms) | ✅ 26 files (98ms) | RAG: only relevant docs |
| `state machine transitions` | ✅ 3 hits (13ms) | ❌ 0 files | **grep fails on multi-word** |
| `scene transition animation` | ✅ 2 hits (11.9ms) | ❌ 0 files | **grep fails on multi-word** |
| `input helper gamepad` | ✅ 2 hits (12ms) | ❌ 0 files | **grep fails on multi-word** |
| `input action mapping` | ✅ 3 hits (11ms) | — | RAG finds cross-references |

**Key insight**: grep can only find exact substring matches. RAG handles natural language queries like "state machine transitions" and returns ranked, contextual results.

### Graph Expansion: Contextual Results

When graph expansion is enabled (default), search results are enriched with related chunks:

- **parent**: Searching `add_child` also returns the `Node` class summary
- **inherits**: Searching `Node` also returns `Object` (its parent class)
- **references**: Chunks that mention matched symbols in their text

```bash
# Graph expansion adds context
$ godot-rag s-class "add_child"
  score: 100.0  symbol: Node.add_child        # direct match
  score: 50.0   symbol: Node    relation: parent (distance=1)  # auto-expanded

# Disable for faster, minimal results
$ godot-rag s-class "add_child" --no-expand
  score: 100.0  symbol: Node.add_child        # direct match only
```

### --addon Filter: Precision Search

```bash
# Without filter: results from multiple addons
$ godot-rag s-addon "state machine"
  → statecharts (API), limboai (docs)    # mixed results

# With filter: only target addon
$ godot-rag s-addon "state machine" --addon statecharts
  → statecharts (API, docs, examples)    # precise
```

### Database Coverage

| Addon | Docs | Examples | API | Total |
|---|---|---|---|---|
| dialogue_manager | 140 | 2 | 55 | 197 |
| doctor | 34 | 125 | 41 | 200 |
| gdUnit4 | 1,030 | — | 214 | 1,244 |
| input_helper | 32 | 3 | 6 | 41 |
| limboai | 299 | 27 | — | 326 |
| phantom-camera | 12 | 11 | 38 | 61 |
| scene_manager | 1 | 2 | 5 | 8 |
| sound_manager | 13 | 2 | 7 | 22 |
| statecharts | 80 | 21 | 98 | 199 |
| **Total** | **1,641** | **193** | **464** | **2,298** |

- **addon_doc**: Documentation markdown/RST, split by headings
- **addon_example**: Example .gd/.cs code files
- **addon_api**: Public declarations and doc comments only (not full source)

## Update

When Godot releases a new version:

```bash
# Update godot-docs submodule
cd godot-docs && git pull origin stable

# Rebuild docs and RAG
uv run godot-rag-build build

# Include Scene Manager wiki docs
uv run godot-rag-build build --with-wiki

# Build and publish to PyPI
uv run godot-rag-build publish --target pypi

# Build and publish to TestPyPI
uv run godot-rag-build publish --target testpypi

# Release database diagnostics
uv run godot-rag-build diagnostics

# Clean build cache
uv run godot-rag-build clean-cache

# Legacy wrapper still works:
./build.sh
```

## Development

```bash
uv run pytest -q
```

## License

MIT

---

Godot 文档与 addon 的混合 RAG 搜索。按类型搜索，精准命中。

## 安装

```bash
uv pip install godot-rag
```

或从 wheel 安装：

```bash
uv pip install godot_rag-4.7.0-py3-none-any.whl
```

## 使用方法

### 按类型搜索

所有搜索命令都有长别名：`search`、`search-class`、`search-tutorial`、`search-engine`、`search-addon`。

```bash
# 搜索类参考（仅 API 文档）
godot-rag s-class "Node.add_child"
godot-rag s-class "Signal.emit" --limit 3

# 搜索教程（教程 + 入门指南）
godot-rag s-tutorial "how to use signals"
godot-rag s-tutorial "2D pathfinding" --limit 5

# 搜索引擎细节（架构、文件格式、GDExtension 等）
godot-rag s-engine "GDExtension"
godot-rag s-engine "IDE debugging" --limit 3

# 搜索 addon 文档和示例
godot-rag s-addon "state machine"
godot-rag s-addon "state machine" --addon statecharts
godot-rag s-addon "dialogue" --limit 3

# 搜索全部文档（无类型过滤）
godot-rag s "Timer"

# 模糊符号匹配（camelCase/snake_case/带点号 都能匹配）
godot-rag s-class "addChild"          # 匹配 add_child, _add_child
godot-rag s-class "Node.add_child"    # 匹配 Node._add_child
godot-rag s-class "node_add_child"    # 匹配 Node.addChild

# 禁用图谱扩展（仅返回直接匹配结果）
godot-rag s-class "add_child" --no-expand
```

### 搜索 addon

```bash
# 搜索所有 addon 文档、示例和 API 摘要
godot-rag s-addon "state machine"
godot-rag s-addon "dialogue balloon"
godot-rag s-addon "scene transition"

# 按指定 addon 过滤
godot-rag s-addon "state" --addon statecharts
godot-rag s-addon "change_scene" --addon scene_manager
godot-rag s-addon "test" --addon gdUnit4

# 查找 API 符号
godot-rag s-addon "SceneManager" --addon scene_manager
godot-rag s-addon "change_scene" --addon scene_manager
godot-rag s-addon "scene_loaded" --addon scene_manager
godot-rag s-addon "BehaviorTree" --addon limboai
godot-rag s-addon "DialogueManager" --addon dialogue_manager

# 搜索示例代码
godot-rag s-addon "ninja_frog" --addon statecharts
godot-rag s-addon "verify_node_path" --addon doctor

# JSON 输出（供 AI agent 使用）
godot-rag s-addon "state machine" --addon statecharts --json
godot-rag s-addon "change_scene" --json
```

### 列出 addon

```bash
# 列出所有已索引的 addon 及 chunk 数量
godot-rag addons

# JSON 输出
godot-rag addons --json
```

### 输出格式

```bash
# JSON 输出（供 AI Agent 使用）
godot-rag s-class "Vector3.normalized" --json
godot-rag s-addon "change_scene" --addon scene_manager --json

# 限制结果数量
godot-rag s-tutorial "C# Variant" --limit 3

# 调试搜索元数据（显示搜索模式、向量可用性、回退原因）
godot-rag s-class "Node.add_child" --debug-search
godot-rag s-class "Node.add_child" --debug-search --json
```

JSON 输出包含图谱关系信息：

```json
{
  "score": 100.0,
  "symbol": "Node.add_child",
  "relation_type": "",
  "distance": 0,
  ...
},
{
  "score": 50.0,
  "symbol": "Node",
  "relation_type": "parent",
  "distance": 1,
  ...
}
```

- `relation_type`：`""`（直接匹配）、`"parent"`、`"inherits"`、`"references"`、`"see_also"`
- `distance`：`0`（直接）、`1`（图谱扩展）

### 数据库统计

```bash
# 显示数据库统计信息（chunk 数量、符号、关系）
godot-rag stats

# JSON 输出
godot-rag stats --json
```

### 诊断

```bash
# 验证语义搜索就绪状态（向量嵌入、模型可用性）
godot-rag diagnostics

# JSON 输出
godot-rag diagnostics --json

# 跳过模型可用性检查
godot-rag diagnostics --no-model
```

## 示例

```bash
# AI 工作流：先查教程，再查 API 细节
godot-rag s-tutorial "scene tree" --json
godot-rag s-class "Node.get_children" --json

# AI 工作流：查看 addon 文档和示例
godot-rag s-addon "state machine" --addon statecharts --json
godot-rag s-addon "dialogue balloon" --addon dialogue_manager --json

# 快速 API 查询
godot-rag s-class "StringName.is_valid_filename"

# 跨全部文档的宽泛搜索
godot-rag s "physics interpolation"
```

## RAG vs 非 RAG：为什么重要

混合 RAG 系统（FTS5 + 符号索引 + 向量语义搜索）在 AI 辅助文档查询中，比原始文本搜索有显著优势。系统使用 RRF（互惠排名融合）来组合词法（FTS5）和语义（向量）搜索结果。

### 基准测试：真实查询对比

测试数据库：**30,529 个 chunk**（28,231 个 Godot 文档 + 2,298 个 addon chunk，覆盖 9 个 addon）。

| 指标 | RAG（本工具） | grep（原始文件） | 提升 |
|---|---|---|---|
| **平均延迟** | 7.1 ms | 120 ms | **快 17 倍** |
| **多词查询** | ✅ 语义排序 | ❌ 仅精确匹配 | — |
| **API 符号查找** | ✅ O(1) 索引 | ❌ 线性扫描 | — |
| **结果排序** | ✅ BM25 相关性 | ❌ 无排序 | — |
| **过滤（addon/类型）** | ✅ SQL WHERE | ❌ 后处理 | — |
| **噪音（test/assets）** | ✅ 自动排除 | ❌ 手动过滤 | — |

### 查询命中率

| 查询 | RAG 结果 | grep 结果 | 备注 |
|---|---|---|---|
| `change_scene` | ✅ 3 命中 (12ms) | ✅ 13 文件 (152ms) | RAG：排序去重 |
| `SceneManager` | ✅ 3 命中 (12ms) | ✅ 41 文件 (100ms) | grep：噪音太多 |
| `SceneManager.change_scene` | ✅ 1 命中 (12ms) | ❌ 0 文件 | **RAG：精确符号命中** |
| `BehaviorTree` | ✅ 3 命中 (12ms) | ✅ 2 文件 (96ms) | RAG：包含文档上下文 |
| `DialogueManager` | ✅ 3 命中 (13ms) | ✅ 26 文件 (98ms) | RAG：仅相关文档 |
| `state machine transitions` | ✅ 3 命中 (13ms) | ❌ 0 文件 | **grep 无法处理多词** |
| `scene transition animation` | ✅ 2 命中 (11.9ms) | ❌ 0 文件 | **grep 无法处理多词** |
| `input helper gamepad` | ✅ 2 命中 (12ms) | ❌ 0 文件 | **grep 无法处理多词** |
| `input action mapping` | ✅ 3 命中 (11ms) | — | RAG 发现交叉引用 |

**核心洞察**：grep 只能做精确子串匹配。RAG 能处理自然语言查询（如 "state machine transitions"），并返回排序后的上下文结果。

### 图谱扩展：上下文关联

启用图谱扩展（默认开启）时，搜索结果会自动关联相关 chunk：

- **parent**：搜索 `add_child` 会同时返回 `Node` 类摘要
- **inherits**：搜索 `Node` 会同时返回 `Object`（其父类）
- **references**：文本中提及匹配符号的 chunk

```bash
# 图谱扩展自动补充上下文
$ godot-rag s-class "add_child"
  score: 100.0  symbol: Node.add_child        # 直接匹配
  score: 50.0   symbol: Node    relation: parent (distance=1)  # 自动扩展

# 禁用以获得更快、更精简的结果
$ godot-rag s-class "add_child" --no-expand
  score: 100.0  symbol: Node.add_child        # 仅直接匹配
```

### --addon 过滤器：精准搜索

```bash
# 不带过滤：结果来自多个 addon
$ godot-rag s-addon "state machine"
  → statecharts (API), limboai (docs)    # 混合结果

# 带过滤：仅目标 addon
$ godot-rag s-addon "state machine" --addon statecharts
  → statecharts (API, docs, examples)    # 精准
```

### 数据库覆盖

| Addon | 文档 | 示例 | API | 总计 |
|---|---|---|---|---|
| dialogue_manager | 140 | 2 | 55 | 197 |
| doctor | 34 | 125 | 41 | 200 |
| gdUnit4 | 1,030 | — | 214 | 1,244 |
| input_helper | 32 | 3 | 6 | 41 |
| limboai | 299 | 27 | — | 326 |
| phantom-camera | 12 | 11 | 38 | 61 |
| scene_manager | 1 | 2 | 5 | 8 |
| sound_manager | 13 | 2 | 7 | 22 |
| statecharts | 80 | 21 | 98 | 199 |
| **总计** | **1,641** | **193** | **464** | **2,298** |

- **addon_doc**：文档 markdown/RST，按标题分段
- **addon_example**：示例 .gd/.cs 代码文件
- **addon_api**：仅公开声明和文档注释（非完整源码）

## 更新

当 Godot 发布新版本时：

```bash
# 更新 godot-docs 子模块
cd godot-docs && git pull origin stable

# 重建文档和 RAG
uv run godot-rag-build build

# 纳入 Scene Manager wiki 文档
uv run godot-rag-build build --with-wiki

# 构建并发布到 PyPI
uv run godot-rag-build publish --target pypi

# 构建并发布到 TestPyPI
uv run godot-rag-build publish --target testpypi

# 发布数据库诊断
uv run godot-rag-build diagnostics

# 清理构建缓存
uv run godot-rag-build clean-cache

# 兼容入口仍可使用：
./build.sh
```

## 开发

```bash
uv run pytest -q
```

## 许可证

MIT
