genai-lite 0.12.0 → 0.13.1

package/dist/llm/LLMService.d.ts

@@ -1,6 +1,6 @@
 import type { ApiKeyProvider, PresetMode } from '../types';
 import type { Logger, LogLevel } from '../logging/types';
-import type { LLMChatRequest, LLMChatRequestWithPreset, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId, LLMSettings, ModelContext, LLMMessage, LLMStreamEvent } from "./types";
+import type { LLMChatRequest, LLMChatRequestWithPreset, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId, LLMSettings, ModelContext, LLMMessage, LLMStreamEvent, LLMRequestCapabilityPreflight, LLMRequestCapabilityValidationResult, ModelCapabilitiesResult, StructuredOutputSupport } from "./types";
 import type { ModelPreset } from "../types/presets";
 import { type RetryPolicy } from "../shared/services/withRetry";
 export type { PresetMode };
@@ -101,6 +101,31 @@ export declare class LLMService {
      * @returns Promise resolving to array of model information
      */
     getModels(providerId: ApiProviderId): Promise<ModelInfo[]>;
+    /**
+     * Gets static capability metadata for a provider/model pair without retrieving
+     * API keys, calling provider adapters, or performing network I/O.
+     *
+     * Unknown or unregistered models use the same fallback model resolution policy
+     * as sendMessage(), but their optional capabilities are reported as unknown.
+     */
+    getModelCapabilities(providerId: ApiProviderId, modelId: string): Promise<ModelCapabilitiesResult | LLMFailureResponse>;
+    /**
+     * Convenience wrapper for checking structured-output support.
+     *
+     * Returns `unknown` when genai-lite has no explicit capability metadata. Callers
+     * should decide whether unknown is acceptable for their use case.
+     */
+    supportsStructuredOutput(providerId: ApiProviderId, modelId: string): Promise<StructuredOutputSupport | LLMFailureResponse>;
+    /**
+     * Preflights provider/model capability requirements for a request without
+     * retrieving API keys, calling provider adapters, or performing network I/O.
+     *
+     * This checks the effective settings after preset and model defaults are
+     * applied. Unknown/unspecified capabilities are reported as unknown and remain
+     * valid; explicitly unsupported capabilities return the same validation error
+     * shape as sendMessage() where possible.
+     */
+    validateRequestCapabilities(request: LLMRequestCapabilityPreflight): Promise<LLMRequestCapabilityValidationResult>;
     /**
      * Sends a chat message to an LLM provider
      *
@@ -116,6 +141,10 @@ export declare class LLMService {
      * are yielded as a single `error` event.
      */
     streamMessage(request: LLMChatRequest | LLMChatRequestWithPreset, callOptions?: StreamMessageOptions): AsyncGenerator<LLMStreamEvent>;
+    private resolveAndValidateCapabilities;
+    private buildModelCapabilities;
+    private getStructuredOutputSupport;
+    private getCapabilitySource;
     private prepareRequest;
     private postProcessResponse;
     /**

package/dist/llm/LLMService.js

@@ -76,6 +76,93 @@ class LLMService {
         this.logger.debug(`Found ${models.length} models for provider: ${providerId}`);
         return [...models]; // Return a copy to prevent external modification
     }
+    /**
+     * Gets static capability metadata for a provider/model pair without retrieving
+     * API keys, calling provider adapters, or performing network I/O.
+     *
+     * Unknown or unregistered models use the same fallback model resolution policy
+     * as sendMessage(), but their optional capabilities are reported as unknown.
+     */
+    async getModelCapabilities(providerId, modelId) {
+        this.logger.debug(`LLMService.getModelCapabilities called for provider: ${providerId}, model: ${modelId}`);
+        const resolved = await this.modelResolver.resolve({ providerId, modelId }, { detectLocalCapabilities: false });
+        if (resolved.error) {
+            return resolved.error;
+        }
+        const resolvedProviderId = resolved.providerId;
+        const resolvedModelId = resolved.modelId;
+        const modelInfo = resolved.modelInfo;
+        const source = this.getCapabilitySource(resolvedProviderId, resolvedModelId);
+        return {
+            object: "model.capabilities",
+            provider: resolvedProviderId,
+            model: resolvedModelId,
+            modelInfo: { ...modelInfo },
+            structuredOutput: this.getStructuredOutputSupport(modelInfo, source),
+        };
+    }
+    /**
+     * Convenience wrapper for checking structured-output support.
+     *
+     * Returns `unknown` when genai-lite has no explicit capability metadata. Callers
+     * should decide whether unknown is acceptable for their use case.
+     */
+    async supportsStructuredOutput(providerId, modelId) {
+        const capabilities = await this.getModelCapabilities(providerId, modelId);
+        if (capabilities.object === "error") {
+            return capabilities;
+        }
+        return capabilities.structuredOutput;
+    }
+    /**
+     * Preflights provider/model capability requirements for a request without
+     * retrieving API keys, calling provider adapters, or performing network I/O.
+     *
+     * This checks the effective settings after preset and model defaults are
+     * applied. Unknown/unspecified capabilities are reported as unknown and remain
+     * valid; explicitly unsupported capabilities return the same validation error
+     * shape as sendMessage() where possible.
+     */
+    async validateRequestCapabilities(request) {
+        this.logger.debug(`LLMService.validateRequestCapabilities called with presetId: ${request.presetId}, provider: ${request.providerId}, model: ${request.modelId}`);
+        try {
+            const validation = await this.resolveAndValidateCapabilities(request, {
+                validateStructure: false,
+                detectLocalCapabilities: false,
+            });
+            if ("error" in validation) {
+                return {
+                    ...validation.error,
+                    valid: false,
+                    ...(validation.capabilities && { capabilities: validation.capabilities }),
+                };
+            }
+            return {
+                object: "capability.validation",
+                valid: true,
+                provider: validation.context.providerId,
+                model: validation.context.modelId,
+                capabilities: validation.context.capabilities,
+            };
+        }
+        catch (error) {
+            this.logger.error("Error in LLMService.validateRequestCapabilities:", error);
+            return {
+                provider: request.providerId || request.presetId || 'unknown',
+                model: request.modelId || request.presetId || 'unknown',
+                error: {
+                    message: error instanceof Error
+                        ? error.message
+                        : "Unexpected error during capability preflight",
+                    code: "UNKNOWN_ERROR",
+                    type: "server_error",
+                    providerError: error,
+                },
+                object: "error",
+                valid: false,
+            };
+        }
+    }
     /**
      * Sends a chat message to an LLM provider
      *
@@ -248,44 +335,95 @@ class LLMService {
             };
         }
     }
-    async prepareRequest(request, callOptions) {
-        // Resolve model information from preset or direct IDs
-        const resolved = await this.modelResolver.resolve(request);
+    async resolveAndValidateCapabilities(request, options) {
+        const resolved = await this.modelResolver.resolve(request, {
+            detectLocalCapabilities: options.detectLocalCapabilities,
+        });
         if (resolved.error) {
             return { error: resolved.error };
         }
-        const { providerId, modelId, modelInfo, settings: resolvedSettings } = resolved;
-        // Create a proper LLMChatRequest with resolved values
+        const providerId = resolved.providerId;
+        const modelId = resolved.modelId;
+        const modelInfo = resolved.modelInfo;
+        const source = this.getCapabilitySource(providerId, modelId);
+        const capabilities = this.buildModelCapabilities(modelInfo, source);
         const resolvedRequest = {
             ...request,
-            providerId: providerId,
-            modelId: modelId,
+            providerId,
+            modelId,
+            messages: "messages" in request && Array.isArray(request.messages)
+                ? request.messages
+                : [],
         };
-        // Validate basic request structure
-        const structureValidationResult = this.requestValidator.validateRequestStructure(resolvedRequest);
-        if (structureValidationResult) {
-            return { error: structureValidationResult };
-        }
-        // Validate settings if provided
-        const combinedSettings = { ...resolvedSettings, ...request.settings };
-        if (combinedSettings) {
-            const settingsValidation = this.requestValidator.validateSettings(combinedSettings, providerId, modelId);
-            if (settingsValidation) {
-                return { error: settingsValidation };
+        if (options.validateStructure) {
+            const structureValidationResult = this.requestValidator.validateRequestStructure(resolvedRequest);
+            if (structureValidationResult) {
+                return { error: structureValidationResult, capabilities };
             }
         }
-        // Apply model-specific defaults and merge with user settings
+        const combinedSettings = {
+            ...(resolved.settings || {}),
+            ...(request.settings || {}),
+        };
+        const settingsValidation = this.requestValidator.validateSettings(combinedSettings, providerId, modelId);
+        if (settingsValidation) {
+            return { error: settingsValidation, capabilities };
+        }
         const finalSettings = this.settingsManager.mergeSettingsForModel(modelId, providerId, combinedSettings, modelInfo);
-        // Validate reasoning settings for model capabilities
         const reasoningValidation = this.requestValidator.validateReasoningSettings(modelInfo, finalSettings.reasoning, resolvedRequest);
         if (reasoningValidation) {
-            return { error: reasoningValidation };
+            return { error: reasoningValidation, capabilities };
         }
-        // Validate structured output settings for model capabilities
         const structuredOutputValidation = this.requestValidator.validateStructuredOutputSettings(modelInfo, finalSettings.structuredOutput, resolvedRequest);
         if (structuredOutputValidation) {
-            return { error: structuredOutputValidation };
+            return { error: structuredOutputValidation, capabilities };
+        }
+        return {
+            context: {
+                providerId,
+                modelId,
+                modelInfo,
+                resolvedRequest,
+                finalSettings,
+                capabilities,
+            },
+        };
+    }
+    buildModelCapabilities(modelInfo, source) {
+        return {
+            structuredOutput: this.getStructuredOutputSupport(modelInfo, source),
+        };
+    }
+    getStructuredOutputSupport(modelInfo, source) {
+        if (modelInfo.structuredOutput === undefined) {
+            return {
+                status: "unknown",
+                source,
+            };
+        }
+        return {
+            status: modelInfo.structuredOutput.supported ? "supported" : "unsupported",
+            ...(modelInfo.structuredOutput.strictMode !== undefined && {
+                strictMode: modelInfo.structuredOutput.strictMode,
+            }),
+            ...(modelInfo.structuredOutput.notes && {
+                notes: modelInfo.structuredOutput.notes,
+            }),
+            source,
+        };
+    }
+    getCapabilitySource(providerId, modelId) {
+        return (0, config_1.getModelById)(modelId, providerId) ? "registry" : "fallback";
+    }
+    async prepareRequest(request, callOptions) {
+        const validation = await this.resolveAndValidateCapabilities(request, {
+            validateStructure: true,
+            detectLocalCapabilities: true,
+        });
+        if ("error" in validation) {
+            return { error: validation.error };
         }
+        const { providerId, modelId, modelInfo, resolvedRequest, finalSettings, } = validation.context;
         // Get provider info for parameter filtering
         const providerInfo = (0, config_1.getProviderById)(providerId);
         if (!providerInfo) {
@@ -355,9 +493,9 @@ class LLMService {
             };
             return {
                 prepared: {
-                    providerId: providerId,
-                    modelId: modelId,
-                    modelInfo: modelInfo,
+                    providerId,
+                    modelId,
+                    modelInfo,
                     resolvedRequest,
                     internalRequest,
                     clientAdapter,

package/dist/llm/clients/AnthropicClientAdapter.js

@@ -54,26 +54,15 @@ class AnthropicClientAdapter {
                 hasStopSequences: !!messageParams.stop_sequences,
                 useStructuredOutput,
             });
-            // Make the API call - use beta endpoint for structured output
-            let completion;
-            if (useStructuredOutput) {
-                // For structured output, we need to use the beta messages endpoint with proper headers
-                completion = await anthropic.messages.create(messageParams, {
-                    headers: {
-                        'anthropic-beta': 'structured-outputs-2025-11-13',
-                    },
-                    ...requestTransportOptions,
-                });
-            }
-            else {
-                completion =
-                    Object.keys(requestTransportOptions).length > 0
-                        ? await anthropic.messages.create(messageParams, requestTransportOptions)
-                        : await anthropic.messages.create(messageParams);
-            }
+            // Structured and unstructured requests take the same endpoint - structured
+            // output is GA, so there is no beta header or beta endpoint involved.
+            const completion = Object.keys(requestTransportOptions).length > 0
+                ? await anthropic.messages.create(messageParams, requestTransportOptions)
+                : await anthropic.messages.create(messageParams);
             this.logger.info(`Anthropic API call successful, response ID: ${completion.id}`);
-            // Convert to standardized response format
-            // Cast to any to handle beta response type differences
+            // Convert to standardized response format. `create` is typed against the
+            // streaming/non-streaming param union; we never set `stream`, so this is
+            // always a Message.
             return this.createSuccessResponse(completion, request);
         }
         catch (error) {
@@ -94,17 +83,12 @@ class AnthropicClientAdapter {
         let started = false;
         try {
             const { anthropic, messageParams, requestTransportOptions, useStructuredOutput, } = this.prepareMessageRequest(request, apiKey, options);
-            this.logger.info(`Making Anthropic streaming API call for model: ${request.modelId}`);
-            const streamOptions = useStructuredOutput
-                ? {
-                    headers: {
-                        "anthropic-beta": "structured-outputs-2025-11-13",
-                    },
-                    ...requestTransportOptions,
-                }
-                : requestTransportOptions;
-            const stream = Object.keys(streamOptions).length > 0
-                ? anthropic.messages.stream(messageParams, streamOptions)
+            this.logger.info(`Making Anthropic streaming API call for model: ${request.modelId}`, {
+                useStructuredOutput,
+            });
+            // No beta header for structured output - output_config.format is GA.
+            const stream = Object.keys(requestTransportOptions).length > 0
+                ? anthropic.messages.stream(messageParams, requestTransportOptions)
                 : anthropic.messages.stream(messageParams);
             for await (const event of stream) {
                 sawEvent = true;
@@ -254,20 +238,22 @@ class AnthropicClientAdapter {
                 stop_sequences: request.settings.stopSequences,
             }),
         };
-        // Handle structured output configuration for Anthropic
-        // Note: Structured output requires the beta API endpoint
+        // Handle structured output configuration for Anthropic.
+        // Structured outputs are generally available: the stable request field is
+        // output_config.format, with no beta header. The format object carries only
+        // `type` and `schema` - the generic StructuredOutputSettings `name` and
+        // `strict` fields exist for other providers and are not serialized here.
         if (useStructuredOutput) {
             const so = request.settings.structuredOutput;
             // Anthropic requires additionalProperties: false on all object schemas
             const processedSchema = so.strict !== false
                 ? this.addAdditionalPropertiesFalse(so.schema)
-                : so.schema;
-            // Anthropic's format: output_format.schema is the schema directly
-            messageParams.output_format = {
-                type: 'json_schema',
-                name: so.name,
-                schema: processedSchema,
-                strict: so.strict !== false,
+                : { ...so.schema };
+            messageParams.output_config = {
+                format: {
+                    type: "json_schema",
+                    schema: processedSchema,
+                },
             };
         }
         // Handle reasoning/thinking configuration for Claude models

package/dist/llm/config.js

@@ -873,6 +873,10 @@ exports.SUPPORTED_MODELS = [
             outputType: 'summary',
             requiresStreamingAbove: 21333,
         },
+        structuredOutput: {
+            supported: true,
+            strictMode: true,
+        },
     },
     {
         id: "claude-sonnet-4-5-20250929",
@@ -897,6 +901,10 @@ exports.SUPPORTED_MODELS = [
             outputType: 'summary',
             requiresStreamingAbove: 21333,
         },
+        structuredOutput: {
+            supported: true,
+            strictMode: true,
+        },
     },
     {
         id: "claude-haiku-4-5-20251001",
@@ -921,8 +929,14 @@ exports.SUPPORTED_MODELS = [
             outputType: 'summary',
             requiresStreamingAbove: 21333,
         },
+        structuredOutput: {
+            supported: true,
+            strictMode: true,
+        },
     },
     // Anthropic Models - Claude 4 Series
+    // Note: Anthropic's structured outputs are generally available for Claude 4.5
+    // and later models only, so the entries below declare it unsupported.
     {
         id: "claude-sonnet-4-20250514",
         name: "Claude Sonnet 4",
@@ -946,6 +960,10 @@ exports.SUPPORTED_MODELS = [
             outputType: 'summary',
             requiresStreamingAbove: 21333,
         },
+        structuredOutput: {
+            supported: false,
+            notes: "Anthropic structured outputs require Claude 4.5 or later",
+        },
     },
     {
         id: "claude-opus-4-20250514",
@@ -970,6 +988,10 @@ exports.SUPPORTED_MODELS = [
             outputType: 'summary',
             requiresStreamingAbove: 21333,
         },
+        structuredOutput: {
+            supported: false,
+            notes: "Anthropic structured outputs require Claude 4.5 or later",
+        },
     },
     {
         id: "claude-3-7-sonnet-20250219",
@@ -994,6 +1016,10 @@ exports.SUPPORTED_MODELS = [
             outputType: 'full',
             requiresStreamingAbove: 21333,
         },
+        structuredOutput: {
+            supported: false,
+            notes: "Anthropic structured outputs require Claude 4.5 or later",
+        },
     },
     {
         id: "claude-3-5-sonnet-20241022",
@@ -1008,6 +1034,10 @@ exports.SUPPORTED_MODELS = [
         supportsPromptCache: true,
         cacheWritesPrice: 3.75,
         cacheReadsPrice: 0.3,
+        structuredOutput: {
+            supported: false,
+            notes: "Anthropic structured outputs require Claude 4.5 or later",
+        },
     },
     {
         id: "claude-3-5-haiku-20241022",
@@ -1022,6 +1052,10 @@ exports.SUPPORTED_MODELS = [
         supportsPromptCache: true,
         cacheWritesPrice: 1.0,
         cacheReadsPrice: 0.08,
+        structuredOutput: {
+            supported: false,
+            notes: "Anthropic structured outputs require Claude 4.5 or later",
+        },
     },
     // Google Gemini Models - Gemini 3 Series (Preview)
     {

package/dist/llm/services/ModelResolver.d.ts

@@ -23,6 +23,17 @@ export interface ModelResolution {
     settings?: LLMSettings;
     error?: LLMFailureResponse;
 }
+/**
+ * Options controlling model resolution side effects.
+ */
+export interface ModelResolutionOptions {
+    /**
+     * Whether resolution may query local provider adapters for dynamic model
+     * capabilities. Defaults to true for sendMessage(), but public capability
+     * preflight uses false so it remains no-network/no-adapter.
+     */
+    detectLocalCapabilities?: boolean;
+}
 /**
  * Resolves model information from presets or direct provider/model IDs
  */
@@ -37,7 +48,7 @@ export declare class ModelResolver {
      * @param options Options containing either presetId or providerId/modelId
      * @returns Resolved model info and settings or error response
      */
-    resolve(options: ModelSelectionOptions): Promise<ModelResolution>;
+    resolve(options: ModelSelectionOptions, resolutionOptions?: ModelResolutionOptions): Promise<ModelResolution>;
     /**
      * Asks the llama.cpp adapter which GGUF model the server has loaded and returns
      * its detected capabilities (cached inside the adapter). Returns undefined when

package/dist/llm/services/ModelResolver.js

@@ -18,7 +18,8 @@ class ModelResolver {
      * @param options Options containing either presetId or providerId/modelId
      * @returns Resolved model info and settings or error response
      */
-    async resolve(options) {
+    async resolve(options, resolutionOptions = {}) {
+        const detectLocalCapabilities = resolutionOptions.detectLocalCapabilities !== false;
         // If presetId is provided, use it
         if (options.presetId) {
             const preset = this.presetManager.resolvePreset(options.presetId);
@@ -53,7 +54,7 @@ class ModelResolver {
             }
             // Overlay detected GGUF capabilities for llama.cpp presets (the server decides
             // which model is actually loaded, regardless of the preset's modelId)
-            if (preset.providerId === 'llamacpp') {
+            if (preset.providerId === 'llamacpp' && detectLocalCapabilities) {
                 const detected = await this.detectLlamaCppCapabilities();
                 if (detected) {
                     modelInfo = { ...modelInfo, ...detected };
@@ -108,7 +109,7 @@ class ModelResolver {
         // decides which model is actually loaded, so detected capabilities and vendor
         // default settings must overlay whatever the registry says.
         let detectedCapabilities;
-        if (options.providerId === 'llamacpp') {
+        if (options.providerId === 'llamacpp' && detectLocalCapabilities) {
             detectedCapabilities = await this.detectLlamaCppCapabilities();
         }
         if (modelInfo) {

package/dist/llm/types.d.ts

@@ -119,6 +119,38 @@ export interface ModelStructuredOutputCapabilities {
     /** Additional notes about the model's structured output support */
     notes?: string;
 }
+/**
+ * Capability support status for provider/model features.
+ *
+ * `unknown` means genai-lite does not have explicit metadata for the feature.
+ * Callers should decide whether to allow, reject, or fall back for unknown
+ * capabilities.
+ */
+export type CapabilityStatus = "supported" | "unsupported" | "unknown";
+/**
+ * Source of a capability decision.
+ */
+export type CapabilitySource = "registry" | "detected" | "fallback";
+/**
+ * Structured-output support status for a provider/model pair.
+ */
+export interface StructuredOutputSupport {
+    /** Whether structured output is known supported, known unsupported, or unknown */
+    status: CapabilityStatus;
+    /** Whether strict provider-side schema enforcement is supported, when known */
+    strictMode?: boolean;
+    /** Additional notes from model metadata */
+    notes?: string;
+    /** Where the capability decision came from */
+    source: CapabilitySource;
+}
+/**
+ * Capability summary for a provider/model pair.
+ */
+export interface ModelCapabilities {
+    /** Structured-output support status */
+    structuredOutput: StructuredOutputSupport;
+}
 /**
  * Message roles supported by LLM APIs
  */
@@ -427,6 +459,35 @@ export interface LLMChatRequestWithPreset extends Omit<LLMChatRequest, 'provider
     /** Preset ID (alternative to providerId/modelId) */
     presetId?: string;
 }
+/**
+ * Request used by LLMService.validateRequestCapabilities().
+ *
+ * This intentionally does not require messages: callers often need to validate
+ * provider/model/settings compatibility during configuration, before the final
+ * prompt messages exist.
+ */
+export interface LLMRequestCapabilityPreflight {
+    /** Provider ID (required if not using presetId) */
+    providerId?: ApiProviderId;
+    /** Model ID (required if not using presetId) */
+    modelId?: string;
+    /** Preset ID (alternative to providerId/modelId) */
+    presetId?: string;
+    /** Settings whose provider/model capability requirements should be checked */
+    settings?: LLMSettings;
+}
+/**
+ * Result of LLMService.getModelCapabilities().
+ */
+export interface ModelCapabilitiesResult {
+    object: "model.capabilities";
+    provider: ApiProviderId;
+    model: string;
+    /** Resolved model metadata used to derive the capability summary */
+    modelInfo: ModelInfo;
+    /** Structured-output support status for this provider/model pair */
+    structuredOutput: StructuredOutputSupport;
+}
 /**
  * Individual choice in an LLM response
  */
@@ -496,6 +557,30 @@ export interface LLMFailureResponse {
     /** The partial response that was generated before the error occurred (if available) */
     partialResponse?: Omit<LLMResponse, 'object'>;
 }
+/**
+ * Successful result of LLMService.validateRequestCapabilities().
+ */
+export interface LLMRequestCapabilityValidationSuccess {
+    object: "capability.validation";
+    valid: true;
+    provider: ApiProviderId;
+    model: string;
+    capabilities: ModelCapabilities;
+}
+/**
+ * Failure result of LLMService.validateRequestCapabilities().
+ *
+ * The base error envelope intentionally matches LLMFailureResponse so callers
+ * can use the same diagnostic handling as sendMessage().
+ */
+export type LLMRequestCapabilityValidationFailure = LLMFailureResponse & {
+    valid: false;
+    capabilities?: ModelCapabilities;
+};
+/**
+ * Result of LLMService.validateRequestCapabilities().
+ */
+export type LLMRequestCapabilityValidationResult = LLMRequestCapabilityValidationSuccess | LLMRequestCapabilityValidationFailure;
 /**
  * Streaming event emitted by LLMService.streamMessage().
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genai-lite",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "A lightweight, portable toolkit for interacting with various Generative AI APIs.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",