Skip to content

A platform for community discussion. Free, open, simple.

22.0 KB
Raw Blame
#frozen_string_literal: true

module DiscourseAi
  module Agents
    class Agent
      DELEGATED_IMAGE_PATTERN = %r{!\[[^\]]*\]\((upload://[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]{1,10})?)\)}

      class << self
        def default_enabled
          true
        end

        def rag_conversation_chunks
          10
        end

        def vision_enabled
          false
        end

        def vision_max_pixels
          1_048_576
        end

        def max_turn_tokens
          nil
        end

        def subagent_ids
          []
        end

        def compression_threshold
          nil
        end

        def rag_document_sources
          []
        end

        def force_default_llm
          false
        end

        def supports_bot_user?
          agents_supporting_bot_user.any? { |klass| self <= klass }
        end

        def allow_chat_channel_mentions
          false
        end

        def allow_chat_direct_messages
          false
        end

        def system_agents
          sync_external_registry!
          @system_agents ||= builtin_system_agents
        end

        def system_agents_by_id
          @system_agents_by_id ||= system_agents.invert
        end

        def builtin_tool_by_name(name)
          normalized_name = name.to_s.gsub("Tool", "")
          normalized_name = "List#{normalized_name}" if %w[Categories Tags Users].include?(
            normalized_name,
          )
          "DiscourseAi::Agents::Tools::#{normalized_name}".safe_constantize
        end

        def external_tool_by_name(name)
          sync_external_registry!
          @external_tools_by_name[name]
        end

        def external_tools
          sync_external_registry!
          @external_tools_by_name.values
        end

        def all(user:)
          # listing tools has to be dynamic cause site settings may change
          available_tools = all_available_tools
          AiAgent.all_agents.filter do |agent|
            next false if !user.in_any_groups?(agent.allowed_group_ids)

            if agent.system
              instance = agent.new
              instance.required_tools == [] || (instance.required_tools - available_tools).empty?
            else
              true
            end
          end
        end

        def find_by(id: nil, name: nil, user:)
          all(user: user).find { |agent| agent.id == id || agent.name == name }
        end

        def name
          I18n.t("discourse_ai.ai_bot.agents.#{to_s.demodulize.underscore}.name")
        end

        def description
          I18n.t("discourse_ai.ai_bot.agents.#{to_s.demodulize.underscore}.description")
        end

        def all_available_tools
          tools = [
            Tools::ListCategories,
            Tools::ListUsers,
            Tools::Time,
            Tools::Search,
            Tools::SearchUploadedDocuments,
            Tools::Read,
            Tools::ReadPost,
            Tools::FlagPost,
            Tools::CloseTopic,
            Tools::SuspendUser,
            Tools::SilenceUser,
            Tools::UnlistTopic,
            Tools::LockPost,
            Tools::DeleteTopic,
            Tools::EditPost,
            Tools::CreateCategory,
            Tools::EditCategory,
            Tools::ChangeTopicCategory,
            Tools::SetTopicTimer,
            Tools::SetSlowMode,
            Tools::MovePosts,
            Tools::GrantBadge,
            Tools::ListReviewables,
            Tools::PerformReviewableAction,
            Tools::AddReviewableNote,
            Tools::DbSchema,
            Tools::SearchSettings,
            Tools::SearchDiscourseNavigation,
            Tools::SettingContext,
            Tools::ReadSiteSetting,
            Tools::ChangeSiteSetting,
            Tools::GenerateAppearanceChange,
            Tools::SaveAppearanceChange,
            Tools::ActivateAppearanceChange,
            Tools::RevertAppearanceChange,
            Tools::ListAppearanceChanges,
            Tools::RandomPicker,
            Tools::LoadDiscourseWebsitePage,
            Tools::DiscourseMetaSearch,
            Tools::GithubFileContent,
            Tools::GithubDiff,
            Tools::GithubSearchFiles,
            Tools::WebBrowser,
            Tools::JavascriptEvaluator,
            Tools::Researcher,
          ]

          if SiteSetting.ai_artifact_security.in?(%w[lax hybrid strict])
            tools << Tools::CreateArtifact
            tools << Tools::UpdateArtifact
            tools << Tools::ReadArtifact
          end

          tools << Tools::GithubSearchCode if SiteSetting.ai_bot_github_access_token.present?

          if SiteSetting.tagging_enabled
            tools << Tools::ListTags
            tools << Tools::CreateTag
            tools << Tools::EditTag
            tools << Tools::ChangeTopicTags
          end

          # Image generation tools - use custom UI-configured tools
          if Tools::Tool.available_custom_image_tools.present?
            tools << Tools::Image
            tools << Tools::CreateImage
            tools << Tools::EditImage
          end

          if SiteSetting.ai_google_custom_search_api_key.present? &&
               SiteSetting.ai_google_custom_search_cx.present?
            tools << Tools::Google
          end

          tools << Tools::Assign if defined?(::Assigner)
          tools << Tools::MarkAsSolved if defined?(::DiscourseSolved)
          tools.concat(external_tools)

          DiscoursePluginRegistry.apply_modifier(:ai_agent_available_tools, tools).uniq
        end

        def external_agent_id(agent_klass)
          -(Digest::SHA1.hexdigest(agent_klass.to_s).to_i(16) % 1_000_000 + 1_000_000)
        end

        private

        def sync_external_registry!
          configs = external_feature_configs
          standalone_tools = DiscoursePluginRegistry.external_ai_tools
          signature = [configs, standalone_tools].hash
          if @external_registry_signature == signature && @external_tools_by_name && @system_agents
            return
          end

          external_agents = {}
          external_tools_by_name = {}
          agent_tools = []

          configs.each do |config|
            agent_klass = config[:agent_klass]
            next if agent_klass.nil?
            next if external_agents.key?(agent_klass)
            next if builtin_system_agents.key?(agent_klass)

            external_agents[agent_klass] = config[:agent_id]
            agent_tools.concat(agent_klass.new.tools)
          end

          (agent_tools + standalone_tools).each do |tool_klass|
            tool_name = tool_klass.to_s.demodulize
            builtin = builtin_tool_by_name(tool_name)
            next if builtin == tool_klass
            if builtin
              raise ArgumentError,
                    "AI tool '#{tool_name}' from #{tool_klass} clashes with built-in #{builtin}"
            end

            existing = external_tools_by_name[tool_name]
            if existing && existing.to_s != tool_klass.to_s
              raise ArgumentError,
                    "AI tool '#{tool_name}' from #{tool_klass} is already registered by #{existing}"
            end

            external_tools_by_name[tool_name] = tool_klass
          end

          new_system_agents = builtin_system_agents.merge(external_agents)
          @system_agents_by_id = nil if @system_agents != new_system_agents
          @system_agents = new_system_agents
          @external_tools_by_name = external_tools_by_name
          @external_registry_signature = signature
        end

        def external_feature_configs
          return [] if !DiscoursePluginRegistry.respond_to?(:_raw_external_ai_features)

          DiscoursePluginRegistry
            ._raw_external_ai_features
            .pluck(:value)
            .each do |config|
              config[:agent_id] ||= external_agent_id(config[:agent_klass]) if config[:agent_klass]
            end
        end

        def agents_supporting_bot_user
          @agents_supporting_bot_user ||= [
            General,
            SqlHelper,
            Artist,
            SettingsExplorer,
            Researcher,
            Creative,
            DiscourseHelper,
            GithubHelper,
            WebArtifactCreator,
            Designer,
            ForumResearcher,
            Discover,
            DiscourseAdminAssistant,
          ].freeze
        end

        def builtin_system_agents
          @builtin_system_agents ||= {
            General => -1,
            SqlHelper => -2,
            Artist => -3,
            SettingsExplorer => -4,
            Researcher => -5,
            Creative => -6,
            DiscourseHelper => -8,
            GithubHelper => -9,
            WebArtifactCreator => -10,
            Summarizer => -11,
            ShortSummarizer => -12,
            Designer => -13,
            ForumResearcher => -14,
            ConceptFinder => -15,
            ConceptMatcher => -16,
            ConceptDeduplicator => -17,
            CustomPrompt => -18,
            SmartDates => -19,
            MarkdownTableGenerator => -20,
            PostIllustrator => -21,
            Proofreader => -22,
            TitlesGenerator => -23,
            Tutor => -24,
            Translator => -25,
            ImageCaptioner => -26,
            LocaleDetector => -27,
            PostRawTranslator => -28,
            TopicTitleTranslator => -29,
            ShortTextTranslator => -30,
            SpamDetector => -31,
            ContentCreator => -32,
            ReportRunner => -33,
            Discover => -34,
            ChatThreadTitler => -35,
            SentimentClassifier => -36,
            EmotionClassifier => -37,
            AdminDashboardHighlights => -38,
            DiscourseAdminAssistant => -39,
            AskAiQueryRewriter => -40,
            AskAiSynthesis => -41,
            AskAiReporter => -42,
          }.freeze
        end
      end

      def id
        @ai_agent&.id || self.class.system_agents[self.class.superclass] ||
          self.class.system_agents[self.class]
      end

      def tools
        []
      end

      def force_tool_use
        []
      end

      def forced_tool_count
        -1
      end

      def required_tools
        []
      end

      def stop_chain_on_pending_approval?
        false
      end

      def temperature
        nil
      end

      def top_p
        nil
      end

      def thinking_effort
        nil
      end

      def options
        {}
      end

      def response_format
        nil
      end

      def examples
        []
      end

      def native_tools
        []
      end

      def available_tools
        self
          .class
          .all_available_tools
          .filter { |tool| tools.include?(tool) }
          .concat(tools.filter(&:custom?))
          .tap do |available_tools|
            next if !rag_tool_available?
            if available_tools.any? { |tool|
                 tool.signature[:name] == Tools::SearchUploadedDocuments.name
               }
              next
            end

            available_tools << Tools::SearchUploadedDocuments
          end
          .uniq
      end

      def runtime_tools(llm: nil, context: nil)
        reserved_spawn_agent = self.class.subagent_ids.present?
        tools =
          available_tools.reject do |tool|
            tool_name = tool.signature[:name]
            !tool.available_for_context?(context) || tool_name == Tools::ViewImage.name ||
              reserved_spawn_agent && tool_name.to_s.casecmp(Tools::SpawnAgent.name).zero?
          end

        if (spawn_agent_tool = spawn_agent_tool_class(context))
          tools.unshift(spawn_agent_tool)
        end

        if automatic_vision_tool_enabled?(context) && llm&.llm_model&.delegated_vision?
          tools << Tools::ViewImage
        end

        tools.uniq { |tool| tool.signature[:name].to_s.downcase }
      end

      def spawn_agent_tool_class(context)
        return if self.class.subagent_ids.blank?
        return if context&.server_owned_tools == false || context&.user.nil?
        return if context.subagent_depth.to_i >= SubagentRunner::MAX_SUBAGENT_DEPTH

        state = context.subagent_execution_state
        return if !state&.completion_available? || state.remaining_tokens <= 0

        records_by_id = AiAgent.where(id: self.class.subagent_ids, enabled: true).index_by(&:id)
        models_by_agent_id = SubagentRunner.resolve_models(records_by_id.values)
        usable_agents =
          self.class.subagent_ids.filter_map do |subagent_id|
            record = records_by_id[subagent_id]
            next if !record
            next if !context.user.in_any_groups?(record.allowed_group_ids)
            next if !models_by_agent_id[subagent_id]
            if record.system?
              required_tools = record.class_instance.new.required_tools
              next if (required_tools - self.class.all_available_tools).present?
            end

            record
          end
        return if usable_agents.empty?

        Tools::SpawnAgent.class_instance(id, usable_agents)
      end

      def automatic_vision_tool_enabled?(context)
        context&.server_owned_tools != false && self.class.vision_enabled
      end

      def defer_forced_tool_for_vision?
        false
      end

      def craft_prompt(context, llm: nil)
        available_tools = runtime_tools(llm: llm, context: context)
        context.runtime_tools = available_tools
        context.runtime_tools_llm_model_id = llm&.llm_model&.id
        messages = delegated_vision_messages(context, llm)
        system_insts = replace_placeholders(system_prompt, context)

        prompt_insts = <<~TEXT.strip
          #{system_insts}
          #{available_tools.map(&:custom_system_message).compact_blank.join("\n")}
          TEXT

        if context.custom_instructions.present?
          prompt_insts << "\n"
          prompt_insts << context.custom_instructions
        end

        post_system_examples = []

        if examples.present?
          examples.flatten.each_with_index do |e, idx|
            post_system_examples << {
              content: replace_placeholders(e, context),
              type: (idx + 1).odd? ? :user : :model,
            }
          end
        end

        prompt =
          DiscourseAi::Completions::Prompt.new(
            prompt_insts,
            messages: post_system_examples.concat(messages),
            topic_id: context.topic_id,
            post_id: context.post_id,
          )

        prompt.max_pixels = self.class.vision_max_pixels if self.class.vision_enabled
        prompt.tools = available_tools.map(&:signature) if available_tools
        prompt.native_tools = native_tools if native_tools.present?
        available_tools.each do |tool|
          tool.inject_prompt(prompt: prompt, context: context, agent: self)
        end
        prompt
      end

      def find_tool(partial, bot_user:, llm:, context:, existing_tools: [])
        return nil if !partial.is_a?(DiscourseAi::Completions::ToolCall)
        tool_instance(
          partial,
          bot_user: bot_user,
          llm: llm,
          context: context,
          existing_tools: existing_tools,
        )
      end

      def allow_partial_tool_calls?
        available_tools.any? { |tool| tool.allow_partial_tool_calls? }
      end

      protected

      def delegated_vision_messages(context, llm)
        return context.messages if !automatic_vision_tool_enabled?(context)
        return context.messages if !llm&.llm_model&.delegated_vision?
        return context.messages if !self.class.vision_enabled

        messages = context.messages.deep_dup
        uploads_by_id, uploads_by_sha1 = delegated_vision_uploads(messages)

        messages.map do |message|
          next message if message[:type].to_sym != :user

          message[:content] = delegated_vision_content(
            message[:content],
            context,
            uploads_by_id,
            uploads_by_sha1,
          )
          message
        end
      end

      def delegated_vision_uploads(messages)
        upload_ids = Set.new
        upload_sha1s = Set.new

        messages.each do |message|
          next if message[:type].to_sym != :user

          content_parts = message[:content].is_a?(Array) ? message[:content] : [message[:content]]
          content_parts.each do |part|
            if part.is_a?(Hash) && part.key?(:upload_id)
              upload_ids << part[:upload_id]
            elsif part.is_a?(String)
              part.scan(DELEGATED_IMAGE_PATTERN) do |(short_url)|
                sha1 = Upload.sha1_from_short_url(short_url)
                upload_sha1s << sha1 if sha1
              end
            end
          end
        end

        return {}, {} if upload_ids.empty? && upload_sha1s.empty?

        uploads = Upload.where(id: upload_ids).or(Upload.where(sha1: upload_sha1s)).to_a
        [uploads.index_by(&:id), uploads.index_by(&:sha1)]
      end

      def delegated_vision_content(content, context, uploads_by_id, uploads_by_sha1)
        seen_upload_ids = Set.new

        if content.is_a?(String)
          replace_delegated_image_references(content, context, seen_upload_ids, uploads_by_sha1)
        elsif content.is_a?(Array)
          content.filter_map do |part|
            if part.is_a?(Hash) && part.key?(:upload_id)
              upload = uploads_by_id[part[:upload_id].to_i]
              if upload.blank? ||
                   !DiscourseAi::Completions::UploadEncoder.supported_image_upload?(upload)
                next part
              end
              next if seen_upload_ids.include?(upload.id)

              delegated_image_handle(upload, context, seen_upload_ids)
            elsif part.is_a?(String)
              replace_delegated_image_references(part, context, seen_upload_ids, uploads_by_sha1)
            else
              part
            end
          end
        else
          content
        end
      end

      def replace_delegated_image_references(content, context, seen_upload_ids, uploads_by_sha1)
        content.gsub(DELEGATED_IMAGE_PATTERN) do |markdown|
          sha1 = Upload.sha1_from_short_url(Regexp.last_match(1))
          upload = uploads_by_sha1[sha1]
          if upload.blank? ||
               !DiscourseAi::Completions::UploadEncoder.supported_image_upload?(upload)
            next markdown
          end
          next "" if seen_upload_ids.include?(upload.id)

          delegated_image_handle(upload, context, seen_upload_ids) || "[Image unavailable]"
        end
      end

      def delegated_image_handle(upload, context, seen_upload_ids)
        return if !prompt_guardian(context).can_see_upload?(upload)

        seen_upload_ids << upload.id
        context.register_image_upload(upload.id)
        "[Image available through view_image: upload_id #{upload.id}]"
      end

      def prompt_guardian(context)
        context.image_guardian
      end

      def replace_placeholders(content, context)
        replaced =
          content.gsub(/\{(\w+)\}/) do |match|
            found = context.lookup_template_param(match[1..-2])
            found.nil? ? match : found.to_s
          end

        return replaced if !context.format_dates

        DiscourseAi::AiHelper::DateFormatter.process_date_placeholders(replaced, context.user)
      end

      def tool_instance(tool_call, bot_user:, llm:, context:, existing_tools:)
        function_id = tool_call.id
        function_name = tool_call.name
        return nil if function_name.nil?

        exposed_tools =
          if context&.runtime_tools.present? &&
               context.runtime_tools_llm_model_id == llm&.llm_model&.id
            context.runtime_tools
          else
            available_tools.reject do |tool|
              tool_name = tool.signature[:name]
              tool_name == Tools::ViewImage.name ||
                self.class.subagent_ids.present? &&
                  tool_name.to_s.casecmp(Tools::SpawnAgent.name).zero?
            end
          end
        tool_klass = exposed_tools.find { |tool| tool.signature.dig(:name) == function_name }
        return nil if tool_klass.nil?

        arguments =
          if tool_klass.signature[:json_schema]
            tool_call.parameters
          else
            coerce_tool_arguments(tool_klass.signature[:parameters].to_a, tool_call)
          end

        tool_instance =
          existing_tools.find { |t| t.name == function_name && t.tool_call_id == function_id }

        if tool_instance
          tool_instance.parameters = arguments
          tool_instance.provider_data = tool_call.provider_data if tool_instance.respond_to?(
            :provider_data=,
          )
          tool_instance
        else
          tool_klass.new(
            arguments,
            tool_call_id: function_id || function_name,
            agent_options: options[tool_klass].to_h,
            bot_user: bot_user,
            llm: llm,
            context: context,
            provider_data: tool_call.provider_data,
            agent: self,
          )
        end
      end

      def rag_tool_available?
        return false if !DiscourseAi::Embeddings.enabled?
        return false if id.blank?

        UploadReference.where(target_id: id, target_type: "AiAgent").exists?
      end

      def coerce_tool_arguments(param_defs, tool_call)
        arguments = {}
        param_defs.each do |param|
          name = param[:name]
          value = tool_call.parameters[name.to_sym]

          if param[:type] == "array" && value
            value =
              if value.is_a?(Array)
                value
              else
                begin
                  JSON.parse(value)
                rescue JSON::ParserError, TypeError
                  [value.to_s]
                end
              end
          elsif param[:type] == "string" && value
            value = strip_quotes(value).to_s
          elsif param[:type] == "integer" && value
            value = strip_quotes(value).to_i
          end

          value = nil if param[:enum] && value && !param[:enum].include?(value)

          arguments[name.to_sym] = value if value
        end
        arguments
      end

      def strip_quotes(value)
        if value.is_a?(String)
          if value.start_with?('"') && value.end_with?('"')
            value = value[1..-2]
          elsif value.start_with?("'") && value.end_with?("'")
            value = value[1..-2]
          else
            value
          end
        else
          value
        end
      end
    end
  end
end