OpenQuery/README.md

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 License

✨ 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):

  docker run -d --name searxng -p 8002:8080 searxng/searxng:latest
  

• A OpenRouter API key from openrouter.ai

2. Installation

# 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

# 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

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

# 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:

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 for detailed help.

📚 Documentation

• Installation Guide - Build and setup instructions
• Configuration - All config options and environment variables
• Usage Guide - Complete CLI reference and examples
• Architecture - System design and patterns
• Components - Deep dive into each module
• Troubleshooting - Solve common problems
• API Reference - 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 - LLM API aggregation
• SearxNG - Privacy-respecting metasearch
• SmartReader - Article extraction
• Built with .NET

---

Need more details? Check the comprehensive documentation in the docs/ folder.