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](https://openrouter.ai/)
2. **Environment Setup**: Add your API key to the environment:
   ```bash
   export OPENROUTER_API_KEY="your-api-key-here"
   ```

### Installation

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

```bash
# 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:

```bash
# 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:

```bash
# 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:

```python
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

```python
@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

```python
@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

```python
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

```python
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

```python
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

```python
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

```bash
# 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

```bash
# 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

```bash
# 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:

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

## Testing

Run the test suite:

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