@jsonstudio/llms 0.4.3 → 0.4.5

package/dist/conversion/hub/tool-governance/engine.js

@@ -0,0 +1,266 @@
+import { DEFAULT_TOOL_GOVERNANCE_RULES } from './rules.js';
+export class ToolGovernanceError extends Error {
+    protocol;
+    direction;
+    field;
+    constructor(message, protocol, direction, field) {
+        super(message);
+        this.protocol = protocol;
+        this.direction = direction;
+        this.field = field;
+        this.name = 'ToolGovernanceError';
+    }
+}
+function normalizeProtocol(protocol) {
+    if (!protocol)
+        return 'openai-chat';
+    const normalized = String(protocol).toLowerCase();
+    if (normalized === 'anthropic-messages') {
+        return 'anthropic';
+    }
+    if (normalized === 'gemini-chat') {
+        return 'gemini';
+    }
+    if (normalized === 'responses' || normalized === 'openai-responses') {
+        return 'openai-responses';
+    }
+    if (normalized === 'openai-chat') {
+        return 'openai-chat';
+    }
+    return protocol;
+}
+export class ToolGovernanceEngine {
+    registry;
+    constructor(registry = DEFAULT_TOOL_GOVERNANCE_RULES) {
+        this.registry = registry;
+    }
+    governRequest(request, protocol) {
+        const rules = this.resolveRules(protocol, 'request');
+        if (!rules) {
+            return {
+                request,
+                summary: buildSummary(protocol, 'request', false)
+            };
+        }
+        const stats = createStats(protocol, 'request');
+        const sanitizedMessages = request.messages.map((msg) => sanitizeStandardizedMessage(msg, rules, stats));
+        const sanitizedTools = request.tools?.map((tool) => sanitizeStandardizedTool(tool, rules, stats));
+        const governed = {
+            ...request,
+            messages: sanitizedMessages,
+            tools: sanitizedTools,
+            metadata: {
+                ...request.metadata,
+                toolGovernance: {
+                    ...request.metadata?.toolGovernance,
+                    request: finalizeSummary(stats)
+                }
+            }
+        };
+        return {
+            request: governed,
+            summary: finalizeSummary(stats)
+        };
+    }
+    governResponse(payload, protocol) {
+        const rules = this.resolveRules(protocol, 'response');
+        if (!rules) {
+            return {
+                payload,
+                summary: buildSummary(protocol, 'response', false)
+            };
+        }
+        const stats = createStats(protocol, 'response');
+        const cloned = JSON.parse(JSON.stringify(payload));
+        const choices = Array.isArray(cloned?.choices) ? cloned.choices : [];
+        for (const choice of choices) {
+            sanitizeChatCompletionChoice(choice, rules, stats);
+        }
+        if (Array.isArray(cloned?.tool_calls)) {
+            cloned.tool_calls = cloned.tool_calls.map((tc) => sanitizeChatCompletionToolCall(tc, rules, stats));
+        }
+        return {
+            payload: cloned,
+            summary: finalizeSummary(stats)
+        };
+    }
+    resolveRules(protocol, direction) {
+        const resolved = normalizeProtocol(protocol);
+        const entry = this.registry[resolved] ?? this.registry['openai-chat'];
+        return entry?.[direction];
+    }
+}
+function sanitizeStandardizedMessage(message, rules, stats) {
+    let changed = false;
+    const next = { ...message };
+    if (Array.isArray(message.tool_calls) && message.tool_calls.length) {
+        next.tool_calls = message.tool_calls.map((call) => sanitizeToolCall(call, rules, stats));
+        if (next.tool_calls !== message.tool_calls) {
+            changed = true;
+        }
+    }
+    if (typeof message.name === 'string' || message.role === 'tool') {
+        const sanitizedName = sanitizeName(message.name, rules, stats, 'message.name');
+        if (sanitizedName !== message.name) {
+            next.name = sanitizedName;
+            changed = true;
+        }
+    }
+    return changed ? next : message;
+}
+function sanitizeStandardizedTool(tool, rules, stats) {
+    const sanitizedName = sanitizeName(tool.function?.name, rules, stats, 'tool.function.name');
+    if (sanitizedName === tool.function?.name) {
+        return tool;
+    }
+    return {
+        ...tool,
+        function: {
+            ...tool.function,
+            name: sanitizedName
+        }
+    };
+}
+function sanitizeToolCall(call, rules, stats) {
+    if (!call?.function) {
+        return call;
+    }
+    const sanitizedName = sanitizeName(call.function.name, rules, stats, 'tool_call.function.name');
+    if (sanitizedName === call.function.name) {
+        return call;
+    }
+    return {
+        ...call,
+        function: {
+            ...call.function,
+            name: sanitizedName
+        }
+    };
+}
+function sanitizeChatCompletionChoice(choice, rules, stats) {
+    const message = choice?.message;
+    if (!message || typeof message !== 'object') {
+        return;
+    }
+    const msg = message;
+    if (Array.isArray(msg.tool_calls)) {
+        msg.tool_calls = msg.tool_calls.map((tc, index) => sanitizeChatCompletionToolCall(tc, rules, stats, `choices[].message.tool_calls[${index}].function.name`));
+    }
+    if (msg.function_call && typeof msg.function_call === 'object') {
+        const orig = msg.function_call.name;
+        const sanitizedName = sanitizeName(orig, rules, stats, 'choices[].message.function_call.name');
+        msg.function_call.name = sanitizedName;
+    }
+    if (typeof msg.name === 'string' || msg.role === 'tool') {
+        msg.name = sanitizeName(msg.name, rules, stats, 'choices[].message.name');
+    }
+}
+function sanitizeChatCompletionToolCall(tc, rules, stats, context = 'choices[].message.tool_calls[].function.name') {
+    if (!tc || typeof tc !== 'object') {
+        return tc;
+    }
+    const fn = tc.function;
+    if (!fn || typeof fn !== 'object') {
+        return tc;
+    }
+    const sanitizedName = sanitizeName(fn.name, rules, stats, context);
+    if (sanitizedName === fn.name) {
+        return tc;
+    }
+    return {
+        ...tc,
+        function: {
+            ...fn,
+            name: sanitizedName
+        }
+    };
+}
+function createStats(protocol, direction) {
+    return {
+        protocol,
+        direction,
+        applied: false,
+        sanitizedNames: 0,
+        truncatedNames: 0,
+        defaultedNames: 0
+    };
+}
+function sanitizeName(rawName, rules, stats, field) {
+    const defaultName = rules.defaultName ?? 'tool';
+    let next = typeof rawName === 'string' ? rawName : '';
+    let changed = false;
+    if (rules.trimWhitespace !== false) {
+        next = next.trim();
+    }
+    if (!next) {
+        next = defaultName;
+        stats.defaultedNames += 1;
+        changed = true;
+    }
+    if (rules.forceCase === 'lower') {
+        const forced = next.toLowerCase();
+        if (forced !== next) {
+            next = forced;
+            changed = true;
+        }
+    }
+    else if (rules.forceCase === 'upper') {
+        const forced = next.toUpperCase();
+        if (forced !== next) {
+            next = forced;
+            changed = true;
+        }
+    }
+    if (rules.allowedCharacters) {
+        const matcher = new RegExp(rules.allowedCharacters.source);
+        const filtered = next
+            .split('')
+            .filter((ch) => matcher.test(ch))
+            .join('');
+        matcher.lastIndex = 0;
+        if (filtered.length === 0) {
+            next = defaultName;
+            stats.defaultedNames += 1;
+            changed = true;
+        }
+        else if (filtered !== next) {
+            next = filtered;
+            changed = true;
+        }
+    }
+    if (rules.maxNameLength && next.length > rules.maxNameLength) {
+        if (rules.onViolation === 'reject') {
+            throw new ToolGovernanceError(`Tool name exceeds max length of ${rules.maxNameLength}`, stats.protocol, stats.direction, field);
+        }
+        next = next.slice(0, rules.maxNameLength);
+        stats.truncatedNames += 1;
+        changed = true;
+    }
+    if (changed || (typeof rawName === 'string' && rawName !== next)) {
+        stats.sanitizedNames += 1;
+    }
+    stats.applied = true;
+    return next || defaultName;
+}
+function finalizeSummary(stats) {
+    return {
+        protocol: stats.protocol,
+        direction: stats.direction,
+        applied: stats.applied,
+        sanitizedNames: stats.sanitizedNames,
+        truncatedNames: stats.truncatedNames,
+        defaultedNames: stats.defaultedNames,
+        timestamp: Date.now()
+    };
+}
+function buildSummary(protocol, direction, applied) {
+    return {
+        protocol,
+        direction,
+        applied,
+        sanitizedNames: 0,
+        truncatedNames: 0,
+        defaultedNames: 0,
+        timestamp: Date.now()
+    };
+}

package/dist/conversion/hub/tool-governance/index.d.ts

@@ -0,0 +1,3 @@
+export { ToolGovernanceEngine, ToolGovernanceError } from './engine.js';
+export { DEFAULT_TOOL_GOVERNANCE_RULES } from './rules.js';
+export type { ToolGovernanceProtocol, ToolGovernanceRules, ToolGovernanceRegistry, ToolGovernanceSummary } from './types.js';

package/dist/conversion/hub/tool-governance/index.js

@@ -0,0 +1,2 @@
+export { ToolGovernanceEngine, ToolGovernanceError } from './engine.js';
+export { DEFAULT_TOOL_GOVERNANCE_RULES } from './rules.js';

package/dist/conversion/hub/tool-governance/rules.d.ts

@@ -0,0 +1,2 @@
+import type { ToolGovernanceRegistry } from './types.js';
+export declare const DEFAULT_TOOL_GOVERNANCE_RULES: ToolGovernanceRegistry;

package/dist/conversion/hub/tool-governance/rules.js

@@ -0,0 +1,76 @@
+const ALPHA_NUMERIC = /[A-Za-z0-9_-]/;
+const LOWER_SNAKE = /[a-z0-9_-]/;
+function clonePattern(pattern) {
+    if (!pattern)
+        return undefined;
+    const flags = pattern.flags.replace(/g/g, '');
+    return new RegExp(pattern.source, flags);
+}
+export const DEFAULT_TOOL_GOVERNANCE_RULES = {
+    'openai-chat': {
+        request: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        },
+        response: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        }
+    },
+    'openai-responses': {
+        request: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        },
+        response: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        }
+    },
+    anthropic: {
+        request: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(LOWER_SNAKE),
+            forceCase: 'lower',
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        },
+        response: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(LOWER_SNAKE),
+            forceCase: 'lower',
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        }
+    },
+    gemini: {
+        request: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        },
+        response: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        }
+    }
+};

package/dist/conversion/hub/tool-governance/types.d.ts

@@ -0,0 +1,38 @@
+import type { JsonObject } from '../types/json.js';
+import type { StandardizedMessage, StandardizedRequest, StandardizedTool } from '../types/standardized.js';
+export type ToolGovernanceProtocol = 'openai-chat' | 'openai-responses' | 'anthropic' | 'gemini' | string;
+export type ToolGovernanceViolationMode = 'truncate' | 'reject';
+export interface ToolGovernanceRules {
+    maxNameLength?: number;
+    allowedCharacters?: RegExp;
+    forceCase?: 'lower' | 'upper';
+    defaultName?: string;
+    trimWhitespace?: boolean;
+    onViolation?: ToolGovernanceViolationMode;
+}
+export interface ToolGovernanceRegistryEntry {
+    request?: ToolGovernanceRules;
+    response?: ToolGovernanceRules;
+}
+export type ToolGovernanceRegistry = Record<ToolGovernanceProtocol, ToolGovernanceRegistryEntry>;
+export interface ToolGovernanceSummary {
+    protocol: ToolGovernanceProtocol;
+    direction: 'request' | 'response';
+    applied: boolean;
+    sanitizedNames: number;
+    truncatedNames: number;
+    defaultedNames: number;
+    timestamp: number;
+}
+export interface GovernedStandardizedRequest {
+    request: StandardizedRequest;
+    summary: ToolGovernanceSummary;
+}
+export interface GovernedChatCompletionPayload {
+    payload: JsonObject;
+    summary: ToolGovernanceSummary;
+}
+export type MutableStandardizedMessage = StandardizedMessage & {
+    tool_calls?: StandardizedMessage['tool_calls'];
+};
+export type MutableStandardizedTool = StandardizedTool;

package/dist/conversion/index.d.ts

@@ -7,6 +7,7 @@ export * from './hub/registry.js';
 export * from './hub/pipelines/inbound.js';
 export * from './hub/pipelines/outbound.js';
 export * from './hub/response/provider-response.js';
+export * from './hub/response/response-runtime.js';
 export * from './hub/pipeline/hub-pipeline.js';
 export * from './hub/format-adapters/index.js';
 export * from './hub/semantic-mappers/index.js';
@@ -26,3 +27,8 @@ export { governTools } from './shared/tool-governor.js';
 export * from './shared/streaming-text-extractor.js';
 export * from './shared/tool-harvester.js';
 export * from './responses/responses-openai-bridge.js';
+export { ProtocolConversionPipeline, PipelineValidationError, type ProtocolInboundPipelineOptions, type ProtocolInboundPipelineResult, type ProtocolOutboundPipelineOptions, type ProtocolOutboundPipelineResult } from './pipeline/index.js';
+export * from './pipeline/schema/index.js';
+export * from './pipeline/hooks/protocol-hooks.js';
+export * from './pipeline/hooks/adapter-context.js';
+export * from './pipeline/meta/meta-bag.js';

package/dist/conversion/index.js

@@ -7,6 +7,7 @@ export * from './hub/registry.js';
 export * from './hub/pipelines/inbound.js';
 export * from './hub/pipelines/outbound.js';
 export * from './hub/response/provider-response.js';
+export * from './hub/response/response-runtime.js';
 export * from './hub/pipeline/hub-pipeline.js';
 export * from './hub/format-adapters/index.js';
 export * from './hub/semantic-mappers/index.js';
@@ -26,3 +27,8 @@ export { governTools } from './shared/tool-governor.js';
 export * from './shared/streaming-text-extractor.js';
 export * from './shared/tool-harvester.js';
 export * from './responses/responses-openai-bridge.js';
+export { ProtocolConversionPipeline, PipelineValidationError } from './pipeline/index.js';
+export * from './pipeline/schema/index.js';
+export * from './pipeline/hooks/protocol-hooks.js';
+export * from './pipeline/hooks/adapter-context.js';
+export * from './pipeline/meta/meta-bag.js';

package/dist/conversion/pipeline/codecs/v2/anthropic-openai-pipeline.d.ts

@@ -0,0 +1,12 @@
+import type { ConversionCodec, ConversionContext, ConversionProfile } from '../../../types.js';
+import type { JsonObject } from '../../../hub/types/json.js';
+export declare class AnthropicOpenAIPipelineCodec implements ConversionCodec {
+    readonly id = "anthropic-openai-v2";
+    private readonly pipeline;
+    private initialized;
+    constructor();
+    initialize(): Promise<void>;
+    private ensureInitialized;
+    convertRequest(payload: unknown, profile: ConversionProfile, context: ConversionContext): Promise<JsonObject>;
+    convertResponse(payload: unknown, profile: ConversionProfile, context: ConversionContext): Promise<JsonObject>;
+}

package/dist/conversion/pipeline/codecs/v2/anthropic-openai-pipeline.js

@@ -0,0 +1,100 @@
+import { ProtocolConversionPipeline } from '../../index.js';
+import { chatEnvelopeToStandardized } from '../../../hub/standardized-bridge.js';
+import { AnthropicFormatAdapter } from '../../../hub/format-adapters/anthropic-format-adapter.js';
+import { AnthropicSemanticMapper } from '../../../hub/semantic-mappers/anthropic-mapper.js';
+import { buildAnthropicFromOpenAIChat } from '../../../codecs/anthropic-openai-codec.js';
+import { buildAdapterContextFromPipeline } from '../../hooks/adapter-context.js';
+import { runStandardChatRequestFilters } from '../../../index.js';
+import { canonicalizeOpenAIChatResponse, convertStandardizedToOpenAIChat as convertCanonicalToOpenAIChat, OPENAI_PROTOCOL } from './shared/openai-chat-helpers.js';
+const DEFAULT_ANTHROPIC_ENDPOINT = '/v1/messages';
+const ANTHROPIC_PROTOCOL = 'anthropic-messages';
+function assertJsonObject(value, stage) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Anthropic pipeline codec requires JSON object payload at ${stage}`);
+    }
+    return value;
+}
+function createAnthropicHooks() {
+    const formatAdapter = new AnthropicFormatAdapter();
+    const semanticMapper = new AnthropicSemanticMapper();
+    return {
+        id: 'anthropic-openai-v2',
+        protocol: ANTHROPIC_PROTOCOL,
+        inbound: {
+            parse: async ({ wire, context }) => {
+                const adapterContext = buildAdapterContextFromPipeline(context, {
+                    defaultEntryEndpoint: DEFAULT_ANTHROPIC_ENDPOINT,
+                    overrideProtocol: ANTHROPIC_PROTOCOL
+                });
+                const formatEnvelope = await formatAdapter.parseRequest(wire, adapterContext);
+                const chatEnvelope = await semanticMapper.toChat(formatEnvelope, adapterContext);
+                const canonical = chatEnvelopeToStandardized(chatEnvelope, {
+                    adapterContext,
+                    endpoint: context.entryEndpoint ?? DEFAULT_ANTHROPIC_ENDPOINT,
+                    requestId: context.requestId
+                });
+                return { canonical };
+            }
+        },
+        outbound: {
+            serialize: async ({ canonical }) => {
+                const anthropicPayload = buildAnthropicFromOpenAIChat(canonical);
+                return { payload: assertJsonObject(anthropicPayload, 'anthropic_outbound_serialize') };
+            }
+        }
+    };
+}
+function buildPipelineContext(profile, context) {
+    return {
+        requestId: context.requestId,
+        entryEndpoint: context.entryEndpoint ?? context.endpoint ?? DEFAULT_ANTHROPIC_ENDPOINT,
+        providerProtocol: context.targetProtocol ?? profile.incomingProtocol ?? ANTHROPIC_PROTOCOL,
+        targetProtocol: profile.outgoingProtocol ?? context.targetProtocol ?? OPENAI_PROTOCOL,
+        profileId: profile.id,
+        stream: context.stream,
+        metadata: context.metadata
+    };
+}
+export class AnthropicOpenAIPipelineCodec {
+    id = 'anthropic-openai-v2';
+    pipeline;
+    initialized = false;
+    constructor() {
+        this.pipeline = new ProtocolConversionPipeline(createAnthropicHooks());
+    }
+    async initialize() {
+        this.initialized = true;
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('AnthropicOpenAIPipelineCodec must be initialized before use');
+        }
+    }
+    async convertRequest(payload, profile, context) {
+        this.ensureInitialized();
+        const inboundContext = buildPipelineContext(profile, context);
+        const inboundOptions = {
+            payload: assertJsonObject(payload, 'anthropic_inbound_request'),
+            context: inboundContext
+        };
+        const inbound = await this.pipeline.convertInbound(inboundOptions);
+        const openaiPayload = await convertCanonicalToOpenAIChat(inbound.canonical, inbound.context);
+        const filterContext = {
+            ...context,
+            requestId: context.requestId ?? inbound.context.requestId ?? `req_${Date.now()}`,
+            entryEndpoint: context.entryEndpoint ?? context.endpoint ?? DEFAULT_ANTHROPIC_ENDPOINT,
+            endpoint: context.endpoint ?? context.entryEndpoint ?? DEFAULT_ANTHROPIC_ENDPOINT
+        };
+        return runStandardChatRequestFilters(openaiPayload, profile, filterContext);
+    }
+    async convertResponse(payload, profile, context) {
+        this.ensureInitialized();
+        const sanitized = await canonicalizeOpenAIChatResponse(assertJsonObject(payload, 'openai_chat_response'), context);
+        const outboundOptions = {
+            canonical: sanitized,
+            context: buildPipelineContext(profile, context)
+        };
+        const outbound = await this.pipeline.convertOutbound(outboundOptions);
+        return outbound.payload;
+    }
+}

package/dist/conversion/pipeline/codecs/v2/openai-openai-pipeline.d.ts

@@ -0,0 +1,15 @@
+import type { ConversionCodec, ConversionContext, ConversionProfile } from '../../../types.js';
+import type { JsonObject } from '../../../hub/types/json.js';
+export declare class OpenAIOpenAIPipelineCodec implements ConversionCodec {
+    readonly id = "openai-openai-v2";
+    private readonly pipeline;
+    private readonly requestMetaStore;
+    private initialized;
+    constructor();
+    initialize(): Promise<void>;
+    private ensureInitialized;
+    private stashMeta;
+    private consumeMeta;
+    convertRequest(payload: unknown, profile: ConversionProfile, context: ConversionContext): Promise<JsonObject>;
+    convertResponse(payload: unknown, profile: ConversionProfile, context: ConversionContext): Promise<JsonObject>;
+}