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

![.NET](https://img.shields.io/badge/.NET-10.0-blue?style=for-the-badge)
![AOT](https://img.shields.io/badge/AOT-Compiled-green?style=for-the-badge)
![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)

## ✨ 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.