llama_bot_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f23b70a2547901b996afd0faf1343947fe83e5c13cd99d15ae38726a3cf6408
+  data.tar.gz: 1b39d998ce51f856490d3206aeba465090e479b34360d4e6ff2ca80188cf17f7
+SHA512:
+  metadata.gz: f07b88075a21db84055d2ffbb517ca5679f5f38bd7df73738b3635f4669235d0faa02fab0e77d810aa360148ff90aa024634284f7c1950b031c2bd3c9b3ccc18
+  data.tar.gz: ce749dc85a5c2a8378d848fc5f219fa6c3769fbcbb8b9dd30d569b879a35db8bbaac3d0964c69a62fbf1b7c1ec0404e8af6edbcffbd4eb88466528dc6a4ef68b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Kody Kendall
+
+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,249 @@
+# 🚀 LlamaBotRails
+
+**Turn any Rails app into an AI Agent in 2 minutes**
+
+Chat with a powerful agent that has access to your models, your application context, and can run console commands. All powered by LangGraph + OpenAI.
+
+[![Gem Version](https://badge.fury.io/rb/llama_bot_rails.svg)](https://badge.fury.io/rb/llama_bot_rails)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-red)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0-red)](https://rubyonrails.org/)
+
+---
+
+## 🎥 **See it in action** (30-Second Demo)
+
+👉 [Insert GIF or YouTube link here]
+“Welcome to the future of Rails + AI.”
+
+### The agent can:
+
+- 🔍 **Explore your Rails app** (models, routes, controllers)
+- 💾 **Query and create data** via Rails console
+- 🛠️ **Take action on your behalf**
+- 🧠 **Understand your domain** through natural conversation
+
+
+---
+
+## 🚀 **Quickstart** →
+
+
+```bash
+
+# 1. Add the gem
+bundle add llama_bot_rails
+
+# 2. Install the routes & chat interface
+rails generate llama_bot_rails:install
+
+# 3. Clone & run the LangGraph backend
+git clone https://github.com/kodykendall/llamabot
+cd llamabot
+OPENAI_API_KEY=your_key 
+cd backend && uvicorn app:app --reload
+
+# Start your Rails server
+rails server
+
+# Visit the chat interface and start chatting.
+open http://localhost:3000/llama_bot/agent/chat
+
+```
+
+**That's it.** ✅ You can now chat with your Rails app like a new assistant.
+
+### Try asking:
+- "What models do I have in this app?"
+- "Show me the User model structure"
+- "Create a test user"
+- "What are my routes?"
+
+### Prerequisites
+- Rails 7.0+
+- Ruby 2.7+  
+- Redis (for ActionCable)
+- OpenAI API key
+
+---
+
+## 🧨 **Power & Responsibility**
+
+### ⚠️ **This gem gives the agent access to your Rails console.**
+
+This is **incredibly powerful** -- and also potentially dangerous in production.
+*Treat it like giving shell access to a developer.*
+
+🚫 **Do not deploy this tool to production** without understanding the risks to your production data & application.
+
+**🛡️ Production safety features coming soon**
+
+## 🏗️ **Architecture**
+
+```
+┌────────────────────┐         WebSocket        ┌────────────────────┐
+│     Rails App      │ ←──────────────────────→ │     LangGraph      │
+│    (Your App)      │                          │  FastAPI (Python)  │
+├────────────────────┤                          ├────────────────────┤
+│   LlamaBotRails    │                          │   Agents & Tools   │
+│        Gem         │                          │    (LangGraph)     │
+└────────────────────┘                          └────────────────────┘
+
+```
+
+**What happens:**
+1. **Rails frontend** provides a chat interface 
+2. **ActionCable WebSocket** handles real-time communication to LangGraph
+3. **LangGraph backend** runs the AI agent with access to tools
+4. **Agent executes** A sequence of Rails console commands, reasoning throughout the process.
+5. **Results stream back** to the chat interface in real-time
+
+## 🛠️ **Customization**
+
+### Custom State Builder
+
+Control what data your agent sees:
+
+```ruby
+# config/initializers/llama_bot_rails.rb
+class CustomAgentStateBuilder < LlamaBotRails::AgentStateBuilder
+  def build
+    super.merge({
+      current_user: @context[:user]&.to_json,
+      app_version: Rails.application.version,
+      custom_context: gather_app_context
+    })
+  end
+  
+  private
+  
+  def gather_app_context
+    {
+      model_count: ActiveRecord::Base.subclasses.count,
+      route_count: Rails.application.routes.routes.count,
+      environment: Rails.env,
+      database_name: ActiveRecord::Base.connection_db_config.database
+    }
+  end
+end
+
+# Configure the gem to use your builder
+Rails.application.configure do
+  config.llama_bot_rails.state_builder_class = "CustomAgentStateBuilder"
+end
+```
+
+### Environment Configuration
+
+```ruby
+# config/environments/development.rb
+Rails.application.configure do
+  config.llama_bot_rails.enable_console_tool = true
+end
+
+# config/environments/production.rb
+Rails.application.configure do
+  config.llama_bot_rails.enable_console_tool = false # Disable in production
+end
+```
+
+## 🧪 **What You Can Build**
+
+### Developer Assistant
+- **Code exploration**: "Show me how authentication works"
+- **Data analysis**: "How many users signed up this month?" 
+- **Quick prototyping**: "Create a basic blog post model"
+
+## 🔧 **Under the Hood**
+
+### Real-Time Communication
+- **ActionCable WebSocket** Real-time Rails <-> Agent communication.
+- **LangGraph Backend** FastAPI + OpenAI tool orchestration
+
+### Security   
+- **Secure channel seperation** -> Per-session isolation.
+- **Token expiration** and automatic refresh mechanisms
+
+### Command Streaming
+- **`run_rails_console_command`**: Execute Ruby code in Rails context
+
+## 📋 **Requirements**
+
+### Rails Application
+- **Rails 7.0+** - Modern Rails version with ActionCable support
+- **Ruby 2.7+** - Compatible Ruby version
+- **ActionCable configured** - For real-time WebSocket communication
+- **Redis** - Recommended for production ActionCable backend
+
+### LangGraph Backend  
+- **Python 3.11+** - Python runtime environment
+- **FastAPI application** - Web framework for the agent backend
+- **OpenAI API access** - For LLM capabilities
+- **WebSocket support** - For real-time bidirectional communication
+
+## 🧨 Troubleshooting
+- Agent not responding? Check that backend is running and OpenAI key is set.
+- WebSocket issues? Confirm LLAMABOT_WEBSOCKET_URL matches backend address.
+
+## 🤝 **Contributing**
+
+We'd love your help making LlamaBotRails better!
+
+### How to Contribute
+
+1. **Fork the repo**
+2. **Create a feature branch**: `git checkout -b my-new-feature`
+3. **Make your changes** and add tests
+4. **Run the test suite**: `bundle exec rspec`
+5. **Submit a pull request**
+
+### Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/kodykendall/llama_bot_rails
+cd llama_bot_rails
+
+# Install dependencies
+bundle install
+
+# Run tests  
+bundle exec rspec
+
+# Test in a real Rails app
+cd example_app
+bundle exec rails server
+```
+
+---
+
+## 🌟 **What's Next?**
+
+We're just getting started. Coming soon:
+
+- 🛡️ **Enhanced security controls** for production deployments
+- 🔧 **More built-in tools** (scaffolding, API calls, database queries)
+- 🎨 **Customizable chat themes** and branding  
+- 📊 **Analytics and monitoring** for agent interactions
+- 🔌 **Plugin system** for custom tool development
+- 🤖 **Multi-agent support** for complex workflows
+- 🔄 **Background job integration** for long-running tasks
+
+---
+
+## 📝 **License**
+
+[MIT](https://opensource.org/licenses/MIT). — free for commercial and personal use.
+
+---
+
+## ⭐️ **Support the Project!**
+
+If LlamaBotRails helped you, **give us a star** ⭐️ and **share it** with other Rails developers.
+
+This is just the beginning. Let's build the Rails agentic future -- together.
+
+**[⭐️ Star on GitHub](https://github.com/kodykendall/llama_bot_rails)** • **[🍴 Fork the repo](https://github.com/kodykendall/llama_bot_rails/fork)** • **[💬 Join discussions](https://github.com/kodykendall/llama_bot_rails/discussions)**
+
+---
+
+*Built with ❤️ by [Kody Kendall](https://kodykendall.com)*

data/Rakefile

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

data/app/assets/config/llama_bot_rails_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/llama_bot_rails .css

data/app/assets/javascripts/llama_bot_rails/application.js

@@ -0,0 +1,7 @@
+//= require action_cable
+//= require_self
+
+(function() {
+  this.LlamaBotRails = this.LlamaBotRails || {};
+  LlamaBotRails.cable = ActionCable.createConsumer();
+}).call(this); 

data/app/assets/javascripts/llama_bot_rails/chat.js

@@ -0,0 +1,13 @@
+// llama_bot_rails/app/assets/javascripts/llama_bot_rails/chat.js
+
+const chatChannel = ActionCable.createConsumer().subscriptions.create(
+    { channel: "LlamaBotRails::ChatChannel" },
+    {
+      received(data) {
+        console.log("Received:", data.message);
+      },
+      connected() {
+        console.log("Connected to llama_bot_rails_chat");
+      }
+    }
+);

data/app/assets/stylesheets/llama_bot_rails/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/channels/llama_bot_rails/application_cable/channel.rb

@@ -0,0 +1,8 @@
+# llama_bot_rails/app/channels/llama_bot_rails/application_cable/channel.rb
+module LlamaBotRails
+    module ApplicationCable
+      class Channel < ActionCable::Channel::Base
+      end
+    end
+  end
+  

data/app/channels/llama_bot_rails/application_cable/connection.rb

@@ -0,0 +1,13 @@
+# llama_bot_rails/app/channels/llama_bot_rails/application_cable/connection.rb
+module LlamaBotRails
+    module ApplicationCable
+      class Connection < ActionCable::Connection::Base
+        identified_by :uuid
+  
+        def connect
+          self.uuid = SecureRandom.uuid
+        end
+      end
+    end
+  end
+  

data/app/channels/llama_bot_rails/chat_channel.rb

@@ -0,0 +1,306 @@
+require 'json'  # Ensure JSON is required if not already
+
+module LlamaBotRails
+  class ChatChannel < ApplicationCable::Channel
+    # _chat.html.erb front-end subscribes to this channel in _websocket.html.erb.
+    def subscribed
+      begin
+        stream_from "chat_channel_#{params[:session_id]}" # Public stream for session-based messages <- this is the channel we're subscribing to in _websocket.html.erb
+        Rails.logger.info "[LlamaBot] Subscribed to chat channel with session ID: #{params[:session_id]}"
+        
+        @connection_id = SecureRandom.uuid
+        Rails.logger.info "[LlamaBot] Created new connection with ID: #{@connection_id}"
+        Rails.logger.info "[LlamaBot] Secure API token generated."
+
+        # Use a begin/rescue block to catch thread creation errors
+      begin
+
+        @api_token = Rails.application.message_verifier(:llamabot_ws).generate(
+          { session_id: SecureRandom.uuid },
+          expires_in: 30.minutes
+        )
+
+        @worker = Thread.new do
+            Thread.current[:connection_id] = @connection_id
+          Thread.current.abort_on_exception = true  # This will help surface errors
+          setup_external_websocket(@connection_id)
+        end
+      rescue => e
+        Rails.logger.error "[LlamaBot] Error in WebSocket subscription: #{e.message}"
+        Rails.logger.error e.backtrace.join("\n")
+        
+        # Send error message to frontend before rejecting
+        begin
+          send_message_to_frontend("error", "Failed to establish chat connection: #{e.message}")
+        rescue => send_error
+          Rails.logger.error "[LlamaBot] Could not send error to frontend: #{send_error.message}"
+        end
+        
+        reject # Reject the connection if there's an error
+        end
+      rescue ThreadError => e
+        Rails.logger.error "[LlamaBot] Failed to allocate thread: #{e.message}"
+        # Handle the error gracefully - potentially notify the client
+        send_message_to_frontend("error", "Failed to establish connection: #{e.message}")
+      end
+    end
+
+    def unsubscribed
+      connection_id = @connection_id
+      Rails.logger.info "[LlamaBot] Unsubscribing connection: #{connection_id}"
+      
+      begin
+        # Only kill the worker if it belongs to this connection
+        if @worker && @worker[:connection_id] == connection_id
+          begin
+            @worker.kill
+            @worker = nil
+            Rails.logger.info "[LlamaBot] Killed worker thread for connection: #{connection_id}"
+          rescue => e
+            Rails.logger.error "[LlamaBot] Error killing worker thread: #{e.message}"
+          end
+        end
+
+        # Clean up async tasks with better error handling
+        begin
+          @listener_task&.stop rescue nil
+          @keepalive_task&.stop rescue nil
+          @external_ws_task&.stop rescue nil
+        rescue => e
+          Rails.logger.error "[LlamaBot] Error stopping async tasks: #{e.message}"
+        end
+        
+        # Clean up the connection
+        if @external_ws_connection
+          begin
+            @external_ws_connection.close
+            Rails.logger.info "[LlamaBot] Closed external WebSocket connection for: #{connection_id}"
+          rescue => e
+            Rails.logger.warn "[LlamaBot] Could not close WebSocket connection: #{e.message}"
+          end
+        end
+        
+        # Force garbage collection in development/test environments to help clean up
+        if !Rails.env.production?
+          GC.start
+        end
+      rescue => e
+        Rails.logger.error "[LlamaBot] Fatal error during channel unsubscription: #{e.message}"
+        Rails.logger.error e.backtrace.join("\n")
+      end
+    end
+
+    # Receive messages from _chat.html.erb frontend and send to llamabot FastAPI backend, frontend comes from the llamabot/_chat.html.erb chatbot, sent
+    # through external websocket to FastAPI/Python backend.
+    def receive(data)
+      begin
+        #used to validate the message before it's sent to the backend.
+
+        #This could be an example of how we might implement hooks & filters in the future.
+        validate_message(data) #Placeholder for now, we are using this to mock errors being thrown. In the future, we can add actual validation logic.        
+        # Forward the processed data to the LlamaBot Backend Socket
+        message = data["message"]
+
+        # 1. Instantiate the builder
+        builder = state_builder_class.new(
+          params: { message: data["message"] },
+          context: { thread_id: data["thread_id"], api_token: @api_token }
+        )
+
+        # 2. Construct the LangGraph-ready state
+        state_payload = builder.build
+
+        # 3. Ship it over the existing WebSocket
+        send_to_external_application(state_payload)
+
+        # Log the incoming WebSocket data
+        Rails.logger.info "[LlamaBot] Got message from Javascript LlamaBot Frontend: #{data.inspect}"
+      rescue => e
+        Rails.logger.error "[LlamaBot] Error in receive method: #{e.message}"
+        send_message_to_frontend("error", e.message)
+      end
+    end
+
+    def send_message_to_frontend(type, message, trace_info = nil)
+      
+      # Log trace info for debugging
+      Rails.logger.info "[LlamaBot] TRACE INFO DEBUG: Type: #{type}, Has trace info: #{trace_info.present?}"
+
+      message_data = {
+        type: type,
+        content: message
+      }
+      
+      formatted_message = { message: message_data.to_json }.to_json
+      
+      ActionCable.server.broadcast "chat_channel_#{params[:session_id]}", formatted_message
+    end
+
+    private
+
+    def state_builder_class
+      LlamaBotRails.config.state_builder_class.constantize
+    end
+
+    def setup_external_websocket(connection_id)
+      Thread.current[:connection_id] = connection_id
+      Rails.logger.info "[LlamaBot] Setting up external websocket for connection: #{connection_id}"
+      
+      # Check if the WebSocket URL is configured
+      websocket_url = ENV['LLAMABOT_WEBSOCKET_URL']
+      if websocket_url.blank?
+        Rails.logger.warn "[LlamaBot] LLAMABOT_WEBSOCKET_URL not configured, skipping external WebSocket setup"
+        return
+      end
+      
+      # endpoint = Async::HTTP::Endpoint.parse(ENV['LLAMABOT_WEBSOCKET_URL']) 
+      uri = URI(websocket_url)
+      
+      uri.scheme = 'wss'
+      uri.scheme = 'ws' if ENV['DEVELOPMENT_ENVIRONMENT'] == 'true'
+
+      endpoint = Async::HTTP::Endpoint.new(
+          uri,
+          ssl_context: OpenSSL::SSL::SSLContext.new.tap do |ctx|
+              ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
+              if ENV["STAGING_ENVIRONMENT"] == 'true'
+                ctx.ca_file = '/usr/local/etc/ca-certificates/cert.pem'
+                # M2 Air : ctx.ca_file = '/etc//ssl/cert.pem'
+                ctx.cert = OpenSSL::X509::Certificate.new(File.read(File.expand_path('~/.ssl/llamapress/cert.pem')))
+                ctx.key = OpenSSL::PKey::RSA.new(File.read(File.expand_path('~/.ssl/llamapress/key.pem')))
+              elsif ENV['DEVELOPMENT_ENVIRONMENT'] == 'true'
+                # do no ctx stuff
+                ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE   
+              else  # production
+                ctx.ca_file ='/etc/ssl/certs/ca-certificates.crt'
+              end
+          end
+      )
+
+      # Initialize the connection and store it in an instance variable
+      @external_ws_task = Async do |task|
+        begin
+          @external_ws_connection = Async::WebSocket::Client.connect(endpoint)
+          Rails.logger.info "[LlamaBot] Connected to external WebSocket for connection: #{connection_id}"
+          
+          #Tell llamabot frontend that we've connected to the backend
+          formatted_message = { message: {type: "external_ws_pong"} }.to_json
+          ActionCable.server.broadcast "chat_channel_#{params[:session_id]}", formatted_message
+          
+          # Store tasks in instance variables so we can clean them up later
+          @listener_task = task.async do
+            listen_to_external_websocket(@external_ws_connection)
+          end
+
+          @keepalive_task = task.async do
+            send_keep_alive_pings(@external_ws_connection)
+          end
+
+          # Wait for tasks to complete or connection to close
+          [@listener_task, @keepalive_task].each(&:wait)
+        rescue => e
+          Rails.logger.error "[LlamaBot] Failed to connect to external WebSocket for connection #{connection_id}: #{e.message}"
+        ensure
+          # Clean up tasks if they exist
+          @listener_task&.stop
+          @keepalive_task&.stop
+          @external_ws_connection&.close
+        end
+      end
+    end
+
+    # Listen for messages from the LlamaBot Backend
+    def listen_to_external_websocket(connection)
+      while message = connection.read
+
+        #Try to fix the ping/pong issue keepliave
+        # if message.type == :ping
+        
+        #   # respond with :pong
+        #   connection.write(Async::WebSocket::Messages::ControlFrame.new(:pong, frame.data))
+        #   connection.flush
+        #   next
+        # end
+        # Extract the actual message content
+        if message.buffer
+          message_content = message.buffer  # Use .data to get the message content
+        else
+          message_content = message.content
+        end
+
+        Rails.logger.info "[LlamaBot] Received from external WebSocket: #{message_content}"
+        
+        begin
+          parsed_message = JSON.parse(message_content)
+          
+          if parsed_message["type"] != "pong"
+            # byebug
+          end
+          
+          case parsed_message["type"]
+          when "ai"
+            # Add any additional handling for write_code messages here
+            formatted_message = { message: {type: "ai", content: parsed_message['content'], base_message: parsed_message["base_message"]} }.to_json
+          when "tool"
+            # Add any additional handling for tool messages here
+            formatted_message = { message: {type: "tool", content: parsed_message['content'], base_message: parsed_message["base_message"]} }.to_json
+          when "error"
+            Rails.logger.error "[LlamaBot] ---------Received error message!----------"
+            response = parsed_message['content']
+            formatted_message = { message: message_content }.to_json
+            Rails.logger.error "[LlamaBot] ---------------------> Response: #{response}"
+            Rails.logger.error "[LlamaBot] ---------Completed error message!----------"
+          when "pong"
+            # Tell llamabot frontend that we've received a pong response, and we're still connected
+            formatted_message = { message: {type: "pong"} }.to_json
+          end
+        rescue JSON::ParserError => e
+          Rails.logger.error "[LlamaBot] Failed to parse message as JSON: #{e.message}"
+        end
+        ActionCable.server.broadcast "chat_channel_#{params[:session_id]}", formatted_message
+      end
+    end
+
+    ###
+    def send_keep_alive_pings(connection)
+      loop do
+        ping_message = {
+          type: 'ping',
+          connection_id: @connection_id,
+          connection_state: !connection.closed? ? 'connected' : 'disconnected',
+          connection_class: connection.class.name
+        }.to_json
+        connection.write(ping_message)
+        connection.flush
+        Rails.logger.debug "[LlamaBot] Sent keep-alive ping: #{ping_message}"
+        Async::Task.current.sleep(30)
+      end
+    rescue => e
+      Rails.logger.error "[LlamaBot] Error in keep-alive ping: #{e.message} | Connection type: #{connection.class.name}"
+    end
+
+    # Send messages from the user to the LlamaBot Backend Socket
+    def send_to_external_application(message)
+      #   ChatMessage.create(content: message_content, user: current_user, chat_conversation: ChatConversation.last, ai_chat_message: true, created_at: Time.now)
+
+      payload = message.to_json
+      if @external_ws_connection
+        begin
+          @external_ws_connection.write(payload)
+          @external_ws_connection.flush
+          Rails.logger.info "[LlamaBot] Sent message to external WebSocket: #{payload}"
+        rescue => e
+          Rails.logger.error "[LlamaBot] Error sending message to external WebSocket: #{e.message}"
+        end
+      else
+        Rails.logger.error "[LlamaBot] External WebSocket connection not established"
+        # Optionally, you might want to attempt to reconnect here
+      end
+    end
+
+    def validate_message(data)
+      # This is a simple method that can be easily mocked
+      true
+    end
+  end  # Single end statement to close the ChatChannel clas
+end