/**
 * Cache Control Utilities for Claude Models
 *
 * This module provides utilities for adding cache_control markers to Claude models
 * to optimize token usage and reduce costs. Cache control is only applied to Claude
 * models and preserves backward compatibility with existing message formats.
 */
import type { ChatCompletionMessageParam, ChatCompletionContentPart, ChatCompletionContentPartText, ChatCompletionFunctionTool, CompletionUsage } from "openai/resources";
/**
 * Cache control directive for Claude models
 */
export interface CacheControl {
    type: "ephemeral";
}
/**
 * Extended text content part with cache control support
 */
export interface ClaudeChatCompletionContentPartText extends ChatCompletionContentPartText {
    type: "text";
    text: string;
    cache_control?: CacheControl;
}
/**
 * Extended tool definition with cache control support
 */
export interface ClaudeChatCompletionFunctionTool extends ChatCompletionFunctionTool {
    type: "function";
    function: ChatCompletionFunctionTool["function"];
    cache_control?: CacheControl;
}
/**
 * Enhanced usage metrics including Claude cache information
 */
export interface ClaudeUsage extends CompletionUsage {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
    cache_read_input_tokens?: number;
    cache_creation_input_tokens?: number;
    cache_creation?: {
        ephemeral_5m_input_tokens: number;
        ephemeral_1h_input_tokens: number;
    };
}
/**
 * Determines if a model supports prompt caching
 * @param modelName - Model identifier
 * @returns True if model name matches the cache pattern (default: contains 'claude')
 */
export declare function supportsPromptCaching(modelName: string): boolean;
/**
 * Determines if a model supports cache control
 * @param modelName - Model identifier
 * @returns True if model name contains 'claude' (case-insensitive)
 * @deprecated Use supportsPromptCaching instead
 */
export declare const isClaudeModel: typeof supportsPromptCaching;
/**
 * Validates cache control structure
 * @param control - Object to validate
 * @returns True if valid cache control object
 */
export declare function isValidCacheControl(control: unknown): control is CacheControl;
/**
 * Adds cache control markers to message content
 * @param content - Original content (string or structured)
 * @param shouldCache - Whether to add cache control
 * @returns Structured content with cache control markers
 */
export declare function addCacheControlToContent(content: string | ChatCompletionContentPart[], shouldCache: boolean): ClaudeChatCompletionContentPartText[];
/**
 * Adds cache control to the last tool in tools array
 * @param tools - Array of tool definitions
 * @returns Tools array with cache control on last tool
 */
export declare function addCacheControlToLastTool(tools: ChatCompletionFunctionTool[]): ClaudeChatCompletionFunctionTool[];
/**
 * Finds the latest message index at 20-message intervals (sliding window approach)
 * @param messages - Array of chat completion messages
 * @returns Index of the latest interval message (20th, 40th, 60th, etc.) or -1 if none
 */
export declare function findIntervalMessageIndex(messages: ChatCompletionMessageParam[]): number;
/**
 * Transforms messages for Claude cache control with hardcoded strategy
 * @param messages - Original OpenAI message array
 * @param modelName - Model name for cache detection
 * @returns Messages with cache control markers applied
 */
export declare function transformMessagesForClaudeCache(messages: ChatCompletionMessageParam[], modelName: string): ChatCompletionMessageParam[];
/**
 * Extends standard usage with cache metrics
 * @param standardUsage - OpenAI usage response
 * @param cacheMetrics - Additional cache metrics from Claude
 * @returns Extended usage with cache information
 */
export declare function extendUsageWithCacheMetrics(standardUsage: CompletionUsage, cacheMetrics?: Partial<ClaudeUsage>): ClaudeUsage;
/**
 * Validates Claude usage structure
 * @param usage - Usage object to validate
 * @returns True if usage structure is valid
 */
export declare function isValidClaudeUsage(usage: unknown): usage is ClaudeUsage;
//# sourceMappingURL=cacheControlUtils.d.ts.map