@jsonstudio/llms 0.4.2

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

@@ -0,0 +1,477 @@
+import { isJsonObject, jsonClone } from '../types/json.js';
+import { buildOpenAIChatFromGeminiRequest } from '../../codecs/gemini-openai-codec.js';
+const GENERATION_CONFIG_KEYS = [
+    { source: 'temperature', target: 'temperature' },
+    { source: 'topP', target: 'top_p' },
+    { source: 'topK', target: 'top_k' },
+    { source: 'maxOutputTokens', target: 'max_output_tokens' },
+    { source: 'candidateCount', target: 'candidate_count' },
+    { source: 'responseMimeType', target: 'response_mime_type' },
+    { source: 'stopSequences', target: 'stop_sequences' }
+];
+const GEMINI_TOP_LEVEL_FIELDS = new Set([
+    'model',
+    'contents',
+    'tools',
+    'systemInstruction',
+    'generationConfig',
+    'safetySettings',
+    'metadata',
+    'toolConfig'
+]);
+const PASSTHROUGH_METADATA_PREFIX = 'rcc_passthrough_';
+const PASSTHROUGH_PARAMETERS = ['tool_choice'];
+function encodePassthroughParametersFromChat(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 extractPassthroughParametersFromMetadata(metadataField) {
+    if (!metadataField)
+        return {};
+    const cloned = jsonClone(metadataField);
+    const passthrough = {};
+    let mutated = 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];
+            mutated = true;
+        }
+        catch {
+            continue;
+        }
+    }
+    return {
+        cleaned: mutated ? (Object.keys(cloned).length ? cloned : undefined) : cloned,
+        passthrough: Object.keys(passthrough).length ? passthrough : undefined
+    };
+}
+function normalizeToolOutputs(messages, missing) {
+    const outputs = [];
+    messages.forEach((msg, index) => {
+        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 normalizeToolContent(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value == null)
+        return '';
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value ?? '');
+    }
+}
+function collectSystemSegments(systemInstruction) {
+    if (!systemInstruction)
+        return [];
+    const flatten = (val) => {
+        if (typeof val === 'string')
+            return val;
+        if (Array.isArray(val))
+            return val.map((entry) => flatten(entry)).filter(Boolean).join('\n');
+        if (val && typeof val === 'object') {
+            const text = val.text;
+            if (typeof text === 'string')
+                return text;
+            const parts = val.parts;
+            if (Array.isArray(parts))
+                return parts.map((entry) => flatten(entry)).filter(Boolean).join('\n');
+        }
+        return '';
+    };
+    const text = flatten(systemInstruction).trim();
+    return text ? [text] : [];
+}
+function normalizeGeminiTools(rawTools, missing) {
+    if (!rawTools)
+        return undefined;
+    const arr = Array.isArray(rawTools) ? rawTools : [rawTools];
+    const tools = [];
+    arr.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object') {
+            missing.push({ path: `tools[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(entry) });
+            return;
+        }
+        const obj = entry;
+        const declarations = Array.isArray(obj.functionDeclarations) ? obj.functionDeclarations : undefined;
+        if (declarations && declarations.length) {
+            declarations.forEach((decl, declIndex) => {
+                if (!decl || typeof decl !== 'object') {
+                    missing.push({ path: `tools[${index}].functionDeclarations[${declIndex}]`, reason: 'invalid_entry' });
+                    return;
+                }
+                const def = decl;
+                const name = typeof def.name === 'string' ? def.name : undefined;
+                if (!name)
+                    return;
+                tools.push({
+                    type: 'function',
+                    function: {
+                        name,
+                        description: typeof def.description === 'string' ? def.description : undefined,
+                        parameters: isJsonObject(def.parameters) ? jsonClone(def.parameters) : { type: 'object', properties: {} }
+                    }
+                });
+            });
+            return;
+        }
+        const name = typeof obj.name === 'string' ? obj.name : undefined;
+        if (!name)
+            return;
+        tools.push({
+            type: 'function',
+            function: {
+                name,
+                description: typeof obj.description === 'string' ? obj.description : undefined,
+                parameters: isJsonObject(obj.parameters) ? jsonClone(obj.parameters) : { type: 'object', properties: {} }
+            }
+        });
+    });
+    return tools.length ? tools : undefined;
+}
+function collectParameters(payload) {
+    const params = {};
+    if (typeof payload.model === 'string') {
+        params.model = payload.model;
+    }
+    const gen = payload.generationConfig;
+    if (gen && typeof gen === 'object') {
+        for (const { source, target } of GENERATION_CONFIG_KEYS) {
+            const value = gen[source];
+            if (value !== undefined) {
+                params[target] = value;
+            }
+        }
+    }
+    if (payload.toolConfig !== undefined) {
+        params.tool_config = jsonClone(payload.toolConfig);
+    }
+    const meta = payload.metadata;
+    if (meta && typeof meta === 'object' && Object.prototype.hasOwnProperty.call(meta, '__rcc_stream')) {
+        params.stream = Boolean(meta.__rcc_stream);
+    }
+    return Object.keys(params).length ? params : undefined;
+}
+function collectExtraFields(payload) {
+    const extras = {};
+    for (const key of Object.keys(payload)) {
+        if (GEMINI_TOP_LEVEL_FIELDS.has(key))
+            continue;
+        extras[key] = payload[key];
+    }
+    return Object.keys(extras).length ? extras : undefined;
+}
+function buildGeminiRequestFromChat(chat, metadata) {
+    const contents = [];
+    for (const message of chat.messages) {
+        if (!message || typeof message !== 'object')
+            continue;
+        if (message.role === 'system')
+            continue;
+        if (message.role === 'tool')
+            continue;
+        const entry = {
+            role: mapChatRoleToGemini(message.role),
+            parts: []
+        };
+        if (typeof message.content === 'string' && message.content.trim().length) {
+            entry.parts.push({ text: message.content });
+        }
+        const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+        for (const tc of toolCalls) {
+            if (!tc || typeof tc !== 'object')
+                continue;
+            const fn = tc.function || {};
+            const name = typeof fn.name === 'string' ? fn.name : undefined;
+            if (!name)
+                continue;
+            let argsStruct;
+            if (typeof fn.arguments === 'string') {
+                try {
+                    argsStruct = JSON.parse(fn.arguments);
+                }
+                catch {
+                    argsStruct = { _raw: fn.arguments };
+                }
+            }
+            else {
+                argsStruct = fn.arguments ?? {};
+            }
+            const part = { functionCall: { name, args: cloneAsJsonValue(argsStruct) } };
+            if (typeof tc.id === 'string') {
+                part.functionCall.id = tc.id;
+            }
+            entry.parts.push(part);
+        }
+        if (entry.parts.length) {
+            contents.push(entry);
+        }
+    }
+    if (Array.isArray(chat.toolOutputs)) {
+        for (const output of chat.toolOutputs) {
+            const response = cloneAsJsonValue(safeParseJson(output.content));
+            const part = {
+                functionResponse: {
+                    name: output.name || 'tool',
+                    id: output.tool_call_id,
+                    response
+                }
+            };
+            contents.push({ role: 'user', parts: [part] });
+        }
+    }
+    const request = {
+        model: chat.parameters?.model || 'models/gemini-pro',
+        contents
+    };
+    if (metadata?.rawSystem && isJsonObject(metadata.rawSystem) && String(metadata.rawSystem.role || '').toLowerCase() === 'system') {
+        request.systemInstruction = metadata.rawSystem;
+    }
+    else if (metadata?.rawSystemInstruction !== undefined) {
+        request.systemInstruction = metadata.rawSystemInstruction;
+    }
+    else if (metadata?.systemInstructions && Array.isArray(metadata.systemInstructions)) {
+        const sysBlocks = metadata.systemInstructions
+            .filter((value) => typeof value === 'string' && value.trim().length > 0)
+            .map((value) => ({ text: value }));
+        if (sysBlocks.length) {
+            request.systemInstruction = { role: 'system', parts: sysBlocks };
+        }
+    }
+    if (chat.tools && chat.tools.length) {
+        request.tools = buildGeminiToolsFromChat(chat.tools);
+    }
+    const generationConfig = buildGenerationConfigFromParameters(chat.parameters || {});
+    if (Object.keys(generationConfig).length) {
+        request.generationConfig = generationConfig;
+    }
+    if (metadata?.extraFields && isJsonObject(metadata.extraFields)) {
+        for (const [key, value] of Object.entries(metadata.extraFields)) {
+            if (request[key] === undefined) {
+                request[key] = value;
+            }
+        }
+    }
+    if (metadata?.providerMetadata && isJsonObject(metadata.providerMetadata)) {
+        request.metadata = jsonClone(metadata.providerMetadata);
+    }
+    if (chat.parameters && chat.parameters.stream !== undefined) {
+        request.metadata = request.metadata ?? {};
+        request.metadata.__rcc_stream = chat.parameters.stream;
+    }
+    if (metadata?.rawSystem !== undefined) {
+        request.metadata = request.metadata ?? {};
+        try {
+            request.metadata.__rcc_raw_system = JSON.stringify(metadata.rawSystem);
+        }
+        catch {
+            // ignore serialization errors
+        }
+    }
+    if (chat.metadata?.toolsFieldPresent && (!Array.isArray(chat.tools) || chat.tools.length === 0)) {
+        request.metadata = request.metadata ?? {};
+        request.metadata.__rcc_tools_field_present = '1';
+    }
+    const passthrough = encodePassthroughParametersFromChat(chat);
+    if (passthrough) {
+        request.metadata = request.metadata ?? {};
+        for (const [key, value] of Object.entries(passthrough)) {
+            request.metadata[key] = value;
+        }
+    }
+    return request;
+}
+function buildGeminiToolsFromChat(tools) {
+    const geminiTools = [];
+    tools.forEach((tool) => {
+        if (!tool || tool.type !== 'function')
+            return;
+        const fn = tool.function;
+        if (!fn || typeof fn.name !== 'string')
+            return;
+        geminiTools.push({
+            functionDeclarations: [
+                {
+                    name: fn.name,
+                    description: fn.description,
+                    parameters: cloneAsJsonValue(fn.parameters ?? { type: 'object', properties: {} })
+                }
+            ]
+        });
+    });
+    return geminiTools;
+}
+function buildGenerationConfigFromParameters(parameters) {
+    const config = {};
+    for (const { source, target } of GENERATION_CONFIG_KEYS) {
+        const value = parameters[target] ?? (target === 'max_output_tokens' ? parameters.max_tokens : undefined);
+        if (value !== undefined) {
+            config[source] = value;
+        }
+    }
+    return config;
+}
+function mapChatRoleToGemini(role) {
+    const r = role.toLowerCase();
+    if (r === 'assistant')
+        return 'model';
+    if (r === 'system')
+        return 'system';
+    if (r === 'tool')
+        return 'tool';
+    return 'user';
+}
+function safeParseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function cloneAsJsonValue(value) {
+    try {
+        return JSON.parse(JSON.stringify(value ?? null));
+    }
+    catch {
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            return value.map((entry) => cloneAsJsonValue(entry));
+        }
+        if (value && typeof value === 'object') {
+            const out = {};
+            for (const [key, entry] of Object.entries(value)) {
+                out[key] = cloneAsJsonValue(entry);
+            }
+            return out;
+        }
+        return String(value ?? '');
+    }
+}
+export class GeminiSemanticMapper {
+    async toChat(format, ctx) {
+        const payload = (format.payload ?? {});
+        const missing = [];
+        const { messages } = buildOpenAIChatFromGeminiRequest(payload);
+        if (!Array.isArray(payload.contents)) {
+            missing.push({ path: 'contents', reason: 'absent' });
+        }
+        const toolOutputs = normalizeToolOutputs(messages, missing);
+        const tools = payload.tools ? normalizeGeminiTools(payload.tools, missing) : undefined;
+        let parameters = collectParameters(payload);
+        const metadata = { context: ctx };
+        const systemSegments = collectSystemSegments(payload.systemInstruction);
+        if (systemSegments.length) {
+            metadata.systemInstructions = systemSegments;
+        }
+        if (payload.systemInstruction !== undefined) {
+            const rawSystem = jsonClone(payload.systemInstruction);
+            metadata.rawSystemInstruction = rawSystem;
+            metadata.rawSystem = rawSystem;
+        }
+        if (payload.safetySettings) {
+            metadata.safetySettings = jsonClone(payload.safetySettings);
+        }
+        if (missing.length) {
+            metadata.missingFields = missing;
+        }
+        const extraFields = collectExtraFields(payload);
+        if (extraFields) {
+            metadata.extraFields = extraFields;
+        }
+        const passthrough = extractPassthroughParametersFromMetadata(payload.metadata);
+        if (passthrough.passthrough) {
+            parameters = { ...(parameters || {}), ...passthrough.passthrough };
+        }
+        const providerMetadataSource = passthrough.cleaned ?? payload.metadata;
+        if (providerMetadataSource) {
+            const providerMetadata = jsonClone(providerMetadataSource);
+            let toolsFieldPresent = false;
+            let rawSystemValue;
+            if (isJsonObject(providerMetadata)) {
+                delete providerMetadata.__rcc_stream;
+                if (Object.prototype.hasOwnProperty.call(providerMetadata, '__rcc_tools_field_present')) {
+                    const sentinel = providerMetadata.__rcc_tools_field_present;
+                    toolsFieldPresent = sentinel === '1' || sentinel === true;
+                    delete providerMetadata.__rcc_tools_field_present;
+                }
+                if (Object.prototype.hasOwnProperty.call(providerMetadata, '__rcc_raw_system')) {
+                    const rawSystemSentinel = providerMetadata.__rcc_raw_system;
+                    delete providerMetadata.__rcc_raw_system;
+                    if (typeof rawSystemSentinel === 'string') {
+                        try {
+                            rawSystemValue = JSON.parse(rawSystemSentinel);
+                        }
+                        catch {
+                            rawSystemValue = undefined;
+                        }
+                    }
+                }
+            }
+            if (toolsFieldPresent) {
+                metadata.toolsFieldPresent = true;
+            }
+            if (rawSystemValue !== undefined) {
+                metadata.rawSystem = rawSystemValue;
+            }
+            metadata.providerMetadata = providerMetadata;
+        }
+        return {
+            messages,
+            tools,
+            toolOutputs,
+            parameters,
+            metadata
+        };
+    }
+    async fromChat(chat, ctx) {
+        const envelopePayload = buildGeminiRequestFromChat(chat, chat.metadata);
+        return {
+            protocol: 'gemini-chat',
+            direction: 'response',
+            payload: envelopePayload,
+            meta: {
+                context: ctx
+            }
+        };
+    }
+}

package/dist/conversion/hub/semantic-mappers/index.d.ts

@@ -0,0 +1,4 @@
+export { ChatSemanticMapper } from './chat-mapper.js';
+export { AnthropicSemanticMapper } from './anthropic-mapper.js';
+export { ResponsesSemanticMapper } from './responses-mapper.js';
+export { GeminiSemanticMapper } from './gemini-mapper.js';

package/dist/conversion/hub/semantic-mappers/index.js

@@ -0,0 +1,4 @@
+export { ChatSemanticMapper } from './chat-mapper.js';
+export { AnthropicSemanticMapper } from './anthropic-mapper.js';
+export { ResponsesSemanticMapper } from './responses-mapper.js';
+export { GeminiSemanticMapper } from './gemini-mapper.js';

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

@@ -0,0 +1,21 @@
+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';
+import { type JsonObject, type JsonValue } from '../types/json.js';
+interface ResponsesToolOutputEntry extends JsonObject {
+    tool_call_id?: string;
+    call_id?: string;
+    id?: string;
+    output?: JsonValue;
+    name?: string;
+}
+interface ResponsesPayload extends JsonObject {
+    input?: JsonValue[];
+    tools?: JsonValue[];
+    tool_outputs?: ResponsesToolOutputEntry[];
+}
+export declare class ResponsesSemanticMapper implements SemanticMapper {
+    toChat(format: FormatEnvelope<ResponsesPayload>, ctx: AdapterContext): Promise<ChatEnvelope>;
+    fromChat(chat: ChatEnvelope, ctx: AdapterContext): Promise<FormatEnvelope>;
+}
+export {};