@serovaai/sdk

Official Serova SDK for Node.js - API client and AI agent tools.

Installation

npm install @serovaai/sdk
# or
pnpm add @serovaai/sdk
# or
yarn add @serovaai/sdk

Quick Start

import { SerovaClient } from '@serovaai/sdk';

const client = new SerovaClient({
  apiKey: process.env.SEROVA_API_KEY!,
  defaultContextId: 'your-community-context-id',
});

// Search for recommendations
const results = await client.awareness.searchRecommendations({
  query: 'plumbers',
  limit: 10,
});

console.log(results.recommendations);

Using with OpenAI Agents SDK

The SDK includes pre-built tool definitions for OpenAI's function calling:

import { SerovaClient, allTools, createToolExecutor } from '@serovaai/sdk';
import OpenAI from 'openai';

const client = new SerovaClient({
  apiKey: process.env.SEROVA_API_KEY!,
  defaultContextId: process.env.SEROVA_CONTEXT_ID!,
});

const openai = new OpenAI();
const executor = createToolExecutor(client);

// Register Serova tools with your agent
const tools = allTools.map((t) => ({ type: 'function' as const, function: t }));

// Create a chat completion with tools
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Can you recommend a plumber?' }],
  tools,
});

// Handle tool calls
for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await executor(
    toolCall.function.name,
    JSON.parse(toolCall.function.arguments)
  );
  console.log(result);
}

Available Tools

| Tool Name | Description | |-----------|-------------| | serova_get_recommendations | Search for service recommendations | | serova_get_sentiment_stats | Get community sentiment statistics | | serova_get_categories | List available recommendation categories |

API Reference

SerovaClient

Main client for interacting with the Serova API.

const client = new SerovaClient({
  apiKey: string;           // Required: Your API key
  baseUrl?: string;         // Optional: API base URL (default: https://api.serova.ai)
  defaultContextId?: string; // Optional: Default context for queries
  timeout?: number;         // Optional: Request timeout in ms (default: 30000)
});

Awareness API

client.awareness.searchRecommendations(query)

Search for recommendations by query string.

const results = await client.awareness.searchRecommendations({
  query: 'italian restaurants',
  limit: 10,
});

client.awareness.getRecommendations(query)

Get paginated recommendations with filters.

const results = await client.awareness.getRecommendations({
  category: 'home services',
  sentiment: 'positive',
  limit: 20,
  offset: 0,
});

client.awareness.getCategories()

Get available recommendation categories.

const categories = await client.awareness.getCategories();
// ['home services', 'food', 'healthcare', ...]

client.awareness.getSentimentStats(query)

Get sentiment statistics for a context.

const stats = await client.awareness.getSentimentStats({
  startDate: '2024-01-01',
  endDate: '2024-12-31',
});
// { positive: 150, neutral: 80, negative: 20, total: 250 }

License

MIT