rails-agent-stack 0.1.0

data/lib/rails_agents/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module RailsAgents
+  class Configuration
+    PROVIDERS = %i[openai anthropic openrouter grok].freeze
+
+    attr_accessor :openai_api_key, :anthropic_api_key, :openrouter_api_key, :grok_api_key,
+      :default_provider, :anthropic_auto_download_files, :anthropic_files_directory
+
+    def initialize
+      @openai_api_key = ENV["OPENAI_API_KEY"]
+      @anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+      @openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+      @grok_api_key = ENV["XAI_API_KEY"] || ENV["GROK_API_KEY"]
+      @default_provider = :openai
+      @anthropic_auto_download_files = true
+      @anthropic_files_directory = nil
+    end
+
+    def api_key_for(provider)
+      public_send(:"#{provider}_api_key")
+    end
+
+    def anthropic_files_directory!
+      return Pathname.new(@anthropic_files_directory) if @anthropic_files_directory.to_s != ""
+
+      return Rails.root.join("tmp/rails_agents/files") if defined?(Rails)
+
+      Pathname.new(Dir.mktmpdir("rails_agents_files_"))
+    end
+  end
+end

data/lib/rails_agents/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ProviderError < Error; end
+end

data/lib/rails_agents/generated_file.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  GeneratedFile = Data.define(:file_id, :filename, :content_type, :data, :path) do
+    def save(directory)
+      dir = File.expand_path(directory)
+      FileUtils.mkdir_p(dir)
+      destination = File.join(dir, filename)
+      File.binwrite(destination, data)
+      self.class.new(file_id:, filename:, content_type:, data:, path: destination)
+    end
+
+    def size = data.bytesize
+  end
+end

data/lib/rails_agents/message.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  Message = Data.define(:role, :content, :tool_calls, :tool_call_id, :raw_content) do
+    def self.system(content) = new(role: :system, content:, tool_calls: nil, tool_call_id: nil, raw_content: nil)
+    def self.user(content) = new(role: :user, content:, tool_calls: nil, tool_call_id: nil, raw_content: nil)
+    def self.assistant(content, tool_calls: nil, raw_content: nil)
+      new(role: :assistant, content:, tool_calls:, tool_call_id: nil, raw_content:)
+    end
+    def self.tool(content, tool_call_id:) = new(role: :tool, content:, tool_calls: nil, tool_call_id:, raw_content: nil)
+  end
+
+  ToolCall = Data.define(:id, :name, :arguments)
+  Usage = Data.define(:input_tokens, :output_tokens) do
+    def total = input_tokens + output_tokens
+  end
+
+  ProviderResponse = Data.define(
+    :content,
+    :tool_calls,
+    :usage,
+    :finish_reason,
+    :content_blocks,
+    :file_ids,
+    :assistant_raw_content
+  )
+end

data/lib/rails_agents/providers/anthropic/files.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module RailsAgents
+  module Providers
+    class Anthropic
+      class Files
+        FILES_BETA = "files-api-2025-04-14"
+        API_VERSION = "2023-06-01"
+
+        def initialize(api_key: RailsAgents.config.anthropic_api_key)
+          raise ConfigurationError, "Set anthropic_api_key in config/initializers/rails_agents.rb" if api_key.to_s.empty?
+          @api_key = api_key
+        end
+
+        def download(file_id)
+          metadata = retrieve(file_id)
+          response = connection.get("files/#{file_id}/content")
+          raise ProviderError, "Failed to download file #{file_id}: #{response.body}" unless response.success?
+
+          GeneratedFile.new(
+            file_id: file_id,
+            filename: metadata.fetch("filename"),
+            content_type: metadata.fetch("mime_type"),
+            data: response.body,
+            path: nil
+          )
+        end
+
+        def retrieve(file_id)
+          response = connection.get("files/#{file_id}")
+          raise ProviderError, "Failed to retrieve file #{file_id}: #{response.body}" unless response.success?
+
+          JSON.parse(response.body)
+        end
+
+        private
+
+        def connection
+          @connection ||= Faraday.new(url: "https://api.anthropic.com/v1") do |f|
+            f.headers["x-api-key"] = @api_key
+            f.headers["anthropic-version"] = API_VERSION
+            f.headers["anthropic-beta"] = FILES_BETA
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_agents/providers/anthropic.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module RailsAgents
+  module Providers
+    class Anthropic < Base
+      API_VERSION = "2023-06-01"
+
+      def initialize(api_key: RailsAgents.config.anthropic_api_key)
+        raise ConfigurationError, "Set anthropic_api_key in config/initializers/rails_agents.rb" if api_key.to_s.empty?
+        @api_key = api_key
+      end
+
+      def chat(messages:, client_tools: [], skills: nil, model:, json: false, &block)
+        anthropic_skills = skills&.anthropic_request || {}
+        body = build_body(messages:, client_tools:, skills: anthropic_skills, model:)
+
+        response = connection(anthropic_skills[:beta_headers]).post("messages", body.to_json)
+        raise ProviderError, parse_error(response) unless response.success?
+
+        parse_response(JSON.parse(response.body), json:)
+      end
+
+      def files = @files ||= Files.new(api_key: @api_key)
+
+      private
+
+      def build_body(messages:, client_tools:, skills:, model:)
+        system, conversation = split_system(messages)
+        tools = client_tools.map { |tool|
+          {name: tool[:name], description: tool[:description], input_schema: tool[:parameters]}
+        }
+        tools.concat(skills.fetch(:server_tools, []))
+
+        {
+          model: model,
+          max_tokens: 16_384,
+          system: system,
+          messages: serialize(conversation),
+          tools: tools.empty? ? nil : tools,
+          container: skills[:container]
+        }.compact
+      end
+
+      def parse_response(data, json:)
+        content_blocks = data.fetch("content")
+        text = Skills::AnthropicContent.extract_text(content_blocks)
+        text = "{}" if json && text.blank?
+        tool_blocks = content_blocks.select { |block| block["type"] == "tool_use" }
+        usage = data.fetch("usage", {})
+
+        ProviderResponse.new(
+          content: text.to_s.empty? ? nil : text,
+          tool_calls: tool_blocks.map { |block|
+            ToolCall.new(id: block["id"], name: block["name"], arguments: block["input"] || {})
+          },
+          usage: Usage.new(usage.fetch("input_tokens", 0), usage.fetch("output_tokens", 0)),
+          finish_reason: data["stop_reason"],
+          content_blocks: content_blocks,
+          file_ids: Skills::AnthropicContent.extract_file_ids(content_blocks),
+          assistant_raw_content: content_blocks
+        )
+      end
+
+      def connection(beta_headers = [])
+        headers = {
+          "x-api-key" => @api_key,
+          "anthropic-version" => API_VERSION,
+          "Content-Type" => "application/json"
+        }
+        headers["anthropic-beta"] = beta_headers.join(",") if beta_headers&.any?
+
+        Faraday.new(url: "https://api.anthropic.com/v1", headers: headers)
+      end
+
+      def split_system(messages)
+        system = messages.select { |message| message.role == :system }.map(&:content).join("\n")
+        conversation = messages.reject { |message| message.role == :system }
+        [system.to_s.empty? ? nil : system, conversation]
+      end
+
+      def serialize(messages)
+        messages.filter_map do |message|
+          case message.role
+          when :user
+            {role: "user", content: message.content}
+          when :assistant
+            if message.raw_content
+              {role: "assistant", content: message.raw_content}
+            else
+              blocks = []
+              blocks << {type: "text", text: message.content} if message.content.present?
+              message.tool_calls&.each do |tool_call|
+                blocks << {type: "tool_use", id: tool_call.id, name: tool_call.name, input: tool_call.arguments}
+              end
+              {role: "assistant", content: blocks}
+            end
+          when :tool
+            {role: "user", content: [{type: "tool_result", tool_use_id: message.tool_call_id, content: message.content}]}
+          end
+        end
+      end
+
+      def parse_error(response)
+        JSON.parse(response.body).dig("error", "message") rescue response.body
+      end
+    end
+  end
+end

data/lib/rails_agents/providers/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  module Providers
+    class Base
+    def chat(messages:, tools: [], client_tools: tools, skills: nil, model:, json: false, &block)
+      raise NotImplementedError
+    end
+    end
+
+    def self.build(name, api_key: nil)
+      kwargs = api_key.nil? ? {} : {api_key: api_key}
+
+      case name.to_sym
+      when :openai then OpenAI.new(**kwargs)
+      when :anthropic then Anthropic.new(**kwargs)
+      when :openrouter then OpenRouter.new(**kwargs)
+      when :grok then Grok.new(**kwargs)
+      else raise ConfigurationError, "Unknown provider: #{name}. Use: #{Configuration::PROVIDERS.join(', ')}"
+      end
+    end
+  end
+end

data/lib/rails_agents/providers/grok.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  module Providers
+    class Grok < OpenAICompatible
+      def initialize(api_key: RailsAgents.config.grok_api_key, base_url: "https://api.x.ai/v1")
+        super(
+          api_key: api_key,
+          base_url: base_url,
+          missing_key_message: "Set grok_api_key (or XAI_API_KEY) in config/initializers/rails_agents.rb"
+        )
+      end
+    end
+  end
+end

data/lib/rails_agents/providers/open_router.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  module Providers
+    class OpenRouter < OpenAICompatible
+      def initialize(api_key: RailsAgents.config.openrouter_api_key, base_url: "https://openrouter.ai/api/v1")
+        super(
+          api_key: api_key,
+          base_url: base_url,
+          extra_headers: {
+            "HTTP-Referer" => (defined?(Rails) ? "https://#{Rails.application.class.module_parent_name.downcase}.app" : "https://railsagents.dev"),
+            "X-Title" => (defined?(Rails) ? Rails.application.class.module_parent_name : "Rails Agents")
+          },
+          missing_key_message: "Set openrouter_api_key in config/initializers/rails_agents.rb"
+        )
+      end
+    end
+  end
+end

data/lib/rails_agents/providers/openai.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  module Providers
+    class OpenAI < OpenAICompatible
+      def initialize(api_key: RailsAgents.config.openai_api_key, base_url: "https://api.openai.com/v1")
+        super(
+          api_key: api_key,
+          base_url: base_url,
+          missing_key_message: "Set openai_api_key in config/initializers/rails_agents.rb"
+        )
+      end
+    end
+  end
+end

data/lib/rails_agents/providers/openai_compatible.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module RailsAgents
+  module Providers
+    class OpenAICompatible < Base
+      def initialize(api_key:, base_url:, extra_headers: {}, missing_key_message:)
+        raise ConfigurationError, missing_key_message if api_key.to_s.empty?
+        @api_key = api_key
+        @base_url = base_url
+        @extra_headers = extra_headers
+      end
+
+      def chat(messages:, client_tools: [], skills: nil, model:, json: false, &block)
+        tools = client_tools
+        body = {
+          model: model,
+          messages: serialize(messages),
+          tools: tools.empty? ? nil : tools.map { |t| {type: "function", function: t} }
+        }.compact
+        body[:response_format] = {type: "json_object"} if json
+
+        response = connection.post("chat/completions", body.to_json)
+        raise ProviderError, parse_error(response) unless response.success?
+
+        data = JSON.parse(response.body)
+        choice = data.fetch("choices").first
+        message = choice.fetch("message")
+        usage = data.fetch("usage", {})
+
+        ProviderResponse.new(
+          content: message["content"],
+          tool_calls: (message["tool_calls"] || []).map { |tc|
+            ToolCall.new(
+              id: tc["id"],
+              name: tc.dig("function", "name"),
+              arguments: JSON.parse(tc.dig("function", "arguments") || "{}")
+            )
+          },
+          usage: Usage.new(usage.fetch("prompt_tokens", 0), usage.fetch("completion_tokens", 0)),
+          finish_reason: choice["finish_reason"],
+          content_blocks: nil,
+          file_ids: [],
+          assistant_raw_content: nil
+        )
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: @base_url) do |f|
+          f.headers["Authorization"] = "Bearer #{@api_key}"
+          f.headers["Content-Type"] = "application/json"
+          @extra_headers.each { |key, value| f.headers[key] = value }
+        end
+      end
+
+      def serialize(messages)
+        messages.map do |msg|
+          h = {role: msg.role.to_s, content: msg.content}
+          if msg.tool_calls&.any?
+            h[:tool_calls] = msg.tool_calls.map { |tc|
+              {id: tc.id, type: "function", function: {name: tc.name, arguments: tc.arguments.to_json}}
+            }
+          end
+          h[:tool_call_id] = msg.tool_call_id if msg.tool_call_id
+          h
+        end
+      end
+
+      def parse_error(response)
+        JSON.parse(response.body).dig("error", "message") rescue response.body
+      end
+    end
+  end
+end

data/lib/rails_agents/railtie.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails_agents"
+
+module RailsAgents
+  class Railtie < Rails::Railtie
+    generators do
+      require "generators/rails_agents/install_generator"
+    end
+
+    initializer "rails_agents.autoload", before: :set_autoload_paths do |app|
+      agents_path = app.root.join("app/agents")
+      next unless agents_path.exist?
+
+      app.autoloaders.main.push_dir(agents_path.to_s)
+
+      tools_path = agents_path.join("tools")
+      app.autoloaders.main.collapse(tools_path.to_s) if tools_path.exist?
+    end
+
+    rake_tasks do
+      load "rails_agents/tasks.rb" if File.exist?(File.expand_path("tasks.rb", __dir__))
+    end
+  end
+end

data/lib/rails_agents/result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  Result = Data.define(:output, :data, :files, :messages, :usage, :success, :error, :content_blocks) do
+    def self.ok(output:, files: [], data: nil, messages: [], usage: Usage.new(0, 0), content_blocks: nil)
+      new(output:, data:, files:, messages:, usage:, success: true, error: nil, content_blocks:)
+    end
+
+    def self.fail(error:, messages: [], usage: Usage.new(0, 0), content_blocks: nil)
+      new(output: nil, data: nil, files: [], messages:, usage:, success: false, error:, content_blocks:)
+    end
+  end
+end

data/lib/rails_agents/runner.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  class Runner
+    DEFAULT_TURNS = 12
+
+    def initialize(agent_class, input:, context: {}, callbacks: {}, parse_json: false, provider: nil, model: nil)
+      @agent = agent_class
+      @input = input
+      @context = context
+      @callbacks = callbacks
+      @parse_json = parse_json
+      @skills = agent_class.skill_set
+      @tools = agent_class.tool_set
+      @provider = provider || agent_class.provider_client
+      @model_override = model
+      @server_tool_names = @skills.server_tool_names
+      @save_files_to = context[:save_files_to]
+      @messages = []
+    end
+
+    def call
+      emit(:start, agent: @agent.name, input: @input, context: @context)
+
+      @messages << Message.system(@agent.render_instructions(@context))
+      @messages << Message.user(format_input(@input))
+
+      turns = 0
+      total_usage = Usage.new(0, 0)
+      last_response = nil
+
+      loop do
+        turns += 1
+        raise Error, "Turn limit reached" if turns > @agent.max_turns
+
+        emit(:turn_start, turn: turns)
+
+        response = @provider.chat(
+          messages: @messages,
+          client_tools: @tools.definitions,
+          skills: @skills,
+          model: @model_override || @agent.resolved_model
+        )
+        last_response = response
+
+        total_usage = Usage.new(
+          total_usage.input_tokens + response.usage.input_tokens,
+          total_usage.output_tokens + response.usage.output_tokens
+        )
+
+        emit(:turn_complete, turn: turns, usage: response.usage, tool_calls: response.tool_calls.map(&:name))
+
+        client_tool_calls = response.tool_calls.reject { |tool_call| @server_tool_names.include?(tool_call.name) }
+
+        if client_tool_calls.any?
+          @messages << Message.assistant(
+            response.content,
+            tool_calls: client_tool_calls,
+            raw_content: response.assistant_raw_content
+          )
+          client_tool_calls.each do |tool_call|
+            emit(:tool_start, name: tool_call.name, arguments: tool_call.arguments)
+            result = @tools.execute(tool_call.name, tool_call.arguments)
+            emit(:tool_finish, name: tool_call.name, result: result)
+            @messages << Message.tool(result.to_json, tool_call_id: tool_call.id)
+          end
+          next
+        end
+
+        files = download_files(response.file_ids)
+        data = parse_structured_output(response.content)
+        result = Result.ok(
+          output: response.content,
+          data: data,
+          files: files,
+          messages: @messages,
+          usage: total_usage,
+          content_blocks: response.content_blocks
+        )
+        emit(:finish, result: result)
+        return result
+      end
+    rescue StandardError => e
+      result = Result.fail(error: e.message, messages: @messages, usage: Usage.new(0, 0))
+      emit(:error, error: e.message, result: result)
+      result
+    end
+
+    private
+
+    def emit(event, payload = {})
+      @callbacks[event]&.call(payload)
+      instrument(event, payload)
+    end
+
+    def instrument(event, payload)
+      return unless defined?(ActiveSupport::Notifications)
+
+      ActiveSupport::Notifications.instrument(
+        "rails_agents.#{event}",
+        payload.merge(agent: @agent.name)
+      )
+    end
+
+    def parse_structured_output(content)
+      return nil unless @parse_json
+      return nil if content.nil? || content.strip.empty?
+
+      JSON.parse(content)
+    rescue JSON::ParserError
+      extract_json_object(content)
+    end
+
+    def extract_json_object(content)
+      match = content.match(/\{.*\}/m)
+      return nil unless match
+
+      JSON.parse(match[0])
+    rescue JSON::ParserError
+      nil
+    end
+
+    def format_input(input)
+      case input
+      when String then input
+      when Hash then input.to_json
+      else input.to_s
+      end
+    end
+
+    def download_files(file_ids)
+      return [] if file_ids.empty?
+      return [] unless @agent.resolved_provider == :anthropic
+      return [] unless RailsAgents.config.anthropic_auto_download_files
+      return [] unless @provider.respond_to?(:files)
+
+      directory = @save_files_to || RailsAgents.config.anthropic_files_directory!
+      FileUtils.mkdir_p(directory)
+
+      file_ids.map do |file_id|
+        generated = @provider.files.download(file_id)
+        generated.save(directory)
+      end
+    end
+  end
+end

data/lib/rails_agents/skill.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  class Skill
+    SERVER = :server
+    PORTABLE = :portable
+    ANTHROPIC_DOCUMENT = :anthropic_document
+
+    attr_reader :name, :kind, :anthropic_tool, :anthropic_skill, :requires, :portable_tool
+
+    def initialize(name:, kind:, anthropic_tool: nil, anthropic_skill: nil, requires: [], portable_tool: nil)
+      @name = name.to_sym
+      @kind = kind
+      @anthropic_tool = anthropic_tool
+      @anthropic_skill = anthropic_skill
+      @requires = requires.map(&:to_sym)
+      @portable_tool = portable_tool
+    end
+
+    def server? = kind == SERVER
+    def portable? = kind == PORTABLE
+    def anthropic_document? = kind == ANTHROPIC_DOCUMENT
+  end
+end

data/lib/rails_agents/skill_declaration.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  SkillDeclaration = Data.define(:key, :options) do
+    def custom? = key.to_s.start_with?("skill_")
+    def name = custom? ? key.to_s : key.to_sym
+  end
+end