1 line
158 KiB
JSON
1 line
158 KiB
JSON
{"repo": "anrgct/autodev-codebase", "files": {"CONFIG.md": {"e7851faa1e24c5d952196dd025fab140fe600b8e": {"t": 1785674036.1099367, "n": 21156, "h": "b6f409d43f7a9b27", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Summarizer Configuration](#summarizer-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase config --get\n\n# View specific configuration items\ncodebase config --get embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase config --get --json\n\n# Set project configuration\ncodebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text\n# Note: also adds `autodev-config.json` to Git global ignore (core.excludesfile) for all repos\n\n# Set global configuration\ncodebase config --set --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json config --get\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache index\n\n# Working directory\ncodebase --path=/my/project index\n\n# Debug logging\ncodebase --log-level=debug index\n\n# Force reindex\ncodebase --force index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `outline <pattern>` - Extract code outlines from file(s) using glob patterns\n- `--summarize` - Generate AI summaries for code outlines\n- `--title` - Show only file-level summary (no function details)\n- `--clear-summarize-cache` - Clear all summary caches for current project\n- `--dry-run` - Preview files without performing the actual operation\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--limit, -l <number>` - Maximum number of search results (overrides config, max 50)\n- `--min-score, -S <number>` - Minimum similarity score for search results 0-1 (overrides config)\n- `--json` - Output search results in JSON format\n- `call [path]` - Analyze code dependencies (file or directory)\n- `--query <names>` - Query dependencies for specific names (comma-separated, for call command)\n- `--depth <number>` - Query depth for dependency traversal (default: 3 for single query, 10 for multi-query, for call command)\n- `--output <file>` - Export dependency data to JSON file (for call command)\n- `--open` - Open HTML visualization in browser (for call command)\n- `--clear-cache` - Clear dependency analysis cache (for call command)\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n### CLI Runtime Override\n\nYou can override search parameters at runtime using CLI arguments:\n\n```bash\n# Override max results (limited to maximum of 50)\ncodebase search \"authentication\" --limit=20\ncodebase search \"API\" -l 30\n\n# Override minimum score (0.0-1.0)\ncodebase search \"user auth\" --min-score=0.7\ncodebase search \"database\" -S 0.5\n\n# Combine both\ncodebase search \"error handling\" --limit=10 --min-score=0.8\n```\n\n**Note:** CLI arguments `--limit` and `--min-score` provide temporary override for individual searches. For persistent settings, use `vectorSearchMaxResults` and `vectorSearchMinScore` in configuration files.\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n| `rerankerConcurrency` | number | No | `3` | Concurrent rerank requests |\n| `rerankerMaxRetries` | number | No | `3` | Retry attempts for failed requests |\n| `rerankerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Summarizer Configuration\n\nGenerate AI-powered summaries for code blocks with intelligent caching and batch processing.\n\n### Quick Start\n\n```bash\n# Generate intelligent code outline with AI summaries\ncodebase outline \"src/**/*.ts\" --summarize\n```\n\n**Output Example:**\n```\n# src/cli.ts (1902 lines)\n└─ Implements a simplified CLI for @autodev/codebase using Node.js native parseArgs. \n Manages codebase indexing, searching, and MCP server operations.\n\n 27--35 | function initGlobalLogger\n └─ Initializes a global logger instance with specified log level and timestamps.\n\n 45--54 | interface SearchResult\n └─ Defines the structure for search result payloads, including file path, code chunk, \n and relevance score.\n\n ... (full outline with AI summaries)\n```\n\n**Setup (One-time):**\n```bash\n# Option 1: Ollama (free, local AI)\ncodebase config --set summarizerProvider=ollama,summarizerOllamaModelId=qwen3-vl:4b-instruct\n\n# Option 2: DeepSeek (cost-effective API)\ncodebase config --set summarizerProvider=openai-compatible,summarizerOpenAiCompatibleBaseUrl=https://api.deepseek.com/v1,summarizerOpenAiCompatibleModelId=deepseek-chat,summarizerOpenAiCompatibleApiKey=sk-your-key\n```\n\n**Key Benefits:**\n- 🧠 **Understand code fast** - Get function-level summaries without reading every line\n- 💾 **Smart caching** - Only summarizes changed code blocks (>90% cache hit on unchanged code)\n- 🌐 **Multi-language** - English/Chinese summaries supported\n- ⚡ **Batch processing** - Efficiently handles large codebases\n\n### Configuration Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `summarizerProvider` | string | No | `ollama` | Summarizer provider: `ollama` or `openai-compatible` |\n| `summarizerLanguage` | string | No | `English` | Output language: `English` or `Chinese` |\n| `summarizerTemperature` | number | No | - | LLM temperature (0.0-1.0), affects output randomness |\n| `summarizerBatchSize` | number | No | `2` | Number of code blocks per batch request |\n| `summarizerConcurrency` | number | No | `2` | Maximum concurrent batch requests |\n| `summarizerMaxRetries` | number | No | `3` | Maximum retry attempts for failed requests |\n| `summarizerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds (exponential backoff) |\n\n### Ollama Summarizer\n\n**Provider ID:** `ollama`\n\nRecommended for local development with complete privacy protection.\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### OpenAI-Compatible Summarizer\n\n**Provider ID:** `openai-compatible`\n\nFor production use with external APIs (DeepSeek, OpenAI, etc.).\n\n```json\n{\n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"summarizerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n**Supported Providers:**\n- **DeepSeek**: `https://api.deepseek.com/v1`\n- **OpenAI**: `https://api.openai.com/v1`\n- **Together AI**: `https://api.together.xyz/v1`\n- Any other OpenAI-compatible API\n\n### Summary Cache System\n\nThe summarizer uses a **two-level caching mechanism** to avoid redundant LLM calls.\n\n#### Cache Levels\n\n1. **File-level Hash**: SHA256 hash of complete file content\n - Fast detection of unchanged files\n - 100% cache hit when file unchanged\n\n2. **Block-level Hash**: SHA256 hash of individual code block + context\n - Precise detection of changed code blocks\n - Only re-summarizes modified blocks\n\n#### Cache Invalidation\n\nCache is automatically invalidated when:\n- **Configuration changes**: Provider, model, language, or temperature changes\n- **File content changes**: File hash no longer matches\n- **Manual clearing**: Using `--clear-summarize-cache` flag\n\n#### Cache Storage\n\n```\n~/.autodev-cache/summary-cache/\n├── {project-hash-1}/\n│ └── files/\n│ ├── src-cli-tools-outline.json\n│ └── src-code-index-manager.json\n└── {project-hash-2}/\n └── files/\n └── lib-utils.json\n```\n\n#### Cache Performance\n\n- **Typical hit rate**: >90% for unchanged codebases\n- **Incremental updates**: Only re-summarizes changed blocks\n- **Batch processing**: Efficiently handles large files\n- **Atomic writes**: Safe concurrent access\n\n#### Cache Management Commands\n\n```bash\n# View cache statistics (automatic)\ncodebase outline src/index.ts --summarize\n# Output: Cache hit rate: 85% (17/20 blocks cached)\n\n# Clear all caches for current project\ncodebase --clear-summarize-cache\n\n# Clear and regenerate\ncodebase outline src/index.ts --summarize --clear-summarize-cache\n\n# Clear caches for specific project\ncodebase --clear-summarize-cache --path=/my/project\n```\n\n### Language Support\n\nThe summarizer supports multiple output languages:\n\n```json\n{\n \"summarizerLanguage\": \"English\" // or \"Chinese\"\n}\n```\n\n**Examples:**\n\nEnglish Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\nChinese Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Performance Tuning\n\nFor large codebases, adjust these parameters:\n\n```json\n{\n \"summarizerBatchSize\": 4, // Increase for faster processing (more memory)\n \"summarizerConcurrency\": 4, // Increase for parallel processing (more API calls)\n \"summarizerMaxRetries\": 5, // Increase for unreliable networks\n \"summarizerRetryDelayMs\": 2000 // Increase for rate-limited APIs\n}\n```\n\n**Trade-offs:**\n- Higher `batchSize` = Faster but more memory usage\n- Higher `concurrency` = More parallel requests but higher API load\n- Higher `maxRetries` = Better reliability but slower on failures\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Complete Configuration with All Features\n\n**File:** `./autodev-config.json`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20,\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5,\n \"rerankerBatchSize\": 10,\n \"rerankerConcurrency\": 3,\n \"rerankerMaxRetries\": 3,\n \"rerankerRetryDelayMs\": 1000,\n \n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### Chinese Language Configuration\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Production Configuration with OpenAI\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-openai-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5,\n \n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleModelId\": \"gpt-4o-mini\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-openai-key\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase config --set qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase config --set embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase config --set vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase config --set embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase config --set embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase config --set embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}, "8dbae7ded3200ff0f1bd241797e3a897e26bc395": {"t": 1785762733.5118158, "n": 21156, "h": "b6f409d43f7a9b27", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Summarizer Configuration](#summarizer-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase config --get\n\n# View specific configuration items\ncodebase config --get embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase config --get --json\n\n# Set project configuration\ncodebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text\n# Note: also adds `autodev-config.json` to Git global ignore (core.excludesfile) for all repos\n\n# Set global configuration\ncodebase config --set --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json config --get\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache index\n\n# Working directory\ncodebase --path=/my/project index\n\n# Debug logging\ncodebase --log-level=debug index\n\n# Force reindex\ncodebase --force index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `outline <pattern>` - Extract code outlines from file(s) using glob patterns\n- `--summarize` - Generate AI summaries for code outlines\n- `--title` - Show only file-level summary (no function details)\n- `--clear-summarize-cache` - Clear all summary caches for current project\n- `--dry-run` - Preview files without performing the actual operation\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--limit, -l <number>` - Maximum number of search results (overrides config, max 50)\n- `--min-score, -S <number>` - Minimum similarity score for search results 0-1 (overrides config)\n- `--json` - Output search results in JSON format\n- `call [path]` - Analyze code dependencies (file or directory)\n- `--query <names>` - Query dependencies for specific names (comma-separated, for call command)\n- `--depth <number>` - Query depth for dependency traversal (default: 3 for single query, 10 for multi-query, for call command)\n- `--output <file>` - Export dependency data to JSON file (for call command)\n- `--open` - Open HTML visualization in browser (for call command)\n- `--clear-cache` - Clear dependency analysis cache (for call command)\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n### CLI Runtime Override\n\nYou can override search parameters at runtime using CLI arguments:\n\n```bash\n# Override max results (limited to maximum of 50)\ncodebase search \"authentication\" --limit=20\ncodebase search \"API\" -l 30\n\n# Override minimum score (0.0-1.0)\ncodebase search \"user auth\" --min-score=0.7\ncodebase search \"database\" -S 0.5\n\n# Combine both\ncodebase search \"error handling\" --limit=10 --min-score=0.8\n```\n\n**Note:** CLI arguments `--limit` and `--min-score` provide temporary override for individual searches. For persistent settings, use `vectorSearchMaxResults` and `vectorSearchMinScore` in configuration files.\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n| `rerankerConcurrency` | number | No | `3` | Concurrent rerank requests |\n| `rerankerMaxRetries` | number | No | `3` | Retry attempts for failed requests |\n| `rerankerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Summarizer Configuration\n\nGenerate AI-powered summaries for code blocks with intelligent caching and batch processing.\n\n### Quick Start\n\n```bash\n# Generate intelligent code outline with AI summaries\ncodebase outline \"src/**/*.ts\" --summarize\n```\n\n**Output Example:**\n```\n# src/cli.ts (1902 lines)\n└─ Implements a simplified CLI for @autodev/codebase using Node.js native parseArgs. \n Manages codebase indexing, searching, and MCP server operations.\n\n 27--35 | function initGlobalLogger\n └─ Initializes a global logger instance with specified log level and timestamps.\n\n 45--54 | interface SearchResult\n └─ Defines the structure for search result payloads, including file path, code chunk, \n and relevance score.\n\n ... (full outline with AI summaries)\n```\n\n**Setup (One-time):**\n```bash\n# Option 1: Ollama (free, local AI)\ncodebase config --set summarizerProvider=ollama,summarizerOllamaModelId=qwen3-vl:4b-instruct\n\n# Option 2: DeepSeek (cost-effective API)\ncodebase config --set summarizerProvider=openai-compatible,summarizerOpenAiCompatibleBaseUrl=https://api.deepseek.com/v1,summarizerOpenAiCompatibleModelId=deepseek-chat,summarizerOpenAiCompatibleApiKey=sk-your-key\n```\n\n**Key Benefits:**\n- 🧠 **Understand code fast** - Get function-level summaries without reading every line\n- 💾 **Smart caching** - Only summarizes changed code blocks (>90% cache hit on unchanged code)\n- 🌐 **Multi-language** - English/Chinese summaries supported\n- ⚡ **Batch processing** - Efficiently handles large codebases\n\n### Configuration Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `summarizerProvider` | string | No | `ollama` | Summarizer provider: `ollama` or `openai-compatible` |\n| `summarizerLanguage` | string | No | `English` | Output language: `English` or `Chinese` |\n| `summarizerTemperature` | number | No | - | LLM temperature (0.0-1.0), affects output randomness |\n| `summarizerBatchSize` | number | No | `2` | Number of code blocks per batch request |\n| `summarizerConcurrency` | number | No | `2` | Maximum concurrent batch requests |\n| `summarizerMaxRetries` | number | No | `3` | Maximum retry attempts for failed requests |\n| `summarizerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds (exponential backoff) |\n\n### Ollama Summarizer\n\n**Provider ID:** `ollama`\n\nRecommended for local development with complete privacy protection.\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### OpenAI-Compatible Summarizer\n\n**Provider ID:** `openai-compatible`\n\nFor production use with external APIs (DeepSeek, OpenAI, etc.).\n\n```json\n{\n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"summarizerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n**Supported Providers:**\n- **DeepSeek**: `https://api.deepseek.com/v1`\n- **OpenAI**: `https://api.openai.com/v1`\n- **Together AI**: `https://api.together.xyz/v1`\n- Any other OpenAI-compatible API\n\n### Summary Cache System\n\nThe summarizer uses a **two-level caching mechanism** to avoid redundant LLM calls.\n\n#### Cache Levels\n\n1. **File-level Hash**: SHA256 hash of complete file content\n - Fast detection of unchanged files\n - 100% cache hit when file unchanged\n\n2. **Block-level Hash**: SHA256 hash of individual code block + context\n - Precise detection of changed code blocks\n - Only re-summarizes modified blocks\n\n#### Cache Invalidation\n\nCache is automatically invalidated when:\n- **Configuration changes**: Provider, model, language, or temperature changes\n- **File content changes**: File hash no longer matches\n- **Manual clearing**: Using `--clear-summarize-cache` flag\n\n#### Cache Storage\n\n```\n~/.autodev-cache/summary-cache/\n├── {project-hash-1}/\n│ └── files/\n│ ├── src-cli-tools-outline.json\n│ └── src-code-index-manager.json\n└── {project-hash-2}/\n └── files/\n └── lib-utils.json\n```\n\n#### Cache Performance\n\n- **Typical hit rate**: >90% for unchanged codebases\n- **Incremental updates**: Only re-summarizes changed blocks\n- **Batch processing**: Efficiently handles large files\n- **Atomic writes**: Safe concurrent access\n\n#### Cache Management Commands\n\n```bash\n# View cache statistics (automatic)\ncodebase outline src/index.ts --summarize\n# Output: Cache hit rate: 85% (17/20 blocks cached)\n\n# Clear all caches for current project\ncodebase --clear-summarize-cache\n\n# Clear and regenerate\ncodebase outline src/index.ts --summarize --clear-summarize-cache\n\n# Clear caches for specific project\ncodebase --clear-summarize-cache --path=/my/project\n```\n\n### Language Support\n\nThe summarizer supports multiple output languages:\n\n```json\n{\n \"summarizerLanguage\": \"English\" // or \"Chinese\"\n}\n```\n\n**Examples:**\n\nEnglish Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\nChinese Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Performance Tuning\n\nFor large codebases, adjust these parameters:\n\n```json\n{\n \"summarizerBatchSize\": 4, // Increase for faster processing (more memory)\n \"summarizerConcurrency\": 4, // Increase for parallel processing (more API calls)\n \"summarizerMaxRetries\": 5, // Increase for unreliable networks\n \"summarizerRetryDelayMs\": 2000 // Increase for rate-limited APIs\n}\n```\n\n**Trade-offs:**\n- Higher `batchSize` = Faster but more memory usage\n- Higher `concurrency` = More parallel requests but higher API load\n- Higher `maxRetries` = Better reliability but slower on failures\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Complete Configuration with All Features\n\n**File:** `./autodev-config.json`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20,\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5,\n \"rerankerBatchSize\": 10,\n \"rerankerConcurrency\": 3,\n \"rerankerMaxRetries\": 3,\n \"rerankerRetryDelayMs\": 1000,\n \n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### Chinese Language Configuration\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Production Configuration with OpenAI\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-openai-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5,\n \n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleModelId\": \"gpt-4o-mini\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-openai-key\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase config --set qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase config --set embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase config --set vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase config --set embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase config --set embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase config --set embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}, "6232750f0305be1518e5b12df974ef24161fe305": {"t": 1785762735.4845743, "n": 21120, "h": "d8fd55f00df6fe32", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Summarizer Configuration](#summarizer-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase config --get\n\n# View specific configuration items\ncodebase config --get embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase config --get --json\n\n# Set project configuration\ncodebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text\n# Note: also adds `autodev-config.json` to Git global ignore (core.excludesfile) for all repos\n\n# Set global configuration\ncodebase config --set --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json config --get\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache index\n\n# Working directory\ncodebase --path=/my/project index\n\n# Debug logging\ncodebase --log-level=debug index\n\n# Force reindex\ncodebase --force index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `outline <pattern>` - Extract code outlines from file(s) using glob patterns\n- `--summarize` - Generate AI summaries for code outlines\n- `--title` - Show only file-level summary (no function details)\n- `--clear-summarize-cache` - Clear all summary caches for current project\n- `--dry-run` - Preview files without performing the actual operation\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--limit, -l <number>` - Maximum number of search results (overrides config, max 50)\n- `--min-score, -S <number>` - Minimum similarity score for search results 0-1 (overrides config)\n- `--json` - Output search results in JSON format\n- `call [path]` - Analyze code dependencies (file or directory)\n- `--query <names>` - Query dependencies for specific names (comma-separated, for call command)\n- `--depth <number>` - Query depth for dependency traversal (default: 10, for call command)\n- `--output <file>` - Export dependency data to JSON file (for call command)\n- `--open` - Open HTML visualization in browser (for call command)\n- `--clear-cache` - Clear dependency analysis cache (for call command)\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n### CLI Runtime Override\n\nYou can override search parameters at runtime using CLI arguments:\n\n```bash\n# Override max results (limited to maximum of 50)\ncodebase search \"authentication\" --limit=20\ncodebase search \"API\" -l 30\n\n# Override minimum score (0.0-1.0)\ncodebase search \"user auth\" --min-score=0.7\ncodebase search \"database\" -S 0.5\n\n# Combine both\ncodebase search \"error handling\" --limit=10 --min-score=0.8\n```\n\n**Note:** CLI arguments `--limit` and `--min-score` provide temporary override for individual searches. For persistent settings, use `vectorSearchMaxResults` and `vectorSearchMinScore` in configuration files.\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n| `rerankerConcurrency` | number | No | `3` | Concurrent rerank requests |\n| `rerankerMaxRetries` | number | No | `3` | Retry attempts for failed requests |\n| `rerankerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Summarizer Configuration\n\nGenerate AI-powered summaries for code blocks with intelligent caching and batch processing.\n\n### Quick Start\n\n```bash\n# Generate intelligent code outline with AI summaries\ncodebase outline \"src/**/*.ts\" --summarize\n```\n\n**Output Example:**\n```\n# src/cli.ts (1902 lines)\n└─ Implements a simplified CLI for @autodev/codebase using Node.js native parseArgs. \n Manages codebase indexing, searching, and MCP server operations.\n\n 27--35 | function initGlobalLogger\n └─ Initializes a global logger instance with specified log level and timestamps.\n\n 45--54 | interface SearchResult\n └─ Defines the structure for search result payloads, including file path, code chunk, \n and relevance score.\n\n ... (full outline with AI summaries)\n```\n\n**Setup (One-time):**\n```bash\n# Option 1: Ollama (free, local AI)\ncodebase config --set summarizerProvider=ollama,summarizerOllamaModelId=qwen3-vl:4b-instruct\n\n# Option 2: DeepSeek (cost-effective API)\ncodebase config --set summarizerProvider=openai-compatible,summarizerOpenAiCompatibleBaseUrl=https://api.deepseek.com/v1,summarizerOpenAiCompatibleModelId=deepseek-chat,summarizerOpenAiCompatibleApiKey=sk-your-key\n```\n\n**Key Benefits:**\n- 🧠 **Understand code fast** - Get function-level summaries without reading every line\n- 💾 **Smart caching** - Only summarizes changed code blocks (>90% cache hit on unchanged code)\n- 🌐 **Multi-language** - English/Chinese summaries supported\n- ⚡ **Batch processing** - Efficiently handles large codebases\n\n### Configuration Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `summarizerProvider` | string | No | `ollama` | Summarizer provider: `ollama` or `openai-compatible` |\n| `summarizerLanguage` | string | No | `English` | Output language: `English` or `Chinese` |\n| `summarizerTemperature` | number | No | - | LLM temperature (0.0-1.0), affects output randomness |\n| `summarizerBatchSize` | number | No | `2` | Number of code blocks per batch request |\n| `summarizerConcurrency` | number | No | `2` | Maximum concurrent batch requests |\n| `summarizerMaxRetries` | number | No | `3` | Maximum retry attempts for failed requests |\n| `summarizerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds (exponential backoff) |\n\n### Ollama Summarizer\n\n**Provider ID:** `ollama`\n\nRecommended for local development with complete privacy protection.\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### OpenAI-Compatible Summarizer\n\n**Provider ID:** `openai-compatible`\n\nFor production use with external APIs (DeepSeek, OpenAI, etc.).\n\n```json\n{\n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"summarizerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n**Supported Providers:**\n- **DeepSeek**: `https://api.deepseek.com/v1`\n- **OpenAI**: `https://api.openai.com/v1`\n- **Together AI**: `https://api.together.xyz/v1`\n- Any other OpenAI-compatible API\n\n### Summary Cache System\n\nThe summarizer uses a **two-level caching mechanism** to avoid redundant LLM calls.\n\n#### Cache Levels\n\n1. **File-level Hash**: SHA256 hash of complete file content\n - Fast detection of unchanged files\n - 100% cache hit when file unchanged\n\n2. **Block-level Hash**: SHA256 hash of individual code block + context\n - Precise detection of changed code blocks\n - Only re-summarizes modified blocks\n\n#### Cache Invalidation\n\nCache is automatically invalidated when:\n- **Configuration changes**: Provider, model, language, or temperature changes\n- **File content changes**: File hash no longer matches\n- **Manual clearing**: Using `--clear-summarize-cache` flag\n\n#### Cache Storage\n\n```\n~/.autodev-cache/summary-cache/\n├── {project-hash-1}/\n│ └── files/\n│ ├── src-cli-tools-outline.json\n│ └── src-code-index-manager.json\n└── {project-hash-2}/\n └── files/\n └── lib-utils.json\n```\n\n#### Cache Performance\n\n- **Typical hit rate**: >90% for unchanged codebases\n- **Incremental updates**: Only re-summarizes changed blocks\n- **Batch processing**: Efficiently handles large files\n- **Atomic writes**: Safe concurrent access\n\n#### Cache Management Commands\n\n```bash\n# View cache statistics (automatic)\ncodebase outline src/index.ts --summarize\n# Output: Cache hit rate: 85% (17/20 blocks cached)\n\n# Clear all caches for current project\ncodebase --clear-summarize-cache\n\n# Clear and regenerate\ncodebase outline src/index.ts --summarize --clear-summarize-cache\n\n# Clear caches for specific project\ncodebase --clear-summarize-cache --path=/my/project\n```\n\n### Language Support\n\nThe summarizer supports multiple output languages:\n\n```json\n{\n \"summarizerLanguage\": \"English\" // or \"Chinese\"\n}\n```\n\n**Examples:**\n\nEnglish Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\nChinese Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Performance Tuning\n\nFor large codebases, adjust these parameters:\n\n```json\n{\n \"summarizerBatchSize\": 4, // Increase for faster processing (more memory)\n \"summarizerConcurrency\": 4, // Increase for parallel processing (more API calls)\n \"summarizerMaxRetries\": 5, // Increase for unreliable networks\n \"summarizerRetryDelayMs\": 2000 // Increase for rate-limited APIs\n}\n```\n\n**Trade-offs:**\n- Higher `batchSize` = Faster but more memory usage\n- Higher `concurrency` = More parallel requests but higher API load\n- Higher `maxRetries` = Better reliability but slower on failures\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Complete Configuration with All Features\n\n**File:** `./autodev-config.json`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20,\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5,\n \"rerankerBatchSize\": 10,\n \"rerankerConcurrency\": 3,\n \"rerankerMaxRetries\": 3,\n \"rerankerRetryDelayMs\": 1000,\n \n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### Chinese Language Configuration\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Production Configuration with OpenAI\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-openai-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5,\n \n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleModelId\": \"gpt-4o-mini\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-openai-key\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase config --set qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase config --set embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase config --set vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase config --set embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase config --set embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase config --set embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}, "f323b75af8bdacfc2861bcd85b28deb72daece9d": {"t": 1785762737.1002853, "n": 20652, "h": "ee2bb2875b26e65a", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Summarizer Configuration](#summarizer-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase config --get\n\n# View specific configuration items\ncodebase config --get embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase config --get --json\n\n# Set project configuration\ncodebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text\n# Note: also adds `autodev-config.json` to Git global ignore (core.excludesfile) for all repos\n\n# Set global configuration\ncodebase config --set --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json config --get\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache index\n\n# Working directory\ncodebase --path=/my/project index\n\n# Debug logging\ncodebase --log-level=debug index\n\n# Force reindex\ncodebase --force index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `outline <pattern>` - Extract code outline from file(s) using glob patterns\n- `--summarize` - Generate AI summaries for code outlines\n- `--title` - Show only file-level summary (no function details)\n- `--clear-summarize-cache` - Clear all summary caches for current project\n- `--dry-run` - Preview files without performing the actual operation\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--limit, -l <number>` - Maximum number of search results (overrides config, max 50)\n- `--min-score, -S <number>` - Minimum similarity score for search results 0-1 (overrides config)\n- `--json` - Output search results in JSON format\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n### CLI Runtime Override\n\nYou can override search parameters at runtime using CLI arguments:\n\n```bash\n# Override max results (limited to maximum of 50)\ncodebase search \"authentication\" --limit=20\ncodebase search \"API\" -l 30\n\n# Override minimum score (0.0-1.0)\ncodebase search \"user auth\" --min-score=0.7\ncodebase search \"database\" -S 0.5\n\n# Combine both\ncodebase search \"error handling\" --limit=10 --min-score=0.8\n```\n\n**Note:** CLI arguments `--limit` and `--min-score` provide temporary override for individual searches. For persistent settings, use `vectorSearchMaxResults` and `vectorSearchMinScore` in configuration files.\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n| `rerankerConcurrency` | number | No | `3` | Concurrent rerank requests |\n| `rerankerMaxRetries` | number | No | `3` | Retry attempts for failed requests |\n| `rerankerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Summarizer Configuration\n\nGenerate AI-powered summaries for code blocks with intelligent caching and batch processing.\n\n### Quick Start\n\n```bash\n# Generate intelligent code outline with AI summaries\ncodebase outline \"src/**/*.ts\" --summarize\n```\n\n**Output Example:**\n```\n# src/cli.ts (1902 lines)\n└─ Implements a simplified CLI for @autodev/codebase using Node.js native parseArgs. \n Manages codebase indexing, searching, and MCP server operations.\n\n 27--35 | function initGlobalLogger\n └─ Initializes a global logger instance with specified log level and timestamps.\n\n 45--54 | interface SearchResult\n └─ Defines the structure for search result payloads, including file path, code chunk, \n and relevance score.\n\n ... (full outline with AI summaries)\n```\n\n**Setup (One-time):**\n```bash\n# Option 1: Ollama (free, local AI)\ncodebase config --set summarizerProvider=ollama,summarizerOllamaModelId=qwen3-vl:4b-instruct\n\n# Option 2: DeepSeek (cost-effective API)\ncodebase config --set summarizerProvider=openai-compatible,summarizerOpenAiCompatibleBaseUrl=https://api.deepseek.com/v1,summarizerOpenAiCompatibleModelId=deepseek-chat,summarizerOpenAiCompatibleApiKey=sk-your-key\n```\n\n**Key Benefits:**\n- 🧠 **Understand code fast** - Get function-level summaries without reading every line\n- 💾 **Smart caching** - Only summarizes changed code blocks (>90% cache hit on unchanged code)\n- 🌐 **Multi-language** - English/Chinese summaries supported\n- ⚡ **Batch processing** - Efficiently handles large codebases\n\n### Configuration Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `summarizerProvider` | string | No | `ollama` | Summarizer provider: `ollama` or `openai-compatible` |\n| `summarizerLanguage` | string | No | `English` | Output language: `English` or `Chinese` |\n| `summarizerTemperature` | number | No | - | LLM temperature (0.0-1.0), affects output randomness |\n| `summarizerBatchSize` | number | No | `2` | Number of code blocks per batch request |\n| `summarizerConcurrency` | number | No | `2` | Maximum concurrent batch requests |\n| `summarizerMaxRetries` | number | No | `3` | Maximum retry attempts for failed requests |\n| `summarizerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds (exponential backoff) |\n\n### Ollama Summarizer\n\n**Provider ID:** `ollama`\n\nRecommended for local development with complete privacy protection.\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### OpenAI-Compatible Summarizer\n\n**Provider ID:** `openai-compatible`\n\nFor production use with external APIs (DeepSeek, OpenAI, etc.).\n\n```json\n{\n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"summarizerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n**Supported Providers:**\n- **DeepSeek**: `https://api.deepseek.com/v1`\n- **OpenAI**: `https://api.openai.com/v1`\n- **Together AI**: `https://api.together.xyz/v1`\n- Any other OpenAI-compatible API\n\n### Summary Cache System\n\nThe summarizer uses a **two-level caching mechanism** to avoid redundant LLM calls.\n\n#### Cache Levels\n\n1. **File-level Hash**: SHA256 hash of complete file content\n - Fast detection of unchanged files\n - 100% cache hit when file unchanged\n\n2. **Block-level Hash**: SHA256 hash of individual code block + context\n - Precise detection of changed code blocks\n - Only re-summarizes modified blocks\n\n#### Cache Invalidation\n\nCache is automatically invalidated when:\n- **Configuration changes**: Provider, model, language, or temperature changes\n- **File content changes**: File hash no longer matches\n- **Manual clearing**: Using `--clear-summarize-cache` flag\n\n#### Cache Storage\n\n```\n~/.autodev-cache/summary-cache/\n├── {project-hash-1}/\n│ └── files/\n│ ├── src-cli-tools-outline.json\n│ └── src-code-index-manager.json\n└── {project-hash-2}/\n └── files/\n └── lib-utils.json\n```\n\n#### Cache Performance\n\n- **Typical hit rate**: >90% for unchanged codebases\n- **Incremental updates**: Only re-summarizes changed blocks\n- **Batch processing**: Efficiently handles large files\n- **Atomic writes**: Safe concurrent access\n\n#### Cache Management Commands\n\n```bash\n# View cache statistics (automatic)\ncodebase outline src/index.ts --summarize\n# Output: Cache hit rate: 85% (17/20 blocks cached)\n\n# Clear all caches for current project\ncodebase --clear-summarize-cache\n\n# Clear and regenerate\ncodebase outline src/index.ts --summarize --clear-summarize-cache\n\n# Clear caches for specific project\ncodebase --clear-summarize-cache --path=/my/project\n```\n\n### Language Support\n\nThe summarizer supports multiple output languages:\n\n```json\n{\n \"summarizerLanguage\": \"English\" // or \"Chinese\"\n}\n```\n\n**Examples:**\n\nEnglish Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\nChinese Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Performance Tuning\n\nFor large codebases, adjust these parameters:\n\n```json\n{\n \"summarizerBatchSize\": 4, // Increase for faster processing (more memory)\n \"summarizerConcurrency\": 4, // Increase for parallel processing (more API calls)\n \"summarizerMaxRetries\": 5, // Increase for unreliable networks\n \"summarizerRetryDelayMs\": 2000 // Increase for rate-limited APIs\n}\n```\n\n**Trade-offs:**\n- Higher `batchSize` = Faster but more memory usage\n- Higher `concurrency` = More parallel requests but higher API load\n- Higher `maxRetries` = Better reliability but slower on failures\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Complete Configuration with All Features\n\n**File:** `./autodev-config.json`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20,\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5,\n \"rerankerBatchSize\": 10,\n \"rerankerConcurrency\": 3,\n \"rerankerMaxRetries\": 3,\n \"rerankerRetryDelayMs\": 1000,\n \n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### Chinese Language Configuration\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Production Configuration with OpenAI\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-openai-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5,\n \n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleModelId\": \"gpt-4o-mini\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-openai-key\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase config --set qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase config --set embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase config --set vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase config --set embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase config --set embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase config --set embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}, "0327148760be1150d33cf514c034924dfed29f91": {"t": 1785762738.67467, "n": 20682, "h": "6d1ba76d64b879da", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Summarizer Configuration](#summarizer-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase --get-config\n\n# View specific configuration items\ncodebase --get-config embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase --get-config --json\n\n# Set project configuration\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\n# Note: also adds `autodev-config.json` to Git global ignore (core.excludesfile) for all repos\n\n# Set global configuration\ncodebase --set-config --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json --get-config\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json --index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache --index\n\n# Working directory\ncodebase --path=/my/project --index\n\n# Debug logging\ncodebase --log-level=debug --index\n\n# Force reindex\ncodebase --force --index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `--outline <pattern>` - Extract code outline from file(s) using glob patterns\n- `--summarize` - Generate AI summaries for code outlines\n- `--title` - Show only file-level summary (no function details)\n- `--clear-summarize-cache` - Clear all summary caches for current project\n- `--dry-run` - Preview files without performing the actual operation\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--limit, -l <number>` - Maximum number of search results (overrides config, max 50)\n- `--min-score, -S <number>` - Minimum similarity score for search results 0-1 (overrides config)\n- `--json` - Output search results in JSON format\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n### CLI Runtime Override\n\nYou can override search parameters at runtime using CLI arguments:\n\n```bash\n# Override max results (limited to maximum of 50)\ncodebase --search=\"authentication\" --limit=20\ncodebase --search=\"API\" -l 30\n\n# Override minimum score (0.0-1.0)\ncodebase --search=\"user auth\" --min-score=0.7\ncodebase --search=\"database\" -S 0.5\n\n# Combine both\ncodebase --search=\"error handling\" --limit=10 --min-score=0.8\n```\n\n**Note:** CLI arguments `--limit` and `--min-score` provide temporary override for individual searches. For persistent settings, use `vectorSearchMaxResults` and `vectorSearchMinScore` in configuration files.\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n| `rerankerConcurrency` | number | No | `3` | Concurrent rerank requests |\n| `rerankerMaxRetries` | number | No | `3` | Retry attempts for failed requests |\n| `rerankerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Summarizer Configuration\n\nGenerate AI-powered summaries for code blocks with intelligent caching and batch processing.\n\n### Quick Start\n\n```bash\n# Generate intelligent code outline with AI summaries\ncodebase --outline \"src/**/*.ts\" --summarize\n```\n\n**Output Example:**\n```\n# src/cli.ts (1902 lines)\n└─ Implements a simplified CLI for @autodev/codebase using Node.js native parseArgs. \n Manages codebase indexing, searching, and MCP server operations.\n\n 27--35 | function initGlobalLogger\n └─ Initializes a global logger instance with specified log level and timestamps.\n\n 45--54 | interface SearchResult\n └─ Defines the structure for search result payloads, including file path, code chunk, \n and relevance score.\n\n ... (full outline with AI summaries)\n```\n\n**Setup (One-time):**\n```bash\n# Option 1: Ollama (free, local AI)\ncodebase --set-config summarizerProvider=ollama,summarizerOllamaModelId=qwen3-vl:4b-instruct\n\n# Option 2: DeepSeek (cost-effective API)\ncodebase --set-config summarizerProvider=openai-compatible,summarizerOpenAiCompatibleBaseUrl=https://api.deepseek.com/v1,summarizerOpenAiCompatibleModelId=deepseek-chat,summarizerOpenAiCompatibleApiKey=sk-your-key\n```\n\n**Key Benefits:**\n- 🧠 **Understand code fast** - Get function-level summaries without reading every line\n- 💾 **Smart caching** - Only summarizes changed code blocks (>90% cache hit on unchanged code)\n- 🌐 **Multi-language** - English/Chinese summaries supported\n- ⚡ **Batch processing** - Efficiently handles large codebases\n\n### Configuration Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `summarizerProvider` | string | No | `ollama` | Summarizer provider: `ollama` or `openai-compatible` |\n| `summarizerLanguage` | string | No | `English` | Output language: `English` or `Chinese` |\n| `summarizerTemperature` | number | No | - | LLM temperature (0.0-1.0), affects output randomness |\n| `summarizerBatchSize` | number | No | `2` | Number of code blocks per batch request |\n| `summarizerConcurrency` | number | No | `2` | Maximum concurrent batch requests |\n| `summarizerMaxRetries` | number | No | `3` | Maximum retry attempts for failed requests |\n| `summarizerRetryDelayMs` | number | No | `1000` | Initial retry delay in milliseconds (exponential backoff) |\n\n### Ollama Summarizer\n\n**Provider ID:** `ollama`\n\nRecommended for local development with complete privacy protection.\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### OpenAI-Compatible Summarizer\n\n**Provider ID:** `openai-compatible`\n\nFor production use with external APIs (DeepSeek, OpenAI, etc.).\n\n```json\n{\n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"summarizerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n**Supported Providers:**\n- **DeepSeek**: `https://api.deepseek.com/v1`\n- **OpenAI**: `https://api.openai.com/v1`\n- **Together AI**: `https://api.together.xyz/v1`\n- Any other OpenAI-compatible API\n\n### Summary Cache System\n\nThe summarizer uses a **two-level caching mechanism** to avoid redundant LLM calls.\n\n#### Cache Levels\n\n1. **File-level Hash**: SHA256 hash of complete file content\n - Fast detection of unchanged files\n - 100% cache hit when file unchanged\n\n2. **Block-level Hash**: SHA256 hash of individual code block + context\n - Precise detection of changed code blocks\n - Only re-summarizes modified blocks\n\n#### Cache Invalidation\n\nCache is automatically invalidated when:\n- **Configuration changes**: Provider, model, language, or temperature changes\n- **File content changes**: File hash no longer matches\n- **Manual clearing**: Using `--clear-summarize-cache` flag\n\n#### Cache Storage\n\n```\n~/.autodev-cache/summary-cache/\n├── {project-hash-1}/\n│ └── files/\n│ ├── src-cli-tools-outline.json\n│ └── src-code-index-manager.json\n└── {project-hash-2}/\n └── files/\n └── lib-utils.json\n```\n\n#### Cache Performance\n\n- **Typical hit rate**: >90% for unchanged codebases\n- **Incremental updates**: Only re-summarizes changed blocks\n- **Batch processing**: Efficiently handles large files\n- **Atomic writes**: Safe concurrent access\n\n#### Cache Management Commands\n\n```bash\n# View cache statistics (automatic)\ncodebase --outline src/index.ts --summarize\n# Output: Cache hit rate: 85% (17/20 blocks cached)\n\n# Clear all caches for current project\ncodebase --clear-summarize-cache\n\n# Clear and regenerate\ncodebase --outline src/index.ts --summarize --clear-summarize-cache\n\n# Clear caches for specific project\ncodebase --clear-summarize-cache --path=/my/project\n```\n\n### Language Support\n\nThe summarizer supports multiple output languages:\n\n```json\n{\n \"summarizerLanguage\": \"English\" // or \"Chinese\"\n}\n```\n\n**Examples:**\n\nEnglish Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\nChinese Configuration:\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Performance Tuning\n\nFor large codebases, adjust these parameters:\n\n```json\n{\n \"summarizerBatchSize\": 4, // Increase for faster processing (more memory)\n \"summarizerConcurrency\": 4, // Increase for parallel processing (more API calls)\n \"summarizerMaxRetries\": 5, // Increase for unreliable networks\n \"summarizerRetryDelayMs\": 2000 // Increase for rate-limited APIs\n}\n```\n\n**Trade-offs:**\n- Higher `batchSize` = Faster but more memory usage\n- Higher `concurrency` = More parallel requests but higher API load\n- Higher `maxRetries` = Better reliability but slower on failures\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Complete Configuration with All Features\n\n**File:** `./autodev-config.json`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20,\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5,\n \"rerankerBatchSize\": 10,\n \"rerankerConcurrency\": 3,\n \"rerankerMaxRetries\": 3,\n \"rerankerRetryDelayMs\": 1000,\n \n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaBaseUrl\": \"http://localhost:11434\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"English\",\n \"summarizerBatchSize\": 2,\n \"summarizerConcurrency\": 2,\n \"summarizerMaxRetries\": 3,\n \"summarizerRetryDelayMs\": 1000\n}\n```\n\n### Chinese Language Configuration\n\n```json\n{\n \"summarizerProvider\": \"ollama\",\n \"summarizerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"summarizerLanguage\": \"Chinese\"\n}\n```\n\n### Production Configuration with OpenAI\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-openai-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5,\n \n \"summarizerProvider\": \"openai-compatible\",\n \"summarizerOpenAiCompatibleModelId\": \"gpt-4o-mini\",\n \"summarizerOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"summarizerOpenAiCompatibleApiKey\": \"sk-your-openai-key\",\n \"summarizerLanguage\": \"English\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase --set-config qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase --index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase --set-config vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase --set-config embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase --set-config embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}, "8ffeb4011144f51c52ad0d22ffd34766c4970138": {"t": 1785762741.0906417, "n": 12070, "h": "970449b5df451f68", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase --get-config\n\n# View specific configuration items\ncodebase --get-config embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase --get-config --json\n\n# Set project configuration\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\n# Note: also adds `autodev-config.json` to Git global ignore (core.excludesfile) for all repos\n\n# Set global configuration\ncodebase --set-config --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json --get-config\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json --index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache --index\n\n# Working directory\ncodebase --path=/my/project --index\n\n# Debug logging\ncodebase --log-level=debug --index\n\n# Force reindex\ncodebase --force --index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--limit, -l <number>` - Maximum number of search results (overrides config, max 50)\n- `--min-score, -S <number>` - Minimum similarity score for search results 0-1 (overrides config)\n- `--json` - Output search results in JSON format\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n### CLI Runtime Override\n\nYou can override search parameters at runtime using CLI arguments:\n\n```bash\n# Override max results (limited to maximum of 50)\ncodebase --search=\"authentication\" --limit=20\ncodebase --search=\"API\" -l 30\n\n# Override minimum score (0.0-1.0)\ncodebase --search=\"user auth\" --min-score=0.7\ncodebase --search=\"database\" -S 0.5\n\n# Combine both\ncodebase --search=\"error handling\" --limit=10 --min-score=0.8\n```\n\n**Note:** CLI arguments `--limit` and `--min-score` provide temporary override for individual searches. For persistent settings, use `vectorSearchMaxResults` and `vectorSearchMinScore` in configuration files.\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase --set-config qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase --index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase --set-config vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase --set-config embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase --set-config embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}, "4619e567ec74450170cf8a12b96fba2d48f2d95f": {"t": 1785762744.2675793, "n": 12070, "h": "015224530b801c63", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase --get-config\n\n# View specific configuration items\ncodebase --get-config embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase --get-config --json\n\n# Set project configuration\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\n# Note: also adds `autodev-config.json` to Git global ignore (core.excludesfile) for all repos\n\n# Set global configuration\ncodebase --set-config --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json --get-config\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json --index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache --index\n\n# Working directory\ncodebase --path=/my/project --index\n\n# Debug logging\ncodebase --log-level=debug --index\n\n# Force reindex\ncodebase --force --index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--limit, -l <number>` - Maximum number of search results (overrides config, max 50)\n- `--min-score, -s <number>` - Minimum similarity score for search results 0-1 (overrides config)\n- `--json` - Output search results in JSON format\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n### CLI Runtime Override\n\nYou can override search parameters at runtime using CLI arguments:\n\n```bash\n# Override max results (limited to maximum of 50)\ncodebase --search=\"authentication\" --limit=20\ncodebase --search=\"API\" -l 30\n\n# Override minimum score (0.0-1.0)\ncodebase --search=\"user auth\" --min-score=0.7\ncodebase --search=\"database\" -s 0.5\n\n# Combine both\ncodebase --search=\"error handling\" --limit=10 --min-score=0.8\n```\n\n**Note:** CLI arguments `--limit` and `--min-score` provide temporary override for individual searches. For persistent settings, use `vectorSearchMaxResults` and `vectorSearchMinScore` in configuration files.\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase --set-config qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase --index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase --set-config vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase --set-config embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase --set-config embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}, "c463c83b031964e3a372f2522881d60f77db05e6": {"t": 1785762746.563721, "n": 12143, "h": "4e08118a311bbfec", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase --get-config\n\n# View specific configuration items\ncodebase --get-config embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase --get-config --json\n\n# Show sensitive values (API keys)\ncodebase --get-config --show-secrets\n\n# Set project configuration\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\n# Note: also adds `autodev-config.json` to Git global ignore (core.excludesfile) for all repos\n\n# Set global configuration\ncodebase --set-config --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json --get-config\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json --index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache --index\n\n# Working directory\ncodebase --path=/my/project --index\n\n# Debug logging\ncodebase --log-level=debug --index\n\n# Force reindex\ncodebase --force --index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--limit, -l <number>` - Maximum number of search results (overrides config, max 50)\n- `--min-score, -s <number>` - Minimum similarity score for search results 0-1 (overrides config)\n- `--json` - Output search results in JSON format\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n### CLI Runtime Override\n\nYou can override search parameters at runtime using CLI arguments:\n\n```bash\n# Override max results (limited to maximum of 50)\ncodebase --search=\"authentication\" --limit=20\ncodebase --search=\"API\" -l 30\n\n# Override minimum score (0.0-1.0)\ncodebase --search=\"user auth\" --min-score=0.7\ncodebase --search=\"database\" -s 0.5\n\n# Combine both\ncodebase --search=\"error handling\" --limit=10 --min-score=0.8\n```\n\n**Note:** CLI arguments `--limit` and `--min-score` provide temporary override for individual searches. For persistent settings, use `vectorSearchMaxResults` and `vectorSearchMinScore` in configuration files.\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase --set-config qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase --index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase --set-config vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase --set-config embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase --set-config embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}, "a5b819df8c1158f6547b6f61b8066b4988b74b54": {"t": 1785762748.92893, "n": 11224, "h": "e382188df619b6e7", "c": "# Configuration Reference\n\nThis document provides a comprehensive reference for all configuration options available in `@autodev/codebase`.\n\n## 📋 Table of Contents\n\n- [Configuration System](#configuration-system)\n- [Configuration Sources](#configuration-sources)\n- [Embedding Providers](#embedding-providers)\n- [Vector Store Configuration](#vector-store-configuration)\n- [Search Configuration](#search-configuration)\n- [Reranker Configuration](#reranker-configuration)\n- [Configuration Examples](#configuration-examples)\n- [Validation Rules](#validation-rules)\n- [Environment Variables](#environment-variables)\n\n## Configuration System\n\nThe tool uses a **layered configuration system** with the following priority order (highest to lowest):\n\n1. **CLI Arguments** - Runtime override for paths, logging, and operational behavior\n2. **Project Config** (`./autodev-config.json`) - Project-specific settings\n3. **Global Config** (`~/.autodev-cache/autodev-config.json`) - User-specific settings\n4. **Built-in Defaults** - Fallback values\n\n### Configuration Management Commands\n\n```bash\n# View complete configuration hierarchy\ncodebase --get-config\n\n# View specific configuration items\ncodebase --get-config embedderProvider qdrantUrl\n\n# JSON output for scripting\ncodebase --get-config --json\n\n# Show sensitive values (API keys)\ncodebase --get-config --show-secrets\n\n# Set project configuration\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\n\n# Set global configuration\ncodebase --set-config --global qdrantUrl=http://localhost:6333\n\n# Use custom config file path\ncodebase --config=/path/to/config.json --get-config\n```\n\n## Configuration Sources\n\n### 1. CLI Arguments (Highest Priority)\n\nCLI arguments provide runtime override for specific operations:\n\n**Path and Storage Options:**\n```bash\n# Custom configuration file\ncodebase --config=/path/to/custom-config.json --index\n\n# Custom storage and cache paths\ncodebase --storage=/custom/storage --cache=/custom/cache --index\n\n# Working directory\ncodebase --path=/my/project --index\n\n# Debug logging\ncodebase --log-level=debug --index\n\n# Force reindex\ncodebase --force --index\n```\n\n**Available CLI Arguments:**\n- `--config, -c <path>` - Configuration file path\n- `--storage <path>` - Custom storage path for index data\n- `--cache <path>` - Custom cache path for temporary files\n- `--log-level <level>` - Log level: debug|info|warn|error\n- `--path, -p <path>` - Working directory path\n- `--force` - Force reindex all files, ignoring cache\n- `--demo` - Create demo files in workspace for testing\n- `--path-filters, -f <filters>` - Filter search results by path patterns\n- `--json` - Output search results in JSON format\n\n### 2. Project Configuration\n\nCreate `./autodev-config.json` in your project root:\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"qdrantUrl\": \"http://localhost:6333\"\n}\n```\n\n### 3. Global Configuration\n\nLocated at `~/.autodev-cache/autodev-config.json`:\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 20\n}\n```\n\n### 4. Environment Variables\n\nAPI keys can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\nexport GEMINI_API_KEY=\"your-gemini-key\"\n```\n\n## Embedding Providers\n\n### Common Configuration Options\n\nAll providers share these options:\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `embedderProvider` | string | Yes | - | Provider identifier |\n| `embedderModelId` | string | No | Provider-specific | Model name/ID |\n| `embedderModelDimension` | number | No | Provider-specific | Vector dimension size |\n\n### 1. Ollama (Recommended)\n\n**Provider ID:** `ollama`\n\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderModelDimension\": 768,\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"embedderOllamaBatchSize\": 10\n}\n```\n\n### 2. OpenAI\n\n**Provider ID:** `openai`\n\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiApiKey\": \"sk-your-api-key\",\n \"embedderOpenAiBatchSize\": 100\n}\n```\n\n**Supported Models:**\n- `text-embedding-3-small` (1536 dimensions)\n- `text-embedding-3-large` (3072 dimensions)\n- `text-embedding-ada-002` (1536 dimensions)\n\n### 3. OpenAI-Compatible\n\n**Provider ID:** `openai-compatible`\n\n```json\n{\n \"embedderProvider\": \"openai-compatible\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderModelDimension\": 1536,\n \"embedderOpenAiCompatibleBaseUrl\": \"https://api.openai.com/v1\",\n \"embedderOpenAiCompatibleApiKey\": \"sk-your-api-key\"\n}\n```\n\n### 4. Other Providers\n\n| Provider | Provider ID | Model Example | Key Environment Variable |\n|----------|-------------|---------------|--------------------------|\n| Jina | `jina` | `jina-embeddings-v2-base-code` | `JINA_API_KEY` |\n| Gemini | `gemini` | `embedding-001` | `GEMINI_API_KEY` |\n| Mistral | `mistral` | `mistral-embed` | `MISTRAL_API_KEY` |\n| Vercel AI Gateway | `vercel-ai-gateway` | `text-embedding-3-small` | `VERCEL_AI_GATEWAY_API_KEY` |\n| OpenRouter | `openrouter` | `text-embedding-3-small` | `OPENROUTER_API_KEY` |\n\n## Vector Store Configuration\n\n### Qdrant Configuration\n\n**Required for all operations.**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `qdrantUrl` | string | Yes | `http://localhost:6333` | Qdrant server URL |\n| `qdrantApiKey` | string | No | - | Qdrant API key |\n\n```json\n{\n \"qdrantUrl\": \"http://localhost:6333\",\n \"qdrantApiKey\": \"your-qdrant-key\"\n}\n```\n\n**Docker Setup:**\n```bash\ndocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant\n```\n\n## Search Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `vectorSearchMinScore` | number | No | `0.1` | Minimum similarity score (0.0-1.0) |\n| `vectorSearchMaxResults` | number | No | `20` | Maximum number of results to return |\n\n```json\n{\n \"vectorSearchMinScore\": 0.3,\n \"vectorSearchMaxResults\": 15\n}\n```\n\n**Score Interpretation:**\n- `0.9-1.0`: Very similar (exact or near-exact match)\n- `0.7-0.9`: Highly similar (same concept, different implementation)\n- `0.5-0.7`: Moderately similar (related concepts)\n- `0.3-0.5`: Somewhat similar (loosely related)\n- `<0.3`: Low similarity (may be irrelevant)\n\n## Reranker Configuration\n\nReranking improves search results by reordering them based on semantic relevance.\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `rerankerEnabled` | boolean | No | `false` | Enable reranking |\n| `rerankerProvider` | string | No | - | Reranker provider |\n| `rerankerMinScore` | number | No | - | Minimum reranker score |\n| `rerankerBatchSize` | number | No | `10` | Reranker batch size |\n\n### Ollama Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"ollama\",\n \"rerankerOllamaModelId\": \"qwen3-vl:4b-instruct\",\n \"rerankerOllamaBaseUrl\": \"http://localhost:11434\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n### OpenAI-Compatible Reranker\n\n```json\n{\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleBaseUrl\": \"https://api.deepseek.com/v1\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\",\n \"rerankerMinScore\": 0.5\n}\n```\n\n## Configuration Examples\n\n### Ollama (Local Development)\n\n**File:** `~/.autodev-cache/autodev-config.json`\n```json\n{\n \"embedderProvider\": \"ollama\",\n \"embedderModelId\": \"nomic-embed-text\",\n \"embedderOllamaBaseUrl\": \"http://localhost:11434\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.3,\n \"rerankerEnabled\": false\n}\n```\n\n### OpenAI (Production)\n\n**File:** `./autodev-config.json`\n```json\n{\n \"embedderProvider\": \"openai\",\n \"embedderModelId\": \"text-embedding-3-small\",\n \"embedderOpenAiApiKey\": \"sk-your-key\",\n \"qdrantUrl\": \"http://localhost:6333\",\n \"vectorSearchMinScore\": 0.4,\n \"vectorSearchMaxResults\": 15,\n \"rerankerEnabled\": true,\n \"rerankerProvider\": \"openai-compatible\",\n \"rerankerOpenAiCompatibleModelId\": \"deepseek-chat\",\n \"rerankerOpenAiCompatibleApiKey\": \"sk-your-deepseek-key\"\n}\n```\n\n### Quick Setup Commands\n\n#### Ollama Setup\n```bash\n# Install and start Ollama\nbrew install ollama\nollama serve\n\n# Pull embedding model\nollama pull nomic-embed-text\n\n# Configure\ncodebase --set-config embedderProvider=ollama,embedderModelId=nomic-embed-text\ncodebase --set-config qdrantUrl=http://localhost:6333\n\n# Start indexing\ncodebase --index --log-level=debug --force\n```\n\n#### OpenAI Setup\n```bash\nexport OPENAI_API_KEY=\"sk-your-key\"\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n```\n\n## Validation Rules\n\n### Configuration Validation\n\nThe tool validates configuration automatically. Common validation rules:\n\n#### Embedder Validation\n- **Required fields**: `embedderProvider`\n- **Provider-specific fields**: Must match provider requirements\n- **Model dimensions**: Must be positive integers\n- **Batch sizes**: Must be positive integers\n\n#### Qdrant Validation\n- **URL format**: Must be valid HTTP/HTTPS URL\n- **API key**: Optional, but required if Qdrant has authentication enabled\n\n#### Search Validation\n- **Min score**: Must be between 0.0 and 1.0\n- **Max results**: Must be positive integer\n\n### Validation Error Examples\n\n```bash\n# Invalid score range\ncodebase --set-config vectorSearchMinScore=1.5\n# Error: Search minimum score must be between 0 and 1\n\n# Missing required field\ncodebase --set-config embedderModelId=nomic-embed-text\n# Error: embedderProvider is required\n\n# Invalid batch size\ncodebase --set-config embedderOllamaBatchSize=-5\n# Error: Embedder Ollama batch size must be positive\n```\n\n## Environment Variables\n\n### API Keys Mapping\n\nEnvironment variables are automatically mapped to configuration keys:\n\n| Environment Variable | Configuration Key | Provider |\n|---------------------|-------------------|----------|\n| `OPENAI_API_KEY` | `embedderOpenAiApiKey` | OpenAI |\n| `OPENAI_COMPATIBLE_API_KEY` | `embedderOpenAiCompatibleApiKey` | OpenAI-Compatible |\n| `GEMINI_API_KEY` | `embedderGeminiApiKey` | Gemini |\n| `JINA_API_KEY` | `embedderJinaApiKey` | Jina |\n| `MISTRAL_API_KEY` | `embedderMistralApiKey` | Mistral |\n| `VERCEL_AI_GATEWAY_API_KEY` | `embedderVercelAiGatewayApiKey` | Vercel AI Gateway |\n| `OPENROUTER_API_KEY` | `embedderOpenRouterApiKey` | OpenRouter |\n| `QDRANT_API_KEY` | `qdrantApiKey` | Qdrant |\n\n### Usage with Environment Variables\n\n```bash\n# Set environment variables\nexport OPENAI_API_KEY=\"sk-your-key\"\nexport QDRANT_API_KEY=\"your-qdrant-key\"\n\n# Configure tool\ncodebase --set-config embedderProvider=openai,embedderModelId=text-embedding-3-small\n\n# The tool will automatically use the environment variables\n```\n\n\n---\n\nFor additional help, see:\n- [Main README](README.md) - Quick start and basic usage\n- [GitHub Repository](https://github.com/anrgct/autodev-codebase) - Issues and contributions\n"}}}} |