@jsonstudio/llms 0.4.4 → 0.4.5

package/dist/conversion/pipeline/index.d.ts

@@ -0,0 +1,35 @@
+import { type CanonicalChatRequest, type CanonicalChatResponse } from './schema/index.js';
+import { type ProtocolPipelineHooks, type ProtocolPipelineContext, type ProtocolValidationErrorDetail } from './hooks/protocol-hooks.js';
+import { ConversionMetaBag, type ConversionMetaInput } from './meta/meta-bag.js';
+export interface ProtocolInboundPipelineOptions<TWire> {
+    payload: TWire;
+    context?: ProtocolPipelineContext;
+    meta?: ConversionMetaInput;
+}
+export interface ProtocolOutboundPipelineOptions<TCanonical> {
+    canonical: TCanonical;
+    context?: ProtocolPipelineContext;
+    meta?: ConversionMetaInput;
+}
+export interface ProtocolInboundPipelineResult<TCanonical> {
+    canonical: TCanonical;
+    meta: ConversionMetaBag;
+    context: ProtocolPipelineContext;
+}
+export interface ProtocolOutboundPipelineResult<TWire> {
+    payload: TWire;
+    meta: ConversionMetaBag;
+    context: ProtocolPipelineContext;
+}
+export declare class PipelineValidationError extends Error {
+    readonly stage: string;
+    readonly errors: ProtocolValidationErrorDetail[];
+    constructor(stage: string, errors: ProtocolValidationErrorDetail[]);
+}
+export declare class ProtocolConversionPipeline<TInboundWire = Record<string, unknown>, TOutboundWire = Record<string, unknown>, TCanonicalInbound = CanonicalChatRequest, TCanonicalOutbound = CanonicalChatResponse> {
+    private readonly hooks;
+    constructor(hooks: ProtocolPipelineHooks<TInboundWire, TOutboundWire, TCanonicalInbound, TCanonicalOutbound>);
+    convertInbound(options: ProtocolInboundPipelineOptions<TInboundWire>): Promise<ProtocolInboundPipelineResult<TCanonicalInbound>>;
+    convertOutbound(options: ProtocolOutboundPipelineOptions<TCanonicalOutbound>): Promise<ProtocolOutboundPipelineResult<TOutboundWire>>;
+    private runValidation;
+}

package/dist/conversion/pipeline/index.js

@@ -0,0 +1,103 @@
+import { ConversionMetaBag } from './meta/meta-bag.js';
+export class PipelineValidationError extends Error {
+    stage;
+    errors;
+    constructor(stage, errors) {
+        super(errors[0]?.message ?? `Validation failed during ${stage}`);
+        this.name = 'PipelineValidationError';
+        this.stage = stage;
+        this.errors = errors;
+    }
+}
+function normalizeContext(hooks, ctx) {
+    return {
+        profileId: ctx?.profileId ?? hooks.id,
+        providerProtocol: ctx?.providerProtocol ?? hooks.protocol,
+        targetProtocol: ctx?.targetProtocol ?? ctx?.providerProtocol ?? hooks.protocol,
+        entryEndpoint: ctx?.entryEndpoint,
+        requestId: ctx?.requestId,
+        stream: ctx?.stream,
+        metadata: ctx?.metadata ?? {}
+    };
+}
+function ingestMeta(target, incoming) {
+    if (!incoming) {
+        return;
+    }
+    target.ingest(incoming);
+}
+export class ProtocolConversionPipeline {
+    hooks;
+    constructor(hooks) {
+        if (!hooks?.inbound?.parse) {
+            throw new Error('ProtocolConversionPipeline requires an inbound.parse hook');
+        }
+        if (!hooks?.outbound?.serialize) {
+            throw new Error('ProtocolConversionPipeline requires an outbound.serialize hook');
+        }
+        this.hooks = hooks;
+    }
+    async convertInbound(options) {
+        const context = normalizeContext(this.hooks, options.context);
+        const meta = new ConversionMetaBag(options.meta);
+        await this.runValidation('inbound.preValidate', this.hooks.inbound.preValidate, {
+            wire: options.payload,
+            meta,
+            context
+        });
+        const parseResult = await this.hooks.inbound.parse({
+            wire: options.payload,
+            meta,
+            context
+        });
+        ingestMeta(meta, parseResult.meta);
+        const canonical = parseResult.canonical;
+        if (!canonical) {
+            throw new Error('ProtocolConversionPipeline inbound.parse returned an empty canonical payload');
+        }
+        if (this.hooks.inbound.cleanup) {
+            await this.hooks.inbound.cleanup({
+                canonical,
+                meta,
+                context
+            });
+        }
+        return { canonical, meta, context };
+    }
+    async convertOutbound(options) {
+        const context = normalizeContext(this.hooks, options.context);
+        const meta = new ConversionMetaBag(options.meta);
+        if (this.hooks.outbound.augment) {
+            await this.hooks.outbound.augment({
+                canonical: options.canonical,
+                meta,
+                context
+            });
+        }
+        const serialized = await this.hooks.outbound.serialize({
+            canonical: options.canonical,
+            meta,
+            context
+        });
+        ingestMeta(meta, serialized.meta);
+        await this.runValidation('outbound.postValidate', this.hooks.outbound.postValidate, {
+            wire: serialized.payload,
+            meta,
+            context
+        });
+        return { payload: serialized.payload, meta, context };
+    }
+    async runValidation(stage, hook, args) {
+        if (!hook) {
+            return;
+        }
+        const result = await hook(args);
+        if (!result) {
+            return;
+        }
+        const errors = result.errors ?? [];
+        if (result.ok === false || errors.length > 0) {
+            throw new PipelineValidationError(stage, errors.length ? errors : [{ message: 'Unknown validation error' }]);
+        }
+    }
+}

package/dist/conversion/pipeline/meta/meta-bag.d.ts

@@ -0,0 +1,20 @@
+import { type JsonValue } from '../../hub/types/json.js';
+export type ConversionMetaValue = JsonValue;
+export type ConversionMetaRecord = Record<string, ConversionMetaValue>;
+export type ConversionMetaEntries = Iterable<[string, ConversionMetaValue]>;
+export type ConversionMetaInput = ConversionMetaBag | ConversionMetaRecord | ConversionMetaEntries | undefined;
+export declare class ConversionMetaBag {
+    private readonly store;
+    constructor(initial?: ConversionMetaInput);
+    static from(input?: ConversionMetaInput): ConversionMetaBag;
+    keys(): string[];
+    has(key: string): boolean;
+    get<T extends ConversionMetaValue>(key: string): T | undefined;
+    set(key: string, value: ConversionMetaValue | undefined): void;
+    consume<T extends ConversionMetaValue>(key: string): T | undefined;
+    ingest(input?: ConversionMetaInput): void;
+    entries(): ConversionMetaEntries;
+    snapshot(): ConversionMetaRecord;
+    toJSON(): ConversionMetaRecord;
+    clone(): ConversionMetaBag;
+}

package/dist/conversion/pipeline/meta/meta-bag.js

@@ -0,0 +1,81 @@
+import { jsonClone } from '../../hub/types/json.js';
+function cloneValue(value) {
+    return jsonClone(value);
+}
+function entriesFromInput(input) {
+    if (!input) {
+        return undefined;
+    }
+    if (input instanceof ConversionMetaBag) {
+        return input.entries();
+    }
+    if (typeof input[Symbol.iterator] === 'function') {
+        return input;
+    }
+    return Object.entries(input);
+}
+export class ConversionMetaBag {
+    store = new Map();
+    constructor(initial) {
+        if (initial) {
+            this.ingest(initial);
+        }
+    }
+    static from(input) {
+        return new ConversionMetaBag(input);
+    }
+    keys() {
+        return Array.from(this.store.keys());
+    }
+    has(key) {
+        return this.store.has(key);
+    }
+    get(key) {
+        const value = this.store.get(key);
+        return value;
+    }
+    set(key, value) {
+        if (value === undefined) {
+            this.store.delete(key);
+            return;
+        }
+        this.store.set(key, cloneValue(value));
+    }
+    consume(key) {
+        const value = this.get(key);
+        if (value !== undefined) {
+            this.store.delete(key);
+        }
+        return value;
+    }
+    ingest(input) {
+        const incoming = entriesFromInput(input);
+        if (!incoming) {
+            return;
+        }
+        for (const [key, value] of incoming) {
+            if (value === undefined) {
+                this.store.delete(key);
+            }
+            else {
+                this.store.set(key, cloneValue(value));
+            }
+        }
+    }
+    entries() {
+        return this.store.entries();
+    }
+    snapshot() {
+        const out = {};
+        for (const [key, value] of this.store.entries()) {
+            out[key] = cloneValue(value);
+        }
+        return out;
+    }
+    toJSON() {
+        return this.snapshot();
+    }
+    clone() {
+        return new ConversionMetaBag(this.entries());
+    }
+}

package/dist/conversion/pipeline/schema/canonical-chat.d.ts

@@ -0,0 +1,18 @@
+import type { ProcessedRequest, StandardizedRequest } from '../../hub/types/standardized.js';
+import type { ChatCompletionLike } from '../../hub/response/response-mappers.js';
+/**
+ * Canonical request payload used by the Chat Process. The structure already
+ * exists inside the hub pipeline (`StandardizedRequest`), so v2 codecs can
+ * simply reuse it to avoid redefining similar shapes.
+ */
+export type CanonicalChatRequest = StandardizedRequest;
+/**
+ * Processed requests (after tool governance/reranking) are also exposed so the
+ * outbound side can make decisions that depend on process metadata.
+ */
+export type CanonicalProcessedRequest = ProcessedRequest;
+/**
+ * Canonical response payloads follow the OpenAI ChatCompletion-like structure
+ * that the existing format adapters emit.
+ */
+export type CanonicalChatResponse = ChatCompletionLike;

package/dist/conversion/pipeline/schema/canonical-chat.js

@@ -0,0 +1 @@
+export {};

package/dist/conversion/pipeline/schema/index.d.ts

@@ -0,0 +1 @@
+export * from './canonical-chat.js';

package/dist/conversion/pipeline/schema/index.js

@@ -0,0 +1 @@
+export * from './canonical-chat.js';

package/dist/conversion/responses/responses-openai-bridge.d.ts

@@ -0,0 +1,48 @@
+import type { BridgeInputItem, BridgeToolDefinition } from '../shared/bridge-message-types.js';
+import type { ChatToolDefinition } from '../hub/types/chat-envelope.js';
+import type { BridgeInputBuildResult } from '../shared/bridge-message-utils.js';
+export interface ResponsesRequestContext {
+    requestId?: string;
+    originalSystemMessages?: string[];
+    input?: BridgeInputItem[];
+    include?: unknown;
+    store?: unknown;
+    toolChoice?: unknown;
+    parallelToolCalls?: boolean;
+    metadata?: Record<string, unknown> | undefined;
+    responseFormat?: unknown;
+    stream?: boolean;
+    isChatPayload?: boolean;
+    isResponsesPayload?: boolean;
+    historyMessages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    currentMessage?: {
+        role: string;
+        content: string;
+    } | null;
+    toolsRaw?: BridgeToolDefinition[];
+    toolsNormalized?: Array<Record<string, unknown>>;
+}
+export interface BuildChatRequestResult {
+    request: Record<string, unknown>;
+    toolsNormalized?: ChatToolDefinition[];
+}
+export interface BuildResponsesRequestResult {
+    request: Record<string, unknown>;
+    originalSystemMessages?: string[];
+}
+export declare function captureResponsesContext(payload: Record<string, unknown>, dto?: {
+    route?: {
+        requestId?: string;
+    };
+}): ResponsesRequestContext;
+export declare function buildChatRequestFromResponses(payload: Record<string, unknown>, context: ResponsesRequestContext): BuildChatRequestResult;
+export declare function buildResponsesRequestFromChat(payload: Record<string, unknown>, ctx?: ResponsesRequestContext, extras?: {
+    bridgeHistory?: BridgeInputBuildResult;
+    systemInstruction?: string;
+}): BuildResponsesRequestResult;
+export declare function buildResponsesPayloadFromChat(payload: unknown, context?: ResponsesRequestContext): Record<string, unknown> | unknown;
+export declare function extractRequestIdFromResponse(response: any): string | undefined;
+export { buildChatResponseFromResponses } from '../shared/responses-response-utils.js';