@mate-academy/llm-gateway 8.8.2 → 8.8.3

package/dist/utilities/promptBuilder.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Utility types and functions for handling prompts with dynamic replacements and conditional sections.
+ * This allows for type-safe string templates with placeholders that can be replaced with actual values.
+ * The `createPromptTemplate` function helps create typed prompts with automatic extraction of replacement keys.
+ *
+ * @module promptBuilder
+ * @example
+ * // Example usage:
+ * const PROMPTS = {
+ *   welcomeMessage: createPromptTemplate(`
+ *     Generate a welcome message for a user who has just started their auto tech check attempt on {{topicTitle}}.
+ *     {{#hasBonus}}
+ *       This topic includes bonus content: {{bonusContent}}
+ *     {{/hasBonus}}
+ *
+ *     {{#valueAsCondition}}
+ *       This is a conditional section that will only appear if the value is truthy.
+ *       Value can be used inside the section: {{valueAsCondition}}
+ *     {{/valueAsCondition}}
+ *
+ *     {{#!skipSection}}
+ *       This negative conditional section will only appear if skipSection is falsy.
+ *     {{/skipSection}}
+ *  `),
+ * };
+ *
+ * const instruction = PROMPTS.welcomeMessage({
+ *   topicTitle: 'JavaScript Basics',
+ *   hasBonus: true,
+ *   bonusContent: 'Advanced debugging techniques',
+ * });
+ *
+ * // This will generate a prompt:
+ * // "Generate a welcome message for a user who has just started their auto tech check attempt on JavaScript Basics.
+ * //  This topic includes bonus content: Advanced debugging techniques"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPromptTemplate = createPromptTemplate;
+function promptBuilder(prompt, variables) {
+    if (!variables) {
+        return prompt;
+    }
+    const replaceVariables = (source) => (
+    // Replace all occurrences of the variable in the source string
+    Object.entries(variables).reduce((acc, [key, value]) => (acc.replace(new RegExp(`{{\\s*${key}\\s*}}`, 'g'), String(value))), source));
+    const processConditionalSections = (source) => {
+        // Process negative conditional sections first ({{#!condition}})
+        let result = source.replace(/{{#!(\w+)}}([\s\S]*?){{\/\1}}/g, (_, sectionName, content) => {
+            const value = variables[sectionName];
+            if (!value) {
+                // Recursively process nested conditional sections and then replace variables
+                const processedContent = processConditionalSections(content);
+                return replaceVariables(processedContent);
+            }
+            return '';
+        });
+        // Then process positive conditional sections ({{#condition}})
+        result = result.replace(/{{#(\w+)}}([\s\S]*?){{\/\1}}/g, (_, sectionName, content) => {
+            const value = variables[sectionName];
+            if (value) {
+                // Recursively process nested conditional sections and then replace variables
+                const processedContent = processConditionalSections(content);
+                return replaceVariables(processedContent);
+            }
+            return '';
+        });
+        return result;
+    };
+    let result = prompt;
+    // Process conditional sections first (with recursive handling for nested sections)
+    result = processConditionalSections(result);
+    // Then process regular variable replacements
+    result = replaceVariables(result);
+    return result;
+}
+/**
+ * Creates a prompt template function that can be used to generate prompts
+ * with dynamic replacements and conditional sections.
+ * @template T The type of the template string. Inferred from the provided template.
+ * @param {T} template The template string with placeholders:
+ * - for dynamic values (e.g., `{{topicTitle}}`)
+ * - for conditional sections (e.g., `{{#section}}...{{/section}}`)
+ * - for negative conditional sections (e.g., `{{#!section}}...{{/section}}`)
+ * - for sections that use conditional variables as values (e.g., `{{#bonus}}...{{bonus}}...{{/bonus}}`)
+ * @returns A function that takes the dynamic values and returns the generated prompt.
+ */
+function createPromptTemplate(template) {
+    const trimmedTemplate = template.trim();
+    return (...args) => promptBuilder(trimmedTemplate, ...args);
+}
+//# sourceMappingURL=promptBuilder.js.map

package/dist/utilities/promptBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptBuilder.js","sourceRoot":"","sources":["../../src/utilities/promptBuilder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;AAgJH,oDAQC;AA3ED,SAAS,aAAa,CACpB,MAAc,EACd,SAA2D;IAE3D,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,gBAAgB,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC;IACnD,+DAA+D;IAC/D,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CACtD,GAAG,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,SAAS,GAAG,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAClE,EAAE,MAAM,CAAC,CACX,CAAC;IAEF,MAAM,0BAA0B,GAAG,CAAC,MAAc,EAAU,EAAE;QAC5D,gEAAgE;QAChE,IAAI,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,gCAAgC,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE;YACxF,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;YAErC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,6EAA6E;gBAC7E,MAAM,gBAAgB,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;gBAC7D,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;YAC5C,CAAC;YAED,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,8DAA8D;QAC9D,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,+BAA+B,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE;YACnF,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;YAErC,IAAI,KAAK,EAAE,CAAC;gBACV,6EAA6E;gBAC7E,MAAM,gBAAgB,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;gBAC7D,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;YAC5C,CAAC;YAED,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF,IAAI,MAAM,GAAG,MAAM,CAAC;IAEpB,mFAAmF;IACnF,MAAM,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC;IAE5C,6CAA6C;IAC7C,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAElC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,oBAAoB,CAAmB,QAAW;IAChE,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,EAAO,CAAC;IAE7C,OAAO,CACL,GAAG,IAEqC,EAChC,EAAE,CAAC,aAAa,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/dist/utilities/reporter/LLMReporterInterface.d.ts

@@ -0,0 +1,46 @@
+import type { LLMProviders, LLMPurposes } from '../../LLMService.typedefs';
+/**
+ * Core LLM metrics that are always collected by the gateway.
+ * These metrics are automatically populated during operations.
+ */
+export interface LLMMetrics {
+    provider: LLMProviders;
+    purpose: LLMPurposes;
+    model: string | null;
+    modelConfig: Record<string, any> | null;
+    method: string;
+    status: 'success' | 'error' | 'cancelled';
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    costs: {
+        input: number;
+        output: number;
+        total: number;
+        currency: string;
+    };
+}
+/**
+ * Function type for writing LLM metrics.
+ *
+ * @param metrics - The LLM metrics to write
+ * @returns A promise that resolves when the metrics have been written
+ */
+export type LLMMetricsWriter = (metrics: LLMMetrics) => Promise<void>;
+/**
+ * Simplified reporter interface for LLM metrics collection.
+ *
+ * @template ReporterContext - User-defined context schema type
+ */
+export interface LLMReporterInterface<ReporterContext extends Record<string, any> | undefined = undefined> {
+    /**
+     * Initializes a metrics writer that tracks timing and provides write function.
+     * The returned write function automatically includes duration and can only be called once.
+     *
+     * @param reporterContext - Optional user-defined context to include with metrics
+     * @returns Write function that stops timer and writes metrics
+     */
+    initWriter(...args: ReporterContext extends undefined ? [] : [reporterContext: ReporterContext]): LLMMetricsWriter;
+}

package/dist/utilities/reporter/LLMReporterInterface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=LLMReporterInterface.js.map

package/dist/utilities/reporter/LLMReporterInterface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMReporterInterface.js","sourceRoot":"","sources":["../../../src/utilities/reporter/LLMReporterInterface.ts"],"names":[],"mappings":""}

package/dist/utilities/reporter/index.d.ts

@@ -0,0 +1 @@
+export * from './LLMReporterInterface';

package/dist/utilities/reporter/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./LLMReporterInterface"), exports);
+//# sourceMappingURL=index.js.map

package/dist/utilities/reporter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utilities/reporter/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC"}

package/dist/utilities/schema/LLMSchema.d.ts

@@ -0,0 +1,112 @@
+import type { LLMProviders } from '../../LLMService.typedefs';
+import type { LLMSchemaInterface, ParseResult, InferSchema } from '../../utilities/schema/LLMSchema.typedefs';
+/**
+ * Concrete implementation of schema builder using Zod as the underlying validator.
+ * This implementation can be replaced with another validator without changing the public API.
+ */
+export declare class LLMSchema<T = any> implements LLMSchemaInterface<T> {
+    private readonly zodSchema;
+    private constructor();
+    /**
+     * Creates a string schema
+     */
+    static string(): LLMSchemaInterface<string>;
+    /**
+     * Creates a number schema
+     */
+    static number(): LLMSchemaInterface<number>;
+    /**
+     * Creates a boolean schema
+     */
+    static boolean(): LLMSchemaInterface<boolean>;
+    /**
+     * Creates an object schema
+     */
+    static object<T extends Record<string, LLMSchemaInterface>>(shape: T): LLMSchemaInterface<{
+        [K in keyof T]: InferSchema<T[K]>;
+    }>;
+    /**
+     * Creates an array schema
+     */
+    static array<T>(itemSchema: LLMSchemaInterface<T>): LLMSchemaInterface<T[]>;
+    /**
+     * Creates an enum schema
+     */
+    static enum<T extends readonly [string, ...string[]]>(values: T): LLMSchemaInterface<T[number]>;
+    /**
+     * Creates a union schema
+     */
+    static union<T extends readonly [LLMSchemaInterface, ...LLMSchemaInterface[]]>(schemas: T): LLMSchemaInterface<InferSchema<T[number]>>;
+    /**
+     * Creates a literal schema
+     */
+    static literal<T extends string | number | boolean>(value: T): LLMSchemaInterface<T>;
+    /**
+     * Makes the schema optional
+     * In Zod v4, this also makes the field nullable to support provider adapters
+     * that convert optional fields to required+nullable (e.g., OpenAI structured output)
+     */
+    optional(): LLMSchemaInterface<T | undefined | null>;
+    /**
+     * Makes the schema nullable
+     */
+    nullable(): LLMSchemaInterface<T | null>;
+    /**
+     * Sets a default value
+     */
+    default(value: any): LLMSchemaInterface<T>;
+    /**
+     * Adds a description (for documentation)
+     */
+    describe(description: string): LLMSchemaInterface<T>;
+    /**
+     * Sets minimum string length
+     */
+    min(length: number): LLMSchemaInterface<T>;
+    /**
+     * Sets maximum string length
+     */
+    max(length: number): LLMSchemaInterface<T>;
+    /**
+     * Validates as email
+     */
+    email(): LLMSchemaInterface<T>;
+    /**
+     * Validates as URL
+     */
+    url(): LLMSchemaInterface<T>;
+    /**
+     * Validates as UUID
+     */
+    uuid(): LLMSchemaInterface<T>;
+    /**
+     * Validates as integer
+     */
+    int(): LLMSchemaInterface<T>;
+    /**
+     * Validates as positive number
+     */
+    positive(): LLMSchemaInterface<T>;
+    /**
+     * Validates as negative number
+     */
+    negative(): LLMSchemaInterface<T>;
+    /**
+     * Validates as non-positive number
+     */
+    nonpositive(): LLMSchemaInterface<T>;
+    /**
+     * Validates as non-negative number
+     */
+    nonnegative(): LLMSchemaInterface<T>;
+    /**
+     * @internal
+     * Parses data using the schema
+     */
+    _parse(data: unknown): ParseResult<T>;
+    /**
+     * @internal
+     * Converts schema to provider-specific format using the adapter registry
+     */
+    _toProviderSchema(provider: LLMProviders): any;
+}

package/dist/utilities/schema/LLMSchema.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMSchema = void 0;
+const zod_1 = require("zod");
+const SchemaAdapterRegistry_1 = require("../../utilities/schema/SchemaAdapterRegistry");
+/**
+ * Concrete implementation of schema builder using Zod as the underlying validator.
+ * This implementation can be replaced with another validator without changing the public API.
+ */
+class LLMSchema {
+    zodSchema;
+    constructor(zodSchema) {
+        this.zodSchema = zodSchema;
+    }
+    // ============ Factory Methods ============
+    /**
+     * Creates a string schema
+     */
+    static string() {
+        return new LLMSchema(zod_1.z.string());
+    }
+    /**
+     * Creates a number schema
+     */
+    static number() {
+        return new LLMSchema(zod_1.z.number());
+    }
+    /**
+     * Creates a boolean schema
+     */
+    static boolean() {
+        return new LLMSchema(zod_1.z.boolean());
+    }
+    /**
+     * Creates an object schema
+     */
+    static object(shape) {
+        const zodShape = {};
+        for (const [key, schema] of Object.entries(shape)) {
+            zodShape[key] = schema.zodSchema;
+        }
+        return new LLMSchema(zod_1.z.object(zodShape));
+    }
+    /**
+     * Creates an array schema
+     */
+    static array(itemSchema) {
+        return new LLMSchema(zod_1.z.array(itemSchema.zodSchema));
+    }
+    /**
+     * Creates an enum schema
+     */
+    static enum(values) {
+        return new LLMSchema(zod_1.z.enum(values));
+    }
+    /**
+     * Creates a union schema
+     */
+    static union(schemas) {
+        const zodSchemas = schemas.map(s => s.zodSchema);
+        return new LLMSchema(zod_1.z.union(zodSchemas));
+    }
+    /**
+     * Creates a literal schema
+     */
+    static literal(value) {
+        return new LLMSchema(zod_1.z.literal(value));
+    }
+    // ============ Modifier Methods ============
+    /**
+     * Makes the schema optional
+     * In Zod v4, this also makes the field nullable to support provider adapters
+     * that convert optional fields to required+nullable (e.g., OpenAI structured output)
+     */
+    optional() {
+        return new LLMSchema(this.zodSchema.optional().nullable());
+    }
+    /**
+     * Makes the schema nullable
+     */
+    nullable() {
+        return new LLMSchema(this.zodSchema.nullable());
+    }
+    /**
+     * Sets a default value
+     */
+    default(value) {
+        return new LLMSchema(this.zodSchema.default(value));
+    }
+    /**
+     * Adds a description (for documentation)
+     */
+    describe(description) {
+        return new LLMSchema(this.zodSchema.describe(description));
+    }
+    // ============ String-specific Modifiers ============
+    /**
+     * Sets minimum string length
+     */
+    min(length) {
+        if (this.zodSchema instanceof zod_1.z.ZodString) {
+            return new LLMSchema(this.zodSchema.min(length));
+        }
+        return this;
+    }
+    /**
+     * Sets maximum string length
+     */
+    max(length) {
+        if (this.zodSchema instanceof zod_1.z.ZodString) {
+            return new LLMSchema(this.zodSchema.max(length));
+        }
+        return this;
+    }
+    /**
+     * Validates as email
+     */
+    email() {
+        if (this.zodSchema instanceof zod_1.z.ZodString) {
+            return new LLMSchema(this.zodSchema.email());
+        }
+        return this;
+    }
+    /**
+     * Validates as URL
+     */
+    url() {
+        if (this.zodSchema instanceof zod_1.z.ZodString) {
+            return new LLMSchema(this.zodSchema.url());
+        }
+        return this;
+    }
+    /**
+     * Validates as UUID
+     */
+    uuid() {
+        if (this.zodSchema instanceof zod_1.z.ZodString) {
+            return new LLMSchema(this.zodSchema.uuid());
+        }
+        return this;
+    }
+    // ============ Number-specific Modifiers ============
+    /**
+     * Validates as integer
+     */
+    int() {
+        if (this.zodSchema instanceof zod_1.z.ZodNumber) {
+            return new LLMSchema(this.zodSchema.int());
+        }
+        return this;
+    }
+    /**
+     * Validates as positive number
+     */
+    positive() {
+        if (this.zodSchema instanceof zod_1.z.ZodNumber) {
+            return new LLMSchema(this.zodSchema.positive());
+        }
+        return this;
+    }
+    /**
+     * Validates as negative number
+     */
+    negative() {
+        if (this.zodSchema instanceof zod_1.z.ZodNumber) {
+            return new LLMSchema(this.zodSchema.negative());
+        }
+        return this;
+    }
+    /**
+     * Validates as non-positive number
+     */
+    nonpositive() {
+        if (this.zodSchema instanceof zod_1.z.ZodNumber) {
+            return new LLMSchema(this.zodSchema.nonpositive());
+        }
+        return this;
+    }
+    /**
+     * Validates as non-negative number
+     */
+    nonnegative() {
+        if (this.zodSchema instanceof zod_1.z.ZodNumber) {
+            return new LLMSchema(this.zodSchema.nonnegative());
+        }
+        return this;
+    }
+    // ============ Internal Methods (Package Use Only) ============
+    /**
+     * @internal
+     * Parses data using the schema
+     */
+    _parse(data) {
+        const result = this.zodSchema.safeParse(data);
+        if (result.success) {
+            return {
+                success: true,
+                data: result.data,
+            };
+        }
+        return {
+            success: false,
+            error: result.error.message,
+        };
+    }
+    /**
+     * @internal
+     * Converts schema to provider-specific format using the adapter registry
+     */
+    _toProviderSchema(provider) {
+        const adapter = (0, SchemaAdapterRegistry_1.getSchemaAdapter)(provider);
+        if (!adapter) {
+            throw new Error(`Provider ${provider} does not support structured output`);
+        }
+        const jsonSchema = zod_1.z.toJSONSchema(this.zodSchema, {
+            target: 'draft-7',
+            reused: 'inline',
+        });
+        return adapter.convertSchema(jsonSchema);
+    }
+}
+exports.LLMSchema = LLMSchema;
+//# sourceMappingURL=LLMSchema.js.map

package/dist/utilities/schema/LLMSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMSchema.js","sourceRoot":"","sources":["../../../src/utilities/schema/LLMSchema.ts"],"names":[],"mappings":"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"}

package/dist/utilities/schema/LLMSchema.typedefs.d.ts

@@ -0,0 +1,55 @@
+import type { LLMProviders } from '../../LLMService.typedefs';
+/**
+ * Result of parsing data against a schema
+ */
+export interface ParseResult<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * Abstract interface for schema implementations
+ * This allows for different validation libraries to be used internally
+ */
+export interface LLMSchemaInterface<T = any> {
+    /**
+     * Parse and validate data against the schema
+     * @internal - Used internally by the package
+     */
+    _parse(data: unknown): ParseResult<T>;
+    /**
+     * Convert schema to provider-specific format using registered adapters
+     * @internal - Used internally by the package
+     */
+    _toProviderSchema(provider: LLMProviders): any;
+    optional(): LLMSchemaInterface<T | undefined | null>;
+    nullable(): LLMSchemaInterface<T | null>;
+    default(value: any): LLMSchemaInterface<T>;
+    describe(description: string): LLMSchemaInterface<T>;
+    min(length: number): LLMSchemaInterface<T>;
+    max(length: number): LLMSchemaInterface<T>;
+    email(): LLMSchemaInterface<T>;
+    url(): LLMSchemaInterface<T>;
+    uuid(): LLMSchemaInterface<T>;
+    int(): LLMSchemaInterface<T>;
+    positive(): LLMSchemaInterface<T>;
+    negative(): LLMSchemaInterface<T>;
+    nonpositive(): LLMSchemaInterface<T>;
+    nonnegative(): LLMSchemaInterface<T>;
+}
+/**
+ * Type inference helper for schemas
+ */
+export type InferSchema<T> = T extends LLMSchemaInterface<infer U> ? U : never;
+/**
+ * Interface for schema adapters that convert generic JSON Schema
+ * to provider-specific formats
+ */
+export interface SchemaAdapterInterface {
+    /**
+     * Converts a JSON Schema to provider-specific format
+     * @param jsonSchema - The JSON Schema to convert
+     * @returns The provider-specific schema format
+     */
+    convertSchema(jsonSchema: any): any;
+}

package/dist/utilities/schema/LLMSchema.typedefs.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=LLMSchema.typedefs.js.map

package/dist/utilities/schema/LLMSchema.typedefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMSchema.typedefs.js","sourceRoot":"","sources":["../../../src/utilities/schema/LLMSchema.typedefs.ts"],"names":[],"mappings":""}

package/dist/utilities/schema/SchemaAdapterRegistry.d.ts

@@ -0,0 +1,26 @@
+import { LLMProviders } from '../../LLMService.typedefs';
+import type { SchemaAdapterInterface } from '../../utilities/schema/LLMSchema.typedefs';
+import { OpenAISchemaAdapter } from '../../providers/OpenAI/schemas/OpenAISchemaAdapter';
+import { GoogleSchemaAdapter } from '../../providers/GoogleGenerativeAI/schemas/GoogleSchemaAdapter';
+import { LLMAPISchemaAdapter } from '../../providers/LLMAPI/schemas/LLMAPISchemaAdapter';
+/**
+ * Type-safe registry of schema adapters for all supported providers.
+ *
+ * When adding a new provider:
+ * 1. Add the provider to LLMProviders enum
+ * 2. Create the schema adapter implementing SchemaAdapterInterface
+ * 3. Add the adapter to this registry (TypeScript will enforce this)
+ * 4. Set to `null` if the provider doesn't support structured output
+ *
+ * This ensures compile-time safety and forces developers to handle all providers.
+ */
+export declare const SCHEMA_ADAPTER_REGISTRY: {
+    readonly OpenAI: OpenAISchemaAdapter;
+    readonly GoogleGenerativeAI: GoogleSchemaAdapter;
+    readonly LLMAPI: LLMAPISchemaAdapter;
+};
+/**
+ * Type-safe helper to get a schema adapter for a provider.
+ * Returns null if the provider doesn't support structured output.
+ */
+export declare function getSchemaAdapter(provider: LLMProviders): SchemaAdapterInterface | null;

package/dist/utilities/schema/SchemaAdapterRegistry.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_ADAPTER_REGISTRY = void 0;
+exports.getSchemaAdapter = getSchemaAdapter;
+const LLMService_typedefs_1 = require("../../LLMService.typedefs");
+const OpenAISchemaAdapter_1 = require("../../providers/OpenAI/schemas/OpenAISchemaAdapter");
+const GoogleSchemaAdapter_1 = require("../../providers/GoogleGenerativeAI/schemas/GoogleSchemaAdapter");
+const LLMAPISchemaAdapter_1 = require("../../providers/LLMAPI/schemas/LLMAPISchemaAdapter");
+/**
+ * Type-safe registry of schema adapters for all supported providers.
+ *
+ * When adding a new provider:
+ * 1. Add the provider to LLMProviders enum
+ * 2. Create the schema adapter implementing SchemaAdapterInterface
+ * 3. Add the adapter to this registry (TypeScript will enforce this)
+ * 4. Set to `null` if the provider doesn't support structured output
+ *
+ * This ensures compile-time safety and forces developers to handle all providers.
+ */
+exports.SCHEMA_ADAPTER_REGISTRY = {
+    [LLMService_typedefs_1.LLMProviders.OpenAI]: new OpenAISchemaAdapter_1.OpenAISchemaAdapter(),
+    [LLMService_typedefs_1.LLMProviders.GoogleGenerativeAI]: new GoogleSchemaAdapter_1.GoogleSchemaAdapter(),
+    [LLMService_typedefs_1.LLMProviders.LLMAPI]: new LLMAPISchemaAdapter_1.LLMAPISchemaAdapter(),
+};
+/**
+ * Type-safe helper to get a schema adapter for a provider.
+ * Returns null if the provider doesn't support structured output.
+ */
+function getSchemaAdapter(provider) {
+    return exports.SCHEMA_ADAPTER_REGISTRY[provider];
+}
+//# sourceMappingURL=SchemaAdapterRegistry.js.map

package/dist/utilities/schema/SchemaAdapterRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaAdapterRegistry.js","sourceRoot":"","sources":["../../../src/utilities/schema/SchemaAdapterRegistry.ts"],"names":[],"mappings":";;;AA2BA,4CAEC;AA7BD,+DAAqD;AAErD,wFAAqF;AACrF,oGAAiG;AACjG,wFAAqF;AAErF;;;;;;;;;;GAUG;AACU,QAAA,uBAAuB,GAAG;IACrC,CAAC,kCAAY,CAAC,MAAM,CAAC,EAAE,IAAI,yCAAmB,EAAE;IAChD,CAAC,kCAAY,CAAC,kBAAkB,CAAC,EAAE,IAAI,yCAAmB,EAAE;IAC5D,CAAC,kCAAY,CAAC,MAAM,CAAC,EAAE,IAAI,yCAAmB,EAAE;CACsB,CAAC;AAEzE;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,QAAsB;IACrD,OAAO,+BAAuB,CAAC,QAAQ,CAAC,CAAC;AAC3C,CAAC"}

package/dist/utilities/schema/index.d.ts

@@ -0,0 +1,2 @@
+export * from './LLMSchema.typedefs';
+export * from './LLMSchema';