{"id":32460114,"url":"https://github.com/rduffyuk/querymind","last_synced_at":"2026-04-16T10:02:32.130Z","repository":{"id":320609687,"uuid":"1082713783","full_name":"rduffyuk/querymind","owner":"rduffyuk","description":"🧠 Intelligent RAG with smart query routing - Choose the right search strategy automatically (FastSearch \u003c1s, DeepResearch ~10s, WebSearch 2-5s)","archived":false,"fork":false,"pushed_at":"2025-10-24T18:02:58.000Z","size":106,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-24T20:13:30.329Z","etag":null,"topics":["ai","chromadb","claude-code","intelligent-routing","llm","mcp","ollama","rag","semantic-search","vector-database"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rduffyuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-24T16:48:12.000Z","updated_at":"2025-10-24T19:49:34.000Z","dependencies_parsed_at":"2025-10-24T20:13:32.561Z","dependency_job_id":"f1856701-640a-42d8-80df-498d501798e4","html_url":"https://github.com/rduffyuk/querymind","commit_stats":null,"previous_names":["rduffyuk/querymind"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rduffyuk/querymind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rduffyuk%2Fquerymind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rduffyuk%2Fquerymind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rduffyuk%2Fquerymind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rduffyuk%2Fquerymind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rduffyuk","download_url":"https://codeload.github.com/rduffyuk/querymind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rduffyuk%2Fquerymind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31880884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T09:23:21.276Z","status":"ssl_error","status_checked_at":"2026-04-16T09:23:15.028Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chromadb","claude-code","intelligent-routing","llm","mcp","ollama","rag","semantic-search","vector-database"],"created_at":"2025-10-26T11:21:44.956Z","updated_at":"2026-04-16T10:02:32.124Z","avatar_url":"https://github.com/rduffyuk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QueryMind\n\n\u003e Multi-agent RAG system with intelligent query routing, semantic search, and web fallback\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://img.shields.io/badge/tests-25%20passing-brightgreen.svg)](./tests)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nQueryMind is a lightweight, production-ready Retrieval-Augmented Generation (RAG) system that combines ChromaDB vector search, Ollama LLM intelligence, and web search capabilities to provide accurate, context-aware responses from your knowledge base.\n\n## ✨ Features\n\n- **🤖 Intelligent Query Routing** - Automatically routes queries to the optimal search strategy\n- **🔍 Semantic Search** - ChromaDB-powered vector search with mxbai-embed-large embeddings\n- **💡 LLM Intent Analysis** - Ollama integration for query understanding and keyword extraction\n- **🌐 Web Search Fallback** - Seamless fallback to Serper.dev when vault has no results\n- **📊 Structured Logging** - Environment-based logging with debug, info, warning, error levels\n- **🛡️ Security Hardened** - Input sanitization, injection protection, and validation\n- **🧪 Fully Tested** - 27 tests covering imports, routing logic, and security\n- **📦 Pip Installable** - Standard Python package with pyproject.toml\n\n## 🏗️ Architecture\n\nQueryMind implements a **multi-agent architecture** with intelligent routing:\n\n```\nUser Query → Router → [ Fast Search Agent   ] → Results\n                      [ Deep Research Agent ]\n                      [ Web Search (fallback) ]\n```\n\n### Agent Types\n\n1. **FastSearchAgent** - Direct keyword matching for simple queries (\u003c1s)\n2. **DeepResearchAgent** - Ollama-powered semantic analysis for complex questions (~10s)\n3. **WebSearchClient** - Serper.dev API integration for external knowledge\n\n### Query Routing Heuristics\n\nQueries are automatically routed based on:\n- **Length**: \u003e10 words → Deep Research\n- **Question words**: \"how\", \"why\", \"what\", \"explain\" → Deep Research\n- **Logical operators**: \"and\", \"or\", \"not\" → Deep Research\n- **Default**: Simple keywords → Fast Search\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n**System Requirements:**\n- Python 3.9 or higher\n- 8GB+ RAM (16GB recommended for better performance)\n- (Optional) NVIDIA GPU for faster embeddings\n\n**Required Services:**\n- **Ollama** - Local LLM inference (mistral:7b or similar)\n- **ChromaDB** - Vector database for semantic search\n- **Redis** - Query caching (optional but recommended)\n\n### Step 1: Install Ollama\n\nOllama provides local LLM inference for query analysis.\n\n**macOS / Linux:**\n```bash\n# Install Ollama\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# Pull the mistral model (7B parameters, ~4GB)\nollama pull mistral:7b\n\n# Verify installation\nollama list\n```\n\n**Windows:**\n1. Download installer from https://ollama.com/download\n2. Run installer and follow prompts\n3. Open PowerShell and run: `ollama pull mistral:7b`\n\n**Verify Ollama is running:**\n```bash\ncurl http://localhost:11434/api/tags\n# Should return list of installed models\n```\n\n### Step 2: Install ChromaDB\n\nChromaDB provides vector search capabilities.\n\n**Option A: Install as Python package (Recommended for development)**\n```bash\n# ChromaDB will be installed automatically with QueryMind\n# It runs in-process (no separate server needed)\n```\n\n**Option B: Run ChromaDB server (Recommended for production)**\n```bash\n# Install ChromaDB server\npip install chromadb\n\n# Run ChromaDB server\nchroma run --host localhost --port 8000\n\n# Verify server is running\ncurl http://localhost:8000/api/v1/heartbeat\n```\n\n### Step 3: Install Redis (Optional)\n\nRedis provides query caching for better performance (73% cache hit rate).\n\n**macOS:**\n```bash\nbrew install redis\nbrew services start redis\n```\n\n**Ubuntu/Debian:**\n```bash\nsudo apt update\nsudo apt install redis-server\nsudo systemctl start redis\n```\n\n**Windows:**\n```bash\n# Download from https://github.com/microsoftarchive/redis/releases\n# Or use WSL2 with Ubuntu instructions above\n```\n\n**Verify Redis:**\n```bash\nredis-cli ping\n# Should return: PONG\n```\n\n### Step 4: Install QueryMind\n\n```bash\n# Clone the repository\ngit clone https://github.com/rduffyuk/querymind.git\ncd querymind\n\n# Create virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install QueryMind with all dependencies\npip install .\n\n# Or install in development mode\npip install -e \".[dev]\"\n```\n\n### Step 5: Configure Environment\n\nCreate a `.env` file from the example:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your settings:\n\n```bash\n# Required - Path to your markdown documents\nVAULT_PATH=/path/to/your/obsidian-vault\n\n# ChromaDB settings\nCHROMADB_URL=http://localhost:8000  # Or leave blank for in-process mode\n\n# Redis settings (optional - will fall back to in-memory cache)\nREDIS_URL=redis://localhost:6379\n\n# Ollama settings\nOLLAMA_API_URL=http://localhost:11434\n\n# Optional - Web search API key (100 free queries/month)\nSERPER_API_KEY=your-api-key-here\n\n# Logging\nLOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR\n```\n\n### Step 6: Verify Installation\n\nRun the test suite to verify everything is working:\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Should see: 25 passed, 2 skipped\n```\n\nTest a simple query:\n\n```python\nfrom querymind import auto_search\n\n# Simple test query\nresult = auto_search(\"test query\", n_results=1)\nprint(f\"Status: {result.status}\")\nprint(f\"Agent: {result.agent_type}\")\n```\n\n### Optional: Get Serper.dev API Key\n\nFor web search fallback functionality:\n\n1. Sign up at https://serper.dev\n2. Get your API key from the dashboard\n3. Add to `.env`: `SERPER_API_KEY=your-key-here`\n4. Free tier: 100 queries/month\n5. After free tier: $0.30 per 1,000 queries\n\n### Optional: Install Obsidian for Document Management\n\nObsidian is a powerful markdown editor that works well for managing the document vault that QueryMind searches. While not required, it provides a great interface for creating and organizing your knowledge base.\n\n**macOS:**\n```bash\n# Download from website\nopen https://obsidian.md/download\n\n# Or install via Homebrew\nbrew install --cask obsidian\n```\n\n**Linux:**\n```bash\n# Download AppImage from website\nwget https://github.com/obsidianmd/obsidian-releases/releases/download/v1.4.16/Obsidian-1.4.16.AppImage\n\n# Make executable and run\nchmod +x Obsidian-1.4.16.AppImage\n./Obsidian-1.4.16.AppImage\n\n# Or install via Snap\nsudo snap install obsidian --classic\n```\n\n**Windows:**\n```bash\n# Download installer from website\nstart https://obsidian.md/download\n\n# Or install via Chocolatey\nchoco install obsidian\n```\n\n**Setup your vault:**\n1. Open Obsidian\n2. Create a new vault or open existing vault at `VAULT_PATH` from your `.env`\n3. Start creating markdown documents\n4. QueryMind will automatically index and search these documents\n\n### Troubleshooting\n\n**Ollama connection failed:**\n```bash\n# Check if Ollama is running\nollama list\n\n# Restart Ollama\n# macOS/Linux: sudo systemctl restart ollama\n# Windows: Restart Ollama Desktop app\n```\n\n**ChromaDB errors:**\n```bash\n# If using server mode, check if running\ncurl http://localhost:8000/api/v1/heartbeat\n\n# If in-process mode, ensure adequate RAM\n# ChromaDB needs ~2-4GB for mxbai-embed-large model\n```\n\n**Redis not available:**\n```bash\n# QueryMind will fall back to in-memory cache\n# To use Redis, ensure it's running:\nredis-cli ping\n```\n\n## 📖 Usage\n\n### Basic Search\n\n```python\nfrom querymind import auto_search\n\n# Simple query (uses FastSearchAgent)\nresult = auto_search(\"Redis caching\")\nprint(f\"Found {result.result_count} results\")\nfor r in result.results:\n    print(f\"  - {r['file']}: {r['score']:.2f}\")\n\n# Complex query (uses DeepResearchAgent)\nresult = auto_search(\"How to implement Redis caching for APIs?\")\nprint(f\"Agent: {result.agent_type}\")\nprint(f\"Time: {result.elapsed_time:.2f}s\")\n```\n\n### Advanced Usage\n\n```python\nfrom querymind.agents.router import AgentRouter\n\n# Initialize router with custom configuration\nrouter = AgentRouter(\n    model=\"mistral:7b\",\n    enable_web_fallback=True\n)\n\n# Execute search with verbose logging\nresult = router.search(\n    query=\"Explain StatefulSet vs Deployment\",\n    n_results=10,\n    verbose=True\n)\n\n# Get routing statistics\nstats = router.get_stats()\nprint(f\"Fast searches: {stats['fast_searches']}\")\nprint(f\"Deep searches: {stats['deep_searches']}\")\n```\n\n### Direct Agent Access\n\n```python\nfrom querymind.agents.vault_search_agent_local import VaultSearchAgentLocal\nfrom querymind.agents.web_search_client import WebSearchClient\n\n# Use vault search agent directly\nvault_agent = VaultSearchAgentLocal(model=\"mistral:7b\")\nresult = vault_agent.search(\"kubernetes deployment patterns\")\n\n# Use web search directly\nweb_client = WebSearchClient(api_key=\"your-key\")\nresults = web_client.search_sync(\"latest FastAPI best practices\", n_results=5)\n```\n\n## 🧪 Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Run specific test file\npytest tests/test_router_basic.py -v\n\n# Run with coverage\npytest tests/ --cov=querymind --cov-report=html\n```\n\nTest coverage:\n- ✅ 27 tests total\n- ✅ 25 passing (92.6%)\n- ⏭️ 2 skipped (optional dependencies)\n\n### Test Suite\n\n- **test_imports_work.py** - Verify all modules can be imported\n- **test_router_basic.py** - Validate query routing logic and heuristics\n- **test_security_validation.py** - Test input sanitization and injection protection\n\n## 🛠️ Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/rduffyuk/querymind.git\ncd querymind\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # or `venv\\Scripts\\activate` on Windows\n\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest tests/\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack querymind/ tests/\n\n# Lint code\nruff querymind/ tests/\n```\n\n## 📋 Project Structure\n\n```\nquerymind/\n├── querymind/\n│   ├── __init__.py           # Package initialization\n│   ├── core/                 # Core functionality\n│   │   ├── __init__.py\n│   │   ├── config.py         # Configuration management\n│   │   ├── logging_config.py # Structured logging (NEW)\n│   │   ├── embeddings.py     # ChromaDB embeddings\n│   │   ├── cache.py          # Query caching (Redis)\n│   │   └── conversation_memory.py  # Conversation stub (NEW)\n│   ├── agents/               # Multi-agent system\n│   │   ├── __init__.py\n│   │   ├── base_agent.py     # Abstract base agent\n│   │   ├── fast_search_agent.py    # Quick keyword search\n│   │   ├── deep_research_agent.py  # LLM-powered search\n│   │   ├── vault_search_agent_local.py  # Ollama integration (NEW)\n│   │   ├── web_search_client.py    # Web search fallback (NEW)\n│   │   └── router.py         # Intelligent routing\n│   └── mcp/                  # Model Context Protocol\n│       └── server.py         # FastMCP server\n├── tests/                    # Test suite (NEW)\n│   ├── __init__.py\n│   ├── test_imports_work.py  # Import verification\n│   ├── test_router_basic.py  # Routing logic tests\n│   └── test_security_validation.py  # Security tests\n├── pyproject.toml            # Package configuration (NEW)\n├── requirements.txt          # Dependencies\n├── .env.example              # Environment template\n├── .gitignore                # Git ignore rules\n├── LICENSE.txt               # MIT License\n└── README.md                 # This file\n```\n\n## ⚙️ Configuration\n\nQueryMind uses environment variables for configuration. See `.env.example` for all available options:\n\n### Core Settings\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `VAULT_PATH` | Path to your markdown documents | `/vault` |\n| `CHROMADB_URL` | ChromaDB HTTP endpoint | `http://localhost:8000` |\n| `REDIS_URL` | Redis cache endpoint | `redis://localhost:6379` |\n| `OLLAMA_API_URL` | Ollama LLM endpoint | `http://localhost:11434` |\n| `LOG_LEVEL` | Logging level (DEBUG/INFO/WARNING/ERROR) | `INFO` |\n\n### Optional Features\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SERPER_API_KEY` | [Serper.dev](https://serper.dev) API key for web search | None |\n| `DISABLE_WEB_SEARCH` | Disable web fallback | `false` |\n\n## 🤝 Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`pytest tests/`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Coding Standards\n\n- Follow [PEP 8](https://peps.python.org/pep-0008/) style guide\n- Use [Black](https://black.readthedocs.io/) for code formatting\n- Add tests for new features\n- Update documentation as needed\n- Use structured logging (not print statements)\n\n## 🗺️ Roadmap\n\n### Current (v0.1.0)\n- [x] Intelligent query routing with 7 heuristics\n- [x] FastSearch, DeepResearch, WebSearch agents\n- [x] Ollama integration for intent analysis\n- [x] ChromaDB vector search\n- [x] Structured logging system\n- [x] Comprehensive test suite (27 tests)\n- [x] Security hardening and input validation\n\n### Planned (v0.2.0)\n- [ ] Enhanced caching with gather cache\n- [ ] Async support for concurrent searches\n- [ ] Connection pooling for ChromaDB\n- [ ] Advanced metrics and monitoring\n- [ ] REST API endpoints\n- [ ] Web UI for query testing\n\n### Future (v1.0.0)\n- [ ] Complete conversation memory implementation\n- [ ] Hot-reload for configuration changes\n- [ ] Docker Compose deployment\n- [ ] Kubernetes deployment guides\n- [ ] Multi-language support\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.\n\n## 🙏 Acknowledgments\n\nQueryMind builds on excellent open-source projects:\n- [ChromaDB](https://www.trychroma.com/) - Vector database for semantic search\n- [Ollama](https://ollama.ai/) - Local LLM inference\n- [Serper.dev](https://serper.dev/) - Web search API\n- [FastMCP](https://github.com/jlowin/fastmcp) - Model Context Protocol server\n\n---\n\n**QueryMind** - Intelligent search for your knowledge base\n\nMade with ❤️ by [Ryan Duffy](https://github.com/rduffyuk)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frduffyuk%2Fquerymind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frduffyuk%2Fquerymind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frduffyuk%2Fquerymind/lists"}