feat(research): Introduce research API with provider implementations, docs and tests

test/test.basic.ts

@@ -0,0 +1,92 @@
+import { tap, expect } from '@push.rocks/tapbundle';
+import * as smartai from '../ts/index.js';
+
+// Basic instantiation tests that don't require API tokens
+// These tests can run in CI/CD environments without credentials
+
+tap.test('Basic: should create SmartAi instance', async () => {
+  const testSmartai = new smartai.SmartAi({
+    openaiToken: 'dummy-token-for-testing'
+  });
+  expect(testSmartai).toBeInstanceOf(smartai.SmartAi);
+  expect(testSmartai.openaiProvider).toBeTruthy();
+});
+
+tap.test('Basic: should instantiate OpenAI provider', async () => {
+  const openaiProvider = new smartai.OpenAiProvider({
+    openaiToken: 'dummy-token'
+  });
+  expect(openaiProvider).toBeInstanceOf(smartai.OpenAiProvider);
+  expect(typeof openaiProvider.chat).toEqual('function');
+  expect(typeof openaiProvider.audio).toEqual('function');
+  expect(typeof openaiProvider.vision).toEqual('function');
+  expect(typeof openaiProvider.document).toEqual('function');
+  expect(typeof openaiProvider.research).toEqual('function');
+});
+
+tap.test('Basic: should instantiate Anthropic provider', async () => {
+  const anthropicProvider = new smartai.AnthropicProvider({
+    anthropicToken: 'dummy-token'
+  });
+  expect(anthropicProvider).toBeInstanceOf(smartai.AnthropicProvider);
+  expect(typeof anthropicProvider.chat).toEqual('function');
+  expect(typeof anthropicProvider.audio).toEqual('function');
+  expect(typeof anthropicProvider.vision).toEqual('function');
+  expect(typeof anthropicProvider.document).toEqual('function');
+  expect(typeof anthropicProvider.research).toEqual('function');
+});
+
+tap.test('Basic: should instantiate Perplexity provider', async () => {
+  const perplexityProvider = new smartai.PerplexityProvider({
+    perplexityToken: 'dummy-token'
+  });
+  expect(perplexityProvider).toBeInstanceOf(smartai.PerplexityProvider);
+  expect(typeof perplexityProvider.chat).toEqual('function');
+  expect(typeof perplexityProvider.research).toEqual('function');
+});
+
+tap.test('Basic: should instantiate Groq provider', async () => {
+  const groqProvider = new smartai.GroqProvider({
+    groqToken: 'dummy-token'
+  });
+  expect(groqProvider).toBeInstanceOf(smartai.GroqProvider);
+  expect(typeof groqProvider.chat).toEqual('function');
+  expect(typeof groqProvider.research).toEqual('function');
+});
+
+tap.test('Basic: should instantiate Ollama provider', async () => {
+  const ollamaProvider = new smartai.OllamaProvider({
+    baseUrl: 'http://localhost:11434'
+  });
+  expect(ollamaProvider).toBeInstanceOf(smartai.OllamaProvider);
+  expect(typeof ollamaProvider.chat).toEqual('function');
+  expect(typeof ollamaProvider.research).toEqual('function');
+});
+
+tap.test('Basic: should instantiate xAI provider', async () => {
+  const xaiProvider = new smartai.XaiProvider({
+    xaiToken: 'dummy-token'
+  });
+  expect(xaiProvider).toBeInstanceOf(smartai.XaiProvider);
+  expect(typeof xaiProvider.chat).toEqual('function');
+  expect(typeof xaiProvider.research).toEqual('function');
+});
+
+tap.test('Basic: should instantiate Exo provider', async () => {
+  const exoProvider = new smartai.ExoProvider({
+    exoBaseUrl: 'http://localhost:8000'
+  });
+  expect(exoProvider).toBeInstanceOf(smartai.ExoProvider);
+  expect(typeof exoProvider.chat).toEqual('function');
+  expect(typeof exoProvider.research).toEqual('function');
+});
+
+tap.test('Basic: all providers should extend MultiModalModel', async () => {
+  const openai = new smartai.OpenAiProvider({ openaiToken: 'test' });
+  const anthropic = new smartai.AnthropicProvider({ anthropicToken: 'test' });
+
+  expect(openai).toBeInstanceOf(smartai.MultiModalModel);
+  expect(anthropic).toBeInstanceOf(smartai.MultiModalModel);
+});
+
+export default tap.start();

test/test.interfaces.ts

@@ -0,0 +1,140 @@
+import { tap, expect } from '@push.rocks/tapbundle';
+import * as smartai from '../ts/index.js';
+
+// Test interface exports and type checking
+// These tests verify that all interfaces are properly exported and usable
+
+tap.test('Interfaces: ResearchOptions should be properly typed', async () => {
+  const testOptions: smartai.ResearchOptions = {
+    query: 'test query',
+    searchDepth: 'basic',
+    maxSources: 10,
+    includeWebSearch: true,
+    background: false
+  };
+
+  expect(testOptions).toBeInstanceOf(Object);
+  expect(testOptions.query).toEqual('test query');
+  expect(testOptions.searchDepth).toEqual('basic');
+});
+
+tap.test('Interfaces: ResearchResponse should be properly typed', async () => {
+  const testResponse: smartai.ResearchResponse = {
+    answer: 'test answer',
+    sources: [
+      {
+        url: 'https://example.com',
+        title: 'Example Source',
+        snippet: 'This is a snippet'
+      }
+    ],
+    searchQueries: ['query1', 'query2'],
+    metadata: {
+      model: 'test-model',
+      tokensUsed: 100
+    }
+  };
+
+  expect(testResponse).toBeInstanceOf(Object);
+  expect(testResponse.answer).toEqual('test answer');
+  expect(testResponse.sources).toBeArray();
+  expect(testResponse.sources[0].url).toEqual('https://example.com');
+});
+
+tap.test('Interfaces: ChatOptions should be properly typed', async () => {
+  const testChatOptions: smartai.ChatOptions = {
+    systemMessage: 'You are a helpful assistant',
+    userMessage: 'Hello',
+    messageHistory: [
+      { role: 'user', content: 'Previous message' },
+      { role: 'assistant', content: 'Previous response' }
+    ]
+  };
+
+  expect(testChatOptions).toBeInstanceOf(Object);
+  expect(testChatOptions.systemMessage).toBeTruthy();
+  expect(testChatOptions.messageHistory).toBeArray();
+});
+
+tap.test('Interfaces: ChatResponse should be properly typed', async () => {
+  const testChatResponse: smartai.ChatResponse = {
+    role: 'assistant',
+    message: 'This is a response'
+  };
+
+  expect(testChatResponse).toBeInstanceOf(Object);
+  expect(testChatResponse.role).toEqual('assistant');
+  expect(testChatResponse.message).toBeTruthy();
+});
+
+tap.test('Interfaces: ChatMessage should be properly typed', async () => {
+  const testMessage: smartai.ChatMessage = {
+    role: 'user',
+    content: 'Test message'
+  };
+
+  expect(testMessage).toBeInstanceOf(Object);
+  expect(testMessage.role).toBeOneOf(['user', 'assistant', 'system']);
+  expect(testMessage.content).toBeTruthy();
+});
+
+tap.test('Interfaces: Provider options should be properly typed', async () => {
+  // OpenAI options
+  const openaiOptions: smartai.IOpenaiProviderOptions = {
+    openaiToken: 'test-token',
+    chatModel: 'gpt-5-mini',
+    audioModel: 'tts-1-hd',
+    visionModel: '04-mini',
+    researchModel: 'o4-mini-deep-research-2025-06-26',
+    enableWebSearch: true
+  };
+
+  expect(openaiOptions).toBeInstanceOf(Object);
+  expect(openaiOptions.openaiToken).toBeTruthy();
+
+  // Anthropic options
+  const anthropicOptions: smartai.IAnthropicProviderOptions = {
+    anthropicToken: 'test-token',
+    enableWebSearch: true,
+    searchDomainAllowList: ['example.com'],
+    searchDomainBlockList: ['blocked.com']
+  };
+
+  expect(anthropicOptions).toBeInstanceOf(Object);
+  expect(anthropicOptions.anthropicToken).toBeTruthy();
+});
+
+tap.test('Interfaces: Search depth values should be valid', async () => {
+  const validDepths: smartai.ResearchOptions['searchDepth'][] = ['basic', 'advanced', 'deep'];
+
+  for (const depth of validDepths) {
+    const options: smartai.ResearchOptions = {
+      query: 'test',
+      searchDepth: depth
+    };
+    expect(options.searchDepth).toBeOneOf(['basic', 'advanced', 'deep', undefined]);
+  }
+});
+
+tap.test('Interfaces: Optional properties should work correctly', async () => {
+  // Minimal ResearchOptions
+  const minimalOptions: smartai.ResearchOptions = {
+    query: 'test query'
+  };
+
+  expect(minimalOptions.query).toBeTruthy();
+  expect(minimalOptions.searchDepth).toBeUndefined();
+  expect(minimalOptions.maxSources).toBeUndefined();
+
+  // Minimal ChatOptions
+  const minimalChat: smartai.ChatOptions = {
+    systemMessage: 'system',
+    userMessage: 'user',
+    messageHistory: []
+  };
+
+  expect(minimalChat.messageHistory).toBeArray();
+  expect(minimalChat.messageHistory.length).toEqual(0);
+});
+
+export default tap.start();

test/test.openai.ts

@@ -9,14 +9,14 @@ import * as smartai from '../ts/index.js';
 
 let testSmartai: smartai.SmartAi;
 
-tap.test('should create a smartai instance', async () => {
+tap.test('OpenAI: should create a smartai instance with OpenAI provider', async () => {
   testSmartai = new smartai.SmartAi({
     openaiToken: await testQenv.getEnvVarOnDemand('OPENAI_TOKEN'),
   });
   await testSmartai.start();
 });
 
-tap.test('should create chat response with openai', async () => {
+tap.test('OpenAI: should create chat response', async () => {
   const userMessage = 'How are you?';
   const response = await testSmartai.openaiProvider.chat({
     systemMessage: 'Hello',
@@ -27,7 +27,7 @@ tap.test('should create chat response with openai', async () => {
   console.log(response.message);
 });
 
-tap.test('should document a pdf', async () => {
+tap.test('OpenAI: should document a pdf', async () => {
   const pdfUrl = 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf';
   const pdfResponse = await smartrequest.SmartRequest.create()
     .url(pdfUrl)
@@ -41,7 +41,7 @@ tap.test('should document a pdf', async () => {
   console.log(result);
 });
 
-tap.test('should recognize companies in a pdf', async () => {
+tap.test('OpenAI: should recognize companies in a pdf', async () => {
   const pdfBuffer = await smartfile.fs.toBuffer('./.nogit/demo_without_textlayer.pdf');
   const result = await testSmartai.openaiProvider.document({
     systemMessage: `
@@ -78,7 +78,7 @@ tap.test('should recognize companies in a pdf', async () => {
   console.log(result);
 });
 
-tap.test('should create audio response with openai', async () => {
+tap.test('OpenAI: should create audio response', async () => {
   // Call the audio method with a sample message.
   const audioStream = await testSmartai.openaiProvider.audio({
     message: 'This is a test of audio generation.',
@@ -95,7 +95,7 @@ tap.test('should create audio response with openai', async () => {
   expect(audioBuffer.length).toBeGreaterThan(0);
 });
 
-tap.test('should stop the smartai instance', async () => {
+tap.test('OpenAI: should stop the smartai instance', async () => {
   await testSmartai.stop();
 });
 

test/test.research.ts

@@ -0,0 +1,65 @@
+import { tap, expect } from '@push.rocks/tapbundle';
+import * as smartai from '../ts/index.js';
+
+// Test the research capabilities
+tap.test('OpenAI research method should exist', async () => {
+  const openaiProvider = new smartai.OpenAiProvider({
+    openaiToken: 'test-token'
+  });
+
+  // Check that the research method exists
+  expect(typeof openaiProvider.research).toEqual('function');
+});
+
+tap.test('Anthropic research method should exist', async () => {
+  const anthropicProvider = new smartai.AnthropicProvider({
+    anthropicToken: 'test-token'
+  });
+
+  // Check that the research method exists
+  expect(typeof anthropicProvider.research).toEqual('function');
+});
+
+tap.test('Research interfaces should be exported', async () => {
+  // Check that the types are available (they won't be at runtime but TypeScript will check)
+  const testResearchOptions: smartai.ResearchOptions = {
+    query: 'test query',
+    searchDepth: 'basic'
+  };
+
+  expect(testResearchOptions).toBeInstanceOf(Object);
+  expect(testResearchOptions.query).toEqual('test query');
+});
+
+tap.test('Perplexity provider should have research method', async () => {
+  const perplexityProvider = new smartai.PerplexityProvider({
+    perplexityToken: 'test-token'
+  });
+
+  // For Perplexity, we actually implemented it, so let's just check it exists
+  expect(typeof perplexityProvider.research).toEqual('function');
+});
+
+tap.test('Other providers should have research stubs', async () => {
+  const groqProvider = new smartai.GroqProvider({
+    groqToken: 'test-token'
+  });
+
+  const ollamaProvider = new smartai.OllamaProvider({});
+
+  // Check that the research method exists and throws error
+  expect(typeof groqProvider.research).toEqual('function');
+  expect(typeof ollamaProvider.research).toEqual('function');
+
+  // Test that they throw errors when called
+  let errorCaught = false;
+  try {
+    await groqProvider.research({ query: 'test' });
+  } catch (error) {
+    errorCaught = true;
+    expect(error.message).toInclude('not yet supported');
+  }
+  expect(errorCaught).toBeTrue();
+});
+
+export default tap.start();