raif 1.0.0

data/app/models/raif/agent.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Raif
+  class Agent < ApplicationRecord
+    include Raif::Concerns::HasLlm
+    include Raif::Concerns::HasRequestedLanguage
+    include Raif::Concerns::HasAvailableModelTools
+    include Raif::Concerns::InvokesModelTools
+
+    belongs_to :creator, polymorphic: true
+
+    has_many :raif_model_completions, as: :source, dependent: :destroy, class_name: "Raif::ModelCompletion"
+
+    after_initialize -> { self.available_model_tools ||= [] }
+    after_initialize -> { self.conversation_history ||= [] }
+
+    boolean_timestamp :started_at
+    boolean_timestamp :completed_at
+    boolean_timestamp :failed_at
+
+    validates :type, inclusion: { in: ->{ Raif.config.agent_types } }
+    validates :task, presence: true
+    validates :system_prompt, presence: true
+    validates :max_iterations, presence: true, numericality: { greater_than: 0 }
+    validates :available_model_tools, length: {
+      minimum: 1,
+      message: ->(_object, _data) {
+        I18n.t("raif.agents.errors.available_model_tools.too_short")
+      }
+    }
+
+    before_validation -> { self.system_prompt ||= build_system_prompt }, on: :create
+
+    attr_accessor :on_conversation_history_entry
+
+    # Runs the agent and returns a Raif::Agent.
+    # If a block is given, it will be called each time a new entry is added to the agent's conversation history.
+    # The block will receive the Raif::Agent and the new entry as arguments:
+    # agent = Raif::Agent.new(
+    #   task: task,
+    #   tools: [Raif::ModelTools::WikipediaSearch, Raif::ModelTools::FetchUrl],
+    #   creator: creator
+    # )
+    #
+    # agent.run! do |conversation_history_entry|
+    #   Turbo::StreamsChannel.broadcast_append_to(
+    #     :my_agent_channel,
+    #     target: "agent-progress",
+    #     partial: "my_partial_displaying_agent_progress",
+    #     locals: { agent: agent, conversation_history_entry: conversation_history_entry }
+    #   )
+    # end
+    #
+    # The conversation_history_entry will be a hash with "role" and "content" keys:
+    # { "role" => "assistant", "content" => "a message here" }
+    #
+    # @param block [Proc] Optional block to be called each time a new entry to the agent's conversation history is generated
+    # @return [Raif::Agent] The agent that was created and run
+    def run!(&block)
+      self.on_conversation_history_entry = block_given? ? block : nil
+      self.started_at = Time.current
+      self.available_model_tools += ["Raif::ModelTools::AgentFinalAnswer"] unless available_model_tools.include?("Raif::ModelTools::AgentFinalAnswer")
+      save!
+
+      logger.debug <<~DEBUG
+        --------------------------------
+        Starting Agent Run
+        --------------------------------
+        System Prompt:
+        #{system_prompt}
+
+        Task: #{task}
+      DEBUG
+
+      add_conversation_history_entry({ role: "user", content: task })
+
+      while iteration_count < max_iterations
+        update_columns(iteration_count: iteration_count + 1)
+
+        model_completion = llm.chat(
+          messages: conversation_history,
+          source: self,
+          system_prompt: system_prompt,
+          available_model_tools: native_model_tools
+        )
+
+        logger.debug <<~DEBUG
+          --------------------------------
+          Agent iteration #{iteration_count}
+          Messages:
+          #{JSON.pretty_generate(conversation_history)}
+
+          Response:
+          #{model_completion.raw_response}
+          --------------------------------
+        DEBUG
+
+        process_iteration_model_completion(model_completion)
+        break if final_answer.present?
+      end
+
+      completed!
+      final_answer
+    rescue StandardError => e
+      self.failed_at = Time.current
+      self.failure_reason = e.message
+      save!
+
+      raise
+    end
+
+  private
+
+    def process_iteration_model_completion(model_completion)
+      raise NotImplementedError, "#{self.class.name} must implement execute_agent_iteration"
+    end
+
+    def native_model_tools
+      # no-op by default
+    end
+
+    def add_conversation_history_entry(entry)
+      entry_stringified = entry.stringify_keys
+      conversation_history << entry_stringified
+      on_conversation_history_entry.call(entry_stringified) if on_conversation_history_entry.present?
+    end
+
+    def build_system_prompt
+      raise NotImplementedError, "Subclasses of Raif::Agent must implement build_system_prompt"
+    end
+
+  end
+end

data/app/models/raif/agents/native_tool_calling_agent.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Raif
+  module Agents
+    class NativeToolCallingAgent < Raif::Agent
+      validate :ensure_llm_supports_native_tool_use
+
+      def build_system_prompt
+        <<~PROMPT.strip
+          You are an AI agent that follows the ReAct (Reasoning + Acting) framework to complete tasks step by step using tool/function calls.
+
+          At each step, you must:
+          1. Think about what to do next.
+          2. Choose and invoke exactly one tool/function call based on that thought.
+          3. Observe the results of the tool/function call.
+          4. Use the results to update your thought process.
+          5. Repeat steps 1-4 until the task is complete.
+          6. Provide a final answer to the user's request.
+
+          For your final answer:
+          - Use the agent_final_answer tool/function with your complete answer as the "final_answer" parameter.
+          - Your answer should be comprehensive and directly address the user's request.
+
+          Guidelines
+          - Always think step by step
+          - Be concise in your reasoning but thorough in your analysis
+          - If a tool returns an error, try to understand why and adjust your approach
+          - If you're unsure about something, explain your uncertainty, but do not make things up
+          - Always provide a final answer that directly addresses the user's request
+
+          Remember: Your goal is to be helpful, accurate, and efficient in solving the user's request.#{system_prompt_language_preference}
+        PROMPT
+      end
+
+    private
+
+      def native_model_tools
+        available_model_tools
+      end
+
+      def process_iteration_model_completion(model_completion)
+        if model_completion.parsed_response.present?
+          add_conversation_history_entry({
+            role: "assistant",
+            content: model_completion.parsed_response
+          })
+        end
+
+        if model_completion.response_tool_calls.blank?
+          add_conversation_history_entry({
+            role: "assistant",
+            content: "<observation>Error: No tool call found. I need make a tool call at each step. Available tools: #{available_model_tools_map.keys.join(", ")}</observation>" # rubocop:disable Layout/LineLength
+          })
+          return
+        end
+
+        tool_call = model_completion.response_tool_calls.first
+
+        unless tool_call["name"] && tool_call["arguments"]
+          add_conversation_history_entry({
+            role: "assistant",
+            content: "<observation>Error: Invalid action specified. Please provide a valid action, formatted as a JSON object with 'tool' and 'arguments' keys.</observation>" # rubocop:disable Layout/LineLength
+          })
+          return
+        end
+
+        tool_name = tool_call["name"]
+        tool_arguments = tool_call["arguments"]
+
+        # Add assistant's response to conversation history (without the actual tool calls)
+        # add_conversation_history_entry({
+        #   role: "assistant",
+        #   content: "<thought>I need to use the #{tool_name} tool to help with this task.</thought>"
+        # })
+
+        # Check if we have a final answer. If yes, we're done.
+        if tool_name == "agent_final_answer"
+          self.final_answer = tool_arguments["final_answer"]
+          add_conversation_history_entry({ role: "assistant", content: "<answer>#{final_answer}</answer>" })
+          return
+        end
+
+        # Add the tool call to conversation history
+        add_conversation_history_entry({
+          role: "assistant",
+          content: "<action>#{JSON.pretty_generate(tool_call)}</action>"
+        })
+
+        # Find the tool class and process it
+        tool_klass = available_model_tools_map[tool_name]
+
+        # The model tried to use a tool that doesn't exist
+        unless tool_klass
+          add_conversation_history_entry({
+            role: "assistant",
+            content: "<observation>Error: Tool '#{tool_name}' not found. Available tools: #{available_model_tools_map.keys.join(", ")}</observation>"
+          })
+          return
+        end
+
+        unless JSON::Validator.validate(tool_klass.tool_arguments_schema, tool_arguments)
+          add_conversation_history_entry({
+            role: "assistant",
+            content: "<observation>Error: Invalid tool arguments. Please provide valid arguments for the tool '#{tool_name}'. Tool arguments schema: #{tool_klass.tool_arguments_schema.to_json}</observation>" # rubocop:disable Layout/LineLength
+          })
+          return
+        end
+
+        # Process the tool and add observation to history
+        tool_invocation = tool_klass.invoke_tool(tool_arguments: tool_arguments, source: self)
+        observation = tool_klass.observation_for_invocation(tool_invocation)
+
+        add_conversation_history_entry({
+          role: "assistant",
+          content: "<observation>#{observation}</observation>"
+        })
+      end
+
+      def ensure_llm_supports_native_tool_use
+        unless llm.supports_native_tool_use?
+          errors.add(:base, "Raif::Agent#llm_model_key must use an LLM that supports native tool use")
+        end
+      end
+
+    end
+  end
+end

data/app/models/raif/agents/re_act_agent.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Raif
+  module Agents
+    class ReActAgent < Raif::Agent
+
+      def build_system_prompt
+        <<~PROMPT.strip
+          You are an intelligent assistant that follows the ReAct (Reasoning + Acting) framework to complete tasks step by step using tool calls.
+
+          # Available Tools
+          You have access to the following tools:
+          #{available_model_tools_map.values.map(&:description_for_llm).join("\n---\n")}
+          # Your Responses
+          Your responses should follow this structure & format:
+          <thought>Your step-by-step reasoning about what to do</thought>
+          <action>JSON object with "tool" and "arguments" keys</action>
+          <observation>Results from the tool, which will be provided to you</observation>
+          ... (repeat Thought/Action/Observation as needed until the task is complete)
+          <thought>Final reasoning based on all observations</thought>
+          <answer>Your final response to the user</answer>
+
+          # How to Use Tools
+          When you need to use a tool:
+          1. Identify which tool is appropriate for the task
+          2. Format your tool call using JSON with the required arguments and place it in the <action> tag
+          3. Here is an example: <action>{"tool": "tool_name", "arguments": {...}}</action>
+
+          # Guidelines
+          - Always think step by step
+          - Use tools when appropriate, but don't use tools for tasks you can handle directly
+          - Be concise in your reasoning but thorough in your analysis
+          - If a tool returns an error, try to understand why and adjust your approach
+          - If you're unsure about something, explain your uncertainty, but do not make things up
+          - After each thought, make sure to also include an <action> or <answer>
+          - Always provide a final answer that directly addresses the user's request
+
+          Remember: Your goal is to be helpful, accurate, and efficient in solving the user's request.#{system_prompt_language_preference}
+        PROMPT
+      end
+
+    private
+
+      def process_iteration_model_completion(model_completion)
+        agent_step = Raif::Agents::ReActStep.new(model_response_text: model_completion.raw_response)
+
+        # Add the thought to conversation history
+        if agent_step.thought
+          add_conversation_history_entry({ role: "assistant", content: "<thought>#{agent_step.thought}</thought>" })
+        end
+
+        # If there's an answer, we're done
+        if agent_step.answer
+          self.final_answer = agent_step.answer
+          add_conversation_history_entry({ role: "assistant", content: "<answer>#{agent_step.answer}</answer>" })
+          return
+        end
+
+        # If there's an action, execute it
+        process_action(agent_step.action) if agent_step.action
+      end
+
+      def process_action(action)
+        add_conversation_history_entry({ role: "assistant", content: "<action>#{action}</action>" })
+
+        # The action should always be a JSON object with "tool" and "arguments" keys
+        parsed_action = begin
+          JSON.parse(action)
+        rescue JSON::ParserError => e
+          add_conversation_history_entry({
+            role: "assistant",
+            content: "<observation>Error parsing action JSON: #{e.message}</observation>"
+          })
+
+          nil
+        end
+
+        return if parsed_action.blank?
+
+        unless parsed_action["tool"] && parsed_action["arguments"]
+          add_conversation_history_entry({
+            role: "assistant",
+            content: "<observation>Error: Invalid action specified. Please provide a valid action, formatted as a JSON object with 'tool' and 'arguments' keys.</observation>" # rubocop:disable Layout/LineLength
+          })
+          return
+        end
+
+        tool_name = parsed_action["tool"]
+        tool_arguments = parsed_action["arguments"]
+        tool_klass = available_model_tools_map[tool_name]
+
+        # The model tried to use a tool that doesn't exist
+        unless tool_klass
+          add_conversation_history_entry({
+            role: "assistant",
+            content: "<observation>Error: Tool '#{tool_name}' not found. Available tools: #{available_model_tools_map.keys.join(", ")}</observation>"
+          })
+          return
+        end
+
+        unless JSON::Validator.validate(tool_klass.tool_arguments_schema, tool_arguments)
+          add_conversation_history_entry({
+            role: "assistant",
+            content: "<observation>Error: Invalid tool arguments. Please provide valid arguments for the tool '#{tool_name}'. Tool arguments schema: #{tool_klass.tool_arguments_schema.to_json}</observation>" # rubocop:disable Layout/LineLength
+          })
+          return
+        end
+
+        tool_invocation = tool_klass.invoke_tool(tool_arguments: tool_arguments, source: self)
+        observation = tool_klass.observation_for_invocation(tool_invocation)
+
+        # Add the tool invocation to conversation history
+        add_conversation_history_entry({
+          role: "assistant",
+          content: "<observation>#{observation}</observation>"
+        })
+      end
+
+    end
+  end
+end

data/app/models/raif/agents/re_act_step.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Raif
+  module Agents
+    class ReActStep
+      attr_reader :model_response_text
+
+      def initialize(model_response_text:)
+        @model_response_text = model_response_text
+      end
+
+      def thought
+        @thought ||= extract_tag_content("thought")
+      end
+
+      def answer
+        @answer ||= extract_tag_content("answer")
+      end
+
+      def action
+        @action ||= extract_tag_content("action")
+      end
+
+    private
+
+      def extract_tag_content(tag_name)
+        match = model_response_text.match(%r{<#{tag_name}>(.*?)</#{tag_name}>}m)
+        match ? match[1].strip : nil
+      end
+
+    end
+  end
+end

data/app/models/raif/application_record.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class Raif::ApplicationRecord < Raif.config.model_superclass.constantize
+  include Raif::Concerns::BooleanTimestamp
+
+  self.abstract_class = true
+
+  scope :newest_first, -> { order(created_at: :desc) }
+  scope :oldest_first, -> { order(created_at: :asc) }
+
+  def self.table_name_prefix
+    "raif_"
+  end
+end

data/app/models/raif/concerns/boolean_timestamp.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Raif::Concerns::BooleanTimestamp
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Column name should be something like email_abc_disabled_at, or its inverse should be specified
+    def boolean_timestamp(column_name, define_inverse_accessors: false)
+      if define_inverse_accessors.present?
+        unless define_inverse_accessors.is_a?(Symbol) || column_name.end_with?("_disabled_at") || column_name.end_with?("_enabled_at")
+          raise ArgumentError, "boolean_timestamp column name (#{column_name}) must end with '_disabled_at' or '_enabled_at'"
+        end
+
+        inverse_boolean_column_name = define_inverse_accessors if define_inverse_accessors.is_a?(Symbol)
+      end
+
+      # Get the boolean version of the column name (e.g. email_abc_disabled)
+      boolean_column_name = column_name.to_s.gsub(/_at$/, "")
+
+      # Define boolean getter (e.g. email_abc_disabled?)
+      define_method("#{boolean_column_name}?") do
+        send(column_name).present?
+      end
+      alias_method boolean_column_name, "#{boolean_column_name}?"
+
+      # Define boolean setter (e.g. email_abc_disabled = true)
+      define_method("#{boolean_column_name}=") do |val|
+        if val == "1" || val == 1 || val == true || val == "true"
+          send("#{column_name}=", Time.current) if send(column_name).nil?
+        else
+          send("#{column_name}=", nil)
+        end
+      end
+
+      # Define bang method to set the value (e.g. email_abc_disabled!)
+      define_method("#{boolean_column_name}!") do
+        update(column_name => Time.current) if send(column_name).nil?
+      end
+
+      scope boolean_column_name, -> { where.not(table_name => { column_name => nil }) }
+
+      # Define the inverse getter/setter (e.g. email_abc_enabled?)
+      if define_inverse_accessors
+        inverse_boolean_column_name ||= if boolean_column_name.end_with?("_disabled")
+          boolean_column_name.gsub(/_disabled$/, "_enabled")
+        else
+          boolean_column_name.gsub(/_enabled$/, "_disabled")
+        end
+
+        # Define boolean getter (e.g. email_abc_enabled)
+        define_method("#{inverse_boolean_column_name}?") do
+          !send(boolean_column_name)
+        end
+        alias_method inverse_boolean_column_name, "#{inverse_boolean_column_name}?"
+
+        # Define boolean setter (e.g. email_abc_enabled = true)
+        define_method("#{inverse_boolean_column_name}=") do |val|
+          if val == "1" || val == 1 || val == true || val == "true"
+            send("#{column_name}=", nil)
+          elsif send(column_name).nil?
+            send("#{column_name}=", Time.current)
+          end
+        end
+
+        scope inverse_boolean_column_name, -> { where(table_name => { column_name => nil }) }
+      end
+    end
+  end
+end

data/app/models/raif/concerns/has_available_model_tools.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Raif::Concerns::HasAvailableModelTools
+  extend ActiveSupport::Concern
+
+  def available_model_tools_map
+    @available_model_tools_map ||= available_model_tools&.map do |tool_name|
+      tool_klass = tool_name.is_a?(String) ? tool_name.constantize : tool_name
+      [tool_klass.tool_name, tool_klass]
+    end.to_h
+  end
+
+end

data/app/models/raif/concerns/has_llm.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Raif::Concerns::HasLlm
+  extend ActiveSupport::Concern
+
+  included do
+    validates :llm_model_key, presence: true, inclusion: { in: ->{ Raif.available_llm_keys.map(&:to_s) } }
+
+    before_validation ->{ self.llm_model_key ||= default_llm_model_key }
+  end
+
+  def default_llm_model_key
+    Rails.env.test? ? :raif_test_llm : Raif.config.default_llm_model_key
+  end
+
+  def llm
+    @llm ||= Raif.llm(llm_model_key.to_sym)
+  end
+end

data/app/models/raif/concerns/has_requested_language.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Raif::Concerns::HasRequestedLanguage
+  extend ActiveSupport::Concern
+
+  included do
+    validates :requested_language_key, inclusion: { in: Raif.supported_languages, allow_blank: true }
+  end
+
+  def requested_language_name
+    @requested_language_name ||= I18n.t("raif.languages.#{requested_language_key}", locale: "en")
+  end
+
+  def system_prompt_language_preference
+    return if requested_language_key.blank?
+
+    "\nYou're collaborating with teammate who speaks #{requested_language_name}. Please respond in #{requested_language_name}."
+  end
+
+end

data/app/models/raif/concerns/invokes_model_tools.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Raif::Concerns::InvokesModelTools
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :raif_model_tool_invocations,
+      class_name: "Raif::ModelToolInvocation",
+      as: :source,
+      dependent: :destroy
+  end
+
+end

data/app/models/raif/concerns/llm_response_parsing.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Raif::Concerns::LlmResponseParsing
+  extend ActiveSupport::Concern
+
+  included do
+    normalizes :raw_response, with: ->(text){ text&.strip }
+
+    enum :response_format, Raif::Llm.valid_response_formats, prefix: true
+
+    validates :response_format, presence: true, inclusion: { in: response_formats.keys }
+  end
+
+  # Parses the response from the LLM into a structured format, based on the response_format.
+  # If the response format is JSON, it will be parsed using JSON.parse.
+  # If the response format is HTML, it will be sanitized via ActionController::Base.helpers.sanitize.
+  #
+  # @return [Object] The parsed response.
+  def parsed_response
+    return if raw_response.blank?
+
+    @parsed_response ||= if response_format_json?
+      json = raw_response.gsub("```json", "").gsub("```", "")
+      JSON.parse(json)
+    elsif response_format_html?
+      html = raw_response.strip.gsub("```html", "").chomp("```")
+      clean_html_fragment(html)
+    else
+      raw_response.strip
+    end
+  end
+
+  def clean_html_fragment(html)
+    fragment = Nokogiri::HTML.fragment(html)
+
+    fragment.traverse do |node|
+      if node.text? && node.text.strip.empty?
+        node.remove
+      end
+    end
+
+    ActionController::Base.helpers.sanitize(fragment.to_html).strip
+  end
+end

data/app/models/raif/conversation.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class Raif::Conversation < Raif::ApplicationRecord
+  include Raif::Concerns::HasLlm
+  include Raif::Concerns::HasRequestedLanguage
+  include Raif::Concerns::HasAvailableModelTools
+
+  belongs_to :creator, polymorphic: true
+
+  has_many :entries, class_name: "Raif::ConversationEntry", dependent: :destroy, foreign_key: :raif_conversation_id, inverse_of: :raif_conversation
+
+  validates :type, inclusion: { in: ->{ Raif.config.conversation_types } }
+
+  after_initialize -> { self.available_model_tools ||= [] }
+  after_initialize -> { self.available_user_tools ||= [] }
+
+  before_validation ->{ self.type ||= "Raif::Conversation" }, on: :create
+  before_validation -> { self.system_prompt ||= build_system_prompt }, on: :create
+
+  def build_system_prompt
+    <<~PROMPT
+      #{system_prompt_intro}
+      #{system_prompt_language_preference}
+    PROMPT
+  end
+
+  def system_prompt_intro
+    Raif.config.conversation_system_prompt_intro
+  end
+
+  # i18n-tasks-use t('raif.conversation.initial_chat_message')
+  def initial_chat_message
+    I18n.t("#{self.class.name.underscore.gsub("/", ".")}.initial_chat_message")
+  end
+
+  def prompt_model_for_entry_response(entry:)
+    llm.chat(
+      messages: llm_messages,
+      source: entry,
+      response_format: :text,
+      system_prompt: system_prompt,
+      available_model_tools: available_model_tools
+    )
+  end
+
+  def llm_messages
+    messages = []
+
+    entries.oldest_first.includes(:raif_model_tool_invocations).each do |entry|
+      messages << { "role" => "user", "content" => entry.user_message }
+      next unless entry.completed?
+
+      messages << { "role" => "assistant", "content" => entry.model_response_message } unless entry.model_response_message.blank?
+      entry.raif_model_tool_invocations.each do |tool_invocation|
+        messages << { "role" => "assistant", "content" => tool_invocation.as_llm_message }
+        messages << { "role" => "assistant", "content" => tool_invocation.result_llm_message } if tool_invocation.result_llm_message.present?
+      end
+    end
+
+    messages
+  end
+
+  def available_user_tool_classes
+    available_user_tools.map(&:constantize)
+  end
+
+end