feat(api): add required tool_choice (#803)

Author: stainless-bot

Diff for: src/resources/beta/threads/runs/runs.ts

@@ -445,8 +445,9 @@ export interface Run {
   /**
    * Controls which (if any) tool is called by the model. `none` means the model will
    * not call any tools and instead generates a message. `auto` is the default value
-   * and means the model can pick between generating a message or calling a tool.
-   * Specifying a particular tool like `{"type": "file_search"}` or
+   * and means the model can pick between generating a message or calling one or more
+   * tools. `required` means the model must call one or more tools before responding
+   * to the user. Specifying a particular tool like `{"type": "file_search"}` or
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
    * call that tool.
    */
@@ -713,8 +714,9 @@ export interface RunCreateParamsBase {
   /**
    * Controls which (if any) tool is called by the model. `none` means the model will
    * not call any tools and instead generates a message. `auto` is the default value
-   * and means the model can pick between generating a message or calling a tool.
-   * Specifying a particular tool like `{"type": "file_search"}` or
+   * and means the model can pick between generating a message or calling one or more
+   * tools. `required` means the model must call one or more tools before responding
+   * to the user. Specifying a particular tool like `{"type": "file_search"}` or
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
    * call that tool.
    */
@@ -964,8 +966,9 @@ export interface RunCreateAndPollParams {
   /**
    * Controls which (if any) tool is called by the model. `none` means the model will
    * not call any tools and instead generates a message. `auto` is the default value
-   * and means the model can pick between generating a message or calling a tool.
-   * Specifying a particular tool like `{"type": "file_search"}` or
+   * and means the model can pick between generating a message or calling one or more
+   * tools. `required` means the model must call one or more tools before responding
+   * to the user. Specifying a particular tool like `{"type": "file_search"}` or
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
    * call that tool.
    */
@@ -1168,8 +1171,9 @@ export interface RunCreateAndStreamParams {
   /**
    * Controls which (if any) tool is called by the model. `none` means the model will
    * not call any tools and instead generates a message. `auto` is the default value
-   * and means the model can pick between generating a message or calling a tool.
-   * Specifying a particular tool like `{"type": "file_search"}` or
+   * and means the model can pick between generating a message or calling one or more
+   * tools. `required` means the model must call one or more tools before responding
+   * to the user. Specifying a particular tool like `{"type": "file_search"}` or
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
    * call that tool.
    */
@@ -1372,8 +1376,9 @@ export interface RunStreamParams {
   /**
    * Controls which (if any) tool is called by the model. `none` means the model will
    * not call any tools and instead generates a message. `auto` is the default value
-   * and means the model can pick between generating a message or calling a tool.
-   * Specifying a particular tool like `{"type": "file_search"}` or
+   * and means the model can pick between generating a message or calling one or more
+   * tools. `required` means the model must call one or more tools before responding
+   * to the user. Specifying a particular tool like `{"type": "file_search"}` or
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
    * call that tool.
    */

Diff for: src/resources/beta/threads/threads.ts

@@ -169,12 +169,13 @@ export interface AssistantToolChoiceFunction {
 /**
  * Controls which (if any) tool is called by the model. `none` means the model will
  * not call any tools and instead generates a message. `auto` is the default value
- * and means the model can pick between generating a message or calling a tool.
- * Specifying a particular tool like `{"type": "file_search"}` or
+ * and means the model can pick between generating a message or calling one or more
+ * tools. `required` means the model must call one or more tools before responding
+ * to the user. Specifying a particular tool like `{"type": "file_search"}` or
  * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
  * call that tool.
  */
-export type AssistantToolChoiceOption = 'none' | 'auto' | AssistantToolChoice;
+export type AssistantToolChoiceOption = 'none' | 'auto' | 'required' | AssistantToolChoice;
 
 /**
  * Represents a thread that contains
@@ -551,8 +552,9 @@ export interface ThreadCreateAndRunParamsBase {
   /**
    * Controls which (if any) tool is called by the model. `none` means the model will
    * not call any tools and instead generates a message. `auto` is the default value
-   * and means the model can pick between generating a message or calling a tool.
-   * Specifying a particular tool like `{"type": "file_search"}` or
+   * and means the model can pick between generating a message or calling one or more
+   * tools. `required` means the model must call one or more tools before responding
+   * to the user. Specifying a particular tool like `{"type": "file_search"}` or
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
    * call that tool.
    */
@@ -900,8 +902,9 @@ export interface ThreadCreateAndRunPollParams {
   /**
    * Controls which (if any) tool is called by the model. `none` means the model will
    * not call any tools and instead generates a message. `auto` is the default value
-   * and means the model can pick between generating a message or calling a tool.
-   * Specifying a particular tool like `{"type": "file_search"}` or
+   * and means the model can pick between generating a message or calling one or more
+   * tools. `required` means the model must call one or more tools before responding
+   * to the user. Specifying a particular tool like `{"type": "file_search"}` or
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
    * call that tool.
    */
@@ -1228,8 +1231,9 @@ export interface ThreadCreateAndRunStreamParams {
   /**
    * Controls which (if any) tool is called by the model. `none` means the model will
    * not call any tools and instead generates a message. `auto` is the default value
-   * and means the model can pick between generating a message or calling a tool.
-   * Specifying a particular tool like `{"type": "file_search"}` or
+   * and means the model can pick between generating a message or calling one or more
+   * tools. `required` means the model must call one or more tools before responding
+   * to the user. Specifying a particular tool like `{"type": "file_search"}` or
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
    * call that tool.
    */

Diff for: src/resources/chat/completions.ts

@@ -598,17 +598,17 @@ export interface ChatCompletionTool {
 }
 
 /**
- * Controls which (if any) function is called by the model. `none` means the model
- * will not call a function and instead generates a message. `auto` means the model
- * can pick between generating a message or calling a function. Specifying a
- * particular function via
+ * Controls which (if any) tool is called by the model. `none` means the model will
+ * not call any tool and instead generates a message. `auto` means the model can
+ * pick between generating a message or calling one or more tools. `required` means
+ * the model must call one or more tools. Specifying a particular tool via
  * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
- * call that function.
+ * call that tool.
  *
- * `none` is the default when no functions are present. `auto` is the default if
- * functions are present.
+ * `none` is the default when no tools are present. `auto` is the default if tools
+ * are present.
  */
-export type ChatCompletionToolChoiceOption = 'none' | 'auto' | ChatCompletionNamedToolChoice;
+export type ChatCompletionToolChoiceOption = 'none' | 'auto' | 'required' | ChatCompletionNamedToolChoice;
 
 export interface ChatCompletionToolMessageParam {
   /**
@@ -796,15 +796,15 @@ export interface ChatCompletionCreateParamsBase {
   temperature?: number | null;
 
   /**
-   * Controls which (if any) function is called by the model. `none` means the model
-   * will not call a function and instead generates a message. `auto` means the model
-   * can pick between generating a message or calling a function. Specifying a
-   * particular function via
+   * Controls which (if any) tool is called by the model. `none` means the model will
+   * not call any tool and instead generates a message. `auto` means the model can
+   * pick between generating a message or calling one or more tools. `required` means
+   * the model must call one or more tools. Specifying a particular tool via
    * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
-   * call that function.
+   * call that tool.
    *
-   * `none` is the default when no functions are present. `auto` is the default if
-   * functions are present.
+   * `none` is the default when no tools are present. `auto` is the default if tools
+   * are present.
    */
   tool_choice?: ChatCompletionToolChoiceOption;