@autonomaai/agent-core 1.0.2

package/src/types.ts

@@ -0,0 +1,402 @@
+/**
+ * Type definitions for the autonoma Agent Core library.
+ * 
+ * Provides standardized interfaces for AI agents across the ecosystem.
+ */
+
+// Import types - these will be resolved when the package is used
+// with the proper dependencies installed
+export type Tool = any; // from "@langchain/core/tools"
+export type BaseChatModel = any; // from "@langchain/core/language_models/chat_models"
+export type MemorySaver = any; // from "@langchain/langgraph"
+export type ReactAgent = any; // from "@langchain/langgraph/prebuilt"
+export type AgentKit = any; // from "@coinbase/agentkit"
+export type WalletProvider = any; // from "@coinbase/agentkit"
+
+// =============================================================================
+// Agent Configuration Types
+// =============================================================================
+
+// Agent types for autonoma trading platform
+export interface AgentConfig {
+  name: string;
+  description?: string;
+  llm?: {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    openAIApiKey?: string;
+  };
+  agentKit?: {
+    cdpApiKeyId?: string;
+    cdpApiKeySecret?: string;
+    networkId?: string;
+    walletDataFile?: string;
+  };
+  tools?: {
+    enableMCP?: boolean;
+    enableRAG?: boolean;
+    enableAgentKit?: boolean;
+    mcpServerUrl?: string;
+    ragServerUrl?: string;
+    customTools?: any[];
+  };
+  prompt?: {
+    systemMessage?: string;
+    capabilities?: string[];
+    context?: string;
+    instructions?: string;
+    enableConversationMemory?: boolean;
+  };
+  memory?: {
+    enabled?: boolean;
+    persistentThreadId?: boolean;
+    maxMessages?: number;
+  };
+  services?: {
+    messageService?: boolean | MessageService;
+    ragService?: boolean | RAGService;
+    analyticsService?: boolean;
+    loggingEnabled?: boolean;
+  };
+}
+
+export interface TradingAgentConfig extends AgentConfig {
+  prompt?: AgentConfig['prompt'] & {
+    capabilities?: (
+      | 'question_answering'
+      | 'knowledge_base_search'
+      | 'issue_escalation'
+      | 'conversation_management'
+      | 'sentiment_analysis'
+      | 'market_making'
+      | 'exchange_connectivity'
+      | 'real_time_analytics'
+      | 'risk_management'
+      | 'automated_trading'
+      | 'performance_monitoring'
+      | 'defi_yield_optimization'
+      | 'multi_chain_analysis'
+      | 'apy_strategy_development'
+      | 'portfolio_optimization'
+      | 'liquidity_provision'
+      | 'yield_farming'
+      | 'protocol_analysis'
+      | 'viral_detection'
+      | 'memecoin_analysis'
+      | 'social_sentiment'
+      | 'trend_analysis'
+    )[];
+  };
+}
+
+/**
+ * Enhanced agent environment interface supporting agent-specific API keys
+ * with fallback to global keys for backward compatibility
+ */
+export interface AgentEnvironment {
+  // Global API Keys (fallback)
+  OPENAI_API_KEY?: string;
+  OPENAI_MODEL?: string;
+  OPENAI_MAX_TOKENS?: string;
+  CDP_API_KEY_ID?: string;
+  CDP_API_KEY_SECRET?: string;
+  NETWORK_ID?: string;
+  
+  // Portfolio Manager Agent API Keys
+  PORTFOLIO_MANAGER_OPENAI_API_KEY?: string;
+  PORTFOLIO_MANAGER_CDP_API_KEY_ID?: string;
+  PORTFOLIO_MANAGER_CDP_API_KEY_SECRET?: string;
+  PORTFOLIO_MANAGER_NETWORK_ID?: string;
+  PORTFOLIO_MANAGER_OPENAI_MODEL?: string;
+  PORTFOLIO_MANAGER_MAX_TOKENS?: string;
+  
+  // Market Maker Agent API Keys
+  MARKET_MAKER_OPENAI_API_KEY?: string;
+  MARKET_MAKER_CDP_API_KEY_ID?: string;
+  MARKET_MAKER_CDP_API_KEY_SECRET?: string;
+  MARKET_MAKER_NETWORK_ID?: string;
+  MARKET_MAKER_OPENAI_MODEL?: string;
+  MARKET_MAKER_MAX_TOKENS?: string;
+  
+  // Memecoin Agent API Keys
+  MEMECOIN_OPENAI_API_KEY?: string;
+  MEMECOIN_CDP_API_KEY_ID?: string;
+  MEMECOIN_CDP_API_KEY_SECRET?: string;
+  MEMECOIN_NETWORK_ID?: string;
+  MEMECOIN_OPENAI_MODEL?: string;
+  MEMECOIN_MAX_TOKENS?: string;
+  
+  // APY Yields Agent API Keys
+  APY_OPENAI_API_KEY?: string;
+  APY_CDP_API_KEY_ID?: string;
+  APY_CDP_API_KEY_SECRET?: string;
+  APY_NETWORK_ID?: string;
+  APY_OPENAI_MODEL?: string;
+  APY_MAX_TOKENS?: string;
+  
+  // Service URLs
+  MCP_SERVER_URL?: string;
+  RAG_SERVER_URL?: string;
+  NODE_ENV?: string;
+}
+
+/**
+ * Utility function to get agent-specific environment variables with fallback
+ */
+export function getAgentEnvironment(
+  agentType: 'portfolio-manager' | 'market-maker' | 'memecoin' | 'apy'
+): {
+  openaiApiKey: string | undefined;
+  cdpApiKeyId: string | undefined;
+  cdpApiKeySecret: string | undefined;
+  networkId: string;
+  openaiModel: string;
+  maxTokens: number;
+} {
+  const env = process.env as AgentEnvironment;
+  
+  const agentPrefix = agentType.toUpperCase().replace('-', '_');
+  
+  return {
+    openaiApiKey: env[`${agentPrefix}_OPENAI_API_KEY` as keyof AgentEnvironment] || env.OPENAI_API_KEY,
+    cdpApiKeyId: env[`${agentPrefix}_CDP_API_KEY_ID` as keyof AgentEnvironment] || env.CDP_API_KEY_ID,
+    cdpApiKeySecret: env[`${agentPrefix}_CDP_API_KEY_SECRET` as keyof AgentEnvironment] || env.CDP_API_KEY_SECRET,
+    networkId: env[`${agentPrefix}_NETWORK_ID` as keyof AgentEnvironment] || env.NETWORK_ID || 'base-sepolia',
+    openaiModel: env[`${agentPrefix}_OPENAI_MODEL` as keyof AgentEnvironment] || env.OPENAI_MODEL || 'gpt-4o-mini',
+    maxTokens: parseInt(env[`${agentPrefix}_MAX_TOKENS` as keyof AgentEnvironment] || env.OPENAI_MAX_TOKENS || '2000', 10)
+  };
+}
+
+// =============================================================================
+// Agent Interface Types
+// =============================================================================
+
+export interface autonomaAgent {
+  id: string;
+  name: string;
+  description?: string;
+  capabilities: string[];
+  tools: Tool[];
+  config: AgentConfig;
+  
+  // Core methods
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  process(message: AgentMessage): Promise<AgentResponse>;
+  
+  // Configuration methods
+  updateConfig(config: Partial<AgentConfig>): Promise<void>;
+  addTool(tool: Tool): Promise<void>;
+  removeTool(toolName: string): Promise<void>;
+  
+  // State methods
+  getStatus(): AgentStatus;
+  getMetrics(): AgentMetrics;
+  
+  // Memory methods
+  clearMemory(): Promise<void>;
+  getConversationHistory(limit?: number): Promise<AgentMessage[]>;
+}
+
+export interface AgentMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface AgentResponse {
+  content: string;
+  timestamp: string;
+  toolCalls?: ToolCall[];
+  metrics?: {
+    processingTime: number;
+    tokensUsed: number;
+    toolsUsed: string[];
+  };
+  error?: string;
+}
+
+export interface ToolCall {
+  tool: string;
+  input: any;
+  output: any;
+  duration: number;
+  success: boolean;
+  error?: string;
+}
+
+export interface AgentStatus {
+  status: 'idle' | 'processing' | 'error' | 'stopped';
+  uptime: number;
+  lastActivity: string;
+  activeTools: string[];
+  memoryUsage?: {
+    conversationMessages: number;
+    totalMemoryMB: number;
+  };
+}
+
+export interface AgentMetrics {
+  totalMessages: number;
+  totalToolCalls: number;
+  averageResponseTime: number;
+  successRate: number;
+  topTools: Array<{ tool: string; count: number }>;
+  errorCount: number;
+  uptime: number;
+}
+
+// =============================================================================
+// Service Interface Types
+// =============================================================================
+
+export interface MessageService {
+  saveMessage(message: AgentMessage): Promise<void>;
+  getRecentMessages(limit: number): Promise<AgentMessage[]>;
+  getConversationStats(): Promise<{
+    totalMessages: number;
+    userMessages: number;
+    assistantMessages: number;
+  }>;
+  clearHistory(): Promise<void>;
+}
+
+export interface RAGService {
+  search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+  getContext(query: string): Promise<string>;
+  addDocument(document: Document): Promise<void>;
+  getStatus(): Promise<{ available: boolean; documentCount: number }>;
+}
+
+export interface SearchOptions {
+  limit?: number;
+  category?: string;
+  threshold?: number;
+}
+
+export interface SearchResult {
+  content: string;
+  metadata: Record<string, any>;
+  score: number;
+}
+
+export interface Document {
+  id: string;
+  content: string;
+  metadata: Record<string, any>;
+}
+
+// =============================================================================
+// Agent Builder Types
+// =============================================================================
+
+export interface AgentBuilder {
+  setName(name: string): AgentBuilder;
+  setDescription(description: string): AgentBuilder;
+  setLLM(config: AgentConfig['llm']): AgentBuilder;
+  setAgentKit(config: AgentConfig['agentKit']): AgentBuilder;
+  setTools(config: AgentConfig['tools']): AgentBuilder;
+  setPrompt(config: AgentConfig['prompt']): AgentBuilder;
+  setMemory(config: AgentConfig['memory']): AgentBuilder;
+  setServices(config: AgentConfig['services']): AgentBuilder;
+  addCustomTool(tool: Tool): AgentBuilder;
+  build(): Promise<autonomaAgent>;
+}
+
+// =============================================================================
+// LangGraph Integration Types
+// =============================================================================
+
+export type LangGraphAgent = ReactAgent;
+
+export interface LangGraphConfig {
+  llm: BaseChatModel;
+  tools: Tool[];
+  checkpointSaver?: MemorySaver;
+  messageModifier?: string;
+}
+
+// =============================================================================
+// AgentKit Integration Types  
+// =============================================================================
+
+export interface AgentKitConfig {
+  agentKit: AgentKit;
+  walletProvider: WalletProvider;
+  networkId: string;
+}
+
+// =============================================================================
+// Factory Function Types
+// =============================================================================
+
+export interface DataAnalysisAgentConfig extends AgentConfig {
+  analysis?: {
+    dataSources?: string[];
+    updateFrequency?: number;
+    analysisTypes?: string[];
+  };
+}
+
+export interface CustomerServiceAgentConfig extends AgentConfig {
+  customerService?: {
+    knowledgeBase?: string;
+    escalationRules?: Record<string, any>;
+    supportedLanguages?: string[];
+  };
+} 
+
+export interface DeFiYieldAgentConfig extends AgentConfig {
+  // DeFi-specific configuration
+  defiConfig?: {
+    // Risk management parameters
+    maxProtocolAllocation?: number;      // Maximum allocation per protocol (default: 0.25)
+    maxPortfolioRisk?: number;          // Maximum portfolio VaR (default: 0.15)
+    minLiquidityThreshold?: number;     // Minimum liquidity requirement (default: 1000000)
+    maxRiskScore?: number;              // Maximum protocol risk score (default: 70)
+    
+    // Optimization settings
+    optimizationStrategy?: 'max_sharpe' | 'risk_parity' | 'mean_variance';
+    rebalancingThreshold?: number;      // Portfolio drift threshold (default: 0.02)
+    rebalancingFrequency?: 'daily' | 'weekly' | 'monthly';
+    
+    // Chain preferences
+    supportedChains?: string[];         // Supported blockchain networks
+    preferredChains?: string[];         // Preferred chains for optimization
+    
+    // Protocol filters
+    whitelistedProtocols?: string[];    // Approved protocols only
+    blacklistedProtocols?: string[];    // Excluded protocols
+    minProtocolTVL?: number;           // Minimum protocol TVL
+    minAuditScore?: number;            // Minimum audit score requirement
+    
+    // Transaction settings
+    maxGasCost?: number;               // Maximum acceptable gas cost
+    slippageTolerance?: number;        // Maximum slippage tolerance
+    mevProtection?: boolean;           // Enable MEV protection
+    
+    // Performance settings
+    benchmarkStrategy?: string;        // Benchmark for performance comparison
+    performanceReportingFrequency?: 'daily' | 'weekly' | 'monthly';
+    enableRealTimeAlerts?: boolean;    // Enable real-time performance alerts
+  };
+  
+  // RAG configuration for DeFi knowledge
+  ragConfig?: {
+    serverUrl?: string;
+    enableHistoricalDecisions?: boolean;
+    enableProtocolKnowledge?: boolean;
+    enableRiskAnalysis?: boolean;
+    knowledgeUpdateFrequency?: 'hourly' | 'daily' | 'weekly';
+  };
+  
+  // Integration settings
+  orchestratorConfig?: {
+    url?: string;
+    enableCoordination?: boolean;
+    conflictResolutionStrategy?: 'priority' | 'consensus' | 'arbitration';
+    resourceSharingEnabled?: boolean;
+  };
+}