feat: Add support for ChatToolChoiceRequired (#474)

packages/langchain_core/lib/src/chat_models/types.dart

@@ -382,6 +382,8 @@ class AIChatMessageToolCall {
   });
 
   /// The id of the tool to call.
+  ///
+  /// This is used to match up the tool results later.
   final String id;
 
   /// The name of the tool to call.
@@ -623,7 +625,7 @@ class ChatMessageContentImage extends ChatMessageContent {
 
   /// Depending on the model, this can be either:
   /// - The base64 encoded image data
-  /// - A URL of the image.
+  /// - A URL of the image (only supported by some providers)
   final String data;
 
   /// The IANA standard MIME type of the source data.
@@ -713,9 +715,12 @@ sealed class ChatToolChoice {
   /// The model does not call a tool, and responds to the end-user.
   static const none = ChatToolChoiceNone();
 
-  /// The model can pick between an end-user or calling a tool.
+  /// The model can pick between responding to the end-user or calling a tool.
   static const auto = ChatToolChoiceAuto();
 
+  /// The model must call at least one tool, but doesn’t force a particular tool.
+  static const required = ChatToolChoiceRequired();
+
   /// The model is forced to to call the specified tool.
   factory ChatToolChoice.forced({required final String name}) =>
       ChatToolChoiceForced(name: name);
@@ -730,13 +735,21 @@ final class ChatToolChoiceNone extends ChatToolChoice {
 }
 
 /// {@template chat_tool_choice_auto}
-/// The model can pick between an end-user or calling a tool.
+/// The model can pick between responding to the end-user or calling a tool.
 /// {@endtemplate}
 final class ChatToolChoiceAuto extends ChatToolChoice {
   /// {@macro chat_tool_choice_auto}
   const ChatToolChoiceAuto();
 }
 
+/// {@template chat_tool_choice_required}
+/// The model must call at least one tool, but doesn’t force a particular tool.
+/// {@endtemplate}
+final class ChatToolChoiceRequired extends ChatToolChoice {
+  /// {@macro chat_tool_choice_none}
+  const ChatToolChoiceRequired();
+}
+
 /// {@template chat_tool_choice_forced}
 /// The model is forced to to call the specified tool.
 /// {@endtemplate}

packages/langchain_core/lib/src/language_models/types.dart

@@ -99,12 +99,16 @@ class LanguageModelUsage {
   });
 
   /// The number of tokens in the prompt.
+  ///
+  /// Some providers call this "input_tokens".
   final int? promptTokens;
 
   /// The total number of billable characters in the prompt if applicable.
   final int? promptBillableCharacters;
 
   /// The number of tokens in the completion.
+  ///
+  /// Some providers call this "output_tokens".
   final int? responseTokens;
 
   /// The total number of billable characters in the completion if applicable.
@@ -172,9 +176,13 @@ LanguageModelUsage{
 /// The reason the model stopped generating tokens.
 enum FinishReason {
   /// The model hit a natural stop point or a provided stop sequence.
+  ///
+  /// Some providers call this "end_turn".
   stop,
 
   /// The maximum number of tokens specified in the request was reached.
+  ///
+  /// Some providers call this "max_tokens".
   length,
 
   /// The content was flagged for content filter reasons.
@@ -184,6 +192,8 @@ enum FinishReason {
   recitation,
 
   /// The model called a tool.
+  ///
+  /// Some providers call this "tool_use".
   toolCalls,
 
   /// The finish reason is unspecified.

packages/langchain_firebase/lib/src/chat_models/vertex_ai/mappers.dart

@@ -293,6 +293,11 @@ extension ChatToolChoiceMapper on ChatToolChoice {
             mode: f.FunctionCallingMode.auto,
           ),
         ),
+      ChatToolChoiceRequired() => f.ToolConfig(
+          functionCallingConfig: f.FunctionCallingConfig(
+            mode: f.FunctionCallingMode.any,
+          ),
+        ),
       final ChatToolChoiceForced t => f.ToolConfig(
           functionCallingConfig: f.FunctionCallingConfig(
             mode: f.FunctionCallingMode.any,

packages/langchain_google/lib/src/chat_models/google_ai/mappers.dart

@@ -294,6 +294,11 @@ extension ChatToolChoiceMapper on ChatToolChoice {
             mode: g.FunctionCallingMode.auto,
           ),
         ),
+      ChatToolChoiceRequired() => g.ToolConfig(
+          functionCallingConfig: g.FunctionCallingConfig(
+            mode: g.FunctionCallingMode.any,
+          ),
+        ),
       final ChatToolChoiceForced t => g.ToolConfig(
           functionCallingConfig: g.FunctionCallingConfig(
             mode: g.FunctionCallingMode.any,

packages/langchain_openai/lib/src/chat_models/mappers.dart

@@ -193,6 +193,9 @@ extension ChatToolChoiceMapper on ChatToolChoice {
       ChatToolChoiceAuto _ => const ChatCompletionToolChoiceOption.mode(
           ChatCompletionToolChoiceMode.auto,
         ),
+      ChatToolChoiceRequired() => const ChatCompletionToolChoiceOption.mode(
+          ChatCompletionToolChoiceMode.required,
+        ),
       final ChatToolChoiceForced t => ChatCompletionToolChoiceOption.tool(
           ChatCompletionNamedToolChoice(
             type: ChatCompletionNamedToolChoiceType.function,