feat: Support AI agent (#887)

codegen/codegen.tsx

@@ -188,6 +188,10 @@ import { generateManagerClasses } from './generate-manager-classes';
  {
  name: 'textGen',
  operationId: 'post_ai_text_gen',
+ },
+ {
+ name: 'getAiAgentDefaultConfig',
+ operationId: 'get_ai_agent_default',
  }
  ]
  }

docs/ai.md

@@ -6,16 +6,18 @@ AI allows to send an intelligence request to supported large language models and
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Send AI request](#send-ai-request)
-- [Send AI text generation request](#send-ai-text-generation-request)
+- [AI](#ai)
+ - [Send AI request](#send-ai-request)
+ - [Send AI text generation request](#send-ai-text-generation-request)
+ - [Get AI agent default configuration](#get-ai-agent-default-configuration)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 Send AI request
 ------------------------
 
 To send an AI request to the supported large language models, call the
-[`ai.ask(body, options?, callback?)`](http://opensource.box.com/box-node-sdk/jsdoc/AI.html#ask) method with the prompt and items. The `items` parameter is a list of items to be processed by the LLM, often files. The `prompt` provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. The `mode` specifies if this request is for a single or multiple items. If you select `single_item_qa` the items array can have one element only. Selecting `multiple_item_qa` allows you to provide up to 25 items.
+[`ai.ask(body, options?, callback?)`](http://opensource.box.com/box-node-sdk/jsdoc/AIManager.html#ask) method with the prompt and items. The `items` parameter is a list of items to be processed by the LLM, often files. The `prompt` provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. The `mode` specifies if this request is for a single or multiple items. If you select `single_item_qa` the items array can have one element only. Selecting `multiple_item_qa` allows you to provide up to 25 items.
 
 <!-- sample post_ai_ask -->
 ```js
@@ -47,7 +49,7 @@ Send AI text generation request
 ------------------------
 
 To send an AI text generation request to the supported large language models, call the
-[`ai.textGen(body, options?, callback?)`](http://opensource.box.com/box-node-sdk/jsdoc/AI.html#textGen) method with the prompt, items and dialogue history. The `dialogue_history` parameter is history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response. The `items` parameter is a list of items to be processed by the LLM, often files. The `prompt` provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.
+[`ai.textGen(body, options?, callback?)`](http://opensource.box.com/box-node-sdk/jsdoc/AIManager.html#textGen) method with the prompt, items and dialogue history. The `dialogue_history` parameter is history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response. The `items` parameter is a list of items to be processed by the LLM, often files. The `prompt` provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.
 
 <!-- sample post_ai_text_gen -->
 ```js
@@ -81,3 +83,37 @@ client.ai.textGen(
  } */
  });
 ```
+
+
+ Get AI agent default configuration
+------------------------
+
+To get an AI agent default configuration call the [ai.getAiAgentDefaultConfig(options?, callback?)](http://opensource.box.com/box-node-sdk/jsdoc/AIManager.html#getAiAgentDefaultConfig) method. The `mode` parameter filters the agent configuration to be returned. It can be either `ask` or `text_gen`. The `language` parameter specifies the ISO language code to return the agent config for. If the language is not supported, the default agent configuration is returned. The `model` parameter specifies the model for which the default agent configuration should be returned.
+
+<!-- sample get_ai_agent_default -->
+```js
+client.ai.getAiAgentDefaultConfig({
+ mode: 'ask',
+ language: 'en',
+ model:'openai__gpt_3_5_turbo'
+}).then(response => {
+ /* response -> {
+ "type": "ai_agent_ask",
+ "basic_text": {
+ "llm_endpoint_params": {
+ "type": "openai_params",
+ "frequency_penalty": 1.5,
+ "presence_penalty": 1.5,
+ "stop": "<|im_end|>",
+ "temperature": 0,
+ "top_p": 1
+ },
+ "model": "openai__gpt_3_5_turbo",
+ "num_tokens_for_completion": 8400,
+ "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
+ "system_message": "You are a helpful travel assistant specialized in budget travel"
+ },
+ ...
+ } */
+});
+```

src/managers/ai.generated.ts

@@ -18,13 +18,13 @@ class AIManager {
  * @param {schemas.AiAsk} body
  * @param {object} [options] Options for the request
  * @param {Function} [callback] Passed the result if successful, error otherwise
- * @returns {Promise<schemas.AiResponse>} A promise resolving to the result or rejecting with an error
+ * @returns {Promise<schemas.AiResponseFull>} A promise resolving to the result or rejecting with an error
  */
  ask(
  body: schemas.AiAsk,
  options?: {},
  callback?: Function
- ): Promise<schemas.AiResponse> {
+ ): Promise<schemas.AiResponseFull> {
  const { ...queryParams } = options,
  apiPath = urlPath('ai', 'ask'),
  params = {
@@ -63,5 +63,45 @@ class AIManager {
  callback
  );
  }
+ /**
+ * Get AI agent default configuration
+ *
+ * Get the AI agent default config
+ * @param {object} options Options for the request
+ * @param {"ask" | "text_gen"} options.mode The mode to filter the agent config to return.
+ * @param {string} [options.language] The ISO language code to return the agent config for. If the language is not supported the default agent config is returned.
+ * @param {string} [options.model] The model to return the default agent config for.
+ * @param {Function} [callback] Passed the result if successful, error otherwise
+ * @returns {Promise<schemas.AiAgentAsk | schemas.AiAgentTextGen>} A promise resolving to the result or rejecting with an error
+ */
+ getAiAgentDefaultConfig(
+ options: {
+ /**
+ * The mode to filter the agent config to return.
+ */
+ readonly mode: 'ask' | 'text_gen';
+ /**
+ * The ISO language code to return the agent config for.
+ * If the language is not supported the default agent config is returned.
+ */
+ readonly language?: string;
+ /**
+ * The model to return the default agent config for.
+ */
+ readonly model?: string;
+ },
+ callback?: Function
+ ): Promise<schemas.AiAgentAsk | schemas.AiAgentTextGen> {
+ const { ...queryParams } = options,
+ apiPath = urlPath('ai_agent_default'),
+ params = {
+ qs: queryParams,
+ };
+ return this.client.wrapWithDefaultHandler(this.client.get)(
+ apiPath,
+ params,
+ callback
+ );
+ }
 }
 export = AIManager;

src/schemas/ai-agent-ask.generated.ts

@@ -0,0 +1,17 @@
+import * as schemas from '.';
+/**
+ * AI agent for question requests
+ *
+ * The AI agent used to handle queries.
+ */
+export interface AiAgentAsk {
+ /**
+ * The type of AI agent used to handle queries.
+ * Example: ai_agent_ask
+ */
+ type: 'ai_agent_ask';
+ long_text?: schemas.AiAgentLongTextTool;
+ basic_text?: schemas.AiAgentBasicTextToolAsk;
+ long_text_multi?: schemas.AiAgentLongTextTool;
+ basic_text_multi?: schemas.AiAgentBasicTextToolAsk;
+}

src/schemas/ai-agent-basic-gen-tool.generated.ts

@@ -0,0 +1,14 @@
+import * as schemas from '.';
+/**
+ * AI agent basic text generation tool
+ *
+ * AI agent basic tool used to generate text.
+ */
+export interface AiAgentBasicGenTool extends schemas.AiAgentLongTextTool {
+ /**
+ * How the content should be included in a request to the LLM.
+ * When passing this parameter, you must include `{content}`.
+ * Example: ---{content}---
+ */
+ content_template?: string;
+}

src/schemas/ai-agent-basic-text-tool-ask.generated.ts

@@ -0,0 +1,34 @@
+import * as schemas from '.';
+/**
+ * AI agent basic text tool
+ *
+ * AI agent tool used to handle basic text.
+ */
+export interface AiAgentBasicTextToolAsk {
+ /**
+ * The model used for the AI Agent for basic text.
+ * Example: openai__gpt_3_5_turbo
+ */
+ model?: string;
+ /**
+ * System messages try to help the LLM "understand" its role and what it is supposed to do.
+ * Example: You are a helpful travel assistant specialized in budget travel
+ */
+ system_message?: string;
+ /**
+ * The prompt template contains contextual information of the request and the user prompt.
+ *
+ * When passing `prompt_template` parameters, you **must include** inputs for `{current_date}`, `{user_question}`, and `{content}`.
+ * Example: It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?
+ */
+ prompt_template?: string;
+ /**
+ * The number of tokens for completion.
+ * Example: 8400
+ */
+ num_tokens_for_completion?: number;
+ /**
+ * The parameters for the LLM endpoint specific to OpenAI / Google models.
+ */
+ llm_endpoint_params?: schemas.AiLlmEndpointParamsOpenAi | schemas.AiLlmEndpointParamsGoogle;
+}

src/schemas/ai-agent-basic-text-tool-text-gen.generated.ts

@@ -0,0 +1,36 @@
+import * as schemas from '.';
+/**
+ * AI agent basic text tool
+ *
+ * AI agent tool used to handle basic text.
+ */
+export interface AiAgentBasicTextToolTextGen {
+ /**
+ * The model to be used for the AI Agent for basic text.
+ * Example: openai__gpt_3_5_turbo
+ */
+ model?: string;
+ /**
+ * System messages try to help the LLM "understand" its role and what it is supposed to do.
+ * This parameter requires using `{current_date}`.
+ * Example: You are a helpful travel assistant specialized in budget travel
+ */
+ system_message?: string;
+ /**
+ * The prompt template contains contextual information of the request and the user prompt.
+ *
+ * When using the `prompt_template` parameter, you **must include** input for `{user_question}`.
+ * Inputs for `{current_date}` and`{content}` are optional, depending on the use.
+ * Example: It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?
+ */
+ prompt_template?: string;
+ /**
+ * The number of tokens for completion.
+ * Example: 8400
+ */
+ num_tokens_for_completion?: number;
+ /**
+ * The parameters for the LLM endpoint specific to OpenAI / Google models.
+ */
+ llm_endpoint_params?: schemas.AiLlmEndpointParamsOpenAi | schemas.AiLlmEndpointParamsGoogle;
+}

src/schemas/ai-agent-long-text-tool.generated.ts

@@ -0,0 +1,10 @@
+import * as schemas from '.';
+/**
+ * AI agent long text tool
+ *
+ * AI agent tool used to to handle longer text.
+ */
+export interface AiAgentLongTextTool
+ extends schemas.AiAgentBasicTextToolTextGen {
+ embeddings?: object;
+}

src/schemas/ai-agent-text-gen.generated.ts

@@ -0,0 +1,14 @@
+import * as schemas from '.';
+/**
+ * AI agent for text generation requests
+ *
+ * The AI agent used for generating text.
+ */
+export interface AiAgentTextGen {
+ /**
+ * The type of AI agent used for generating text.
+ * Example: ai_agent_text_gen
+ */
+ type: 'ai_agent_text_gen';
+ basic_gen?: schemas.AiAgentBasicGenTool;
+}

src/schemas/ai-ask.generated.ts

@@ -1,8 +1,8 @@
 import * as schemas from '.';
 /**
- * AI Ask Request
+ * AI ask request
  *
- * AI Ask request object
+ * AI ask request object
  */
 export interface AiAsk {
  /**
@@ -27,4 +27,14 @@ export interface AiAsk {
  type?: string;
  content?: string;
  }[];
+ /**
+ * The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response.
+ */
+ dialogue_history?: schemas.AiDialogueHistory[];
+ /**
+ * A flag to indicate whether citations should be returned.
+ * Example: true
+ */
+ include_citations?: boolean;
+ ai_agent?: schemas.AiAgentAsk;
 }

src/schemas/ai-citation.generated.ts

@@ -0,0 +1,28 @@
+import * as schemas from '.';
+/**
+ * The citation of the LLM's answer reference
+ *
+ * The citation of the LLM's answer reference.
+ */
+export interface AiCitation {
+ /**
+ * The specific content from where the answer was referenced.
+ * Example: Public APIs are key drivers of innovation and growth.
+ */
+ content?: string;
+ /**
+ * The id of the item.
+ * Example: 123
+ */
+ id?: string;
+ /**
+ * The type of the item.
+ * Example: file
+ */
+ type?: 'file';
+ /**
+ * The name of the item.
+ * Example: The importance of public APIs.pdf
+ */
+ name?: string;
+}

src/schemas/ai-dialogue-history.generated.ts

@@ -0,0 +1,23 @@
+import * as schemas from '.';
+/**
+ * Dialogue history
+ *
+ * A context object that can hold prior prompts and answers.
+ */
+export interface AiDialogueHistory {
+ /**
+ * The prompt previously provided by the client and answered by the LLM.
+ * Example: Make my email about public APIs sound more professional.
+ */
+ prompt?: string;
+ /**
+ * The answer previously provided by the LLM.
+ * Example: Here is the first draft of your professional email about public APIs.
+ */
+ answer?: string;
+ /**
+ * The ISO date formatted timestamp of when the previous answer to the prompt was created.
+ * Example: 2012-12-12T10:53:43-08:00
+ */
+ created_at?: string;
+}

src/schemas/ai-llm-endpoint-params-google.generated.ts

@@ -0,0 +1,32 @@
+import * as schemas from '.';
+/**
+ * AI LLM endpoint params Google
+ *
+ * AI LLM endpoint params Google object
+ */
+export interface AiLlmEndpointParamsGoogle {
+ /**
+ * The type of the AI LLM endpoint params object for Google.
+ * This parameter is **required**.
+ * Example: google_params
+ */
+ type: 'google_params';
+ /**
+ * The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied.
+ * Temperature controls the degree of randomness in token selection.
+ */
+ temperature?: number;
+ /**
+ * `Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable
+ * until the sum of their probabilities equals the `top-P` value.
+ * Example: 1
+ */
+ top_p?: number;
+ /**
+ * `Top-K` changes how the model selects tokens for output. A `top-K` of 1 means the next selected token is
+ * the most probable among all tokens in the model's vocabulary (also called greedy decoding),
+ * while a `top-K` of 3 means that the next token is selected from among the three most probable tokens by using temperature.
+ * Example: 1
+ */
+ top_k?: number;
+}