# RAG Box
A powerful command-line tool for querying documents using RAG (Retrieval Augmented Generation). Built with LlamaIndex and supports both OpenAI and Ollama models.
## Features
- 🚀 **Dual Provider Support**: Use OpenAI (cloud) or Ollama (local) for LLM and embeddings
- 📚 **Smart Document Indexing**: Automatically indexes documents with configurable embeddings
- 💬 **Interactive & Direct Modes**: Single questions or continuous conversations
- 🔄 **Streaming Responses**: Real-time token streaming for faster perceived responses
- 💾 **Persistent Vector Store**: Reuses embeddings for instant subsequent queries
- 🎯 **Auto-Rebuild Detection**: Automatically rebuilds index when embedding config changes
- 📊 **Source Attribution**: Shows which documents contributed to each answer
- ⚙️ **Flexible Configuration**: JSON config files, environment variables, or CLI args
- 🎨 **Beautiful Output**: Formatted boxes with proper text wrapping
## Installation
### From PyPI (once published)
```bash
pip install ragbox
```
### From Source
```bash
git clone https://github.com/praysimanjuntak/ragbox.git
cd ragbox
pip install -e .
```
## Quick Start
### Using OpenAI (Recommended for Best Quality)
```bash
# Set your API key
export OPENAI_API_KEY='sk-...'
# Ask a question
ragbox "What is this project about?"
```
### Using Ollama (Local, No API Key Needed)
**Prerequisites**: Ollama server must be running with models pulled
```bash
# 1. Install and start Ollama server
# Download from https://ollama.ai
ollama serve
# 2. Pull models (required before using)
# Embedding model (choose one):
ollama pull embeddinggemma # Recommended for embeddings
# LLM model (choose any model you prefer):
ollama pull granite4:micro # Fast, 500MB
ollama pull llama3.2:3b # More capable, 2GB
ollama pull qwen2.5:7b # High quality, 4.7GB
ollama pull mistral:latest # Or any other model you prefer
# 3. Create and configure
ragbox --init
# 4. Edit .rag_config.json to use ollama provider
# Set "llm_model" to any model you've pulled (e.g., "llama3.2:3b")
# 5. Ask questions
ragbox "What is this project about?"
```
**Note**: Replace `granite4:micro` with any Ollama model you've pulled. See available models at https://ollama.ai/library
## Usage
### Basic Commands
```bash
# Ask a single question
ragbox "What is the main purpose of this codebase?"
# Interactive mode
ragbox
# Specify documents directory
ragbox -d /path/to/docs "Summarize the key features"
# Force rebuild index
ragbox --rebuild
# List indexed files
ragbox --list-files
# Verbose output (show timing and config)
ragbox --verbose "question"
# Plain text output (easy to copy)
ragbox --format copy "question"
```
### Command-Line Options
```
usage: ragbox [-h] [-d DOCS_DIR] [-s STORAGE_DIR] [-m MODEL] [--rebuild]
[--list-files] [-v] [--format {box,copy}] [--init] [question]
positional arguments:
question Question to ask (if not provided, enters interactive mode)
options:
-h, --help show this help message and exit
-d DOCS_DIR, --docs-dir DOCS_DIR
Directory containing documents (default: current directory)
-s STORAGE_DIR, --storage-dir STORAGE_DIR
Directory for storing index (default: .storage)
-m MODEL, --model MODEL
LLM model to use
--rebuild Force rebuild of index
--list-files List indexed files and exit
-v, --verbose Show detailed initialization logs
--format {box,copy} Output format: 'box' (default) or 'copy' (plain text)
--init Create a default .rag_config.json file
```
## Configuration
### Configuration File
Create a `.rag_config.json` file in your project directory:
```bash
ragbox --init
```
Example configuration:
```json
{
"embedding_model": "text-embedding-3-small",
"embedding_provider": "openai",
"embedding_base_url": "http://localhost:11434",
"embedding_dimensions": 1536,
"llm_model": "gpt-4o-mini",
"llm_provider": "openai",
"request_timeout": 360,
"context_window": 32000,
"chat_mode": "context",
"streaming": true,
"system_prompt": "You are a helpful assistant that analyzes documents and answers questions based on the provided context. Always cite relevant information from the documents."
}
```
### Provider Options
**OpenAI (Recommended)**
```json
{
"embedding_provider": "openai",
"embedding_model": "text-embedding-3-small",
"llm_provider": "openai",
"llm_model": "gpt-4o-mini"
}
```
**Ollama (Local)**
```json
{
"embedding_provider": "ollama",
"embedding_model": "embeddinggemma",
"llm_provider": "ollama",
"llm_model": "granite4:micro"
}
```
**Note**: You can use any Ollama model for `llm_model` - just replace `granite4:micro` with any model you've pulled (e.g., `llama3.2:3b`, `mistral:latest`, `qwen2.5:7b`, etc.). See all available models at https://ollama.ai/library
**Mix and Match Providers**
You can use different providers for embeddings and LLM:
```json
{
"embedding_provider": "ollama",
"embedding_model": "embeddinggemma",
"llm_provider": "openai",
"llm_model": "gpt-4o-mini"
}
```
### Switching Between Providers
To switch from Ollama to OpenAI (or vice versa):
1. **Edit `.rag_config.json`** and update the provider settings:
```json
{
"embedding_provider": "openai",
"embedding_model": "text-embedding-3-small",
"llm_provider": "openai",
"llm_model": "gpt-4o-mini"
}
```
2. **Set your API key** (for OpenAI):
```bash
export OPENAI_API_KEY='sk-...'
```
3. **Rebuild the index** (required when changing embedding provider):
```bash
ragbox --rebuild
```
**Note**: When you change the embedding provider or model, the index will automatically rebuild on the next run.
### Environment Variables
```bash
# Required for OpenAI
export OPENAI_API_KEY='sk-...'
# Optional overrides
export RAG_EMBEDDING_MODEL="text-embedding-3-small"
export RAG_EMBEDDING_PROVIDER="openai"
export RAG_LLM_MODEL="gpt-4o-mini"
export RAG_LLM_PROVIDER="openai"
export RAG_CHAT_MODE="context"
export RAG_STREAMING="true"
```
## How It Works
1. **First Run**: Loads documents → Creates embeddings → Saves vector index
2. **Subsequent Runs**: Loads existing index (instant startup)
3. **Config Change Detection**: Automatically rebuilds if embedding config changes
4. **Query Processing**:
- Embeds your question
- Retrieves relevant document chunks
- Sends context + question to LLM
- Streams back the answer with sources
## Supported File Types
- **Text files**: `.txt`, `.md`, `.rst`
- **Code files**: `.py`, `.js`, `.java`, `.cpp`, `.go`, `.ts`, `.html`, `.css`, `.sh`, etc.
- **Documents**: `.pdf`, `.docx`, `.epub`, `.ppt`, `.pptx`, `.pptm`
- **Data files**: `.csv`, `.json`, `.yaml`, `.xml`
- **Notebooks**: `.ipynb` (Jupyter Notebooks)
- **Images**: `.png`, `.jpg`, `.jpeg` (with OCR/vision capabilities)
- **Media**: `.mp3`, `.mp4` (audio/video transcription)
- **Email**: `.mbox` (email archives)
- **Other**: `.hwp` (Hangul Word Processor)
All files are processed via LlamaIndex's SimpleDirectoryReader, which automatically detects file types and uses appropriate parsers.
### Auto-Excluded
- `.storage`, `.git`, `.venv`, `venv`, `node_modules`
- `__pycache__`, `.pytest_cache`, `.mypy_cache`
- `*.log`, `*.pyc`
## Examples
### Analyze a Codebase
```bash
cd my-project
ragbox "Explain the authentication flow"
ragbox "Are there any security issues?"
ragbox "How is the database configured?"
```
### Query CCTV/Security Logs
Perfect for analyzing large log files quickly:
```bash
# Point to your logs directory
cd /var/log/security
ragbox "Show me all failed login attempts from yesterday"
ragbox "Were there any suspicious access patterns?"
ragbox "Summarize the security events from IP 192.168.1.100"
# Or specify the directory
ragbox -d /var/log/cctv "When did motion detection trigger last night?"
ragbox -d /var/log/cctv "List all events between 10pm and 6am"
```
**How it works**: RAG CLI indexes all log files, allowing you to ask natural language questions instead of manually searching through thousands of lines. The AI retrieves relevant log entries and provides contextual answers.
### Research Papers
```bash
ragbox -d ~/papers "Compare the methodologies"
ragbox -d ~/papers "What are the main findings?"
```
### Documentation
```bash
ragbox -d ./docs "How do I setup the project?"
ragbox -d ./docs --rebuild # After updating docs
```
### Interactive Session
```bash
$ ragbox
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💬 RAG Box - Interactive Mode
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 Documents: /home/user/docs
📚 Indexed files: 42
🤖 Model: gpt-4o-mini
Commands:
/exit, /quit - Exit the program
/files - List indexed files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❯ What are the main topics covered?
[Answer with sources...]
❯ Tell me more about topic X
[Continued conversation with context...]
❯ /exit
👋 Goodbye!
```
## Troubleshooting
### OpenAI API Key Issues
```bash
# Verify key is set
echo $OPENAI_API_KEY
# Set the key
export OPENAI_API_KEY='sk-...'
```
### Ollama Connection Issues
**Important**: Make sure Ollama server is running and required models are pulled!
```bash
# Start Ollama server (required!)
ollama serve
# Check what's running
ollama ps
# Pull required models if not already pulled
ollama pull embeddinggemma # For embeddings
ollama pull granite4:micro # For LLM (or any other model)
# Verify models are available
ollama list
# Keep models loaded in memory for faster response
ollama run granite4:micro
# Press Ctrl+D to exit but keep loaded
```
Common issues:
- **"Connection refused"**: Ollama server not running → Run `ollama serve`
- **"Model not found"**: Models not pulled → Run `ollama pull <model-name>`
- **Slow responses**: Models loading from disk → Keep them loaded with `ollama run <model>`
### Index/Embedding Mismatch
Don't worry! The tool automatically detects config changes and rebuilds:
```bash
# Or force rebuild manually
ragbox --rebuild
```
### No Documents Found
```bash
# Check current directory
ls -la
# Specify directory explicitly
ragbox -d /path/to/docs "question"
```
## Performance Tips
1. **OpenAI**: Faster embeddings, better quality, requires API key
2. **Ollama**: Free, local, but slower (keep models loaded: `ollama run model`)
3. **Index Reuse**: First run is slow (embedding creation), subsequent runs are instant
4. **Streaming**: Enabled by default for faster perceived response
5. **Model Choice**: Smaller models (granite4:micro) faster, larger models (gpt-4o) better quality
## Development
```bash
git clone https://github.com/praysimanjuntak/ragbox.git
cd ragbox
pip install -e ".[dev]"
```
## Roadmap
- [x] OpenAI and Ollama support
- [x] Streaming responses
- [x] Auto-rebuild on config change
- [x] Source attribution
- [x] Interactive mode
- [x] Configurable output format
- [ ] **Image document support with OCR** (planned for next update)
- [ ] Web search integration
- [ ] Conversation history export
- [ ] Query caching
## License
MIT License
## Acknowledgments
- [LlamaIndex](https://www.llamaindex.ai/) - RAG framework
- [OpenAI](https://openai.com/) - Cloud embeddings and LLMs
- [Ollama](https://ollama.ai/) - Local LLM runtime
---
**Author**: Pray Apostel Simanjuntak
If you find this project helpful, please consider giving it a ⭐ on [GitHub](https://github.com/praysimanjuntak/ragbox)!
Raw data
{
"_id": null,
"home_page": null,
"name": "ragbox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "rag, llm, cli, llamaindex, ollama, openai, question-answering, documents",
"author": null,
"author_email": "Pray Apostel Simanjuntak <simanjuntakpray@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/42/6f/9bceef93d469faee8cc16b99d5ac9c0e4e8bab808ac4c4b2062afc0ec814/ragbox-0.1.1.tar.gz",
"platform": null,
"description": "# RAG Box\n\nA powerful command-line tool for querying documents using RAG (Retrieval Augmented Generation). Built with LlamaIndex and supports both OpenAI and Ollama models.\n\n## Features\n\n- \ud83d\ude80 **Dual Provider Support**: Use OpenAI (cloud) or Ollama (local) for LLM and embeddings\n- \ud83d\udcda **Smart Document Indexing**: Automatically indexes documents with configurable embeddings\n- \ud83d\udcac **Interactive & Direct Modes**: Single questions or continuous conversations\n- \ud83d\udd04 **Streaming Responses**: Real-time token streaming for faster perceived responses\n- \ud83d\udcbe **Persistent Vector Store**: Reuses embeddings for instant subsequent queries\n- \ud83c\udfaf **Auto-Rebuild Detection**: Automatically rebuilds index when embedding config changes\n- \ud83d\udcca **Source Attribution**: Shows which documents contributed to each answer\n- \u2699\ufe0f **Flexible Configuration**: JSON config files, environment variables, or CLI args\n- \ud83c\udfa8 **Beautiful Output**: Formatted boxes with proper text wrapping\n\n## Installation\n\n### From PyPI (once published)\n\n```bash\npip install ragbox\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/praysimanjuntak/ragbox.git\ncd ragbox\npip install -e .\n```\n\n## Quick Start\n\n### Using OpenAI (Recommended for Best Quality)\n\n```bash\n# Set your API key\nexport OPENAI_API_KEY='sk-...'\n\n# Ask a question\nragbox \"What is this project about?\"\n```\n\n### Using Ollama (Local, No API Key Needed)\n\n**Prerequisites**: Ollama server must be running with models pulled\n\n```bash\n# 1. Install and start Ollama server\n# Download from https://ollama.ai\nollama serve\n\n# 2. Pull models (required before using)\n# Embedding model (choose one):\nollama pull embeddinggemma # Recommended for embeddings\n\n# LLM model (choose any model you prefer):\nollama pull granite4:micro # Fast, 500MB\nollama pull llama3.2:3b # More capable, 2GB\nollama pull qwen2.5:7b # High quality, 4.7GB\nollama pull mistral:latest # Or any other model you prefer\n\n# 3. Create and configure\nragbox --init\n\n# 4. Edit .rag_config.json to use ollama provider\n# Set \"llm_model\" to any model you've pulled (e.g., \"llama3.2:3b\")\n# 5. Ask questions\nragbox \"What is this project about?\"\n```\n\n**Note**: Replace `granite4:micro` with any Ollama model you've pulled. See available models at https://ollama.ai/library\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Ask a single question\nragbox \"What is the main purpose of this codebase?\"\n\n# Interactive mode\nragbox\n\n# Specify documents directory\nragbox -d /path/to/docs \"Summarize the key features\"\n\n# Force rebuild index\nragbox --rebuild\n\n# List indexed files\nragbox --list-files\n\n# Verbose output (show timing and config)\nragbox --verbose \"question\"\n\n# Plain text output (easy to copy)\nragbox --format copy \"question\"\n```\n\n### Command-Line Options\n\n```\nusage: ragbox [-h] [-d DOCS_DIR] [-s STORAGE_DIR] [-m MODEL] [--rebuild]\n [--list-files] [-v] [--format {box,copy}] [--init] [question]\n\npositional arguments:\n question Question to ask (if not provided, enters interactive mode)\n\noptions:\n -h, --help show this help message and exit\n -d DOCS_DIR, --docs-dir DOCS_DIR\n Directory containing documents (default: current directory)\n -s STORAGE_DIR, --storage-dir STORAGE_DIR\n Directory for storing index (default: .storage)\n -m MODEL, --model MODEL\n LLM model to use\n --rebuild Force rebuild of index\n --list-files List indexed files and exit\n -v, --verbose Show detailed initialization logs\n --format {box,copy} Output format: 'box' (default) or 'copy' (plain text)\n --init Create a default .rag_config.json file\n```\n\n## Configuration\n\n### Configuration File\n\nCreate a `.rag_config.json` file in your project directory:\n\n```bash\nragbox --init\n```\n\nExample configuration:\n\n```json\n{\n \"embedding_model\": \"text-embedding-3-small\",\n \"embedding_provider\": \"openai\",\n \"embedding_base_url\": \"http://localhost:11434\",\n \"embedding_dimensions\": 1536,\n \"llm_model\": \"gpt-4o-mini\",\n \"llm_provider\": \"openai\",\n \"request_timeout\": 360,\n \"context_window\": 32000,\n \"chat_mode\": \"context\",\n \"streaming\": true,\n \"system_prompt\": \"You are a helpful assistant that analyzes documents and answers questions based on the provided context. Always cite relevant information from the documents.\"\n}\n```\n\n### Provider Options\n\n**OpenAI (Recommended)**\n```json\n{\n \"embedding_provider\": \"openai\",\n \"embedding_model\": \"text-embedding-3-small\",\n \"llm_provider\": \"openai\",\n \"llm_model\": \"gpt-4o-mini\"\n}\n```\n\n**Ollama (Local)**\n```json\n{\n \"embedding_provider\": \"ollama\",\n \"embedding_model\": \"embeddinggemma\",\n \"llm_provider\": \"ollama\",\n \"llm_model\": \"granite4:micro\"\n}\n```\n\n**Note**: You can use any Ollama model for `llm_model` - just replace `granite4:micro` with any model you've pulled (e.g., `llama3.2:3b`, `mistral:latest`, `qwen2.5:7b`, etc.). See all available models at https://ollama.ai/library\n\n**Mix and Match Providers**\n\nYou can use different providers for embeddings and LLM:\n\n```json\n{\n \"embedding_provider\": \"ollama\",\n \"embedding_model\": \"embeddinggemma\",\n \"llm_provider\": \"openai\",\n \"llm_model\": \"gpt-4o-mini\"\n}\n```\n\n### Switching Between Providers\n\nTo switch from Ollama to OpenAI (or vice versa):\n\n1. **Edit `.rag_config.json`** and update the provider settings:\n ```json\n {\n \"embedding_provider\": \"openai\",\n \"embedding_model\": \"text-embedding-3-small\",\n \"llm_provider\": \"openai\",\n \"llm_model\": \"gpt-4o-mini\"\n }\n ```\n\n2. **Set your API key** (for OpenAI):\n ```bash\n export OPENAI_API_KEY='sk-...'\n ```\n\n3. **Rebuild the index** (required when changing embedding provider):\n ```bash\n ragbox --rebuild\n ```\n\n**Note**: When you change the embedding provider or model, the index will automatically rebuild on the next run.\n\n### Environment Variables\n\n```bash\n# Required for OpenAI\nexport OPENAI_API_KEY='sk-...'\n\n# Optional overrides\nexport RAG_EMBEDDING_MODEL=\"text-embedding-3-small\"\nexport RAG_EMBEDDING_PROVIDER=\"openai\"\nexport RAG_LLM_MODEL=\"gpt-4o-mini\"\nexport RAG_LLM_PROVIDER=\"openai\"\nexport RAG_CHAT_MODE=\"context\"\nexport RAG_STREAMING=\"true\"\n```\n\n## How It Works\n\n1. **First Run**: Loads documents \u2192 Creates embeddings \u2192 Saves vector index\n2. **Subsequent Runs**: Loads existing index (instant startup)\n3. **Config Change Detection**: Automatically rebuilds if embedding config changes\n4. **Query Processing**:\n - Embeds your question\n - Retrieves relevant document chunks\n - Sends context + question to LLM\n - Streams back the answer with sources\n\n## Supported File Types\n\n- **Text files**: `.txt`, `.md`, `.rst`\n- **Code files**: `.py`, `.js`, `.java`, `.cpp`, `.go`, `.ts`, `.html`, `.css`, `.sh`, etc.\n- **Documents**: `.pdf`, `.docx`, `.epub`, `.ppt`, `.pptx`, `.pptm`\n- **Data files**: `.csv`, `.json`, `.yaml`, `.xml`\n- **Notebooks**: `.ipynb` (Jupyter Notebooks)\n- **Images**: `.png`, `.jpg`, `.jpeg` (with OCR/vision capabilities)\n- **Media**: `.mp3`, `.mp4` (audio/video transcription)\n- **Email**: `.mbox` (email archives)\n- **Other**: `.hwp` (Hangul Word Processor)\n\nAll files are processed via LlamaIndex's SimpleDirectoryReader, which automatically detects file types and uses appropriate parsers.\n\n### Auto-Excluded\n\n- `.storage`, `.git`, `.venv`, `venv`, `node_modules`\n- `__pycache__`, `.pytest_cache`, `.mypy_cache`\n- `*.log`, `*.pyc`\n\n## Examples\n\n### Analyze a Codebase\n\n```bash\ncd my-project\nragbox \"Explain the authentication flow\"\nragbox \"Are there any security issues?\"\nragbox \"How is the database configured?\"\n```\n\n### Query CCTV/Security Logs\n\nPerfect for analyzing large log files quickly:\n\n```bash\n# Point to your logs directory\ncd /var/log/security\nragbox \"Show me all failed login attempts from yesterday\"\nragbox \"Were there any suspicious access patterns?\"\nragbox \"Summarize the security events from IP 192.168.1.100\"\n\n# Or specify the directory\nragbox -d /var/log/cctv \"When did motion detection trigger last night?\"\nragbox -d /var/log/cctv \"List all events between 10pm and 6am\"\n```\n\n**How it works**: RAG CLI indexes all log files, allowing you to ask natural language questions instead of manually searching through thousands of lines. The AI retrieves relevant log entries and provides contextual answers.\n\n### Research Papers\n\n```bash\nragbox -d ~/papers \"Compare the methodologies\"\nragbox -d ~/papers \"What are the main findings?\"\n```\n\n### Documentation\n\n```bash\nragbox -d ./docs \"How do I setup the project?\"\nragbox -d ./docs --rebuild # After updating docs\n```\n\n### Interactive Session\n\n```bash\n$ ragbox\n\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\ud83d\udcac RAG Box - Interactive Mode\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\ud83d\udcc1 Documents: /home/user/docs\n\ud83d\udcda Indexed files: 42\n\ud83e\udd16 Model: gpt-4o-mini\n\nCommands:\n /exit, /quit - Exit the program\n /files - List indexed files\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\n\u276f What are the main topics covered?\n[Answer with sources...]\n\n\u276f Tell me more about topic X\n[Continued conversation with context...]\n\n\u276f /exit\n\ud83d\udc4b Goodbye!\n```\n\n## Troubleshooting\n\n### OpenAI API Key Issues\n\n```bash\n# Verify key is set\necho $OPENAI_API_KEY\n\n# Set the key\nexport OPENAI_API_KEY='sk-...'\n```\n\n### Ollama Connection Issues\n\n**Important**: Make sure Ollama server is running and required models are pulled!\n\n```bash\n# Start Ollama server (required!)\nollama serve\n\n# Check what's running\nollama ps\n\n# Pull required models if not already pulled\nollama pull embeddinggemma # For embeddings\nollama pull granite4:micro # For LLM (or any other model)\n\n# Verify models are available\nollama list\n\n# Keep models loaded in memory for faster response\nollama run granite4:micro\n# Press Ctrl+D to exit but keep loaded\n```\n\nCommon issues:\n- **\"Connection refused\"**: Ollama server not running \u2192 Run `ollama serve`\n- **\"Model not found\"**: Models not pulled \u2192 Run `ollama pull <model-name>`\n- **Slow responses**: Models loading from disk \u2192 Keep them loaded with `ollama run <model>`\n\n### Index/Embedding Mismatch\n\nDon't worry! The tool automatically detects config changes and rebuilds:\n\n```bash\n# Or force rebuild manually\nragbox --rebuild\n```\n\n### No Documents Found\n\n```bash\n# Check current directory\nls -la\n\n# Specify directory explicitly\nragbox -d /path/to/docs \"question\"\n```\n\n## Performance Tips\n\n1. **OpenAI**: Faster embeddings, better quality, requires API key\n2. **Ollama**: Free, local, but slower (keep models loaded: `ollama run model`)\n3. **Index Reuse**: First run is slow (embedding creation), subsequent runs are instant\n4. **Streaming**: Enabled by default for faster perceived response\n5. **Model Choice**: Smaller models (granite4:micro) faster, larger models (gpt-4o) better quality\n\n## Development\n\n```bash\ngit clone https://github.com/praysimanjuntak/ragbox.git\ncd ragbox\npip install -e \".[dev]\"\n```\n\n## Roadmap\n\n- [x] OpenAI and Ollama support\n- [x] Streaming responses\n- [x] Auto-rebuild on config change\n- [x] Source attribution\n- [x] Interactive mode\n- [x] Configurable output format\n- [ ] **Image document support with OCR** (planned for next update)\n- [ ] Web search integration\n- [ ] Conversation history export\n- [ ] Query caching\n\n## License\n\nMIT License\n\n## Acknowledgments\n\n- [LlamaIndex](https://www.llamaindex.ai/) - RAG framework\n- [OpenAI](https://openai.com/) - Cloud embeddings and LLMs\n- [Ollama](https://ollama.ai/) - Local LLM runtime\n\n---\n\n**Author**: Pray Apostel Simanjuntak\n\nIf you find this project helpful, please consider giving it a \u2b50 on [GitHub](https://github.com/praysimanjuntak/ragbox)!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A command-line RAG tool for querying documents using LlamaIndex with OpenAI and Ollama support",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/praysimanjuntak/ragbox",
"Issues": "https://github.com/praysimanjuntak/ragbox/issues",
"Repository": "https://github.com/praysimanjuntak/ragbox"
},
"split_keywords": [
"rag",
" llm",
" cli",
" llamaindex",
" ollama",
" openai",
" question-answering",
" documents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "971578079ee8fc12ae7cf63df1899faf74e92f85513bf2e1cb318572c2b53a11",
"md5": "ff47556d2f2a4bd8df8d264c6d1398fd",
"sha256": "7dced66b33692b50440adfac0cab32c8c8be34e438510395cb69c3888c035ac7"
},
"downloads": -1,
"filename": "ragbox-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff47556d2f2a4bd8df8d264c6d1398fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17210,
"upload_time": "2025-10-13T12:25:52",
"upload_time_iso_8601": "2025-10-13T12:25:52.946098Z",
"url": "https://files.pythonhosted.org/packages/97/15/78079ee8fc12ae7cf63df1899faf74e92f85513bf2e1cb318572c2b53a11/ragbox-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "426f9bceef93d469faee8cc16b99d5ac9c0e4e8bab808ac4c4b2062afc0ec814",
"md5": "5259613143c5fb5974e4146c05a3ec0f",
"sha256": "5569d16ea2c4d61f2a765965cbde5e234ba6ce35008d9e9873dd6085db11c6d1"
},
"downloads": -1,
"filename": "ragbox-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "5259613143c5fb5974e4146c05a3ec0f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20600,
"upload_time": "2025-10-13T12:25:54",
"upload_time_iso_8601": "2025-10-13T12:25:54.274080Z",
"url": "https://files.pythonhosted.org/packages/42/6f/9bceef93d469faee8cc16b99d5ac9c0e4e8bab808ac4c4b2062afc0ec814/ragbox-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-13 12:25:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "praysimanjuntak",
"github_project": "ragbox",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ragbox"
}
JSON
