65ca2401ae
- Add user-friendly README.md with quick start guide - Create docs/ folder with structured technical documentation: - installation.md: Build and setup instructions - configuration.md: Complete config reference - usage.md: CLI usage guide with examples - architecture.md: System design and patterns - components/: Deep dive into each component (OpenQueryApp, SearchTool, Services, Models) - api/: CLI reference, environment variables, programmatic API - troubleshooting.md: Common issues and solutions - performance.md: Latency, throughput, and optimization - All documentation fully cross-referenced with internal links - Covers project overview, architecture, components, APIs, and support See individual files for complete documentation.
197 lines
6.2 KiB
Markdown
197 lines
6.2 KiB
Markdown
# OpenQuery
|
|
|
|
**AI-powered search and answer system** that finds accurate, well-sourced answers to your questions by searching the web, extracting relevant content, and synthesizing intelligent responses.
|
|
|
|
|
|
[AOT](https://img.shields.io/badge/AOT-Compiled-green)
|
|
[License](https://img.shields.io/badge/license-MIT-green)
|
|
|
|
## ✨ Features
|
|
|
|
- 🤖 **Smart Query Generation** - Automatically creates multiple diverse search queries from your question
|
|
- ⚡ **Parallel Processing** - Fast concurrent searches, article fetching, and embedding generation
|
|
- 🎯 **Semantic Search** - Uses vector embeddings to find the most relevant information
|
|
- 📚 **Clean Article Extraction** - Intelligently extracts article content using SmartReader
|
|
- 🔄 **Streaming Responses** - Watch the AI answer generate in real-time
|
|
- ⚙️ **Fully Configurable** - Control queries, results, and context chunks
|
|
- 🛡️ **Production Ready** - Built with rate limiting, retries, and error handling
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Prerequisites
|
|
|
|
- A **SearxNG** instance (Docker recommended):
|
|
```bash
|
|
docker run -d --name searxng -p 8002:8080 searxng/searxng:latest
|
|
```
|
|
|
|
- A **OpenRouter API key** from [openrouter.ai](https://openrouter.ai)
|
|
|
|
### 2. Installation
|
|
|
|
```bash
|
|
# Clone and build
|
|
git clone <your-repo-url>
|
|
cd OpenQuery
|
|
chmod +x install.sh
|
|
./install.sh
|
|
|
|
# Or build manually
|
|
dotnet publish -c Release -r linux-x64 --self-contained true /p:PublishAot=true
|
|
```
|
|
|
|
### 3. Configuration
|
|
|
|
```bash
|
|
# Interactive setup
|
|
openquery configure -i
|
|
|
|
# Or set environment variables
|
|
export OPENROUTER_API_KEY="sk-or-..."
|
|
export SEARXNG_URL="http://localhost:8002" # default
|
|
```
|
|
|
|
### 4. Ask a Question
|
|
|
|
```bash
|
|
openquery "What is quantum entanglement and how does it work?"
|
|
```
|
|
|
|
That's it! The system will:
|
|
1. Generate 3 search queries (configurable)
|
|
2. Search the web via SearxNG
|
|
3. Extract and chunk relevant articles
|
|
4. Rank content by semantic relevance
|
|
5. Stream a comprehensive answer with citations
|
|
|
|
## 📖 Usage Examples
|
|
|
|
```bash
|
|
# Concise answer
|
|
openquery -s "Who won the 2024 US presidential election?"
|
|
|
|
# Detailed research
|
|
openquery -l -q 5 -r 10 "Explain quantum computing and its applications"
|
|
|
|
# See everything
|
|
openquery -v "What are the health benefits of meditation?"
|
|
|
|
# Customize
|
|
openquery -c 5 -r 8 "Current state of SpaceX Starship development"
|
|
```
|
|
|
|
## 🔧 Options
|
|
|
|
```
|
|
-c, --chunks N Number of top context chunks (default: 3)
|
|
-r, --results N Search results per query (default: 5)
|
|
-q, --queries N Number of search queries to generate (default: 3)
|
|
-s, --short Give a concise answer
|
|
-l, --long Give a detailed answer
|
|
-v, --verbose Show detailed progress
|
|
```
|
|
|
|
## 🌐 Supported Models
|
|
|
|
OpenQuery works with any OpenRouter model. Popular choices:
|
|
|
|
- `qwen/qwen3.5-flash-02-23` (default, fast & affordable)
|
|
- `google/gemini-3-flash-preview`
|
|
- `deepseek/deepseek-v3.2`
|
|
- `moonshotai/kimi-k2.5`
|
|
|
|
Configure your preferred model:
|
|
```bash
|
|
openquery configure --model "google/gemini-3-flash-preview"
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
OpenQuery/
|
|
├── README.md # This file
|
|
├── docs/ # Detailed documentation
|
|
│ ├── installation.md
|
|
│ ├── configuration.md
|
|
│ ├── usage.md
|
|
│ ├── architecture.md
|
|
│ ├── components/
|
|
│ └── troubleshooting.md
|
|
├── Program.cs # CLI entry point
|
|
├── OpenQuery.cs # Main application logic
|
|
├── Services/ # Business logic services
|
|
├── Models/ # Data models
|
|
├── Tools/ # Search orchestration
|
|
└── ConfigManager.cs # Configuration management
|
|
```
|
|
|
|
## 🏗️ Architecture
|
|
|
|
OpenQuery uses a multi-stage pipeline:
|
|
|
|
```
|
|
Query → Multiple Searches → Article Fetching → Embeddings → Ranking → AI Answer
|
|
```
|
|
|
|
1. **Query Expansion**: LLM generates diverse search queries
|
|
2. **Parallel Search**: SearxNG executes all queries simultaneously
|
|
3. **Content Extraction**: SmartReader pulls clean article text
|
|
4. **Embedding Generation**: Vectorize query and chunks
|
|
5. **Semantic Ranking**: Cosine similarity scoring
|
|
6. **Answer Synthesis**: Final LLM response with sources
|
|
|
|
## 🔍 How It Works
|
|
|
|
1. **You ask a question** → OpenQuery generates 3 optimized search queries
|
|
2. **Searches the web** → All queries run in parallel via SearxNG
|
|
3. **Fetches articles** → Extracts clean content from top results
|
|
4. **Splits into chunks** → ~500 character pieces for embedding
|
|
5. **Ranks by relevance** → Semantic similarity to your question
|
|
6. **Synthesizes answer** → LLM reviews top 3 chunks and responds with citations
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
**Common issues** and solutions:
|
|
|
|
| Problem | Solution |
|
|
|---------|----------|
|
|
| "API Key is missing" | Run `openquery configure -i` or set `OPENROUTER_API_KEY` |
|
|
| No search results | Check your SearxNG instance is running (`curl http://localhost:8002`) |
|
|
| Slow performance | Reduce `--results` or `--queries` count |
|
|
| Articles failing to fetch | Some sites block scrapers; try different queries |
|
|
|
|
See [docs/troubleshooting.md](docs/troubleshooting.md) for detailed help.
|
|
|
|
## 📚 Documentation
|
|
|
|
- **[Installation Guide](docs/installation.md)** - Build and setup instructions
|
|
- **[Configuration](docs/configuration.md)** - All config options and environment variables
|
|
- **[Usage Guide](docs/usage.md)** - Complete CLI reference and examples
|
|
- **[Architecture](docs/architecture.md)** - System design and patterns
|
|
- **[Components](docs/components/)** - Deep dive into each module
|
|
- **[Troubleshooting](docs/troubleshooting.md)** - Solve common problems
|
|
- **[API Reference](docs/api-reference.md)** - Programmatic interfaces
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions welcome! Please:
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Submit a pull request
|
|
|
|
## 📄 License
|
|
|
|
MIT License - see LICENSE file for details.
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- [OpenRouter](https://openrouter.ai) - LLM API aggregation
|
|
- [SearxNG](https://searx.space) - Privacy-respecting metasearch
|
|
- [SmartReader](https://github.com/kfasten/SmartReader) - Article extraction
|
|
- Built with [.NET](https://dotnet.microsoft.com)
|
|
|
|
---
|
|
|
|
**Need more details?** Check the comprehensive documentation in the [docs/](docs/) folder.
|