# SmartAI Research API Implementation

This document describes the new research capabilities added to the SmartAI library, enabling web search and deep research features for OpenAI and Anthropic providers.

## Features Added

### 1. Research Method Interface

Added a new `research()` method to the `MultiModalModel` abstract class with the following interfaces:

```typescript
interface ResearchOptions {
  query: string;
  searchDepth?: 'basic' | 'advanced' | 'deep';
  maxSources?: number;
  includeWebSearch?: boolean;
  background?: boolean;
}

interface ResearchResponse {
  answer: string;
  sources: Array<{
    url: string;
    title: string;
    snippet: string;
  }>;
  searchQueries?: string[];
  metadata?: any;
}
```

### 2. OpenAI Provider Research Implementation

The OpenAI provider now supports:
- **Deep Research API** with models:
  - `o3-deep-research-2025-06-26` (comprehensive analysis)
  - `o4-mini-deep-research-2025-06-26` (lightweight, faster)
- **Web Search** for standard models (gpt-5, o3, o3-pro, o4-mini)
- **Background processing** for async deep research tasks

### 3. Anthropic Provider Research Implementation

The Anthropic provider now supports:
- **Web Search API** with Claude models
- **Domain filtering** (allow/block lists)
- **Progressive searches** for comprehensive research
- **Citation extraction** from responses

### 4. Perplexity Provider Research Implementation

The Perplexity provider implements research using:
- **Sonar models** for standard searches
- **Sonar Pro** for deep research
- Built-in citation support

### 5. Other Providers

Added research method stubs to:
- Groq Provider
- Ollama Provider
- xAI Provider
- Exo Provider

These providers throw a "not yet supported" error when research is called, maintaining interface compatibility.

## Usage Examples

### Basic Research with OpenAI

```typescript
import { OpenAiProvider } from '@push.rocks/smartai';

const openai = new OpenAiProvider({
  openaiToken: 'your-api-key',
  researchModel: 'o4-mini-deep-research-2025-06-26'
});

await openai.start();

const result = await openai.research({
  query: 'What are the latest developments in quantum computing?',
  searchDepth: 'basic',
  includeWebSearch: true
});

console.log(result.answer);
console.log('Sources:', result.sources);
```

### Deep Research with OpenAI

```typescript
const deepResult = await openai.research({
  query: 'Comprehensive analysis of climate change mitigation strategies',
  searchDepth: 'deep',
  background: true
});
```

### Research with Anthropic

```typescript
import { AnthropicProvider } from '@push.rocks/smartai';

const anthropic = new AnthropicProvider({
  anthropicToken: 'your-api-key',
  enableWebSearch: true,
  searchDomainAllowList: ['nature.com', 'science.org']
});

await anthropic.start();

const result = await anthropic.research({
  query: 'Latest breakthroughs in CRISPR gene editing',
  searchDepth: 'advanced'
});
```

### Research with Perplexity

```typescript
import { PerplexityProvider } from '@push.rocks/smartai';

const perplexity = new PerplexityProvider({
  perplexityToken: 'your-api-key'
});

const result = await perplexity.research({
  query: 'Current state of autonomous vehicle technology',
  searchDepth: 'deep' // Uses Sonar Pro model
});
```

## Configuration Options

### OpenAI Provider
- `researchModel`: Specify deep research model (default: `o4-mini-deep-research-2025-06-26`)
- `enableWebSearch`: Enable web search for standard models

### Anthropic Provider
- `enableWebSearch`: Enable web search capabilities
- `searchDomainAllowList`: Array of allowed domains
- `searchDomainBlockList`: Array of blocked domains

## API Pricing

- **OpenAI Deep Research**: $10 per 1,000 calls
- **Anthropic Web Search**: $10 per 1,000 searches + standard token costs
- **Perplexity Sonar**: $5 per 1,000 searches (Sonar Pro)

## Testing

Run the test suite:

```bash
pnpm test test/test.research.ts
```

All providers have been tested to ensure:
- Research methods are properly exposed
- Interfaces are correctly typed
- Unsupported providers throw appropriate errors

## Next Steps

Future enhancements could include:
1. Implementing Google Gemini Grounding API support
2. Adding Brave Search API integration
3. Implementing retry logic for rate limits
4. Adding caching for repeated queries
5. Supporting batch research operations

## Notes

- The implementation maintains backward compatibility
- All existing methods continue to work unchanged
- Research capabilities are optional and don't affect existing functionality