UNPKG

@langchain/core

Version:
1 lines 25.9 kB
{"version":3,"file":"message.cjs","names":["message: unknown"],"sources":["../../src/messages/message.ts"],"sourcesContent":["import type { ContentBlock } from \"./content/index.js\";\nimport type { ResponseMetadata, UsageMetadata } from \"./metadata.js\";\nimport type { $MergeDiscriminatedUnion, $MergeObjects } from \"./utils.js\";\n\n/**\n * Represents the possible types of messages in the system.\n * Includes standard message types (\"ai\", \"human\", \"tool\", \"system\")\n * and allows for custom string types that are non-null.\n *\n * @example\n * ```ts\n * // Standard message types\n * const messageType1: MessageType = \"ai\";\n * const messageType2: MessageType = \"human\";\n *\n * // Custom message type\n * const messageType3: MessageType = \"custom_type\";\n * ```\n */\nexport type MessageType =\n | \"ai\"\n | \"human\"\n | \"tool\"\n | \"system\"\n | (string & NonNullable<unknown>);\n\n/**\n * Represents the output version format for message content.\n *\n * This type determines how the content field is structured in a message:\n * - \"v0\": Content is represented as a simple string or array of content blocks\n * - provides backward compatibility with simpler content representations\n * - \"v1\": Content follows the structured ContentBlock format with typed discriminated unions\n * - enables full type safety and structured content block handling\n *\n * @example\n * ```ts\n * // v0 format - simple content representation\n * const v0Message: Message<{ outputVersion: \"v0\", content: ... }> = {\n * type: \"human\",\n * content: \"Hello world\" // string | Array<ContentBlock | ContentBlock.Text>\n * };\n *\n * // v1 format - structured content blocks\n * const v1Message: Message<{ outputVersion: \"v1\", content: ... }> = {\n * type: \"human\",\n * content: [\n * { type: \"text\", text: \"Hello world\" },\n * { type: \"image\", image_url: \"...\" }\n * ] // Array<ContentBlock | ...> (determined by the structure)\n * };\n * ```\n */\nexport type MessageOutputVersion = \"v0\" | \"v1\";\n\n/**\n * Represents the input and output types of a tool that can be used in messages.\n *\n * @template TInput - The type of input the tool accepts.\n * @template TOutput - The type of output the tool produces.\n *\n * @example\n * ```ts\n * // Tool that takes a string input and returns a number\n * interface StringToNumberTool extends MessageToolDefinition<string, number> {\n * input: string;\n * output: number;\n * }\n * ```\n */\nexport interface MessageToolDefinition<TInput = unknown, TOutput = unknown> {\n input: TInput;\n output: TOutput;\n}\n\n/**\n * Represents a structured set of tools by mapping tool names to definitions\n * that can be used in messages.\n *\n * @example\n * ```ts\n * interface MyToolSet extends MessageToolSet {\n * calculator: MessageToolDefinition<\n * { operation: string; numbers: number[] },\n * number\n * >;\n * translator: MessageToolDefinition<\n * { text: string; targetLanguage: string },\n * string\n * >;\n * }\n * ```\n */\nexport interface MessageToolSet {\n [key: string]: MessageToolDefinition;\n}\n\n/**\n * Represents a tool call block within a message structure by mapping tool names to their\n * corresponding tool call formats, including the input arguments and an optional identifier.\n *\n * @template TStructure - A message structure type that may contain tool definitions\n *\n * @example\n * ```ts\n * // Given a message structure with a calculator tool:\n * interface MyStructure extends MessageStructure {\n * tools: {\n * calculator: MessageToolDefinition<{ operation: string, numbers: number[] }, number>\n * }\n * }\n *\n * // The tool call block would be:\n * type CalcToolCall = $MessageToolCallBlock<MyStructure>;\n * // Resolves to:\n * // {\n * // type: \"tool_call\";\n * // name: \"calculator\";\n * // args: { operation: string, numbers: number[] };\n * // id?: string;\n * // }\n * ```\n */\nexport type $MessageToolCallBlock<TStructure extends MessageStructure> =\n TStructure[\"tools\"] extends MessageToolSet\n ? {\n [K in keyof TStructure[\"tools\"]]: K extends string\n ? TStructure[\"tools\"][K] extends MessageToolDefinition\n ? ContentBlock.Tools.ToolCall<K, TStructure[\"tools\"][K][\"input\"]>\n : never\n : never;\n }[keyof TStructure[\"tools\"]]\n : never;\n\n/**\n * Core interface that defines the structure of messages.\n *\n * @example\n * ```ts\n * // Basic message structure with just content blocks\n * interface SimpleMessageStructure extends MessageStructure {\n * content: {\n * human: ContentBlock.Text;\n * // allows for text + reasoning blocks in ai messages\n * ai: ContentBlock.Text | ContentBlock.Reasoning;\n * }\n * }\n *\n * // Message structure with tools and properties\n * interface AdvancedMessageStructure extends MessageStructure {\n * tools: {\n * calculator: MessageToolDefinition<\n * { operation: string; numbers: number[] },\n * number\n * >;\n * };\n * content: {\n * // allows for text + image blocks in human messages\n * human: ContentBlock.Text | ContentBlock.Multimodal.Image;\n * // only allows for text blocks in ai messages\n * ai: ContentBlock.Text;\n * };\n * properties: {\n * // pins properties to ai messages\n * ai: {\n * response_metadata: {\n * confidence: number;\n * model: string;\n * };\n * };\n * }\n * }\n *\n * // Using with $MergeMessageStructure to combine structures\n * // The resulting type when passed into BaseMessage will have a calculator tool,\n * // allow for text + image blocks in human messages,\n * // and text + reasoning blocks + additional arbitrary properties in ai messages.\n * type CombinedStructure = $MergeMessageStructure<\n * SimpleMessageStructure,\n * AdvancedMessageStructure\n * >;\n *\n * // Using in a Message object\n * const message: Message<CombinedStructure> = {\n * id: \"msg-123\",\n * type: \"human\",\n * content: [\n * { type: \"text\", text: \"Hello!\" }\n * { type: \"image\", mimeType: \"image/jpeg\", url: \"https://example.com/image.jpg\" }\n * // this block will throw an error because it's not defined in the structure\n * { type: \"reasoning\", reasoning: \"The answer is 42\" }\n * ]\n * };\n * ```\n */\nexport interface MessageStructure {\n /**\n * Optional output version for the message structure.\n * If not provided, defaults to \"v0\".\n */\n readonly outputVersion?: MessageOutputVersion;\n /**\n * Optional set of tool definitions that can be used in messages.\n * Each tool is defined with input/output types and can be referenced in tool messages.\n */\n readonly tools?: MessageToolSet;\n /**\n * Optional mapping of message types to their allowed content blocks.\n * Each message type can specify what content block types it supports (text, images, etc).\n */\n readonly content?: Partial<{\n [key in MessageType]: ContentBlock;\n }>;\n /**\n * Optional mapping of message types to arbitrary property objects.\n * Allows attaching custom metadata or other information to specific message types.\n */\n readonly properties?: Partial<{\n [key in MessageType]: Record<string, unknown>;\n }>;\n}\n\n/**\n * Normalizes an arbitrary type to a message output version or undefined.\n * Accepts unknown and narrows to a valid MessageOutputVersion if present.\n */\ntype $NormalizeMessageOutputVersion<T> =\n | Extract<T, MessageOutputVersion>\n | undefined;\n\n/**\n * Merges two output version types from message structures.\n *\n * This utility type determines the resulting output version when combining two message structures.\n * The merge logic follows these rules:\n *\n * - If both T and U are undefined, defaults to \"v0\" for backwards compatibility\n * - If T is undefined but U is defined, uses U's version\n * - If U is undefined but T is defined, uses T's version\n * - If both T and U are defined, U takes precedence (later structure wins)\n *\n * @template T - The output version from the first message structure\n * @template U - The output version from the second message structure\n *\n * @example\n * ```ts\n * // Both undefined - defaults to \"v0\"\n * type Result1 = $MergeOutputVersion<undefined, undefined>; // \"v0\"\n *\n * // One defined - uses the defined version\n * type Result2 = $MergeOutputVersion<undefined, \"v1\">; // \"v1\"\n * type Result3 = $MergeOutputVersion<\"v0\", undefined>; // \"v0\"\n *\n * // Both defined - second takes precedence\n * type Result4 = $MergeOutputVersion<\"v0\", \"v1\">; // \"v1\"\n * ```\n */\nexport type $MergeOutputVersion<T, U> =\n $NormalizeMessageOutputVersion<T> extends infer TV\n ? $NormalizeMessageOutputVersion<U> extends infer UV\n ? [TV, UV] extends [undefined, undefined]\n ? \"v0\"\n : [TV] extends [undefined]\n ? Exclude<UV, undefined>\n : [UV] extends [undefined]\n ? Exclude<TV, undefined>\n : UV\n : never\n : never;\n\n/**\n * Merges two content definition objects from message structures.\n *\n * This utility type combines content definitions from two message structures, handling\n * the merging of content block types for each message type. The merge logic follows\n * these rules:\n *\n * - For keys that exist in both T and U: Merges the content blocks using discriminated\n * union merging based on the \"type\" property. This allows combining different content\n * block types (e.g., text + image) for the same message type.\n * - For keys that exist only in T: Uses T's content definition as-is\n * - For keys that exist only in U: Uses U's content definition as-is\n *\n * @template T - The content definition from the first message structure\n * @template U - The content definition from the second message structure\n *\n * @example\n * ```ts\n * // T allows text content for human messages\n * type ContentA = {\n * human: ContentBlock.Text;\n * };\n *\n * // U allows image content for human messages and text for AI messages\n * type ContentB = {\n * human: ContentBlock.Multimodal.Image;\n * ai: ContentBlock.Text;\n * };\n *\n * // Merged result allows both text and images for human messages, text for AI\n * type Merged = $MergeContentDefinition<ContentA, ContentB>;\n * // Result: {\n * // human: ContentBlock.Text | ContentBlock.Multimodal.Image;\n * // ai: ContentBlock.Text;\n * // }\n * ```\n */\nexport type $MergeContentDefinition<T, U> = {\n [K in keyof T | keyof U as Extract<\n (K extends keyof T ? T[K] : never) | (K extends keyof U ? U[K] : never),\n ContentBlock\n > extends never\n ? never\n : K]: K extends keyof T\n ? K extends keyof U\n ? $MergeDiscriminatedUnion<\n Extract<T[K], ContentBlock>,\n Extract<U[K], ContentBlock>,\n \"type\"\n >\n : Extract<T[K], ContentBlock>\n : K extends keyof U\n ? Extract<U[K], ContentBlock>\n : never;\n};\n\n/**\n * Merges two message structures A and B into a combined structure.\n * This is a type utility that handles merging of tools, content blocks, and properties\n * from two message structures. The resulting type is usable as its own message structure.\n *\n * @example\n * ```ts\n * // Structure A allows text in human messages and has a confidence property on AI messages\n * interface StructureA extends MessageStructure {\n * content: {\n * human: ContentBlock.Text;\n * };\n * properties: {\n * ai: { confidence: number };\n * }\n * }\n *\n * // Structure B allows images in human messages and has a model property on AI messages\n * interface StructureB extends MessageStructure {\n * content: {\n * human: ContentBlock.Multimodal.Image;\n * };\n * properties: {\n * ai: { model: string };\n * }\n * }\n *\n * // Merged structure allows both text and images in human messages\n * // AI messages have both confidence and model properties\n * type Merged = $MergeMessageStructure<StructureA, StructureB>;\n * ```\n *\n * @template A - First message structure to merge\n * @template B - Second message structure to merge (takes precedence over A)\n */\nexport type $MergeMessageStructure<\n T extends MessageStructure,\n U extends MessageStructure\n> = {\n outputVersion: $MergeOutputVersion<T[\"outputVersion\"], U[\"outputVersion\"]>;\n tools: $MergeObjects<T[\"tools\"], U[\"tools\"]>;\n content: $MergeContentDefinition<T[\"content\"], U[\"content\"]>;\n properties: $MergeObjects<T[\"properties\"], U[\"properties\"]>;\n};\n\n/**\n * Standard message structured used to define the most basic message structure that's\n * used throughout the library.\n *\n * This is also the message structure that's used when a message structure is not provided.\n */\nexport interface StandardMessageStructure extends MessageStructure {\n content: {\n /** Text content for AI messages */\n ai: ContentBlock.Text;\n /** Text content for human messages */\n human: ContentBlock.Text;\n /** Text content for system messages */\n system: ContentBlock.Text;\n /** Text content for tool messages */\n tool: ContentBlock.Text;\n };\n properties: {\n /** Properties specific to AI messages */\n ai: {\n /** Metadata about the AI model response */\n response_metadata: ResponseMetadata;\n /** Usage statistics for the AI response */\n usage_metadata: UsageMetadata;\n };\n human: {\n /** Metadata about the human message */\n response_metadata: Record<string, unknown>;\n };\n system: {\n /** Metadata about the system message */\n response_metadata: Record<string, unknown>;\n };\n tool: {\n /** Metadata about the tool message */\n response_metadata: Record<string, unknown>;\n };\n };\n}\n\n/**\n * Takes a message structure type T and normalizes it by merging it with the standard message structure.\n * If T is already a standard message structure, returns T unchanged.\n *\n * This ensures that any custom message structure includes all the standard message structure fields\n * by default while allowing overrides and extensions.\n *\n * @template T - The message structure type to normalize, must extend MessageStructure\n * @returns Either T if it's already a standard structure, or the merged result of T with standard structure\n */\nexport type $NormalizedMessageStructure<T extends MessageStructure> =\n T extends StandardMessageStructure\n ? T\n : $MergeMessageStructure<StandardMessageStructure, T>;\n\n/**\n * Infers the content blocks for a specific message type in a message structure.\n *\n * This utility type extracts the content block type that corresponds to a given message type\n * from the message structure's content definition.\n *\n * @template TStructure - The message structure to infer content from\n * @template TRole - The message role/type to get content for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @returns The content block type for the specified type, or never if its not defined in the structure\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n * content: {\n * human: ContentBlock.Text;\n * ai: ContentBlock.Text | ContentBlock.ToolCall;\n * };\n * }\n *\n * type HumanContent = $InferMessageContentBlocks<MyStructure, \"human\">;\n * // HumanContent = ContentBlock.Text\n *\n * type AIContent = $InferMessageContentBlocks<MyStructure, \"ai\">;\n * // AIContent = ContentBlock.Text | ContentBlock.ToolCall\n * ```\n */\nexport type $InferMessageContentBlocks<\n TStructure extends MessageStructure,\n TRole extends MessageType\n> = $NormalizedMessageStructure<TStructure> extends infer S\n ? S extends MessageStructure\n ? S[\"content\"] extends infer C\n ? C extends Record<PropertyKey, ContentBlock>\n ? TRole extends keyof C\n ? [$MessageToolCallBlock<TStructure>] extends [never]\n ? C[TRole]\n : $MergeDiscriminatedUnion<\n NonNullable<C[TRole]>,\n $MessageToolCallBlock<TStructure>,\n \"type\"\n >\n : never\n : never\n : never\n : never\n : never;\n\n/**\n * Infers the content type for a specific message type from a message structure.\n *\n * This utility type determines the appropriate content type based on the message structure's\n * output version and the specified message type. The content type varies depending on the\n * output version (see {@link MessageOutputVersion})\n *\n * @template TStructure - The message structure to infer content from\n * @template TRole - The message role/type to get content for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @returns The content type for the specified role based on the output version\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n * outputVersion: \"v0\";\n * content: {\n * human: ContentBlock.Text;\n * ai: ContentBlock.Text | ContentBlock.ToolCall;\n * };\n * }\n *\n * type HumanContentV0 = $InferMessageContent<MyStructure, \"human\">;\n * // HumanContentV0 = string | Array<ContentBlock | ContentBlock.Text>\n *\n * interface MyStructureV1 extends MessageStructure {\n * outputVersion: \"v1\";\n * content: {\n * human: ContentBlock.Text;\n * ai: ContentBlock.Text | ContentBlock.Reasoning;\n * };\n * }\n *\n * type HumanContentV1 = $InferMessageContent<MyStructureV1, \"human\">;\n * // HumanContentV1 = ContentBlock.Text\n *\n * type AIContentV1 = $InferMessageContent<MyStructureV1, \"ai\">;\n * // AIContentV1 = ContentBlock.Text | ContentBlock.Reasoning\n * ```\n */\nexport type $InferMessageContent<\n TStructure extends MessageStructure,\n TRole extends MessageType\n> = TStructure[\"outputVersion\"] extends \"v1\"\n ? Array<$InferMessageContentBlocks<TStructure, TRole>>\n : string | Array<ContentBlock | ContentBlock.Text>;\n\n/**\n * Infers the properties for a specific message type from a message structure.\n *\n * This utility type extracts the properties object that corresponds to a given message type\n * from the message structure's properties definition, and excludes the reserved\n * \"content\" and \"type\" properties to avoid conflicts with the core message structure.\n *\n * If the specified type is not defined in the message structure's properties, it returns\n * a generic Record<string, unknown> type to allow for arbitrary properties.\n *\n * @template TStructure - The message structure to infer properties from\n * @template TRole - The message type/role to get properties for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @returns The properties object type for the specified type, excluding \"content\" and \"type\"\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n * properties: {\n * ai: {\n * response_metadata: { model: string };\n * usage_metadata: { tokens: number };\n * content: string; // This will be omitted\n * type: string; // This will be omitted\n * };\n * human: { metadata: Record<string, unknown> };\n * };\n * }\n *\n * type AIProperties = $InferMessageProperties<MyStructure, \"ai\">;\n * // AIProperties = { response_metadata: { model: string }; usage_metadata: { tokens: number } }\n *\n * type HumanProperties = $InferMessageProperties<MyStructure, \"human\">;\n * // HumanProperties = { metadata: Record<string, unknown> }\n *\n * type SystemProperties = $InferMessageProperties<MyStructure, \"system\">;\n * // SystemProperties = Record<string, unknown> (fallback for undefined role)\n * ```\n */\nexport type $InferMessageProperties<\n TStructure extends MessageStructure,\n TRole extends MessageType\n> = $NormalizedMessageStructure<TStructure> extends infer S\n ? S extends MessageStructure\n ? S[\"properties\"] extends infer P | undefined\n ? P extends Record<PropertyKey, unknown>\n ? TRole extends keyof P\n ? Omit<P[TRole], \"content\" | \"type\">\n : Record<string, unknown>\n : Record<string, unknown>\n : Record<string, unknown>\n : never\n : never;\n\n/**\n * Infers the type of a specific property for a message type from a message structure.\n *\n * This utility type extracts the type of a single property by name from the properties\n * object that corresponds to a given message type. If the specified property key does\n * not exist in the type's properties, it returns `never`.\n *\n * @template TStructure - The message structure to infer the property from\n * @template TRole - The message type/role to get the property for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @template K - The property key to extract the type for\n * @returns The type of the specified property, or `never` if the property doesn't exist\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n * properties: {\n * ai: {\n * response_metadata: { model: string; temperature: number };\n * usage_metadata: { input_tokens: number; output_tokens: number };\n * };\n * human: { metadata: Record<string, unknown> };\n * };\n * }\n *\n * type ResponseMetadata = $InferMessageProperty<MyStructure, \"ai\", \"response_metadata\">;\n * // ResponseMetadata = { model: string; temperature: number }\n *\n * type UsageMetadata = $InferMessageProperty<MyStructure, \"ai\", \"usage_metadata\">;\n * // UsageMetadata = { input_tokens: number; output_tokens: number }\n *\n * type NonExistentProperty = $InferMessageProperty<MyStructure, \"ai\", \"nonExistent\">;\n * // NonExistentProperty = Record<string, unknown>\n *\n * type HumanMetadata = $InferMessageProperty<MyStructure, \"human\", \"metadata\">;\n * // HumanMetadata = Record<string, unknown>\n * ```\n */\nexport type $InferMessageProperty<\n TStructure extends MessageStructure,\n TRole extends MessageType,\n K extends string\n> = K extends keyof $InferMessageProperties<TStructure, TRole>\n ? $InferMessageProperties<TStructure, TRole>[K]\n : never;\n\n/**\n * Infers the response metadata type for a specific message type from a message structure.\n *\n * This utility type extracts the `response_metadata` property type for a given message type.\n *\n * @template TStructure - The message structure to infer the response metadata from\n * @template TRole - The message type/role to get the response metadata for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @returns The type of the response_metadata property, or `Record<string, unknown>` as fallback\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n * properties: {\n * ai: {\n * response_metadata: { model: string; temperature: number; tokens: number };\n * };\n * human: { metadata: Record<string, unknown> };\n * };\n * }\n *\n * type AIResponseMetadata = $InferResponseMetadata<MyStructure, \"ai\">;\n * // AIResponseMetadata = { model: string; temperature: number; tokens: number }\n *\n * type HumanResponseMetadata = $InferResponseMetadata<MyStructure, \"human\">;\n * // HumanResponseMetadata = Record<string, unknown> (fallback since not defined)\n * ```\n */\nexport type $InferResponseMetadata<\n TStructure extends MessageStructure,\n TRole extends MessageType\n> = $InferMessageProperty<\n TStructure,\n TRole,\n \"response_metadata\"\n> extends infer P\n ? [P] extends [never]\n ? Record<string, unknown>\n : P\n : never;\n\n/**\n * Represents a message object that organizes context for an LLM.\n *\n * @example\n * ```ts\n * // Basic message with text content\n * const message: Message = {\n * id: \"msg-123\",\n * name: \"user\",\n * type: \"human\",\n * content: [{ type: \"text\", text: \"Hello!\" }]\n * };\n *\n * // Basic ai message interface extension\n * interface MyMessage extends Message<StandardMessageStructure, \"ai\"> {\n * // Additional AI-specific properties can be added here\n * }\n *`\n * // Custom message structure\n * interface CustomStructure extends MessageStructure {\n * content: {\n * ai: ContentBlock.Text | ContentBlock.ToolCall<\"search\", { query: string }>;\n * human: ContentBlock.Text | ContentBlock.Multimodal.Image;\n * };\n * }\n *\n * // Create a message with custom structure\n * const message: Message<CustomStructure> = {\n * id: \"msg-123\",\n * name: \"user\",\n * type: \"ai\",\n * content: [\n * { type: \"text\", text: \"Hello!\" },\n * {\n * type: \"tool_call\",\n * name: \"search\",\n * args: { query: \"What is the capital of France?\" }\n * }\n * ]\n * };\n * ```\n */\nexport interface Message<\n TStructure extends MessageStructure = StandardMessageStructure,\n TRole extends MessageType = MessageType\n> {\n /** The message type/role */\n readonly type: TRole;\n /** Unique identifier for this message */\n id?: string;\n /** Optional name/identifier for the entity that created this message */\n name?: string;\n /** Array of content blocks that make up the message content */\n content: $InferMessageContent<TStructure, TRole>;\n /** Metadata about the message */\n response_metadata?: Partial<$InferResponseMetadata<TStructure, TRole>>;\n}\n\n/**\n * Type guard to check if a value is a valid Message object.\n *\n * @param message - The value to check\n * @returns true if the value is a valid Message object, false otherwise\n */\nexport function isMessage(message: unknown): message is Message {\n return (\n typeof message === \"object\" &&\n message !== null &&\n \"type\" in message &&\n \"content\" in message &&\n (typeof message.content === \"string\" || Array.isArray(message.content))\n );\n}\n"],"mappings":";;;;;;;;AAitBA,SAAgB,UAAUA,SAAsC;AAC9D,QACE,OAAO,YAAY,YACnB,YAAY,QACZ,UAAU,WACV,aAAa,YACZ,OAAO,QAAQ,YAAY,YAAY,MAAM,QAAQ,QAAQ,QAAQ;AAEzE"}