From ac2b719071915e2a8323e790bfe1e4922ec3cae4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Barbara=20Czy=C5=BC?= Date: Tue, 15 Oct 2024 10:12:06 +0200 Subject: [PATCH] DDOC-1152: add guides for AI model overrides (#610) * AI agents tutorials initial version * improvements * minor fixes * samples fix * add links * remove dialogue history * added links --- .spelling | 3 +- .../ai-agents/get-agent-default-config.md | 232 +++++++++++- content/guides/box-ai/ai-agents/index.md | 23 +- .../box-ai/ai-agents/overrides-tutorial.md | 357 ++++++++++++++++++ content/guides/box-ai/ask-questions.md | 6 +- .../box-ai/extract-metadata-structured.md | 4 +- content/guides/box-ai/extract-metadata.md | 8 +- content/guides/box-ai/generate-text.md | 5 +- 8 files changed, 609 insertions(+), 29 deletions(-) create mode 100644 content/guides/box-ai/ai-agents/overrides-tutorial.md diff --git a/.spelling b/.spelling index cb36efe50..91e9cd342 100644 --- a/.spelling +++ b/.spelling @@ -314,4 +314,5 @@ GPT-4 GPT-3 freeform pre-defined -stringified \ No newline at end of file +stringified +params \ No newline at end of file diff --git a/content/guides/box-ai/ai-agents/get-agent-default-config.md b/content/guides/box-ai/ai-agents/get-agent-default-config.md index 02d71d055..8e0d16696 100644 --- a/content/guides/box-ai/ai-agents/get-agent-default-config.md +++ b/content/guides/box-ai/ai-agents/get-agent-default-config.md @@ -1,5 +1,5 @@ --- -rank: 7 +rank: 2 related_endpoints: - get_ai_agent_default - post_ai_text_gen @@ -18,13 +18,7 @@ Box AI API is currently a beta feature offered subject to Boxโ€™s Main Beta Agre The `GET /2.0/ai_agent_default` endpoint allows you to fetch the default configuration for AI services. -Once you get the configuration details, you can override them using the `ai_agent` parameter available in the [`POST /2.0/ai/ask`][ask] and [`POST /2.0/ai/text_gen`][text-gen] requests. - -Override examples include: - -* Replacing the default LLM with a custom one based on your organization's needs. -* Tweaking the base prompt to allow a more customized user experience. -* Changing a parameter, such as `temperature`, to make the results more or less creative. +Once you get the configuration details you can override them using the [`ai_agent`][ai-agent-config] parameter. ## Send a request @@ -44,10 +38,222 @@ To make a call, you must pass the following parameters. Mandatory parameters are | Parameter| Description| Example| |--------|--------|-------| |`language`| The language code the agent configuration is returned for. If the language is not supported, the default configuration is returned. | `ja-JP`| -|**`mode`**|The mode used to filter the agent configuration. The value can be `ask` or `text_gen`. |`ask`| -|`model`|The model you want to get the configuration for. To make sure your chosen model is supported, see the [list of models][models].| `openai__gpt_3_5_turbo`| +|**`mode`**|The mode used to filter the agent configuration. The value can be `ask`, `text_gen`, `extract`, or `extract_structured` depending on the result you want to achieve. |`ask`| +|`model`|The model you want to get the configuration for. To make sure your chosen model is supported, see the [list of models][models].| `azure__openai__gpt_3_5_turbo_16k`| + +## Responses + +The responses to the call may vary depending on the `mode` parameter value you choose. + + + + + +When you set the `mode` parameter to `ask` the response will be as follows: + +```sh +{ + "type": "ai_agent_ask", + "basic_text": { + "model": "azure__openai__gpt_4o_mini", + "system_message": "", + "prompt_template": "prompt_template": "{user_question}Write it in an informal way.{content}" + }, + "num_tokens_for_completion": 6000, + "llm_endpoint_params": { + "temperature": 0, + "top_p": 1, + "frequency_penalty": 0, + "presence_penalty": 1.5, + "stop": "<|im_end|>", + "type": "openai_params" + } + }, + "long_text": { + "model": "azure__openai__gpt_4o_mini", + "system_message": "", + "prompt_template": "prompt_template": "{user_question}Write it in an informal way.{content}" + }, + "num_tokens_for_completion": 6000, + "llm_endpoint_params": { + "temperature": 0, + "top_p": 1, + "frequency_penalty": 0, + "presence_penalty": 1.5, + "stop": "<|im_end|>", + "type": "openai_params" + }, + "embeddings": { + "model": "azure__openai__text_embedding_ada_002", + "strategy": { + "id": "basic", + "num_tokens_per_chunk": 64 + } + } + }, + "basic_text_multi": { + "model": "azure__openai__gpt_4o_mini", + "system_message": "", + "prompt_template": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.", + "num_tokens_for_completion": 6000, + "llm_endpoint_params": { + "temperature": 0, + "top_p": 1, + "frequency_penalty": 0, + "presence_penalty": 1.5, + "stop": "<|im_end|>", + "type": "openai_params" + } + }, + "long_text_multi": { + "model": "azure__openai__gpt_4o_mini", + "system_message": "Role and Goal: You are an assistant designed to analyze and answer a question based on provided snippets from multiple documents, which can include business-oriented documents like docs, presentations, PDFs, etc. The assistant will respond concisely, using only the information from the provided documents.\n\nConstraints: The assistant should avoid engaging in chatty or extensive conversational interactions and focus on providing direct answers. It should also avoid making assumptions or inferences not supported by the provided document snippets.\n\nGuidelines: When answering, the assistant should consider the file's name and path to assess relevance to the question. In cases of conflicting information from multiple documents, it should list the different answers with citations. For summarization or comparison tasks, it should concisely answer with the key points. It should also consider the current date to be the date given.\n\nPersonalization: The assistant's tone should be formal and to-the-point, suitable for handling business-related documents and queries.\n", + "prompt_template": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.", + "num_tokens_for_completion": 6000, + "llm_endpoint_params": { + "temperature": 0, + "top_p": 1, + "frequency_penalty": 0, + "presence_penalty": 1.5, + "stop": "<|im_end|>", + "type": "openai_params" + }, + "embeddings": { + "model": "azure__openai__text_embedding_ada_002", + "strategy": { + "id": "basic", + "num_tokens_per_chunk": 64 + } + } + } +} +``` + + + + + +When you set the `mode` parameter to `text_gen` the response will be as follows: + +```sh +{ + "type": "ai_agent_text_gen", + "basic_gen": { + "model": "azure__openai__gpt_3_5_turbo_16k", + "system_message": "\nIf you need to know today's date to respond, it is {current_date}.\nThe user is working in a collaborative document creation editor called Box Notes.\nAssume that you are helping a business user create documents or to help the user revise existing text.\nYou can help the user in creating templates to be reused or update existing documents, you can respond with text that the user can use to place in the document that the user is editing.\nIf the user simply asks to \"improve\" the text, then simplify the language and remove jargon, unless the user specifies otherwise.\nDo not open with a preamble to the response, just respond.\n", + "prompt_template": "{user_question}", + "num_tokens_for_completion": 12000, + "llm_endpoint_params": { + "temperature": 0.1, + "top_p": 1, + "frequency_penalty": 0.75, + "presence_penalty": 0.75, + "stop": "<|im_end|>", + "type": "openai_params" + }, + "embeddings": { + "model": "azure__openai__text_embedding_ada_002", + "strategy": { + "id": "basic", + "num_tokens_per_chunk": 64 + } + }, + "content_template": "`````{content}`````" + } +} +``` + + + + + +When you set the `mode` parameter to `extract` the response will be as follows: + +```sh +{ + "type": "ai_agent_extract", + "basic_text": { + "model": "google__gemini_1_5_flash_001", + "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````", + "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````", + "num_tokens_for_completion": 4096, + "llm_endpoint_params": { + "temperature": 0, + "top_p": 1, + "top_k": null, + "type": "google_params" + } + }, + "long_text": { + "model": "google__gemini_1_5_flash_001", + "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````", + "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````", + "num_tokens_for_completion": 4096, + "llm_endpoint_params": { + "temperature": 0, + "top_p": 1, + "top_k": null, + "type": "google_params" + }, + "embeddings": { + "model": "azure__openai__text_embedding_ada_002", + "strategy": { + "id": "basic", + "num_tokens_per_chunk": 64 + } + } + } +} +``` + + + + + +When you set the `mode` parameter to `extract_structured` the response will be as follows: + +```sh +{ + "type": "ai_agent_extract_structured", + "basic_text": { + "model": "google__gemini_1_5_flash_001", + "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````", + "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````", + "num_tokens_for_completion": 4096, + "llm_endpoint_params": { + "temperature": 0, + "top_p": 1, + "top_k": null, + "type": "google_params" + } + }, + "long_text": { + "model": "google__gemini_1_5_flash_001", + "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````", + "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````", + "num_tokens_for_completion": 4096, + "llm_endpoint_params": { + "temperature": 0, + "top_p": 1, + "top_k": null, + "type": "google_params" + }, + "embeddings": { + "model": "google__textembedding_gecko_003", + "strategy": { + "id": "basic", + "num_tokens_per_chunk": 64 + } + } + } +} +``` + + + + [prereq]: g://box-ai/prerequisites -[ask]: e://post_ai_ask#param_ai_agent -[text-gen]: e://post_ai_text_gen#param_ai_agent -[models]: g://box-ai/supported-models \ No newline at end of file +[models]: g://box-ai/supported-models +[ai-agent-config]: g://box-ai/ai-agents/overrides-tutorial +[override-tutorials]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file diff --git a/content/guides/box-ai/ai-agents/index.md b/content/guides/box-ai/ai-agents/index.md index 56f5cc906..6ae9ec0c4 100644 --- a/content/guides/box-ai/ai-agents/index.md +++ b/content/guides/box-ai/ai-agents/index.md @@ -2,16 +2,29 @@ rank: 1 related_endpoints: - get_ai_agent_default + - post_ai_text_gen + - post_ai_ask + - post_ai_extract + - post_ai_extract_structured related_guides: - - box-ai/index + - box-ai/ai-agents/get-agent-default-config + - box-ai/ai-agents/overrides-tutorial --- -# AI agent configuration +# AI model overrides -You can use the `ai_agent` parameter available in the [`POST /2.0/ai/ask`][ask] and [`POST /2.0/ai/text_gen`][text-gen] requests to override the default agent configuration and introduce your own custom settings. +Box updates the default models across the endpoints on a regular basis to stay up to date with the most advanced options. -For details, see [AI agent default configuration][agent-default]. +If your implementation is based on Box AI, a new default model might alter the results in a way that could break or change a downstream process. Switching to a specific version may prevent encountering any issues. + +Selecting a specific model may also bring better results to your use case. This is why, you can switch to any model included in the [supported models][models] list. + +Apart from switching models, you can pass options to further customize the agents used in Box AI implementation and get the responses that suit your use case. + +To see specific use cases, check the [overrides tutorial][overrides]. [ask]: e://post_ai_ask#param_ai_agent [text-gen]: e://post_ai_text_gen#param_ai_agent -[agent-default]: g://box-ai/ai-agents/get-agent-default-config \ No newline at end of file +[agent-default]: g://box-ai/ai-agents/get-agent-default-config +[overrides]: g://box-ai/ai-agents/overrides-tutorial +[models]: g://box-ai/supported-models \ No newline at end of file diff --git a/content/guides/box-ai/ai-agents/overrides-tutorial.md b/content/guides/box-ai/ai-agents/overrides-tutorial.md new file mode 100644 index 000000000..e60ec7a1d --- /dev/null +++ b/content/guides/box-ai/ai-agents/overrides-tutorial.md @@ -0,0 +1,357 @@ +--- +rank: 4 +related_endpoints: + - get_ai_agent_default + - post_ai_text_gen + - post_ai_ask +related_guides: + - box-ai/prerequisites + - box-ai/ask-questions + - box-ai/generate-text +--- + +# Override AI model configuration + + +Box AI API is currently a beta feature offered subject to Boxโ€™s Main Beta Agreement, and the available capabilities may change. Box AI API is available to all Enterprise Plus customers. + + + +The `agent_ai` configuration allows you to override the default AI model configuration. It is available for the following endpoints: + +* [`POST ai/ask`][ask] +* [`POST ai/text_gen`][text-gen] +* [`POST ai/extract`][extract] +* [`POST ai/extract_structured`][extract-structured] + + + +Use the [`GET ai_agent_default`][agent] endpoint to fetch the default configuration. + + + +The override examples include: + +* Replacing the default AI model with a custom one based on your organization's needs. +* Tweaking the base `prompt` to allow a more customized user experience. +* Changing a parameter, such as `temperature`, to make the results more or less creative. + +## Sample configuration + +A sample configuration for `ai/ask` is as follows: + +```sh +{ + "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": "azure__openai__gpt_3_5_turbo_16k", + "num_tokens_for_completion": 8400, + "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", + "system_message": "You are a helpful travel assistant specialized in budget travel" + }, + "basic_text_multi": { + "llm_endpoint_params": { + "type": "openai_params", + "frequency_penalty": 1.5, + "presence_penalty": 1.5, + "stop": "<|im_end|>", + "temperature": 0, + "top_p": 1 + }, + "model": "azure__openai__gpt_3_5_turbo_16k", + "num_tokens_for_completion": 8400, + "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", + "system_message": "You are a helpful travel assistant specialized in budget travel" + }, + "long_text": { + "embeddings": { + "model": "openai__text_embedding_ada_002", + "strategy": { + "id": "basic", + "num_tokens_per_chunk": 64 + } + }, + "llm_endpoint_params": { + "type": "openai_params", + "frequency_penalty": 1.5, + "presence_penalty": 1.5, + "stop": "<|im_end|>", + "temperature": 0, + "top_p": 1 + }, + "model": "azure__openai__gpt_3_5_turbo_16k", + "num_tokens_for_completion": 8400, + "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", + "system_message": "You are a helpful travel assistant specialized in budget travel" + }, + "long_text_multi": { + "embeddings": { + "model": "openai__text_embedding_ada_002", + "strategy": { + "id": "basic", + "num_tokens_per_chunk": 64 + } + }, + "llm_endpoint_params": { + "type": "openai_params", + "frequency_penalty": 1.5, + "presence_penalty": 1.5, + "stop": "<|im_end|>", + "temperature": 0, + "top_p": 1 + }, + "model": "azure__openai__gpt_3_5_turbo_16k", + "num_tokens_for_completion": 8400, + "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", + "system_message": "You are a helpful travel assistant specialized in budget travel" + } +} +``` + +### Differences in parameter sets + +The set of parameters available for `ask`, `text_gen`, `extract`, `extract_structured` differs slightly, depending on the API call. + + * The agent configuration for the `ask` endpoint includes `basic_text`, `basic_text_multi`, `long_text` and `long_text_multi` parameters. This is because of the `mode` parameter you use to specify if the request is for a single item or multiple items. If you selected `multiple_item_qa` as the `mode`, you can also use `multi` parameters for overrides. + + * The agent configuration for `text_gen` includes the `basic_gen` parameter + that is used to generate text. + +### LLM endpoint params + +The `llm_endpoint_params` configuration options differ depending on the overall AI model being [Google][google-params] or [OpenAI][openai-params] based. + +For example, both `llm_endpoint_params` objects accept a `temperature` parameter, but the outcome differs depending on the model. + +For Google models, the [`temperature`][google-temp] is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection. + +For OpenAI models, [`temperature`][openai-temp] is the sampling temperature with values between 0 and 2. Higher values like 0.8 make the output more random, while lower values like 0.2 make it more focused and deterministic. When introducing your own configuration, use `temperature` or or `top_p` but not both. + +### System message + +The `system_message` parameter's aim is to help the LLM understand its role and what itโ€™s supposed to do. +For example, if your solution is processing travel itineraries, you can add a system message saying: + +```sh +You are a travel agent aid. You are going to help support staff process large amounts of schedules, tickets, etc. +``` + +This message is separate from the content you send in, but it can improve the results. + +### Number of tokens for completion + +The `num_tokens_for_completion` parameter represents the number of [tokens][openai-tokens] Box AI can return. This number can vary based on the model used. + +## Use case: Box AI Q&A + +This example shows how to use the `prompt_template` parameter to change the +query result. +The first step is to ask Box AI to summarize a document about Box AI for Documents. +The `mode` parameter is set to `single_item_qa` because only one document is supplied. + +```sh +curl -i -L POST "https://api.box.com/2.0/ai/ask" \ +-H "content-type: application/json" \ +-H "authorization: " \ +-d '{ + "mode": "single_item_qa", + "prompt": "Summarize this article about Box AI for Documents", + "items": [ + { + "type": "file", + "id": "123467890" + } + ] + }' +``` + +You will get a response similar to the following: + +```sh +{ + "answer": "Box AI for Documents is a tool that enhances document analysis by allowing users to summarize content, identify key points, and draft outlines directly from files in Box. It supports various file types, including text documents, spreadsheets, and presentation slides. Users can initiate interactions with Box AI through the web app, where they can select suggestions or type specific questions. Responses are generated in real time, and users have options to save or clear chat history. The document also provides guidelines for effective inquiries and troubleshooting tips for potential issues with using Box AI.", + "created_at": "2024-10-08T00:29:07.283-07:00", + "completion_reason": "done" +} +``` + +To further improve the result, you can use the `prompt_template` parameter to add some more instructions for Box AI. In this example, let's change the tone of the response. + +```sh +{ + "prompt": "Summarize this article about Box AI for Documents", + "mode": "single_item_qa", + "items": [ + { + "id": "123467890", + "type": "file" + } + ], + "ai_agent": { + "type": "ai_agent_ask", + "basic_text": { + "prompt_template": "prompt_template": "{user_question} Write the summary in an informal way.{content}" + }, + } + } +} +``` + +The response would be slightly less formal: + +```sh +{ + "answer": "Box AI for Documents is a tool that helps you analyze and gain insights from your documents in Box. You can use it to summarize content, identify key points, and draft outlines, making it easier to handle meeting notes, reports, and marketing materials. To get started, just open a file in the Box web app and click the Box AI button. It offers quick suggestions like summarizing the document or checking for next steps. Responses are generated in real time, and you can save them or clear chat history as needed. Just remember, Box AI only pulls info from the document you're viewing, so be specific with your questions!", + "created_at": "2024-10-08T00:38:01.767-07:00", + "completion_reason": "done" +} +``` + +## Use case: Generating text + +This example shows you how changing the AI model in the `ai_agent` options can influence the way the text is generated. + +First let's generate some text using the `POST ai/text_gen` endpoint. This endpoint is using the OpenAI 3.5 turbo model by default. + +```sh +curl -i -L POST "https://api.box.com/2.0/ai/text_gen" \ + -H "content-type: application/json" \ + -H "authorization: Bearer TOKEN" \ + -d '{ + "prompt": "Write a short post about Box AI for documents.Make it highlight the benefits of the solution. You can add some emoticons.", + "items": [ + { + "id": "123467890", + "type": "file" + } + ] + } +``` + +The response is as follows: + +```sh +{ + "answer": "๐ŸŒŸ Exciting News! ๐ŸŒŸ\n\nIntroducing Box AI for documents - your new best friend in creating smarter, more efficient content! ๐Ÿค–๐Ÿ’ก\n\n๐Ÿ”น Say goodbye to manual searching and organizing - Box AI does it all for you!\n๐Ÿ”น Enjoy lightning-fast document analysis and categorization.\n๐Ÿ”น Boost productivity with automated suggestions and smart recommendations.\n๐Ÿ”น Collaborate seamlessly with real-time insights and intelligent tagging.\n\nExperience the future of document creation with Box AI - making work easier, faster, and more fun! ๐Ÿš€๐Ÿ’ป #BoxAI #SmartDocuments", + "created_at": "2024-10-08T01:19:06.22-07:00", + "completion_reason": "done" +} +``` + +Let's change the model using the `ai_agent` configuration: + +```sh +curl -i -L POST "https://api.box.com/2.0/ai/text_gen" \ + -H "content-type: application/json" \ + -H "authorization: Bearer TOKEN" \ + -d '{ + "prompt": "Write a short post about Box AI for documents.Make it highlight the benefits of the solution. You can add some emoticons.", + "items": [ + { + "id": "123467890", + "type": "file" + } + ], + "ai_agent": { + "type": "ai_agent_text_gen", + "basic_gen": { + "model": "openai__gpt_4o_2024_05_13" + } + } + } + +``` + +After the model switch, the response is slightly different: + +```sh +{ + "answer": "๐Ÿš€ **Boost Your Productivity with Box AI for Documents!** ๐Ÿ“„โœจ\n\nSay goodbye to tedious document creation and editing! With Box AI, you can streamline your workflow and focus on what truly matters. Hereโ€™s why youโ€™ll love it:\n\n1. **Smart Suggestions** ๐Ÿค–: Get real-time recommendations to enhance your content.\n2. **Automated Formatting** ๐Ÿ“: Ensure consistency across all your documents effortlessly.\n3. **Collaboration Made Easy** ๐Ÿ‘ฅ: Work seamlessly with your team, no matter where they are.\n4. **Time-Saving Templates** โณ: Use pre-built templates to speed up document creation.\n5. **Enhanced Accuracy** โœ…: Reduce errors with intelligent proofreading.\n\nTransform the way you work with documents and experience a new level of efficiency with Box AI! ๐ŸŒŸ", + "created_at": "2024-10-08T01:28:36.777-07:00", + "completion_reason": "done" +} +``` + +As you can see the responses differ to some extent. Thanks to the model switch, you can optimize your interaction with Box AI and choose the most suitable model for your needs. + +## Use case: Metadata extraction + +Switching models can also give us different results for metadata extraction. +Let's use a sample contract to extract the metadata. In this example, the model used is Google Gemini. + +```sh +curl -i -L 'https://api.box.com/2.0/ai/extract' \ + -H 'content-type: application/json' \ + -H 'authorization: Bearer TOKEN' \ + -d '{ + "prompt": "Extract any data that would be good metadata to save for future contracts.", + "items": [ + { + "type": "file", + "id": "123456789" + } + ] + }' +``` + +The response is a set of metadata: + +```sh +{ + "answer": "{\"Buyer Legal Entity Name\": \"Acme Retail Corp.\", \"Supplier Legal Entity Name\": \"Acme Manufacturing Inc.\", \"Buyer Contact Person\": \"Jane Doe\", \"Supplier Contact Person\": \"Eva Smith\", \"Payment Term\": \"payment in full before pickup of goods\", \"Invoice Currency\": \"Euro\", \"Incoterm\": \"FCA Amsterdam\", \"Governing Law\": \"laws state jurisdiction in which supplier is located\", \"Effective Date\": \"March 27, 2024\", \"Buyer Signature Date\": \"March 28th, 2024\", \"Supplier Signature Date\": \"March 28th, 2024\"}", + "created_at": "2024-10-08T01:53:14.993-07:00", + "completion_reason": "done" +} +``` + +Let's change the model to the most recent OpenAI option: + +```sh +curl -i -L 'https://api.box.com/2.0/ai/extract' \ + -H 'content-type: application/json' \ + -H 'authorization: Bearer TOKEN' \ + -d '{ + "prompt": "Extract any data that would be good metadata to save for future contracts.", + "items": [ + { + "type": "file", + "id": "123456789" + } + ], + "ai_agent": { + "type": "ai_agent_extract", + "basic_text": { + "model": "openai__gpt_4o_2024_05_13" + } + } + }' +``` + +Using this model results in a response listing more metadata entries: + +```sh +{ + "answer": "{\"Effective Date\": \"March 27, 2024\", \"Supplier Legal Entity Name\": \"Acme Manufacturing Inc.\", \"Supplier Registered Office Address\": \"123 Main Street\", \"Supplier Contact Person(s)\": \"Eva Smith\", \"Buyer Legal Entity Name\": \"Acme Retail Corp.\", \"Buyer Registered Office Address\": \"456 Market Avenue\", \"Buyer Contact Person(s)\": \"Jane Doe\", \"Incoterm\": \"FCA Amsterdam\", \"Payment Term\": \"payment in full before pickup of goods\", \"Invoice Currency\": \"Euro\", \"Buyer Printed Name\": \"Jane Doe\", \"Buyer Date\": \"March 28th, 2024\", \"Buyer Title / Position\": \"CEO\", \"Seller Printed Name\": \"Eve Smith\", \"Seller Date\": \"March 28th, 2024\", \"Seller Title / Position\": \"Sales Manager\"}", + "created_at": "2024-10-08T01:54:28.099-07:00", + "completion_reason": "done" +} +``` + +[ask]: e://post_ai_ask#param_ai_agent +[text-gen]: e://post_ai_text_gen#param_ai_agent +[extract]: e://post_ai_extract#param_ai_agent +[extract-structured]: e://post_ai_extract_structured#param_ai_agent +[google-params]: r://ai-llm-endpoint-params-google +[openai-params]: r://ai-llm-endpoint-params-openai +[openai-tokens]: https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them +[agent]: e://get_ai_agent_default +[google-temp]: https://ai.google.dev/gemini-api/docs/models/generative-models#model-parameters +[openai-temp]: https://community.openai.com/t/temperature-top-p-and-top-k-for-chatbot-responses/295542 \ No newline at end of file diff --git a/content/guides/box-ai/ask-questions.md b/content/guides/box-ai/ask-questions.md index ae8ee286e..c76937962 100644 --- a/content/guides/box-ai/ask-questions.md +++ b/content/guides/box-ai/ask-questions.md @@ -6,6 +6,7 @@ related_guides: - box-ai/prerequisites - box-ai/generate-text - box-ai/ai-agents/get-agent-default-config + - box-ai/ai-agents/overrides-tutorial --- # Ask questions to Box AI @@ -52,9 +53,10 @@ Mandatory parameters are in **bold**. |**`items.id`** | The Box file ID you want to provide as input. | | `112233445566`| | **`items.type`** | The type of the provided input. Currently, it can be a single file or multiple files. | `file` | `file` | | `items.content` | The content of the item, often the text representation. | | `An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface...` | -|`ai_agent` | The AI agent used to override the default agent configuration. You can use this parameter replace the default LLM with a custom one using the [`model`][model-param] parameter for shorter and longer texts, tweak the base [`prompt`][prompt-param] to allow for a more customized user experience, or change an LLM parameter, such as `temperature`, to make the results more or less creative. Before you use the `ai_agent` parameter, you can get the default configuration using the [`GET 2.0/ai_agent_default`][agent] request.||| +|`ai_agent` | The AI agent used to override the default agent configuration. You can use this parameter replace the default LLM with a custom one using the [`model`][model-param] parameter for shorter and longer texts, tweak the base [`prompt`][prompt-param] to allow for a more customized user experience, or change an LLM parameter, such as `temperature`, to make the results more or less creative. Before you use the `ai_agent` parameter, you can get the default configuration using the [`GET 2.0/ai_agent_default`][agent] request. For specific use cases, see the [AI model overrides tutorial][overrides]. || [prereq]: g://box-ai/prerequisites [agent]: e://get_ai_agent_default [model-param]: r://ai_agent_ask#param_basic_text_model -[prompt-param]: e://ai_agent_ask#param_basic_text_prompt_template \ No newline at end of file +[prompt-param]: e://ai_agent_ask#param_basic_text_prompt_template +[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file diff --git a/content/guides/box-ai/extract-metadata-structured.md b/content/guides/box-ai/extract-metadata-structured.md index 514b71729..51f21b5c0 100644 --- a/content/guides/box-ai/extract-metadata-structured.md +++ b/content/guides/box-ai/extract-metadata-structured.md @@ -6,6 +6,7 @@ related_guides: - box-ai/prerequisites - box-ai/extract-metadata - box-ai/ai-agents/get-agent-default-config + - box-ai/ai-agents/overrides-tutorial --- # Extract metadata from file (structured) @@ -55,7 +56,7 @@ The `items` array can have exactly one element. | `fields.options` | A list of options for this field. This is most often used in combination with the `enum` and `multiSelect` field types. | `[{"key":"First Name"},{"key":"Last Name"}]` | | `fields.options.key` | A unique identifier for the field. | `First Name` | | `fields.prompt` | Additional context about the key (identifier) that may include how to find and format it. | `Name is the first and last name from the email address` | -| `ai_agent` | The AI agent used to override the default agent configuration. This parameter allows you to, for example, replace the default LLM with a custom one using the [`model`][model-param] parameter, tweak the base [`prompt`][prompt-param] to allow for a more customized user experience, or change an LLM parameter, such as `temperature`, to make the results more or less creative. Before using the `ai_agent` parameter, you can get the default configuration using the [`GET 2.0/ai_agent_default`][agent] request. | | +| `ai_agent` | The AI agent used to override the default agent configuration. This parameter allows you to, for example, replace the default LLM with a custom one using the [`model`][model-param] parameter, tweak the base [`prompt`][prompt-param] to allow for a more customized user experience, or change an LLM parameter, such as `temperature`, to make the results more or less creative. Before you use the `ai_agent` parameter, you can get the default configuration using the [`GET 2.0/ai_agent_default`][agent] request. For specific use cases, see the [AI model overrides tutorial][overrides]. | | ## Use case @@ -180,3 +181,4 @@ The response lists the fields included in the metadata template and their values [prompt-param]: r://ai_agent_text_gen#param_basic_gen_prompt_template [templates-console]: https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates [templates-api]: g://metadata/templates/create +[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file diff --git a/content/guides/box-ai/extract-metadata.md b/content/guides/box-ai/extract-metadata.md index 65ed52d59..680cf2d06 100644 --- a/content/guides/box-ai/extract-metadata.md +++ b/content/guides/box-ai/extract-metadata.md @@ -43,10 +43,7 @@ The `items` array can have exactly one element. |**`items.id`**|Box file ID of the document. The ID must reference an actual file with an extension. |`1233039227512`| |**`items.type`**|The type of the supplied input. | `file`| | `items.content` | The content of the item, often the text representation. | `This article is about Box AI`. | -| `dialogue_history.prompt` | The prompt previously provided by the client and answered by the Large Language Model (LLM). | `Make my email about public APIs sound more professional` | -| `dialogue_history.answer` | The answer previously provided by the LLM. | `Here is a draft of your professional email about public APIs.` | -| `dialogue_history.created_at` | The ISO date formatted timestamp of when the previous answer to the prompt was created. | `2012-12-12T10:53:43-08:00` | -|`ai_agent` | The AI agent used to override the default agent configuration. This parameter allows you to, for example, replace the default LLM with a custom one using the [`model`][model-param] parameter, tweak the base [`prompt`][prompt-param] to allow for a more customized user experience, or change an LLM parameter, such as `temperature`, to make the results more or less creative. Before using the `ai_agent` parameter, you can get the default configuration using the [`GET 2.0/ai_agent_default`][agent] request.| | +|`ai_agent` | The AI agent used to override the default agent configuration. This parameter allows you to, for example, replace the default LLM with a custom one using the [`model`][model-param] parameter, tweak the base [`prompt`][prompt-param] to allow for a more customized user experience, or change an LLM parameter, such as `temperature`, to make the results more or less creative. Before you use the `ai_agent` parameter, you can get the default configuration using the [`GET 2.0/ai_agent_default`][agent] request. For specific use cases, see the [AI model overrides tutorial][overrides].| | ## Use case @@ -155,4 +152,5 @@ In such a case, the response will be based on the keywords included in the query [prereq]: g://box-ai/prerequisites [agent]: e://get_ai_agent_default [model-param]: r://ai_agent_text_gen#param_basic_gen_model -[prompt-param]: r://ai_agent_text_gen#param_basic_gen_prompt_template \ No newline at end of file +[prompt-param]: r://ai_agent_text_gen#param_basic_gen_prompt_template +[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file diff --git a/content/guides/box-ai/generate-text.md b/content/guides/box-ai/generate-text.md index bf5645ca7..45bb1eaf0 100644 --- a/content/guides/box-ai/generate-text.md +++ b/content/guides/box-ai/generate-text.md @@ -48,9 +48,10 @@ To make a call, you must pass the following parameters. Mandatory parameters are | `dialogue_history.prompt` | The prompt previously provided by the client and answered by the Large Language Model (LLM). | `Make my email about public APIs sound more professional` | | `dialogue_history.answer` | The answer previously provided by the LLM. | `Here is a draft of your professional email about public APIs.` | | `dialogue_history.created_at` | The ISO date formatted timestamp of when the previous answer to the prompt was created. | `2012-12-12T10:53:43-08:00` | -|`ai_agent` | The AI agent used to override the default agent configuration. This parameter allows you to, for example, replace the default LLM with a custom one using the [`model`][model-param] parameter, tweak the base [`prompt`][prompt-param] to allow for a more customized user experience, or change an LLM parameter, such as `temperature`, to make the results more or less creative. Before using the `ai_agent` parameter, you can get the default configuration using the [`GET 2.0/ai_agent_default`][agent] request.| | +|`ai_agent` | The AI agent used to override the default agent configuration. This parameter allows you to, for example, replace the default LLM with a custom one using the [`model`][model-param] parameter, tweak the base [`prompt`][prompt-param] to allow for a more customized user experience, or change an LLM parameter, such as `temperature`, to make the results more or less creative. Before you use the `ai_agent` parameter, you can get the default configuration using the [`GET 2.0/ai_agent_default`][agent] request. For specific use cases, see the [AI model overrides tutorial][overrides]| | [prereq]: g://box-ai/prerequisites [agent]: e://get_ai_agent_default [model-param]: r://ai_agent_text_gen#param_basic_gen_model -[prompt-param]: r://ai_agent_text_gen#param_basic_gen_prompt_template \ No newline at end of file +[prompt-param]: r://ai_agent_text_gen#param_basic_gen_prompt_template +[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file