@jsonstudio/llms 0.4.2

package/dist/conversion/hub/semantic-mappers/anthropic-mapper.js

@@ -0,0 +1,308 @@
+import { isJsonObject, jsonClone } from '../types/json.js';
+import { buildOpenAIChatFromAnthropic, buildAnthropicRequestFromOpenAIChat } from '../../codecs/anthropic-openai-codec.js';
+const ANTHROPIC_PARAMETER_KEYS = [
+    'model',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'max_output_tokens',
+    'metadata',
+    'stream',
+    'tool_choice'
+];
+const ANTHROPIC_TOP_LEVEL_FIELDS = new Set([
+    'model',
+    'messages',
+    'tools',
+    'system',
+    'stop_sequences',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'max_output_tokens',
+    'metadata',
+    'stream',
+    'tool_choice'
+]);
+const PASSTHROUGH_METADATA_PREFIX = 'rcc_passthrough_';
+const PASSTHROUGH_PARAMETERS = ['tool_choice'];
+function encodePassthroughParameters(chat) {
+    if (!chat.parameters)
+        return undefined;
+    const encoded = {};
+    for (const key of PASSTHROUGH_PARAMETERS) {
+        const value = chat.parameters[key];
+        if (value === undefined)
+            continue;
+        try {
+            encoded[`${PASSTHROUGH_METADATA_PREFIX}${key}`] = JSON.stringify(value);
+        }
+        catch {
+            continue;
+        }
+    }
+    return Object.keys(encoded).length ? encoded : undefined;
+}
+function extractPassthroughParameters(metadataField) {
+    if (!isJsonObject(metadataField))
+        return {};
+    const cloned = jsonClone(metadataField);
+    const passthrough = {};
+    let metadataMutated = false;
+    let hasPassthrough = false;
+    for (const key of Object.keys(cloned)) {
+        if (!key.startsWith(PASSTHROUGH_METADATA_PREFIX))
+            continue;
+        const paramKey = key.slice(PASSTHROUGH_METADATA_PREFIX.length);
+        if (!PASSTHROUGH_PARAMETERS.includes(paramKey))
+            continue;
+        const rawValue = cloned[key];
+        if (typeof rawValue !== 'string')
+            continue;
+        try {
+            const parsed = rawValue ? JSON.parse(rawValue) : undefined;
+            passthrough[paramKey] = parsed;
+            delete cloned[key];
+            metadataMutated = true;
+            hasPassthrough = true;
+        }
+        catch {
+            continue;
+        }
+    }
+    return {
+        metadata: metadataMutated ? (Object.keys(cloned).length ? cloned : undefined) : cloned,
+        passthrough: hasPassthrough ? passthrough : undefined
+    };
+}
+function collectParameters(payload) {
+    const params = {};
+    for (const key of ANTHROPIC_PARAMETER_KEYS) {
+        if (payload[key] !== undefined) {
+            params[key] = payload[key];
+        }
+    }
+    if (Array.isArray(payload.stop_sequences)) {
+        params.stop = payload.stop_sequences;
+    }
+    return Object.keys(params).length ? params : undefined;
+}
+function normalizeAnthropicTools(rawTools, missing) {
+    if (!Array.isArray(rawTools) || rawTools.length === 0)
+        return undefined;
+    const tools = [];
+    rawTools.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            missing.push({ path: `tools[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(entry) });
+            return;
+        }
+        const nameValue = entry.name;
+        if (typeof nameValue !== 'string' || !nameValue.trim())
+            return;
+        const desc = entry.description;
+        const schema = entry.input_schema;
+        const parameters = schema && typeof schema === 'object' && !Array.isArray(schema)
+            ? schema
+            : { type: 'object', properties: {} };
+        tools.push({
+            type: 'function',
+            function: {
+                name: nameValue,
+                description: typeof desc === 'string' ? desc : undefined,
+                parameters
+            }
+        });
+    });
+    return tools.length ? tools : undefined;
+}
+function normalizeToolContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content == null)
+        return '';
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content ?? '');
+    }
+}
+function collectToolOutputsFromMessages(messages, missing) {
+    const outputs = [];
+    messages.forEach((msg, index) => {
+        if (!msg || typeof msg !== 'object')
+            return;
+        if (msg.role !== 'tool')
+            return;
+        const callId = msg.tool_call_id || msg.id;
+        if (typeof callId !== 'string' || !callId.trim()) {
+            missing.push({ path: `messages[${index}].tool_call_id`, reason: 'missing_tool_call_id' });
+            return;
+        }
+        outputs.push({
+            tool_call_id: callId.trim(),
+            content: normalizeToolContent(msg.content),
+            name: typeof msg.name === 'string' ? msg.name : undefined
+        });
+    });
+    return outputs.length ? outputs : undefined;
+}
+function collectExtraFields(payload) {
+    const extras = {};
+    for (const key of Object.keys(payload)) {
+        if (ANTHROPIC_TOP_LEVEL_FIELDS.has(key))
+            continue;
+        extras[key] = payload[key];
+    }
+    return Object.keys(extras).length ? extras : undefined;
+}
+function collectSystemSegments(systemField) {
+    if (!systemField)
+        return [];
+    const flatten = (value) => {
+        if (typeof value === 'string')
+            return value;
+        if (Array.isArray(value)) {
+            return value.map(v => flatten(v)).filter(Boolean).join('\n');
+        }
+        if (value && typeof value === 'object') {
+            const obj = value;
+            if (typeof obj.text === 'string')
+                return obj.text;
+            if (typeof obj.content === 'string')
+                return obj.content;
+            if (Array.isArray(obj.content))
+                return obj.content.map(v => flatten(v)).join('\n');
+        }
+        return '';
+    };
+    const text = flatten(systemField).trim();
+    return text ? [text] : [];
+}
+function systemSegmentsToAnthropicBlocks(segments) {
+    if (!segments || !segments.length)
+        return undefined;
+    return segments.map(seg => ({ type: 'text', text: seg }));
+}
+export class AnthropicSemanticMapper {
+    async toChat(format, ctx) {
+        const payload = (format.payload ?? {});
+        const missing = [];
+        if (!Array.isArray(payload.messages))
+            missing.push({ path: 'messages', reason: 'absent' });
+        if (typeof payload.model !== 'string')
+            missing.push({ path: 'model', reason: 'absent' });
+        const { messages } = buildOpenAIChatFromAnthropic(payload);
+        const toolOutputs = collectToolOutputsFromMessages(messages, missing);
+        const tools = payload.tools ? normalizeAnthropicTools(payload.tools, missing) : undefined;
+        let parameters = collectParameters(payload);
+        const passthrough = extractPassthroughParameters(payload.metadata);
+        if (passthrough.passthrough) {
+            parameters = { ...(parameters || {}), ...passthrough.passthrough };
+        }
+        const systemSegments = collectSystemSegments(payload.system);
+        const metadata = { context: ctx };
+        if (systemSegments.length) {
+            metadata.systemInstructions = systemSegments;
+        }
+        if (payload.system !== undefined) {
+            metadata.rawSystem = jsonClone(payload.system);
+        }
+        if (payload.tools && Array.isArray(payload.tools) && payload.tools.length === 0) {
+            metadata.toolsFieldPresent = true;
+        }
+        if (missing.length) {
+            metadata.missingFields = missing;
+        }
+        const extraFields = collectExtraFields(payload);
+        if (extraFields) {
+            metadata.extraFields = extraFields;
+        }
+        if (passthrough.metadata) {
+            metadata.providerMetadata = passthrough.metadata;
+        }
+        else if (payload.metadata && isJsonObject(payload.metadata)) {
+            metadata.providerMetadata = jsonClone(payload.metadata);
+        }
+        return {
+            messages,
+            tools,
+            toolOutputs,
+            parameters,
+            metadata
+        };
+    }
+    async fromChat(chat, ctx) {
+        const model = chat.parameters?.model;
+        if (typeof model !== 'string' || !model.trim()) {
+            throw new Error('ChatEnvelope.parameters.model is required for anthropic-messages outbound conversion');
+        }
+        const baseRequest = {
+            ...(chat.parameters || {}),
+            model,
+            messages: chat.metadata?.systemInstructions ? chat.messages.filter(message => message.role !== 'system') : chat.messages,
+            tools: chat.tools
+        };
+        const passthroughMetadata = encodePassthroughParameters(chat);
+        if (passthroughMetadata) {
+            const rawMetadata = baseRequest.metadata;
+            const existingMetadata = isJsonObject(rawMetadata)
+                ? jsonClone(rawMetadata)
+                : {};
+            for (const [key, value] of Object.entries(passthroughMetadata)) {
+                existingMetadata[key] = value;
+            }
+            baseRequest.metadata = existingMetadata;
+        }
+        if (baseRequest.max_output_tokens && !baseRequest.max_tokens) {
+            baseRequest.max_tokens = baseRequest.max_output_tokens;
+        }
+        const systemSegmentsRaw = Array.isArray(chat.metadata?.systemInstructions)
+            ? chat.metadata?.systemInstructions
+            : undefined;
+        const systemSegments = systemSegmentsRaw?.filter((seg) => typeof seg === 'string' && seg.trim().length > 0);
+        if (chat.metadata?.rawSystem !== undefined) {
+            baseRequest.system = chat.metadata.rawSystem;
+        }
+        else if (systemSegments && systemSegments.length > 0) {
+            baseRequest.system = systemSegmentsToAnthropicBlocks(systemSegments);
+        }
+        if (isJsonObject(chat.metadata?.providerMetadata)) {
+            baseRequest.metadata = jsonClone(chat.metadata?.providerMetadata);
+        }
+        if (chat.metadata?.toolsFieldPresent && (!Array.isArray(chat.tools) || chat.tools.length === 0)) {
+            baseRequest.tools = [];
+        }
+        if (isJsonObject(chat.metadata?.extraFields)) {
+            for (const [key, value] of Object.entries(chat.metadata?.extraFields)) {
+                if (baseRequest[key] === undefined) {
+                    baseRequest[key] = value;
+                }
+            }
+        }
+        const payload = buildAnthropicRequestFromOpenAIChat(baseRequest);
+        if (chat.metadata?.rawSystem !== undefined) {
+            payload.system = chat.metadata.rawSystem;
+        }
+        if (chat.metadata?.toolsFieldPresent && (!Array.isArray(chat.tools) || chat.tools.length === 0)) {
+            payload.tools = [];
+        }
+        if (isJsonObject(chat.metadata?.extraFields)) {
+            for (const [key, value] of Object.entries(chat.metadata?.extraFields)) {
+                if (payload[key] === undefined) {
+                    payload[key] = value;
+                }
+            }
+        }
+        return {
+            protocol: 'anthropic-messages',
+            direction: 'response',
+            payload,
+            meta: {
+                context: ctx
+            }
+        };
+    }
+}

package/dist/conversion/hub/semantic-mappers/chat-mapper.d.ts

@@ -0,0 +1,7 @@
+import type { SemanticMapper } from '../format-adapters/index.js';
+import type { AdapterContext, ChatEnvelope } from '../types/chat-envelope.js';
+import type { FormatEnvelope } from '../types/format-envelope.js';
+export declare class ChatSemanticMapper implements SemanticMapper {
+    toChat(format: FormatEnvelope, ctx: AdapterContext): Promise<ChatEnvelope>;
+    fromChat(chat: ChatEnvelope, ctx: AdapterContext): Promise<FormatEnvelope>;
+}

package/dist/conversion/hub/semantic-mappers/chat-mapper.js

@@ -0,0 +1,304 @@
+import { isJsonObject, jsonClone } from '../types/json.js';
+const CHAT_PARAMETER_KEYS = [
+    'model',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'frequency_penalty',
+    'presence_penalty',
+    'logit_bias',
+    'response_format',
+    'parallel_tool_calls',
+    'tool_choice',
+    'seed',
+    'user',
+    'metadata',
+    'stop',
+    'stop_sequences',
+    'stream'
+];
+const KNOWN_TOP_LEVEL_FIELDS = new Set([
+    'messages',
+    'tools',
+    'tool_outputs',
+    ...CHAT_PARAMETER_KEYS
+]);
+function flattenSystemContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content.map(flattenSystemContent).filter(Boolean).join('\n');
+    }
+    if (content && typeof content === 'object') {
+        const obj = content;
+        if (typeof obj.text === 'string')
+            return obj.text;
+        if (typeof obj.content === 'string')
+            return obj.content;
+        if (Array.isArray(obj.content))
+            return obj.content.map(flattenSystemContent).join('\n');
+    }
+    return '';
+}
+function normalizeToolContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content === null || content === undefined)
+        return '';
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content ?? '');
+    }
+}
+function collectSystemRawBlocks(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const blocks = [];
+    const pushText = (text) => {
+        if (typeof text === 'string' && text.trim().length) {
+            blocks.push({ type: 'text', text });
+        }
+    };
+    raw.forEach((entry) => {
+        if (!isJsonObject(entry))
+            return;
+        if (entry.role !== 'system')
+            return;
+        const content = entry.content;
+        if (typeof content === 'string') {
+            pushText(content);
+            return;
+        }
+        if (Array.isArray(content)) {
+            content.forEach((part) => {
+                if (typeof part === 'string') {
+                    pushText(part);
+                }
+                else if (isJsonObject(part) && typeof part.text === 'string') {
+                    pushText(part.text);
+                }
+            });
+            return;
+        }
+        if (isJsonObject(content) && typeof content.text === 'string') {
+            pushText(content.text);
+        }
+    });
+    return blocks.length ? blocks : undefined;
+}
+function normalizeChatMessages(raw) {
+    const norm = {
+        messages: [],
+        systemSegments: [],
+        toolOutputs: [],
+        missingFields: []
+    };
+    if (raw === undefined) {
+        norm.missingFields.push({ path: 'messages', reason: 'absent' });
+        return norm;
+    }
+    if (!Array.isArray(raw)) {
+        norm.missingFields.push({ path: 'messages', reason: 'invalid_type', originalValue: jsonClone(raw) });
+        return norm;
+    }
+    raw.forEach((value, index) => {
+        if (!isJsonObject(value)) {
+            norm.missingFields.push({ path: `messages[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(value) });
+            return;
+        }
+        const roleValue = value.role;
+        if (typeof roleValue !== 'string') {
+            norm.missingFields.push({ path: `messages[${index}].role`, reason: 'missing_role' });
+            return;
+        }
+        const chatMessage = value;
+        norm.messages.push(chatMessage);
+        if (roleValue === 'system') {
+            const segment = flattenSystemContent(chatMessage.content);
+            if (segment.trim().length) {
+                norm.systemSegments.push(segment);
+            }
+            return;
+        }
+        if (roleValue === 'tool') {
+            const rawCallId = (value.tool_call_id ?? value.call_id ?? value.id);
+            const toolCallId = typeof rawCallId === 'string' && rawCallId.trim().length ? rawCallId.trim() : undefined;
+            if (!toolCallId) {
+                norm.missingFields.push({ path: `messages[${index}].tool_call_id`, reason: 'missing_tool_call_id' });
+                return;
+            }
+            const outputEntry = {
+                tool_call_id: toolCallId,
+                content: normalizeToolContent(value.content ?? value.output),
+                name: typeof value.name === 'string' && value.name.trim().length ? value.name : undefined
+            };
+            norm.toolOutputs.push(outputEntry);
+        }
+    });
+    return norm;
+}
+function normalizeStandaloneToolOutputs(raw, missing) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return [];
+    const outputs = [];
+    raw.forEach((entry, index) => {
+        if (!isJsonObject(entry)) {
+            missing.push({ path: `tool_outputs[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(entry) });
+            return;
+        }
+        const rawCallId = entry.tool_call_id ?? entry.call_id ?? entry.id;
+        const toolCallId = typeof rawCallId === 'string' && rawCallId.trim().length ? rawCallId.trim() : undefined;
+        if (!toolCallId) {
+            missing.push({ path: `tool_outputs[${index}].tool_call_id`, reason: 'missing_tool_call_id' });
+            return;
+        }
+        outputs.push({
+            tool_call_id: toolCallId,
+            content: normalizeToolContent(entry.content ?? entry.output),
+            name: typeof entry.name === 'string' && entry.name.trim().length ? entry.name : undefined
+        });
+    });
+    return outputs;
+}
+function normalizeTools(raw, missing) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const tools = [];
+    raw.forEach((entry, index) => {
+        if (!isJsonObject(entry)) {
+            missing.push({ path: `tools[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(entry) });
+            return;
+        }
+        tools.push(entry);
+    });
+    return tools.length ? tools : undefined;
+}
+function extractParameters(body) {
+    const params = {};
+    for (const key of CHAT_PARAMETER_KEYS) {
+        if (body[key] !== undefined) {
+            params[key] = body[key];
+        }
+    }
+    return Object.keys(params).length ? params : undefined;
+}
+function collectExtraFields(payload) {
+    const extras = {};
+    for (const key of Object.keys(payload)) {
+        if (KNOWN_TOP_LEVEL_FIELDS.has(key))
+            continue;
+        extras[key] = payload[key];
+    }
+    return Object.keys(extras).length ? extras : undefined;
+}
+export class ChatSemanticMapper {
+    async toChat(format, ctx) {
+        const payload = (format.payload ?? {});
+        const normalized = normalizeChatMessages(payload.messages);
+        const rawSystemSentinel = payload.__rcc_raw_system;
+        const providerMetadataSentinel = payload.__rcc_provider_metadata;
+        if (rawSystemSentinel !== undefined) {
+            delete payload.__rcc_raw_system;
+        }
+        if (providerMetadataSentinel !== undefined) {
+            delete payload.__rcc_provider_metadata;
+        }
+        const topLevelOutputs = normalizeStandaloneToolOutputs(payload.tool_outputs, normalized.missingFields);
+        const toolOutputs = [...normalized.toolOutputs];
+        for (const entry of topLevelOutputs) {
+            if (!toolOutputs.find(item => item.tool_call_id === entry.tool_call_id)) {
+                toolOutputs.push(entry);
+            }
+        }
+        const metadata = { context: ctx };
+        if (typeof rawSystemSentinel === 'string') {
+            try {
+                metadata.rawSystem = JSON.parse(rawSystemSentinel);
+            }
+            catch {
+                // ignore parse errors
+            }
+        }
+        if (typeof providerMetadataSentinel === 'string') {
+            try {
+                metadata.providerMetadata = JSON.parse(providerMetadataSentinel);
+            }
+            catch {
+                // ignore parse errors
+            }
+        }
+        if (normalized.systemSegments.length) {
+            metadata.systemInstructions = normalized.systemSegments;
+        }
+        const rawSystemBlocks = collectSystemRawBlocks(payload.messages);
+        if (!metadata.rawSystem && rawSystemBlocks) {
+            metadata.rawSystem = rawSystemBlocks;
+        }
+        if (normalized.missingFields.length) {
+            metadata.missingFields = normalized.missingFields;
+        }
+        const extraFields = collectExtraFields(payload);
+        if (extraFields) {
+            metadata.extraFields = extraFields;
+        }
+        if (Array.isArray(payload.tools) && payload.tools.length === 0) {
+            metadata.toolsFieldPresent = true;
+        }
+        return {
+            messages: normalized.messages,
+            tools: normalizeTools(payload.tools, normalized.missingFields),
+            toolOutputs: toolOutputs.length ? toolOutputs : undefined,
+            parameters: extractParameters(payload),
+            metadata
+        };
+    }
+    async fromChat(chat, ctx) {
+        const payload = {
+            messages: chat.messages,
+            tools: chat.tools ?? (chat.metadata?.toolsFieldPresent ? [] : undefined),
+            ...(chat.parameters || {})
+        };
+        if (chat.metadata?.rawSystem !== undefined) {
+            try {
+                payload.__rcc_raw_system = JSON.stringify(chat.metadata.rawSystem);
+            }
+            catch {
+                // ignore serialization errors
+            }
+        }
+        if (chat.metadata?.providerMetadata && isJsonObject(chat.metadata.providerMetadata)) {
+            try {
+                payload.__rcc_provider_metadata = JSON.stringify(chat.metadata.providerMetadata);
+            }
+            catch {
+                // ignore serialization errors
+            }
+        }
+        if (chat.toolOutputs?.length) {
+            payload.tool_outputs = chat.toolOutputs;
+        }
+        if (payload.max_tokens === undefined && typeof payload.max_output_tokens === 'number') {
+            payload.max_tokens = payload.max_output_tokens;
+            delete payload.max_output_tokens;
+        }
+        const extraFields = chat.metadata?.extraFields;
+        if (isJsonObject(extraFields)) {
+            for (const [key, value] of Object.entries(extraFields)) {
+                if (payload[key] === undefined) {
+                    payload[key] = value;
+                }
+            }
+        }
+        return {
+            protocol: 'openai-chat',
+            direction: 'response',
+            payload,
+            meta: {
+                context: ctx
+            }
+        };
+    }
+}

package/dist/conversion/hub/semantic-mappers/gemini-mapper.d.ts

@@ -0,0 +1,7 @@
+import type { SemanticMapper } from '../format-adapters/index.js';
+import type { AdapterContext, ChatEnvelope } from '../types/chat-envelope.js';
+import type { FormatEnvelope } from '../types/format-envelope.js';
+export declare class GeminiSemanticMapper implements SemanticMapper {
+    toChat(format: FormatEnvelope, ctx: AdapterContext): Promise<ChatEnvelope>;
+    fromChat(chat: ChatEnvelope, ctx: AdapterContext): Promise<FormatEnvelope>;
+}