mistral_translator 0.1.0

data/README.md

@@ -0,0 +1,205 @@
+# MistralTranslator
+
+Une gem Ruby pour traduire et résumer du texte en utilisant l'API Mistral AI.
+
+## Installation
+
+Ajoutez cette ligne à votre Gemfile :
+
+```ruby
+gem 'mistral_translator'
+```
+
+Puis exécutez :
+
+```bash
+bundle install
+```
+
+Ou installez directement :
+
+```bash
+gem install mistral_translator
+```
+
+## Configuration
+
+```ruby
+require 'mistral_translator'
+
+MistralTranslator.configure do |config|
+  config.api_key = 'votre_clé_api_mistral'
+  config.api_url = 'https://api.mistral.ai'  # optionnel
+  config.model = 'mistral-small'             # optionnel
+end
+```
+
+### Variables d'environnement
+
+Vous pouvez aussi utiliser des variables d'environnement :
+
+```bash
+export MISTRAL_API_KEY=votre_clé_api
+export MISTRAL_API_URL=https://api.mistral.ai
+```
+
+## Utilisation
+
+### Traduction simple
+
+```ruby
+# Traduction de base
+result = MistralTranslator.translate("Bonjour le monde", from: 'fr', to: 'en')
+# => "Hello world"
+
+# Vers plusieurs langues
+results = MistralTranslator.translate_to_multiple(
+  "Bonjour le monde", 
+  from: 'fr', 
+  to: ['en', 'es', 'de']
+)
+# => { 'en' => "Hello world", 'es' => "Hola mundo", 'de' => "Hallo Welt" }
+```
+
+### Traduction en lot
+
+```ruby
+texts = ["Bonjour", "Au revoir", "Merci"]
+results = MistralTranslator.translate_batch(texts, from: 'fr', to: 'en')
+# => { 0 => "Hello", 1 => "Goodbye", 2 => "Thank you" }
+```
+
+### Auto-détection de langue
+
+```ruby
+result = MistralTranslator.translate_auto("Hello world", to: 'fr')
+# => "Bonjour le monde"
+```
+
+### Résumés
+
+```ruby
+long_text = "Un très long texte à résumer..."
+
+# Résumé simple
+summary = MistralTranslator.summarize(long_text, language: 'fr', max_words: 100)
+
+# Résumé avec traduction
+summary = MistralTranslator.summarize_and_translate(
+  long_text, 
+  from: 'fr', 
+  to: 'en', 
+  max_words: 150
+)
+
+# Résumés par niveaux
+summaries = MistralTranslator.summarize_tiered(
+  long_text,
+  language: 'fr',
+  short: 50,
+  medium: 150, 
+  long: 300
+)
+# => { short: "...", medium: "...", long: "..." }
+```
+
+### Extensions String (optionnel)
+
+```ruby
+# Activer les extensions String
+ENV['MISTRAL_TRANSLATOR_EXTEND_STRING'] = 'true'
+require 'mistral_translator'
+
+"Bonjour".mistral_translate(from: 'fr', to: 'en')
+# => "Hello"
+
+"Long texte...".mistral_summarize(language: 'fr', max_words: 50)
+# => "Résumé..."
+```
+
+## Langues supportées
+
+La gem supporte les langues suivantes :
+- Français (fr)
+- Anglais (en)
+- Espagnol (es)
+- Portugais (pt)
+- Allemand (de)
+- Italien (it)
+- Néerlandais (nl)
+- Russe (ru)
+- Japonais (ja)
+- Coréen (ko)
+- Chinois (zh)
+- Arabe (ar)
+
+```ruby
+# Vérifier les langues supportées
+MistralTranslator.supported_languages
+MistralTranslator.locale_supported?('fr') # => true
+```
+
+## Gestion d'erreurs
+
+```ruby
+begin
+  result = MistralTranslator.translate("Hello", from: 'en', to: 'fr')
+rescue MistralTranslator::RateLimitError
+  puts "Rate limit dépassé, réessayez plus tard"
+rescue MistralTranslator::AuthenticationError
+  puts "Clé API invalide"
+rescue MistralTranslator::UnsupportedLanguageError => e
+  puts "Langue non supportée: #{e.language}"
+end
+```
+
+## Utilisation avancée
+
+### Client personnalisé
+
+```ruby
+client = MistralTranslator::Client.new(api_key: 'autre_clé')
+translator = MistralTranslator::Translator.new(client: client)
+result = translator.translate("Hello", from: 'en', to: 'fr')
+```
+
+### Health check
+
+```ruby
+status = MistralTranslator.health_check
+# => { status: :ok, message: "API connection successful" }
+```
+
+## Développement
+
+Après avoir cloné le repo :
+
+```bash
+bundle install
+bin/setup
+```
+
+Pour lancer les tests :
+
+```bash
+bundle exec rspec
+```
+
+Pour lancer RuboCop :
+
+```bash
+bundle exec rubocop
+```
+
+## Contribution
+
+Les contributions sont les bienvenues ! Merci de :
+1. Forker le projet
+2. Créer une branche pour votre feature
+3. Commiter vos changements
+4. Pousser vers la branche
+5. Ouvrir une Pull Request
+
+## Licence
+
+Cette gem est disponible sous la licence MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/basic_usage.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Exemple d'utilisation de base de la gem MistralTranslator
+require "mistral_translator"
+
+# Configuration
+MistralTranslator.configure do |config|
+  config.api_key = ENV["MISTRAL_API_KEY"] || "your_api_key_here"
+  # config.api_url = 'https://api.mistral.ai'  # optionnel
+  # config.model = 'mistral-small'             # optionnel
+end
+
+puts "=== MistralTranslator Examples ==="
+puts "Version: #{MistralTranslator.version}"
+puts
+
+# Vérification de la santé de l'API
+puts "🔍 Health Check:"
+health = MistralTranslator.health_check
+puts "Status: #{health[:status]} - #{health[:message]}"
+puts
+
+# Exemple 1: Traduction simple
+puts "📝 Traduction simple:"
+begin
+  result = MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
+  puts "FR → EN: 'Bonjour le monde' → '#{result}'"
+rescue MistralTranslator::Error => e
+  puts "Erreur: #{e.message}"
+end
+puts
+
+# Exemple 2: Traduction vers plusieurs langues
+puts "🌍 Traduction vers plusieurs langues:"
+begin
+  results = MistralTranslator.translate_to_multiple(
+    "Hello world",
+    from: "en",
+    to: %w[fr es de]
+  )
+
+  results.each do |locale, translation|
+    puts "EN → #{locale.upcase}: '#{translation}'"
+  end
+rescue MistralTranslator::Error => e
+  puts "Erreur: #{e.message}"
+end
+puts
+
+# Exemple 3: Traduction en lot
+puts "📦 Traduction en lot:"
+begin
+  texts = ["Good morning", "Good afternoon", "Good evening"]
+  results = MistralTranslator.translate_batch(texts, from: "en", to: "fr")
+
+  results.each do |index, translation|
+    puts "#{index}: '#{texts[index]}' → '#{translation}'"
+  end
+rescue MistralTranslator::Error => e
+  puts "Erreur: #{e.message}"
+end
+puts
+
+# Exemple 4: Auto-détection de langue
+puts "🔍 Auto-détection de langue:"
+begin
+  result = MistralTranslator.translate_auto("¡Hola mundo!", to: "en")
+  puts "Auto-détection → EN: '#{result}'"
+rescue MistralTranslator::Error => e
+  puts "Erreur: #{e.message}"
+end
+puts
+
+# Exemple 5: Résumé de texte
+puts "📄 Résumé de texte:"
+long_text = <<~TEXT
+  Ruby on Rails est un framework de développement web écrit en Ruby qui suit le paradigme#{" "}
+  Modèle-Vue-Contrôleur (MVC). Il privilégie la convention plutôt que la configuration,#{" "}
+  ce qui permet aux développeurs de créer rapidement des applications web robustes.#{" "}
+  Rails comprend de nombreux outils intégrés comme Active Record pour l'ORM,#{" "}
+  Action View pour les templates, Action Controller pour la logique métier,#{" "}
+  et bien d'autres composants. Le framework a été créé par David Heinemeier Hansson#{" "}
+  en 2004 et continue d'évoluer avec une communauté active de développeurs.
+TEXT
+
+begin
+  summary = MistralTranslator.summarize(long_text, language: "fr", max_words: 50)
+  puts "Texte original: #{long_text.length} caractères"
+  puts "Résumé (50 mots max): #{summary}"
+rescue MistralTranslator::Error => e
+  puts "Erreur: #{e.message}"
+end
+puts
+
+# Exemple 6: Résumé avec traduction
+puts "🔄 Résumé + Traduction:"
+begin
+  result = MistralTranslator.summarize_and_translate(
+    long_text,
+    from: "fr",
+    to: "en",
+    max_words: 75
+  )
+  puts "Résumé traduit EN (75 mots max): #{result}"
+rescue MistralTranslator::Error => e
+  puts "Erreur: #{e.message}"
+end
+puts
+
+# Exemple 7: Résumés par niveaux
+puts "📊 Résumés par niveaux:"
+begin
+  tiered = MistralTranslator.summarize_tiered(
+    long_text,
+    language: "fr",
+    short: 25,
+    medium: 75,
+    long: 150
+  )
+
+  puts "Court (25 mots): #{tiered[:short]}"
+  puts "Moyen (75 mots): #{tiered[:medium]}"
+  puts "Long (150 mots): #{tiered[:long]}"
+rescue MistralTranslator::Error => e
+  puts "Erreur: #{e.message}"
+end
+puts
+
+# Informations sur les langues supportées
+puts "🌐 Langues supportées:"
+puts MistralTranslator.supported_languages
+puts
+
+puts "✅ Exemples terminés!"

data/lib/mistral_translator/client.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require_relative "logger"
+
+module MistralTranslator
+  class Client
+    def initialize(api_key: nil)
+      @api_key = api_key || MistralTranslator.configuration.api_key!
+      @base_uri = MistralTranslator.configuration.api_url
+      @model = MistralTranslator.configuration.model
+      @retry_delays = MistralTranslator.configuration.retry_delays
+    end
+
+    def complete(prompt, max_tokens: nil, temperature: nil)
+      response = make_request_with_retry(prompt, max_tokens, temperature)
+      parsed_response = JSON.parse(response.body)
+
+      content = parsed_response.dig("choices", 0, "message", "content")
+      raise InvalidResponseError, "No content in API response" if content.nil? || content.empty?
+
+      content
+    rescue JSON::ParserError => e
+      raise InvalidResponseError, "Invalid JSON in API response: #{e.message}"
+    rescue NoMethodError => e
+      raise InvalidResponseError, "Invalid response structure: #{e.message}"
+    end
+
+    def chat(prompt, max_tokens: nil, temperature: nil)
+      response = make_request_with_retry(prompt, max_tokens, temperature)
+      parsed_response = JSON.parse(response.body)
+
+      parsed_response.dig("choices", 0, "message", "content")
+    rescue JSON::ParserError => e
+      raise InvalidResponseError, "JSON parse error: #{e.message}"
+    rescue NoMethodError => e
+      raise InvalidResponseError, "Invalid response structure: #{e.message}"
+    end
+
+    private
+
+    def make_request_with_retry(prompt, max_tokens, temperature, attempt = 0)
+      response = make_request(prompt, max_tokens, temperature)
+
+      # Vérifier les erreurs dans la réponse
+      check_response_for_errors(response)
+
+      if rate_limit_exceeded?(response)
+        handle_rate_limit(prompt, max_tokens, temperature, attempt)
+      else
+        response
+      end
+    end
+
+    def make_request(prompt, max_tokens, temperature)
+      uri = URI("#{@base_uri}/v1/chat/completions")
+
+      request_body = build_request_body(prompt, max_tokens, temperature)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.read_timeout = 60 # 60 secondes de timeout
+
+      request = Net::HTTP::Post.new(uri.path, headers)
+      request.body = request_body.to_json
+
+      response = http.request(request)
+      log_request_response(request_body, response)
+
+      response
+    rescue Net::ReadTimeout, Timeout::Error => e
+      raise ApiError, "Request timeout: #{e.message}"
+    rescue Net::HTTPError => e
+      raise ApiError, "HTTP error: #{e.message}"
+    end
+
+    def build_request_body(prompt, max_tokens, temperature)
+      body = {
+        model: @model,
+        messages: [{ role: "user", content: prompt }]
+      }
+
+      body[:max_tokens] = max_tokens if max_tokens
+      body[:temperature] = temperature if temperature
+
+      body
+    end
+
+    def headers
+      {
+        "Authorization" => "Bearer #{@api_key}",
+        "Content-Type" => "application/json",
+        "User-Agent" => "mistral-translator-gem/#{MistralTranslator::VERSION}"
+      }
+    end
+
+    def check_response_for_errors(response)
+      case response.code.to_i
+      when 401
+        raise AuthenticationError, "Invalid API key"
+      when 429
+        # Rate limit sera géré séparément
+        nil
+      when 400..499
+        raise ApiError, "Client error (#{response.code})}"
+      when 500..599
+        raise ApiError, "Server error (#{response.code})}"
+      end
+    end
+
+    def rate_limit_exceeded?(response)
+      return true if response.code.to_i == 429
+
+      return false unless response.code.to_i == 200
+
+      body_content = response.body.to_s
+      return false if body_content.length > 1000
+
+      body_content.match?(/rate.?limit|quota.?exceeded/i)
+    end
+
+    def handle_rate_limit(prompt, max_tokens, temperature, attempt)
+      unless attempt < @retry_delays.length
+        raise RateLimitError, "API rate limit exceeded after #{@retry_delays.length} retries"
+      end
+
+      wait_time = @retry_delays[attempt]
+      log_rate_limit_retry(wait_time, attempt)
+      sleep(wait_time)
+      make_request_with_retry(prompt, max_tokens, temperature, attempt + 1)
+    end
+
+    def log_request_response(_request_body, response)
+      # Log seulement si mode verbose activé
+      Logger.debug_if_verbose("Request sent to API", sensitive: true)
+      Logger.debug_if_verbose("Response received: #{response.code}", sensitive: false)
+    end
+
+    def log_rate_limit_retry(wait_time, attempt)
+      message = "Rate limit exceeded, retrying in #{wait_time} seconds (attempt #{attempt + 1})"
+      # Log une seule fois par session pour éviter le spam
+      Logger.warn_once(message, key: "rate_limit_retry", sensitive: false, ttl: 60)
+    end
+  end
+end

data/lib/mistral_translator/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module MistralTranslator
+  class Configuration
+    attr_accessor :api_key, :api_url, :model, :default_max_tokens, :default_temperature, :retry_delays
+
+    def initialize
+      @api_key = nil
+      @api_url = "https://api.mistral.ai"
+      @model = "mistral-small"
+      @default_max_tokens = nil
+      @default_temperature = nil
+      @retry_delays = [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024]
+    end
+
+    def api_key!
+      if @api_key.nil?
+        raise ConfigurationError,
+              "API key is required. Set it with MistralTranslator.configure { |c| c.api_key = 'your_key' }"
+      end
+
+      @api_key
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/mistral_translator/errors.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module MistralTranslator
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ApiError < Error
+    attr_reader :response, :status_code
+
+    def initialize(message, response = nil, status_code = nil)
+      super(message)
+      @response = response
+      @status_code = status_code
+    end
+  end
+
+  class RateLimitError < ApiError
+    def initialize(message = "API rate limit exceeded", response = nil, status_code = 429)
+      super
+    end
+  end
+
+  class AuthenticationError < ApiError
+    def initialize(message = "Invalid API key", response = nil, status_code = 401)
+      super
+    end
+  end
+
+  class InvalidResponseError < Error
+    attr_reader :raw_response
+
+    def initialize(message, raw_response = nil)
+      super(message)
+      @raw_response = raw_response
+    end
+  end
+
+  class EmptyTranslationError < Error
+    def initialize(message = "Empty translation received from API")
+      super
+    end
+  end
+
+  class UnsupportedLanguageError < Error
+    attr_reader :language
+
+    def initialize(language)
+      @language = language
+      super("Unsupported language: #{language}")
+    end
+  end
+end

data/lib/mistral_translator/locale_helper.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module MistralTranslator
+  module LocaleHelper
+    SUPPORTED_LANGUAGES = {
+      "fr" => "français",
+      "en" => "english",
+      "es" => "español",
+      "pt" => "português",
+      "de" => "deutsch",
+      "it" => "italiano",
+      "nl" => "nederlands",
+      "ru" => "русский",
+      "mg" => "malagasy",
+      "ja" => "日本語",
+      "ko" => "한국어",
+      "zh" => "中文",
+      "ar" => "العربية"
+    }.freeze
+
+    # Mapping des noms alternatifs vers les codes de langue
+    LANGUAGE_ALIASES = {
+      "french" => "fr",
+      "german" => "de",
+      "spanish" => "es",
+      "portuguese" => "pt",
+      "italian" => "it",
+      "dutch" => "nl",
+      "russian" => "ru",
+      "malagasy" => "mg",
+      "japanese" => "ja",
+      "korean" => "ko",
+      "chinese" => "zh",
+      "arabic" => "ar"
+    }.freeze
+
+    class << self
+      def locale_to_language(locale)
+        locale_code = normalize_locale(locale)
+        SUPPORTED_LANGUAGES[locale_code] || locale_code.to_s
+      end
+
+      def language_to_locale(language)
+        normalized_language = language.to_s.downcase.strip
+
+        # Vérifier d'abord les alias
+        return LANGUAGE_ALIASES[normalized_language] if LANGUAGE_ALIASES.key?(normalized_language)
+
+        # Recherche directe par valeur
+        found_locale = SUPPORTED_LANGUAGES.find { |_, lang| lang.downcase == normalized_language }
+        return found_locale[0] if found_locale
+
+        # Retourne la langue telle quelle si pas trouvée
+        normalized_language
+      end
+
+      def supported_locales
+        SUPPORTED_LANGUAGES.keys
+      end
+
+      def supported_languages
+        SUPPORTED_LANGUAGES.values
+      end
+
+      def locale_supported?(locale)
+        SUPPORTED_LANGUAGES.key?(normalize_locale(locale))
+      end
+
+      def validate_locale!(locale)
+        normalized = normalize_locale(locale)
+        raise UnsupportedLanguageError, normalized unless locale_supported?(normalized)
+
+        normalized
+      end
+
+      def normalize_locale(locale)
+        return "" if locale.nil? || locale.to_s.empty?
+
+        normalized = locale.to_s.downcase
+        return "" if normalized.empty?
+
+        # Diviser par "-" et prendre la première partie
+        first_part = normalized.split("-").first
+        return "" if first_part.nil? || first_part.empty?
+
+        # Diviser par "_" et prendre la première partie
+        result = first_part.split("_").first
+        return "" if result.nil? || result.empty?
+
+        result
+      end
+
+      # Méthode pour obtenir une liste formatée des langues supportées
+      def supported_languages_list
+        SUPPORTED_LANGUAGES.map { |code, name| "#{code} (#{name})" }.join(", ")
+      end
+    end
+  end
+end