OpenQuery/docs/configuration.md

Configuration

Complete guide to configuring OpenQuery for your environment.

📋 Table of Contents

1. Configuration Methods
2. Configuration File
3. Environment Variables
4. Command-Line Options
5. Configuration Priority
6. Recommended Settings
7. Advanced Configuration

Configuration Methods

OpenQuery can be configured through three methods, which merge together with clear priority:

Method	Persistence	Use Case
Configuration File	Permanent	Default values you use daily
Environment Variables	Session/Shell	CI/CD, scripting, temporary overrides
Command-Line Options	Per-execution	One-off customizations

Configuration File

Location

OpenQuery follows the XDG Base Directory specification:

• Linux/macOS: ~/.config/openquery/config
• Windows: %APPDATA%\openquery\config (e.g., C:\Users\<user>\AppData\Roaming\openquery\config)

Format

Simple key=value pairs, one per line:

ApiKey=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Model=qwen/qwen3.5-flash-02-23
DefaultQueries=3
DefaultChunks=3
DefaultResults=5

Schema

Key	Type	Default	Description
ApiKey	string	""	OpenRouter API authentication key
Model	string	qwen/qwen3.5-flash-02-23	Default LLM model to use
DefaultQueries	int	3	Number of search queries to generate
DefaultChunks	int	3	Number of top context chunks to include
DefaultResults	int	5	Number of search results per query

Example Configurations

Minimal (just API key):

ApiKey=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Optimized for Research:

ApiKey=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Model=google/gemini-3-flash-preview
DefaultQueries=5
DefaultChunks=4
DefaultResults=10

Cost-Conscious:

ApiKey=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Model=qwen/qwen3.5-flash-02-23
DefaultQueries=2
DefaultChunks=2
DefaultResults=3

Environment Variables

Environment variables override the configuration file and can be set temporarily or permanently in your shell profile.

Available Variables

Variable	Purpose	Required	Example
OPENROUTER_API_KEY	OpenRouter API key	Yes (unless in config file)	export OPENROUTER_API_KEY="sk-or-..."
OPENROUTER_MODEL	Override default LLM model	No	export OPENROUTER_MODEL="deepseek/deepseek-v3.2"
SEARXNG_URL	URL of SearxNG instance	No (default: http://localhost:8002)	export SEARXNG_URL="https://searx.example.com"

Setting Environment Variables

Temporary (Current Session)

# Linux/macOS
export OPENROUTER_API_KEY="sk-or-..."
export SEARXNG_URL="http://localhost:8002"

# Windows PowerShell
$env:OPENROUTER_API_KEY="sk-or-..."
$env:SEARXNG_URL="http://localhost:8002"

Permanent (Shell Profile)

bash (~/.bashrc or ~/.bash_profile):

export OPENROUTER_API_KEY="sk-or-..."
export SEARXNG_URL="http://localhost:8002"

zsh (~/.zshrc):

export OPENROUTER_API_KEY="sk-or-..."
export SEARXNG_URL="http://localhost:8002"

fish (~/.config/fish/config.fish):

set -x OPENROUTER_API_KEY "sk-or-..."
set -x SEARXNG_URL "http://localhost:8002"

Windows (PowerShell profile):

[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-...", "User")
[Environment]::SetEnvironmentVariable("SEARXNG_URL", "http://localhost:8002", "User")

After editing profile files, restart your terminal or run source ~/.bashrc (or equivalent).

Security Note

Never commit your API key to version control. Use environment variables or config file that's in .gitignore. The default .gitignore already excludes common build directories but doesn't include the config file since it's outside the project directory (~/.config/).

Command-Line Options

Options passed directly to the openquery command override both config file and environment variables for that specific execution.

Main Command Options

openquery [OPTIONS] <question>

Option	Aliases	Type	Default Source	Description
--chunks	-c	int	Config DefaultChunks	Number of top context chunks
--results	-r	int	Config DefaultResults	Search results per query
``--queries`	-q	int	Config DefaultQueries	Number of search queries
--short	-s	bool	false	Request concise answer
--long	-l	bool	false	Request detailed answer
--verbose	-v	bool	false	Show detailed progress

Configure Command Options

openquery configure [OPTIONS]

Option	Type	Description
--interactive / -i	bool	Launch interactive configuration wizard
--key	string	Set API key
--model	string	Set default model
--queries	int?	Set default queries
--chunks	int?	Set default chunks
--results	int?	Set default results

Configuration Priority

When OpenQuery needs a value, it checks sources in this order (highest to lowest priority):

1. Command-line option (if provided)
2. Environment variable (if set)
3. Configuration file (if key exists)
4. Hard-coded default (if all above missing)

Examples

Example 1: Environment overrides config

# config file: DefaultQueries=5
export OPENROUTER_MODEL="deepseek/deepseek-v3.2"
openquery --queries 2 "question"  # Uses: queries=2 (CLI), model=deepseek (env), chunks=3 (config)

Example 2: CLI overrides everything

export OPENROUTER_MODEL="qwen/qwen3.5-flash-02-23"
openquery --model "google/gemini-3-flash-preview" --chunks 5 "question"
# Uses: model=google (CLI), chunks=5 (CLI), queries=3 (default)

Example 3: All sources combined

# config: DefaultChunks=4
# env: OPENROUTER_MODEL="moonshotai/kimi-k2.5", SEARXNG_URL="http://custom:8002"
# CLI: --queries 6 --short
openquery "question"
# Uses: queries=6 (CLI), chunks=4 (config), results=5 (config), 
#       model=kimi-k2.5 (env), searxng=custom (env), short=true (CLI)

Recommended Settings

For Quick Questions (Facts, Definitions)

openquery -q 2 -r 3 -c 2 "What is the capital of France?"

• Few queries (2) for straightforward facts
• Few results (3) to minimize processing
• Few chunks (2) for focused answer

For Research (Complex Topics)

openquery -q 5 -r 10 -c 4 -l "Explain the causes of the French Revolution"

• More queries (5) for diverse perspectives
• More results (10) for comprehensive coverage
• More chunks (4) for rich context
• Long format for depth

For Exploration (Broad Topics)

openquery -q 8 -r 15 -c 5 "What are the latest developments in AI?"

• Many queries (8) to explore different angles
• Many results (15) for breadth
• More chunks (5) for extensive context

Cost Optimization

openquery configure --model "qwen/qwen3.5-flash-02-23"
# Keep defaults: -q 3 -r 5 -c 3

• Qwen Flash is very cost-effective
• Default parameters provide good balance

Performance Optimization

# Adjust ParallelProcessingOptions in SearchTool.cs if needed
# Default: MaxConcurrentArticleFetches=10, MaxConcurrentEmbeddingRequests=4

• Reduce these values if you see rate limits or memory pressure
• Increase them if you have fast network/API and want more speed

Advanced Configuration

Changing Concurrency Limits

Concurrency limits are currently hardcoded in SearchTool.cs but can be adjusted:

public class ParallelProcessingOptions
{
    public int MaxConcurrentArticleFetches { get; set; } = 10;  // ← Change this
    public int MaxConcurrentEmbeddingRequests { get; set; } = 4;  // ← Change this
    public int EmbeddingBatchSize { get; set; } = 300;  // ← Change this
}

To make these configurable, you could:

1. Add fields to AppConfig
2. Read from config file
3. Pass through to SearchTool constructor

Custom Embedding Model

The embedding model is hardcoded to openai/text-embedding-3-small. To change:

Edit the EmbeddingService constructor:

public EmbeddingService(OpenRouterClient client, string embeddingModel = "your-model")

Or make it configurable via CLI/config (future enhancement).

Changing Chunk Size

Chunk size (500 chars) is defined in ChunkingService.cs:

private const int MAX_CHUNK_SIZE = 500;

Modify this constant to change how articles are split. Larger chunks:

• ✅ More context per chunk
• ❌ Fewer chunks for same article
• ❌ Higher token usage in final answer

Smaller chunks:

• ✅ More granular matching
• ❌ May lose context across chunk boundaries

Using a Custom SearxNG Instance

Some SearxNG deployments may require HTTPS, authentication, or custom paths:

# With authentication (if supported)
export SEARXNG_URL="https://user:pass@searx.example.com:8080"

# With custom path
export SEARXNG_URL="https://searx.example.com/custom-path"

Note: Most SearxNG instances don't require auth as they're designed for privacy.

OpenRouter Settings

OpenRouter supports additional parameters (not yet exposed in OpenQuery):

• temperature - Randomness (0-2, default ~1)
• max_tokens - Response length limit
• top_p - Nucleus sampling
• frequency_penalty / presence_penalty

These could be added to ChatCompletionRequest in future versions.

Managing Multiple Configurations

You can maintain multiple config files and symlink or set per-project:

# Create project-specific config
cp ~/.config/openquery/config ~/myproject/openquery.config

# Use it temporarily
OPENQUERY_CONFIG=~/myproject/openquery.config openquery "question"

Note: Currently OpenQuery only looks at ~/.config/openquery/config. Multi-config support would require code changes (reading from OPENQUERY_CONFIG env var).

Configuration Validation

OpenQuery doesn't strictly validate config values. Invalid settings may cause runtime errors:

• DefaultQueries <= 0 → May cause exceptions or zero queries
• DefaultChunks <= 0 → May return no context
• DefaultResults <= 0 → No search results

Validate manually:

# Test your config loads
cat ~/.config/openquery/config

# Test with verbose mode
openquery -v "test"

---

Next Steps

• Usage Guide - Learn how to use the CLI
• Architecture - Understand the system design
• Troubleshooting - Fix common issues