Query Rewrite

Optimize queries for better RAG retrieval using QueryRewriterAgent

The --query-rewrite flag transforms user queries to improve RAG retrieval quality using the QueryRewriterAgent.

Quick Start

praisonai "AI trends" --query-rewrite

Usage

Basic Query Rewrite

praisonai "AI trends" --query-rewrite

Expected Output:

🔄 Query rewritten: "What are the current trends in Artificial Intelligence?"

╭─ Agent Info ─────────────────────────────────────────────────────────────────╮
│  👤 Agent: DirectAgent                                                       │
│  Role: Assistant                                                             │
╰──────────────────────────────────────────────────────────────────────────────╯

╭────────────────────────────────── Response ──────────────────────────────────╮
│ Current AI trends include...                                                 │
╰──────────────────────────────────────────────────────────────────────────────╯

With Search Tools

# Built-in SDK tool
praisonai "latest developments" --query-rewrite --rewrite-tools "internet_search"

# praisonai-tools / entry-point plugin — now resolved via the full tool chain
praisonai "latest developments" --query-rewrite --rewrite-tools "duckduckgo_search"

# Custom local tool (requires the env-var gate)
PRAISONAI_ALLOW_LOCAL_TOOLS=1 praisonai "latest developments" --query-rewrite --rewrite-tools "my_search"

--rewrite-tools now accepts any name reachable by praisonai tools list — the same resolver chain used by praisonai research --tools and --expand-tools. See Tool Resolution for the full chain.

Combine with Other Flags

# Query rewrite with prompt expansion
praisonai "AI news" --query-rewrite --expand-prompt

# Query rewrite with deep research
praisonai research --query-rewrite "AI trends"

# Query rewrite with verbose output
praisonai "explain quantum computing" --query-rewrite -v

How It Works

1. Query Analysis: The QueryRewriterAgent analyzes your input
2. Strategy Selection: Automatically selects the best rewrite strategy
3. Query Transformation: Expands abbreviations, adds context, fixes typos
4. Execution: The rewritten query is used for the task

Rewrite Strategies

Strategy	Description	Best For
BASIC	Expand abbreviations, fix typos, add context	General queries
HYDE	Generate hypothetical document for semantic matching	Conceptual questions
STEP_BACK	Generate higher-level concept questions	Specific technical queries
SUB_QUERIES	Decompose multi-part questions	Complex queries
MULTI_QUERY	Generate multiple paraphrased versions	Ambiguous queries
CONTEXTUAL	Resolve references using conversation history	Follow-up questions
AUTO	Automatically detect best strategy	Default

Examples

Technical Query

praisonai "GPT-4 vs Claude 3?" --query-rewrite

Rewritten to: “What are the key differences between OpenAI’s GPT-4 and Anthropic’s Claude 3 language models in terms of capabilities, performance, and use cases?”

Ambiguous Query

praisonai "RAG setup" --query-rewrite

Rewritten to: “How do I set up a Retrieval-Augmented Generation (RAG) system, including document ingestion, embedding generation, vector storage, and query processing?”

Follow-up Query

praisonai "What about cost?" --query-rewrite

Rewritten to: “What are the cost considerations and pricing models for implementing this solution?”

Choosing the rewriter’s model

The CLI’s --query-rewrite step honours the standard cascade — CLI flag wins, env vars next, gpt-4o-mini fallback last:

# Rewriter uses claude-3-5-sonnet-latest, matching the main agent
praisonai "What about cost?" --query-rewrite --llm claude-3-5-sonnet-latest

To keep a cheap rewriter regardless of the main model, pin it explicitly with OPENAI_MODEL_NAME=gpt-4o-mini while --llm drives the main agent — but the recommended pattern is running the rewriter and main agent on the same model.

Programmatic Usage

The model= kwarg on QueryRewriterAgent is unchanged — the cascade above applies only to the CLI path.

from praisonaiagents import QueryRewriterAgent, RewriteStrategy

agent = QueryRewriterAgent(model="gpt-4o-mini")

# Basic rewrite
result = agent.rewrite("AI trends")
print(result.primary_query)  # "What are the current trends in Artificial Intelligence?"

# With specific strategy
result = agent.rewrite("What is quantum computing?", strategy=RewriteStrategy.HYDE)

# Step-back for broader context
result = agent.rewrite("GPT-4 vs Claude 3?", strategy=RewriteStrategy.STEP_BACK)

# Sub-queries for complex questions
result = agent.rewrite("RAG setup and best embedding models?", strategy=RewriteStrategy.SUB_QUERIES)

# Contextual with chat history
result = agent.rewrite("What about cost?", chat_history=[...])

Best Practices

Use --query-rewrite for RAG and search optimization. For expanding task prompts, use --expand-prompt instead.

Query rewriting adds an additional LLM call. Use --metrics to monitor token usage.

Use Case	Flag
RAG/Search optimization	--query-rewrite
Task prompt expansion	--expand-prompt
Both	--query-rewrite --expand-prompt

Related

• Query Rewriter Agent
• Prompt Expansion CLI
• Deep Research CLI