feat: Support ai/extract and ai/extract_structured endpoints (box/box-codegen#566) (#356)

Author: box-sdk-build

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "5b7aecf", "specHash": "b21666d", "version": "1.6.0" }
+{ "engineHash": "5ceb679", "specHash": "d9f90b8", "version": "1.6.0" }

docs/ai.md

@@ -1,10 +1,12 @@
 # AiManager
 
-- [Send AI question request](#send-ai-question-request)
-- [Send AI request to generate text](#send-ai-request-to-generate-text)
+- [Ask question](#ask-question)
+- [Generate text](#generate-text)
 - [Get AI agent default configuration](#get-ai-agent-default-configuration)
+- [Extract metadata (freeform)](#extract-metadata-freeform)
+- [Extract metadata (structured)](#extract-metadata-structured)
 
-## Send AI question request
+## Ask question
 
 Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context.
 
@@ -20,14 +22,14 @@ await client.ai.createAiAsk({
   mode: 'multiple_item_qa' as AiAskModeField,
   prompt: 'Which direction sun rises?',
   items: [
-    new AiAskItemsField({
+    new AiItemBase({
       id: fileToAsk1.id,
-      type: 'file' as AiAskItemsTypeField,
+      type: 'file' as AiItemBaseTypeField,
       content: 'Earth goes around the sun',
     }),
-    new AiAskItemsField({
+    new AiItemBase({
       id: fileToAsk2.id,
-      type: 'file' as AiAskItemsTypeField,
+      type: 'file' as AiItemBaseTypeField,
       content: 'Sun rises in the East in the morning',
     }),
   ],
@@ -47,9 +49,9 @@ This function returns a value of type `AiResponseFull`.
 
 A successful response including the answer from the LLM.
 
-## Send AI request to generate text
+## Generate text
 
-Sends an AI request to supported LLMs and returns an answer specifically focused on the creation of new text.
+Sends an AI request to supported Large Language Models (LLMs) and returns generated text based on the provided prompt.
 
 This operation is performed by calling function `createAiTextGen`.
 
@@ -124,9 +126,72 @@ await client.ai.getAiAgentDefaultConfig({
 
 ### Returns
 
-This function returns a value of type `AiAgentAskOrAiAgentTextGen`.
+This function returns a value of type `AiAgentAskOrAiAgentExtractOrAiAgentExtractStructuredOrAiAgentTextGen`.
 
 A successful response including the default agent configuration.
-This response can be one of the following two objects:
-AI agent for questions and AI agent for text generation. The response
-depends on the agent configuration requested in this endpoint.
+This response can be one of the following four objects:
+
+- AI agent for questions
+- AI agent for text generation
+- AI agent for freeform metadata extraction
+- AI agent for structured metadata extraction.
+  The response depends on the agent configuration requested in this endpoint.
+
+## Extract metadata (freeform)
+
+Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs.
+Freeform metadata extraction does not require any metadata template setup before sending the request.
+
+This operation is performed by calling function `createAiExtract`.
+
+See the endpoint docs at
+[API Reference](https://developer.box.com/reference/post-ai-extract/).
+
+<!-- sample post_ai_extract -->
+
+```ts
+await client.ai.createAiExtract({
+  prompt: 'firstName, lastName, location, yearOfBirth, company',
+  items: [new AiItemBase({ id: file.id })],
+} satisfies AiExtract);
+```
+
+### Arguments
+
+- requestBody `AiExtract`
+  - Request body of createAiExtract method
+- optionalsInput `CreateAiExtractOptionalsInput`
+  -
+
+### Returns
+
+This function returns a value of type `AiResponse`.
+
+A response including the answer from the LLM.
+
+## Extract metadata (structured)
+
+Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs.
+For this request, you need to use an already defined metadata template or a define a schema yourself.
+To learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates)
+or use the [metadata template API](g://metadata/templates/create).
+
+This operation is performed by calling function `createAiExtractStructured`.
+
+See the endpoint docs at
+[API Reference](https://developer.box.com/reference/post-ai-extract-structured/).
+
+_Currently we don't have an example for calling `createAiExtractStructured` in integration tests_
+
+### Arguments
+
+- requestBody `AiExtractStructured`
+  - Request body of createAiExtractStructured method
+- optionalsInput `CreateAiExtractStructuredOptionalsInput`
+  -
+
+### Returns
+
+This function returns a value of type `AiExtractResponse`.
+
+A successful response including the answer from the LLM.