rails_chatbot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13b20ee2717e914aea6e5634f28cee026b971f5b6ec3216f70e6cd48a860159a
+  data.tar.gz: 288ca5976edf919441a32264401b7fa26ea249f25de530d9b0319b8b937ba897
+SHA512:
+  metadata.gz: ddfdc4e42f4c3bf733f002232879fb96d7a7bfecd8e1a9b1319497d0ded151c8c91853773f10f085f88ffdd1e13b5afc82213865b2d4d450b960cc3a75d1cb46
+  data.tar.gz: 05167d520483a23de9df8153f0b5e459e5986e0a6fde86940e5082b6b4b567771eb1433c6498ed2a656c6a1ef51510e5323194ff2d81dbc6e174df687502f9af

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights 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 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.

data/README.md

@@ -0,0 +1,284 @@
+# RailsChatbot
+
+A powerful Rails engine gem that provides an intelligent chatbot system with knowledge base integration for your Ruby on Rails application. The chatbot can answer questions about your application by indexing your models and content.
+
+## � Quick Start Guide
+
+### Step 1: Install the Gem
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_chatbot"
+```
+
+Then execute:
+
+```bash
+$ bundle install
+```
+
+### Step 2: Run Migrations
+
+```bash
+$ rails rails_chatbot:install:migrations
+$ rails db:migrate
+```
+
+### Step 3: Configure OpenAI
+
+Create `config/initializers/rails_chatbot.rb`:
+
+```ruby
+RailsChatbot.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY'] # Required
+  config.openai_model = 'gpt-4o-mini' # Optional
+  config.chatbot_title = 'My App Assistant' # Optional
+end
+```
+
+Set your OpenAI API key:
+
+```bash
+export OPENAI_API_KEY=your_openai_api_key_here
+```
+
+### Step 4: Mount the Engine
+
+Add to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount RailsChatbot::Engine => "/chatbot"
+  
+  # Your other routes...
+end
+```
+
+### Step 5: Start Your Server
+
+```bash
+rails server
+```
+
+Visit `http://localhost:3000/chatbot` to see your chatbot!
+
+## 🧪 Testing Your Chatbot
+
+### 1. Test Basic Chat
+- Open `http://localhost:3000/chatbot`
+- Type "Hello" and send a message
+- The chatbot should respond
+
+### 2. Add Knowledge Base Content
+
+```bash
+# Add custom knowledge
+rails runner "RailsChatbot::KnowledgeIndexer.add_custom_knowledge(
+  title: 'User Registration',
+  content: 'Users can register by clicking the Sign Up button...',
+  source_type: 'help'
+)"
+```
+
+### 3. Test Knowledge Search
+In the chat, try asking:
+- "How do users register?"
+- "What features are available?"
+- "Tell me about user management"
+
+### 4. Test API Endpoints
+
+```bash
+# Test search
+curl "http://localhost:3000/chatbot/search?q=user"
+
+# Test conversation creation
+curl -X POST "http://localhost:3000/chatbot/conversations" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+### 5. Check Knowledge Base Stats
+
+```bash
+rake app:rails_chatbot:stats
+```
+
+## 📚 Advanced Usage
+
+### Index Your Models
+
+```bash
+# Index specific models
+rake app:rails_chatbot:index_models[User,Post,Product]
+
+# Index all models
+rake app:rails_chatbot:index_all
+```
+
+### Add Custom Knowledge
+
+```ruby
+# Via code
+RailsChatbot::KnowledgeBase.create!(
+  title: "How to Reset Password",
+  content: "Click 'Forgot Password' on the login page...",
+  source_type: "help"
+)
+
+# Via rake task
+rake app:rails_chatbot:add_knowledge['Title','Content','Type']
+```
+
+### Customize Configuration
+
+```ruby
+RailsChatbot.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+  config.openai_model = 'gpt-4o-mini'
+  config.chatbot_title = 'Support Assistant'
+  config.current_user_proc = proc { |controller| controller.current_user }
+  config.indexable_models = [User, Product, Order] # Custom models to index
+end
+```
+
+## 🔧 Management Commands
+
+```bash
+# Knowledge base management
+rake app:rails_chatbot:stats                    # View statistics
+rake app:rails_chatbot:clear_knowledge_base     # Clear all entries
+rake app:rails_chatbot:add_knowledge['Title','Content','Type'] # Add knowledge
+rake app:rails_chatbot:index_all               # Index all models
+rake app:rails_chatbot:index_models[User,Post] # Index specific models
+```
+
+## 🎯 Common Use Cases
+
+### E-commerce Site
+```ruby
+# Index products
+rake app:rails_chatbot:index_models[Product,Category]
+
+# Add help content
+RailsChatbot::KnowledgeIndexer.add_custom_knowledge(
+  title: "Shipping Policy",
+  content: "We ship within 3-5 business days...",
+  source_type: "policy"
+)
+```
+
+### SaaS Application
+```ruby
+# Index user models and features
+rake app:rails_chatbot:index_models[User,Feature,Subscription]
+
+# Add feature documentation
+RailsChatbot::KnowledgeIndexer.add_custom_knowledge(
+  title: "Dashboard Overview",
+  content: "The dashboard shows your usage statistics...",
+  source_type: "documentation"
+)
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **OpenAI API Errors**
+   - Check your API key is valid
+   - Verify you have credits in your OpenAI account
+   - Try a different model (gpt-3.5-turbo)
+
+2. **No Knowledge Found**
+   - Run `rake app:rails_chatbot:index_all` to populate knowledge base
+   - Add custom knowledge entries
+   - Check `rake app:rails_chatbot:stats` for entries
+
+3. **Search Not Working**
+   - Ensure PostgreSQL is configured
+   - Check database migrations ran successfully
+   - Verify knowledge base has content
+
+4. **Routing Issues**
+   - Confirm engine is mounted in routes.rb
+   - Check for route conflicts with existing paths
+   - Restart Rails server after route changes
+
+### Debug Mode
+
+```ruby
+# In development, add to initializer
+RailsChatbot.configure do |config|
+  # ... other config
+  Rails.logger.level = :debug
+end
+```
+
+## 📱 API Reference
+
+### Endpoints
+
+- `GET /chatbot` - Chat interface
+- `POST /chatbot/conversations` - Create conversation
+- `GET /chatbot/conversations` - List conversations
+- `POST /chatbot/conversations/:id/messages` - Send message
+- `GET /chatbot/search?q=query` - Search knowledge
+
+### Response Format
+
+```json
+{
+  "message": {
+    "role": "assistant",
+    "content": "Here's the answer...",
+    "created_at": "2026-02-12T12:00:00Z"
+  },
+  "knowledge_sources": [
+    {
+      "title": "User Guide",
+      "source_type": "documentation",
+      "source_url": "/docs/users"
+    }
+  ]
+}
+```
+
+## 🎨 Customization
+
+### Override Views
+
+Create `app/views/rails_chatbot/chat/index.html.erb` in your app to customize the chat interface.
+
+### Custom Styles
+
+Add to `app/assets/stylesheets/rails_chatbot/custom.css`:
+
+```css
+.chatbot-container {
+  background: your-brand-color;
+  border-radius: your-preference;
+}
+```
+
+### Custom JavaScript
+
+Extend functionality in `app/javascript/rails_chatbot/custom.js`.
+
+## 📋 Requirements
+
+- Ruby on Rails 8.0.4 or higher
+- PostgreSQL (for full-text search)
+- OpenAI API key
+- Modern web browser
+
+## 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 🤝 Support
+
+- 📖 [Documentation](https://github.com/yourusername/rails_chatbot)
+- 🐛 [Issues](https://github.com/yourusername/rails_chatbot/issues)
+- 💬 [Discussions](https://github.com/yourusername/rails_chatbot/discussions)

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/rails_chatbot/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/rails_chatbot/application_controller.rb

@@ -0,0 +1,14 @@
+module RailsChatbot
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception, if: -> { request.format.html? }
+    skip_before_action :verify_authenticity_token, if: -> { request.format.json? }
+
+    private
+
+    def current_user
+      # Override this method in your main application controller
+      # or define it in an initializer
+      instance_eval(&Rails.application.config.rails_chatbot.current_user_proc) if Rails.application.config.rails_chatbot&.current_user_proc
+    end
+  end
+end

data/app/controllers/rails_chatbot/chat_controller.rb

@@ -0,0 +1,27 @@
+module RailsChatbot
+  class ChatController < ApplicationController
+    def index
+      # Main chat interface
+    end
+
+    def search
+      query = params[:q].to_s.strip
+      return render json: { results: [] } if query.blank?
+
+      service = KnowledgeRetrievalService.new(query: query, limit: 10)
+      results = service.retrieve
+
+      render json: {
+        results: results.map do |result|
+          {
+            title: result[:title],
+            content: result[:content].truncate(200),
+            source_type: result[:source_type],
+            source_id: result[:source_id],
+            source_url: result[:source_url]
+          }
+        end
+      }
+    end
+  end
+end

data/app/controllers/rails_chatbot/conversations_controller.rb

@@ -0,0 +1,48 @@
+module RailsChatbot
+  class ConversationsController < ApplicationController
+    before_action :set_conversation, only: [:show, :destroy]
+
+    def index
+      @conversations = Conversation.where(session_id: session_id)
+                                   .recent
+                                   .limit(20)
+      render json: @conversations.map { |c| { id: c.id, title: c.title, created_at: c.created_at } }
+    end
+
+    def show
+      @messages = @conversation.messages.order(created_at: :asc)
+      render json: {
+        conversation: {
+          id: @conversation.id,
+          title: @conversation.title,
+          created_at: @conversation.created_at
+        },
+        messages: @messages.map { |m| { role: m.role, content: m.content, created_at: m.created_at } }
+      }
+    end
+
+    def create
+      @conversation = Conversation.find_or_create_by(session_id: session_id) do |conv|
+        conv.title = params[:title] || "Conversation #{Time.current.strftime('%Y-%m-%d %H:%M')}"
+        conv.user = current_user if respond_to?(:current_user) && current_user
+      end
+
+      render json: { conversation_id: @conversation.id, title: @conversation.title }
+    end
+
+    def destroy
+      @conversation.destroy
+      head :no_content
+    end
+
+    private
+
+    def set_conversation
+      @conversation = Conversation.find_by!(id: params[:id], session_id: session_id)
+    end
+
+    def session_id
+      @session_id ||= session[:chatbot_session_id] ||= SecureRandom.uuid
+    end
+  end
+end

data/app/controllers/rails_chatbot/messages_controller.rb

@@ -0,0 +1,55 @@
+module RailsChatbot
+  class MessagesController < ApplicationController
+    before_action :set_conversation
+
+    def create
+      user_message = params[:message].to_s.strip
+
+      if user_message.blank?
+        render json: { error: 'Message cannot be blank' }, status: :unprocessable_entity
+        return
+      end
+
+      chat_service = ChatService.new(conversation: @conversation)
+      result = chat_service.process_message(user_message)
+
+      render json: {
+        message: {
+          role: 'assistant',
+          content: result[:response],
+          created_at: Time.current
+        },
+        knowledge_sources: result[:knowledge_sources].map do |source|
+          {
+            title: source[:title],
+            source_type: source[:source_type],
+            source_id: source[:source_id],
+            source_url: source[:source_url]
+          }
+        end
+      }
+    rescue => e
+      Rails.logger.error("Chat error: #{e.message}\n#{e.backtrace.join("\n")}")
+      render json: { error: 'An error occurred while processing your message' }, status: :internal_server_error
+    end
+
+    private
+
+    def set_conversation
+      conversation_id = params[:conversation_id] || params[:conversation][:id] rescue nil
+      
+      if conversation_id
+        @conversation = Conversation.find_by!(id: conversation_id, session_id: session_id)
+      else
+        @conversation = Conversation.find_or_create_by(session_id: session_id) do |conv|
+          conv.title = "Conversation #{Time.current.strftime('%Y-%m-%d %H:%M')}"
+          conv.user = current_user if respond_to?(:current_user) && current_user
+        end
+      end
+    end
+
+    def session_id
+      @session_id ||= session[:chatbot_session_id] ||= SecureRandom.uuid
+    end
+  end
+end

data/app/helpers/rails_chatbot/application_helper.rb

@@ -0,0 +1,12 @@
+module RailsChatbot
+  module ApplicationHelper
+    def rails_chatbot_routes
+      routes = {
+        conversations_path: rails_chatbot.conversations_path,
+        messages_path: rails_chatbot.messages_path,
+        conversation_messages_path_template: rails_chatbot.conversation_messages_path(':id')
+      }
+      routes.to_json.html_safe
+    end
+  end
+end

data/app/javascript/rails_chatbot/application.js

@@ -0,0 +1,163 @@
+// Chatbot controller using Stimulus (or vanilla JS)
+document.addEventListener('DOMContentLoaded', function() {
+  const chatbotContainer = document.querySelector('[data-controller="chatbot"]');
+  if (!chatbotContainer) return;
+
+  const messagesContainer = chatbotContainer.querySelector('[data-chatbot-target="messages"]');
+  const input = chatbotContainer.querySelector('[data-chatbot-target="input"]');
+  const sendButton = chatbotContainer.querySelector('[data-chatbot-target="sendButton"]');
+  let conversationId = null;
+  let isLoading = false;
+
+  // Initialize conversation
+  function initializeConversation() {
+    fetch(window.RailsChatbot.routes.conversationsPath(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]')?.content || ''
+      },
+      body: JSON.stringify({})
+    })
+    .then(response => response.json())
+    .then(data => {
+      conversationId = data.conversation_id;
+    })
+    .catch(error => console.error('Error initializing conversation:', error));
+  }
+
+  // Add message to UI
+  function addMessage(role, content, knowledgeSources = []) {
+    const messageDiv = document.createElement('div');
+    messageDiv.className = `message ${role}`;
+    
+    const bubble = document.createElement('div');
+    bubble.className = 'message-bubble';
+    bubble.textContent = content;
+    
+    messageDiv.appendChild(bubble);
+    
+    if (knowledgeSources && knowledgeSources.length > 0) {
+      const sourcesDiv = document.createElement('div');
+      sourcesDiv.className = 'knowledge-sources';
+      sourcesDiv.innerHTML = 'Sources: ' + knowledgeSources.map(s => {
+        if (s.source_url) {
+          return `<a href="${s.source_url}" target="_blank">${s.title}</a>`;
+        }
+        return s.title;
+      }).join(', ');
+      messageDiv.appendChild(sourcesDiv);
+    }
+    
+    const timeDiv = document.createElement('div');
+    timeDiv.className = 'message-time';
+    timeDiv.textContent = new Date().toLocaleTimeString();
+    messageDiv.appendChild(timeDiv);
+    
+    messagesContainer.appendChild(messageDiv);
+    messagesContainer.scrollTop = messagesContainer.scrollHeight;
+  }
+
+  // Show loading indicator
+  function showLoading() {
+    const loadingDiv = document.createElement('div');
+    loadingDiv.className = 'message assistant';
+    loadingDiv.id = 'loading-message';
+    loadingDiv.innerHTML = '<div class="message-bubble"><div class="loading"></div></div>';
+    messagesContainer.appendChild(loadingDiv);
+    messagesContainer.scrollTop = messagesContainer.scrollHeight;
+  }
+
+  // Remove loading indicator
+  function removeLoading() {
+    const loading = document.getElementById('loading-message');
+    if (loading) loading.remove();
+  }
+
+  // Send message
+  function sendMessage() {
+    const message = input.value.trim();
+    if (!message || isLoading) return;
+
+    // Add user message to UI
+    addMessage('user', message);
+    input.value = '';
+    isLoading = true;
+    sendButton.disabled = true;
+    showLoading();
+
+    // Determine endpoint
+    const url = conversationId 
+      ? window.RailsChatbot.routes.conversationMessagesPath(conversationId)
+      : window.RailsChatbot.routes.messagesPath();
+
+    // Send to server
+    fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]')?.content || ''
+      },
+      body: JSON.stringify({ message: message })
+    })
+    .then(response => response.json())
+    .then(data => {
+      removeLoading();
+      
+      if (data.error) {
+        addMessage('assistant', `Error: ${data.error}`);
+      } else {
+        if (!conversationId && data.conversation_id) {
+          conversationId = data.conversation_id;
+        }
+        addMessage('assistant', data.message.content, data.knowledge_sources || []);
+      }
+    })
+    .catch(error => {
+      removeLoading();
+      addMessage('assistant', 'Sorry, there was an error processing your message. Please try again.');
+      console.error('Error:', error);
+    })
+    .finally(() => {
+      isLoading = false;
+      sendButton.disabled = false;
+      input.focus();
+    });
+  }
+
+  // Handle key press
+  function handleKeyDown(event) {
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
+      sendMessage();
+    }
+  }
+
+  // Attach event listeners
+  sendButton.addEventListener('click', sendMessage);
+  input.addEventListener('keydown', handleKeyDown);
+
+  // Initialize conversation on load
+  initializeConversation();
+});
+
+// Routes helper - populated from server
+if (window.RailsChatbot && window.RailsChatbot.routes) {
+  const routes = typeof window.RailsChatbot.routes === 'string' 
+    ? JSON.parse(window.RailsChatbot.routes) 
+    : window.RailsChatbot.routes;
+  
+  window.RailsChatbot.routes = {
+    conversationsPath: () => routes.conversations_path,
+    conversationMessagesPath: (id) => routes.conversation_messages_path_template.replace(':id', id),
+    messagesPath: () => routes.messages_path
+  };
+} else {
+  // Fallback routes
+  window.RailsChatbot = window.RailsChatbot || {};
+  window.RailsChatbot.routes = {
+    conversationsPath: () => '/rails_chatbot/conversations',
+    conversationMessagesPath: (id) => `/rails_chatbot/conversations/${id}/messages`,
+    messagesPath: () => '/rails_chatbot/messages'
+  };
+}

data/app/jobs/rails_chatbot/application_job.rb

@@ -0,0 +1,4 @@
+module RailsChatbot
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/rails_chatbot/application_mailer.rb

@@ -0,0 +1,6 @@
+module RailsChatbot
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/rails_chatbot/application_record.rb

@@ -0,0 +1,5 @@
+module RailsChatbot
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end