package com.saas.shared.service.ai;

import com.saas.shared.dto.AiCostCalculationResult;

import java.util.Map;

/**
 * AI Cost Calculator Interface
 * 
 * Clean Architecture:
 * - Abstraction for AI cost calculation (Dependency Inversion Principle)
 * - Each AI provider implements this interface
 * - Allows easy addition of new AI providers without modifying existing code
 * 
 * Implementations:
 * - OpenAiRealtimeCostCalculator (OpenAI Realtime API)
 * - ElevenLabsCostCalculator (ElevenLabs TTS)
 * - GeminiCostCalculator (Google Gemini)
 * - etc.
 * 
 * Usage:
 * 1. Call AI API and track usage (tokens, characters, etc.)
 * 2. Pass usage data to calculateCost()
 * 3. Get AiCostCalculationResult with cost breakdown
 * 4. Persist via AiCostTrackingService
 */
public interface AiCostCalculator {
    
    /**
     * Calculate AI API cost based on usage metrics
     * 
     * @param usageMetrics Usage data from AI API
     *        Examples:
     *        OpenAI: {"input_audio_tokens": 12500, "output_audio_tokens": 8300, "model": "gpt-4o-realtime"}
     *        ElevenLabs: {"characters": 1250, "model": "eleven_turbo_v2"}
     *        Gemini: {"input_tokens": 5000, "output_tokens": 2000, "model": "gemini-2.0-flash"}
     * 
     * @return AiCostCalculationResult with cost and breakdown
     */
    AiCostCalculationResult calculateCost(Map<String, Object> usageMetrics);
    
    /**
     * Get AI provider name
     * 
     * @return Provider name (OPENAI, ELEVENLABS, GEMINI, etc.)
     */
    String getProviderName();
    
    /**
     * Get supported cost types for this provider
     * 
     * @return Array of cost types (e.g., ["REALTIME_API", "TTS", "STT"])
     */
    String[] getSupportedCostTypes();
}