mistral_translator 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ecf7ff10300ed8793126b3417e1b26444daf4c6778ac13d95224880175cb96c
-  data.tar.gz: 5ade2f503013b9b539831e9dfddb830fdd68ca6e8a98762a1a0cd97f2d0d1f63
+  metadata.gz: 22b02e4c378ffdd992bbb525c57a03fd15c4c82e2ee916c43a3753b09398c8e0
+  data.tar.gz: 1bdf19928ac211fbbc7e7fe064f600d53639c3b0aa57063b14b74fe3b95384c0
 SHA512:
-  metadata.gz: 23afe648e77f352c771231bee584b0a2cee50c1bf3a2c4c747bf24874a0aeca4c9304fd1f0c8e34cd732591d4551235258d0091a4624f82879235bab737708f2
-  data.tar.gz: cd5c9ab42a3369c70ac0d9716e263f25eaf38e7541c8dc18533b1c603db14d6d96c6e628c074bc13e9471ebd2e51b034e946432e8bdca0d0ed1d511fea9bc9cf
+  metadata.gz: 67bb96d4142aa345f2feb2f1cf35ef30e131d529ad22338e9bd31c0c237d165a446b74e8ed75aa7715d903e486657250fb823e4add5994edade18d763fa50e2f
+  data.tar.gz: 39fcfd92f88aa10bb1ca930a8c9539a9d3e12ce7a8b4d1564d2cd0336ac5f349d9903334abec4a7f0d8fe8876a90d82738d8e6bc2a024bc91df5303c8f096588

data/CHANGELOG.md

@@ -1,4 +1,36 @@
-## [Unreleased]
+## [0.5.0] - 2026-10-29
+
+### Added
+
+- `config.read_timeout`: how long to wait for the API's answer, in seconds. Defaults to 60, the value the gem used until now; anything but a positive number raises `ConfigurationError` when it is set.
+- `config.open_timeout`: how long to wait for the connection to open (TCP, then TLS), in seconds. Defaults to 60, validated the same way.
+
+### Changed
+
+No change to translation results:
+
+- Translations and summaries share one retry policy, with the same delays and counts as before. Their retry log lines now share one format, such as `translation retry 1/3 for fr->en in 2s: …`.
+- The `Summarizer` no longer prints to stdout when `MISTRAL_TRANSLATOR_TEST_OUTPUT` is set.
+- A response is parsed once instead of twice.
+
+### Deprecated
+
+These options still work, print a warning, and will be removed in 1.0:
+
+- `config.ssl_timeout`, the former name of `open_timeout`, which it still sets. It is now validated like `open_timeout`, so `nil` (no limit) is rejected.
+- `config.default_max_tokens` and `config.default_temperature`, which the gem never read.
+
+### Removed
+
+Undocumented code that the gem never called:
+
+- the `HelpersExtensions` copies of `translate_with_progress`, `translate_multi_style` and `find_locale_suggestions`, which `Helpers` redefines;
+- `TranslatorHelpers::RetryHandler`, `TranslatorHelpers::LoggingHelper` and `InputValidator#validate_batch_inputs!`;
+- `PromptBuilder.bulk_translation_prompt`, `PromptBuilder.tiered_summary_prompt`, `PromptHelpers::FormatInstructions`, `ResponseParser.parse_bulk_translation_response` and `ResponseParser::JsonParserState`.
+
+### Security
+
+- When the scan for a JSON object inside text reached its limit, the error kept the `JSON::ParserError` as its `cause`, and that error quotes the response.
 
 ## [0.4.0] - 2026-10-28
 

data/README.md

@@ -37,7 +37,7 @@ MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
 
 ## Supported Languages
 
-All 182 ISO 639-1 languages named by CLDR (`fr`, `en`, `es`, `de`, `ja`, `br`, `wo`, `mg`…). `MistralTranslator.supported_locales` lists them, and English or French names are accepted in place of codes (`"German"`, `"allemand"`).
+All 182 ISO 639-1 languages named by CLDR (`fr`, `en`, `es`, `de`, `ja`, `br`, `wo`, `mg`…). `MistralTranslator.supported_locales` lists them, and English or French names are accepted in place of codes (`"German"`, `"allemand"`). The list and the names come from the CLDR data of macOS 27.2, through `bin/generate_languages` (2026-10-28).
 
 Translation quality depends on the Mistral model: excellent for widely used languages, weaker for rare ones. Check the output before relying on a rare language.
 
@@ -166,6 +166,9 @@ MistralTranslator.configure do |config|
   config.enable_metrics = true                     # Enable performance metrics
   config.proxy = :env                              # HTTP proxy: nil (default), "http://host:port", or :env
                                                    # to read HTTPS_PROXY / HTTP_PROXY and NO_PROXY
+  config.open_timeout = 60                         # Seconds to open the connection (default 60)
+  config.read_timeout = 60                         # Seconds to wait for the API's answer (default 60);
+                                                   # raise it for long texts or summaries
 
   # Callbacks for monitoring
   config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
@@ -178,6 +181,8 @@ MistralTranslator.configure do |config|
 end
 ```
 
+Configure the gem before the first call. The module-level methods (`MistralTranslator.translate`, `summarize`…) share one client, which reads `api_key`, `model`, `api_url`, `retry_delays` and the connection settings (`read_timeout`, `proxy`, SSL) on the first call. To change them afterwards, call `MistralTranslator.reset_configuration!` and configure again, or create a `MistralTranslator::Translator.new` (or `Summarizer.new`), which builds its own client from the current configuration.
+
 ## Error Handling
 
 ```ruby

data/docs/api-reference/configuration.md

@@ -13,14 +13,37 @@ MistralTranslator.configure do |config|
   config.api_key = ENV['MISTRAL_API_KEY']        # Obligatoire
   config.model = "mistral-small-latest"                 # Défaut
   config.api_url = "https://api.mistral.ai"      # URL API
-  config.default_max_tokens = 4000               # Limite tokens
-  config.default_temperature = 0.3               # Créativité (0-1)
   config.retry_delays = [2, 4, 8, 16, 32]       # Délais retry (secondes)
   config.enable_metrics = false                  # Suivi des stats
   config.proxy = nil                             # Proxy HTTP (désactivé par défaut)
+  config.open_timeout = 60                       # Ouverture de la connexion (secondes)
+  config.read_timeout = 60                       # Attente maximale de la réponse (secondes)
 end
 ```
 
+Configurez la gem avant le premier appel. Les méthodes du module (`MistralTranslator.translate`, `summarize`…) partagent un client, qui lit `api_key`, `model`, `api_url`, `retry_delays` et les réglages de connexion (`read_timeout`, `proxy`, SSL) lors du premier appel. Pour les changer ensuite, appelez `MistralTranslator.reset_configuration!` puis configurez à nouveau, ou créez un `MistralTranslator::Translator.new` (ou `Summarizer.new`), qui construit son propre client avec la configuration du moment.
+
+## Délais
+
+Deux délais, en secondes, 60 par défaut :
+
+- `open_timeout` : ouverture de la connexion à l'API (TCP puis TLS) ;
+- `read_timeout` : attente de la réponse. Un long texte ou un résumé détaillé peut demander plus au modèle ; augmentez-le dans ce cas.
+
+```ruby
+config.read_timeout = 180
+```
+
+- Seul un nombre strictement positif est accepté (entier ou décimal) ; toute autre valeur lève `ConfigurationError` dès l'affectation.
+- Délai de réponse dépassé : la requête lève `ApiError` (« Request timeout »).
+
+## Options obsolètes
+
+Elles fonctionnent encore, avec un avertissement, et seront retirées en 1.0 :
+
+- `ssl_timeout` : ancien nom d'`open_timeout`, qu'il règle toujours ;
+- `default_max_tokens` et `default_temperature` : jamais lues par la gem, elles n'ont aucun effet. Pour régler ces paramètres, passez `max_tokens:` et `temperature:` à `Client#chat` ou `Client#complete`.
+
 ## Proxy
 
 Désactivé par défaut. Trois valeurs possibles :

data/docs/getting-started.md

@@ -52,6 +52,8 @@ MistralTranslator::LocaleHelper.locale_supported?("ja")
 # => true
 ```
 
+La liste et les noms viennent des données CLDR de macOS 27.2, via `bin/generate_languages` (2026-10-28).
+
 La qualité de traduction dépend du modèle Mistral : excellente pour les langues les plus parlées, plus faible pour les langues rares. Vérifiez le résultat avant de vous appuyer sur une langue rare.
 
 ## 🚨 Gestion d'Erreurs Simple

data/docs/installation.md

@@ -79,8 +79,6 @@ MistralTranslator.configure do |config|
   config.model = "mistral-small-latest"                # Modèle par défaut
   config.retry_delays = [2, 4, 8, 16]          # Délais retry
   config.enable_metrics = true                  # Suivi des stats
-  config.default_max_tokens = 4000              # Limite tokens
-  config.default_temperature = 0.3              # Créativité
 end
 ```
 

data/docs/rails-integration/setup.md

@@ -272,7 +272,6 @@ MistralTranslator.configure do |config|
 
   # Optimisation Rails
   config.enable_metrics = true
-  config.default_max_tokens = 4000
 
   # Cache intelligent des traductions
   config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {

data/lib/mistral_translator/client_helpers.rb

@@ -30,9 +30,9 @@ module MistralTranslator
       def http_pool
         @http_pool ||= begin
           pool = Net::HTTP::Persistent.new(name: "mistral_translator")
-          pool.read_timeout = 60
+          pool.read_timeout = MistralTranslator.configuration.read_timeout
           pool.idle_timeout = 30
-          pool.open_timeout = MistralTranslator.configuration.ssl_timeout
+          pool.open_timeout = MistralTranslator.configuration.open_timeout
           pool.max_requests = 100
 
           # SSL/TLS configuration

data/lib/mistral_translator/configuration.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "proxy"
+require_relative "deprecated_options"
 
 module MistralTranslator
   class Configuration
-    attr_accessor :api_key, :model, :default_max_tokens, :default_temperature, :retry_delays,
+    include DeprecatedOptions
+
+    attr_accessor :api_key, :model, :retry_delays,
                   :on_translation_start, :on_translation_complete, :on_translation_error,
                   :on_rate_limit, :on_batch_complete, :enable_metrics,
-                  :ssl_verify_mode, :ssl_ca_file, :ssl_ca_path, :ssl_timeout
-    attr_reader :api_url, :proxy
+                  :ssl_verify_mode, :ssl_ca_file, :ssl_ca_path
+    attr_reader :api_url, :proxy, :open_timeout, :read_timeout
 
     def initialize
       @api_key = nil
@@ -30,7 +33,10 @@ module MistralTranslator
       @ssl_verify_mode = :peer  # :peer, :none, or OpenSSL constant
       @ssl_ca_file = nil        # Path to CA certificate file
       @ssl_ca_path = nil        # Path to CA certificates directory
-      @ssl_timeout = 60         # SSL handshake timeout in seconds
+
+      # Délais en secondes : ouverture de la connexion (TCP puis TLS), puis attente de la réponse
+      @open_timeout = 60
+      @read_timeout = 60
 
       # Proxy : nil (aucun), URI ou String, ou :env (HTTPS_PROXY, HTTP_PROXY, NO_PROXY)
       @proxy = nil
@@ -66,6 +72,14 @@ module MistralTranslator
       @proxy = value
     end
 
+    def open_timeout=(seconds)
+      @open_timeout = positive_seconds!(:open_timeout, seconds)
+    end
+
+    def read_timeout=(seconds)
+      @read_timeout = positive_seconds!(:read_timeout, seconds)
+    end
+
     # Méthodes pour les callbacks
     def trigger_translation_start(from_locale, to_locale, text_length)
       @on_translation_start&.call(from_locale, to_locale, text_length, Time.now)
@@ -176,6 +190,12 @@ module MistralTranslator
 
     private
 
+    def positive_seconds!(name, seconds)
+      return seconds if seconds.is_a?(Numeric) && seconds.real? && seconds.positive?
+
+      raise ConfigurationError, "#{name} must be a positive number of seconds, got: #{seconds.inspect}"
+    end
+
     def validate_api_url(url)
       uri = parse_uri(url)
       validate_uri_scheme(uri, url)

data/lib/mistral_translator/deprecated_options.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MistralTranslator
+  # Options de configuration obsolètes, retirées en 1.0 : ssl_timeout a toujours réglé
+  # l'ouverture de la connexion, default_max_tokens et default_temperature n'ont jamais été lus.
+  module DeprecatedOptions
+    def ssl_timeout
+      deprecated(:ssl_timeout, "use open_timeout")
+      open_timeout
+    end
+
+    def ssl_timeout=(seconds)
+      deprecated(:ssl_timeout, "use open_timeout")
+      self.open_timeout = seconds
+    end
+
+    def default_max_tokens
+      deprecated(:default_max_tokens, "it has no effect")
+      @default_max_tokens
+    end
+
+    def default_max_tokens=(value)
+      deprecated(:default_max_tokens, "it has no effect")
+      @default_max_tokens = value
+    end
+
+    def default_temperature
+      deprecated(:default_temperature, "it has no effect")
+      @default_temperature
+    end
+
+    def default_temperature=(value)
+      deprecated(:default_temperature, "it has no effect")
+      @default_temperature = value
+    end
+
+    private
+
+    # L'avertissement désigne la ligne de l'appelant, pas celle de la gem
+    def deprecated(name, advice)
+      Kernel.warn("[MistralTranslator] config.#{name} is deprecated and will be removed in 1.0: #{advice}",
+                  uplevel: 2)
+    end
+  end
+end

data/lib/mistral_translator/helpers.rb

@@ -252,11 +252,6 @@ module MistralTranslator
 
         LevenshteinHelpers.levenshtein_distance(input, name) <= (name.length >= 8 ? 2 : 1)
       end
-
-      # Exposer la distance de Levenshtein en privé via délégation pour les tests
-      def levenshtein_distance(source_string, target_string)
-        LevenshteinHelpers.levenshtein_distance(source_string, target_string)
-      end
     end
 
     # Module pour inclure dans les classes Rails si souhaité

data/lib/mistral_translator/helpers_extensions.rb

@@ -25,43 +25,6 @@ module MistralTranslator
         opts = { context: options[:context], glossary: options[:glossary] }
         MistralTranslator.translate(text, from: from, to: to, preserve_html: true, **opts)
       end
-
-      def translate_with_progress(items, from:, to:, **options)
-        results = {}
-        total = items.size
-        processed = 0
-
-        items.each do |key, text|
-          results[key] = MistralTranslator.translate(text, from: from, to: to, **options)
-          processed += 1
-          yield(processed, total, key) if block_given?
-        end
-
-        results
-      end
-
-      def translate_multi_style(text, from:, to:, **options)
-        results = {}
-
-        styles = options[:styles] || %i[formal casual]
-        styles.each do |style|
-          style_context = options[:context] ? "#{options[:context]} (Style: #{style})" : "Style: #{style}"
-
-          begin
-            results[style] = MistralTranslator.translate(
-              text,
-              from: from,
-              to: to,
-              context: style_context,
-              glossary: options[:glossary]
-            )
-          rescue StandardError => e
-            results[style] = { error: e.message }
-          end
-        end
-
-        results
-      end
     end
 
     # Extensions pour les helpers d'analyse
@@ -103,27 +66,6 @@ module MistralTranslator
           compression_ratio: (optimal_words.to_f / word_count * 100).round(1)
         }
       end
-
-      def find_locale_suggestions(invalid_locale)
-        return [] unless invalid_locale.is_a?(String)
-
-        supported = LocaleHelper.supported_locales.map(&:to_s)
-
-        # Recherche par similarité basique
-        suggestions = supported.select do |locale|
-          locale.start_with?(invalid_locale.downcase) ||
-            invalid_locale.downcase.start_with?(locale)
-        end
-
-        # Si pas de suggestions par préfixe, chercher par distance
-        if suggestions.empty?
-          suggestions = supported.select do |locale|
-            levenshtein_distance(invalid_locale.downcase, locale) <= 2
-          end
-        end
-
-        suggestions.first(3) # Limiter à 3 suggestions
-      end
     end
 
     # Extensions pour les helpers de coût

data/lib/mistral_translator/prompt_builder.rb

@@ -9,7 +9,6 @@ module MistralTranslator
   module PromptBuilder
     extend PromptHelpers::ContextBuilder
     extend PromptHelpers::HtmlInstructions
-    extend PromptHelpers::FormatInstructions
     extend PromptMetadataHelpers
 
     class << self
@@ -49,55 +48,6 @@ module MistralTranslator
         PROMPT
       end
 
-      # rubocop:disable Metrics/MethodLength
-      def bulk_translation_prompt(texts, source_language, target_language, **options)
-        source_name = LocaleHelper.prompt_language_name(source_language)
-        target_name = LocaleHelper.prompt_language_name(target_language)
-
-        context_section = build_context_section(options[:context], options[:glossary])
-        html_instruction = options[:preserve_html] ? build_html_preservation_instruction : ""
-
-        # Extraire les valeurs pour les métadonnées
-        context = options[:context]
-        glossary = options[:glossary]
-        preserve_html = options[:preserve_html]
-
-        Prompt.new(instructions: <<~PROMPT, text: numbered_texts(texts))
-          Tu es un traducteur professionnel. Traduis les textes fournis, numérotés.
-          Langue source : #{source_name}. Langue cible : #{target_name}.
-          #{context_section}
-          RÈGLES :
-          - Traduis fidèlement chaque texte sans ajouter d'informations
-          - Conserve le style, ton et format originaux#{html_instruction}
-          - Maintiens la cohérence terminologique entre tous les textes
-          - #{Prompt::DATA_RULE}
-          - Réponds UNIQUEMENT en JSON valide
-
-          FORMAT OBLIGATOIRE :
-          {
-            "translations": [
-              {
-                "index": 1,
-                "source": "texte original 1",
-                "target": "texte traduit 1"
-              },
-              {
-                "index": 2,
-                "source": "texte original 2",
-                "target": "texte traduit 2"
-              }
-            ],
-            "metadata": {
-              "source_language": "#{source_language}",
-              "target_language": "#{target_language}",
-              "count": #{texts.length},
-              "operation": "bulk_translation"#{build_metadata_additions(context, glossary, preserve_html)}
-            }
-          }
-        PROMPT
-      end
-      # rubocop:enable Metrics/MethodLength
-
       def summary_prompt(text, max_words, target_language = "fr", context: nil, style: nil)
         target_name = LocaleHelper.prompt_language_name(target_language)
 
@@ -168,50 +118,6 @@ module MistralTranslator
         PROMPT
       end
 
-      def tiered_summary_prompt(text, target_language, **options)
-        target_name = LocaleHelper.prompt_language_name(target_language)
-
-        context_section = build_summary_context_section(options[:context], options[:style])
-        style_instruction = build_style_instruction(options[:style])
-
-        # Extraire les valeurs pour les métadonnées
-        context = options[:context]
-        style = options[:style]
-
-        Prompt.new(instructions: <<~PROMPT, text: text)
-          Tu es un rédacteur professionnel. Crée trois résumés du texte fourni en #{target_name}.
-          #{context_section}
-          RÈGLES :
-          - Résume fidèlement sans ajouter d'informations
-          - Respecte strictement les longueurs demandées
-          - Court: #{options[:short]} mots, Moyen: #{options[:medium]} mots, Long: #{options[:long]} mots#{style_instruction}
-          - #{Prompt::DATA_RULE}
-          - Réponds UNIQUEMENT en JSON valide
-
-          FORMAT OBLIGATOIRE :
-          {
-            "content": {
-              "source": "texte original",
-              "summaries": {
-                "short": "résumé court (#{options[:short]} mots)",
-                "medium": "résumé moyen (#{options[:medium]} mots)",
-                "long": "résumé long (#{options[:long]} mots)"
-              }
-            },
-            "metadata": {
-              "source_language": "original",
-              "target_language": "#{target_language}",
-              "summaries": {
-                "short": #{options[:short]},
-                "medium": #{options[:medium]},
-                "long": #{options[:long]}
-              },
-              "operation": "tiered_summarization"#{build_summary_metadata_additions(context, style)}
-            }
-          }
-        PROMPT
-      end
-
       def language_detection_prompt(text, confidence_score: false)
         confidence_instruction = if confidence_score
                                    ', "confidence": score_de_confiance_entre_0_et_1'

data/lib/mistral_translator/prompt_helpers.rb

@@ -69,28 +69,5 @@ module MistralTranslator
         HTML_INSTRUCTION
       end
     end
-
-    # Helper pour les instructions de formatage
-    module FormatInstructions
-      def build_json_format_instruction
-        <<~JSON_INSTRUCTION
-
-          FORMAT DE RÉPONSE : Réponds UNIQUEMENT avec un objet JSON valide.
-          Pas de texte avant ou après le JSON.
-        JSON_INSTRUCTION
-      end
-
-      def numbered_texts(texts)
-        texts.map.with_index { |text, i| "#{i + 1}. #{text}" }.join("\n")
-      end
-
-      def build_batch_format_instruction
-        <<~BATCH_INSTRUCTION
-
-          FORMAT DE RÉPONSE : Réponds avec un tableau JSON contenant les traductions dans l'ordre.
-          Chaque élément doit être la traduction correspondante.
-        BATCH_INSTRUCTION
-      end
-    end
   end
 end

data/lib/mistral_translator/prompt_metadata_helpers.rb

@@ -32,10 +32,5 @@ module MistralTranslator
 
       additions.any? ? ",\n    #{additions.join(",\n    ")}" : ""
     end
-
-    def log_prompt_generation(prompt_type, source_locale, target_locale)
-      message = "Generated #{prompt_type} prompt for #{source_locale} -> #{target_locale}"
-      Logger.debug_if_verbose(message, sensitive: false)
-    end
   end
 end

data/lib/mistral_translator/response_parser.rb

@@ -16,6 +16,11 @@ module MistralTranslator
       %w[content original], %w[original]
     ].freeze
 
+    # Garde-fous contre les réponses démesurées
+    MAX_CONTENT_SIZE = 1_000_000
+    MAX_SCAN_LENGTH = 100_000
+    BRACE_DEPTH = { "{" => 1, "}" => -1 }.freeze
+
     class << self
       def parse_translation_response(raw_content)
         return nil if raw_content.nil? || raw_content.empty?
@@ -56,25 +61,6 @@ module MistralTranslator
         end
       end
 
-      def parse_bulk_translation_response(raw_content)
-        return [] if raw_content.nil? || raw_content.empty?
-
-        with_response_errors("bulk", raw_content) do
-          translations = parse_response_json(raw_content, "bulk")["translations"]
-          unless translations.is_a?(Array)
-            raise InvalidResponseError.new("No translations array in response", raw_content)
-          end
-
-          translations.map do |translation|
-            {
-              index: translation["index"],
-              original: translation["source"],
-              translated: translation["target"]
-            }
-          end
-        end
-      end
-
       def parse_json_content(json_content)
         JSON.parse(json_content)
       rescue JSON::ParserError
@@ -111,118 +97,75 @@ module MistralTranslator
         raise InvalidResponseError.new("Error processing #{label} response (#{e.class})", raw_content), cause: nil
       end
 
+      # Le mode JSON de l'API renvoie un objet seul, lu tel quel. Sinon, on lit le premier objet
+      # trouvé dans le texte, en réparant les continuations de ligne.
       def parse_response_json(raw_content, label)
-        json_content = extract_json_from_content(raw_content)
-        raise InvalidResponseError.new("No JSON in #{label} response", raw_content) unless json_content
-
-        data = parse_json_content(json_content)
+        ensure_content_size!(raw_content)
+        data = parse_whole_or_embedded(raw_content, label)
         raise InvalidResponseError.new("Unexpected JSON in #{label} response", raw_content) unless data.is_a?(Hash)
 
         data
-      rescue JSON::ParserError
-        details = "raw_len=#{raw_content.length} json_len=#{json_content&.length}"
-        Logger.debug_if_verbose("JSON parse failed: #{details}", sensitive: false)
-        raise InvalidResponseError.new("Invalid JSON in #{label} response (#{details})", raw_content), cause: nil
       end
 
-      def extract_json_from_content(content)
-        return nil if content.nil? || content.empty?
-
-        # Limiter la taille pour éviter les attaques DoS
-        max_content_size = 1_000_000 # 1MB max
-        if content.length > max_content_size
-          raise InvalidResponseError, "Response content too large (#{content.length} bytes, max: #{max_content_size})"
-        end
+      def ensure_content_size!(content)
+        return if content.length <= MAX_CONTENT_SIZE
 
-        # Essayer d'abord de parser directement le contenu comme JSON
-        begin
-          JSON.parse(content)
-          content
-        rescue JSON::ParserError
-          # Si ça échoue, chercher le JSON dans la réponse (peut être entouré de texte)
-          # Utiliser une approche plus robuste pour les JSON complexes
-          find_json_in_text(content)
-        end
+        raise InvalidResponseError, "Response content too large (#{content.length} bytes, max: #{MAX_CONTENT_SIZE})"
       end
 
-      def find_json_in_text(text)
-        start_pos = find_json_start(text)
-        return nil unless start_pos
+      def parse_whole_or_embedded(raw_content, label)
+        JSON.parse(raw_content)
+      rescue JSON::ParserError
+        json_content = find_json_in_text(raw_content)
+        raise InvalidResponseError.new("No JSON in #{label} response", raw_content), cause: nil unless json_content
 
-        parse_json_until_end(text, start_pos)
+        parse_embedded_json(json_content, raw_content, label)
       end
 
-      def find_json_start(text)
-        text.index("{")
+      def parse_embedded_json(json_content, raw_content, label)
+        parse_json_content(json_content)
+      rescue JSON::ParserError
+        details = "raw_len=#{raw_content.length} json_len=#{json_content.length}"
+        Logger.debug_if_verbose("JSON parse failed: #{details}", sensitive: false)
+        raise InvalidResponseError.new("Invalid JSON in #{label} response (#{details})", raw_content), cause: nil
       end
 
-      def parse_json_until_end(text, start_pos)
-        parser_state = JsonParserState.new
-        max_iterations = 100_000
-
-        (start_pos...text.length).each do |i|
-          parser_state.increment_iterations
-          if parser_state.iterations > max_iterations
-            raise InvalidResponseError,
-                  "JSON parsing exceeded maximum iterations"
+      # Le premier objet du texte, de sa première accolade à celle qui la referme.
+      def find_json_in_text(text)
+        start = text.index("{")
+        finish = closing_brace_index(text, start) if start
+        text[start..finish] if finish
+      end
+
+      # Les accolades des chaînes ne comptent pas ; le parcours est plafonné.
+      def closing_brace_index(text, start)
+        depth = 0
+        in_string = false
+        escaped = false
+
+        (start...text.length).each do |index|
+          ensure_scan_length!(index - start)
+          char = text[index]
+
+          if escaped
+            escaped = false
+          elsif char == "\\"
+            escaped = true
+          elsif char == '"'
+            in_string = !in_string
+          elsif !in_string
+            depth += BRACE_DEPTH.fetch(char, 0)
+            return index if depth.zero?
           end
-
-          char = text[i]
-          parser_state.process_character(char)
-
-          return text[start_pos..i] if parser_state.found_complete_json?
         end
 
         nil
       end
 
-      # Helper class pour gérer l'état du parsing JSON
-      class JsonParserState
-        attr_reader :iterations
-
-        def initialize
-          @brace_count = 0
-          @in_string = false
-          @escape_next = false
-          @iterations = 0
-        end
-
-        def increment_iterations
-          @iterations += 1
-        end
-
-        def process_character(char)
-          return handle_escape_character if @escape_next
-          return handle_backslash_character if char == "\\"
-          return handle_quote_character(char) if char == '"' && !@escape_next
-          return if @in_string
-
-          handle_brace_character(char)
-        end
+      def ensure_scan_length!(scanned)
+        return if scanned < MAX_SCAN_LENGTH
 
-        def handle_escape_character
-          @escape_next = false
-        end
-
-        def handle_backslash_character
-          @escape_next = true
-        end
-
-        def handle_quote_character(_char)
-          @in_string = !@in_string
-        end
-
-        def handle_brace_character(char)
-          if char == "{"
-            @brace_count += 1
-          elsif char == "}"
-            @brace_count -= 1
-          end
-        end
-
-        def found_complete_json?
-          @brace_count.zero?
-        end
+        raise InvalidResponseError, "JSON parsing exceeded maximum iterations", cause: nil
       end
 
       # Le texte traduit ou résumé : toujours une String non vide, jamais un objet ou un tableau.

data/lib/mistral_translator/retries.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "logger"
+
+module MistralTranslator
+  # Relances communes aux traductions et aux résumés.
+  # Le client relance déjà les 429 avec backoff : ici, quelques tentatives de plus suffisent.
+  module Retries
+    RETRY_COUNT = 3
+    RETRY_DELAY = 2
+
+    private
+
+    # Exécute le bloc, qui reçoit le numéro de tentative (0 pour la première).
+    # Une réponse inexploitable est relancée avec un backoff exponentiel, un quota dépassé
+    # après un délai fixe ; au-delà de RETRY_COUNT relances, l'erreur remonte.
+    # operation et subject nomment la requête dans les journaux, jamais son contenu.
+    def with_retries(operation:, subject:)
+      attempt = 0
+      begin
+        yield attempt
+      rescue EmptyTranslationError, InvalidResponseError => e
+        raise if attempt >= RETRY_COUNT
+
+        wait_time = RETRY_DELAY * (2**attempt)
+        attempt += 1
+        log_retry(operation, subject, e, attempt, wait_time)
+        sleep(wait_time)
+        retry
+      rescue RateLimitError
+        raise if attempt >= RETRY_COUNT
+
+        attempt += 1
+        log_rate_limit_hit(operation, subject)
+        sleep(RETRY_DELAY)
+        retry
+      end
+    end
+
+    def log_retry(operation, subject, error, attempt, wait_time)
+      message = "#{operation} retry #{attempt}/#{RETRY_COUNT} for #{subject} in #{wait_time}s: #{error.message}"
+      Logger.warn_once(message, key: "#{operation}_retry_#{subject}_#{error.class.name}", sensitive: false, ttl: 120)
+    end
+
+    def log_rate_limit_hit(operation, subject)
+      Logger.warn_once("Rate limit hit for #{operation} #{subject}, retrying",
+                       key: "#{operation}_rate_limit_#{subject}", sensitive: false, ttl: 300)
+    end
+  end
+end

data/lib/mistral_translator/summarizer.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 require_relative "logger"
+require_relative "retries"
 require_relative "security"
 
 module MistralTranslator
   class Summarizer
+    include Retries
+
     DEFAULT_MAX_WORDS = 250
-    DEFAULT_RETRY_COUNT = 3
-    DEFAULT_RETRY_DELAY = 2
+    DEFAULT_RETRY_COUNT = Retries::RETRY_COUNT
+    DEFAULT_RETRY_DELAY = Retries::RETRY_DELAY
 
     def initialize(client: nil)
       @client = client || Client.new
@@ -84,28 +87,16 @@ module MistralTranslator
 
     private
 
-    # Relances communes à tous les résumés ; une réponse inexploitable finit par lever une erreur.
-    def request_summary(prompt, target_locale, attempt = 0)
-      log_debug("Summary attempt #{attempt + 1} for #{target_locale}")
-
-      result = ResponseParser.parse_summary_response(@client.complete(prompt, json: true))
-      raise EmptyTranslationError, "Empty summary received" if result.nil? || result[:summary].to_s.empty?
+    # Commun à tous les résumés ; une réponse inexploitable finit par lever une erreur.
+    def request_summary(prompt, target_locale)
+      with_retries(operation: "summary", subject: target_locale) do |attempt|
+        log_debug("Summary attempt #{attempt + 1} for #{target_locale}")
 
-      result[:summary]
-    rescue EmptyTranslationError, InvalidResponseError => e
-      raise if attempt >= DEFAULT_RETRY_COUNT
+        result = ResponseParser.parse_summary_response(@client.complete(prompt, json: true))
+        raise EmptyTranslationError, "Empty summary received" if result.nil? || result[:summary].to_s.empty?
 
-      wait_time = DEFAULT_RETRY_DELAY * (2**attempt)
-      log_retry(e, attempt + 1, wait_time, target_locale)
-      sleep(wait_time)
-      request_summary(prompt, target_locale, attempt + 1)
-    rescue RateLimitError
-      # Le client a déjà relancé avec backoff : quelques tentatives de plus suffisent.
-      raise if attempt >= DEFAULT_RETRY_COUNT
-
-      log_rate_limit_hit("summary", target_locale)
-      sleep(DEFAULT_RETRY_DELAY)
-      request_summary(prompt, target_locale, attempt + 1)
+        result[:summary]
+      end
     end
 
     def clean_document_content(content)
@@ -157,36 +148,8 @@ module MistralTranslator
       raise ArgumentError, "Long length must be greater than medium" unless long > medium
     end
 
-    def log_retry(error, attempt, wait_time, locale)
-      message = "Summary retry #{attempt}/#{DEFAULT_RETRY_COUNT} for #{locale} in #{wait_time}s: #{error.message}"
-      # Log une seule fois par locale et type d'erreur
-      Logger.warn_once(message, key: "summary_retry_#{locale}_#{error.class.name}", sensitive: false, ttl: 120)
-    end
-
-    def log_rate_limit_hit(operation, locale)
-      message = "Rate limit hit for #{operation} in #{locale}, retrying..."
-      # Log une seule fois par opération et locale
-      Logger.warn_once(message, key: "summary_rate_limit_#{operation}_#{locale}", sensitive: false, ttl: 300)
-    end
-
     def log_debug(message)
-      # Log de debug seulement si mode verbose activé
       Logger.debug_if_verbose(message, sensitive: false)
-
-      # Pour les tests, permettre un output dans stdout si nécessaire
-      return unless ENV["MISTRAL_TRANSLATOR_TEST_OUTPUT"] == "true"
-
-      puts "[MistralTranslator] #{message}"
-    end
-
-    def log_error(message)
-      # Utiliser le logger centralisé
-      Logger.warn(message, sensitive: false)
-
-      # Pour les tests, optionnellement afficher en stdout
-      return unless ENV["MISTRAL_TRANSLATOR_TEST_OUTPUT"] == "true"
-
-      puts "[MistralTranslator] ERROR: #{message}"
     end
   end
 end

data/lib/mistral_translator/translator.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
 require_relative "logger"
+require_relative "retries"
 require_relative "translator_helpers"
 require_relative "security"
 
 module MistralTranslator
   class Translator
+    include Retries
     include TranslatorHelpers::InputValidator
-    include TranslatorHelpers::RetryHandler
-    include TranslatorHelpers::LoggingHelper
     include TranslatorHelpers::AnalysisHelper
     include TranslatorHelpers::RequestHelper
     include TranslatorHelpers::MultiTargetHelper
 
-    DEFAULT_RETRY_COUNT = 3
-    DEFAULT_RETRY_DELAY = 2
+    DEFAULT_RETRY_COUNT = Retries::RETRY_COUNT
+    DEFAULT_RETRY_DELAY = Retries::RETRY_DELAY
 
     def initialize(client: nil)
       @client = client || Client.new
@@ -176,29 +176,15 @@ module MistralTranslator
       nil
     end
 
-    def translate_with_retry(text, source_locale, target_locale, attempt = 0, **options)
-      prompt = build_prompt_for_retry(text, source_locale, target_locale, **options)
-      request_context = build_request_context(source_locale, target_locale, attempt)
+    def translate_with_retry(text, source_locale, target_locale, **)
+      prompt = build_translation_prompt(text, source_locale, target_locale, **)
 
-      raw_response = perform_client_request(prompt, request_context)
-      extract_translated_text!(raw_response)
-    rescue EmptyTranslationError, InvalidResponseError => e
-      handle_retryable_error!(e, attempt) do
-        translate_with_retry(text, source_locale, target_locale, attempt + 1, **options)
+      with_retries(operation: "translation", subject: "#{source_locale}->#{target_locale}") do |attempt|
+        raw_response = perform_client_request(prompt, build_request_context(source_locale, target_locale, attempt))
+        extract_translated_text!(raw_response)
       end
-    rescue RateLimitError
-      # Le client a déjà relancé avec backoff : quelques tentatives de plus suffisent.
-      raise if attempt >= DEFAULT_RETRY_COUNT
-
-      log_rate_limit_hit(source_locale, target_locale)
-      sleep(DEFAULT_RETRY_DELAY)
-      translate_with_retry(text, source_locale, target_locale, attempt + 1, **options)
     end
 
-    # Ces méthodes sont héritées via RequestHelper
-
-    # Log via LoggingHelper
-
     def build_translation_prompt(text, source_locale, target_locale, **options)
       PromptBuilder.translation_prompt(text, source_locale, target_locale,
                                        context: options[:context],

data/lib/mistral_translator/translator_helpers.rb

@@ -20,75 +20,6 @@ module MistralTranslator
         validate_inputs!(text, from, to)
         raise ArgumentError, "Target languages cannot be empty" if Array(to).empty?
       end
-
-      def validate_batch_inputs!(texts, from, to)
-        raise ArgumentError, "Texts array cannot be nil or empty" if texts.nil? || texts.empty?
-
-        ensure_present!(from, "Source language")
-        ensure_present!(to, "Target language")
-
-        texts.each_with_index do |t, i|
-          ensure_present!(t, "Text at index #{i}")
-        end
-      end
-
-      private
-
-      def ensure_present!(value, field_name)
-        raise ArgumentError, "#{field_name} cannot be nil or empty" if value.nil? || value.to_s.strip.empty?
-      end
-    end
-
-    # Helper pour la gestion des retry
-    module RetryHandler
-      DEFAULT_RETRY_DELAY = 2
-
-      def handle_retry_error(error, source_locale, target_locale, attempt)
-        case error
-        when RateLimitError
-          handle_rate_limit_retry?(source_locale, target_locale, attempt)
-        when ApiError
-          handle_api_error_retry?(error, source_locale, target_locale, attempt)
-        else
-          raise error
-        end
-      end
-
-      # Renvoie true si un retry a été effectué
-      def handle_rate_limit_retry?(source_locale, target_locale, _attempt)
-        log_rate_limit_hit(source_locale, target_locale)
-        sleep(DEFAULT_RETRY_DELAY)
-        # NOTE: retry logic should be handled by the calling method
-        true
-      end
-
-      # Renvoie true si un retry a été effectué
-      def handle_api_error_retry?(error, _source_locale, _target_locale, attempt)
-        raise error unless attempt < 3 && error.message.include?("timeout")
-
-        Logger.warn("API timeout, retrying... (attempt #{attempt + 1})")
-        sleep(DEFAULT_RETRY_DELAY)
-        # NOTE: retry logic should be handled by the calling method
-        true
-      end
-    end
-
-    # Helper pour le logging
-    module LoggingHelper
-      def log_rate_limit_hit(source_locale, target_locale)
-        message = "Rate limit hit for #{source_locale}->#{target_locale}"
-        Logger.warn_once(message, key: "rate_limit_#{source_locale}_#{target_locale}", sensitive: false, ttl: 300)
-      end
-
-      def log_translation_attempt(source_locale, target_locale, attempt)
-        Logger.debug("Translation attempt #{attempt} for #{source_locale}->#{target_locale}")
-      end
-
-      def log_retry(error, attempt, wait_time)
-        default_retry_count = MistralTranslator::Translator::DEFAULT_RETRY_COUNT
-        message = "Translation retry #{attempt}/#{default_retry_count} in #{wait_time}s: #{error.message}"
-        Logger.warn_once(message, key: "translate_retry_#{error.class.name}_#{attempt}", sensitive: false, ttl: 120)
-      end
     end
 
     # Helper pour l'analyse et la détection de langue
@@ -140,17 +71,6 @@ module MistralTranslator
 
     # Helper pour requêtes client et retries
     module RequestHelper
-      def build_prompt_for_retry(text, source_locale, target_locale, **options)
-        build_translation_prompt(
-          text,
-          source_locale,
-          target_locale,
-          context: options[:context],
-          glossary: options[:glossary],
-          preserve_html: options.fetch(:preserve_html, false)
-        )
-      end
-
       def build_request_context(source_locale, target_locale, attempt)
         {
           from_locale: source_locale,
@@ -170,15 +90,6 @@ module MistralTranslator
 
         raise EmptyTranslationError
       end
-
-      def handle_retryable_error!(error, attempt)
-        raise error unless attempt < MistralTranslator::Translator::DEFAULT_RETRY_COUNT
-
-        wait_time = MistralTranslator::Translator::DEFAULT_RETRY_DELAY * (2**attempt)
-        log_retry(error, attempt + 1, wait_time)
-        sleep(wait_time)
-        yield
-      end
     end
 
     # Helper pour traductions multi-cibles

data/lib/mistral_translator/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module MistralTranslator
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 
   # Informations additionnelles sur la gem
   API_VERSION = "v1"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mistral_translator
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Pierre Cherbero
@@ -160,6 +160,7 @@ files:
 - lib/mistral_translator/client_helpers.rb
 - lib/mistral_translator/configuration.rb
 - lib/mistral_translator/data/languages.json
+- lib/mistral_translator/deprecated_options.rb
 - lib/mistral_translator/errors.rb
 - lib/mistral_translator/helpers.rb
 - lib/mistral_translator/helpers_extensions.rb
@@ -172,6 +173,7 @@ files:
 - lib/mistral_translator/prompt_metadata_helpers.rb
 - lib/mistral_translator/proxy.rb
 - lib/mistral_translator/response_parser.rb
+- lib/mistral_translator/retries.rb
 - lib/mistral_translator/security.rb
 - lib/mistral_translator/summarizer.rb
 - lib/mistral_translator/translator.rb