177 lines
4.5 KiB
Markdown
177 lines
4.5 KiB
Markdown
# 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 |