@masuidrive/bloom-local-rag

# @masuidrive/bloom-local-rag [🇯🇵 Japanese version](./README.ja.md) RAG (Retrieval-Augmented Generation) system for local directories. This tool enables semantic search across your local documents with AI-powered answers, without requiring a daemon process. ## What is bloom-local-rag? bloom-local-rag is a command-line tool that brings the power of RAG to your local files. It creates a vector database from your documents and uses Large Language Models (LLMs) to provide accurate, context-aware answers based on your actual content. ### Key Features - 🔍 **Semantic Search**: Find information based on meaning, not just keywords - 🤖 **AI-Powered Answers**: Get contextual answers generated from your documents - 📁 **Multiple File Types**: Supports Markdown, code files (JS/TS), YAML, and more - 🔄 **Smart Indexing**: Automatically updates index when files change - 🚀 **No Daemon Required**: Runs on-demand without background processes - 💾 **Efficient Storage**: Uses LanceDB for fast vector operations - 🌐 **Multi-Provider Support**: Works with both Google Gemini and OpenAI ## Installation No installation required! Use directly with npx: ```bash npx @masuidrive/bloom-local-rag ``` Or install globally: ```bash npm install -g @masuidrive/bloom-local-rag ``` ## Quick Start ### 1. Set up your API key For Google Gemini (recommended): ```bash export GOOGLE_API_KEY=your-api-key # or export GEMINI_API_KEY=your-api-key ``` For OpenAI: ```bash export OPENAI_API_KEY=your-api-key ``` ### 2. Initialize your directory ```bash npx @masuidrive/bloom-local-rag --init ``` This creates a `.bloom-local-rag` directory with the vector database. ### 3. Search your documents ```bash npx @masuidrive/bloom-local-rag "how do I authenticate users?" # Search a specific directory npx @masuidrive/bloom-local-rag "how do I authenticate users?" --dir /path/to/docs # Or use --directory npx @masuidrive/bloom-local-rag --directory /path/to/docs "how do I authenticate users?" ``` ## Detailed Usage ### Initialize Command The `--init` option scans your directory and creates a searchable index: ```bash npx @masuidrive/bloom-local-rag --init [options] ``` **Options:** - `-d, --dir, --directory <path>`: Directory to initialize (default: current directory) - `-e, --extensions <exts...>`: File extensions to index (default: .md, .mdx, .txt, .js, .ts, .jsx, .tsx, .yaml, .yml) - `--chunk-size <size>`: Text chunk size for indexing (default: 1000) - `--chunk-overlap <size>`: Overlap between chunks (default: 200) - `--embedding-provider <provider>`: Choose between 'gemini' or 'openai' (default: gemini) - `--embedding-model <model>`: Specific embedding model to use - `--llm-provider <provider>`: LLM provider for answers (default: gemini) - `--llm-model <model>`: Specific LLM model to use - `--exclude <patterns...>`: Additional patterns to exclude from indexing **Example:** ```bash # Initialize current directory npx @masuidrive/bloom-local-rag --init # Initialize a specific directory npx @masuidrive/bloom-local-rag --init --dir ./docs # Index only markdown and TypeScript files npx @masuidrive/bloom-local-rag --init --extensions .md .ts # Use OpenAI for both embeddings and answers npx @masuidrive/bloom-local-rag --init --embedding-provider openai --llm-provider openai ``` ### Query Command (Default Mode) Search your indexed documents and get AI-powered answers: ```bash npx @masuidrive/bloom-local-rag "your question here" [options] ``` **Options:** - `-d, --dir, --directory <path>`: Directory to search (default: current directory) - `-l, --limit <n>`: Number of source documents to retrieve (default: 5) - `--no-context`: Skip AI answer generation, show only source documents - `--json`: Output results in JSON format - `--temperature <value>`: Control creativity of AI answers (0-2, default: 0.7) - `-v, --verbose`: Show detailed information including sources **Examples:** ```bash # Simple query npx @masuidrive/bloom-local-rag "how to handle errors in async functions" # Get more source documents npx @masuidrive/bloom-local-rag "database schema design" --limit 10 # Get only relevant documents without AI summary npx @masuidrive/bloom-local-rag "API endpoints" --no-context # Get JSON output for integration with other tools npx @masuidrive/bloom-local-rag "user authentication" --json # Search in a different directory npx @masuidrive/bloom-local-rag "deployment process" --dir ../other-project # Directory option can come before or after the query npx @masuidrive/bloom-local-rag --dir ../docs "deployment process" ``` ### Reindex Command Manually update the index (though this happens automatically during queries): ```bash npx @masuidrive/bloom-local-rag --reindex [options] ``` **Options:** - `-d, --dir, --directory <path>`: Directory to reindex (default: current directory) - `--force`: Force reindex all files, ignoring cache - `-v, --verbose`: Show detailed information ### Status Command Check the status of your indexed documents: ```bash npx @masuidrive/bloom-local-rag --status [options] ``` **Options:** - `-d, --dir, --directory <path>`: Directory to check status (default: current directory) Shows: - Configuration details - Number of indexed files and chunks - Last index update time - Storage usage ## How It Works 1. **Indexing**: bloom-local-rag scans your directory and splits documents into chunks 2. **Embedding**: Each chunk is converted to a vector embedding using AI models 3. **Storage**: Vectors are stored in a local LanceDB database 4. **Search**: Your query is converted to a vector and compared with stored vectors 5. **Context**: Most relevant chunks are retrieved as context 6. **Answer**: An LLM generates an answer based on the retrieved context ## File Type Support By default, bloom-local-rag indexes: - **Documentation**: `.md`, `.mdx`, `.txt` - **Code**: `.js`, `.ts`, `.jsx`, `.tsx` - **Configuration**: `.yaml`, `.yml` Special handling: - **Markdown files**: Frontmatter is extracted as metadata - **YAML files**: Parsed for structured data - **.gitignore**: Respected for file exclusion ## Best Practices 1. **Choose the Right Files**: Focus on documentation, well-commented code, and configuration files 2. **Chunk Size**: Larger chunks (2000) for narrative docs, smaller (500) for code 3. **Exclusions**: Exclude generated files, build outputs, and dependencies 4. **API Keys**: Use environment variables, never commit keys to version control 5. **Regular Updates**: Run queries regularly - the index updates automatically ## Configuration The `.bloom-local-rag/config.json` file stores your settings: ```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 } } ``` ## Troubleshooting ### API Key Issues ``` Error: Gemini API key not found ``` Solution: Set the appropriate environment variable: - For Gemini: `export GOOGLE_API_KEY=your-key` - For OpenAI: `export OPENAI_API_KEY=your-key` ### Directory Not Initialized ``` Error: Directory not initialized. Run "init" command first. ``` Solution: Run `npx @masuidrive/bloom-local-rag init` in your project directory ### No Results Found - Check if files match the configured extensions - Verify files aren't excluded by .gitignore - Try broader search terms - Increase the `--limit` parameter ## Privacy & Security - **Local Processing**: All data stays on your machine - **No Telemetry**: We don't collect any usage data - **API Calls**: Only your queries and relevant chunks are sent to the LLM provider - **Gitignore**: Sensitive files excluded by default ## Requirements - Node.js v20 or higher - API key for Google Gemini or OpenAI ## License MIT --- **Important Note**: When modifying this README, please also update the Japanese translation in [README.ja.md](./README.ja.md) to maintain consistency across both versions.