smartai/readme.research.md

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:

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

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

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

Research with Anthropic

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

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:

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