godot-rag 4.7.0.post12

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

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

# 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

# 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

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

# JSON output
godot-rag addons --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

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

{
  "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

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

# JSON output
godot-rag stats --json

Diagnostics

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

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:

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:

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

Compare against the reviewed baseline:

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

# 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

# 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

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

# 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

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

使用方法

按类型搜索

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

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

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

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

# JSON 输出
godot-rag addons --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

# 调试搜索元数据（显示搜索模式、向量可用性、回退原因）
godot-rag s-class "Node.add_child" --debug-search
godot-rag s-class "Node.add_child" --debug-search --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（图谱扩展）

数据库统计

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

# JSON 输出
godot-rag stats --json

诊断

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

# JSON 输出
godot-rag diagnostics --json

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

示例

# 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

# 图谱扩展自动补充上下文
$ 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 过滤器：精准搜索

# 不带过滤：结果来自多个 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 发布新版本时：

# 更新 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

开发

uv run pytest -q

许可证

MIT