docs: add comprehensive documentation with README and detailed guides
- 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.
This commit is contained in:
OpenQuery Documentation
196
README.md
Normal file
196
README.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user