ruby_conversations 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29d0a2bc2bf832a2bd4a452e1213d024604d73c3be3406851d2ac77dce20278d
+  data.tar.gz: 973a5a996c8146aa0651dfeb42cb95d27c9a4623c53b1b4f662cefb48f90bc88
+SHA512:
+  metadata.gz: bf8a698597f4a53c26a0850ee8afc0552d9280b5ea46ba05b890e5bebaa587e40d666e93349ec1667e1ac438c881b9a1afa79b7482cc970fedc49d7e89d49be5
+  data.tar.gz: c9b77726ec303b37ad0af8f8e16ad3979802f8d995c254dcd2713a4a60563e0cbd7865b4bb433ade118ff2a597c8cc896940004b0abc874b802c63f666d037ba

data/README.md

@@ -0,0 +1,125 @@
+# RubyConversations
+
+A Rails engine for managing AI conversations with support for both local and remote storage modes. Built on top of RubyLLM for AI interactions.
+
+## Features
+
+- **Flexible Storage**: Choose between local database storage or remote API storage
+- **Built-in Prompt Management**: Version-controlled prompts with placeholder validation
+- **Conversation History**: Track and manage conversation threads
+- **Input/Output Storage**: Structured storage for message inputs and responses
+- **Real-time Updates**: Built-in broadcasting support for real-time applications
+- **JWT Authentication**: Secure remote mode with JWT authentication
+- **Easy Integration**: Simple setup with Rails generators
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_conversations'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install ruby_conversations
+```
+
+After installation, run the setup generator:
+
+```bash
+rails generate ai_conversation_engine:install
+```
+
+This will:
+- Create necessary database migrations
+- Generate an initializer file
+- Set up default configurations
+
+## Configuration
+
+Configure the engine in `config/initializers/ai_conversation_engine.rb`:
+
+```ruby
+AiConversationEngine.configure do |config|
+  # Storage mode: :local or :remote
+  config.storage_mode = :local
+  
+  # Remote API settings (only needed for remote mode)
+  # config.api_url = ENV['AI_CONVERSATION_API_URL']
+  # config.jwt_secret = ENV['AI_CONVERSATION_JWT_SECRET']
+  
+  # Default LLM settings
+  config.default_llm_model = 'gpt-4'
+  
+  # Customize model behaviors
+  config.conversation_class = 'AiConversation'
+  config.message_class = 'AiMessage'
+  config.prompt_class = 'Prompt'
+  
+end
+```
+
+## Usage
+
+### Basic Conversation
+
+```ruby
+# Create a new conversation
+conversation = AiConversation.create!
+
+# Ask a question using a predefined prompt
+conversation.ask("explain_code", inputs: { code: "def hello; end" })
+```
+
+### With Associated Objects
+
+```ruby
+# Create a conversation linked to another object
+class Project < ApplicationRecord
+  has_many :conversations, as: :conversationable, 
+           class_name: 'AiConversationEngine::AiConversation'
+end
+
+project = Project.find(1)
+conversation = project.conversations.create!
+conversation.ask("analyze_project", inputs: { name: project.name })
+```
+
+### Remote Storage Mode
+
+```ruby
+# Configure for remote storage
+AiConversationEngine.configure do |config|
+  config.storage_mode = :remote
+  config.api_url = "https://ai-conversation-api.example.com"
+  config.jwt_secret = ENV['JWT_SECRET']
+end
+
+# Usage remains the same
+conversation = AiConversation.create!
+conversation.ask("explain_code", inputs: { code: "def hello; end" })
+```
+
+### Real-time Updates
+
+```ruby
+# In your view
+<%= turbo_stream_from "chat_#{@conversation.id}" %>
+
+# Updates are automatically broadcast when messages are added
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/app/models/concerns/ruby_conversations/messageable.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # Provides message-related functionalities for conversations.
+  module Messageable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :ai_conversations, as: :conversationable, dependent: :destroy
+      has_many :ai_messages, through: :ai_conversations
+    end
+  end
+end

data/app/models/concerns/ruby_conversations/versionable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # Provides versioning functionalities for models.
+  module Versionable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :versions, class_name: 'PromptVersion', dependent: :destroy
+      has_one :latest_version, -> { order(version: :desc) }, class_name: 'PromptVersion'
+
+      delegate :content, :metadata, to: :latest_version, allow_nil: true
+    end
+
+    def create_version!(content:, metadata: {})
+      next_version = versions.maximum(:version).to_i + 1
+      versions.create!(content: content, metadata: metadata, version: next_version)
+    end
+  end
+end

data/app/models/ruby_conversations/ai_conversation.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # An AI conversation is a conversation between an AI and a user.
+  class AiConversation < ActiveRecord::Base
+    # Associations
+    belongs_to :conversationable, polymorphic: true, optional: true, touch: true
+    has_many :ai_messages, class_name: RubyConversations.configuration.message_class, dependent: :destroy
+
+    # Validations
+    validates :ai_messages, presence: { message: 'At least one message is required' }, on: :update
+    validate :validate_messages
+
+    # Scopes
+    scope :recent, -> { order(updated_at: :desc) }
+    scope :with_messages, -> { includes(:ai_messages) }
+
+    # Attributes
+    attr_accessor :model_identifier, :provider, :tool
+
+    def initialize(attributes = nil)
+      attributes ||= {}
+      super
+      @model_identifier ||= attributes[:model_identifier] || RubyConversations.configuration.default_llm_model
+      @provider ||= attributes[:provider] || RubyConversations.configuration.default_llm_provider
+    end
+
+    # Instance Methods
+    def ask_multiple(prompt_inputs, description: nil)
+      MessageBuilder.new(self).build_from_multiple_prompts(prompt_inputs, description: description)
+      self
+    end
+
+    def ask(name, description: nil, inputs: {})
+      MessageBuilder.new(self).build_from_single_prompt(name, description: description, inputs: inputs)
+      self
+    end
+
+    def execute(system_message: nil)
+      save!
+      message = ai_messages.last
+      raise ArgumentError, 'Conversation must have at least one message to execute' unless message
+
+      chat = setup_llm_chat(system_message: system_message)
+      response = chat.ask(message.request)
+      update_last_message_response(message, response)
+      response
+    end
+
+    def latest_message
+      ai_messages.order(created_at: :desc).first
+    end
+
+    def message_count
+      ai_messages.count
+    end
+
+    private
+
+    def validate_messages
+      ai_messages.each do |message|
+        validate_message_level(message)
+        message.ai_message_prompts.each do |prompt|
+          validate_prompt_level(prompt)
+          prompt.ai_message_inputs.each do |input|
+            validate_input_level(input)
+          end
+        end
+      end
+    end
+
+    def validate_message_level(message)
+      return if message.valid?
+
+      message.errors.full_messages.each do |msg|
+        errors.add(:base, "Message error: #{msg}")
+      end
+    end
+
+    def validate_prompt_level(prompt)
+      return if prompt.valid?
+
+      prompt.errors.full_messages.each do |msg|
+        errors.add(:base, "Message prompt error: #{msg}")
+      end
+    end
+
+    def validate_input_level(input)
+      return if input.valid?
+
+      input.errors.full_messages.each do |msg|
+        errors.add(:base, "Message prompt input error: #{msg}")
+      end
+    end
+
+    def setup_llm_chat(system_message: nil)
+      chat = RubyLLM.chat(model: model_identifier, provider: provider).with_temperature(0.0)
+      chat.with_tool(tool) if tool.present?
+      chat.add_message(role: :system, content: system_message) if system_message.present?
+      chat
+    end
+
+    def update_last_message_response(message, response)
+      message.update!(response: response.to_h.to_json)
+    end
+  end
+end

data/app/models/ruby_conversations/ai_message.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # An AI message is a message in an AI conversation.
+  class AiMessage < ActiveRecord::Base
+    # Associations
+    belongs_to :ai_conversation, class_name: RubyConversations.configuration.conversation_class
+    has_many :ai_message_prompts, class_name: RubyConversations.configuration.message_prompt_class, dependent: :destroy
+    has_many :prompts, through: :ai_message_prompts, class_name: RubyConversations.configuration.prompt_class
+
+    # Validations
+    validates :llm, presence: true
+    validates :request, presence: true
+
+    # Scopes
+    scope :ordered, -> { order(created_at: :desc) }
+    scope :with_tool, ->(tool) { where(tool: tool) }
+    scope :with_prompts, -> { includes(:ai_message_prompts) }
+
+    def prompt_inputs
+      ai_message_prompts.includes(:ai_message_inputs).flat_map(&:ai_message_inputs)
+    end
+
+    def tool?
+      tool.present?
+    end
+  end
+end

data/app/models/ruby_conversations/ai_message_input.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # Represents an input provided for a specific prompt placeholder within an AI message.
+  class AiMessageInput < ActiveRecord::Base
+    # Associations
+    belongs_to :ai_message_prompt
+
+    # Validations
+    validates :placeholder_name, presence: true
+    validate :value_not_nil
+
+    # Scopes
+    scope :ordered, -> { order(:placeholder_name) }
+
+    private
+
+    def value_not_nil
+      errors.add(:value, "can't be blank") if value.nil?
+    end
+  end
+end

data/app/models/ruby_conversations/ai_message_prompt.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # Represents the association between an AI message and a specific version of a Prompt.
+  class AiMessagePrompt < ActiveRecord::Base
+    # Associations
+    belongs_to :ai_message
+    belongs_to :prompt, optional: true
+    belongs_to :prompt_version, optional: true
+    has_many :ai_message_inputs, class_name: RubyConversations.configuration.message_input_class, dependent: :destroy
+
+    # Validations
+    validate :prompt_or_inline_data_present
+
+    # Scopes
+    scope :with_inputs, -> { includes(:ai_message_inputs) }
+    scope :for_prompt, ->(prompt) { where(prompt: prompt) }
+
+    private
+
+    def prompt_or_inline_data_present
+      return if prompt_id.present? || prompt_version_id.present?
+      return if name.present? && role.present? && draft.present?
+
+      errors.add(:base, 'Must have either a prompt/version reference or inline prompt data (name, role, draft)')
+    end
+  end
+end

data/app/models/ruby_conversations/message_builder.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # Builds AiMessage objects with their prompts and inputs based on Prompt templates.
+  class MessageBuilder
+    def initialize(conversation)
+      @conversation = conversation
+    end
+
+    def build_from_single_prompt(name, description: nil, inputs: {})
+      prompt = Prompt.find_by!(name: name)
+      validate_inputs!(prompt, inputs)
+
+      interpolated_message = prompt.interpolate(inputs)
+      message = build_ai_message(interpolated_message, description)
+      build_prompt_association(message, prompt, inputs)
+
+      message # Return the built message
+    end
+
+    def build_from_multiple_prompts(prompt_inputs, description: nil)
+      message = @conversation.ai_messages.build(
+        request: '',
+        change_description: description,
+        llm: @conversation.model_identifier,
+        tool: @conversation.tool
+      )
+
+      prompt_inputs.each do |prompt_name, inputs|
+        process_single_prompt_input(message, prompt_name, inputs)
+      end
+
+      message # Return the built message
+    end
+
+    def process_single_prompt_input(message, prompt_name, inputs)
+      prompt = Prompt.find_by!(name: prompt_name)
+      validate_inputs!(prompt, inputs)
+
+      interpolated_message = prompt.interpolate(inputs)
+      message.request += interpolated_message
+
+      message_prompt = message.ai_message_prompts.build(
+        prompt_version_id: prompt.latest_version_id,
+        draft: prompt.message
+      )
+      build_inputs_for_prompt(message_prompt, inputs)
+    end
+
+    private
+
+    def validate_inputs!(prompt, inputs)
+      return unless prompt.valid_placeholders.present?
+
+      missing_inputs, extra_inputs = calculate_input_discrepancies(prompt, inputs)
+
+      errors = []
+      errors << "Missing required inputs: #{missing_inputs.join(', ')}" if missing_inputs.any?
+      errors << "Unknown inputs provided: #{extra_inputs.join(', ')}" if extra_inputs.any?
+
+      raise ArgumentError, errors.join("\n") if errors.any?
+    end
+
+    def build_prompt_association(message, prompt, inputs)
+      message_prompt = message.ai_message_prompts.build(
+        prompt: prompt,
+        prompt_version_id: prompt.latest_version_id,
+        draft: prompt.message
+      )
+      build_inputs_for_prompt(message_prompt, inputs)
+    end
+
+    def build_inputs_for_prompt(message_prompt, inputs)
+      inputs.each do |input_name, value|
+        message_prompt.ai_message_inputs.build(
+          placeholder_name: input_name.to_s,
+          value: value.to_s
+        )
+      end
+    end
+
+    # Calculates missing and extra inputs compared to prompt placeholders
+    def calculate_input_discrepancies(prompt, inputs)
+      required_placeholders = prompt.valid_placeholders.split(',').map(&:strip)
+      provided_keys = inputs.keys.map(&:to_s)
+      missing_inputs = required_placeholders - provided_keys
+      extra_inputs = provided_keys - required_placeholders
+      [missing_inputs, extra_inputs]
+    end
+
+    def build_ai_message(interpolated_message, description)
+      @conversation.ai_messages.build(
+        request: interpolated_message,
+        change_description: description,
+        llm: @conversation.model_identifier,
+        tool: @conversation.tool
+      )
+    end
+  end
+end

data/app/models/ruby_conversations/prompt.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # A prompt is a message template that can be used to generate messages for an AI conversation.
+  class Prompt < ActiveRecord::Base
+    include Versionable
+
+    # Constants
+    VALID_ROLES = %w[system user assistant].freeze
+
+    # Associations
+    has_many :versions, class_name: RubyConversations.configuration.prompt_version_class
+    has_many :message_prompts, class_name: RubyConversations.configuration.message_prompt_class
+    has_many :messages, through: :message_prompts, class_name: RubyConversations.configuration.message_class,
+                        source: :ai_message, dependent: :nullify
+    belongs_to :organization, optional: true
+
+    # Validations
+    validates :message, presence: true
+    validates :name, presence: true, uniqueness: true
+    validates :temperature, numericality: { greater_than_or_equal_to: 0.0 }, allow_nil: true
+    validates :role, presence: true, inclusion: { in: VALID_ROLES }
+    validate :validate_placeholders_format
+
+    # Scopes
+    scope :active, -> { where(active: true) }
+    scope :by_role, ->(role) { where(role: role) }
+    scope :with_versions, -> { includes(:versions) }
+    scope :ordered_by_name, -> { order(:name) }
+    scope :internal, -> { where(internal: true) }
+    scope :external, -> { where(internal: false) }
+
+    # Class methods
+    def self.find_by_name!(name)
+      find_by!(name: name.to_s.strip)
+    end
+
+    def self.roles
+      VALID_ROLES
+    end
+
+    # Instance methods
+    def latest_version_id
+      populate_initial_version!
+      versions.last&.id
+    end
+
+    def populate_initial_version!
+      versions.create!(message:, temperature:, created_at:, updated_at:) if versions.empty?
+    end
+
+    def interpolate(inputs = {})
+      return message if placeholders.empty?
+
+      validate_required_variables!(inputs)
+
+      interpolated = message.dup
+      format(interpolated, **inputs)
+    end
+
+    def placeholders
+      return [] if message.nil?
+
+      matches = message.scan(/%<([^>]+)>/)
+      matches&.flatten&.uniq || []
+    end
+
+    def active?
+      active
+    end
+
+    def deactivate!
+      update!(active: false)
+    end
+
+    def activate!
+      update!(active: true)
+    end
+
+    private
+
+    def versioned_attributes
+      %i[content role]
+    end
+
+    def validate_placeholders_format
+      invalid_placeholders = placeholders.grep_v(/\A[a-z_][a-z0-9_]*\z/i)
+
+      return unless invalid_placeholders.any?
+
+      errors.add(:message, "contains invalid placeholders: #{invalid_placeholders.join(', ')}")
+    end
+
+    def validate_required_variables!(variables)
+      missing = placeholders - variables.keys.map(&:to_s)
+      raise ArgumentError, "Missing required variables: #{missing.join(', ')}" if missing.any?
+
+      extra = variables.keys.map(&:to_s) - placeholders
+      return unless extra.any?
+
+      raise ArgumentError, "Unknown variables provided: #{extra.join(', ')}"
+    end
+  end
+end

data/app/models/ruby_conversations/prompt_version.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyConversations
+  # Represents a specific version of a Prompt template.
+  class PromptVersion < ActiveRecord::Base
+    # Associations
+    belongs_to :prompt
+
+    # Validations
+    validates :message, presence: true
+    validates :temperature, numericality: { greater_than_or_equal_to: 0.0 }, allow_nil: true
+
+    # Scopes
+    scope :ordered, -> { order(created_at: :desc) }
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module RubyConversations
+  module Generators
+    # Generates the necessary files for installing the ruby_conversations engine.
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migrations
+        migration_template_details.each do |file, description|
+          migration_template(
+            "migrations/#{file}",
+            "db/migrate/#{file.sub('.erb', '')}",
+            migration_version: migration_version,
+            migration_description: description
+          )
+        end
+      end
+
+      def create_initializer
+        template 'initializer.rb.erb', 'config/initializers/ruby_conversations.rb'
+      end
+
+      def mount_engine
+        route "mount RubyConversations::Engine => '/ai', as: 'ruby_conversations'"
+      end
+
+      def display_post_install_message
+        readme 'README.md'
+      end
+
+      private
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+
+      def migration_template_details
+        {
+          'create_prompts.rb.erb' => 'Create prompts table',
+          'create_prompt_versions.rb.erb' => 'Create prompt versions table',
+          'create_ai_conversations.rb.erb' => 'Create conversations table',
+          'create_ai_messages.rb.erb' => 'Create messages table',
+          'create_ai_message_prompts.rb.erb' => 'Create message prompts table',
+          'create_ai_message_inputs.rb.erb' => 'Create message inputs table'
+        }
+      end
+    end
+  end
+end

data/lib/generators/ruby_conversations/install/templates/README.md

@@ -0,0 +1,42 @@
+# RubyConversations Installation
+
+The gem has been installed! Here are the next steps:
+
+1. Run the migrations:
+   ```bash
+   bin/rails db:migrate
+   ```
+
+2. Configure the gem in `config/initializers/ruby_conversations.rb`
+   - Set your storage mode (:local or :remote)
+   - If using remote mode, set your API URL and JWT secret
+   - Customize model names if needed
+
+3. For remote mode, ensure your API endpoint is accessible and JWT authentication is configured.
+
+4. Start using conversations in your models:
+   ```ruby
+   class MyModel < ApplicationRecord
+     has_one :conversation, as: :conversationable, class_name: 'AiConversation'
+   end
+
+   # Create a conversation
+   conversation = my_model.create_conversation!
+   
+   # Ask a question using a prompt
+   conversation.ask("explain_code", inputs: { code: "def hello; end" })
+   ```
+
+5. The engine is mounted at `/ai`. You can change this in `config/routes.rb` if needed.
+
+## What's Next?
+
+- Check out the documentation at https://github.com/yourusername/ruby_conversations
+- Review the example app at https://github.com/yourusername/ruby_conversations_example
+- Join our Discord community at https://discord.gg/ruby_conversations
+
+## Need Help?
+
+- Open an issue on GitHub
+- Check our FAQ at https://github.com/yourusername/ruby_conversations/wiki/FAQ
+- Email support at support@example.com