add detailed comments

Author: fishonamos

packages/sui-agent/src/@types/interface.ts

@@ -1,4 +1,21 @@
-// Response interface for the intent agent's operations
+/**
+ * Core Type Definitions for the Atoma AI Agent System
+ * This file contains all the essential interfaces and types used throughout the agent.
+ *
+ * The type system is designed to ensure:
+ * 1. Type Safety - Strong typing for all agent operations
+ * 2. Consistency - Standardized interfaces across the system
+ * 3. Extensibility - Easy addition of new tools and features
+ *
+ * @module Types
+ */
+
+/**
+ * Response interface for the intent agent's operations.
+ * Represents the structured output from tool selection and execution.
+ *
+ * @interface IntentAgentResponse
+ */
 export interface IntentAgentResponse {
   success: boolean; // Indicates if the operation was successful
   selected_tools: null | string[]; // Name of the tool that was selected for the operation
@@ -8,9 +25,20 @@ export interface IntentAgentResponse {
   tool_arguments: (string | number | boolean | bigint)[]; // Arguments passed to the tool
 }
 
+/**
+ * Basic type for tool arguments.
+ * Supports common primitive types used in tool execution.
+ *
+ * @typedef ToolArgument
+ */
 export type ToolArgument = string | number | boolean | bigint;
 
-// Response interface for tool operations (similar to IntentAgentResponse)
+/**
+ * Response interface for tool operations.
+ * Similar structure to IntentAgentResponse for consistency.
+ *
+ * @interface toolResponse
+ */
 export interface toolResponse {
   success: boolean;
   selected_tools: null | string;
@@ -20,15 +48,25 @@ export interface toolResponse {
   tool_arguments: (string | number | boolean | bigint)[];
 }
 
-// Defines the structure for tool parameters
+/**
+ * Defines the structure for tool parameters.
+ * Used in tool registration and validation.
+ *
+ * @interface ToolParameter
+ */
 export interface ToolParameter {
   name: string; // Name of the parameter
   type: string; // Data type of the parameter
   description: string; // Description of what the parameter does
   required: boolean; // Whether the parameter is mandatory
 }
 
-// Defines the structure for tools that can be used by the agent
+/**
+ * Defines the structure for tools that can be used by the agent.
+ * Core interface for all tool implementations.
+ *
+ * @interface Tool
+ */
 export interface Tool {
   name: string; // Name of the tool
   description: string; // Description of what the tool does
@@ -38,8 +76,21 @@ export interface Tool {
   ) => Promise<string> | string; // Function to execute the tool
 }
 
-// Mapping of different coin names/variants to their standardized symbol
-// This helps in recognizing different ways users might refer to the same coin
+/**
+ * Mapping of different coin names/variants to their standardized symbol.
+ * Helps in recognizing different ways users might refer to the same coin.
+ *
+ * Key Features:
+ * - Case-insensitive matching
+ * - Multiple variants per coin
+ * - Standardized output symbols
+ *
+ * TODO:
+ * - Add support for more coin variants
+ * - Add support for token metadata
+ *
+ * @const COIN_SYNONYMS
+ */
 export const COIN_SYNONYMS: Record<string, string> = {
   // SUI and variants
   SUI: 'SUI',
@@ -124,8 +175,16 @@ export const COIN_SYNONYMS: Record<string, string> = {
   WSBCOIN: 'WSB',
 } as const;
 
-// Mapping of coin symbols to their respective addresses on the Sui network
-// These addresses are used to interact with the coins on the blockchain
+/**
+ * Mapping of coin symbols to their respective addresses on the Sui network.
+ * Used for blockchain interactions and token operations.
+ *
+ * Features:
+ * - Mainnet addresses
+ * - Type information
+ * - Standardized format
+ * @const COIN_ADDRESSES
+ */
 export const COIN_ADDRESSES = {
   SUI: '0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI',
   USDC: '0x549e8b69270defbfafd4f94e17ec44cdbdd99820b33bda2278dea3b9a32d3f55::cert::CERT',
@@ -164,27 +223,46 @@ export const COIN_ADDRESSES = {
   WSB: '0x4db126eac4fa99207e98db61d968477021fdeae153de3b244bcfbdc468ef0722::wsb::WSB',
 } as const;
 
-// Structure for token balance information
+/**
+ * Structure for token balance information.
+ * Used for representing token holdings and balances.
+ *
+ * @interface TokenBalance
+ */
 export interface TokenBalance {
   token: string; // Token address or identifier
   amount: bigint; // Token amount
   symbol?: string; // Token symbol (optional)
   decimals?: number; // Number of decimal places for the token (optional)
 }
 
-// Configuration for a specific network (mainnet or testnet)
+/**
+ * Configuration for a specific network (mainnet or testnet).
+ * Contains network-specific endpoints and settings.
+ *
+ * @interface NetworkConfig
+ */
 export interface NetworkConfig {
   fullnode: string; // URL for the network's fullnode
   faucet?: string; // URL for the network's faucet (optional)
 }
 
-// Configuration for all supported networks
+/**
+ * Configuration for all supported networks.
+ * Manages configurations for different network environments.
+ *
+ * @interface NetworkConfigs
+ */
 export interface NetworkConfigs {
   MAINNET: NetworkConfig; // Mainnet configuration
   TESTNET: NetworkConfig; // Testnet configuration
 }
 
-// Network configuration constants
+/**
+ * Network configuration constants.
+ * Defines the default network endpoints and settings.
+ * @const NETWORK_CONFIG
+ */
 export const NETWORK_CONFIG: NetworkConfigs = {
   MAINNET: {
     fullnode: 'https://fullnode.mainnet.sui.io',

packages/sui-agent/src/agents/SuiAgent.ts

@@ -8,8 +8,22 @@ import Atoma from '../config/atoma';
 import decomposerPrompt from '../prompts/decomposer';
 
 /**
- * Main agent class that handles intent processing and decision making
- * Coordinates between different agent types to process user queries
+ * Main agent class that handles intent processing and decision making.
+ * Coordinates between different agent types to process user queries.
+ * This is the primary entry point for all agent-based operations.
+ *
+ * The agent follows a pipeline architecture:
+ * 1. Query Decomposition - Breaks down complex queries into simpler subqueries
+ * 2. Tool Selection - Identifies appropriate tools for each subquery
+ * 3. Query Processing - Executes tools and aggregates results
+ *
+ * TODO:
+ * - Implement retry mechanisms for failed tool executions
+ * - Add context management to maintain conversation history
+ * - Implement caching for frequently used tool results
+ * - Add error recovery strategies for each pipeline stage
+ * - Implement rate limiting for API calls
+ * - Add validation for tool arguments before execution
  *
  * @example
  * const agent = new Agents("your-bearer-auth-token");
@@ -21,6 +35,13 @@ class Agents {
   private utils: Utils;
   private AtomaClass: Atoma;
 
+  /**
+   * Creates a new instance of the Agents class.
+   * Initializes all necessary components and registers available tools.
+   *
+   * @param bearerAuth - Authentication token for API access
+   * TODO: Add support for additional configuration options
+   */
   constructor(bearerAuth: string) {
     this.tools = new Tools(bearerAuth, intent_agent_prompt);
     this.AtomaClass = new Atoma(bearerAuth);
@@ -29,6 +50,13 @@ class Agents {
     registerAllTools(this.tools);
   }
 
+  /**
+   * Decomposes a complex user query into simpler subqueries that can be processed independently.
+   * Uses the Atoma LLM to break down queries based on the decomposer prompt.
+   *
+   * @param prompt - The original user query to decompose
+   * @returns Promise containing array of decomposed subqueries
+   */
   async QueryDecomposer(prompt: string) {
     return await this.AtomaClass.atomaChat([
       { content: decomposerPrompt, role: 'assistant' },
@@ -37,9 +65,12 @@ class Agents {
   }
 
   /**
-   * Processes initial user intent and selects appropriate tools
-   * @param prompt - User's input query
-   * @returns IntentAgentResponse containing tool selection and processing details
+   * Analyzes decomposed subqueries and selects appropriate tools for processing each one.
+   * Maps each subquery to one or more tools that can handle it.
+   *
+   * @param subqueries - Array of decomposed subqueries
+   * @param address - Optional wallet address for context
+   * @returns Promise containing tool selection responses for each subquery
    */
   async toolsSelector(subqueries: string[], address?: string) {
     const IntentResponse: IntentAgentResponse[] =
@@ -53,14 +84,17 @@ class Agents {
   }
 
   /**
-   * Makes decisions based on the intent response and user query
-   * @param intentResponse - Response from the IntentAgent
-   * @param query - Original user query
-   * @returns Processed response after decision making
+   * Processes the selected tools' responses and generates a final answer.
+   * Coordinates execution of tools and aggregates their results.
+   *
+   * @param intentResponse - Array of tool selection responses
+   * @param query - Original user query for context
+   * @returns Promise containing processed final response
+   *
+   * TODO:
+   * - Add support for parallel tool execution
    */
   async QueryProcessor(intentResponse: IntentAgentResponse[], query: string) {
-    // Pass both the selected tool name and arguments to processQuery
-
     return await this.utils.processQuery(
       this.AtomaClass,
       query,
@@ -69,10 +103,18 @@ class Agents {
   }
 
   /**
-   * Main entry point for processing user queries
-   * Coordinates between IntentAgent and DecisionMakingAgent
+   * Main pipeline for processing user queries from start to finish.
+   * Orchestrates the entire process from query decomposition to final response.
+   *
+   * Pipeline stages:
+   * 1. Query decomposition
+   * 2. Tool selection for each subquery
+   * 3. Tool execution and response processing
+   * 4. Final answer generation
+   *
    * @param prompt - User's input query
-   * @returns Final processed response
+   * @param walletAddress - Optional wallet address for context
+   * @returns Promise containing final processed response
    */
   async processUserQueryPipeline(prompt: string, walletAddress?: string) {
     // Process intent

packages/sui-agent/src/config/atoma.ts

@@ -2,21 +2,70 @@ import { AtomaSDK } from 'atoma-sdk';
 import * as dotenv from 'dotenv';
 dotenv.config();
 
+/**
+ * Default model for chat completions if not specified in environment
+ * Currently defaults to Llama-3.3-70B-Instruct for optimal performance
+ *
+ * TODO:
+ * - Add support for model fallbacks
+ * - Implement model performance tracking
+ * - Add model selection based on query complexity
+ */
 const ATOMA_CHAT_COMPLETIONS_MODEL =
   process.env.ATOMA_CHAT_MODEL || 'meta-llama/Llama-3.3-70B-Instruct';
 console.log(ATOMA_CHAT_COMPLETIONS_MODEL);
 
+/**
+ * Core class for interacting with the Atoma AI platform.
+ * Handles all LLM-related operations including chat completions and health checks.
+ *
+ * This class serves as the primary interface for:
+ * - Chat completions
+ * - Model management
+ * - Health monitoring
+ * - SDK initialization
+ *
+ * TODO:
+ * - Implement request rate limiting
+ * - Add response caching
+ * - Implement retry mechanisms
+ * - Add support for streaming responses
+ * - Implement context management
+ * - Add token usage tracking
+ * - Implement cost optimization strategies
+ */
 class Atoma {
   private bearerAuth;
+
+  /**
+   * Creates a new Atoma instance with authentication
+   *
+   * @param bearerAuth - Bearer authentication token for API access
+   *
+   * TODO:
+   * - Add support for multiple authentication methods
+   * - Implement token refresh mechanism
+   * - Add token validation
+   */
   constructor(bearerAuth: string) {
     this.bearerAuth = bearerAuth;
   }
 
   /**
-   * Helper function to create chat completions using Atoma SDK
-   * @param messages - Array of message objects with content and role
+   * Creates chat completions using the Atoma SDK.
+   * Handles message formatting and model selection.
+   *
+   * @param messages - Array of message objects containing content and role
    * @param model - Optional model identifier (defaults to environment variable or Llama-3.3-70B-Instruct)
-   * @returns Chat completion response
+   * @returns Promise containing chat completion response
+   *
+   * TODO:
+   * - Implement message validation
+   * - Add support for conversation history
+   * - Implement response filtering
+   * - Add support for system messages
+   * - Implement prompt optimization
+   * - Add response quality checks
    */
   async atomaChat(
     messages: { content: string; role: string }[],
@@ -32,17 +81,34 @@ class Atoma {
   }
 
   /**
-   * Initialize Atoma SDK with authentication
-   * @param bearerAuth - Bearer auth token for Atoma SDK
-   * @returns Initialized Atoma SDK instance
+   * Initializes the Atoma SDK with authentication.
+   * Creates and configures a new SDK instance.
+   *
+   * @param bearerAuth - Bearer authentication token
+   * @returns Configured AtomaSDK instance
+   *
+   * TODO:
+   * - Add SDK configuration validation
+   * - Implement SDK instance pooling
+   * - Add support for custom configurations
    */
   public static initializeAtomaSDK(bearerAuth: string): AtomaSDK {
     return new AtomaSDK({ bearerAuth });
   }
+
   /**
-   * Health check function that returns service status
+   * Performs a health check on the Atoma service.
+   * Verifies if the service is responsive and functioning correctly.
+   *
    * @param sdk - Initialized Atoma SDK instance
-   * @returns Boolean indicating if service is healthy
+   * @returns Promise<boolean> indicating if service is healthy
+   *
+   * TODO:
+   * - Add detailed health metrics
+   * - Implement health check caching
+   * - Add support for custom health checks
+   * - Implement health check alerts
+   * - Add performance monitoring
    */
   static async isAtomaHealthy(sdk: AtomaSDK): Promise<boolean> {
     try {