semtools

Semtools：セマンティック検索

埋め込みベースの類似度マッチングを使って、コードやドキュメントを意味に基づいて検索します。

目的

semtools スキルでは、セマンティック検索とドキュメント処理に対応した、高性能な Rust ベースの CLI である Semtools を利用できます。完全一致する文字列を検索する従来のテキスト検索（ripgrep）や、構文パターンを検索する構造検索（ast-grep）とは異なり、semtools は埋め込みを通じて意味を理解します。

主な機能：

1. セマンティック検索：キーワードだけでなく、意味に基づいてコードやテキストを検索します
2. ワークスペース管理：大規模なコードベースにインデックスを作成し、繰り返しの検索を高速化します
3. ドキュメント解析：PDF、DOCX、PPTX を検索可能なテキストに変換します（API キーが必要です）

semtools は発見に優れており、正確なキーワード、関数名、構文パターンがわからなくても、関連するコードを見つけられます。

このスキルを使う場面

意味に基づく検索が必要な場合は、semtools スキルを使います。

セマンティックなコードの発見：

• 概念を実装するコード（「エラーハンドリング」「データ検証」など）を見つける
• 異なるモジュール間で類似した機能を見つける
• 正確な名前がわからないパターンの例を探す
• すべてを読まずに、コードの動作を理解する

ドキュメントと知識：

• キーワードではなく概念でドキュメントを検索する
• コメントやドキュメント内の関連する議論を見つける
• 類似する問題や解決策を見つける
• 技術文書（PDF、レポート）を分析する

ユースケース：

• 「認証関連のコードをすべて見つけて」（関数名がわからなくても検索できます）
• 「エラーハンドリングのパターンを見せて」（具体的なエラーの種類を問わず検索できます）
• 「この実装に似たコードを見つけて」（セマンティックな類似性で検索できます）
• 「『distributed consensus』についての研究論文を検索して」（ドキュメント検索）

次の場合は file-search（ripgrep/ast-grep）より semtools を選びます：

• 概念はわかっているものの、キーワードがわからない
• 完全一致検索では関連する結果を見逃してしまう
• 完全一致ではなく、意味的に類似するコードを探したい
• 言語をまたいだ検索や、異なる種類のコンテンツが混在する検索を行う

次の場合は引き続き file-search を使います：

• 正確なキーワード、関数名、パターンがわかっている
• 構造に基づくコード検索が必要（ast-grep）
• 速度が重要（完全一致検索では ripgrep の方が高速です）
• 特定のシンボルや参照を検索する

利用可能なコマンド

Semtools には、execute_command 経由で使用できる 3 つの CLI コマンドがあります。

• search - コードやテキストファイルをセマンティック検索します
• workspace - 埋め込みをキャッシュするワークスペースを管理します
• parse - ドキュメント（PDF、DOCX、PPTX）を検索可能なテキストに変換します

すべてのコマンドは、実行環境ですぐに使用できます。 ドキュメントの解析には、LLAMA_CLOUD_API_KEY 環境変数の設定が必要です。

主な操作

1. セマンティック検索（search）

意味に基づいてファイルやコードセクションを見つけます。

# Basic semantic search
search "authentication logic" src/

# Search with more context (5 lines before/after)
search "error handling" --n-lines 5 src/

# Get more results (default: 3)
search "database queries" --top-k 10 src/

# Control similarity threshold (0.0-1.0, lower = more lenient)
search "API endpoints" --max-distance 0.4 src/

パラメーター：

• --n-lines N：一致箇所の前後に表示するコンテキスト行数（デフォルト：3）
• --top-k K：類似度が高い上位 K 件の一致を返します（デフォルト：3）
• --max-distance D：埋め込みの最大距離（0.0～1.0、デフォルト：0.3）
• -i：大文字と小文字を区別しない検索

出力形式：

Match 1 (similarity: 0.12)
File: src/auth/handlers.py
Lines: 42-47
----
def authenticate_user(username: str, password: str) -> Optional[User]:
    """Authenticate user credentials against database."""
    user = get_user_by_username(username)
    if user and verify_password(password, user.password_hash):
        return user
    return None
----

Match 2 (similarity: 0.18)
File: src/middleware/auth.py
...

2. ワークスペース管理（workspace）

大規模なコードベースでは、ワークスペースを作成して埋め込みをキャッシュすると、繰り返しの検索を高速化できます。

# Create/activate workspace
workspace use my-project

# Set workspace via environment variable
export SEMTOOLS_WORKSPACE=my-project

# Index files in workspace (workspace auto-detected from env var)
search "query" src/

# Check workspace status
workspace status

# Clean up old workspaces
workspace prune

利点：

• 繰り返しの検索を高速化：埋め込みがキャッシュされるため、再計算は不要です
• 大規模なコードベースに対応：スケーラビリティを高める IVF_PQ インデックスを利用します
• セッションを保持：複数回の検索にわたってコンテキストを維持します

ワークスペースを使う場面：

• 同じコードベースを複数回検索する
• 非常に大規模なプロジェクト（ファイル数が 1000 以上）
• 対話形式で探索するセッション
• 検索を繰り返す CI/CD パイプライン

3. ドキュメント解析（parse）⚠️ API キーが必要です

ドキュメントを検索可能な Markdown に変換します（LlamaParse API キーが必要です）。

# Parse PDFs to markdown
parse research_papers/*.pdf

# Parse Word documents
parse reports/*.docx

# Parse presentations
parse slides/*.pptx

# Parse and pipe to search
parse docs/*.pdf | xargs search "neural networks"

対応形式：

• PDF（.pdf）
• Word（.docx）
• PowerPoint（.pptx）

設定：

# Via environment variable
export LLAMA_CLOUD_API_KEY="llx-..."

# Via config file
cat > ~/.parse_config.json << EOF
{
  "api_key": "llx-...",
  "max_concurrent_requests": 10,
  "timeout_seconds": 3600
}
EOF

重要： ドキュメント解析は任意です。解析を行わなくても、セマンティック検索は利用できます。

ワークフローパターン

パターン 1：概念の発見

探しているものの概念はわかっていても、名前がわからない場合：

# Step 1: Broad semantic search
search "rate limiting implementation" src/

# Step 2: Review results, refine query
search "throttle requests per user" src/ --top-k 10

# Step 3: Use ripgrep for exact follow-up
rg "RateLimiter" --type py src/

パターン 2：類似コードの検索

参照実装に似たコードを見つけたい場合：

# Step 1: Extract key concepts from reference code
# [Read example_auth.py and identify key concepts]

# Step 2: Search for similar implementations
search "user authentication with JWT tokens" src/

# Step 3: Compare implementations
# [Review semantic matches to find similar approaches]

パターン 3：ドキュメントの検索

ドキュメントやコメント内の概念を調べる場合：

# Search code comments semantically
search "thread safety guarantees" src/ --n-lines 10

# Search markdown documentation
search "deployment best practices" docs/

# Combined search
search "performance optimization" --top-k 20

パターン 4：言語横断検索

異なる言語間で概念を検索する場合：

# Semantic search works across languages
search "connection pooling" src/

# May find:
# - Java: "ConnectionPool manager"
# - Python: "database connection reuse"
# - Go: "pool of persistent connections"
# All semantically related despite different terminology

パターン 5：ドキュメントの分析（API キーを使用）

PDF やドキュメントを分析する場合：

# Step 1: Parse documents to markdown
parse research/*.pdf > papers.md

# Step 2: Search converted content
search "transformer architecture" papers.md

# Step 3: Combine with code search
search "attention mechanism implementation" src/

file-search との連携

Semtools と file-search（ripgrep/ast-grep）は相互補完的なツールです。包括的な検索には、組み合わせて使用してください。

検索戦略マトリックス

わかっていること	最初に使うツール	次に使うツール	理由
正確なキーワード	ripgrep	search	高速に完全一致を見つけ、その後で類似するものを探します
概念のみ	search	ripgrep	関連するコードを見つけ、その後で具体的な内容を検索します
関数名	ripgrep	search	定義を見つけ、その後で類似する使用例を探します
コードパターン	ast-grep	search	構造を見つけ、その後で類似するロジックを探します
おおまかなアイデア	search	ripgrep + ast-grep	見つけた後、詳細を絞り込みます

段階的な検索方法

# Layer 1: Semantic discovery (what's related?)
search "user session management" --top-k 10

# Layer 2: Exact text search (what's the implementation?)
rg "SessionManager|session_store" --type py

# Layer 3: Structural search (how is it used?)
sg --pattern 'session.$METHOD($$$)' --lang python

# Layer 4: Reference tracking (where is it called?)
# [Use serena skill for symbol-level tracking]

ベストプラクティス

1. 広く検索してから絞り込む

セマンティック検索で見つけてから、完全一致検索で範囲を絞り込みます。

# GOOD: Broad semantic discovery first
search "authentication" src/ --top-k 10
# [Review results to learn terminology]
rg "authenticate|verify_credentials" --type py src/

# AVOID: Starting too narrow and missing variations
rg "authenticate" --type py  # Misses "verify_credentials", "check_auth", etc.

2. 類似度のしきい値を調整する

結果に応じて --max-distance を調整します。

# Too many irrelevant results? Decrease distance (more strict)
search "query" --max-distance 0.2

# Missing relevant results? Increase distance (more lenient)
search "query" --max-distance 0.5

# Default (0.3) works well for most cases
search "query"

3. 繰り返し検索にはワークスペースを使う

対話的な探索では、必ずワークスペースを使用してください。

# GOOD: Create workspace once, search many times
export SEMTOOLS_WORKSPACE=my-analysis
search "concept1" src/
search "concept2" src/
search "concept3" src/

# INEFFICIENT: Re-compute embeddings every time
search "concept1" src/
search "concept2" src/

4. コンテキストツールと組み合わせる

セマンティック検索の一致箇所の周辺にあるコンテキストを取得します。

# Find semantically similar code
search "retry logic" src/ --n-lines 2

# Get more context with ripgrep
rg -C 10 "retry" src/specific_file.py

# Or read the full file
cat src/specific_file.py

5. 概念を使ってクエリを表現する

正確なキーワードではなく、概念を使ってクエリを記述します。

# GOOD: Conceptual queries
search "handling network timeouts"
search "user input validation"
search "concurrent data access"

# LESS EFFECTIVE: Exact keyword queries (use ripgrep instead)
search "timeout"  # Use: rg "timeout"
search "validate"  # Use: rg "validate"

セマンティック距離について

Semtools は埋め込みベクトルを使用して、セマンティック類似度を測定します。

• 距離 0.0：意味が同一
• 距離 0.1-0.2：非常に類似（同義語、言い換え）
• 距離 0.2-0.3：関連する概念（デフォルトのしきい値）
• 距離 0.3-0.4：関連性が低い
• 距離 0.5+：関連性が弱い、または無関係

実用上のガイドライン：

# Strict matching (only close matches)
--max-distance 0.2

# Balanced matching (default, recommended)
--max-distance 0.3

# Lenient matching (exploratory search)
--max-distance 0.4

# Very lenient (may include false positives)
--max-distance 0.5

ローカル埋め込みとクラウド埋め込み

セマンティック検索（ローカル）：

• ローカル埋め込み（model2vec、potion-multilingual-128M）を使用します
• API 呼び出しは不要で、クラウドへの依存もありません
• 高速で、プライバシーが保たれ、費用もかかりません
• オフラインで動作します

ドキュメントの解析（クラウド）：

• LlamaParse API（クラウドベース）を使用します
• API キーとインターネット接続が必要です
• PDF、DOCX、PPTX を処理します
• 使用量に応じた料金（LlamaIndex の料金を確認してください）

**プライバシーに関する考慮事項：**セマンティック検索は 100％ローカルで実行されます。LlamaParse API にデータを送信するのは、ドキュメントの解析のみです。

パフォーマンスに関する考慮事項

速度の特性

ワークスペースなし：

• 初回検索：約 2～5 秒（埋め込みの計算）
• 2 回目以降の検索：約 2～5 秒（毎回、埋め込みを再計算）

ワークスペースあり（埋め込みをキャッシュ）：

• 初回検索：約 2～5 秒（インデックスを構築）
• 2 回目以降の検索：約 0.1～0.5 秒（キャッシュを使用）
• 大規模なコードベース：スケーラビリティ向上のため IVF_PQ インデックスを使用

比較：

• ripgrep：0.01～0.1 秒（最速、完全一致）
• ast-grep：0.1～0.5 秒（高速、構造検索）
• semtools（キャッシュあり）：0.1～0.5 秒（高速、セマンティック検索）
• semtools（キャッシュなし）：2～5 秒（低速、セマンティック検索）

最適化のヒント

# 1. Use workspaces for repeated searches
export SEMTOOLS_WORKSPACE=my-project

# 2. Limit search scope to relevant directories
search "query" src/ --not tests/

# 3. Use --top-k to control result count
search "query" --top-k 5

# 4. Pipe to head for quick preview
search "query" | head -50

Unix パイプラインとの連携

Semtools は Unix スタイルの組み合わせを想定して設計されています。

# Find and parse PDFs, then search
find docs/ -name "*.pdf" | xargs parse | xargs search "topic"

# Search and filter with grep
search "authentication" src/ | grep -i "jwt"

# Count matches
search "error handling" src/ | grep "Match" | wc -l

# Combine with other tools
search "API" src/ | xargs -I {} rg -l "REST" {}

制限事項

Semtools を使わない方がよい場合

1. **完全一致のキーワード検索：**既知のキーワードには ripgrep を使用します

   # WRONG TOOL: Semantic search for exact function name
   search "authenticate_user"
   
   # RIGHT TOOL: Use ripgrep for exact matches
   rg "authenticate_user" --type py
   

2. **構造的なコードパターン：**構文の一致には ast-grep を使用します

   # WRONG TOOL: Semantic search for code structure
   search "class with constructor"
   
   # RIGHT TOOL: Use ast-grep for structure
   sg --pattern 'class $NAME { constructor($$$) { $$$ } }'
   

3. **シンボル参照：**LSP ベースの追跡には serena を使用します

   # WRONG TOOL: Semantic search for all usages
   search "MyClass usage"
   
   # RIGHT TOOL: Use serena for precise references
   serena find_referencing_symbols --name 'MyClass'
   

4. **小規模なコードベース：**100 ファイル未満の場合、オーバーヘッドに見合いません

   • 小規模なプロジェクトでは、ripgrep の方が高速でシンプルです

既知のエッジケース

• 曖昧なクエリ：漠然とした概念では、幅広い結果が返されます
• 専門用語：分野固有の用語では精度が低くなることがあります
• 短いコードスニペット：コンテキストが限られるため、埋め込みの品質が低下します
• 複数言語の混在：埋め込みは英語向けに調整されています（多言語モデルを使用）
• 生成されたコード：繰り返しのパターンが同じクラスタにまとまることがあります

トラブルシューティング

セマンティック検索で一致する項目が見つからない

セマンティック検索で結果がゼロ件の場合：

1. ファイルの存在を確認：ripgrep を使ってコンテンツを確認します

   rg "concept" src/
   

2. 類似度のしきい値を上げる：条件を緩めます

   search "query" --max-distance 0.5
   

3. クエリを言い換える：異なる用語を試します

   search "user authentication"
   search "verify user credentials"
   search "login validation"
   

4. ファイルの種類を確認：正しい拡張子を検索していることを確認します

   search "query" src/*.py  # Target specific types
   

関連性の低い結果が多すぎる

セマンティック検索でノイズが多すぎる場合：

1. 類似度のしきい値を下げる：条件を厳しくします

   search "query" --max-distance 0.2
   

2. 結果数を制限する：上位の一致項目のみを確認します

   search "query" --top-k 3
   

3. ディレクトリの範囲を絞る：特定のパスを検索します

   search "query" src/specific_module/
   

4. クエリを改善する：より具体的な概念を追加します

   # Vague
   search "data"
   
   # Specific
   search "data validation with regex patterns"
   

ドキュメントの解析に失敗する

parse に失敗する場合：

1. API キーが設定されていることを確認：

   echo $LLAMA_CLOUD_API_KEY
   

2. ファイル形式を確認：サポートされている形式（PDF、DOCX、PPTX）であることを確認します

   file document.pdf  # Verify file type
   

3. ファイルサイズを確認：サイズの大きいファイルはタイムアウトすることがあります

   du -h document.pdf  # Check size
   

4. 解析設定を確認：必要に応じてタイムアウトを調整します

   cat ~/.parse_config.json
   

ワークスペースの問題

ワークスペースのコマンドに失敗する場合：

# Check workspace status
workspace status

# Prune corrupted workspaces
workspace prune

# Recreate workspace
rm -rf ~/.semtools/workspaces/my-workspace
export SEMTOOLS_WORKSPACE=my-workspace

リソース

• Semtools GitHub
• LlamaParse のドキュメント
• model2vec の埋め込み
• セマンティック検索の概念