@adaptic/lumic-utils 1.0.6 → 1.0.8

package/dist/types/functions/aws-lambda.d.ts

@@ -14,4 +14,4 @@ import { LambdaResponse, InvocationType } from '../types';
  * @throws If the Lambda function returns an invalid response
  * @returns A LambdaResponse object with a statusCode and a body
  */
-export declare const invokeLambdaFunction: (functionName: string, payload?: Record<string, any>, invocationType?: InvocationType, auth?: AWSAuth | null) => Promise<LambdaResponse>;
+export declare const invokeLambdaFunction: (functionName: string, payload?: Record<string, unknown>, invocationType?: InvocationType, auth?: AWSAuth | null) => Promise<LambdaResponse>;

package/dist/types/functions/aws-s3-utils.d.ts

@@ -31,7 +31,7 @@ export declare const createS3: (bucketName: string, auth?: AWSAuth | null) => Pr
 /**
  * Uploads a file or directory to an S3 bucket.
  * @param {string} bucketName - The name of the S3 bucket to upload to.
- * @param {string} sourcePath - The path to the file or directory to upload.
+ * @param {string} sourcePath - The path to the file or directory to upload. Must start with an allowed path (configurable via LUMIC_ALLOWED_UPLOAD_PATHS environment variable, defaults to '/tmp'). Path traversal (..) is not allowed.
  * @param {Object} [options] - Optional parameters.
  * @param {string} [options.destinationPath] - The path to the destination in the S3 bucket.
  * @param {AWSAuth} [options.auth] - Optional AWS credentials to use for the operation. If not provided, the AWS SDK will use the default credential provider chain.
@@ -59,7 +59,7 @@ export declare function readS3File(bucket: string, key: string, auth?: AWSAuth |
  * Downloads files from S3 to a local directory.
  * @param {string} bucketName - The name of the S3 bucket to download from.
  * @param {string} [s3Path=''] - The path in the S3 bucket to start downloading from. Defaults to the root of the bucket.
- * @param {string} [localPath='/tmp'] - The local directory to download the files to. Defaults to '/tmp'.
+ * @param {string} [localPath] - The local directory to download the files to. Defaults to os.tmpdir().
  * @param {AWSAuth} [auth] - Optional AWS credentials to use for the operation. If not provided, the AWS SDK will use the default credential provider chain.
  * @returns {Promise<AWSApiResponse>} - A Promise that resolves with an AWSApiResponse object.
  * @example

package/dist/types/functions/google-sheets.d.ts

@@ -1,4 +1,4 @@
-import { GoogleSheetConfig, GoogleSheetCell, GoogleSheetAddRowResponse, GoogleSheetAddSheetResponse, GoogleSheetCellResponse, GoogleSheetWriteArrayResponse } from '../types';
+import { GoogleSheetConfig, GoogleSheetCell, GoogleSheetCellValue, GoogleSheetAddRowResponse, GoogleSheetAddSheetResponse, GoogleSheetCellResponse, GoogleSheetWriteArrayResponse } from '../types';
 import 'dotenv/config';
 /**
  * Adds a row of values to the bottom of a specified Google Sheet
@@ -7,7 +7,7 @@ import 'dotenv/config';
  * @param startColumn Optional starting column (defaults to 'A')
  * @returns Promise resolving to response with success status and row details
  */
-export declare function addRow(config: GoogleSheetConfig, values: any[], startColumn?: string): Promise<GoogleSheetAddRowResponse>;
+export declare function addRow(config: GoogleSheetConfig, values: GoogleSheetCellValue[], startColumn?: string): Promise<GoogleSheetAddRowResponse>;
 /**
  * Adds a new sheet to an existing Google Spreadsheet
  * @param spreadsheetId The ID of the spreadsheet to add the sheet to
@@ -22,7 +22,7 @@ export declare function addSheet(spreadsheetId: string, sheetTitle: string): Pro
  * @param value The value to write
  * @returns Promise resolving to response with success status
  */
-export declare function writeCell(config: GoogleSheetConfig, cell: GoogleSheetCell, value: any): Promise<GoogleSheetCellResponse>;
+export declare function writeCell(config: GoogleSheetConfig, cell: GoogleSheetCell, value: GoogleSheetCellValue): Promise<GoogleSheetCellResponse>;
 /**
  * Gets the value from a specific cell in a Google Sheet
  * @param config The sheet configuration containing spreadsheetId and sheetName
@@ -37,4 +37,4 @@ export declare function getCell(config: GoogleSheetConfig, cell: GoogleSheetCell
  * @param startCell Optional starting cell in A1 notation (defaults to 'A1')
  * @returns Promise resolving to response with success status and update details
  */
-export declare function writeArray(config: GoogleSheetConfig, data: any[][], startCell?: string): Promise<GoogleSheetWriteArrayResponse>;
+export declare function writeArray(config: GoogleSheetConfig, data: GoogleSheetCellValue[][], startCell?: string): Promise<GoogleSheetWriteArrayResponse>;

package/dist/types/functions/json-llm-tools.d.ts

@@ -1,12 +1,34 @@
 import { JsonValue } from '../types';
+/**
+ * Options for AI-powered JSON fixing
+ */
+export interface FixJsonWithAIOptions {
+    /**
+     * The OpenAI API key to use, or undefined to use the value of the OPENAI_API_KEY environment variable
+     */
+    apiKey?: string;
+    /**
+     * Maximum recursion depth to prevent infinite loops.
+     * @default 2
+     */
+    maxDepth?: number;
+    /**
+     * Internal: Current recursion depth. Do not set manually.
+     * @internal
+     */
+    _depth?: number;
+}
 /**
  * Fixes broken JSON by sending it to the OpenAI gpt-5 model as a chat completion.
  * The gpt-5 model is a large language model that can understand and generate code,
  * including JSON. The returned JSON is the fixed version of the input JSON.
  * If the model fails to return valid JSON, an error is thrown.
+ *
+ * WARNING: This function uses AI and adds cost and latency. Use sparingly.
+ *
  * @param jsonStr - the broken JSON to fix
- * @param apiKey - the OpenAI API key to use, or undefined to use the value of the OPENAI_API_KEY environment variable
+ * @param options - configuration options including API key and recursion limits
  * @returns the fixed JSON
- * @throws an error if the model fails to return valid JSON
+ * @throws an error if the model fails to return valid JSON or max depth is exceeded
  */
-export declare function fixJsonWithAI(jsonStr: string, apiKey?: string): Promise<JsonValue>;
+export declare function fixJsonWithAI(jsonStr: string, options?: string | FixJsonWithAIOptions): Promise<JsonValue>;

package/dist/types/functions/llm-call.d.ts

@@ -9,7 +9,7 @@ import { Tool } from 'openai/resources/responses/responses';
  * @param options The options for the LLM call. Defaults to an empty object.
  * @return A promise that resolves to the response from the LLM.
  */
-export declare function makeLLMCall<T = any>(content: string | ChatCompletionContentPart[], responseFormat?: OpenAIResponseFormat, options?: LLMOptions): Promise<LLMResponse<T>>;
+export declare function makeLLMCall<T = unknown>(content: string | ChatCompletionContentPart[], responseFormat?: OpenAIResponseFormat, options?: LLMOptions): Promise<LLMResponse<T>>;
 /**
  * Makes a call to the OpenAI Responses API for advanced use cases with built-in tools.
  *
@@ -17,7 +17,7 @@ export declare function makeLLMCall<T = any>(content: string | ChatCompletionCon
  * @param options The options for the Responses API call, including optional image data.
  * @return A promise that resolves to the response from the Responses API.
  */
-export declare function makeResponsesCall<T = any>(input: string, options?: {
+export declare function makeResponsesCall<T = unknown>(input: string, options?: {
     apiKey?: string;
     model?: OpenAIModel;
     responseFormat?: 'text' | 'json';

package/dist/types/functions/llm-deepseek.d.ts

@@ -8,4 +8,4 @@ import { LLMResponse, LLMOptions, OpenAIResponseFormat } from '../types';
  * @param options Configuration options including model ('deepseek-chat' or 'deepseek-reasoner'), tools, and apiKey.
  * @return A promise that resolves to the response from the Deepseek API.
  */
-export declare const makeDeepseekCall: <T = any>(content: string | ChatCompletionContentPart[], responseFormat?: OpenAIResponseFormat, options?: LLMOptions) => Promise<LLMResponse<T>>;
+export declare const makeDeepseekCall: <T = unknown>(content: string | ChatCompletionContentPart[], responseFormat?: OpenAIResponseFormat, options?: LLMOptions) => Promise<LLMResponse<T>>;

package/dist/types/functions/llm-openai.d.ts

@@ -22,7 +22,7 @@ export declare function isReasoningModel(model: string): boolean;
  * @param options The options for the LLM call. Defaults to an empty object.
  * @return A promise that resolves to the response from the LLM.
  */
-export declare const makeOpenAIChatCompletionCall: <T = any>(content: string | ChatCompletionContentPart[], responseFormat?: OpenAIResponseFormat, options?: LLMOptions) => Promise<LLMResponse<T>>;
+export declare const makeOpenAIChatCompletionCall: <T = unknown>(content: string | ChatCompletionContentPart[], responseFormat?: OpenAIResponseFormat, options?: LLMOptions) => Promise<LLMResponse<T>>;
 /**
  * Makes a call to OpenAI's Responses API for more advanced use cases with built-in tools.
  *
@@ -49,7 +49,8 @@ export declare const makeOpenAIChatCompletionCall: <T = any>(content: string | C
  * @returns Promise<LLMResponse<T>> - The response in the same format as makeOpenAIChatCompletionCall
  * @throws Error if the API call fails
  */
-export declare const makeResponsesAPICall: <T = any>(input: string | ResponseCreateParamsNonStreaming["input"], options?: Omit<ResponseCreateParamsNonStreaming, "input" | "model"> & {
+export declare const makeResponsesAPICall: <T = unknown>(input: string | ResponseCreateParamsNonStreaming["input"], options?: Omit<ResponseCreateParamsNonStreaming, "input" | "model"> & {
     apiKey?: string;
     model?: string;
+    timeout?: number;
 }) => Promise<LLMResponse<T>>;

package/dist/types/functions/llm-utils.d.ts

@@ -1,6 +1,28 @@
 import { OpenAIResponseFormat } from '../types';
 export declare function normalizeModelName(model: string): string;
 export declare const CODE_BLOCK_TYPES: string[];
+/**
+ * Options for JSON parsing behavior
+ */
+export interface ParseJsonOptions {
+    /**
+     * Enable AI-powered JSON fixing as a fallback strategy.
+     * Warning: This adds cost and latency. Disabled by default.
+     * @default false
+     */
+    enableAiFix?: boolean;
+    /**
+     * Maximum number of times to retry AI fixing if it returns broken JSON.
+     * Only applies when enableAiFix is true.
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Internal: Current recursion depth. Do not set manually.
+     * @internal
+     */
+    _recursionDepth?: number;
+}
 /**
  * Tries to parse JSON from the given content string according to the specified
  * response format. If the response format is 'json' or a JSON schema object, it
@@ -10,6 +32,7 @@ export declare const CODE_BLOCK_TYPES: string[];
  *
  * @param content The content string to parse
  * @param responseFormat The desired format of the response
+ * @param options Optional parsing configuration
  * @returns The parsed JSON object or null if it fails
  */
-export declare function parseResponse<T>(content: string, responseFormat: OpenAIResponseFormat): Promise<T | null>;
+export declare function parseResponse<T>(content: string, responseFormat: OpenAIResponseFormat, options?: ParseJsonOptions): Promise<T | null>;

package/dist/types/functions/slack-utils.d.ts

@@ -1,11 +1,10 @@
-/*************  ✨ Codeium Command ⭐  *************/
 /**
  * Sends a message to a Slack channel.
  *
  * @param channel - The channel to send the message to.
  * @param message - The message to send.
  * @param slackBotToken - The slack bot token to use. If not provided, the SLACK_BOT_TOKEN environment variable will be used.
- * @returns A promise that resolves to true if the message is sent successfully, false otherwise.
-
-/******  739f6db2-05ce-46a9-b3f6-9d22cffb8c30  *******/
+ * @returns A promise that resolves to true if the message is sent successfully.
+ * @throws {Error} If the Slack API request fails or returns an error status.
+ */
 export declare const sendMessageToSlack: (channel: string, message: string, slackBotToken?: string) => Promise<boolean>;

package/dist/types/functions/utils.d.ts

@@ -1,5 +1,4 @@
-declare const LOG_TYPES: readonly ["info", "warn", "error", "debug", "trace"];
-type LogType = typeof LOG_TYPES[number];
+type LogType = 'info' | 'warn' | 'error' | 'debug' | 'trace';
 /**
  * Debug logging utility that respects environment debug flags
  * @param message - The message to log
@@ -7,16 +6,5 @@ type LogType = typeof LOG_TYPES[number];
  * @param type - Log level. One of: 'info' | 'warn' | 'error' | 'debug' | 'trace'
  */
 export declare const logIfDebug: (message: string, data?: unknown, type?: LogType) => void;
-/**
- * Fetches a URL with retry logic. If the response is not 2xx, it will retry up to `retries` times
- * with an exponential backoff of `backoff` milliseconds between each attempt.
- *
- * @param url The URL to fetch
- * @param options Optional `RequestInit` object to modify the request
- * @param retries The number of times to retry the request (default: 3)
- * @param backoff The initial backoff time in milliseconds (default: 300)
- * @returns A `Response` object if the fetch is successful
- * @throws An error if the fetch fails after all retries
- */
-export declare function fetchWithRetry(url: string, options?: RequestInit, retries?: number, backoff?: number): Promise<Response>;
+export declare const fetchWithRetry: typeof import("@adaptic/utils/dist/types/misc-utils").fetchWithRetry;
 export {};

package/dist/types/functions/zip-utils.d.ts

@@ -1,7 +1,7 @@
 /**
  * Creates a zip file containing the contents of the provided directory.
- * The zip file is created in the /tmp directory.
- * The source directory must be located in the /tmp directory.
+ * The zip file is created in the configured temp directory (default: os.tmpdir()).
+ * The source directory must be within an allowed path (configurable via LUMIC_ALLOWED_UPLOAD_PATHS).
  * The zip file name is the same as the source directory name with a .zip extension.
  * If a node_modules directory exists in the source directory,
  * it is added separately to ensure it is included in the zip file.
@@ -14,25 +14,27 @@ export declare function createZipFile(sourceDir: string): Promise<string>;
 /**
  * Extracts a zip archive into a specified directory.
  *
- * Both the zip file path and destination path must start with /tmp/.
+ * Both the zip file path and destination path must be within an allowed path
+ * (configurable via LUMIC_ALLOWED_UPLOAD_PATHS, defaults to os.tmpdir()).
  *
- * @param zipPath The path of the zip file to extract. Must start with /tmp/.
- * @param destPath The path of the directory to extract the zip file into. Must start with /tmp/.
+ * @param zipPath The path of the zip file to extract.
+ * @param destPath The path of the directory to extract the zip file into.
  * @returns The path of the extracted directory.
- * @throws If the zip file or destination path does not start with /tmp/.
+ * @throws If the paths are not within allowed paths.
  * @throws If there is an error extracting the zip file.
  */
 export declare function extractZipFile(zipPath: string, destPath: string): Promise<string>;
 /**
  * Adds a file or directory to an existing zip file.
  *
- * The zip file path and item path must start with /tmp/.
+ * The zip file path and item path must be within an allowed path
+ * (configurable via LUMIC_ALLOWED_UPLOAD_PATHS, defaults to os.tmpdir()).
  *
- * @param zipFilePath The path of the zip file to add the item to. Must start with /tmp/.
- * @param itemPath The path of the item to add to the zip file. Must start with /tmp/.
+ * @param zipFilePath The path of the zip file to add the item to.
+ * @param itemPath The path of the item to add to the zip file.
  * @param destPath Optional. The destination path inside the zip file to add the item to. Defaults to the root of the zip file.
  * @returns The path of the updated zip file.
- * @throws If the zip file or item path does not start with /tmp/.
+ * @throws If the paths are not within allowed paths.
  * @throws If there is an error adding the item to the zip file.
  */
 export declare function addToZipFile(zipFilePath: string, itemPath: string, destPath?: string): Promise<string>;

package/dist/types/google-types.ts

@@ -13,16 +13,19 @@ export interface GoogleSheetRange {
   endCell: GoogleSheetCell;
 }
 
+/** Represents a primitive value that can be stored in a Google Sheet cell */
+export type GoogleSheetCellValue = string | number | boolean | null;
+
 export interface GoogleSheetResponse {
   success: boolean;
   error?: string;
-  data?: any;
+  data?: unknown;
 }
 
 export interface GoogleSheetAddRowResponse extends GoogleSheetResponse {
   data?: {
     rowNumber: number;
-    values: any[];
+    values: GoogleSheetCellValue[];
   };
 }
 
@@ -35,7 +38,7 @@ export interface GoogleSheetAddSheetResponse extends GoogleSheetResponse {
 
 export interface GoogleSheetCellResponse extends GoogleSheetResponse {
   data?: {
-    value: any;
+    value: GoogleSheetCellValue;
   };
 }
 

package/dist/types/index.d.ts

@@ -14,7 +14,37 @@ import { createPDFFromMarkdown } from './functions/pdf-create';
 import { addRow, addSheet, writeCell, getCell, writeArray } from './functions/google-sheets';
 import { parseResponse } from './functions/llm-utils';
 import { tools } from './llm-tools';
+import { LumicLogger, setLumicLogger, getLumicLogger } from './utils/logger';
+import { sanitizeForLog, sanitizeError, sanitizeAWSAuth, sanitizeObject } from './utils/sanitizer';
 export * from './types';
+export * from './errors';
+export * from './utils/timeouts';
+export { LumicLogger, setLumicLogger, getLumicLogger };
+export { sanitizeForLog, sanitizeError, sanitizeAWSAuth, sanitizeObject };
+export { getSecrets, resetSecrets, requireSecret } from './config/secrets';
+export type { LumicSecrets } from './config/secrets';
+export { withRetry } from './utils/retry';
+export type { RetryConfig } from './utils/retry';
+export { CircuitBreaker, CircuitBreakerState, CircuitBreakerOpenError, DEFAULT_CIRCUIT_BREAKER_CONFIG, } from './utils/circuit-breaker';
+export type { CircuitBreakerConfig, CircuitBreakerStateChangeCallback, } from './utils/circuit-breaker';
+export { validateSlackChannel, validateS3Key, validateGoogleSheetsRange, } from './utils/input-validator';
+export type { ValidationResult } from './utils/input-validator';
+export { LLMCostTracker, getLLMCostTracker, setLLMCostTracker, resetLLMCostTracker, } from './utils/llm-cost-tracker';
+export type { LLMUsageRecord, ImageUsageRecord, ModelCostSummary, ImageCostSummary, CostSummary, FormattedCostSummary, } from './utils/llm-cost-tracker';
+export { setMetricsCollector, getMetricsCollector, resetMetricsCollector, withMetrics, } from './utils/metrics';
+export type { MetricsCollector } from './utils/metrics';
+export { generateCorrelationId, getCorrelationId, getCorrelationContext, withCorrelationId, getCorrelationHeaders, } from './utils/correlation';
+export type { CorrelationContext } from './utils/correlation';
+export { TokenBucketRateLimiter, RATE_LIMIT_PROFILES, getRateLimiter, resetAllRateLimiters, withRateLimit, } from './utils/rate-limiter';
+export type { RateLimiterConfig } from './utils/rate-limiter';
+export { checkIntegrationHealth } from './utils/health-check';
+export type { IntegrationHealthStatus, HealthCheckResult, } from './utils/health-check';
+export { ParseJsonOptions } from './functions/llm-utils';
+export { FixJsonWithAIOptions } from './functions/json-llm-tools';
+export { SUPPORTED_MODELS, isValidModel, getModelCapabilities } from './types/openai-types';
+export type { SupportedModel, OpenAIModel, DeepseekModel, LLMModel } from './types/openai-types';
+export { openAIChatCompletionSchema, openAIImageResponseSchema, validateOpenAIChatCompletion, safeValidateOpenAIChatCompletion, perplexityResponseSchema, validatePerplexityResponse, safeValidatePerplexityResponse, googleSheetsValueRangeSchema, validateGoogleSheetsResponse, safeValidateGoogleSheetsResponse, s3ListObjectsSchema, s3GetObjectSchema, lambdaInvokeResponseSchema, validateS3ListObjects, safeValidateS3ListObjects, validateLambdaResponse, safeValidateLambdaResponse, createValidator, createSafeValidator, } from './schemas';
+export type { ValidationResult as SchemaValidationResult } from './schemas';
 interface LumicUtilities {
     llm: {
         call: typeof makeLLMCall;

package/dist/types/index.ts

@@ -27,7 +27,7 @@ export type InvocationType = 'RequestResponse' | 'Event' | 'DryRun';
 
 export interface LambdaResponse {
   statusCode: number;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 // Export types from sendMessageToSlack

package/dist/types/openai-types.ts

@@ -1,22 +1,176 @@
 // openai-types.ts
 import { ChatCompletionMessageParam, ChatCompletionTool, ChatCompletionMessageToolCall } from 'openai/resources/chat/completions';
-import { ImageGenerateParams, ImageModel } from 'openai/resources/images';
+import { ImageGenerateParams } from 'openai/resources/images';
+
+/**
+ * Model capability configuration
+ */
+interface ModelCapabilities {
+  provider: 'openai' | 'deepseek';
+  supportsTools: boolean;
+  supportsJson: boolean;
+  supportsStructuredOutput: boolean;
+  supportsDeveloperPrompt: boolean;
+  supportsTemperature: boolean;
+  isReasoningModel: boolean;
+}
+
+/**
+ * Supported models with their capabilities
+ */
+export const SUPPORTED_MODELS = {
+  // OpenAI GPT-5 series
+  'gpt-5': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: true,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: true,
+    isReasoningModel: false,
+  },
+  'gpt-5-mini': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: true,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: true,
+    isReasoningModel: false,
+  },
+  // OpenAI GPT-4.1 series
+  'gpt-4.1': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: true,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: true,
+    isReasoningModel: false,
+  },
+  'gpt-4.1-mini': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: true,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: true,
+    isReasoningModel: false,
+  },
+  'gpt-4.1-nano': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: true,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: true,
+    isReasoningModel: false,
+  },
+  // OpenAI reasoning models (o-series)
+  'o1': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: false,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: false,
+    isReasoningModel: true,
+  },
+  'o1-mini': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: false,
+    supportsStructuredOutput: false,
+    supportsDeveloperPrompt: false,
+    supportsTemperature: false,
+    isReasoningModel: true,
+  },
+  'o3': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: false,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: false,
+    isReasoningModel: true,
+  },
+  'o3-mini': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: true,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: false,
+    isReasoningModel: true,
+  },
+  'o4-mini': {
+    provider: 'openai',
+    supportsTools: true,
+    supportsJson: false,
+    supportsStructuredOutput: true,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: false,
+    isReasoningModel: true,
+  },
+  // Deepseek models
+  'deepseek-chat': {
+    provider: 'deepseek',
+    supportsTools: true,
+    supportsJson: true,
+    supportsStructuredOutput: false,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: true,
+    isReasoningModel: false,
+  },
+  'deepseek-reasoner': {
+    provider: 'deepseek',
+    supportsTools: false,
+    supportsJson: false,
+    supportsStructuredOutput: false,
+    supportsDeveloperPrompt: true,
+    supportsTemperature: true,
+    isReasoningModel: true,
+  },
+} as const satisfies Record<string, ModelCapabilities>;
+
+/**
+ * Represents all supported LLM models
+ */
+export type SupportedModel = keyof typeof SUPPORTED_MODELS;
 
 /**
  * Represents OpenAI models
  */
+export type OpenAIModel = Extract<SupportedModel, 'gpt-5' | 'gpt-5-mini' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'o1' | 'o1-mini' | 'o3' | 'o3-mini' | 'o4-mini'>;
 
-export type OpenAIModel = 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano'
 /**
  * Represents Deepseek models
  */
-export type DeepseekModel = 'deepseek-chat' | 'deepseek-reasoner';
+export type DeepseekModel = Extract<SupportedModel, 'deepseek-chat' | 'deepseek-reasoner'>;
 
 /**
  * Represents all supported LLM models
  */
 export type LLMModel = OpenAIModel | DeepseekModel;
 
+/**
+ * Type guard to check if a string is a valid supported model
+ * @param model The model name to validate
+ * @returns True if the model is supported
+ */
+export function isValidModel(model: string): model is SupportedModel {
+  return model in SUPPORTED_MODELS;
+}
+
+/**
+ * Get capabilities for a supported model
+ * @param model The model to get capabilities for
+ * @returns Model capabilities object
+ */
+export function getModelCapabilities(model: SupportedModel): Readonly<ModelCapabilities> {
+  return SUPPORTED_MODELS[model];
+}
+
 /**
  * Represents the usage of the LLM.
  */
@@ -49,6 +203,11 @@ export interface LLMOptions {
   parallel_tool_calls?: boolean;
   service_tier?: 'auto' | 'default';
   apiKey?: string;
+  /**
+   * Request timeout in milliseconds. Overrides the default LLM_TIMEOUT_MS (120000ms).
+   * Applied to the OpenAI/Deepseek SDK client for the request.
+   */
+  timeout?: number;
 }
 
 /**
@@ -63,11 +222,11 @@ export interface LLMResponse<T> {
 /**
  * Represents the format of the OpenAI response.
  */
-export type OpenAIResponseFormat = 'text' | 'json' | { 
-  type: 'json_schema'; 
+export type OpenAIResponseFormat = 'text' | 'json' | {
+  type: 'json_schema';
   schema: {
     type: 'object';
-    properties: Record<string, any>;
+    properties: Record<string, unknown>;
     required?: string[];
   }
 };