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.
2026-03-19 10:01:58 +01:00
parent b28d8998f7
commit 65ca2401ae
16 changed files with 7073 additions and 0 deletions
--- a/docs/api/environment-variables.md
+++ b/docs/api/environment-variables.md
@@ -0,0 +1,235 @@
+# Environment Variables
+
+Reference for all environment variables used by OpenQuery.
+
+## 📋 Summary
+
+| Variable | Purpose | Required | Default | Example |
+|----------|---------|----------|---------|---------|
+| `OPENROUTER_API_KEY` | OpenRouter authentication | **Yes** | (none) | `sk-or-...` |
+| `OPENROUTER_MODEL` | Override default LLM model | No | `qwen/qwen3.5-flash-02-23` | `google/gemini-3-flash-preview` |
+| `SEARXNG_URL` | SearxNG instance URL | No | `http://localhost:8002` | `https://searx.example.com` |
+
+## Detailed Reference
+
+### `OPENROUTER_API_KEY`
+
+**Purpose**: Your OpenRouter API authentication token.
+
+**Required**: Yes, unless you have `ApiKey` set in config file.
+
+**How to Obtain**:
+1. Sign up at https://openrouter.ai
+2. Go to Dashboard → API Keys
+3. Copy your key (starts with `sk-or-`)
+
+**Priority**: Overrides config file `ApiKey`.
+
+**Setting**:
+
+```bash
+# Bash/Zsh
+export OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+# Fish
+set -x OPENROUTER_API_KEY "sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+# PowerShell
+$env:OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+# Windows CMD
+set OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+**Security**:
+- Never commit API key to version control
+- Don't share key publicly
+- Use environment variables or config file with restrictive permissions (600)
+- Rotate key if accidentally exposed
+
+**Validation**: OpenQuery checks if key is empty string and exits with error if missing:
+
+```
+[Error] API Key is missing. Set OPENROUTER_API_KEY environment variable or run 'configure -i' to set it up.
+```
+
+### `OPENROUTER_MODEL`
+
+**Purpose**: Override the default LLM model used for both query generation and final answer.
+
+**Required**: No.
+
+**Default**: `qwen/qwen3.5-flash-02-23`
+
+**Available Models** (from OpenRouter):
+
+| Model | Provider | Context | Cost (Input/Output per 1M tokens) |
+|-------|----------|---------|-----------------------------------|
+| `qwen/qwen3.5-flash-02-23` | Alibaba | 200K | \$0.10 / \$0.20 |
+| `qwen/qwen3.5-122b-a10b` | Alibaba | 200K | ~\$0.20 / ~\$0.40 |
+| `minimax/minimax-m2.5` | MiniMax | 200K | ~\$0.20 / ~\$0.40 |
+| `google/gemini-3-flash-preview` | Google | 1M | ~\$0.10 / ~\$0.40 |
+| `deepseek/deepseek-v3.2` | DeepSeek | 200K | ~\$0.10 / ~\$0.30 |
+| `moonshotai/kimi-k2.5` | Moonshot AI | 200K | ~\$0.10 / ~\$0.30 |
+
+(See OpenRouter for current pricing.)
+
+**Setting**:
+
+```bash
+export OPENROUTER_MODEL="google/gemini-3-flash-preview"
+```
+
+**Interactive Config Models**: The `configure -i` wizard shows only these 6 models for convenience, but you can set any OpenRouter model via environment variable or non-interactive configure.
+
+**Note**: Different models have different:
+- Speed (Flash models faster)
+- Cost (check pricing)
+- Quality (may vary by task)
+- Context window size (Gemini 3 Flash has 1M tokens, others ~200K)
+
+### `SEARXNG_URL`
+
+**Purpose**: URL of the SearxNG metasearch instance.
+
+**Required**: No.
+
+**Default**: `http://localhost:8002`
+
+**Format**: Must include protocol (`http://` or `https://`) and host:port.
+
+**Setting**:
+
+```bash
+# Local Docker instance
+export SEARXNG_URL="http://localhost:8002"
+
+# Remote instance with HTTPS
+export SEARXNG_URL="https://searx.example.com"
+
+# Custom port
+export SEARXNG_URL="http://localhost:8080"
+```
+
+**Finding a Public Instance**:
+- Visit https://searx.space for list of public instances
+- Choose one with HTTPS and low latency
+- Note: Public instances may have rate limits or require attribution
+
+**Priority**: Overrides any default, but not config file (no config setting for SearxNG URL - only env var). Could be added to config in future.
+
+**Test Your Instance**:
+```bash
+curl "$SEARXNG_URL/search?q=test&format=json" | head
+```
+
+Expected: JSON with `"results": [...]`.
+
+---
+
+## Configuration Priority Recap
+
+When OpenQuery needs a value:
+
+1. **Command-line option** (`--model`, `--key` from configure) - highest
+2. **Environment variable** (`OPENROUTER_MODEL`, `OPENROUTER_API_KEY`, `SEARXNG_URL`)
+3. **Configuration file** (`~/.config/openquery/config`: `Model`, `ApiKey`)
+4. **Hard-coded default** (only for model)
+
+**Example**:
+```bash
+# Config file: Model=qwen/qwen3.5-flash-02-23
+export OPENROUTER_MODEL="deepseek/deepseek-v3.2"
+openquery --model "google/gemini-3-flash-preview" "question"
+# Uses: model=google (CLI override), overrides env and config
+```
+
+---
+
+## Troubleshooting Environment Variables
+
+### Variable Not Taking Effect
+
+**Symptom**: `openquery` still uses old value after export.
+
+**Causes**:
+- Exported in different shell session
+- Exported after running `openquery`
+- Shell profile not reloaded
+
+**Check**:
+```bash
+echo $OPENROUTER_API_KEY
+# Should print the key (or blank if unset)
+```
+
+**Fix**:
+```bash
+# Export in current session
+export OPENROUTER_API_KEY="sk-or-..."
+
+# Or add to ~/.bashrc / ~/.zshrc and restart terminal
+```
+
+### Special Characters in Values
+
+If your API key contains special characters (`$`, `!`, etc.), quote properly:
+
+```bash
+export OPENROUTER_API_KEY='sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+# Single quotes prevent shell expansion
+```
+
+### Variable Name Typos
+
+`OPENROUTER_API_KEY` is all caps with underscores. `openrouter_api_key` (lowercase) won't work.
+
+**Check spelling**:
+```bash
+env | grep -i openrouter
+```
+
+### Windows Environment Variables
+
+On Windows, environment variables are set per-session or user-level:
+
+**PowerShell** (current session):
+```powershell
+$env:OPENROUTER_API_KEY="sk-or-..."
+```
+
+**Persistent** (PowerShell):
+```powershell
+[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-...", "User")
+```
+
+**CMD**:
+```cmd
+set OPENROUTER_API_KEY=sk-or-...
+```
+
+**System Properties** → Advanced → Environment Variables (GUI)
+
+---
+
+## Next Steps
+
+- **[Configuration File](../configuration.md)** - Persistent configuration
+- **[Usage Guide](../usage.md)** - How to use these variables
+- **[Troubleshooting](../troubleshooting.md)** - Diagnose environment issues
+
+---
+
+**Quick Reference**
+
+```bash
+# Required
+export OPENROUTER_API_KEY="sk-or-..."
+
+# Optional (override defaults)
+export OPENROUTER_MODEL="google/gemini-3-flash-preview"
+export SEARXNG_URL="https://searx.example.com"
+
+# Run
+openquery "your question"
+```