feat: Support AI Extract endpoints

Author: Hawra2020

.eslintrc.yml

@@ -246,9 +246,6 @@ rules:
         - error
         - last
     space-before-blocks: error
-    space-before-function-paren:
-        - error
-        - never
     space-infix-ops: error
     space-unary-ops:
         - error

.prettierrc

@@ -0,0 +1,6 @@
+module.exports = {
+	semi: true,
+	singleQuote: true,
+	bracketSpacing: true,
+	trailingComma: 'all',
+};

.prettierrc.js

@@ -78,3 +78,71 @@ EXAMPLES
 ```
 
 _See code: [src/commands/ai/text-gen.js](https://github.com/box/boxcli/blob/v4.0.1/src/commands/ai/text-gen.js)_
+
+## `box ai:extract`
+
+Sends an AI request to supported LLMs and returns metadata in form of key-value pairs.
+
+```
+USAGE
+  $ box ai:extract --prompt <value> --items <value>... --ai-agent <value> [-t <value>] [--as-user <value>] [--no-color] [--json |
+    --csv] [-s | --save-to-file-path <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q]
+
+FLAGS
+  -h, --help                       Show CLI help
+  -q, --quiet                      Suppress any non-error output to stderr
+  -s, --save                       Save report to default reports folder on disk
+  -t, --token=<value>              Provide a token to perform this call
+  -v, --verbose                    Show verbose output, which can be helpful for debugging
+  -y, --yes                        Automatically respond yes to all confirmation prompts
+      --as-user=<value>            Provide an ID for a user
+      --bulk-file-path=<value>     File path to bulk .csv or .json objects
+      --csv                        Output formatted CSV
+      --fields=<value>             Comma separated list of fields to show
+      --items=<value>...           (required) The items for the AI request
+      --json                       Output formatted JSON
+      --no-color                   Turn off colors for logging
+      --prompt=<value>             (required) The prompt for the AI request
+      --ai-agent=<value>           The AI agent to used for extraction
+      --save-to-file-path=<value>  Override default file path to save report
+
+DESCRIPTION
+  Sends an AI request to supported LLMs and returns metadata in form of key-value pairs.
+
+EXAMPLES
+  $ box ai:extract --prompt "firstName, lastName, location, yearOfBirth, company" --items "id=12345,type=file" --ai-agent \'{"type":"ai_agent_extract","basicText":{"llmEndpointParams":{"type":"openai_params","frequencyPenalty": 1.5,"presencePenalty": 1.5,"stop": "<|im_end|>","temperature": 0,"topP": 1},"model": "azure__openai__gpt_4o_mini","numTokensForCompletion": 8400,"promptTemplate": "It is, consider these travel options and answer the.","systemMessage": "You are a helpful travel assistant specialized in budget travel"},"longText":{"embeddings":{ "model": "azure__openai__text_embedding_ada_002","strategy":{"id": "basic","numTokensPerChunk": 64}},"llmEndpointParams":{"type":"openai_params","frequencyPenalty": 1.5,"presencePenalty": 1.5,"stop": "<|im_end|>","temperature": 0,"topP": 1},"model":"azure__openai__gpt_4o_mini","numTokensForCompletion":8400,"promptTemplate":"It is , consider these travel options and answer the.","systemMessage":"You are a helpful travel assistant specialized in budget travel"}}\'
+```
+
+## `box ai:extract-structured`
+
+Sends an AI request to supported LLMs and returns metadata in form of key-value pairs.
+
+```
+USAGE
+  $ box ai:extract-structured --items <value> --fields <value>... --metadata-template <value> --ai-agent <value> [-t <value>] [--as-user <value>] [--no-color] [--json |
+    --csv] [-s | --save-to-file-path <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q]
+
+FLAGS
+  -h, --help                       Show CLI help
+  -q, --quiet                      Suppress any non-error output to stderr
+  -s, --save                       Save report to default reports folder on disk
+  -t, --token=<value>              Provide a token to perform this call
+  -v, --verbose                    Show verbose output, which can be helpful for debugging
+  -y, --yes                        Automatically respond yes to all confirmation prompts
+      --as-user=<value>            Provide an ID for a user
+      --bulk-file-path=<value>     File path to bulk .csv or .json objects
+      --csv                        Output formatted CSV
+      --fields=<value>             Comma separated list of fields to show
+      --items=<value>...           (required) The items for the AI request
+      --json                       Output formatted JSON
+      --no-color                   Turn off colors for logging
+      --prompt=<value>             (required) The prompt for the AI request
+      --ai-agent=<value>           The AI agent to be used for structured extraction
+      --save-to-file-path=<value>  Override default file path to save report
+
+DESCRIPTION
+  Sends an AI request to supported LLMs and returns metadata in form of key-value pairs.
+
+EXAMPLES
+  $ box ai:extract-structured --items="id=12345,type=file" --fields "key=firstName,type=string,description=Person first name,prompt=What is the first name?,displayName=First name" --fields "key=lastName,type=string,description=Person last name,prompt=What is the last name?,displayName=Last name" --ai-agent \'{"type":"ai_agent_extract_structured","basicText":{"llmEndpointParams":{"type":"openai_params","frequencyPenalty": 1.5,"presencePenalty": 1.5,"stop": "<|im_end|>","temperature": 0,"topP": 1},"model": "azure__openai__gpt_4o_mini","numTokensForCompletion": 8400,"promptTemplate": "It is, consider these travel options and answer the.","systemMessage": "You are a helpful travel assistant specialized in budget travel"},"longText":{"embeddings":{ "model": "azure__openai__text_embedding_ada_002","strategy":{"id": "basic","numTokensPerChunk": 64}},"llmEndpointParams":{"type":"openai_params","frequencyPenalty": 1.5,"presencePenalty": 1.5,"stop": "<|im_end|>","temperature": 0,"topP": 1},"model":"azure__openai__gpt_4o_mini","numTokensForCompletion":8400,"promptTemplate":"It is , consider these travel options and answer the.","systemMessage":"You are a helpful travel assistant specialized in budget travel"}}\'
+```

docs/ai.md

@@ -30,7 +30,7 @@
 		"@oclif/plugin-version": "^2.2.16",
 		"archiver": "^3.0.0",
 		"box-node-sdk": "^3.7.0",
-		"box-typescript-sdk-gen": "^1.11.0",
+		"box-typescript-sdk-gen": "^1.15.1",
 		"chalk": "^2.4.1",
 		"cli-progress": "^2.1.0",
 		"csv": "^6.3.3",
@@ -50,7 +50,6 @@
 		"p-event": "^2.3.1"
 	},
 	"devDependencies": {
-		"@oclif/prettier-config": "^0.2.1",
 		"@oclif/test": "^3.2.15",
 		"@typescript-eslint/eslint-plugin": "^8.17.0",
 		"babel-eslint": "^10.1.0",

package-lock.json

@@ -118,6 +118,32 @@ function getBooleanFlagValue(value) {
 	);
 }
 
+/**
+ * Removes all the undefined values from the object
+ *
+ * @param {Object} obj The object to format for display
+ * @returns {Object} The formatted object output
+ */
+function removeUndefinedValues(obj) {
+	if (typeof obj !== 'object' || obj === null) {
+		return obj;
+	}
+
+	if (Array.isArray(obj)) {
+		return obj.map((item) => removeUndefinedValues(item));
+	}
+
+	Object.keys(obj).forEach((key) => {
+		if (obj[key] === undefined) {
+			delete obj[key];
+		} else {
+			obj[key] = removeUndefinedValues(obj[key]);
+		}
+	});
+
+	return obj;
+}
+
 /**
  * Add or subtract a given offset from a date
  *
@@ -157,7 +183,7 @@ function offsetDate(date, timeLength, timeUnit) {
 function formatKey(key) {
 	// Converting camel case to snake case and then to title case
 	return key
-		.replace(/[A-Z]/gu, letter => `_${letter.toLowerCase()}`)
+		.replace(/[A-Z]/gu, (letter) => `_${letter.toLowerCase()}`)
 		.split('_')
 		.map((s) => KEY_MAPPINGS[s] || _.capitalize(s))
 		.join(' ');
@@ -433,7 +459,9 @@ class BoxCommand extends Command {
 	 * @private
 	 */
 	_setFlagsForBulkInput(bulkData) {
-		const bulkDataFlags = bulkData.filter((o) => o.type === 'flag' && !_.isNil(o.value)).map((o) => o.fieldKey);
+		const bulkDataFlags = bulkData
+			.filter((o) => o.type === 'flag' && !_.isNil(o.value))
+			.map((o) => o.fieldKey);
 		Object.keys(this.flags)
 			.filter((flag) => flag !== 'bulk-file-path') // Remove the bulk file path flag so we don't recurse!
 			.filter((flag) => !bulkDataFlags.includes(flag))
@@ -810,7 +838,6 @@ class BoxCommand extends Command {
 				tokenCache
 			);
 			DEBUG.init('Initialized client from environment config');
-
 		} else {
 			// No environments set up yet!
 			throw new BoxCLIError(
@@ -824,8 +851,12 @@ class BoxCommand extends Command {
 		// Using the as-user flag should have precedence over the environment setting
 		if (this.flags['as-user']) {
 			client.asUser(this.flags['as-user']);
-			DEBUG.init('Impersonating user ID %s using the ID provided via the --as-user flag', this.flags['as-user']);
-		} else if (!this.flags.token && environment.useDefaultAsUser) { // We don't want to use any environment settings if a token is passed in the command
+			DEBUG.init(
+				'Impersonating user ID %s using the ID provided via the --as-user flag',
+				this.flags['as-user']
+			);
+		} else if (!this.flags.token && environment.useDefaultAsUser) {
+			// We don't want to use any environment settings if a token is passed in the command
 			client.asUser(environment.defaultAsUserId);
 			DEBUG.init(
 				'Impersonating default user ID %s using environment configuration',
@@ -879,21 +910,26 @@ class BoxCommand extends Command {
 			}
 
 			const { enterpriseID } = configObj;
-			const tokenCache = environment.cacheTokens === false
-				? null
-				: new CLITokenCache(environmentsObj.default);
-			let ccgConfig = new BoxTSSDK.CcgConfig(ccgUser ? {
-				clientId,
-				clientSecret,
-				userId: ccgUser,
-				tokenStorage: tokenCache,
-			} : {
-				clientId,
-				clientSecret,
-				enterpriseId: enterpriseID,
-				tokenStorage: tokenCache,
-			});
-			let ccgAuth = new BoxTSSDK.BoxCcgAuth({config: ccgConfig});
+			const tokenCache =
+				environment.cacheTokens === false
+					? null
+					: new CLITokenCache(environmentsObj.default);
+			let ccgConfig = new BoxTSSDK.CcgConfig(
+				ccgUser
+					? {
+							clientId,
+							clientSecret,
+							userId: ccgUser,
+							tokenStorage: tokenCache,
+					  }
+					: {
+							clientId,
+							clientSecret,
+							enterpriseId: enterpriseID,
+							tokenStorage: tokenCache,
+					  }
+			);
+			let ccgAuth = new BoxTSSDK.BoxCcgAuth({ config: ccgConfig });
 			client = new BoxTSSDK.BoxClient({
 				auth: ccgAuth,
 			});
@@ -918,7 +954,7 @@ class BoxCommand extends Command {
 				const oauthAuth = new BoxTSSDK.BoxOAuth({
 					config: oauthConfig,
 				});
-				client = new BoxTSSDK.BoxClient({auth: oauthAuth});
+				client = new BoxTSSDK.BoxClient({ auth: oauthAuth });
 				client = this._configureTsSdk(client, SDK_CONFIG);
 			} catch (err) {
 				throw new BoxCLIError(
@@ -969,8 +1005,8 @@ class BoxCommand extends Command {
 				enterpriseId: environment.enterpriseId,
 				tokenStorage: tokenCache,
 			});
-			let jwtAuth = new BoxTSSDK.BoxJwtAuth({config: jwtConfig});
-			client = new BoxTSSDK.BoxClient({auth: jwtAuth});
+			let jwtAuth = new BoxTSSDK.BoxJwtAuth({ config: jwtConfig });
+			client = new BoxTSSDK.BoxClient({ auth: jwtAuth });
 
 			DEBUG.init('Initialized client from environment config');
 			if (environment.useDefaultAsUser) {
@@ -1083,7 +1119,9 @@ class BoxCommand extends Command {
 			this.settings.enableAnalyticsClient &&
 			this.settings.analyticsClient.name
 		) {
-			additionalHeaders['X-Box-UA'] = `${DEFAULT_ANALYTICS_CLIENT_NAME} ${this.settings.analyticsClient.name}`;
+			additionalHeaders[
+				'X-Box-UA'
+			] = `${DEFAULT_ANALYTICS_CLIENT_NAME} ${this.settings.analyticsClient.name}`;
 		} else {
 			additionalHeaders['X-Box-UA'] = DEFAULT_ANALYTICS_CLIENT_NAME;
 		}
@@ -1128,6 +1166,9 @@ class BoxCommand extends Command {
 		let logFunc;
 		let stringifiedOutput;
 
+		// remove all the undefined values from the object
+		formattedOutputData = removeUndefinedValues(formattedOutputData);
+
 		if (outputFormat === 'json') {
 			stringifiedOutput = stringifyStream(formattedOutputData, null, 4);
 
@@ -1141,21 +1182,21 @@ class BoxCommand extends Command {
 				},
 			});
 
-			writeFunc = async(savePath) => {
+			writeFunc = async (savePath) => {
 				await pipeline(
 					stringifiedOutput,
 					appendNewLineTransform,
 					fs.createWriteStream(savePath, { encoding: 'utf8' })
 				);
 			};
 
-			logFunc = async() => {
+			logFunc = async () => {
 				await this.logStream(stringifiedOutput);
 			};
 		} else {
 			stringifiedOutput = await this._stringifyOutput(formattedOutputData);
 
-			writeFunc = async(savePath) => {
+			writeFunc = async (savePath) => {
 				await utils.writeFileAsync(savePath, stringifiedOutput + os.EOL, {
 					encoding: 'utf8',
 				});
@@ -1471,7 +1512,11 @@ class BoxCommand extends Command {
 	 * @returns {void}
 	 */
 	async catch(err) {
-		if (err instanceof BoxTsErrors.BoxApiError && err.responseInfo && err.responseInfo.body) {
+		if (
+			err instanceof BoxTsErrors.BoxApiError &&
+			err.responseInfo &&
+			err.responseInfo.body
+		) {
 			const responseInfo = err.responseInfo;
 			let errorMessage = `Unexpected API Response [${responseInfo.body.status} ${responseInfo.body.message} | ${responseInfo.body.request_id}] ${responseInfo.body.code} - ${responseInfo.body.message}`;
 			err = new BoxCLIError(errorMessage, err);