deeprepo

DeepRepo — コードベース向けローカル RAG エンジン

ローカルのコードベースで RAG（検索拡張生成）を実行するための、本番環境向け Python ライブラリです。重いフレームワークも、外部ベクトルデータベースも、クラウドも必要ありません。

機能

DeepRepo はコードベースを取り込み、次の 3 つを同時に構築します。

レイヤー	保存内容	用途
コードナレッジグラフ	クラス、関数、インポート、呼び出しエッジ（SQLite）	シンボル検索、影響範囲分析
埋め込みベクトル + FTS インデックス	セマンティックベクトル + 全文検索	関連コードの検索
階層型 Wiki	モジュールごとの平易な英語の .md ファイル	AI による説明、チャットのコンテキスト

スマートなクエリルーターがすべての質問を分類し、最も低コストのコンテキスト戦略を選択するため、単純な RAG と比べて LLM のトークン使用量を 5～50 倍削減できます。

---

特長

• 重いフレームワークへの依存ゼロ — 純粋な Python、SQLite を基盤としています
• 複数の AI プロバイダー — Ollama（無料／ローカル）、OpenAI、Anthropic、Gemini、HuggingFace
• CLI ファースト — deeprepo ingest . / deeprepo serve / deeprepo query "…"
• Wiki ビューアー — ページ内チャット付きの閲覧・検索可能な HTML Wiki（deeprepo serve）
• 用途を絞った 7 つの MCP ツール — DeepRepo を Cursor / Claude Desktop に MCP サーバーとして追加できます
• ブランチ分離 — ベースブランチからコピーオンライトで作成する、ブランチごとの SQLite データベース
• 3 段階の検索 — Embeddings → FTS → Graph の順でフォールバックする、堅牢な検索
• 差分取り込み — 変更のないファイルはスキップし、差分のみを再処理します

---

クイックスタート

1. インストール

cd deeprepo_core
pip install -e .

MCP サーバーのサポートを有効にする場合：

pip install -e ".[mcp]"

2. Ollama をインストール（無料、ローカル — 推奨）

# macOS
brew install ollama
ollama serve                          # keep this running

ollama pull nomic-embed-text          # embedding model
ollama pull llama3.1:8b               # LLM

3. コードベースを取り込む

cd /path/to/your/project
deeprepo ingest .

4. Wiki を閲覧する

deeprepo serve                        # opens http://localhost:8080

5. 質問する

deeprepo query "how does authentication work?"
deeprepo query "what breaks if I change auth.py?"

---

CLI リファレンス

deeprepo <command> [options]

コマンド	機能
deeprepo init	プロバイダーの設定を検出し、取り込みコマンドを表示します
deeprepo ingest [PATH]	リポジトリをスキャンし、グラフ + Wiki + 埋め込みベクトルを構築します
deeprepo wiki [PATH]	再インデックスを省略し、Wiki ページのみを再生成します
deeprepo serve	ポート 8080 で Wiki ビューアーとページ内チャットを起動します
deeprepo query "QUESTION"	質問をして、AI の回答を取得します
deeprepo status	ブランチの分離状況とキャッシュの最新状態を表示します

共通フラグ（すべてのコマンド）

--llm ollama|openai|anthropic|gemini|huggingface   # LLM provider
--embed ollama|openai|huggingface                  # embedding provider (default: same as --llm)
--branch-isolation                                 # enable per-branch databases
--base-branch main                                 # seed feature-branch cache from main
--wiki-dir .deeprepo/wiki                          # override wiki output directory

ingest のフラグ

--chunk-size N      # chars per text chunk (default: 1000)
--overlap N         # overlap between chunks (default: 100)
--workers N         # wiki parallel workers (default: 3)
--no-wiki           # skip wiki generation

serve のフラグ

--port N            # HTTP port (default: 8080)

使用例

# Ollama (free, fully local)
deeprepo ingest .

# OpenAI embeddings + Anthropic LLM
deeprepo ingest . --embed openai --llm anthropic

# Branch isolation for a feature branch
deeprepo ingest . --branch-isolation --base-branch main

# Serve wiki with chat on a custom port
deeprepo serve --llm openai --port 9000

# Query with specific top-k results
deeprepo query "where is AuthService defined?" --top-k 3

---

Python API

from deeprepo import DeepRepoClient

# Single provider (backward-compatible shorthand)
client = DeepRepoClient(provider_name="ollama")

# Split providers — Anthropic LLM + OpenAI embeddings
client = DeepRepoClient(
    embedding_provider_name="openai",
    llm_provider_name="anthropic",
)

# Branch isolation (team workflow)
client = DeepRepoClient(
    provider_name="ollama",
    branch_isolation=True,
    base_branches=["main"],
)

# Ingest (incremental — unchanged files are skipped)
result = client.ingest("/path/to/your/code")
print(f"Files: {result['files_scanned']}, Wiki pages: {result['wiki_generated']}")

# Query — smart routing selects the cheapest context strategy
response = client.query("How does authentication work?")
print(response['answer'])
print(f"Intent: {response['intent']}, Strategy: {response['strategy']}")
print(f"Sources: {response['sources']}")        # list of file paths

# Browse the generated wiki
print(f"Wiki at: {client.get_wiki_dir()}")

query() の戻り値の形式

{
    "answer":         str,           # LLM-generated answer
    "sources":        list[str],     # file paths used as context
    "intent":         str,           # navigate | impact | explain | debug | review | general
    "strategy":       str,           # e.g. symbol_lookup, blast_radius, wiki_plus_skeleton, …
    "retrieval":      str,           # embeddings | fts | graph
    "token_estimate": int,           # estimated tokens consumed
    "history":        list[dict],    # conversation history (last N exchanges)
}

---

対応 AI プロバイダー

プロバイダー	費用	設定	最適な用途
Ollama	無料、無制限	アプリをインストール + ollama pull	ローカル開発、プライバシー、オフライン利用
OpenAI	有料	OPENAI_API_KEY	本番環境、最高の品質
Anthropic	有料	ANTHROPIC_API_KEY	本番環境、優れた推論能力
Gemini	無料枠あり	GEMINI_API_KEY	実験
HuggingFace	無料枠あり	HUGGINGFACE_API_KEY	クラウドでの埋め込み処理、GPU 不要

注： Anthropic には埋め込み API がありません。別のプロバイダーと組み合わせてください。

client = DeepRepoClient(embedding_provider_name="openai", llm_provider_name="anthropic")

---

アーキテクチャ

deeprepo_core/src/deeprepo/
├── client.py         # Main facade — branch isolation, freshness, provider wiring
├── graph.py          # SQLite store: graph nodes/edges, embeddings, wiki index, state
├── graph_builder.py  # Tree-sitter AST parser → code knowledge graph
├── wiki.py           # Hierarchical wiki engine — bottom-up LLM synthesis
├── router.py         # Intent classifier + 6 context strategy selectors
├── ingestion.py      # File scanner, chunker, language detection
├── interfaces.py     # Abstract base classes (EmbeddingProvider, LLMProvider)
├── registry.py       # @register_embedding / @register_llm decorator system
├── ui.py             # Wiki viewer (HTTP server + mermaid renderer + chat)
├── mcp/
│   └── server.py     # 7 MCP tools for AI assistants (Cursor, Claude Desktop)
└── providers/
    ├── ollama_v.py
    ├── openai_v.py
    ├── anthropic_v.py
    ├── gemini_v.py
    └── huggingface_v.py

.deeprepo/            # Generated (gitignore this)
├── default.db        # SQLite: graph + embeddings + wiki index + state
├── <branch>.db       # Per-branch database when branch_isolation=True
└── wiki/             # Browsable .md wiki files
    ├── overview.md   # Whole-repo narrative overview
    └── *.md          # One page per module

ストレージ

すべてのデータはブランチごとの単一の SQLite ファイルに保存されます。Redis、Postgres、Chroma は不要です。

テーブル	内容
nodes	メタデータ付きのファイル、クラス、関数
edges	ノード間のインポート／呼び出し関係
embeddings	セマンティック検索用の浮動小数点ベクトル
wiki_pages	生成された Wiki の Markdown（キー → コンテンツ）
wiki_fts	Wiki の全文検索インデックス
state	差分更新用のファイルごとの SHA-256 ハッシュ

設計パターン

• ファサード — DeepRepoClient を単一のエントリーポイントとし、内部構造を隠します
• ストラテジー — LLMProvider ／ EmbeddingProvider の抽象インターフェースを使用し、プロバイダーを切り替えられます
• レジストリー — @register_llm("ollama") デコレーターにより、インポート時にプロバイダーが自動登録されます
• ボトムアップ合成 — Wiki ページを末端から生成し、親ページでは子ページの要約を利用します
• 3 段階フォールバック — 埋め込み → FTS → グラフの順にフォールバックします。埋め込みが未準備でもクエリを実行できます
• コピーオンライト分岐 — フィーチャーブランチはベースブランチのキャッシュから開始し、その後差分を更新します

---

MCP サーバー（AI アシスタントとの連携）

DeepRepo を MCP サーバーとして接続すると、Cursor、Claude Desktop、または MCP 対応の AI アシスタントから、元のファイルを直接読み込むことなく呼び出せます。

セットアップ

pip install deeprepo[mcp]

Cursor — ~/.cursor/mcp.json を作成します：

{
  "mcpServers": {
    "deeprepo": {
      "command": "python",
      "args": ["-m", "deeprepo.mcp.server"],
      "env": {
        "LLM_PROVIDER": "ollama"
      }
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "deeprepo": {
      "command": "deeprepo-mcp",
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "LLM_PROVIDER": "anthropic",
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

利用可能な MCP ツール（7 つ）

ツール	使用する場面	トークンコスト
ingest_codebase	初回セットアップ — リポジトリのディレクトリをインデックス化する	—
find_symbol	「X の定義場所／X が何行目にあるか」	約 50 トークン
get_file_structure	「X の API ／関数を表示する」	約 150 トークン
explain_file	「X の仕組み／X の説明／X が何をするか」	約 300 トークン
find_change_impact	「X を変更したら何が壊れるか」	約 300 トークン
ask_codebase	コードに関するあらゆる自由形式の質問	約 600～2000 トークン
get_project_overview	「概要を教えて／このプロジェクトは何をするのか」	約 600 トークン

単純な RAG と比較したトークン削減量

クエリの種類	単純な RAG	DeepRepo	削減量
「X の定義場所はどこか」	約 4 000 トークン	約 80 トークン	50 倍
「X を変更したら何が壊れるか」	約 4 000 トークン	約 300 トークン	13 倍
「X はどのように動作するか」	約 4 000 トークン	約 600 トークン	7 倍
「X のバグを修正する」	約 4 000 トークン	約 900 トークン	4 倍

CLAUDE.md のヒント

Claude が DeepRepo を自動的に使用するよう、プロジェクトの CLAUDE.md に次の内容を追加します：

## Code navigation
Before reading any source file directly, use these MCP tools:
- `find_symbol(name)` to locate a class or function
- `get_file_structure(filepath)` to see a file's API without reading it
- `explain_file(filepath)` to understand what a file does
- `find_change_impact(filepath)` before editing any file
- `ask_codebase(question)` for open-ended questions
- `get_project_overview()` at the start of a new session

Only call Read/Grep on a file after the above tools have been tried.

---

設定

環境変数

変数	デフォルト値	説明
LLM_PROVIDER	openai	LLM プロバイダー名
EMBEDDING_PROVIDER	LLM_PROVIDER と同じ	埋め込みプロバイダー名
OPENAI_API_KEY	—	OpenAI に必要
ANTHROPIC_API_KEY	—	Anthropic に必要
GEMINI_API_KEY	—	Gemini に必要
HUGGINGFACE_API_KEY / HF_TOKEN	—	HuggingFace に必要
OLLAMA_MODEL	llama3.1:8b	Ollama の LLM モデル名
OLLAMA_EMBED_MODEL	nomic-embed-text	Ollama の埋め込みモデル
OLLAMA_BASE_URL	http://localhost:11434	Ollama サーバーの URL
OLLAMA_TIMEOUT	300	LLM の応答タイムアウト（秒）

---

テスト

# Full end-to-end test suite (runs ingest + all checks)
python3 test_deeprepo_flow.py

# Skip ingest, use cached index (faster iteration)
python3 test_deeprepo_flow.py --skip-ingest

# pytest unit tests
pytest tests/unit/ -v

# pytest with coverage
pytest tests/unit/ --cov=deeprepo --cov-report=html

test_deeprepo_flow.py スクリプトでは、7 つのセクションすべてをエンドツーエンドでテストします：

1. クライアントの初期化とブランチフラグ
2. 取り込み（グラフ + 埋め込み + Wiki）
3. WikiEngine — ページ生成、キャッシュ、リポジトリの概要
4. Graph API — スケルトン、影響範囲、シンボル検索
5. RAG ／ Router — インテント分類、クエリ実行
6. CLI コマンド — すべてのサブコマンドとヘルプ
7. ブランチ分離フラグの組み合わせ

---

新しいプロバイダーの追加

1. src/deeprepo/providers/myprovider.py を作成します
2. EmbeddingProvider および／または LLMProvider のインターフェースを実装します
3. @register_embedding("myprovider") ／ @register_llm("myprovider") を付けます
4. インポート時に自動検出されるため、ほかに変更は不要です

from deeprepo.interfaces import EmbeddingProvider, LLMProvider
from deeprepo.registry import register_embedding, register_llm

@register_embedding("myprovider")
class MyEmbeddingProvider(EmbeddingProvider):
    def embed(self, text: str) -> list[float]:
        ...  # return a list of floats

@register_llm("myprovider")
class MyLLMProvider(LLMProvider):
    def generate(self, prompt: str, context: str | None = None) -> str:
        ...  # return generated text

---

ドキュメント

• DEVELOPER_WORKFLOW_GUIDE.md — 日々の開発ワークフローと自動化のレシピ
• deeprepo_core/README.md — パッケージの README（PyPI）
• docs/high-level-design.excalidraw — プロセスフロー図
• docs/class-interaction-design.excalidraw — クラス図

---

ライセンス

MIT License — 詳細は LICENSE ファイルをご覧ください。

---

RAG パイプラインを完全に制御したい開発者のために作られています。