Metadata-Version: 2.4
Name: godot-rag
Version: 4.7.0.post13
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

> **Language note**: Queries must be in English. For non-English queries, translate to English first (e.g., "怎么做二段跳" → "how to double jump"). The embedding model is English-only.

### Search by type

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

**Default behavior**: `s`, `s-class`, `s-tutorial`, `s-engine` exclude addon results. Use `s-addon` to search addons.

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

# class.method queries work — finds the class
godot-rag s-class "ResourceLoader.load"

# Tutorials + getting started guides
godot-rag s-tutorial "how to use signals"

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

# Addon docs and examples (must use s-addon)
godot-rag s-addon "state machine"
godot-rag s-addon "state machine" --addon statecharts

# Search all docs (no type filter, excludes addons)
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

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

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

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

### List addons

```bash
godot-rag addons
godot-rag addons --json
```

### Output format

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

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

# Debug search metadata
godot-rag s-class "Node.add_child" --debug-search
```

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

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

## 使用方法

> **语言说明**：查询必须使用英文。非英文查询请先翻译为英文（例如："怎么做二段跳" → "how to double jump"）。Embedding 模型仅支持英文。

### 按类型搜索

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

**默认行为**：`s`、`s-class`、`s-tutorial`、`s-engine` 排除 addon 结果。使用 `s-addon` 搜索 addon。

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

# class.method 查询可用 — 自动找到类
godot-rag s-class "ResourceLoader.load"

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

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

# 搜索 addon 文档和示例（必须使用 s-addon）
godot-rag s-addon "state machine"
godot-rag s-addon "state machine" --addon statecharts

# 搜索全部文档（无类型过滤，排除 addon）
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 "add_child" --no-expand
```

### 搜索 addon

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

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

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

### 列出 addon

```bash
godot-rag addons
godot-rag addons --json
```

### 输出格式

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

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

# 调试搜索元数据
godot-rag s-class "Node.add_child" --debug-search
```

## 更新

当 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
```

## 开发

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

## 许可证

MIT
