feat(core,openai): export message conversion helpers (#9340)

Author: hntrl

.changeset/gold-apples-lay.md

@@ -0,0 +1,5 @@
+---
+"@langchain/openai": minor
+---
+
+hoist message/tool conversion utilities from classes

.changeset/quiet-chicken-wave.md

@@ -0,0 +1,5 @@
+---
+"@langchain/core": patch
+---
+
+Export standard converter function utility

libs/langchain-core/package.json

@@ -602,6 +602,17 @@
         "default": "./dist/utils/event_source_parse.js"
       }
     },
+    "./utils/format": {
+      "input": "./src/utils/format.ts",
+      "require": {
+        "types": "./dist/utils/format.d.cts",
+        "default": "./dist/utils/format.cjs"
+      },
+      "import": {
+        "types": "./dist/utils/format.d.ts",
+        "default": "./dist/utils/format.js"
+      }
+    },
     "./utils/function_calling": {
       "input": "./src/utils/function_calling.ts",
       "require": {

libs/langchain-core/src/load/import_map.ts

@@ -44,6 +44,7 @@ export * as utils__async_caller from "../utils/async_caller.js";
 export * as utils__chunk_array from "../utils/chunk_array.js";
 export * as utils__env from "../utils/env.js";
 export * as utils__event_source_parse from "../utils/event_source_parse.js";
+export * as utils__format from "../utils/format.js";
 export * as utils__function_calling from "../utils/function_calling.js";
 export * as utils__hash from "../utils/hash.js";
 export * as utils__json_patch from "../utils/json_patch.js";

libs/langchain-core/src/utils/format.ts

@@ -0,0 +1,55 @@
+/**
+ * A function that converts data from one format to another.
+ *
+ * This is commonly used for transforming message content blocks between different
+ * provider-specific formats and standardized internal representations.
+ *
+ * @template T - The input type to convert from
+ * @template U - The output type to convert to
+ *
+ * @param input - The data to convert
+ * @returns The converted data in the target format
+ *
+ * @example
+ * ```typescript
+ * // Convert from OpenAI format to standard format
+ * const converter: Converter<OpenAIBlock, ContentBlock.Standard> = (block) => {
+ *   return { type: "text", text: block.text };
+ * };
+ * ```
+ */
+export type Converter<T, U> = (input: T) => U;
+
+/**
+ * A pair of bidirectional conversion functions for transforming data between two formats.
+ *
+ * This type is used throughout the message system to enable conversion between
+ * provider-specific message formats (like OpenAI, Anthropic, Google, etc.) and
+ * standardized internal content block representations. The `encode` function
+ * typically converts from a standard format to a provider-specific format, while
+ * `decode` converts from a provider-specific format back to the standard format.
+ *
+ * @template T - The first format (typically the standard/internal format)
+ * @template U - The second format (typically the provider-specific format)
+ *
+ * @property encode - Converts from format T to format U
+ * @property decode - Converts from format U back to format T
+ *
+ * @example
+ * ```typescript
+ * // Converter pair for OpenAI message blocks
+ * const openAIConverter: ConverterPair<ContentBlock.Standard, OpenAIBlock> = {
+ *   encode: (standard) => ({ text: standard.text }),
+ *   decode: (openai) => ({ type: "text", text: openai.text })
+ * };
+ *
+ * // Usage
+ * const standardBlock = { type: "text", text: "Hello" };
+ * const openaiBlock = openAIConverter.encode(standardBlock);
+ * const backToStandard = openAIConverter.decode(openaiBlock);
+ * ```
+ */
+export type ConverterPair<T, U> = {
+  encode: Converter<T, U>;
+  decode: Converter<U, T>;
+};

libs/providers/langchain-openai/src/chat_models/base.ts

@@ -57,8 +57,6 @@ import {
   interopZodResponseFormat,
   _convertOpenAIResponsesUsageToLangChainUsage,
 } from "../utils/output.js";
-import { _convertMessagesToOpenAIParams } from "../utils/message_inputs.js";
-import { _convertToResponsesMessageFromV1 } from "../utils/standard.js";
 import { isReasoningModel, messageToOpenAIRole } from "../utils/misc.js";
 
 interface OpenAILLMOutput {
@@ -615,7 +613,7 @@ export abstract class BaseChatOpenAI<
           : this._convertChatOpenAIToolToCompletionsTool(tool, { strict })
       ),
       ...kwargs,
-    });
+    } as Partial<CallOptions>);
   }
 
   override async stream(input: BaseLanguageModelInput, options?: CallOptions) {
@@ -894,7 +892,7 @@ export abstract class BaseChatOpenAI<
           kwargs: { method: "json_mode" },
           schema: { title: name ?? "extract", ...asJsonSchema },
         },
-      });
+      } as Partial<CallOptions>);
     } else if (method === "jsonSchema") {
       const openaiJsonSchemaParams = {
         name: name ?? "extract",
@@ -917,7 +915,7 @@ export abstract class BaseChatOpenAI<
             ...asJsonSchema,
           },
         },
-      });
+      } as Partial<CallOptions>);
       if (isInteropZodSchema(schema)) {
         const altParser = StructuredOutputParser.fromZodSchema(schema);
         outputParser = RunnableLambda.from<AIMessageChunk, RunOutput>(
@@ -960,7 +958,7 @@ export abstract class BaseChatOpenAI<
           },
           // Do not pass `strict` argument to OpenAI if `config.strict` is undefined
           ...(config?.strict !== undefined ? { strict: config.strict } : {}),
-        });
+        } as Partial<CallOptions>);
         outputParser = new JsonOutputKeyToolsParser({
           returnSingle: true,
           keyName: functionName,
@@ -1004,7 +1002,7 @@ export abstract class BaseChatOpenAI<
           },
           // Do not pass `strict` argument to OpenAI if `config.strict` is undefined
           ...(config?.strict !== undefined ? { strict: config.strict } : {}),
-        });
+        } as Partial<CallOptions>);
         outputParser = new JsonOutputKeyToolsParser<RunOutput>({
           returnSingle: true,
           keyName: functionName,