godot-rag 4.7.0.post5

Hybrid RAG search for Godot documentation

Godot RAG

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

Installation

uv pip install godot-rag

Or from wheel:

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

Usage

Search by type

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

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

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

# Search 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"

Search addons

# 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

Output format

# 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

Examples

# 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) gives significantly better results than raw text search for AI-assisted documentation lookup.

Benchmark: Real Query Comparison

Tested on a database of 30,631 chunks (28,235 Godot docs + 2,396 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	✅ 3 hits (12ms)	❌ 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.

--addon Filter: Precision Search

# 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	351	27	—	378
phantom-camera	12	11	38	61
scene_manager	47	2	5	54
sound_manager	13	2	7	22
statecharts	80	21	98	199
Total	1,739	193	464	2,396

• 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:

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

# Rebuild docs and RAG
./build.sh

# Or manually:
PYTHONPATH=rst2md uv run python3 rst2md/rst2md_batch.py -i godot-docs -o godot_rag/docs-md
PYTHONPATH=rst2md uv run python3 -m rag.cli build --docs godot_rag/docs-md --db godot_rag/rag/godot_docs.sqlite --addons addons
uv build --wheel

Development

uv run pytest -q

License

MIT

---

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

安装

uv pip install godot-rag

或从 wheel 安装：

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

使用方法

按类型搜索

# 搜索类参考（仅 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"

搜索 addon

# 搜索所有 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

输出格式

# 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

示例

# 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 辅助文档查询中，比原始文本搜索有显著优势。

基准测试：真实查询对比

测试数据库：30,631 个 chunk（28,235 个 Godot 文档 + 2,396 个 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	✅ 3 命中 (12ms)	❌ 0 文件	grep 无法处理多词
input helper gamepad	✅ 2 命中 (12ms)	❌ 0 文件	grep 无法处理多词
input action mapping	✅ 3 命中 (11ms)	—	RAG 发现交叉引用

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

--addon 过滤器：精准搜索

# 不带过滤：结果来自多个 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	351	27	—	378
phantom-camera	12	11	38	61
scene_manager	47	2	5	54
sound_manager	13	2	7	22
statecharts	80	21	98	199
总计	1,739	193	464	2,396

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

更新

当 Godot 发布新版本时：

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

# 重建文档和 RAG
./build.sh

# 或手动执行：
PYTHONPATH=rst2md uv run python3 rst2md/rst2md_batch.py -i godot-docs -o godot_rag/docs-md
PYTHONPATH=rst2md uv run python3 -m rag.cli build --docs godot_rag/docs-md --db godot_rag/rag/godot_docs.sqlite --addons addons
uv build --wheel

开发

uv run pytest -q

许可证

MIT