diff --git a/content/guides/box-ai/ai-agents/ai-agent-overrides.md b/content/guides/box-ai/ai-agents/ai-agent-overrides.md new file mode 100644 index 000000000..049e74d9e --- /dev/null +++ b/content/guides/box-ai/ai-agents/ai-agent-overrides.md @@ -0,0 +1,163 @@ +--- +rank: 4 +related_endpoints: + - get_ai_agent_default + - post_ai_text_gen + - post_ai_ask +related_guides: + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/default-agent-overrides +--- + +# Override AI model configuration + + +Endpoints related to metadata extraction are 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 `ai_agent` 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 complete 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], [OpenAI][openai-params] or [AWS][aws-params] based. + +For example, both `llm_endpoint_params` objects accept a `temperature` parameter, but the outcome differs depending on the model. + +For Google and AWS 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. + +[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 +[aws-params]: r://ai-llm-endpoint-params-aws \ No newline at end of file diff --git a/content/guides/box-ai/ai-agents/ai-agent-versioning.md b/content/guides/box-ai/ai-agents/ai-agent-versioning.md index 5e0e8b30e..35b6e75a3 100644 --- a/content/guides/box-ai/ai-agents/ai-agent-versioning.md +++ b/content/guides/box-ai/ai-agents/ai-agent-versioning.md @@ -5,11 +5,11 @@ related_endpoints: - post_ai_text_gen - post_ai_ask related_guides: - - box-ai/prerequisites - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured --- # AI agent configuration versioning @@ -209,4 +209,4 @@ To make sure your configurations are not affected in a negative way, you can use ``` [default-config]: g://box-ai/ai-agents/get-agent-default-config -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ 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 9c256c855..3fb92dad5 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 @@ -5,11 +5,11 @@ related_endpoints: - post_ai_text_gen - post_ai_ask related_guides: - - box-ai/prerequisites - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured --- # Get default AI agent configuration @@ -254,7 +254,7 @@ When you set the `mode` parameter to `extract_structured` the response will be a -[prereq]: g://box-ai/prerequisites +[prereq]: g://box-ai/ai-tutorials/prerequisites [models]: g://box-ai/ai-models -[ai-agent-config]: g://box-ai/ai-agents/overrides-tutorial -[override-tutorials]: g://box-ai/ai-agents/overrides-tutorial +[ai-agent-config]: g://box-ai/ai-agents/ai-agent-overrides +[override-tutorials]: g://box-ai/ai-agents/ai-agent-overrides diff --git a/content/guides/box-ai/ai-agents/index.md b/content/guides/box-ai/ai-agents/index.md index d10b8e79c..44ec95944 100644 --- a/content/guides/box-ai/ai-agents/index.md +++ b/content/guides/box-ai/ai-agents/index.md @@ -8,7 +8,7 @@ related_endpoints: - post_ai_extract_structured related_guides: - box-ai/ai-agents/get-agent-default-config - - box-ai/ai-agents/overrides-tutorial + - box-ai/ai-agents/ai-agent-overrides --- # AI model overrides @@ -30,5 +30,5 @@ 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 -[overrides]: g://box-ai/ai-agents/overrides-tutorial +[overrides]: g://box-ai/ai-agents/ai-agent-overrides [models]: g://box-ai/ai-models \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/aws-claude-3-5-sonnet-model-card.md b/content/guides/box-ai/ai-models/aws-claude-3-5-sonnet-model-card.md index 14f569c2e..cb1156b95 100644 --- a/content/guides/box-ai/ai-models/aws-claude-3-5-sonnet-model-card.md +++ b/content/guides/box-ai/ai-models/aws-claude-3-5-sonnet-model-card.md @@ -1,10 +1,10 @@ --- rank: 14 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # AWS Claude 3.5 Sonnet @@ -33,4 +33,4 @@ related_guides: For additional information, see [official AWS Claude 3.5 Sonnet documentation][aws-claude]. [aws-claude]: https://aws.amazon.com/bedrock/claude/ -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/aws-claude-3-haiku-model-card.md b/content/guides/box-ai/ai-models/aws-claude-3-haiku-model-card.md index 14f264107..9e47ff3e6 100644 --- a/content/guides/box-ai/ai-models/aws-claude-3-haiku-model-card.md +++ b/content/guides/box-ai/ai-models/aws-claude-3-haiku-model-card.md @@ -1,10 +1,10 @@ --- rank: 15 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # AWS Claude 3 Haiku @@ -33,4 +33,4 @@ related_guides: For additional information, see [official AWS Claude 3 Haiku documentation][aws-claude]. [aws-claude]: https://aws.amazon.com/bedrock/claude/ -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/aws-claude-3-sonnet-model-card.md b/content/guides/box-ai/ai-models/aws-claude-3-sonnet-model-card.md index b08ba9ad7..2248cca68 100644 --- a/content/guides/box-ai/ai-models/aws-claude-3-sonnet-model-card.md +++ b/content/guides/box-ai/ai-models/aws-claude-3-sonnet-model-card.md @@ -1,10 +1,10 @@ --- rank: 16 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # AWS Claude 3 Sonnet @@ -31,4 +31,4 @@ related_guides: For additional information, see [official AWS Claude 3 Sonnet documentation][aws-claude]. [aws-claude]: https://aws.amazon.com/bedrock/claude/ -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/aws-titan-text-lite-model-card.md b/content/guides/box-ai/ai-models/aws-titan-text-lite-model-card.md index 54f0ec4aa..9e0f7e16f 100644 --- a/content/guides/box-ai/ai-models/aws-titan-text-lite-model-card.md +++ b/content/guides/box-ai/ai-models/aws-titan-text-lite-model-card.md @@ -1,10 +1,10 @@ --- rank: 17 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # AWS Titan Text Lite @@ -32,4 +32,4 @@ although the model itself is lightweight. For additional information, see [official AWS Titan documentation][aws-titan]. [aws-titan]: https://aws.amazon.com/bedrock/titan/ -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/azure-openai-gpt-4o-2024-05-13-model-card.md b/content/guides/box-ai/ai-models/azure-openai-gpt-4o-2024-05-13-model-card.md index 05094e6b6..b6f564486 100644 --- a/content/guides/box-ai/ai-models/azure-openai-gpt-4o-2024-05-13-model-card.md +++ b/content/guides/box-ai/ai-models/azure-openai-gpt-4o-2024-05-13-model-card.md @@ -1,10 +1,10 @@ --- rank: 3 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # Azure OpenAI GPT-4o-2024-05-13 @@ -31,4 +31,4 @@ related_guides: For additional information, see [official Azure OpenAI GPT-4o-2024-05-13 documentation][azure-ai-mini-4o-model]. [azure-ai-mini-4o-model]: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/azure-openai-gpt-4o-mini-model-card.md b/content/guides/box-ai/ai-models/azure-openai-gpt-4o-mini-model-card.md index bb3700f3b..2235b0a7c 100644 --- a/content/guides/box-ai/ai-models/azure-openai-gpt-4o-mini-model-card.md +++ b/content/guides/box-ai/ai-models/azure-openai-gpt-4o-mini-model-card.md @@ -1,10 +1,10 @@ --- rank: 4 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # Azure OpenAI GPT-4o Mini @@ -48,4 +48,4 @@ Box AI API uses this model to cover the following use cases: For additional information, see [official Azure OpenAI GPT-4o Mini documentation][azure-ai-mini-4o-model]. [azure-ai-mini-4o-model]: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/azure-text-embedding-ada-002-model-card.md b/content/guides/box-ai/ai-models/azure-text-embedding-ada-002-model-card.md index 4dd7dd269..24a8eae2a 100644 --- a/content/guides/box-ai/ai-models/azure-text-embedding-ada-002-model-card.md +++ b/content/guides/box-ai/ai-models/azure-text-embedding-ada-002-model-card.md @@ -1,10 +1,10 @@ --- rank: 5 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # Azure text-embedding-ada-002 @@ -31,4 +31,4 @@ related_guides: For additional information, see [official Azure Embeddings models documentation][azure-ai-embeddings]. [azure-ai-embeddings]: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embeddings -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/google-gemini-1-5-flash-001-model-card.md b/content/guides/box-ai/ai-models/google-gemini-1-5-flash-001-model-card.md index 65af2e7d4..e0d0d2ae1 100644 --- a/content/guides/box-ai/ai-models/google-gemini-1-5-flash-001-model-card.md +++ b/content/guides/box-ai/ai-models/google-gemini-1-5-flash-001-model-card.md @@ -1,10 +1,10 @@ --- rank: 6 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- @@ -32,4 +32,4 @@ related_guides: For additional information, see [official Google Gemini 1.5 Flash documentation][vertex-ai-gemini-models]. [vertex-ai-gemini-models]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/google-gemini-1-5-pro-001-model-card.md b/content/guides/box-ai/ai-models/google-gemini-1-5-pro-001-model-card.md index 5bebb9f38..8513b46f8 100644 --- a/content/guides/box-ai/ai-models/google-gemini-1-5-pro-001-model-card.md +++ b/content/guides/box-ai/ai-models/google-gemini-1-5-pro-001-model-card.md @@ -1,10 +1,10 @@ --- rank: 7 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- @@ -32,4 +32,4 @@ related_guides: For additional information, see [official Google Gemini 1.5 Pro documentation][vertex-ai-gemini-models]. [vertex-ai-gemini-models]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/google-text-bison-32-model-card.md b/content/guides/box-ai/ai-models/google-text-bison-32-model-card.md index 5bc8e4318..e4fee01fc 100644 --- a/content/guides/box-ai/ai-models/google-text-bison-32-model-card.md +++ b/content/guides/box-ai/ai-models/google-text-bison-32-model-card.md @@ -1,10 +1,10 @@ --- rank: 8 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- @@ -32,4 +32,4 @@ related_guides: For additional information, see [official Google Text Bison documentation][vertex-text-models]. [vertex-text-models]: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/google-text-bison-model-card.md b/content/guides/box-ai/ai-models/google-text-bison-model-card.md index 7592260ab..f502a6208 100644 --- a/content/guides/box-ai/ai-models/google-text-bison-model-card.md +++ b/content/guides/box-ai/ai-models/google-text-bison-model-card.md @@ -1,10 +1,10 @@ --- rank: 9 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- @@ -32,4 +32,4 @@ related_guides: For additional information, see [official Google Text Bison documentation][vertex-text-models]. [vertex-text-models]: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/google-text-unicorn-model-card.md b/content/guides/box-ai/ai-models/google-text-unicorn-model-card.md index c0dcadb3d..7d79df744 100644 --- a/content/guides/box-ai/ai-models/google-text-unicorn-model-card.md +++ b/content/guides/box-ai/ai-models/google-text-unicorn-model-card.md @@ -1,10 +1,10 @@ --- rank: 10 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- @@ -32,4 +32,4 @@ related_guides: For additional information, see [official Google Text Unicorn documentation][vertex-text-models]. [vertex-text-models]: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/google-textembedding-gecko-002-model-card.md b/content/guides/box-ai/ai-models/google-textembedding-gecko-002-model-card.md index 2af337631..ad294f198 100644 --- a/content/guides/box-ai/ai-models/google-textembedding-gecko-002-model-card.md +++ b/content/guides/box-ai/ai-models/google-textembedding-gecko-002-model-card.md @@ -1,10 +1,10 @@ --- rank: 12 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # Google textembedding-gecko@002 @@ -31,4 +31,4 @@ Text embedding models convert textual data into numerical vectors that can be pr For additional information, see [official Google textembedding models documentation][vertex-ai-model]. [vertex-ai-model]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#models -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/google-textembedding-gecko-003-model-card.md b/content/guides/box-ai/ai-models/google-textembedding-gecko-003-model-card.md index 3009bcf07..3a39a366b 100644 --- a/content/guides/box-ai/ai-models/google-textembedding-gecko-003-model-card.md +++ b/content/guides/box-ai/ai-models/google-textembedding-gecko-003-model-card.md @@ -1,10 +1,10 @@ --- rank: 13 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # Google textembedding-gecko@003 @@ -31,4 +31,4 @@ Text embedding models convert textual data into numerical vectors that can be pr For additional information, see [official Google textembedding models documentation][vertex-ai-model]. [vertex-ai-model]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#models -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/google-textembedding-gecko-model-card.md b/content/guides/box-ai/ai-models/google-textembedding-gecko-model-card.md index 8226c022b..bea5f745c 100644 --- a/content/guides/box-ai/ai-models/google-textembedding-gecko-model-card.md +++ b/content/guides/box-ai/ai-models/google-textembedding-gecko-model-card.md @@ -1,10 +1,10 @@ --- rank: 11 related_guides: - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata - - box-ai/extract-metadata-structured + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured - box-ai/ai-agents/get-agent-default-config --- # Google textembedding-gecko @@ -31,4 +31,4 @@ Text embedding models convert textual data into numerical vectors that can be pr For additional information, see [official Google textembedding models documentation][vertex-ai-model]. [vertex-ai-model]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#models -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-models/index.md b/content/guides/box-ai/ai-models/index.md index 4eb2558d9..e85cbc07e 100644 --- a/content/guides/box-ai/ai-models/index.md +++ b/content/guides/box-ai/ai-models/index.md @@ -1,9 +1,10 @@ --- rank: 1 related_guides: - - box-ai/ask-questions - - box-ai/generate-text + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text - box-ai/ai-agents/get-agent-default-config + - box-ai/ai-tutorials/default-agent-overrides alias_paths: - guides/box-ai/supported-models --- diff --git a/content/guides/box-ai/ai-tutorials/ask-questions.md b/content/guides/box-ai/ai-tutorials/ask-questions.md new file mode 100644 index 000000000..f6ef3f601 --- /dev/null +++ b/content/guides/box-ai/ai-tutorials/ask-questions.md @@ -0,0 +1,181 @@ +--- +rank: 2 +related_endpoints: + - post_ai_ask +related_guides: + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/default-agent-overrides + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured +--- + +# Ask questions to Box AI + + +Box AI API is available to all Enterprise Plus customers. + + + +Box AI API allows you to +ask a question about a supplied file or +a set of files, and get a response based on +the content. +For example, while viewing a document in Box, +you can ask Box AI to summarize the content. + +## Before you start + +Make sure you followed the steps listed in [prerequisites for using Box AI][prereq] to create a custom app and authenticate. + +## Send a request + +To send a request containing your question, +use the `POST /2.0/ai/ask` endpoint and +provide the mandatory parameters. + + + +### Parameters + +To make a call, you need to pass the following parameters. +Mandatory parameters are in **bold**. + +| Parameter |Description | Available values | Example | +| ------------ | ------ | ----------- | --- | +| **`mode`** | The type of request. It can be a question about a single file or a set of files. For a single file, Box AI API supports up to 1MB of text representation. If the file size exceeds 1MB, the first 1MB of text representation will be processed. If you want to list multiple files, the limit is 25 files. If you set `mode` to `single_item_qa`, the `items` array can list only one element.| `single_item_qa`, `multiple_item_qa` | `single_item_qa` | +| **`prompt`** | The question about your document or content. The prompt's length cannot exceed 10000 characters. | | `What is this document about?` | +| `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` | +|`include_citations`| Specifies if the citations should be returned in the answer.| `true`, `false`| `true`| +|**`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. Usually it is 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. For specific use cases, see the [AI model overrides tutorial][overrides]. || + +## Use cases + +## Ask questions about an item + +This example shows how to ask a question about one or more items using the `POST ask/ai` API. When using this endpoint, remember to specify the `mode` parameter depending on the number of items you want to supply. + +```sh +curl -i -L POST "https://api.box.com/2.0/ai/ask" \ + -H "content-type: application/json" \ + -H "authorization: Bearer " \ + -d '{ + "mode": "single_item_qa", + "items": [ + { + "id": "12345678", + "type": "file" + } + ], + "prompt": "List the guidelines on creating questions in Box AI for Documents" +}' +``` + +The response will be as follows: + +```sh +{ + "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview.\n2. If questions fall outside the scope of the document, Box AI will inform you that it cannot answer.\n3. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n4. Aim to stay within the scope of the document.\n5. Focus on text-based responses only.", + "created_at": "2024-11-04T02:30:09.557-08:00", + "completion_reason": "done" +} +``` + +## Ask questions with `content` parameter + +If you use the `content` parameter as the source of input for Box AI, it will use it as the primary source. + +```sh +curl -i -L POST "https://api.box.com/2.0/ai/ask" \ + -H "content-type: application/json" \ + -H "authorization: Bearer " \ + -d '{ + "mode": "single_item_qa", + "items": [ + { + "id": "12345678", + "type": "file", + "content": "This is a document about Box AI For documents. It consists of the functionality summary and guidelines on how to work with Box AI. Additionally, it provides a set of best practices for creating questions." + } + ], + "prompt": "List the guidelines on creating questions in Box AI for Documents" +}' +``` + +The response to this request is based on the `content` parameter instead of the file's content: + +```sh +{ + "answer": "The document does not provide specific guidelines on working with questions in Box AI for Documents. It only mentions that it includes a set of best practices for creating questions, but the details of those guidelines are not included in the text provided. If you have more information or another document, I can help further!", + "created_at": "2024-11-04T02:31:51.125-08:00", + "completion_reason": "done" +} +``` + +## Ask questions with `citations` parameter + +Setting the `citations` parameter to `true` causes the response to include excerpts from source file or files Box AI used to compile the answer. + +```sh +curl -i -L POST "https://api.box.com/2.0/ai/ask" \ + -H "content-type: application/json" \ + -H "authorization: Bearer " \ + -d '{ + "mode": "multiple_item_qa", + "include_citations": true, + "items": [ + { + "id": "12345678", + "type": "file" + } + ], + "prompt": "List the guidelines on working with responses in Box AI for Documents" +}' +``` + +The resulting answer includes the source file and direct content citations. + +```sh +{ + "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview, and cannot answer questions outside its scope.\n2. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n3. Examples of better phrasing include asking for a numbered list of key points instead of just \"list key points,\" and requesting a succinct outline of important points rather than a general inquiry about the document's purpose.\n4. Stay within the scope of the document and focus on text-based responses only.", + "created_at": "2024-11-04T02:35:00.578-08:00", + "completion_reason": "done", + "citations": [ + { + "type": "file", + "id": "12345678", + "name": "Box AI for Documents.docx", + "content": "Guidelines for Box AI questions\nBox AI pulls information only from the document you loaded in preview." + }, + { + "type": "file", + "id": "12345678", + "name": "Box AI for Documents.docx", + "content": "If you ask any questions outside of the scope of the document, Box AI informs you that it cannot answer the question with the information provided." + }, + { + "type": "file", + "id": "12345678", + "name": "Box AI for Documents.docx", + "content": "As you ask Box AI to analyze your document, consider these suggestions:\n· Be as specific as possible." + }, + { + "type": "file", + "id": "12345678", + "name": "Box AI for Documents.docx", + "content": "Box AI for Documents\n\nWhen viewing a document in Box, you can ask Box AI to summarize document content, search key points, and write outline drafts based on your document files." + } + ] +} +``` + +[prereq]: g://box-ai/ai-tutorials/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 +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-agents/overrides-tutorial.md b/content/guides/box-ai/ai-tutorials/default-agent-overrides.md similarity index 59% rename from content/guides/box-ai/ai-agents/overrides-tutorial.md rename to content/guides/box-ai/ai-tutorials/default-agent-overrides.md index b210ac554..acd846056 100644 --- a/content/guides/box-ai/ai-agents/overrides-tutorial.md +++ b/content/guides/box-ai/ai-tutorials/default-agent-overrides.md @@ -5,9 +5,12 @@ related_endpoints: - post_ai_text_gen - post_ai_ask related_guides: - - box-ai/prerequisites - - box-ai/ask-questions - - box-ai/generate-text + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured + - box-ai/ai-agents/ai-agent-overrides --- # Override AI model configuration @@ -16,140 +19,12 @@ related_guides: Endpoints related to metadata extraction are 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: +## Before you start -* [`POST ai/ask`][ask] -* [`POST ai/text_gen`][text-gen] -* [`POST ai/extract`][extract] -* [`POST ai/extract_structured`][extract-structured] +Make sure you followed the steps listed in [prerequisites for using Box AI][prereq] to create a custom app and authenticate. +To get more context, read about [agent overrides][agent-overrides]. - - -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], [OpenAI][openai-params] or [AWS][aws-params] based. - -For example, both `llm_endpoint_params` objects accept a `temperature` parameter, but the outcome differs depending on the model. - -For Google and AWS 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 +## Override prompt This example shows how to use the `prompt_template` parameter to change the query result. @@ -214,7 +89,7 @@ The response would be slightly less formal: } ``` -## Use case: Generating text +## Override AI model (text generation) This example shows you how changing the AI model in the `ai_agent` options can influence the way the text is generated. @@ -281,7 +156,7 @@ After the model switch, the response is slightly different: 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 +## Override AI model (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. @@ -344,14 +219,5 @@ Using this model results in a response listing more metadata entries: } ``` -[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 -[aws-params]: r://ai-llm-endpoint-params-aws \ No newline at end of file +[agent-overrides]: g://box-ai/ai-agents/ai-agent-overrides +[prereq]: g://box-ai/ai-tutorials/prerequisites \ No newline at end of file diff --git a/content/guides/box-ai/extract-metadata-structured.md b/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md similarity index 94% rename from content/guides/box-ai/extract-metadata-structured.md rename to content/guides/box-ai/ai-tutorials/extract-metadata-structured.md index 66a3d05cb..16ac7b833 100644 --- a/content/guides/box-ai/extract-metadata-structured.md +++ b/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md @@ -3,10 +3,11 @@ rank: 9 related_endpoints: - post-ai-extract related_guides: - - box-ai/prerequisites - - box-ai/extract-metadata - - box-ai/ai-agents/get-agent-default-config - - box-ai/ai-agents/overrides-tutorial + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/default-agent-overrides + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/extract-metadata --- # Extract metadata from file (structured) @@ -21,15 +22,15 @@ and get the result in the form of key-value pairs. As input, you can either create a structure using the `fields` parameter, or use an already defined metadata template. To learn more about creating templates, see [Creating metadata templates in the Admin Console][templates-console] or use the [metadata template API][templates-api]. +## Before you start + +Make sure you followed the steps listed in [prerequisites for using Box AI][prereq] to create a custom app and authenticate. + ## Send a request To send a request, use the `POST /2.0/ai/extract_structured` endpoint. -Make sure you have generated the developer token -to authorize your app. See [prerequisites for using Box AI][prereq] -for details. - ### Parameters @@ -58,15 +59,16 @@ The `items` array can have exactly one element. | `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 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 +## Use cases -Let's assume you want to extract the vendor name, invoice number, and a few more details from the following sample invoice: +This example shows you how to extract metadata from a sample invoice in a structured way. +Let's assume you want to extract the vendor name, invoice number, and a few more details. -![sample invoice](./images/sample-invoice.png) +![sample invoice](../images/sample-invoice.png) ### Create the request -To get the response from Box AI, call `POST /2.0/ai/extract` endpoint with the following parameters: +To get the response from Box AI, call `POST /2.0/ai/extract_structured` endpoint with the following parameters: - `items.type` and `items.id` to specify the file to extract the data from. - `fields` to specify the data that you want to extract from the given file. @@ -78,7 +80,7 @@ You can use either `fields` or `metadata_template` to specify your structure, bu -### Using `fields` parameter +### Use `fields` parameter The `fields` parameter allows you to specify the data you want to extract. Each `fields` object has a subset of parameters you can use to add more information about the searched data. For example, you can add the field type, description, or even a prompt with some additional context. @@ -140,7 +142,7 @@ The response lists the specified fields and their values: } ``` -### Using metadata template +### Use metadata template If you prefer to use a metadata template, you can provide its `template_key`, `type`, and `scope`. @@ -175,10 +177,10 @@ The response lists the fields included in the metadata template and their values } ``` -[prereq]: g://box-ai/prerequisites +[prereq]: g://box-ai/ai-tutorials/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 [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 +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/extract-metadata.md b/content/guides/box-ai/ai-tutorials/extract-metadata.md similarity index 79% rename from content/guides/box-ai/extract-metadata.md rename to content/guides/box-ai/ai-tutorials/extract-metadata.md index 14d19cddd..99951780a 100644 --- a/content/guides/box-ai/extract-metadata.md +++ b/content/guides/box-ai/ai-tutorials/extract-metadata.md @@ -3,8 +3,11 @@ rank: 8 related_endpoints: - post-ai-extract-structured related_guides: - - box-ai/extract-metadata-structured - - box-ai/prerequisites + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/default-agent-overrides + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/extract-metadata-structured --- # Extract metadata from file (freeform) @@ -17,15 +20,15 @@ Endpoints related to metadata extraction are currently a beta feature offered su Box AI API allows you to query a document and extract metadata based on a provided prompt. **Freeform** means that the prompt can include a stringified version of formats such as JSON or XML, or even plain text. +## Before you start + +Make sure you followed the steps listed in [prerequisites for using Box AI][prereq] to create a custom app and authenticate. + ## Send a request To send a request, use the `POST /2.0/ai/extract` endpoint. -Make sure you have generated the developer token -to authorize your app. See [prerequisites for using Box AI][prereq] -for details. - ### Parameters @@ -45,11 +48,9 @@ The `items` array can have exactly one element. | `items.content` | The content of the item, often the text representation. | `This article is about Box AI`. | |`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 - -Let's assume you want to extract the vendor name, invoice number, and a few more details from the following sample invoice: +## Use cases -![sample invoice](./images/sample-invoice.png) +This example shows you how to extract metadata from a sample invoice. ### Create the request @@ -62,9 +63,38 @@ To get the response from Box AI, call `POST /2.0/ai/extract` endpoint with the f Depending on the use case and the level of detail, you can construct various prompts. -#### Using keywords +#### Use plain text + +Because this endpoint allows freeform prompts, you can use plain text to get the information. + +```bash +curl --location 'https://api.box.com/2.0/ai/extract' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' \ +--data '{ + "prompt": "find the document type (invoice or po), vendor, total, and po number", + "items": [ + { + "type": "file", + "id": "1443721424754" + } + ] +}' +``` + +In such a case, the response will be based on the keywords included in the text: + +```bash +{ + "answer": "{\"Document Type\": \"Invoice\", \"Vendor\": \"Quasar Innovations\", \"Total\": \"$1,050\", \"PO Number\": \"003\"}", + "created_at": "2024-05-31T10:30:51.223-07:00", + "completion_reason": "done" +} +``` + +#### Use specific terms -The prompt can include a list of keywords that you expect to find in an invoice: +If you don't want to write the entire sentence, the prompt can consist of terms that you expect to find in an invoice: ```bash curl --location 'https://api.box.com/2.0/ai/extract' \ @@ -81,7 +111,7 @@ The prompt can include a list of keywords that you expect to find in an invoice: }' ``` -Using this approach results in a list of keywords provided in the request and their values: +Using this approach results in a list of terms provided in the request and their values: ```bash { @@ -91,9 +121,9 @@ Using this approach results in a list of keywords provided in the request and th } ``` -#### Using key-value pairs +#### Use key-value pairs -The prompt can be a list of key-value pairs that helps Box AI to come up with the metadata structure: +The prompt can also be a list of key-value pairs that helps Box AI to come up with the metadata structure. This approach requires listing the key-value pairs within a `fields` array. ```bash curl --location 'https://api.box.com/2.0/ai/extract' \ @@ -110,7 +140,7 @@ curl --location 'https://api.box.com/2.0/ai/extract' \ }' ``` -The response includes the fields present in the file, along with their values: +The response includes the `fields` present in the file, along with their values: ```bash { @@ -120,37 +150,8 @@ The response includes the fields present in the file, along with their values: } ``` -#### Using plain text - -You can also use plain text: - -```bash -curl --location 'https://api.box.com/2.0/ai/extract' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer ' \ ---data '{ - "prompt": "find the document type (invoice or po), vendor, total, and po number", - "items": [ - { - "type": "file", - "id": "1443721424754" - } - ] -}' -``` - -In such a case, the response will be based on the keywords included in the query: - -```bash -{ - "answer": "{\"Document Type\": \"Invoice\", \"Vendor\": \"Quasar Innovations\", \"Total\": \"$1,050\", \"PO Number\": \"003\"}", - "created_at": "2024-05-31T10:30:51.223-07:00", - "completion_reason": "done" -} -``` - -[prereq]: g://box-ai/prerequisites +[prereq]: g://box-ai/ai-tutorials/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 -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-tutorials/generate-text.md b/content/guides/box-ai/ai-tutorials/generate-text.md new file mode 100644 index 000000000..bea297861 --- /dev/null +++ b/content/guides/box-ai/ai-tutorials/generate-text.md @@ -0,0 +1,88 @@ +--- +rank: 3 +related_endpoints: + - post_ai_text_gen +related_guides: + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/default-agent-overrides + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured +--- +# Generate text with Box AI + + +Box AI API is available to all Enterprise Plus customers. + + + +You can use Box AI to generate text +based on provided content. + For example, you can ask Box AI to + generate a template based + on the content you read or create in Box Notes. + Then you can embed the generated text + directly into your document. + +## Before you start + +Make sure you followed the steps listed in [prerequisites for using Box AI][prereq] to create a custom app and authenticate. + +## Send a request + +To send a request, use the +`POST /2.0/ai/text_gen` endpoint. + + + +### Parameters + +To make a call, you must pass the following parameters. Mandatory parameters are in **bold**. + +**Note**: The `items` array can have exactly one element. + +| Parameter| Description| Example| +|--------|--------|-------| +|**`prompt`**| The request for Box AI to generate or refine the text. The prompt's length cannot exceed 10000 characters.|Create a meeting agenda for a weekly sales meeting.| +|**`items.id`**|Box file ID of the document. |`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 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 cases + +Generate text based on the provided file content and a prompt. + +```sh +curl -i -L POST "https://api.box.com/2.0/ai/text_gen" \ + -H "content-type: application/json" \ + -H "authorization: Bearer " \ + -d '{ + "items": [ + { + "id": "12345678", + "type": "file" + } + ], + "prompt": "Create a short blog post that provides information on Box AI for Documents and focuses on best practices for asking questions. You can add emoticons, but not too many." +}' +``` + +The result will be as follows: + +```sh +{ + "answer": "📝 **Box AI for Documents: Best Practices for Asking Questions** 🤔\n\n---\n\nWelcome to our blog post on Box AI for Documents! 🎉 Today, we're going to dive into some best practices when it comes to asking questions within this innovative platform.\n\n1. **Be Clear and Concise**: When formulating a question in Box Notes, make sure your query is clear and to the point. This helps Box AI understand exactly what you're looking for.\n\n2. **Provide Context**: Giving context around your question can significantly improve the accuracy of the response generated by Box AI. Include relevant details or background information.\n\n3. **Use Keywords**: Utilize keywords related to your query within the question itself. This can help Box AI better identify the main topic of your inquiry.\n\n4. **Avoid Ambiguity**: Try to avoid vague or ambiguous questions that could lead to misunderstandings. The more precise you are, the better Box AI can assist you.\n\n5. **Review Suggestions Carefully**: After receiving suggestions from Box AI, take the time to review them carefully before incorporating them into your document. Ensure they align with your intended message.\n\nBy following these best practices, you can maximize the effectiveness of Box AI for Documents and streamline your workflow like never before! 💼✨\n\nStay tuned for more tips and tricks on leveraging technology for enhanced productivity! 👩‍💻🚀", + "created_at": "2024-11-04T02:46:23.459-08:00", + "completion_reason": "done" +} +``` + +[prereq]: g://box-ai/ai-tutorials/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 +[overrides]: g://box-ai/ai-agents/ai-agent-overrides \ No newline at end of file diff --git a/content/guides/box-ai/ai-tutorials/index.md b/content/guides/box-ai/ai-tutorials/index.md new file mode 100644 index 000000000..a53a31d65 --- /dev/null +++ b/content/guides/box-ai/ai-tutorials/index.md @@ -0,0 +1,14 @@ +--- +rank: 0 +related_guides: + - authentication/tokens/developer-tokens/ + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/default-agent-overrides + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata-structured + - box-ai/ai-tutorials/extract-metadata +--- + +# Box AI tutorials + +The listed tutorials provide you with an overview and use cases for Q&A and text generation, metadata extraction, and AI model configuration overrides. diff --git a/content/guides/box-ai/prerequisites.md b/content/guides/box-ai/ai-tutorials/prerequisites.md similarity index 90% rename from content/guides/box-ai/prerequisites.md rename to content/guides/box-ai/ai-tutorials/prerequisites.md index 6a0bb21a4..9a99d6eff 100644 --- a/content/guides/box-ai/prerequisites.md +++ b/content/guides/box-ai/ai-tutorials/prerequisites.md @@ -1,10 +1,11 @@ --- -rank: 2 +rank: 1 related_guides: - - authentication/tokens/developer-tokens/ - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/ai-agents/get-agent-default-config + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/default-agent-overrides + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata + - box-ai/ai-tutorials/extract-metadata-structured --- # Get started with Box AI @@ -50,7 +51,7 @@ To add a scope: 2. Go to **Configuration** > **Application Scopes** > **Content Actions** 3. Select the **Manage AI** scope. Box Platform will automatically include the scope when making the call. If you are added as an collaborator for a given app, but do not have Box AI API access, you will see the **Manage AI** scope checked and grayed out. This means the app owner has the AI scope enabled but you cannot change this setting. - ![box ai scopes](./images/box-ai-app-scopes.png) + ![box ai scopes](../images/box-ai-app-scopes.png) 4. Submit your app for [authorization or enablement][authorization]. If you want to enable Box AI API for an existing application, you must [re-authorize][reauthorization] it. @@ -65,7 +66,7 @@ To generate a token: 2. Click the **Options menu** button (…) on the right. 3. Select **Generate Developer Token**. The token will be automatically generated and saved to clipboard. -![generate token](./images/developer-token.png) +![generate token](../images/developer-token.png) You can also open your app, go to **Configuration** > **Developer Token** diff --git a/content/guides/box-ai/ask-questions.md b/content/guides/box-ai/ask-questions.md deleted file mode 100644 index 6ba77746a..000000000 --- a/content/guides/box-ai/ask-questions.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -rank: 3 -related_endpoints: - - post_ai_ask -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 - - -Box AI API is available to all Enterprise Plus customers. - - - -Box AI API allows you to -ask a question about a supplied file or -a set of files, and get a response based on -the content. -For example, while viewing a document in Box, -you can ask Box AI to summarize the content. - -## Send a request - -To send a request containing your question, -use the `POST /2.0/ai/ask` endpoint and -provide the mandatory parameters. - - - -### Authentication - -Make sure you have generated the developer token -to authorize your app. See [prerequisites for using Box AI][prereq] -for details. - -### Parameters - -To make a call, you need to pass the following parameters. -Mandatory parameters are in **bold**. - -| Parameter |Description | Available values | Example | -| ------------ | ------ | ----------- | --- | -| **`mode`** | The type of request. It can be a question about a single file or a set of files. For a single file, Box AI API supports up to 1MB of text representation. If the file size exceeds 1MB, the first 1MB of text representation will be processed. If you want to list multiple files, the limit is 25 files. If you set `mode` to `single_item_qa`, the `items` array can list only one element.| `single_item_qa`, `multiple_item_qa` | `single_item_qa` | -| **`prompt`** | The question about your document or content. The prompt's length cannot exceed 10000 characters. | | `What is this document about?` | -| `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` | -|`include_citations`| Specifies if the citations should be returned in the answer.| `true`, `false`| `true`| -|**`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. 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 -[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 deleted file mode 100644 index 420320692..000000000 --- a/content/guides/box-ai/generate-text.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -rank: 6 -related_endpoints: - - post_ai_text_gen -related_guides: - - box-ai/prerequisites - - box-ai/ask-questions - - box-ai/ai-agents/get-agent-default-config ---- -# Generate text with Box AI - - -Box AI API is available to all Enterprise Plus customers. - - - -You can use Box AI to generate text -based on provided content. - For example, you can ask Box AI to - generate a template based - on the content you read or create in Box Notes. - Then you can embed the generated text - directly into your document. - -## Send a request - -To send a request, use the -`POST /2.0/ai/text_gen` endpoint. - -Make sure you have generated the developer token -to authorize your app. See [prerequisites for using Box AI][prereq] -for details. - - - -### Parameters - -To make a call, you must pass the following parameters. Mandatory parameters are in **bold**. - -**Note**: The `items` array can have exactly one element. - -| Parameter| Description| Example| -|--------|--------|-------| -|**`prompt`**| The request for Box AI to generate or refine the text. The prompt's length cannot exceed 10000 characters.|Create a meeting agenda for a weekly sales meeting.| -|**`items.id`**|Box file ID of the document. |`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 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 -[overrides]: g://box-ai/ai-agents/overrides-tutorial \ No newline at end of file diff --git a/content/guides/box-ai/index.md b/content/guides/box-ai/index.md index 3eb273c76..e72cf92e0 100644 --- a/content/guides/box-ai/index.md +++ b/content/guides/box-ai/index.md @@ -4,11 +4,11 @@ related_endpoints: - post_ai_text_gen - post_ai_ask related_guides: - - box-ai/prerequisites - - box-ai/ask-questions - - box-ai/generate-text - - box-ai/extract-metadata-structured - - box-ai/extract-metadata + - box-ai/ai-tutorials/prerequisites + - box-ai/ai-tutorials/ask-questions + - box-ai/ai-tutorials/generate-text + - box-ai/ai-tutorials/extract-metadata-structured + - box-ai/ai-tutorials/extract-metadata --- diff --git a/content/microcopy/ai_dev_zone.yml b/content/microcopy/ai_dev_zone.yml index 0ad5e364a..53988ea59 100644 --- a/content/microcopy/ai_dev_zone.yml +++ b/content/microcopy/ai_dev_zone.yml @@ -81,7 +81,7 @@ side_panel: summary: title: Document summary cta: Learn more - url: /guides/box-ai/ask-questions/ + url: /guides/box-ai/ai-tutorials/ask-questions/ metadata: title: Structured metadata extraction cta: Learn more @@ -93,7 +93,7 @@ side_panel: qa: title: Document Q&A cta: Learn more - url: /guides/box-ai/generate-text/ + url: /guides/box-ai/ai-tutorials/generate-text/ tab_demo: Demo tab_sample_code: Sample code filtersError: Select the tone of voice and length to generate