genai-lite 0.12.0 → 0.13.0

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/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.0",
   "description": "A lightweight, portable toolkit for interacting with various Generative AI APIs.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",