@robota-sdk/core

Core package for Robota SDK - A powerful AI agent framework with a modular Manager pattern architecture.

Documentation

For full documentation, visit https://robota.io

Installation

npm install @robota-sdk/core

Overview

@robota-sdk/core provides the foundation for building AI agents with Robota SDK. Built with a clean Manager pattern architecture, it separates concerns across specialized managers while providing a unified API through the main Robota class.

Key Features & Advantages

🚀 Multi-Provider Support

• OpenAI: GPT-4, GPT-3.5 - Function calling, streaming, vision support
• Anthropic: Claude 3.5 Sonnet, Claude 3 - Large context, advanced reasoning
• Google AI: Gemini 1.5 Pro, Gemini Flash - Multimodal, long context
• Seamless switching between providers and dynamic configuration

⚡ Real-Time Streaming Responses

• Real-time streaming support across all providers
• Chunk-based response processing for fast user experience
• Background processing and asynchronous responses

📊 Analytics & Monitoring

• Detailed usage statistics including request count and token usage
• Real-time limit management (token and request limits)
• Comprehensive logging system for debugging

🏗️ Modular Architecture

• Clean separation of concerns with high extensibility
• Independent usage of each component
• Plugin-style tool and provider system

🛠️ Type-Safe Function Calling

• Zod schema-based type-safe function definitions
• Automatic parameter validation and type inference
• Extensible tool system architecture

Architecture Overview

Manager Pattern

The core package is built around specialized managers that handle specific domains:

• AIProviderManager: Manages multiple AI providers and model switching
• ToolProviderManager: Handles tool registration and execution
• SystemMessageManager: Manages system prompts and messages
• ToolProviderManager: Handles tool registration and execution
• AnalyticsManager: Tracks usage, token consumption, and request history
• RequestLimitManager: Enforces token and request limits

Service Layer

• ConversationService: Orchestrates conversation flow and AI interactions
• TokenAnalyzer: Calculates and estimates token usage

Core Features

• Provider-agnostic architecture with easy switching
• Real-time streaming responses across all providers
• Comprehensive conversation history management
• Built-in analytics and monitoring
• Request/token limit enforcement
• Type-safe function calling integration

Basic Usage

import { Robota } from '@robota-sdk/core';
import { OpenAIProvider } from '@robota-sdk/openai';
import { createZodFunctionToolProvider } from '@robota-sdk/tools';
import { z } from 'zod';
import OpenAI from 'openai';

// Create OpenAI client and provider
const openaiClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const openaiProvider = new OpenAIProvider(openaiClient);

// Create tool provider
const toolProvider = createZodFunctionToolProvider({
  tools: {
    getWeather: {
      name: 'getWeather',
      description: 'Get weather information',
      parameters: z.object({
        location: z.string().describe('City name')
      }),
      handler: async ({ location }) => {
        return { temperature: 22, condition: 'Sunny', location };
      }
    }
  }
});

// Create Robota instance with Manager pattern
const robota = new Robota({
  aiProviders: {
    openai: openaiProvider
  },
  currentProvider: 'openai',
  currentModel: 'gpt-4',
  toolProviders: [toolProvider],
  systemPrompt: 'You are a helpful AI assistant.',
  maxTokenLimit: 4096,  // Request limit management
  maxRequestLimit: 25,  // Request count limit
  debug: true          // Enable detailed logging
});

// Simple conversation
const response = await robota.run('Tell me about TypeScript and check weather in Seoul');
console.log(response);

// Streaming response
const stream = await robota.runStream('What is the weather like?');
for await (const chunk of stream) {
  process.stdout.write(chunk.content || '');
}

// Analytics and monitoring
console.log('Analytics:', robota.getAnalytics());
console.log('Limit Info:', robota.getLimitInfo());

// Clean up resources
await robota.close();

Manager APIs

AI Provider Management

// Add providers dynamically
robota.addAIProvider('anthropic', anthropicProvider);
robota.addAIProvider('google', googleProvider);

// Switch providers
robota.setCurrentAI('anthropic', 'claude-3-5-sonnet-20241022');
robota.setCurrentAI('google', 'gemini-1.5-pro');

// Get current configuration
const currentAI = robota.getCurrentAI();
console.log(`Using: ${currentAI.provider}/${currentAI.model}`);

System Message Management

// Set system prompt
robota.setSystemPrompt('You are a helpful coding assistant.');

// Add multiple system messages
robota.setSystemMessages([
  { role: 'system', content: 'You are an expert in TypeScript.' },
  { role: 'system', content: 'Always provide code examples.' }
]);

// Add individual system message
robota.addSystemMessage('Focus on best practices and clean code.');

Tool Provider Management

// Add tool providers
robota.addToolProvider(weatherToolProvider);
robota.addToolProvider(calculatorToolProvider);

// Remove tool provider
robota.removeToolProvider('weather-tools');

// Get available tools
const availableTools = robota.getAvailableTools();
console.log('Available tools:', availableTools.map(t => t.name));

Analytics and Monitoring

// Get usage statistics
const analytics = robota.getAnalytics();
console.log(`Requests: ${analytics.requestCount}`);
console.log(`Total tokens: ${analytics.totalTokensUsed}`);
console.log(`Average tokens per request: ${analytics.averageTokensPerRequest}`);

// Get detailed limit information
const limitInfo = robota.getLimitInfo();
console.log(`Token usage: ${limitInfo.currentTokensUsed}/${limitInfo.maxTokens}`);
console.log(`Requests: ${limitInfo.currentRequestCount}/${limitInfo.maxRequests}`);

// Get token usage for specific period
const weeklyUsage = robota.getTokenUsageByPeriod(
  new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), // 7 days ago
  new Date()
);

Request Limit Management

// Set limits
robota.setMaxTokenLimit(10000);  // 10k tokens max
robota.setMaxRequestLimit(100);  // 100 requests max

// Set unlimited (0 = unlimited)
robota.setMaxTokenLimit(0);
robota.setMaxRequestLimit(0);

// Check current limits
console.log('Max tokens:', robota.getMaxTokenLimit());
console.log('Max requests:', robota.getMaxRequestLimit());

Core Components

Interfaces

• AIProvider: Interface for AI provider implementations
• ToolProvider: Interface for tool provider implementations
• ConversationHistory: Interface for conversation history management
• Logger: Interface for custom logging implementations

Conversation History

import { SimpleConversationHistory, PersistentSystemConversationHistory } from '@robota-sdk/core';

// Simple in-memory history
const simpleHistory = new SimpleConversationHistory();

// Persistent history with system message handling
const persistentHistory = new PersistentSystemConversationHistory();

const robota = new Robota({
  // ... other options
  conversationHistory: persistentHistory
});

Custom Logger

const customLogger = {
  info: (msg, ...args) => console.log(`[INFO] ${msg}`, ...args),
  debug: (msg, ...args) => console.log(`[DEBUG] ${msg}`, ...args),
  warn: (msg, ...args) => console.warn(`[WARN] ${msg}`, ...args),
  error: (msg, ...args) => console.error(`[ERROR] ${msg}`, ...args)
};

const robota = new Robota({
  // ... other options
  logger: customLogger,
  debug: true
});

Tool Integration

Tool and function creation utilities are provided by the @robota-sdk/tools package:

• createZodFunctionToolProvider - Zod schema-based tools
• createMcpToolProvider - MCP (Model Context Protocol) integration
• createOpenAPIToolProvider - OpenAPI specification tools

License

MIT