llm-messages 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,179 @@
+/**
+ * Type definitions for the three supported provider message formats plus the
+ * shared conversion plumbing.
+ *
+ * The OpenAI Chat Completions format is the canonical hub: every conversion goes
+ * `source -> OpenAI -> target`. The provider request shapes (Anthropic, Gemini)
+ * keep the system prompt outside the message list, so they are modelled as
+ * "conversation" objects rather than plain arrays.
+ */
+/** A supported provider. */
+type Provider = 'openai' | 'anthropic' | 'gemini';
+/** A stable, machine readable code describing a non fatal conversion event. */
+type WarningCode = 'generated-id' | 'unmapped-tool-result' | 'merged-role' | 'dropped-content' | 'invalid-json-arguments' | 'system-midstream';
+/** A non fatal event raised during conversion. */
+interface Warning {
+    code: WarningCode;
+    message: string;
+}
+/** Options accepted by every conversion function. */
+interface ConvertOptions {
+    /** Called for each non fatal conversion event (generated id, merged turn, ...). */
+    onWarning?: (warning: Warning) => void;
+}
+interface OpenAITextPart {
+    type: 'text';
+    text: string;
+}
+/** A content part. Non text parts (images, audio) are preserved verbatim. */
+type OpenAIContentPart = OpenAITextPart | {
+    type: string;
+    [key: string]: unknown;
+};
+interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        /** Arguments as a JSON encoded string, per the OpenAI wire format. */
+        arguments: string;
+    };
+}
+interface OpenAISystemMessage {
+    /** `developer` is the o-series alias for `system`; both map to a system prompt. */
+    role: 'system' | 'developer';
+    content: string | OpenAITextPart[];
+    name?: string;
+}
+interface OpenAIUserMessage {
+    role: 'user';
+    content: string | OpenAIContentPart[];
+    name?: string;
+}
+interface OpenAIAssistantMessage {
+    role: 'assistant';
+    /** Text reply. `null` (or omitted) when the turn only contains tool calls. */
+    content?: string | OpenAIContentPart[] | null;
+    name?: string;
+    tool_calls?: OpenAIToolCall[];
+}
+interface OpenAIToolMessage {
+    role: 'tool';
+    tool_call_id: string;
+    content: string | OpenAITextPart[];
+}
+type OpenAIMessage = OpenAISystemMessage | OpenAIUserMessage | OpenAIAssistantMessage | OpenAIToolMessage;
+interface AnthropicTextBlock {
+    type: 'text';
+    text: string;
+}
+interface AnthropicToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    /** Parsed arguments object (not a JSON string). */
+    input: Record<string, unknown>;
+}
+interface AnthropicToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | AnthropicTextBlock[];
+    is_error?: boolean;
+}
+type AnthropicContentBlock = AnthropicTextBlock | AnthropicToolUseBlock | AnthropicToolResultBlock | {
+    type: string;
+    [key: string]: unknown;
+};
+interface AnthropicMessage {
+    role: 'user' | 'assistant';
+    content: string | AnthropicContentBlock[];
+}
+/** An Anthropic request body fragment: the system prompt sits outside `messages`. */
+interface AnthropicConversation {
+    system?: string;
+    messages: AnthropicMessage[];
+}
+interface GeminiTextPart {
+    text: string;
+}
+interface GeminiFunctionCallPart {
+    functionCall: {
+        id?: string;
+        name: string;
+        /** Parsed arguments object (not a JSON string). */
+        args: Record<string, unknown>;
+    };
+}
+interface GeminiFunctionResponsePart {
+    functionResponse: {
+        id?: string;
+        name: string;
+        /** Result as a JSON object. Gemini has no string shorthand. */
+        response: Record<string, unknown>;
+    };
+}
+type GeminiPart = GeminiTextPart | GeminiFunctionCallPart | GeminiFunctionResponsePart | Record<string, unknown>;
+interface GeminiContent {
+    /** `model` is Gemini's name for the assistant role. */
+    role?: 'user' | 'model';
+    parts: GeminiPart[];
+}
+/** A Gemini request body fragment: `systemInstruction` sits outside `contents`. */
+interface GeminiConversation {
+    systemInstruction?: GeminiContent;
+    contents: GeminiContent[];
+}
+
+/**
+ * Converts a canonical OpenAI conversation into an Anthropic request fragment
+ * (`{ system, messages }`). System messages move to the top-level `system`
+ * field, tool-call arguments are JSON parsed into `input` objects, tool results
+ * are folded into `tool_result` blocks inside a user turn, and consecutive
+ * same-role turns are merged to satisfy Anthropic's strict alternation.
+ */
+declare function toAnthropic(messages: OpenAIMessage[], options?: ConvertOptions): AnthropicConversation;
+/**
+ * Converts an Anthropic request fragment back into a canonical OpenAI message
+ * array. The top-level `system` becomes a leading system message, `tool_use`
+ * blocks become `tool_calls` (with `input` re-serialized to a JSON string), and
+ * `tool_result` blocks become standalone `role: 'tool'` messages.
+ */
+declare function fromAnthropic(conversation: AnthropicConversation, options?: ConvertOptions): OpenAIMessage[];
+
+/**
+ * Converts a canonical OpenAI conversation into a Gemini request fragment
+ * (`{ systemInstruction, contents }`). The assistant role becomes `model`,
+ * tool-call arguments are JSON parsed into `args` objects, tool results become
+ * `functionResponse` parts whose `name` is recovered from the matching call, and
+ * consecutive same-role turns are merged for Gemini's strict alternation.
+ *
+ * The OpenAI tool-call `id` is carried through as `functionCall.id` so that a
+ * round trip (OpenAI -> Gemini -> OpenAI) preserves ids exactly.
+ */
+declare function toGemini(messages: OpenAIMessage[], options?: ConvertOptions): GeminiConversation;
+/**
+ * Converts a Gemini request fragment back into a canonical OpenAI message array.
+ * Because Gemini matches tool calls and responses by function name (the `id`
+ * field is optional), this maintains a queue of pending calls and resolves each
+ * `functionResponse` by id when present, otherwise by name in call order,
+ * generating a deterministic id as a last resort.
+ */
+declare function fromGemini(conversation: GeminiConversation, options?: ConvertOptions): OpenAIMessage[];
+
+/** Maps a provider to the conversation shape it accepts and returns. */
+type ConversationOf<P extends Provider> = P extends 'openai' ? OpenAIMessage[] : P extends 'anthropic' ? AnthropicConversation : P extends 'gemini' ? GeminiConversation : never;
+/**
+ * Converts a conversation from one provider format to another. Every conversion
+ * routes through the canonical OpenAI representation, so any source/target pair
+ * is supported, including same-provider normalization.
+ *
+ * @example
+ * const gemini = convert(openaiMessages, { from: 'openai', to: 'gemini' });
+ * const openai = convert(anthropicBody, { from: 'anthropic', to: 'openai' });
+ */
+declare function convert<From extends Provider, To extends Provider>(conversation: ConversationOf<From>, route: {
+    from: From;
+    to: To;
+}, options?: ConvertOptions): ConversationOf<To>;
+
+export { type AnthropicContentBlock, type AnthropicConversation, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResultBlock, type AnthropicToolUseBlock, type ConversationOf, type ConvertOptions, type GeminiContent, type GeminiConversation, type GeminiFunctionCallPart, type GeminiFunctionResponsePart, type GeminiPart, type GeminiTextPart, type OpenAIAssistantMessage, type OpenAIContentPart, type OpenAIMessage, type OpenAISystemMessage, type OpenAITextPart, type OpenAIToolCall, type OpenAIToolMessage, type OpenAIUserMessage, type Provider, type Warning, type WarningCode, convert, fromAnthropic, fromGemini, toAnthropic, toGemini };

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Type definitions for the three supported provider message formats plus the
+ * shared conversion plumbing.
+ *
+ * The OpenAI Chat Completions format is the canonical hub: every conversion goes
+ * `source -> OpenAI -> target`. The provider request shapes (Anthropic, Gemini)
+ * keep the system prompt outside the message list, so they are modelled as
+ * "conversation" objects rather than plain arrays.
+ */
+/** A supported provider. */
+type Provider = 'openai' | 'anthropic' | 'gemini';
+/** A stable, machine readable code describing a non fatal conversion event. */
+type WarningCode = 'generated-id' | 'unmapped-tool-result' | 'merged-role' | 'dropped-content' | 'invalid-json-arguments' | 'system-midstream';
+/** A non fatal event raised during conversion. */
+interface Warning {
+    code: WarningCode;
+    message: string;
+}
+/** Options accepted by every conversion function. */
+interface ConvertOptions {
+    /** Called for each non fatal conversion event (generated id, merged turn, ...). */
+    onWarning?: (warning: Warning) => void;
+}
+interface OpenAITextPart {
+    type: 'text';
+    text: string;
+}
+/** A content part. Non text parts (images, audio) are preserved verbatim. */
+type OpenAIContentPart = OpenAITextPart | {
+    type: string;
+    [key: string]: unknown;
+};
+interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        /** Arguments as a JSON encoded string, per the OpenAI wire format. */
+        arguments: string;
+    };
+}
+interface OpenAISystemMessage {
+    /** `developer` is the o-series alias for `system`; both map to a system prompt. */
+    role: 'system' | 'developer';
+    content: string | OpenAITextPart[];
+    name?: string;
+}
+interface OpenAIUserMessage {
+    role: 'user';
+    content: string | OpenAIContentPart[];
+    name?: string;
+}
+interface OpenAIAssistantMessage {
+    role: 'assistant';
+    /** Text reply. `null` (or omitted) when the turn only contains tool calls. */
+    content?: string | OpenAIContentPart[] | null;
+    name?: string;
+    tool_calls?: OpenAIToolCall[];
+}
+interface OpenAIToolMessage {
+    role: 'tool';
+    tool_call_id: string;
+    content: string | OpenAITextPart[];
+}
+type OpenAIMessage = OpenAISystemMessage | OpenAIUserMessage | OpenAIAssistantMessage | OpenAIToolMessage;
+interface AnthropicTextBlock {
+    type: 'text';
+    text: string;
+}
+interface AnthropicToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    /** Parsed arguments object (not a JSON string). */
+    input: Record<string, unknown>;
+}
+interface AnthropicToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | AnthropicTextBlock[];
+    is_error?: boolean;
+}
+type AnthropicContentBlock = AnthropicTextBlock | AnthropicToolUseBlock | AnthropicToolResultBlock | {
+    type: string;
+    [key: string]: unknown;
+};
+interface AnthropicMessage {
+    role: 'user' | 'assistant';
+    content: string | AnthropicContentBlock[];
+}
+/** An Anthropic request body fragment: the system prompt sits outside `messages`. */
+interface AnthropicConversation {
+    system?: string;
+    messages: AnthropicMessage[];
+}
+interface GeminiTextPart {
+    text: string;
+}
+interface GeminiFunctionCallPart {
+    functionCall: {
+        id?: string;
+        name: string;
+        /** Parsed arguments object (not a JSON string). */
+        args: Record<string, unknown>;
+    };
+}
+interface GeminiFunctionResponsePart {
+    functionResponse: {
+        id?: string;
+        name: string;
+        /** Result as a JSON object. Gemini has no string shorthand. */
+        response: Record<string, unknown>;
+    };
+}
+type GeminiPart = GeminiTextPart | GeminiFunctionCallPart | GeminiFunctionResponsePart | Record<string, unknown>;
+interface GeminiContent {
+    /** `model` is Gemini's name for the assistant role. */
+    role?: 'user' | 'model';
+    parts: GeminiPart[];
+}
+/** A Gemini request body fragment: `systemInstruction` sits outside `contents`. */
+interface GeminiConversation {
+    systemInstruction?: GeminiContent;
+    contents: GeminiContent[];
+}
+
+/**
+ * Converts a canonical OpenAI conversation into an Anthropic request fragment
+ * (`{ system, messages }`). System messages move to the top-level `system`
+ * field, tool-call arguments are JSON parsed into `input` objects, tool results
+ * are folded into `tool_result` blocks inside a user turn, and consecutive
+ * same-role turns are merged to satisfy Anthropic's strict alternation.
+ */
+declare function toAnthropic(messages: OpenAIMessage[], options?: ConvertOptions): AnthropicConversation;
+/**
+ * Converts an Anthropic request fragment back into a canonical OpenAI message
+ * array. The top-level `system` becomes a leading system message, `tool_use`
+ * blocks become `tool_calls` (with `input` re-serialized to a JSON string), and
+ * `tool_result` blocks become standalone `role: 'tool'` messages.
+ */
+declare function fromAnthropic(conversation: AnthropicConversation, options?: ConvertOptions): OpenAIMessage[];
+
+/**
+ * Converts a canonical OpenAI conversation into a Gemini request fragment
+ * (`{ systemInstruction, contents }`). The assistant role becomes `model`,
+ * tool-call arguments are JSON parsed into `args` objects, tool results become
+ * `functionResponse` parts whose `name` is recovered from the matching call, and
+ * consecutive same-role turns are merged for Gemini's strict alternation.
+ *
+ * The OpenAI tool-call `id` is carried through as `functionCall.id` so that a
+ * round trip (OpenAI -> Gemini -> OpenAI) preserves ids exactly.
+ */
+declare function toGemini(messages: OpenAIMessage[], options?: ConvertOptions): GeminiConversation;
+/**
+ * Converts a Gemini request fragment back into a canonical OpenAI message array.
+ * Because Gemini matches tool calls and responses by function name (the `id`
+ * field is optional), this maintains a queue of pending calls and resolves each
+ * `functionResponse` by id when present, otherwise by name in call order,
+ * generating a deterministic id as a last resort.
+ */
+declare function fromGemini(conversation: GeminiConversation, options?: ConvertOptions): OpenAIMessage[];
+
+/** Maps a provider to the conversation shape it accepts and returns. */
+type ConversationOf<P extends Provider> = P extends 'openai' ? OpenAIMessage[] : P extends 'anthropic' ? AnthropicConversation : P extends 'gemini' ? GeminiConversation : never;
+/**
+ * Converts a conversation from one provider format to another. Every conversion
+ * routes through the canonical OpenAI representation, so any source/target pair
+ * is supported, including same-provider normalization.
+ *
+ * @example
+ * const gemini = convert(openaiMessages, { from: 'openai', to: 'gemini' });
+ * const openai = convert(anthropicBody, { from: 'anthropic', to: 'openai' });
+ */
+declare function convert<From extends Provider, To extends Provider>(conversation: ConversationOf<From>, route: {
+    from: From;
+    to: To;
+}, options?: ConvertOptions): ConversationOf<To>;
+
+export { type AnthropicContentBlock, type AnthropicConversation, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResultBlock, type AnthropicToolUseBlock, type ConversationOf, type ConvertOptions, type GeminiContent, type GeminiConversation, type GeminiFunctionCallPart, type GeminiFunctionResponsePart, type GeminiPart, type GeminiTextPart, type OpenAIAssistantMessage, type OpenAIContentPart, type OpenAIMessage, type OpenAISystemMessage, type OpenAITextPart, type OpenAIToolCall, type OpenAIToolMessage, type OpenAIUserMessage, type Provider, type Warning, type WarningCode, convert, fromAnthropic, fromGemini, toAnthropic, toGemini };