active_agent_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02e5f8fc660eb1f31241e29aed06e49203969ad06a131e7e2023d3d767a93799
+  data.tar.gz: 73e500f5db889fbdc6b6eb9183bf9f079fb5ec6c5f42177fd5952db4e65fde79
+SHA512:
+  metadata.gz: 4c990e108ceb57fb81634f63b1e71e56ce3b2db40915aacf5dc953e22a867ca0b459b271615a09d12421a9470d184c39e04feab9aa4447129c244c3260ecef51
+  data.tar.gz: 5bac33da0987e589a30bbf2caff249bcc41325e6e0f06a3248c2d2e3d22d9106352f5b8487d880ca64316f36941a33771c693943e24ef3a7d93f9461c8fc012d

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in active_agent.gemspec
+gemspec
+
+gem "rake"
+gem "minitest"
+gem "sqlite3" # useful for active_record testing or local test db

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shiboshree Roy
+
+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,151 @@
+# ActiveAgent
+
+`ActiveAgent` is a Rails-like framework and engine designed to integrate LLMs, AI agents, and custom tools into Ruby on Rails applications with ease.
+
+It supports multiple provider adapters (Gemini, OpenAI, Anthropic), handles multi-turn tool-execution loops automatically, offers plug-and-play conversation memory (in-memory or ActiveRecord), and includes a gorgeous streaming chat widget ready for your Rails views.
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_agent_rails', path: 'path/to/active_agent_rails'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+### Setup Configuration & Memory
+
+Run the installation generator to create the initializer and the migration for database-backed conversation history:
+
+```bash
+$ rails generate active_agent:install
+```
+
+Run the migration to create the `active_agent_messages` table:
+
+```bash
+$ rails db:migrate
+```
+
+---
+
+## Configuration
+
+You can configure providers and API keys in `config/initializers/active_agent.rb`:
+
+```ruby
+ActiveAgent.configure do |config|
+  # Default provider: :gemini, :openai, or :anthropic
+  config.default_provider = :gemini
+
+  # API Keys
+  config.gemini_api_key = ENV["GEMINI_API_KEY"]
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+
+  # Memory store: :in_memory or :active_record
+  config.memory_store = :active_record
+end
+```
+
+---
+
+## Defining an Agent
+
+Generate a new agent using the generator:
+
+```bash
+$ rails generate active_agent:agent customer_service
+```
+
+This scaffolds `app/agents/customer_service_agent.rb`. You can configure the system instructions, providers, and declare custom tools:
+
+```ruby
+# app/agents/customer_service_agent.rb
+class CustomerServiceAgent < ActiveAgent::Base
+  provider :gemini # Or :openai, :anthropic
+  model "gemini-2.5-flash"
+  system_prompt "You are a customer service assistant. You help users check their order details."
+
+  # Expose a Ruby method as a tool for the agent
+  tool :get_order_status, description: "Check shipping status of an order" do
+    parameter :order_id, type: :string, description: "Order ID (e.g., ORD-123)", required: true
+  end
+
+  # Define the tool implementation
+  def get_order_status(order_id:)
+    order = Order.find_by(order_number: order_id)
+    return "Order #{order_id} not found." unless order
+
+    "Order #{order_id} is currently #{order.status}. Expected delivery: #{order.delivery_date}."
+  end
+end
+```
+
+---
+
+## Usage
+
+### 1. In Ruby Code (Rails Controller, Job, or Console)
+
+```ruby
+# Initialize agent for a specific user/session ID
+agent = CustomerServiceAgent.new(conversation_id: "user_session_99")
+
+# Run agent chat
+response = agent.chat("Hi! Can you check the status of my order ORD-5541?")
+puts response
+# => "Order ORD-5541 is currently Shipped. Expected delivery: 2026-07-02."
+```
+
+### 2. View Integration: Streaming Chat Widget
+
+Mount the `ActiveAgent` engine routes in your application's `config/routes.rb`:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # ... other routes
+  mount ActiveAgent::Engine => "/active_agent"
+end
+```
+
+Now, you can drop the chat assistant widget into any of your Rails views:
+
+```erb
+<!-- app/views/home/index.html.erb -->
+<%= active_agent_chat_widget(agent: :customer_service, conversation_id: current_user.id) %>
+```
+
+This will inject a floating AI chat assistant at the bottom right. When the user types a message:
+- The UI communicates with `/active_agent/chats`.
+- The controller leverages **Server-Sent Events (SSE)** to stream the response back in real-time.
+- The assistant displays typing animations and updates the response character-by-character.
+- Message history is preserved automatically in the database using the ActiveRecord memory store.
+
+---
+
+## Customizing Tools
+
+`ActiveAgent` tools support several parameter types (`:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`):
+
+```ruby
+tool :update_profile, description: "Update user profile data" do
+  parameter :user_id, type: :integer, description: "Target user ID"
+  parameter :updates, type: :object, description: "Hash of update key-values"
+end
+```
+
+The engine maps these types to the appropriate API schema formatting expected by the LLM providers (Google Gemini, OpenAI, Anthropic).
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib" << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+  t.verbose = true
+end
+
+task default: :test

data/app/controllers/active_agent/chats_controller.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  class ChatsController < ::ActionController::Base
+    include ActionController::Live
+
+    # Disable CSRF verification for this API endpoint since it can be consumed as an API,
+    # or handle standard rails session if CSRF token is provided.
+    protect_from_forgery with: :null_session
+
+    def create
+      agent_name = params[:agent]
+      conversation_id = params[:conversation_id]
+      message = params[:message]
+
+      if agent_name.blank? || conversation_id.blank? || message.blank?
+        return render json: { error: "Missing required parameters: agent, conversation_id, message" }, status: :bad_request
+      end
+
+      agent_class = ActiveAgent.find_agent(agent_name)
+      agent = agent_class.new(conversation_id: conversation_id)
+
+      if request.headers["Accept"]&.include?("text/event-stream")
+        response.headers["Content-Type"] = "text/event-stream"
+        response.headers["Last-Modified"] = Time.now.httpdate
+        response.headers["X-Accel-Buffering"] = "no"
+        response.headers["Cache-Control"] = "no-cache, no-store"
+        response.headers["Connection"] = "keep-alive"
+
+        begin
+          agent.chat(message) do |chunk|
+            response.stream.write("data: #{ { chunk: chunk }.to_json }\n\n")
+          end
+        rescue StandardError => e
+          ActiveAgent.logger.error("[ActiveAgent] Streaming controller error: #{e.message}\n#{e.backtrace.join("\n")}")
+          response.stream.write("data: #{ { error: e.message }.to_json }\n\n")
+        ensure
+          response.stream.close
+        end
+      else
+        begin
+          reply = agent.chat(message)
+          render json: { reply: reply }
+        rescue StandardError => e
+          ActiveAgent.logger.error("[ActiveAgent] Controller error: #{e.message}")
+          render json: { error: e.message }, status: :unprocessable_entity
+        end
+      end
+    end
+
+    # Optional endpoint to fetch history
+    def index
+      agent_name = params[:agent]
+      conversation_id = params[:conversation_id]
+
+      if agent_name.blank? || conversation_id.blank?
+        return render json: { error: "Missing agent or conversation_id" }, status: :bad_request
+      end
+
+      agent_class = ActiveAgent.find_agent(agent_name)
+      agent = agent_class.new(conversation_id: conversation_id)
+
+      # Filter out system and tool messages for the client UI if desired
+      user_facing_messages = agent.memory.messages.reject { |m| m[:role].to_s == "system" }
+      render json: { messages: user_facing_messages }
+    end
+
+    # Optional endpoint to clear history
+    def destroy
+      agent_name = params[:agent]
+      conversation_id = params[:conversation_id]
+
+      if agent_name.blank? || conversation_id.blank?
+        return render json: { error: "Missing agent or conversation_id" }, status: :bad_request
+      end
+
+      agent_class = ActiveAgent.find_agent(agent_name)
+      agent = agent_class.new(conversation_id: conversation_id)
+      agent.memory.clear
+
+      render json: { success: true, message: "Conversation history cleared." }
+    end
+  end
+end