namespace GermanApp.Domain.Interfaces;

/// <summary>
/// Domain interface for Mistral AI text generation service.
/// This is part of the Domain layer.
/// </summary>
public interface IMistralService
{
    /// <summary>
    /// Generates text from a prompt using Mistral API.
    /// </summary>
    /// <param name="prompt">The input prompt</param>
    /// <param name="model">The model to use (defaults to configured default)</param>
    /// <param name="temperature">Creativity level (0-1)</param>
    /// <param name="maxTokens">Maximum tokens to generate</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Generated text</returns>
    Task<string> GenerateTextAsync(
        string prompt,
        string? model = null,
        float temperature = 0.7f,
        int? maxTokens = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Generates text from chat messages using Mistral API.
    /// </summary>
    /// <param name="messages">List of chat messages (role, content)</param>
    /// <param name="model">The model to use</param>
    /// <param name="temperature">Creativity level (0-1)</param>
    /// <param name="maxTokens">Maximum tokens to generate</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Generated text response</returns>
    Task<string> GenerateChatAsync(
        IReadOnlyList<(string role, string content)> messages,
        string? model = null,
        float temperature = 0.7f,
        int? maxTokens = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Generates a story based on lesson context and vocabulary.
    /// </summary>
    /// <param name="level">CEFR level (A1, A2, B1, B2, C1)</param>
    /// <param name="topic">Story topic</param>
    /// <param name="vocabularyWords">List of vocabulary words to include</param>
    /// <param name="length">Approximate story length in words</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Generated story text</returns>
    Task<string> GenerateStoryAsync(
        string level,
        string topic,
        IReadOnlyList<string> vocabularyWords,
        int length = 200,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Provides feedback on user writing.
    /// </summary>
    /// <param name="userText">The text written by the user</param>
    /// <param name="level">CEFR level for appropriate feedback</param>
    /// <param name="prompt">Original prompt/exercise</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Feedback with corrections and suggestions</returns>
    Task<string> GenerateWritingFeedbackAsync(
        string userText,
        string level,
        string? prompt = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Tests the Mistral API connection.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if connection is successful</returns>
    Task<bool> TestConnectionAsync(CancellationToken cancellationToken = default);
}