polylingo_chat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03e17e594f585909ba895a3dab27bda4b0f731bd59fd12fac90dd5a0df7afe2e
+  data.tar.gz: e0ae5358db6d20f888e1524af38458e3457a9583bd31837a3ca6db3d33937d68
+SHA512:
+  metadata.gz: 868e647b05dd1d14836fcbe8aa794cdb6f5ffd0dd3629255e79833e849a963bf6c7ad2b58d0bfd146aec673b2305ab2706dcb7d656bf1a53dfeb805613258478
+  data.tar.gz: 26d96b4e747de39519e76f4c3158215caebd940e5acbbd656f6403039904df4f7d63cfe9d627e750b884f7e9c27053be3c6b30b1c047dbc96891351095093189

data/README.md

@@ -0,0 +1,432 @@
+# PolylingoChat — Real-time Multilingual Chat Engine for Rails
+
+PolylingoChat is a plug-and-play Rails Engine that adds real-time chat to your Rails app. Use it as a **chat-only engine** or enable **AI-powered translation** for multilingual conversations.
+
+Perfect for marketplaces, SaaS apps, CRMs, support systems, or global communities.
+
+---
+
+## ✨ Features
+
+- 🔥 **Real-time chat** using ActionCable with Solid Cable (database-backed)
+- 🚀 **One-command installer** — everything set up automatically
+- 🌍 **Optional AI translation** - works with or without translation
+- ⚙️ **Multi-provider support** — OpenAI, Anthropic Claude, or Google Gemini
+- 🧩 **Rails Engine** — mounts directly inside your app
+- 👥 **Conversations, Participants & Messages** models included
+- 🔌 **Works with any ActiveJob backend** (Sidekiq, Solid Queue, Delayed Job, etc.)
+- 🔐 **Secure & scoped** ActionCable channels
+- 🧱 **Extendable architecture** (custom UI, custom providers, custom storage)
+- 💾 **Built-in caching** support for translations
+- 🧪 **RSpec testing** framework included
+- 🗄️ **No Redis required** — uses Solid Cable for WebSocket persistence
+
+---
+
+## 📋 Requirements
+
+- Ruby >= 2.7.0
+- Rails >= 6.0
+- A background job processor (Sidekiq, Solid Queue, or Delayed Job)
+- **Optional:** AI API key (only if you want translation)
+
+**Note:** PolylingoChat uses **Solid Cable** (database-backed ActionCable) by default, so Redis is optional.
+
+---
+
+## 🚀 Installation
+
+### 1. Add the gem
+```ruby
+# Gemfile
+gem "polylingo_chat", github: "AdwareTechnologies/polylingo_chat"
+
+# Add a background job processor
+gem 'sidekiq'  # or 'solid_queue' or 'delayed_job_active_record'
+```
+
+### 2. Install and generate
+```bash
+bundle install
+bin/rails generate polylingo_chat:install
+bin/rails db:migrate
+```
+
+**The installer automatically:**
+- ✅ Creates migrations for Conversations, Participants, and Messages
+- ✅ Generates model files with associations
+- ✅ Sets up ActionCable channels (PolylinguoChatChannel)
+- ✅ Creates JavaScript files for real-time chat
+- ✅ Configures Solid Cable in `config/cable.yml`
+- ✅ Downloads ActionCable ESM module to `vendor/javascript`
+- ✅ Updates `config/routes.rb` with chat routes
+- ✅ Updates `config/importmap.rb` with required pins
+- ✅ Updates `app/javascript/application.js` with chat import
+- ✅ Creates `config/initializers/polylingo_chat.rb` for configuration
+
+### 3. Configure ActiveJob
+```ruby
+# config/application.rb or config/environments/production.rb
+config.active_job.queue_adapter = :sidekiq  # or :solid_queue, :delayed_job, :async
+```
+
+### 4. Add preferred_language to User (optional, only if using translation)
+```bash
+bin/rails generate migration AddPreferredLanguageToUsers preferred_language:string
+bin/rails db:migrate
+```
+
+### 5. Configure PolylingoChat
+
+Edit `config/initializers/polylingo_chat.rb` (created by installer):
+
+**Option A: Chat-Only Mode (No Translation)**
+```ruby
+PolylingoChat.configure do |config|
+  # Leave api_key as nil for chat-only mode
+  config.api_key = nil
+
+  config.queue_adapter = :sidekiq
+  config.async = true
+end
+```
+
+**Option B: With AI Translation**
+```ruby
+PolylingoChat.configure do |config|
+  # Enable translation by setting API key
+  config.provider = :openai  # or :anthropic, :gemini
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.model = 'gpt-4o-mini'
+
+  config.queue_adapter = :sidekiq
+  config.default_language = 'en'
+  config.cache_store = Rails.cache
+  config.timeout = 15
+  config.async = true
+end
+```
+
+### 6. Configure ActionCable Authentication
+
+The installer creates `app/channels/application_cable/connection.rb` with authentication logic. For development, it accepts `user_id` from WebSocket params:
+
+```ruby
+# app/channels/application_cable/connection.rb
+def find_verified_user
+  user_id = request.params[:user_id] || cookies.encrypted[:user_id]
+
+  if user_id && (verified_user = User.find_by(id: user_id))
+    verified_user
+  else
+    reject_unauthorized_connection
+  end
+end
+```
+
+The JavaScript consumer automatically passes `window.currentUserId` to authenticate. Make sure to set this in your views:
+
+```erb
+<!-- app/views/conversations/show.html.erb -->
+<script>
+  window.conversationId = <%= @conversation.id %>;
+  window.currentUserId = <%= current_user.id %>;
+</script>
+```
+
+**For production:** Replace the `find_verified_user` method with your actual authentication (Devise, session, JWT, etc.)
+
+### 7. Start your background worker
+```bash
+bundle exec sidekiq  # or bin/rails solid_queue:start, or bin/rails jobs:work
+```
+
+---
+
+## 🎯 Usage
+
+### 1. Set up your view
+
+First, expose the conversation and user IDs to JavaScript in your chat view:
+
+```erb
+<!-- app/views/conversations/show.html.erb -->
+<script>
+  window.conversationId = <%= @conversation.id %>;
+  window.currentUserId = <%= current_user.id %>;
+</script>
+
+<div id="messages">
+  <!-- Messages will appear here via ActionCable -->
+</div>
+```
+
+### 2. Send a message
+
+```ruby
+# Create a conversation
+conversation = Conversation.create!(title: "Project Discussion")
+
+# Add participants
+Participant.create!(conversation: conversation, user: user1)
+Participant.create!(conversation: conversation, user: user2)
+
+# Send a message
+Message.create!(
+  conversation: conversation,
+  sender: user1,
+  body: "Hello! How are you?"
+)
+```
+
+**What happens:**
+- Message is saved to database
+- Background job is enqueued automatically
+- **Without API key:** Message is broadcast as-is to all participants
+- **With API key:** Message is translated to each participant's preferred language
+- All participants see the message in real-time via ActionCable
+
+### 3. Real-time updates with ActionCable
+
+The installer creates JavaScript files that handle real-time updates automatically. The key file is `app/javascript/chat.js`:
+
+```javascript
+// This file is automatically generated by the installer
+// It connects to PolylinguoChatChannel and handles incoming messages
+
+import consumer from "channels/consumer"
+
+consumer.subscriptions.create({
+  channel: "PolylinguoChatChannel",
+  conversation_id: window.conversationId
+}, {
+  received(data) {
+    // data.message - message text (translated if translation enabled)
+    // data.original - original text
+    // data.sender_id - sender's ID
+    // data.translated - boolean (true if translation was used)
+    console.log("Received:", data.message)
+    console.log("Was translated:", data.translated)
+
+    // The generated code automatically appends messages to #messages div
+  }
+})
+```
+
+**You don't need to write this code** — the installer creates it for you!
+
+---
+
+## 🌍 Translation (Optional)
+
+### When to Use Translation
+
+Translation is **optional**. Use it when:
+- ✅ You have a global user base speaking different languages
+- ✅ You want automatic message translation
+- ✅ You're willing to pay for AI API usage
+
+Skip translation when:
+- ❌ All users speak the same language
+- ❌ You want a simple chat without AI costs
+- ❌ You'll handle translation elsewhere
+
+### AI Providers
+
+#### OpenAI
+```ruby
+config.provider = :openai
+config.api_key = ENV['OPENAI_API_KEY']
+config.model = 'gpt-4o-mini'  # Fast & cost-effective
+```
+Get key: https://platform.openai.com/api-keys
+
+**Models:** `gpt-4o-mini`, `gpt-4o`, `gpt-3.5-turbo`
+
+#### Anthropic Claude
+```ruby
+config.provider = :anthropic
+config.api_key = ENV['ANTHROPIC_API_KEY']
+config.model = 'claude-3-5-sonnet-20241022'
+```
+Get key: https://console.anthropic.com/
+
+**Models:** `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`, `claude-3-opus-20240229`
+
+#### Google Gemini
+```ruby
+config.provider = :gemini
+config.api_key = ENV['GOOGLE_API_KEY']
+config.model = 'gemini-1.5-flash'
+```
+Get key: https://ai.google.dev/
+
+**Models:** `gemini-1.5-flash`, `gemini-1.5-pro`
+
+---
+
+## ⚙️ Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `provider` | Symbol | `:openai` | AI provider (`:openai`, `:anthropic`, `:gemini`) |
+| `api_key` | String | `nil` | API key - leave nil for chat-only mode |
+| `model` | String | `'gpt-4o-mini'` | Model name for the provider |
+| `queue_adapter` | Symbol | `nil` | Which ActiveJob adapter you're using (informational) |
+| `default_language` | String | `'en'` | Default target language (ISO 639-1 code) |
+| `cache_store` | Cache | `nil` | Rails cache store for caching translations |
+| `async` | Boolean | `true` | Enable async processing via ActiveJob |
+| `timeout` | Integer | `15` | API request timeout in seconds |
+
+---
+
+## 🏗️ How It Works
+
+### Message Flow
+
+1. User sends a message → saved to database
+2. `Message#after_create_commit` enqueues job
+3. Job runs in background via your ActiveJob adapter
+4. **If API key present:** Message translated for each participant
+5. **If no API key:** Original message used for all participants
+6. Messages broadcast via ActionCable (using Solid Cable)
+7. Recipients see messages in real-time
+
+### Models
+
+**Conversation** - Chat conversation with many participants and messages
+
+**Participant** - Join table linking Users to Conversations
+
+**Message** - Individual chat message with translation tracking
+
+### Solid Cable (Database-Backed WebSockets)
+
+PolylingoChat uses **Solid Cable** instead of Redis for ActionCable. Benefits:
+
+- ✅ **No Redis dependency** - One less service to manage
+- ✅ **Message persistence** - WebSocket messages stored in database
+- ✅ **Simpler deployment** - Works anywhere your database works
+- ✅ **Better for development** - No need to run Redis locally
+- ✅ **Cost-effective** - No separate Redis hosting required
+
+Solid Cable uses your existing database (SQLite, PostgreSQL, MySQL) to store WebSocket messages with configurable retention:
+
+```yaml
+# config/cable.yml (configured automatically by installer)
+development:
+  adapter: solid_cable
+  polling_interval: 0.1.seconds
+  message_retention: 1.day
+```
+
+The installer runs `bin/rails solid_cable:install` automatically, which creates the necessary migrations.
+
+---
+
+## 🧪 Running Tests
+
+```bash
+bundle exec rspec
+
+# Current status:
+# 29 examples, 0 failures
+# Line Coverage: 91.02%
+```
+
+---
+
+## 🚀 Performance Tips
+
+### 1. Enable Caching (if using translation)
+```ruby
+config.cache_store = Rails.cache
+```
+
+### 2. Choose the Right Model
+- **High-volume:** `gpt-4o-mini`, `claude-3-5-haiku`, `gemini-1.5-flash`
+- **Quality:** `gpt-4o`, `claude-3-5-sonnet`, `gemini-1.5-pro`
+
+### 3. Scale Your Job Processor
+
+**Sidekiq:**
+```yaml
+# config/sidekiq.yml
+:concurrency: 25
+:queues:
+  - [polylingo_chat_translations, 10]
+  - [default, 5]
+```
+
+**Solid Queue:**
+```yaml
+# config/solid_queue.yml
+workers:
+  - queues: polylingo_chat_translations
+    threads: 5
+    processes: 3
+```
+
+---
+
+## 🔒 Security
+
+1. **API Keys:** Use environment variables, never commit
+2. **User Scoping:** Ensure users can only access their conversations
+3. **ActionCable Auth:** Secure channels with authentication
+4. **Rate Limiting:** Consider limiting message creation
+5. **Content Filtering:** Add profanity/spam filters if needed
+
+---
+
+## 💡 Use Cases
+
+### Chat-Only Mode (No Translation)
+Perfect for:
+- Internal team chat
+- Customer support (same language)
+- Community forums
+- Simple messaging features
+
+### With Translation
+Perfect for:
+- Global marketplaces
+- International teams
+- Multi-language support systems
+- Cross-border collaboration
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Write tests for your changes
+4. Commit and push
+5. Open a Pull Request
+
+---
+
+## 📝 License
+
+MIT License
+
+---
+
+## 👤 Author
+
+**Shoaib Malik**
+- Email: shoaib2109@gmail.com
+- GitHub: [@shoaibmalik786](https://github.com/shoaibmalik786)
+
+---
+
+## 📞 Support
+
+- 🐛 **Issues:** [GitHub Issues](https://github.com/shoaibmalik786/polylingo_chat/issues)
+- 📖 **Documentation:** [GitHub Wiki](https://github.com/shoaibmalik786/polylingo_chat/wiki)
+- 💬 **Discussions:** [GitHub Discussions](https://github.com/shoaibmalik786/polylingo_chat/discussions)
+
+---
+
+**Made with ❤️ for the global Rails community**

data/lib/generators/polylingo_chat/install/install_generator.rb

@@ -0,0 +1,107 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module PolylingoChat
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc "Installs PolylingoChat with real-time multilingual chat"
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migrations
+        migration_template "create_conversations.rb", "db/migrate/create_conversations.rb"
+        migration_template "create_participants.rb", "db/migrate/create_participants.rb"
+        migration_template "create_messages.rb", "db/migrate/create_messages.rb"
+      end
+
+      def create_models
+        template "models/conversation.rb", "app/models/conversation.rb"
+        template "models/participant.rb", "app/models/participant.rb"
+        template "models/message.rb", "app/models/message.rb"
+      end
+
+      def create_channels
+        empty_directory "app/channels/application_cable"
+        template "channels/application_cable/channel.rb", "app/channels/application_cable/channel.rb"
+        template "channels/application_cable/connection.rb", "app/channels/application_cable/connection.rb"
+        template "channels/polylingo_chat_chat_channel.rb", "app/channels/polylingo_chat_chat_channel.rb"
+      end
+
+      def create_javascript_files
+        empty_directory "app/javascript/channels"
+        template "javascript/chat.js", "app/javascript/chat.js"
+        template "javascript/channels/consumer.js", "app/javascript/channels/consumer.js"
+        template "javascript/channels/index.js", "app/javascript/channels/index.js"
+      end
+
+      def configure_cable
+        if File.exist?("config/cable.yml")
+          gsub_file "config/cable.yml", /^development:\s*\n\s+adapter:\s+\w+.*$/m do |match|
+            "development:\n  adapter: solid_cable\n  polling_interval: 0.1.seconds\n  message_retention: 1.day"
+          end
+        end
+      end
+
+      def setup_solid_cable
+        say "Setting up Solid Cable...", :green
+        rails_command "solid_cable:install", abort_on_failure: false
+      end
+
+      def download_actioncable
+        empty_directory "vendor/javascript"
+        say "Downloading ActionCable ESM module...", :green
+        run "curl -o vendor/javascript/@rails--actioncable.js https://ga.jspm.io/npm:@rails/actioncable@7.1.3/app/assets/javascripts/actioncable.esm.js"
+      end
+
+      def add_routes
+        route 'mount ActionCable.server => "/cable"'
+        route <<~RUBY
+          resources :conversations do
+            resources :messages, only: [:create]
+          end
+        RUBY
+      end
+
+      def update_importmap
+        if File.exist?("config/importmap.rb")
+          append_to_file "config/importmap.rb" do
+            <<~RUBY
+
+              # PolylingoChat real-time chat
+              pin "@rails/actioncable", to: "@rails--actioncable.js"
+              pin_all_from "app/javascript/channels", under: "channels"
+              pin "chat", to: "chat.js"
+            RUBY
+          end
+        end
+      end
+
+      def update_application_js
+        if File.exist?("app/javascript/application.js")
+          append_to_file "app/javascript/application.js" do
+            <<~JS
+
+              // PolylingoChat real-time chat
+              import "chat"
+            JS
+          end
+        end
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/polylingo_chat.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/polylingo_chat/install/templates/README

@@ -0,0 +1,48 @@
+===============================================================================
+
+PolylingoChat has been installed successfully!
+
+Next steps:
+
+1. Run migrations:
+   rails db:migrate
+
+2. Ensure your User model has a `preferred_language` column (optional):
+   rails g migration AddPreferredLanguageToUsers preferred_language:string
+   rails db:migrate
+
+3. Configure your AI provider in config/initializers/polylingo_chat.rb:
+   - Set config.api_key with your API key
+   - Choose your provider (:openai, :anthropic, or :gemini)
+   - Or leave api_key as nil for chat-only mode (no translation)
+
+4. Set up Solid Cable for production:
+   - Already configured for development
+   - For production, ensure database is configured in config/cable.yml
+
+5. Import chat.js in your application.js:
+   // Add to app/javascript/application.js
+   import "chat"
+
+6. Add this to your User model if it doesn't exist:
+   # app/models/user.rb
+   class User < ApplicationRecord
+     has_many :participants, dependent: :destroy
+     has_many :conversations, through: :participants
+     has_many :messages, foreign_key: 'sender_id', dependent: :destroy
+   end
+
+7. In your conversation view, add these window variables:
+   <script>
+     window.conversationId = <%= @conversation.id %>;
+     window.currentUserId = <%= current_user.id %>;
+   </script>
+
+8. Add a messages container in your view:
+   <div id="messages">
+     <!-- Messages will appear here in real-time -->
+   </div>
+
+For more information, visit: https://github.com/yourusername/polylingo_chat
+
+===============================================================================

data/lib/generators/polylingo_chat/install/templates/channels/application_cable/channel.rb

@@ -0,0 +1,4 @@
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

data/lib/generators/polylingo_chat/install/templates/channels/application_cable/connection.rb

@@ -0,0 +1,30 @@
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user
+
+    def connect
+      self.current_user = find_verified_user
+    end
+
+    private
+
+    def find_verified_user
+      # TODO: Implement your authentication logic here
+      # Example with Devise:
+      # if verified_user = env['warden'].user
+      #   verified_user
+      # else
+      #   reject_unauthorized_connection
+      # end
+
+      # For development/testing, accept user_id from request params or cookies:
+      user_id = request.params[:user_id] || cookies.encrypted[:user_id]
+
+      if user_id && (verified_user = User.find_by(id: user_id))
+        verified_user
+      else
+        reject_unauthorized_connection
+      end
+    end
+  end
+end

data/lib/generators/polylingo_chat/install/templates/channels/polylingo_chat_channel.rb

@@ -0,0 +1,15 @@
+class PolylinguoChatChannel < ApplicationCable::Channel
+  def subscribed
+    conversation_id = params[:conversation_id]
+
+    # Subscribe to conversation-level channel for demo
+    stream_from "conversation_#{conversation_id}"
+
+    # Also subscribe to user-specific channel for production use
+    stream_from "polylingo_chat_recipient_#{current_user.id}"
+  end
+
+  def unsubscribed
+    # Cleanup when channel is unsubscribed
+  end
+end

data/lib/generators/polylingo_chat/install/templates/create_conversations.rb

@@ -0,0 +1,9 @@
+class CreateConversations < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :conversations do |t|
+      t.string :title
+      t.boolean :private, default: true
+      t.timestamps
+    end
+  end
+end

data/lib/generators/polylingo_chat/install/templates/create_messages.rb

@@ -0,0 +1,13 @@
+class CreateMessages < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :messages do |t|
+      t.references :sender, null: false, foreign_key: { to_table: :users }
+      t.references :conversation, null: false, foreign_key: true
+      t.text :body
+      t.string :language
+      t.text :translated_body
+      t.boolean :translated, default: false
+      t.timestamps
+    end
+  end
+end

data/lib/generators/polylingo_chat/install/templates/create_participants.rb

@@ -0,0 +1,12 @@
+class CreateParticipants < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :participants do |t|
+      t.references :user, null: false, foreign_key: true
+      t.references :conversation, null: false, foreign_key: true
+      t.string :role
+      t.timestamps
+    end
+
+    add_index :participants, [:user_id, :conversation_id], unique: true
+  end
+end