trax/docs/RESEARCH_AGENT.md

Perplexity Research Agent

A focused research application that leverages Perplexity's sonar-reasoning-pro model through OpenRouter for comprehensive research with real-time web search capabilities.

Features

• 🧠 Advanced Reasoning: Uses Perplexity's sonar-reasoning-pro model for superior reasoning capabilities
• 🌐 Real-time Web Search: Access to current information with source citations
• 📱 Streamlit Interface: Beautiful web interface for interactive research
• 💻 CLI Interface: Command-line tools for automation and scripting
• 📊 Performance Metrics: Detailed timing, confidence scores, and token usage tracking
• 💾 Export Options: Download results as JSON or Markdown
• 📚 Research History: Track and review previous research sessions

Quick Start

Prerequisites

1. OpenRouter API Key: Get your API key from OpenRouter
2. Environment Setup: Add your API key to the environment:

   export OPENROUTER_API_KEY="your-api-key-here"
   

Installation

The research agent is included in the main project. Install dependencies:

# Install project dependencies
uv pip install -e ".[dev]"

# Or install streamlit separately if needed
uv pip install streamlit

Usage

1. Streamlit Web Interface

Launch the interactive web interface:

# Using the launcher script
python launch_research_agent.py

# Or directly with streamlit
uv run streamlit run src/research_agent_app.py

The interface will open at http://localhost:8501

2. CLI Interface

Use the command-line interface for automation:

# Single research query
uv run python -m src.cli.research query -q "What are the latest developments in AI reasoning models?"

# With additional context
uv run python -m src.cli.research query -q "How do vector databases compare?" -c "Focus on 2025 trends"

# Export to file
uv run python -m src.cli.research query -q "Your query" -o results.json -f json

# List available models
uv run python -m src.cli.research models

# Batch processing
uv run python -m src.cli.research batch -f queries.txt -o results/

3. Programmatic Usage

Use the research agent in your Python code:

import asyncio
from src.services.protocols import ResearchQuery
from src.services.research.service import OpenRouterResearchService
from src.services.research.config import ResearchConfig

async def conduct_research():
    # Initialize service
    config = ResearchConfig.from_env("your-api-key")
    service = OpenRouterResearchService(config)
    
    # Create query
    query = ResearchQuery(
        query="What are the latest developments in AI reasoning models?",
        context="Focus on models like o1 and o3",
        max_tokens=4000,
        temperature=0.1,
        model="perplexity/sonar-reasoning-pro"
    )
    
    # Conduct research
    result = await service.research(query)
    
    print(f"Answer: {result.answer}")
    print(f"Confidence: {result.confidence_score:.1%}")
    print(f"Sources: {result.sources}")

# Run the research
asyncio.run(conduct_research())

Configuration

Environment Variables

• OPENROUTER_API_KEY: Your OpenRouter API key (required)

Research Parameters

• Model: perplexity/sonar-reasoning-pro (default)
• Max Tokens: 1000-4000 (default: 4000)
• Temperature: 0.0-1.0 (default: 0.1)
• Context: Optional additional context for the research

API Reference

ResearchQuery

@dataclass
class ResearchQuery:
    query: str                    # Research question
    context: Optional[str] = None # Additional context
    max_tokens: int = 4000        # Maximum response length
    temperature: float = 0.1      # Response creativity
    model: str = "perplexity/sonar-reasoning-pro"

ResearchResult

@dataclass
class ResearchResult:
    query: str                    # Original query
    answer: str                   # Research answer
    sources: List[str]            # Source URLs
    confidence_score: float       # Confidence (0.0-1.0)
    processing_time: float        # Processing time in seconds
    model_used: str              # Model that generated the response
    token_usage: Dict[str, int]   # Token usage statistics

OpenRouterResearchService

class OpenRouterResearchService:
    async def research(self, query: ResearchQuery) -> ResearchResult
    async def batch_research(self, queries: List[ResearchQuery]) -> List[ResearchResult]
    def get_available_models(self) -> List[str]

Examples

Example 1: Basic Research

from src.services.protocols import ResearchQuery
from src.services.research.service import OpenRouterResearchService

async def basic_research():
    service = OpenRouterResearchService()
    
    query = ResearchQuery(
        query="What are the latest developments in AI reasoning models?"
    )
    
    result = await service.research(query)
    print(result.answer)

Example 2: Research with Context

query = ResearchQuery(
    query="How do vector databases compare for RAG applications?",
    context="I'm building a personal knowledge management system for processing research papers",
    temperature=0.2
)

Example 3: Batch Processing

queries = [
    ResearchQuery(query="Query 1"),
    ResearchQuery(query="Query 2"),
    ResearchQuery(query="Query 3")
]

results = await service.batch_research(queries)
for result in results:
    print(f"Query: {result.query}")
    print(f"Answer: {result.answer[:100]}...")

CLI Commands

Single Query

# Basic query
uv run python -m src.cli.research query -q "Your research question"

# With options
uv run python -m src.cli.research query \
  -q "Your question" \
  -c "Additional context" \
  -m 3000 \
  -t 0.2 \
  -o results.json \
  -f json

Batch Processing

# Create queries file
echo "Query 1" > queries.txt
echo "Query 2" >> queries.txt
echo "Query 3" >> queries.txt

# Run batch research
uv run python -m src.cli.research batch \
  -f queries.txt \
  -o results/ \
  --format json

Model Information

# List available models
uv run python -m src.cli.research models

Performance

Expected Performance

• Processing Time: 2-5 seconds per query
• Confidence Score: 80-95% for well-formed queries
• Token Usage: 1000-2000 tokens per response
• Sources: 3-8 relevant sources per query

Optimization Tips

1. Clear Queries: Be specific and clear in your research questions
2. Context Usage: Provide relevant context to improve accuracy
3. Temperature: Use lower values (0.1-0.3) for factual research
4. Batch Processing: Use batch mode for multiple related queries

Troubleshooting

Common Issues

1. API Key Error

   ❌ OPENROUTER_API_KEY not found in environment
   

   Solution: Set your OpenRouter API key in the environment

2. Model Not Available

   ❌ Model perplexity/sonar-reasoning-pro not available
   

   Solution: Check available models with uv run python -m src.cli.research models

3. Rate Limiting

   ❌ Rate limit exceeded
   

   Solution: Wait a moment and retry, or check your OpenRouter usage limits

4. Network Issues

   ❌ Connection failed
   

   Solution: Check your internet connection and OpenRouter service status

Debug Mode

Enable debug logging:

export TASKMASTER_LOG_LEVEL=DEBUG
uv run python -m src.cli.research query -q "Your query"

Testing

Run the test suite:

# Run all research agent tests
uv run pytest tests/test_research_agent.py -v

# Run with coverage
uv run pytest tests/test_research_agent.py --cov=src.services.research

Architecture

The research agent follows the project's architecture patterns:

• Protocol-Based Services: Uses ResearchServiceProtocol for clean interfaces
• Configuration Management: Centralized config via ResearchConfig
• Error Handling: Comprehensive error handling with custom exceptions
• Testing: Unit tests with mocks and integration tests
• Modular Design: Separate concerns for API, service, and UI layers

Contributing

When contributing to the research agent:

1. Test First: Write unit tests before implementing features
2. Follow Patterns: Use existing service patterns and protocols
3. Keep Modular: Maintain separation between UI, service, and API layers
4. Document: Update this documentation for new features
5. Type Hints: Use proper type hints throughout

License

This research agent is part of the Trax project and follows the same licensing terms.