genai-lite 0.6.1 → 0.7.2

package/dist/llm/services/SettingsManager.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SettingsManager = void 0;
+const defaultLogger_1 = require("../../logging/defaultLogger");
 const config_1 = require("../config");
 /**
  * Manages LLM settings including merging with defaults and filtering unsupported parameters
  */
 class SettingsManager {
+    constructor(logger) {
+        this.logger = logger ?? (0, defaultLogger_1.createDefaultLogger)();
+    }
     /**
      * Merges request settings with model-specific and global defaults
      *
@@ -28,6 +32,10 @@ class SettingsManager {
             user: requestSettings?.user ?? modelDefaults.user,
             supportsSystemMessage: requestSettings?.supportsSystemMessage ??
                 modelDefaults.supportsSystemMessage,
+            systemMessageFallback: {
+                ...modelDefaults.systemMessageFallback,
+                ...requestSettings?.systemMessageFallback,
+            },
             geminiSafetySettings: requestSettings?.geminiSafetySettings ??
                 modelDefaults.geminiSafetySettings,
             reasoning: {
@@ -38,9 +46,10 @@ class SettingsManager {
                 ...modelDefaults.thinkingTagFallback,
                 ...requestSettings?.thinkingTagFallback,
             },
+            openRouterProvider: requestSettings?.openRouterProvider ?? modelDefaults.openRouterProvider,
         };
         // Log the final settings for debugging
-        console.log(`Merged settings for ${providerId}/${modelId}:`, {
+        this.logger.debug(`Merged settings for ${providerId}/${modelId}:`, {
             temperature: mergedSettings.temperature,
             maxTokens: mergedSettings.maxTokens,
             topP: mergedSettings.topP,
@@ -74,23 +83,23 @@ class SettingsManager {
             modelInfo.unsupportedParameters.forEach((param) => paramsToExclude.add(param));
         }
         if (paramsToExclude.size > 0) {
-            console.log(`LLMService: Potential parameters to exclude for provider '${providerInfo.id}', model '${modelInfo.id}':`, Array.from(paramsToExclude));
+            this.logger.debug(`LLMService: Potential parameters to exclude for provider '${providerInfo.id}', model '${modelInfo.id}':`, Array.from(paramsToExclude));
         }
         paramsToExclude.forEach((param) => {
             // Check if the parameter key actually exists in filteredSettings before trying to delete
             if (param in filteredSettings) {
-                console.log(`LLMService: Removing excluded parameter '${String(param)}' for provider '${providerInfo.id}', model '${modelInfo.id}'. Value was:`, filteredSettings[param]);
+                this.logger.debug(`LLMService: Removing excluded parameter '${String(param)}' for provider '${providerInfo.id}', model '${modelInfo.id}'. Value was:`, filteredSettings[param]);
                 delete filteredSettings[param]; // Cast to allow deletion
             }
             else {
                 // This case should ideally not happen if settings truly is Required<LLMSettings>
-                console.log(`LLMService: Parameter '${String(param)}' marked for exclusion was not found in settings for provider '${providerInfo.id}', model '${modelInfo.id}'.`);
+                this.logger.debug(`LLMService: Parameter '${String(param)}' marked for exclusion was not found in settings for provider '${providerInfo.id}', model '${modelInfo.id}'.`);
             }
         });
         // Handle reasoning settings for models that don't support it
         // This happens after validateReasoningSettings so we know it's safe to strip
         if (!modelInfo.reasoning?.supported && filteredSettings.reasoning) {
-            console.log(`LLMService: Removing reasoning settings for non-reasoning model ${modelInfo.id}`);
+            this.logger.debug(`LLMService: Removing reasoning settings for non-reasoning model ${modelInfo.id}`);
             delete filteredSettings.reasoning;
         }
         return filteredSettings;
@@ -121,71 +130,71 @@ class SettingsManager {
         for (const [key, value] of Object.entries(settings)) {
             // Check if it's a known field
             if (!knownFields.includes(key)) {
-                console.warn(`Unknown setting "${key}" in template metadata. Ignoring.`);
+                this.logger.warn(`Unknown setting "${key}" in template metadata. Ignoring.`);
                 continue;
             }
             // Type-specific validation
             if (key === 'temperature') {
                 if (typeof value !== 'number' || value < 0 || value > 2) {
-                    console.warn(`Invalid temperature value in template: ${value}. Must be a number between 0 and 2.`);
+                    this.logger.warn(`Invalid temperature value in template: ${value}. Must be a number between 0 and 2.`);
                     continue;
                 }
             }
             if (key === 'maxTokens') {
                 if (typeof value !== 'number' || value <= 0) {
-                    console.warn(`Invalid maxTokens value in template: ${value}. Must be a positive number.`);
+                    this.logger.warn(`Invalid maxTokens value in template: ${value}. Must be a positive number.`);
                     continue;
                 }
             }
             if (key === 'topP') {
                 if (typeof value !== 'number' || value < 0 || value > 1) {
-                    console.warn(`Invalid topP value in template: ${value}. Must be a number between 0 and 1.`);
+                    this.logger.warn(`Invalid topP value in template: ${value}. Must be a number between 0 and 1.`);
                     continue;
                 }
             }
             if (key === 'stopSequences') {
                 if (!Array.isArray(value) || !value.every(v => typeof v === 'string')) {
-                    console.warn(`Invalid stopSequences value in template. Must be an array of strings.`);
+                    this.logger.warn(`Invalid stopSequences value in template. Must be an array of strings.`);
                     continue;
                 }
             }
             if ((key === 'frequencyPenalty' || key === 'presencePenalty')) {
                 if (typeof value !== 'number' || value < -2 || value > 2) {
-                    console.warn(`Invalid ${key} value in template: ${value}. Must be a number between -2 and 2.`);
+                    this.logger.warn(`Invalid ${key} value in template: ${value}. Must be a number between -2 and 2.`);
                     continue;
                 }
             }
             if (key === 'user' && typeof value !== 'string') {
-                console.warn(`Invalid user value in template. Must be a string.`);
+                this.logger.warn(`Invalid user value in template. Must be a string.`);
                 continue;
             }
             if (key === 'supportsSystemMessage' && typeof value !== 'boolean') {
-                console.warn(`Invalid supportsSystemMessage value in template. Must be a boolean.`);
+                this.logger.warn(`Invalid supportsSystemMessage value in template. Must be a boolean.`);
                 continue;
             }
             // Nested object validation
             if (key === 'reasoning' && typeof value === 'object' && value !== null) {
                 const reasoningValidated = {};
                 if ('enabled' in value && typeof value.enabled !== 'boolean') {
-                    console.warn(`Invalid reasoning.enabled value in template. Must be a boolean.`);
+                    this.logger.warn(`Invalid reasoning.enabled value in template. Must be a boolean.`);
                 }
                 else if ('enabled' in value) {
                     reasoningValidated.enabled = value.enabled;
                 }
                 if ('effort' in value && !['low', 'medium', 'high'].includes(value.effort)) {
-                    console.warn(`Invalid reasoning.effort value in template: ${value.effort}. Must be 'low', 'medium', or 'high'.`);
+                    this.logger.warn(`Invalid reasoning.effort value in template: ${value.effort}. Must be 'low', 'medium', or 'high'.`);
                 }
                 else if ('effort' in value) {
                     reasoningValidated.effort = value.effort;
                 }
                 if ('maxTokens' in value && (typeof value.maxTokens !== 'number' || value.maxTokens <= 0)) {
-                    console.warn(`Invalid reasoning.maxTokens value in template. Must be a positive number.`);
+                    this.logger.warn(`Invalid reasoning.maxTokens value in template. Must be a positive number.`);
                 }
                 else if ('maxTokens' in value) {
                     reasoningValidated.maxTokens = value.maxTokens;
                 }
                 if ('exclude' in value && typeof value.exclude !== 'boolean') {
-                    console.warn(`Invalid reasoning.exclude value in template. Must be a boolean.`);
+                    this.logger.warn(`Invalid reasoning.exclude value in template. Must be a boolean.`);
                 }
                 else if ('exclude' in value) {
                     reasoningValidated.exclude = value.exclude;
@@ -198,19 +207,19 @@ class SettingsManager {
             if (key === 'thinkingTagFallback' && typeof value === 'object' && value !== null) {
                 const thinkingValidated = {};
                 if ('enabled' in value && typeof value.enabled !== 'boolean') {
-                    console.warn(`Invalid thinkingTagFallback.enabled value in template. Must be a boolean.`);
+                    this.logger.warn(`Invalid thinkingTagFallback.enabled value in template. Must be a boolean.`);
                 }
                 else if ('enabled' in value) {
                     thinkingValidated.enabled = value.enabled;
                 }
                 if ('tagName' in value && typeof value.tagName !== 'string') {
-                    console.warn(`Invalid thinkingTagFallback.tagName value in template. Must be a string.`);
+                    this.logger.warn(`Invalid thinkingTagFallback.tagName value in template. Must be a string.`);
                 }
                 else if ('tagName' in value) {
                     thinkingValidated.tagName = value.tagName;
                 }
                 if ('enforce' in value && typeof value.enforce !== 'boolean') {
-                    console.warn(`Invalid thinkingTagFallback.enforce value in template. Must be a boolean.`);
+                    this.logger.warn(`Invalid thinkingTagFallback.enforce value in template. Must be a boolean.`);
                 }
                 else if ('enforce' in value) {
                     thinkingValidated.enforce = value.enforce;

package/dist/llm/types.d.ts

@@ -83,6 +83,74 @@ export interface LLMThinkingTagFallbackSettings {
      */
     enforce?: boolean;
 }
+/**
+ * Format options for prepending system content when model doesn't support system messages.
+ * - 'xml': Wrap in XML tags (default) - `<system>content</system>\n\n{user message}`
+ * - 'separator': Use a simple separator - `{content}\n\n---\n\n{user message}`
+ * - 'plain': Just prepend with double newline - `{content}\n\n{user message}`
+ */
+export type SystemMessageFallbackFormat = 'xml' | 'separator' | 'plain';
+/**
+ * Settings for handling system messages when the model doesn't support them natively.
+ * When a model has `supportsSystemMessage: false`, these settings control how
+ * system content is formatted when prepended to the first user message.
+ */
+export interface SystemMessageFallbackSettings {
+    /**
+     * Format to use when prepending system content to user message.
+     * @default 'xml'
+     */
+    format?: SystemMessageFallbackFormat;
+    /**
+     * Tag name to use when format is 'xml'.
+     * @default 'system'
+     * @example tagName: 'instructions' produces `<instructions>content</instructions>`
+     */
+    tagName?: string;
+    /**
+     * Separator string to use when format is 'separator'.
+     * @default '---'
+     */
+    separator?: string;
+}
+/**
+ * OpenRouter-specific provider routing settings
+ *
+ * These settings allow controlling which underlying providers serve requests
+ * when using OpenRouter. All fields are optional - by default, OpenRouter
+ * automatically selects the best provider based on price, latency, and availability.
+ *
+ * @see https://openrouter.ai/docs/provider-routing
+ */
+export interface OpenRouterProviderSettings {
+    /**
+     * Provider priority order. OpenRouter will try providers in this order.
+     * @example order: ["Together", "Fireworks", "Lepton"]
+     */
+    order?: string[];
+    /**
+     * Providers to exclude from serving this request.
+     * @example ignore: ["Azure", "OpenAI"]
+     */
+    ignore?: string[];
+    /**
+     * Providers to allow exclusively. If set, only these providers can serve the request.
+     * @example allow: ["Together", "Fireworks"]
+     */
+    allow?: string[];
+    /**
+     * Control whether providers can use your prompts for training.
+     * Set to 'deny' to opt out of data collection by providers.
+     * @default undefined (provider's default behavior)
+     */
+    dataCollection?: 'deny' | 'allow';
+    /**
+     * If true, only route to providers that support all parameters in your request.
+     * Useful when using provider-specific features.
+     * @default false
+     */
+    requireParameters?: boolean;
+}
 /**
  * Configurable settings for LLM requests
  */
@@ -103,6 +171,11 @@ export interface LLMSettings {
     user?: string;
     /** Whether the LLM supports system message (almost all LLMs do nowadays) */
     supportsSystemMessage?: boolean;
+    /**
+     * Settings for handling system messages when the model doesn't support them.
+     * Controls how system content is formatted when prepended to user messages.
+     */
+    systemMessageFallback?: SystemMessageFallbackSettings;
     /** Gemini-specific safety settings for content filtering */
     geminiSafetySettings?: GeminiSafetySetting[];
     /** Universal reasoning/thinking configuration */
@@ -121,6 +194,12 @@ export interface LLMSettings {
      * The library only extracts them - it doesn't generate them automatically.
      */
     thinkingTagFallback?: LLMThinkingTagFallbackSettings;
+    /**
+     * OpenRouter-specific provider routing settings.
+     * Only used when providerId is 'openrouter'.
+     * @see OpenRouterProviderSettings
+     */
+    openRouterProvider?: OpenRouterProviderSettings;
 }
 /**
  * Request structure for chat completion

package/dist/logging/defaultLogger.d.ts

@@ -0,0 +1,35 @@
+import type { Logger, LogLevel } from './types';
+/**
+ * The default log level, read once at module initialization.
+ * Can be overridden per-service via constructor options.
+ */
+export declare const DEFAULT_LOG_LEVEL: LogLevel;
+/**
+ * Creates a default console-based logger with level filtering.
+ *
+ * @param level - The minimum log level to output (defaults to env var or 'warn')
+ * @returns A Logger instance that filters messages below the specified level
+ *
+ * @example
+ * ```typescript
+ * const logger = createDefaultLogger('debug');
+ * logger.debug('This will be shown');
+ * logger.info('This will be shown');
+ *
+ * const quietLogger = createDefaultLogger('error');
+ * quietLogger.debug('This will be suppressed');
+ * quietLogger.info('This will be suppressed');
+ * quietLogger.error('This will be shown');
+ * ```
+ */
+export declare function createDefaultLogger(level?: LogLevel): Logger;
+/**
+ * A silent logger that discards all output.
+ * Useful for testing or when logging should be completely disabled.
+ *
+ * @example
+ * ```typescript
+ * const service = new LLMService(apiKeyProvider, { logger: silentLogger });
+ * ```
+ */
+export declare const silentLogger: Logger;

package/dist/logging/defaultLogger.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silentLogger = exports.DEFAULT_LOG_LEVEL = void 0;
+exports.createDefaultLogger = createDefaultLogger;
+/**
+ * Numeric values for log levels (higher = more verbose)
+ */
+const LOG_LEVEL_VALUES = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+/**
+ * Valid log level strings for validation
+ */
+const VALID_LOG_LEVELS = new Set(['silent', 'error', 'warn', 'info', 'debug']);
+/**
+ * Reads the default log level from environment variable.
+ * Called once at module load time.
+ *
+ * @returns The log level from GENAI_LITE_LOG_LEVEL or 'warn' as default
+ */
+function getDefaultLogLevelFromEnv() {
+    const envLevel = process.env.GENAI_LITE_LOG_LEVEL?.toLowerCase();
+    if (envLevel && VALID_LOG_LEVELS.has(envLevel)) {
+        return envLevel;
+    }
+    return 'warn'; // Sensible default: errors + warnings
+}
+/**
+ * The default log level, read once at module initialization.
+ * Can be overridden per-service via constructor options.
+ */
+exports.DEFAULT_LOG_LEVEL = getDefaultLogLevelFromEnv();
+/**
+ * Creates a default console-based logger with level filtering.
+ *
+ * @param level - The minimum log level to output (defaults to env var or 'warn')
+ * @returns A Logger instance that filters messages below the specified level
+ *
+ * @example
+ * ```typescript
+ * const logger = createDefaultLogger('debug');
+ * logger.debug('This will be shown');
+ * logger.info('This will be shown');
+ *
+ * const quietLogger = createDefaultLogger('error');
+ * quietLogger.debug('This will be suppressed');
+ * quietLogger.info('This will be suppressed');
+ * quietLogger.error('This will be shown');
+ * ```
+ */
+function createDefaultLogger(level = exports.DEFAULT_LOG_LEVEL) {
+    const threshold = LOG_LEVEL_VALUES[level];
+    return {
+        debug(message, ...args) {
+            if (threshold >= LOG_LEVEL_VALUES.debug) {
+                console.log(`[genai-lite:debug] ${message}`, ...args);
+            }
+        },
+        info(message, ...args) {
+            if (threshold >= LOG_LEVEL_VALUES.info) {
+                console.log(`[genai-lite:info] ${message}`, ...args);
+            }
+        },
+        warn(message, ...args) {
+            if (threshold >= LOG_LEVEL_VALUES.warn) {
+                console.warn(`[genai-lite:warn] ${message}`, ...args);
+            }
+        },
+        error(message, ...args) {
+            if (threshold >= LOG_LEVEL_VALUES.error) {
+                console.error(`[genai-lite:error] ${message}`, ...args);
+            }
+        },
+    };
+}
+/**
+ * A silent logger that discards all output.
+ * Useful for testing or when logging should be completely disabled.
+ *
+ * @example
+ * ```typescript
+ * const service = new LLMService(apiKeyProvider, { logger: silentLogger });
+ * ```
+ */
+exports.silentLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};

package/dist/logging/index.d.ts

@@ -0,0 +1,2 @@
+export type { Logger, LogLevel, LoggingConfig } from './types';
+export { createDefaultLogger, DEFAULT_LOG_LEVEL, silentLogger, } from './defaultLogger';

package/dist/logging/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silentLogger = exports.DEFAULT_LOG_LEVEL = exports.createDefaultLogger = void 0;
+var defaultLogger_1 = require("./defaultLogger");
+Object.defineProperty(exports, "createDefaultLogger", { enumerable: true, get: function () { return defaultLogger_1.createDefaultLogger; } });
+Object.defineProperty(exports, "DEFAULT_LOG_LEVEL", { enumerable: true, get: function () { return defaultLogger_1.DEFAULT_LOG_LEVEL; } });
+Object.defineProperty(exports, "silentLogger", { enumerable: true, get: function () { return defaultLogger_1.silentLogger; } });

package/dist/logging/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Log level type - ordered from most quiet to most verbose
+ */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * Logger interface compatible with popular logging libraries
+ * (pino, winston, bunyan, console all have these methods)
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Configuration for the logging system
+ */
+export interface LoggingConfig {
+    /** Log level threshold - messages below this level are suppressed */
+    level: LogLevel;
+    /** Custom logger implementation (optional) */
+    logger?: Logger;
+}

package/dist/logging/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/prompting/parser.js

@@ -10,6 +10,9 @@ exports.parseStructuredContent = parseStructuredContent;
 exports.extractInitialTaggedContent = extractInitialTaggedContent;
 exports.parseRoleTags = parseRoleTags;
 exports.parseTemplateWithMetadata = parseTemplateWithMetadata;
+const defaultLogger_1 = require("../logging/defaultLogger");
+// Module-level logger for utility functions
+const logger = (0, defaultLogger_1.createDefaultLogger)();
 /**
  * Parses a string containing structured data wrapped in custom XML-style tags.
  *
@@ -183,7 +186,7 @@ function parseTemplateWithMetadata(template) {
     catch (error) {
         // If the JSON is invalid, we warn the developer and treat the <META> block
         // as regular text to avoid crashing.
-        console.warn('Could not parse <META> block in template. Treating it as content.', error);
+        logger.warn('Could not parse <META> block in template. Treating it as content.', error);
         return { metadata: { settings: {} }, content: template };
     }
 }

package/dist/shared/adapters/systemMessageUtils.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Format options for prepending system content when model doesn't support system messages.
+ * - 'xml': Wrap in XML tags (default) - `<system>content</system>\n\n{user message}`
+ * - 'separator': Use a custom separator string - `{content}{separator}{user message}`
+ *   Default separator is `\n\n---\n\n`. Specify full separator including whitespace.
+ * - 'plain': Just prepend with double newline - `{content}\n\n{user message}`
+ */
+export type SystemMessageFallbackFormat = 'xml' | 'separator' | 'plain';
+/**
+ * Options for formatting system content when prepending to user messages
+ */
+export interface SystemMessageFormatOptions {
+    /**
+     * Format to use when prepending system content to user message.
+     * @default 'xml'
+     */
+    format?: SystemMessageFallbackFormat;
+    /**
+     * Tag name to use when format is 'xml'.
+     * @default 'system'
+     * @example tagName: 'instructions' produces `<instructions>content</instructions>`
+     */
+    tagName?: string;
+    /**
+     * Separator string to use when format is 'separator'.
+     * Include any whitespace/newlines in the separator itself.
+     * @default '\n\n---\n\n'
+     * @example separator: '\n\n===\n\n' produces `content\n\n===\n\nuser message`
+     */
+    separator?: string;
+}
+/**
+ * Result of collecting system content for fallback handling
+ */
+export interface SystemContentResult {
+    /** Combined system content from all sources */
+    combinedSystemContent: string | undefined;
+    /** Whether to use native system message support */
+    useNativeSystemMessage: boolean;
+}
+/**
+ * Generic message interface for system message handling
+ */
+export interface GenericMessage {
+    role: string;
+    content: string;
+}
+/**
+ * Default format options for system message fallback
+ */
+export declare const DEFAULT_SYSTEM_MESSAGE_FORMAT_OPTIONS: Required<SystemMessageFormatOptions>;
+/**
+ * Formats system content according to the specified format options.
+ *
+ * @param systemContent - The system content to format
+ * @param userContent - The original user message content
+ * @param options - Format options (defaults to XML with 'system' tag)
+ * @returns The formatted combined content
+ *
+ * @example
+ * ```typescript
+ * // XML format (default)
+ * formatSystemContentForPrepend('Be helpful', 'Hello', { format: 'xml' });
+ * // Returns: '<system>\nBe helpful\n</system>\n\nHello'
+ *
+ * // Separator format (default separator is '\n\n---\n\n')
+ * formatSystemContentForPrepend('Be helpful', 'Hello', { format: 'separator' });
+ * // Returns: 'Be helpful\n\n---\n\nHello'
+ *
+ * // Custom separator (specify full separator including whitespace)
+ * formatSystemContentForPrepend('Be helpful', 'Hello', { format: 'separator', separator: '\n\n===\n\n' });
+ * // Returns: 'Be helpful\n\n===\n\nHello'
+ *
+ * // Plain format
+ * formatSystemContentForPrepend('Be helpful', 'Hello', { format: 'plain' });
+ * // Returns: 'Be helpful\n\nHello'
+ * ```
+ */
+export declare function formatSystemContentForPrepend(systemContent: string, userContent: string, options?: SystemMessageFormatOptions): string;
+/**
+ * Collects and combines system content from multiple sources.
+ *
+ * Combines the request-level systemMessage with any inline system messages
+ * from the messages array into a single string.
+ *
+ * @param requestSystemMessage - The request.systemMessage field (if any)
+ * @param inlineSystemMessages - Array of system message contents from the messages array
+ * @param supportsSystemMessage - Whether the model supports native system messages
+ * @returns Object with combined content and whether to use native support
+ *
+ * @example
+ * ```typescript
+ * const { combinedSystemContent, useNativeSystemMessage } = collectSystemContent(
+ *   'You are helpful',
+ *   ['Be concise'],
+ *   false // Model doesn't support system messages
+ * );
+ * // combinedSystemContent = 'You are helpful\n\nBe concise'
+ * // useNativeSystemMessage = false
+ * ```
+ */
+export declare function collectSystemContent(requestSystemMessage: string | undefined, inlineSystemMessages: string[], supportsSystemMessage: boolean): SystemContentResult;
+/**
+ * Prepends system content to the first user message in an array.
+ *
+ * This is used as a fallback for models that don't support native system
+ * instructions. The system content is formatted according to the options
+ * and prepended to the first user message.
+ *
+ * @param messages - Array of message objects with role and content
+ * @param systemContent - System content to prepend
+ * @param options - Format options (defaults to XML with 'system' tag)
+ * @returns The index of the modified message, or -1 if no user message found
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { role: 'user', content: 'Hello' },
+ *   { role: 'assistant', content: 'Hi!' }
+ * ];
+ *
+ * // Default (XML format)
+ * prependSystemToFirstUserMessage(messages, 'Be helpful');
+ * // messages[0].content = '<system>\nBe helpful\n</system>\n\nHello'
+ *
+ * // Plain format
+ * prependSystemToFirstUserMessage(messages, 'Be helpful', { format: 'plain' });
+ * // messages[0].content = 'Be helpful\n\nHello'
+ *
+ * // Separator format (default separator is '\n\n---\n\n')
+ * prependSystemToFirstUserMessage(messages, 'Be helpful', { format: 'separator' });
+ * // messages[0].content = 'Be helpful\n\n---\n\nHello'
+ * ```
+ */
+export declare function prependSystemToFirstUserMessage<T extends GenericMessage>(messages: T[], systemContent: string, options?: SystemMessageFormatOptions): number;
+/**
+ * Filters system messages from an array and returns non-system messages
+ * along with collected system content.
+ *
+ * This is a convenience function that combines message filtering with
+ * system content collection in a single pass.
+ *
+ * @param messages - Array of messages to process
+ * @param requestSystemMessage - Optional request-level system message
+ * @param supportsSystemMessage - Whether the model supports native system messages
+ * @returns Object with filtered messages and system content handling info
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { role: 'system', content: 'Be helpful' },
+ *   { role: 'user', content: 'Hello' }
+ * ];
+ * const result = processMessagesForSystemSupport(messages, undefined, false);
+ * // result.nonSystemMessages = [{ role: 'user', content: 'Hello' }]
+ * // result.systemContent.combinedSystemContent = 'Be helpful'
+ * ```
+ */
+export declare function processMessagesForSystemSupport<T extends GenericMessage>(messages: T[], requestSystemMessage: string | undefined, supportsSystemMessage: boolean): {
+    nonSystemMessages: T[];
+    systemContent: SystemContentResult;
+};