Merge pull request #12 from madschristensen99/main

Add documentation

Author: spacesailor24

packages/fss-agent/src/lib/agent.ts

@@ -1,10 +1,12 @@
+// Import the OpenAI class from the 'openai' package.
 import { OpenAI } from 'openai';
 import type {
   IntentMatcher,
   IntentMatcherResponse,
 } from '@lit-protocol/fss-signer';
 import type { FssTool } from '@lit-protocol/fss-tool';
 
+// Import helper functions for matching tools and parsing parameters based on intent.
 import { getToolForIntent } from './get-tool-for-intent';
 import { parseToolParametersFromIntent } from './parse-tool-parameters';
 
@@ -37,15 +39,17 @@ export class OpenAiIntentMatcher implements IntentMatcher {
       registeredTools
     );
 
+    // If a tool is matched, parse the parameters from the intent using `parseToolParametersFromIntent`.
     const params = matchedTool
       ? await parseToolParametersFromIntent(
           this.openai,
           this.model,
           intent,
           matchedTool
         )
-      : { foundParams: {}, missingParams: [] };
+      : { foundParams: {}, missingParams: [] }; // If no tool is matched, return empty parameters.
 
+    // Return the analysis, matched tool, and parameters.
     return { analysis, matchedTool, params };
   }
 }

packages/fss-agent/src/lib/get-tool-for-intent.ts

@@ -1,8 +1,23 @@
+// Import the OpenAI class from the 'openai' package.
 import { OpenAI } from 'openai';
+
 import type { FssTool } from '@lit-protocol/fss-tool';
 
+// Import a helper function to generate a prompt for tool matching.
 import { getToolMatchingPrompt } from './get-tool-matching-prompt';
 
+/**
+ * Matches a user's intent to an appropriate tool from the available tools on a specified Lit network.
+ * This function uses OpenAI's API to analyze the intent and recommend a tool.
+ *
+ * @param openai - An instance of the OpenAI client.
+ * @param openAiModel - The name of the OpenAI model to use for analysis.
+ * @param userIntent - The user's intent as a string (e.g., "I want to mint an NFT").
+ * @param litNetwork - The Lit network to use for filtering available tools.
+ * @returns A Promise that resolves to an object containing:
+ *   - analysis: The raw analysis result from OpenAI, parsed as a JSON object.
+ *   - matchedTool: The tool matched to the user's intent, or `null` if no match is found.
+ */
 export async function getToolForIntent(
   openai: OpenAI,
   openAiModel: string,
@@ -12,6 +27,7 @@ export async function getToolForIntent(
   analysis: any;
   matchedTool: FssTool | null;
 }> {
+
   const completion = await openai.chat.completions.create({
     model: openAiModel,
     messages: [
@@ -21,18 +37,22 @@ export async function getToolForIntent(
       },
       {
         role: 'user',
-        content: userIntent,
+        content: userIntent, // Provide the user's intent as input.
       },
     ],
-    response_format: { type: 'json_object' },
+    response_format: { type: 'json_object' }, // Request the response in JSON format.
   });
 
+  // Parse the analysis result from OpenAI's response.
   const analysis = JSON.parse(completion.choices[0].message.content || '{}');
+
+  // Find the matched tool based on the recommended CID from the analysis.
   const matchedTool = analysis.recommendedCID
     ? registeredTools.find(
         (tool) => tool.ipfsCid === analysis.recommendedCID
       ) || null
     : null;
 
+  // Return the analysis and the matched tool (or null if no match is found).
   return { analysis, matchedTool };
 }

packages/fss-agent/src/lib/get-tool-matching-prompt.ts

@@ -1,6 +1,15 @@
+// Import the FssTool type from the '@lit-protocol/fss-tool' package.
 import type { FssTool } from '@lit-protocol/fss-tool';
 
+/**
+ * Generates a prompt for OpenAI to analyze a user's intent and match it to an appropriate tool.
+ * The prompt includes descriptions of the available tools and instructions for OpenAI to follow.
+ *
+ * @param tools - An array of FssTool objects representing the available tools.
+ * @returns A string containing the generated prompt.
+ */
 export function getToolMatchingPrompt(tools: FssTool<any, any>[]): string {
+
   const toolDescriptions = tools
     .map(
       (tool) =>
@@ -11,7 +20,6 @@ export function getToolMatchingPrompt(tools: FssTool<any, any>[]): string {
   return `
         You are a web3 transaction analyzer.
         Given a user's intent and available tools, determine if there's an appropriate tool that matches exactly what the user wants to do.
-
         Available tools:
         ${toolDescriptions}
         Important:

packages/fss-agent/src/lib/parse-tool-parameters.ts

@@ -1,6 +1,24 @@
+// Import the OpenAI class from the 'openai' package.
 import { OpenAI } from 'openai';
+
+// Import the FssTool type from the '@lit-protocol/fss-tool' package.
 import type { FssTool } from '@lit-protocol/fss-tool';
 
+/**
+ * Parses and validates parameters from a user's intent for a given tool.
+ * This function uses OpenAI's API to extract parameter values and ensures they conform to the tool's validation rules.
+ *
+ * @template TParams - A generic type representing the tool's parameter structure.
+ * @template TPolicy - A generic type representing the tool's policy structure.
+ * @param openai - An instance of the OpenAI client.
+ * @param openAiModel - The name of the OpenAI model to use for parsing.
+ * @param intent - The user's intent as a string.
+ * @param tool - The tool for which parameters are being parsed.
+ * @returns A Promise that resolves to an object containing:
+ *   - foundParams: A partial object of the parsed parameters.
+ *   - missingParams: An array of parameter names that could not be parsed.
+ *   - validationErrors: An array of validation errors for invalid parameters.
+ */
 export async function parseToolParametersFromIntent<
   TParams extends Record<string, any>,
   TPolicy extends { type: string }
@@ -14,6 +32,7 @@ export async function parseToolParametersFromIntent<
   missingParams: Array<keyof TParams>;
   validationErrors: Array<{ param: string; error: string }>;
 }> {
+  // Use OpenAI's API to parse parameters from the user's intent.
   const completion = await openai.chat.completions.create({
     model: openAiModel,
     messages: [
@@ -65,12 +84,14 @@ export async function parseToolParametersFromIntent<
     response_format: { type: 'json_object' },
   });
 
+  // Parse the result from OpenAI's response.
   const result = JSON.parse(completion.choices[0].message.content || '{}');
 
-  // Validate found parameters
+  // Validate the found parameters using the tool's validation function.
   const foundParams = result.foundParams || {};
   const validationResult = tool.parameters.validate(foundParams);
 
+  // If validation passes, return the found and missing parameters.
   if (validationResult === true) {
     return {
       foundParams,
@@ -80,12 +101,12 @@ export async function parseToolParametersFromIntent<
     };
   }
 
-  // If validation fails, only treat invalid params as missing
+  // If validation fails, filter out invalid parameters and add them to missingParams.
   const invalidParams = new Set(validationResult.map((error) => error.param));
   const filteredParams: Partial<TParams> = {};
   const missingParams = new Set<keyof TParams>(result.missingParams || []);
 
-  // Keep only valid params in foundParams
+  // Keep only valid parameters in foundParams.
   Object.entries(foundParams).forEach(([param, value]) => {
     if (!invalidParams.has(param)) {
       filteredParams[param as keyof TParams] = value as TParams[keyof TParams];
@@ -94,6 +115,7 @@ export async function parseToolParametersFromIntent<
     }
   });
 
+  // Return the filtered parameters, missing parameters, and validation errors.
   return {
     foundParams: filteredParams,
     missingParams: Array.from(missingParams),

packages/fss-cli/src/lib/handlers/admin/add-delegatee.ts

@@ -1,29 +1,58 @@
+// Import the FssAdmin type from the '@lit-protocol/full-self-signing' package.
 import { type Admin as FssAdmin } from '@lit-protocol/full-self-signing';
 
+// Import the logger utility for logging messages.
 import { logger } from '../../utils/logger';
+
+// Import custom error types and utilities.
 import { FssCliError, FssCliErrorType } from '../../errors';
 import { promptDelegateeAddress } from '../../prompts/admin';
 
+/**
+ * Adds a delegatee to the Full Self-Signing (FSS) system.
+ * This function logs the progress and success of the operation.
+ *
+ * @param fssAdmin - An instance of the FssAdmin class.
+ * @param address - The address of the delegatee to add.
+ */
 const addDelegatee = async (fssAdmin: FssAdmin, address: string) => {
+  // Log a loading message to indicate the operation is in progress.
   logger.loading('Adding delegatee...');
+
+  // Add the delegatee to the FSS system.
   await fssAdmin.addDelegatee(address);
+
+  // Log a success message once the delegatee is added.
   logger.success(`Successfully added delegatee ${address}.`);
 };
 
+/**
+ * Handles the process of adding a delegatee to the FSS system.
+ * This function prompts the user for the delegatee's address, adds the delegatee,
+ * and handles any errors that occur during the process.
+ *
+ * @param fssAdmin - An instance of the FssAdmin class.
+ */
 export const handleAddDelegatee = async (fssAdmin: FssAdmin) => {
   try {
+    // Prompt the user for the delegatee's address.
     const address = await promptDelegateeAddress();
+
+    // Add the delegatee to the FSS system.
     await addDelegatee(fssAdmin, address);
   } catch (error) {
+    // Handle specific errors related to delegatee addition.
     if (error instanceof FssCliError) {
       if (
         error.type === FssCliErrorType.ADMIN_GET_DELEGATEE_ADDRESS_CANCELLED
       ) {
+        // Log an error message if the user cancels the operation.
         logger.error('Delegatee addition cancelled.');
         return;
       }
     }
 
+    // Re-throw any other errors to be handled by the caller.
     throw error;
   }
 };

packages/fss-cli/src/lib/handlers/admin/batch-add-delegatee.ts

@@ -1,27 +1,56 @@
+// Import the FssAdmin type from the '@lit-protocol/full-self-signing' package.
 import { type Admin as FssAdmin } from '@lit-protocol/full-self-signing';
 
+// Import the logger utility for logging messages.
 import { logger } from '../../utils/logger';
+
+// Import custom error types and utilities.
 import { FssCliError, FssCliErrorType } from '../../errors';
 import { promptSelectDelegateesToAdd } from '../../prompts/admin';
 
+/**
+ * Adds multiple delegatees to the Full Self-Signing (FSS) system in a batch operation.
+ * This function logs the progress and success of the operation.
+ *
+ * @param fssAdmin - An instance of the FssAdmin class.
+ * @param addresses - An array of delegatee addresses to add.
+ */
 const batchAddDelegatees = async (fssAdmin: FssAdmin, addresses: string[]) => {
+  // Log a loading message to indicate the operation is in progress.
   logger.loading('Adding delegatees...');
+
+  // Add the delegatees to the FSS system in a batch operation.
   await fssAdmin.batchAddDelegatees(addresses);
-  logger.success('Successfully added delegatees');
+
+  // Log a success message once the delegatees are added.
+  logger.success('Successfully added delegatees.');
 };
 
+/**
+ * Handles the process of adding multiple delegatees to the FSS system in a batch operation.
+ * This function prompts the user to select delegatee addresses, adds the delegatees,
+ * and handles any errors that occur during the process.
+ *
+ * @param fssAdmin - An instance of the FssAdmin class.
+ */
 export const handleBatchAddDelegatee = async (fssAdmin: FssAdmin) => {
   try {
+    // Prompt the user to select delegatee addresses.
     const addresses = await promptSelectDelegateesToAdd();
+
+    // Add the selected delegatees to the FSS system.
     await batchAddDelegatees(fssAdmin, addresses);
   } catch (error) {
+    // Handle specific errors related to batch delegatee addition.
     if (error instanceof FssCliError) {
       if (error.type === FssCliErrorType.ADMIN_BATCH_ADD_DELEGATEE_CANCELLED) {
+        // Log an error message if the user cancels the operation.
         logger.error('Batch delegatee addition cancelled.');
         return;
       }
     }
 
+    // Re-throw any other errors to be handled by the caller.
     throw error;
   }
 };

packages/fss-cli/src/lib/handlers/admin/batch-remove-delegatee.ts

@@ -1,34 +1,64 @@
+// Import the FssAdmin type from the '@lit-protocol/full-self-signing' package.
 import { type Admin as FssAdmin } from '@lit-protocol/full-self-signing';
 
+// Import the logger utility for logging messages.
 import { logger } from '../../utils/logger';
+
+// Import custom error types and utilities.
 import { FssCliError, FssCliErrorType } from '../../errors';
 import { promptSelectDelegateesToRemove } from '../../prompts/admin';
 
+/**
+ * Removes multiple delegatees from the Full Self-Signing (FSS) system in a batch operation.
+ * This function logs the progress and success of the operation.
+ *
+ * @param fssAdmin - An instance of the FssAdmin class.
+ * @param addresses - An array of delegatee addresses to remove.
+ */
 const batchRemoveDelegatees = async (
   fssAdmin: FssAdmin,
   addresses: string[]
 ) => {
+  // Log a loading message to indicate the operation is in progress.
   logger.loading('Removing delegatees...');
+
+  // Remove the delegatees from the FSS system in a batch operation.
   await fssAdmin.batchRemoveDelegatees(addresses);
-  logger.success('Successfully removed delegatees');
+
+  // Log a success message once the delegatees are removed.
+  logger.success('Successfully removed delegatees.');
 };
 
+/**
+ * Handles the process of removing multiple delegatees from the FSS system in a batch operation.
+ * This function prompts the user to select delegatee addresses, removes the delegatees,
+ * and handles any errors that occur during the process.
+ *
+ * @param fssAdmin - An instance of the FssAdmin class.
+ */
 export const handleBatchRemoveDelegatee = async (fssAdmin: FssAdmin) => {
   try {
-    const addresses = await promptSelectDelegateesToRemove(
-      await fssAdmin.getDelegatees()
-    );
+    // Retrieve the current list of delegatees from the FSS system.
+    const delegatees = await fssAdmin.getDelegatees();
+
+    // Prompt the user to select delegatee addresses to remove.
+    const addresses = await promptSelectDelegateesToRemove(delegatees);
+
+    // Remove the selected delegatees from the FSS system.
     await batchRemoveDelegatees(fssAdmin, addresses);
   } catch (error) {
+    // Handle specific errors related to batch delegatee removal.
     if (error instanceof FssCliError) {
       if (
         error.type === FssCliErrorType.ADMIN_BATCH_REMOVE_DELEGATEE_CANCELLED
       ) {
+        // Log an error message if the user cancels the operation.
         logger.error('Batch delegatee removal cancelled.');
         return;
       }
     }
 
+    // Re-throw any other errors to be handled by the caller.
     throw error;
   }
 };