@masuidrive/bloom-local-rag/README.ja.md

RAG (Retrieval-Augmented Generation) system for local directories - Index and search your documents with AI-powered answers

# @masuidrive/bloom-local-rag

[🇬🇧 English version](./README.md)

ローカルディレクトリ用のRAG（Retrieval-Augmented Generation）システム。デーモンプロセスを必要とせず、ローカルドキュメントに対してセマンティック検索とAIによる回答生成を提供します。

## bloom-local-ragとは？

bloom-local-ragは、ローカルファイルにRAGの力をもたらすコマンドラインツールです。ドキュメントからベクトルデータベースを作成し、大規模言語モデル（LLM）を使用して、実際のコンテンツに基づいた正確でコンテキストを考慮した回答を提供します。

### 主な機能

- 🔍 **セマンティック検索**: キーワードだけでなく、意味に基づいて情報を検索
- 🤖 **AI駆動の回答**: ドキュメントから生成されたコンテキストに基づく回答
- 📁 **複数のファイルタイプ**: Markdown、コードファイル（JS/TS）、YAMLなどをサポート
- 🔄 **スマートインデックス**: ファイルの変更時に自動的にインデックスを更新
- 🚀 **デーモン不要**: バックグラウンドプロセスなしでオンデマンド実行
- 💾 **効率的なストレージ**: 高速ベクトル操作のためのLanceDBを使用
- 🌐 **マルチプロバイダー対応**: Google GeminiとOpenAIの両方に対応

## インストール

インストール不要！npxで直接使用できます：

```bash
npx @masuidrive/bloom-local-rag
```

またはグローバルインストール：

```bash
npm install -g @masuidrive/bloom-local-rag
```

## クイックスタート

### 1. APIキーの設定

Google Gemini（推奨）の場合：
```bash
export GOOGLE_API_KEY=your-api-key
# または
export GEMINI_API_KEY=your-api-key
```

OpenAIの場合：
```bash
export OPENAI_API_KEY=your-api-key
```

### 2. ディレクトリの初期化

```bash
npx @masuidrive/bloom-local-rag --init
```

これにより、ベクトルデータベースを含む`.bloom-local-rag`ディレクトリが作成されます。

### 3. ドキュメントの検索

```bash
npx @masuidrive/bloom-local-rag query "ユーザー認証の実装方法は？"

# 特定のディレクトリを検索
npx @masuidrive/bloom-local-rag query "ユーザー認証の実装方法は？" --directory /path/to/docs
```

## 詳細な使用方法

### Initコマンド

`init`コマンドは、ディレクトリをスキャンして検索可能なインデックスを作成します：

```bash
npx @masuidrive/bloom-local-rag init [options]
```

**オプション:**
- `-d, --directory <path>`: 初期化対象ディレクトリ（デフォルト: カレントディレクトリ）
- `-e, --extensions <exts...>`: インデックス対象の拡張子（デフォルト: .md, .mdx, .txt, .js, .ts, .jsx, .tsx, .yaml, .yml）
- `--chunk-size <size>`: インデックス用のテキストチャンクサイズ（デフォルト: 1000）
- `--chunk-overlap <size>`: チャンク間のオーバーラップ（デフォルト: 200）
- `--embedding-provider <provider>`: 'gemini'または'openai'を選択（デフォルト: gemini）
- `--embedding-model <model>`: 使用する特定の埋め込みモデル
- `--llm-provider <provider>`: 回答用のLLMプロバイダー（デフォルト: gemini）
- `--llm-model <model>`: 使用する特定のLLMモデル
- `--exclude <patterns...>`: インデックスから除外する追加パターン

**例:**
```bash
# カレントディレクトリを初期化
npx @masuidrive/bloom-local-rag init

# 特定のディレクトリを初期化
npx @masuidrive/bloom-local-rag init --directory ./docs

# MarkdownとTypeScriptファイルのみをインデックス
npx @masuidrive/bloom-local-rag init --extensions .md .ts

# 埋め込みと回答の両方にOpenAIを使用
npx @masuidrive/bloom-local-rag init --embedding-provider openai --llm-provider openai
```

### Queryコマンド

インデックスされたドキュメントを検索し、AI駆動の回答を取得：

```bash
npx @masuidrive/bloom-local-rag query "質問内容" [options]
```

**オプション:**
- `-d, --directory <path>`: 検索対象ディレクトリ（デフォルト: カレントディレクトリ）
- `-l, --limit <n>`: 取得するソースドキュメント数（デフォルト: 5）
- `--no-context`: AI回答生成をスキップし、ソースドキュメントのみを表示
- `--json`: JSON形式で結果を出力
- `--temperature <value>`: AI回答の創造性を制御（0-2、デフォルト: 0.7）
- `-v, --verbose`: ソースを含む詳細情報を表示

**例:**
```bash
# シンプルなクエリ
npx @masuidrive/bloom-local-rag query "非同期関数でのエラー処理方法"

# より多くのソースドキュメントを取得
npx @masuidrive/bloom-local-rag query "データベーススキーマ設計" --limit 10

# AIサマリーなしで関連ドキュメントのみを取得
npx @masuidrive/bloom-local-rag query "APIエンドポイント" --no-context

# 他のツールとの統合用にJSON出力
npx @masuidrive/bloom-local-rag query "ユーザー認証" --json

# 別のディレクトリを検索
npx @masuidrive/bloom-local-rag query "デプロイプロセス" --directory ../other-project
```

### Reindexコマンド

手動でインデックスを更新（クエリ時に自動的に実行されますが）：

```bash
npx @masuidrive/bloom-local-rag reindex [options]
```

**オプション:**
- `-d, --directory <path>`: 再インデックス対象ディレクトリ（デフォルト: カレントディレクトリ）
- `--force`: キャッシュを無視してすべてのファイルを強制的に再インデックス
- `-v, --verbose`: 詳細情報を表示

### Statusコマンド

インデックスされたドキュメントのステータスを確認：

```bash
npx @masuidrive/bloom-local-rag status [options]
```

**オプション:**
- `-d, --directory <path>`: ステータス確認対象ディレクトリ（デフォルト: カレントディレクトリ）

表示内容：
- 設定の詳細
- インデックスされたファイルとチャンクの数
- 最終インデックス更新時刻
- ストレージ使用量

## 仕組み

1. **インデックス作成**: bloom-local-ragがディレクトリをスキャンし、ドキュメントをチャンクに分割
2. **埋め込み**: 各チャンクがAIモデルを使用してベクトル埋め込みに変換
3. **ストレージ**: ベクトルがローカルのLanceDBデータベースに保存
4. **検索**: クエリがベクトルに変換され、保存されたベクトルと比較
5. **コンテキスト**: 最も関連性の高いチャンクがコンテキストとして取得
6. **回答**: LLMが取得したコンテキストに基づいて回答を生成

## ファイルタイプのサポート

デフォルトでbloom-local-ragがインデックスするファイル：
- **ドキュメント**: `.md`, `.mdx`, `.txt`
- **コード**: `.js`, `.ts`, `.jsx`, `.tsx`
- **設定**: `.yaml`, `.yml`

特殊な処理：
- **Markdownファイル**: フロントマターがメタデータとして抽出
- **YAMLファイル**: 構造化データとして解析
- **.gitignore**: ファイル除外のために尊重

## ベストプラクティス

1. **適切なファイルの選択**: ドキュメント、コメントの多いコード、設定ファイルに焦点を当てる
2. **チャンクサイズ**: ナラティブドキュメントには大きめ（2000）、コードには小さめ（500）
3. **除外設定**: 生成ファイル、ビルド出力、依存関係を除外
4. **APIキー**: 環境変数を使用し、キーをバージョン管理にコミットしない
5. **定期的な更新**: 定期的にクエリを実行 - インデックスは自動的に更新される

## 設定

`.bloom-local-rag/config.json`ファイルに設定が保存されます：

```json
{
  "version": "1.0",
  "directory": "/path/to/your/project",
  "extensions": [".md", ".js", ".ts"],
  "embedding": {
    "provider": "gemini",
    "model": "text-embedding-004",
    "chunkSize": 1000,
    "chunkOverlap": 200
  },
  "llm": {
    "provider": "gemini",
    "model": "gemini-2.0-flash-exp",
    "temperature": 0.7
  }
}
```

## トラブルシューティング

### APIキーの問題
```
Error: Gemini API key not found
```
解決策: 適切な環境変数を設定：
- Geminiの場合: `export GOOGLE_API_KEY=your-key`
- OpenAIの場合: `export OPENAI_API_KEY=your-key`

### ディレクトリが初期化されていない
```
Error: Directory not initialized. Run "init" command first.
```
解決策: プロジェクトディレクトリで`npx @masuidrive/bloom-local-rag init`を実行

### 結果が見つからない
- ファイルが設定された拡張子と一致するか確認
- ファイルが.gitignoreで除外されていないか確認
- より広い検索語を試す
- `--limit`パラメータを増やす

## プライバシーとセキュリティ

- **ローカル処理**: すべてのデータはマシン内に留まる
- **テレメトリなし**: 使用状況データは収集しない
- **API呼び出し**: クエリと関連チャンクのみがLLMプロバイダーに送信される
- **Gitignore**: デフォルトで機密ファイルは除外

## 要件

- Node.js v20以上
- Google GeminiまたはOpenAIのAPIキー

## ライセンス

MIT

---

**重要な注意**: このREADMEを変更する場合は、英語版との一貫性を保つため、[README.md](./README.md)の日本語翻訳も更新してください。