mistral_translator 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73a244fe12fa2b20b8541ae5fda6ad872072b39494a4df7898eeaef52463ecda
-  data.tar.gz: d2542178c4b3bea537b3d2737341809457141fea38f3a6354c7ccf6c0feb86e2
+  metadata.gz: 5e52138d192d693042abbc570da3a9ed1f7f56acaed881c46a59df100dc476a0
+  data.tar.gz: 74a169d74c5248dc7ec1cab84c5892018eeacf3ba398bfb0b0a3c41a98d87ae9
 SHA512:
-  metadata.gz: 4c307437bb32492e4a428eb1f37b868306e48f9c90229aab59565226199c322a8a142ecb41da83ce5c99d6c807c47dc85281ee4e2b09a51870cdba72405ed94e
-  data.tar.gz: aa2153e0a4f70459e2983c13c4cb529e836aff7262cc7d9411b9a43c685a105a47ba9961180188f87fe84eb6b7dd2563da6c653611ab4e843a5eeb032f738159
+  metadata.gz: 3f324d7cb87b75c340d1875fc6189c13c39dfe26c1878ff187c30c04674b88549c813be6f73c644b2b01a5f28ed5e88da55351c86b37800d9648835113f58b3e
+  data.tar.gz: 0d9ac452969b457ed81cd34295e564d869c3e8f254e0807a8d473af8c99fbcb10f0d2ea5bc5abea518a0f7bd59d978428dac8e5c25864c63a4fa61d0dfb1617a

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 ## [Unreleased]
 
+## [0.3.0] - 2025-12-09
+
+### Added
+
+- Thread-safe metrics with Mutex protection for concurrent usage
+- Connection pooling with net-http-persistent (automatic connection reuse)
+- SSL/TLS configuration options: `ssl_verify_mode`, `ssl_ca_file`, `ssl_ca_path`, `ssl_timeout`
+- Thread-safe logger cache for `warn_once` method
+- Comprehensive concurrent/async documentation with SolidQueue, Sidekiq, Concurrent Ruby examples
+- 39 new tests for thread-safety, SSL configuration, and connection pooling
+
+### Changed
+
+- HTTP client now uses Net::HTTP::Persistent for better performance
+- Configuration metrics now thread-safe across concurrent requests
+- Documentation reorganized with SolidQueue as recommended background job backend
+
+### Performance
+
+- Connection pooling reduces TCP handshake overhead
+- Thread-safe implementation enables safe concurrent translations
+- Configurable SSL timeout for production environments
+
+## [0.2.0] - 2025-09-09
+
+### Added
+
+- Contexte et glossaire via `MistralTranslator::Translator#translate`
+- Rate limiting client (50 req/min par défaut, thread-safe)
+- Validation basique des entrées (max 50k chars, batch ≤ 20)
+- Nouvelles erreurs: `SecurityError`, `RateLimitExceededError`
+- Métriques intégrées et callbacks de monitoring
+- Documentation mise à jour + guide de migration 0.1.0 → 0.2.0
+
+### Changed
+
+- Exemples et docs: utilisation d’une instance `Translator` pour `context`/`glossary`
+- Amélioration de la structure interne (client/translator/summarizer)
+
+### Fixed
+
+- Masquage renforcé des secrets dans VCR
+- Messages d’erreurs plus explicites pour les réponses invalides
+
 ## [0.1.0] - 2025-09-01
 
 - Initial release

data/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to MistralTranslator
+
+Thank you for your interest in contributing to MistralTranslator! We welcome contributions of all kinds.
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 3.2+
+- Bundler
+
+### Installation
+
+```bash
+git clone https://github.com/your-username/mistral_translator.git
+cd mistral_translator
+bundle install
+```
+
+## Running Tests
+
+```bash
+# Unit tests (no API key required)
+bundle exec rspec
+
+# Integration tests (requires real API key)
+export MISTRAL_API_KEY=your_key && bundle exec rspec spec/integration/mistral_api_integration_spec.rb
+
+# All tests with coverage
+bundle exec rspec --format documentation
+```
+
+## Contributing Guidelines
+
+### Reporting Issues
+
+- Use GitHub Issues for bug reports and feature requests
+- Include Ruby version, gem version, and relevant code snippets
+- For API-related issues, include sanitized request/response examples
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes with tests
+4. Ensure all tests pass: `bundle exec rspec`
+5. Follow Ruby style conventions (we use RuboCop - no error) : `bundle exec rubocop`
+6. Submit a pull request with a clear description
+
+### Code Standards
+
+- Write tests for new features and bug fixes
+- Follow existing code patterns and architecture
+- Update documentation for public API changes
+- Keep commits atomic and well-described
+
+### Testing
+
+- Unit tests should not require API calls (use mocks/stubs)
+- Integration tests should use VCR cassettes when possible
+- Test edge cases and error conditions
+- Test coverage must be at 100% (for now)
+
+## Release Process
+
+Releases are handled by maintainers following semantic versioning.
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing.

data/LICENSE.txt

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2025 PierreArko
+Copyright (c) 2024 Pierre Cherbero (peyochanchan)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,205 +1,298 @@
 # MistralTranslator
 
-Une gem Ruby pour traduire et résumer du texte en utilisant l'API Mistral AI.
+Ruby gem for AI-powered translation and text summarization using Mistral AI API, with advanced Rails support.
 
-## Installation
+[![Ruby](https://img.shields.io/badge/ruby-%23CC342D.svg?style=flat&logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Gem Version](https://badge.fury.io/rb/mistral_translator.svg)](https://badge.fury.io/rb/mistral_translator)
+[![RSpec](https://img.shields.io/badge/tested%20with-RSpec-red.svg)](https://rspec.info/)
+[![RuboCop](https://img.shields.io/badge/code%20style-RuboCop-brightgreen.svg)](https://rubocop.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Ajoutez cette ligne à votre Gemfile :
+## Quick Start
 
 ```ruby
+# Installation
 gem 'mistral_translator'
+
+# Configuration
+MistralTranslator.configure do |config|
+  config.api_key = ENV['MISTRAL_API_KEY']
+end
+
+# Basic usage
+MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
+# => "Hello world"
 ```
 
-Puis exécutez :
+## Key Features
 
-```bash
-bundle install
+- **Smart translation** with context and custom glossaries
+- **Native Rails integration** (Mobility, Globalize, I18n attributes)
+- **Batch processing** for high-volume translations
+- **Multi-level summarization** with translation
+- **Robust error handling** with automatic retry and fallback
+- **Complete monitoring** with metrics and callbacks
+- **Thread-safe & concurrent** with connection pooling ([docs](https://peyochanchan.github.io/mistral_translator/#/advanced-usage/concurrent-async))
+- **Built-in rate limiting** and security
+
+## Supported Languages
+
+`fr` `en` `es` `pt` `de` `it` `nl` `ru` `mg` `ja` `ko` `zh` `ar`
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'mistral_translator'
 ```
 
-Ou installez directement :
+Then run:
 
 ```bash
-gem install mistral_translator
+bundle install
 ```
 
-## Configuration
+### API Key Setup
+
+Get your API key from [Mistral AI Console](https://console.mistral.ai/) and configure it:
 
 ```ruby
-require 'mistral_translator'
+# Environment variable (recommended)
+export MISTRAL_API_KEY="your_api_key_here"
 
+# Or in Rails config/initializers/mistral_translator.rb
 MistralTranslator.configure do |config|
-  config.api_key = 'votre_clé_api_mistral'
-  config.api_url = 'https://api.mistral.ai'  # optionnel
-  config.model = 'mistral-small'             # optionnel
+  config.api_key = ENV['MISTRAL_API_KEY']
+  config.enable_metrics = Rails.env.production?
 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
+## Basic Usage Examples
 
-### Traduction simple
+### Simple Translation
 
 ```ruby
-# Traduction de base
-result = MistralTranslator.translate("Bonjour le monde", from: 'fr', to: 'en')
-# => "Hello world"
+# Basic translation
+result = MistralTranslator.translate("Bonjour", from: "fr", to: "en")
+# => "Hello"
 
-# Vers plusieurs langues
-results = MistralTranslator.translate_to_multiple(
-  "Bonjour le monde", 
-  from: 'fr', 
-  to: ['en', 'es', 'de']
+# With context for better accuracy
+result = MistralTranslator.translate(
+  "Le produit est disponible",
+  from: "fr",
+  to: "en",
+  context: "E-commerce website"
 )
-# => { 'en' => "Hello world", 'es' => "Hola mundo", 'de' => "Hallo Welt" }
+# => "The product is available"
+
+# With custom glossary
+result = MistralTranslator.translate(
+  "Notre API est performante",
+  from: "fr",
+  to: "en",
+  glossary: { "API" => "API" }  # Preserve technical terms
+)
+# => "Our API is high-performing"
 ```
 
-### Traduction en lot
+### Auto-Detection
 
 ```ruby
-texts = ["Bonjour", "Au revoir", "Merci"]
-results = MistralTranslator.translate_batch(texts, from: 'fr', to: 'en')
-# => { 0 => "Hello", 1 => "Goodbye", 2 => "Thank you" }
+# Automatic source language detection
+MistralTranslator.translate_auto("¡Hola mundo!", to: "fr")
+# => "Salut le monde !"
 ```
 
-### Auto-détection de langue
+### Batch Processing
 
 ```ruby
-result = MistralTranslator.translate_auto("Hello world", to: 'fr')
-# => "Bonjour le monde"
+texts = ["Bonjour", "Merci", "Au revoir"]
+results = MistralTranslator.translate_batch(texts, from: "fr", to: "en")
+# => {0 => "Hello", 1 => "Thank you", 2 => "Goodbye"}
 ```
 
-### Résumés
+### Text Summarization
 
 ```ruby
-long_text = "Un très long texte à résumer..."
+long_text = "Ruby on Rails is a web framework..."
 
-# Résumé simple
-summary = MistralTranslator.summarize(long_text, language: 'fr', max_words: 100)
+# Simple summary
+summary = MistralTranslator.summarize(long_text, language: "en", max_words: 50)
 
-# Résumé avec traduction
+# Summary with translation
 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
+  from: "en",
+  to: "fr",
+  max_words: 100
 )
-# => { short: "...", medium: "...", long: "..." }
 ```
 
-### Extensions String (optionnel)
+### Rails Integration
 
 ```ruby
-# Activer les extensions String
-ENV['MISTRAL_TRANSLATOR_EXTEND_STRING'] = 'true'
-require 'mistral_translator'
-
-"Bonjour".mistral_translate(from: 'fr', to: 'en')
-# => "Hello"
+# With Mobility
+class Article < ApplicationRecord
+  extend Mobility
+  translates :title, :content, backend: :table
+
+  def translate_to_all_languages!
+    MistralTranslator::RecordTranslation.translate_mobility_record(
+      self,
+      [:title, :content],
+      source_locale: I18n.locale
+    )
+  end
+end
 
-"Long texte...".mistral_summarize(language: 'fr', max_words: 50)
-# => "Résumé..."
+# Usage
+article = Article.create!(title_fr: "Titre français", content_fr: "Contenu...")
+article.translate_to_all_languages!
 ```
 
-## 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)
+## Configuration Options
 
 ```ruby
-# Vérifier les langues supportées
-MistralTranslator.supported_languages
-MistralTranslator.locale_supported?('fr') # => true
+MistralTranslator.configure do |config|
+  # Required
+  config.api_key = ENV['MISTRAL_API_KEY']
+
+  # Optional
+  config.model = "mistral-small"                    # AI model to use
+  config.retry_delays = [1, 2, 4, 8, 16]          # Retry delays in seconds
+  config.enable_metrics = true                     # Enable performance metrics
+
+  # Callbacks for monitoring
+  config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
+    Rails.logger.info "Translation #{from}→#{to} completed in #{duration.round(2)}s"
+  }
+
+  config.on_translation_error = ->(from, to, error, attempt, timestamp) {
+    Rails.logger.error "Translation failed: #{error.message} (attempt #{attempt})"
+  }
+end
 ```
 
-## Gestion d'erreurs
+## Error Handling
 
 ```ruby
 begin
-  result = MistralTranslator.translate("Hello", from: 'en', to: 'fr')
+  result = MistralTranslator.translate("Hello", from: "en", to: "fr")
 rescue MistralTranslator::RateLimitError
-  puts "Rate limit dépassé, réessayez plus tard"
+  # Rate limit hit - automatic retry with backoff
+  retry
 rescue MistralTranslator::AuthenticationError
-  puts "Clé API invalide"
+  # Invalid API key
+  Rails.logger.error "Check your Mistral API key"
 rescue MistralTranslator::UnsupportedLanguageError => e
-  puts "Langue non supportée: #{e.language}"
+  # Language not supported
+  Rails.logger.error "Language '#{e.language}' not supported"
+rescue MistralTranslator::Error => e
+  # General error handling
+  Rails.logger.error "Translation failed: #{e.message}"
 end
 ```
 
-## Utilisation avancée
-
-### Client personnalisé
+## Performance Monitoring
 
 ```ruby
-client = MistralTranslator::Client.new(api_key: 'autre_clé')
-translator = MistralTranslator::Translator.new(client: client)
-result = translator.translate("Hello", from: 'en', to: 'fr')
+# Enable metrics
+MistralTranslator.configure { |c| c.enable_metrics = true }
+
+# View metrics
+metrics = MistralTranslator.metrics
+puts "Total translations: #{metrics[:total_translations]}"
+puts "Average time: #{metrics[:average_translation_time]}s"
+puts "Error rate: #{metrics[:error_rate]}%"
 ```
 
-### Health check
+## 📖 Complete Documentation
 
-```ruby
-status = MistralTranslator.health_check
-# => { status: :ok, message: "API connection successful" }
-```
+**For comprehensive guides, advanced usage, and Rails integration examples:**
+
+### 🌐 [**Full Documentation Website**](https://peyochanchan.github.io/mistral_translator/)
 
-## Développement
+The complete documentation includes:
 
-Après avoir cloné le repo :
+- **Getting Started Guide** - Step-by-step tutorials
+- **Advanced Usage** - Context, glossaries, batch processing, monitoring
+- **Rails Integration** - Mobility, Globalize, jobs, controllers
+- **API Reference** - Complete method documentation
+- **Examples** - Ready-to-use code samples
+- **Error Handling** - Comprehensive error management strategies
+
+### Quick Links
+
+- [Installation & Setup](https://peyochanchan.github.io/mistral_translator/#/installation)
+- [Rails Integration Guide](https://peyochanchan.github.io/mistral_translator/#/rails-integration/setup)
+- [API Methods Reference](https://peyochanchan.github.io/mistral_translator/#/api-reference/methods)
+- [Error Handling Guide](https://peyochanchan.github.io/mistral_translator/#/api-reference/errors)
+- [Monitoring Setup](https://peyochanchan.github.io/mistral_translator/#/advanced-usage/monitoring)
+
+## Requirements
+
+- Ruby 3.2+
+- Mistral AI API key
+- Rails 6.0+ (optional, for Rails integration features)
+
+## Testing
 
 ```bash
+# Install dependencies
 bundle install
-bin/setup
-```
 
-Pour lancer les tests :
+# Run all unit tests (no API key required)
+bundle exec rspec spec/mistral_translator/
 
-```bash
-bundle exec rspec
+# Run all tests with documentation format
+bundle exec rspec --format documentation
 ```
 
-Pour lancer RuboCop :
+### Integration Tests
+
+Integration tests require a real Mistral API key. **Never commit API keys to version control.**
 
 ```bash
-bundle exec rubocop
+# Set API key via environment variable (recommended)
+export MISTRAL_API_KEY="your_api_key_here"
+
+# Run integration tests
+bundle exec rspec spec/integration/
+
+**Security Note:** Use a dedicated test API key with limited quotas for integration testing.
 ```
 
-## Contribution
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE.txt) for details.
+
+## Support
 
-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
+- 📖 [Documentation](https://peyochanchan.github.io/mistral_translator/)
+- 🐛 [Issues](../../issues)
+- 📧 Support: Create an issue for help
 
-## Licence
+### ☕ Support the Project
 
-Cette gem est disponible sous la licence MIT.
+If this gem helps you, consider supporting its development:
+
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/peyochanchan)
+
+---
+
+Built with Ruby ❤️ by [@peyochanchan](https://github.com/peyochanchan)
+
+```
+
+```

data/README_TESTING.md

@@ -0,0 +1,33 @@
+# Tests de la gem MistralTranslator
+
+## Types de tests
+
+### 1. Tests unitaires (par défaut)
+
+- Utilisent des mocks et stubs
+- Pas besoin de clé API
+- Rapides et fiables
+
+### 2. Tests d'intégration
+
+- Marqués avec `:integration`
+- Nécessitent `MISTRAL_TEST_API_KEY`
+- Utilisent la vraie API Mistral
+
+### 3. Tests VCR
+
+- Marqués avec `:vcr`
+- Enregistrent les réponses API
+- Rejouent les réponses sans nouvelle requête
+
+## Configuration
+
+### Variables d'environnement
+
+```bash
+# Pour les tests d'intégration (optionnel)
+export MISTRAL_TEST_API_KEY="votre_cle_de_test"
+
+# Alternative (utilise votre clé principale)
+export MISTRAL_API_KEY="votre_cle_principale"
+```