rails-agent-stack 0.1.0

data/lib/rails_agents/skill_set.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  class SkillSet
+    FILES_BETA = "files-api-2025-04-14"
+
+    attr_reader :provider, :entries, :custom_skills, :declarations
+
+    def initialize(declarations:, provider:)
+      @provider = provider.to_sym
+      @declarations = declarations
+      @custom_skills = []
+      @options_by_name = declarations.to_h { |declaration|
+        key = declaration.custom? ? declaration.key.to_s : declaration.name.to_s
+        [key, declaration.options]
+      }
+      @entries = expand(resolve)
+    end
+
+    def server_tool_names
+      entries.select(&:server?).filter_map { |entry| entry.anthropic_tool&.dig(:name) }
+    end
+
+    def portable_tool_classes
+      return [] unless use_portable?
+
+      entries.filter_map(&:portable_tool)
+    end
+
+    def anthropic_document_skills?
+      entries.any?(&:anthropic_document?) || custom_skills.any?
+    end
+
+    def anthropic_request
+      return {} unless provider == :anthropic
+
+      tools = entries.filter_map { |entry| anthropic_tool_for(entry) }
+      skills = entries.filter_map { |entry| anthropic_skill_for(entry) } + custom_skills
+      headers = anthropic_beta_headers(tools:, skills:)
+
+      {
+        server_tools: tools.uniq { |tool| tool[:name] },
+        container: (skills.empty? ? nil : {skills: skills}),
+        beta_headers: headers
+      }
+    end
+
+    def validate!
+      if custom_skills.any? && provider != :anthropic
+        raise ConfigurationError, "Custom Anthropic skills require provider :anthropic"
+      end
+
+      declarations.each do |declaration|
+        next if declaration.custom?
+        next if Skills::Registry.fetch(declaration.name)
+
+        raise ConfigurationError, "Unknown skill: #{declaration.key}. See RailsAgents::Skills::Registry::ENTRIES"
+      end
+
+      entries.each do |entry|
+        next if provider == :anthropic
+        next if entry.portable_tool
+
+        raise ConfigurationError,
+          "Skill :#{entry.name} requires provider :anthropic. " \
+          "Portable skills: #{Skills::Registry::PORTABLE_SKILL_IDS.join(', ')}"
+      end
+    end
+
+    private
+
+    def use_portable?
+      provider != :anthropic
+    end
+
+    def resolve
+      declarations.filter_map do |declaration|
+        if declaration.custom?
+          @custom_skills << anthropic_custom_skill(declaration)
+          next
+        end
+
+        Skills::Registry.fetch(declaration.name)
+      end
+    end
+
+    def expand(resolved)
+      expanded = resolved.dup
+      resolved.each do |entry|
+        entry.requires.each do |required|
+          dependency = Skills::Registry.fetch(required)
+          expanded << dependency unless expanded.any? { |existing| existing.name == dependency.name }
+        end
+      end
+      expanded.uniq { |entry| entry.name }
+    end
+
+    def anthropic_tool_for(entry)
+      return unless entry.anthropic_tool
+
+      tool = entry.anthropic_tool.dup
+      options = @options_by_name.fetch(entry.name.to_s, {})
+      merge_tool_options!(tool, options)
+      tool
+    end
+
+    def anthropic_skill_for(entry)
+      return unless entry.anthropic_skill
+
+      skill = entry.anthropic_skill.dup
+      options = @options_by_name.fetch(entry.name.to_s, {})
+      skill[:version] = options.fetch(:version, skill[:version] || "latest")
+      skill
+    end
+
+    def anthropic_custom_skill(declaration)
+      {
+        type: "custom",
+        skill_id: declaration.key.to_s,
+        version: declaration.options.fetch(:version, "latest")
+      }
+    end
+
+    def merge_tool_options!(tool, options)
+      allowed = %i[max_uses allowed_domains blocked_domains user_location response_inclusion]
+      options.each do |key, value|
+        tool[key] = value if allowed.include?(key.to_sym)
+      end
+    end
+
+    def anthropic_beta_headers(tools:, skills:)
+      headers = []
+      headers << "code-execution-2025-08-25" if skills.any? || tools.any? { |tool| tool[:name] == "code_execution" }
+      headers << "skills-2025-10-02" if skills.any?
+      headers << FILES_BETA if skills.any? || tools.any? { |tool| tool[:name] == "code_execution" }
+      headers
+    end
+  end
+end

data/lib/rails_agents/skills/anthropic_content.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  module Skills
+    module AnthropicContent
+      module_function
+
+      def extract_text(blocks)
+        Array(blocks).select { |block| block["type"] == "text" }.map { |block| block["text"] }.join("\n").strip
+      end
+
+      def extract_file_ids(blocks)
+        ids = []
+        walk(blocks) { |node| ids << node["file_id"] if node.is_a?(Hash) && !node["file_id"].to_s.empty? }
+        ids.uniq
+      end
+
+      def walk(object)
+        case object
+        when Array
+          object.each { |item| walk(item) { |node| yield node } }
+        when Hash
+          yield object
+          object.each_value { |value| walk(value) { |node| yield node } }
+        end
+      end
+    end
+  end
+end

data/lib/rails_agents/skills/portable/web_fetch.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module RailsAgents
+  module Skills
+    module Portable
+      class WebFetch < Tool
+        description "Fetch and read the text content of a web page"
+        param :url, :string, description: "URL to fetch"
+
+        def call(url:)
+          response = Faraday.get(url, nil, {"User-Agent" => "RailsAgents/1.0"})
+          return {error: "Fetch failed", url: url, status: response.status} unless response.success?
+
+          text = response.body.gsub(/<script.*?>.*?<\/script>/m, "")
+            .gsub(/<style.*?>.*?<\/style>/m, "")
+            .gsub(/<[^>]+>/, " ")
+            .gsub(/\s+/, " ")
+            .strip
+
+          {url: url, content: text[0, 8_000]}
+        rescue StandardError => e
+          {error: e.message, url: url}
+        end
+      end
+    end
+  end
+end

data/lib/rails_agents/skills/portable/web_search.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module RailsAgents
+  module Skills
+    module Portable
+      class WebSearch < Tool
+        SEARCH_URL = "https://html.duckduckgo.com/html/"
+
+        description "Search the web for current information"
+        param :query, :string, description: "Search query"
+
+        def call(query:)
+          response = Faraday.get(SEARCH_URL, {q: query}, {"User-Agent" => "RailsAgents/1.0"})
+          return {error: "Search failed", query: query} unless response.success?
+
+          titles = response.body.scan(/class="result__a"[^>]*>(.*?)<\/a>/).first(5).map { |match|
+            match.first.gsub(/<[^>]+>/, "").strip
+          }.reject(&:empty?)
+
+          urls = response.body.scan(/class="result__url"[^>]*>(.*?)<\/a>/).first(5).map { |match|
+            match.first.gsub(/<[^>]+>/, "").strip
+          }
+
+          {query: query, results: titles.zip(urls).map { |title, url| {title:, url:} }}
+        rescue StandardError => e
+          {error: e.message, query: query}
+        end
+      end
+    end
+  end
+end

data/lib/rails_agents/skills/registry.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  module Skills
+    class Registry
+      ENTRIES = {
+        web_search: Skill.new(
+          name: :web_search,
+          kind: Skill::SERVER,
+          anthropic_tool: {type: "web_search_20260209", name: "web_search"},
+          portable_tool: Portable::WebSearch
+        ),
+        web_fetch: Skill.new(
+          name: :web_fetch,
+          kind: Skill::SERVER,
+          anthropic_tool: {type: "web_fetch_20260309", name: "web_fetch"},
+          portable_tool: Portable::WebFetch
+        ),
+        code_execution: Skill.new(
+          name: :code_execution,
+          kind: Skill::SERVER,
+          anthropic_tool: {type: "code_execution_20250825", name: "code_execution"}
+        ),
+        memory: Skill.new(
+          name: :memory,
+          kind: Skill::SERVER,
+          anthropic_tool: {type: "memory_20250818", name: "memory"}
+        ),
+        pptx: Skill.new(
+          name: :pptx,
+          kind: Skill::ANTHROPIC_DOCUMENT,
+          anthropic_skill: {type: "anthropic", skill_id: "pptx", version: "latest"},
+          requires: [:code_execution]
+        ),
+        xlsx: Skill.new(
+          name: :xlsx,
+          kind: Skill::ANTHROPIC_DOCUMENT,
+          anthropic_skill: {type: "anthropic", skill_id: "xlsx", version: "latest"},
+          requires: [:code_execution]
+        ),
+        docx: Skill.new(
+          name: :docx,
+          kind: Skill::ANTHROPIC_DOCUMENT,
+          anthropic_skill: {type: "anthropic", skill_id: "docx", version: "latest"},
+          requires: [:code_execution]
+        ),
+        pdf: Skill.new(
+          name: :pdf,
+          kind: Skill::ANTHROPIC_DOCUMENT,
+          anthropic_skill: {type: "anthropic", skill_id: "pdf", version: "latest"},
+          requires: [:code_execution]
+        )
+      }.freeze
+
+      ANTHROPIC_SKILL_IDS = %i[pptx xlsx docx pdf].freeze
+      PORTABLE_SKILL_IDS = %i[web_search web_fetch].freeze
+
+      def self.fetch(name)
+        ENTRIES[name.to_sym]
+      end
+
+      def self.known?(name)
+        name.to_s.start_with?("skill_") || ENTRIES.key?(name.to_sym)
+      end
+    end
+  end
+end

data/lib/rails_agents/tool.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module RailsAgents
+  class Tool
+    class << self
+      attr_reader :description_text, :parameters
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@parameters, (parameters || {}).dup)
+      end
+
+      def description(text = nil)
+        return @description_text if text.nil?
+        @description_text = text
+      end
+
+      def param(name, type, required: true, description: nil)
+        @parameters ||= {}
+        @parameters[name.to_sym] = {type: type.to_sym, required:, description:}
+      end
+
+      def tool_name
+        name.split("::").last.gsub(/Tool$/, "").underscore
+      end
+
+      def definition
+        {
+          name: tool_name,
+          description: description_text,
+          parameters: {
+            type: "object",
+            properties: parameters.transform_values { |p|
+              {type: p[:type].to_s, description: p[:description]}.compact
+            },
+            required: parameters.select { |_, p| p[:required] }.keys.map(&:to_s)
+          }
+        }
+      end
+    end
+
+    def call(**kwargs)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/rails_agents/tool_set.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  class ToolSet
+    def initialize(*tools)
+      @tools = tools.flatten.compact.map { |t| resolve(t) }
+    end
+
+    def self.from_directory(path = nil)
+      path ||= (defined?(::Rails) && ::Rails.respond_to?(:root) ? ::Rails.root.join("app/agents/tools") : nil)
+      return new unless path && Dir.exist?(path)
+
+      classes = Dir.glob("#{path}/**/*.rb").filter_map do |file|
+        require_dependency file if defined?(Rails)
+        const_name = file.delete_prefix("#{path}/").delete_suffix(".rb").camelize
+        const_name.safe_constantize
+      end
+      new(*classes)
+    end
+
+    def self.use(*tools) = new(*tools)
+
+    def resolve(klass)
+      case klass
+      when Class
+        klass < Tool ? klass : klass
+      when String, Symbol
+        resolved = klass.to_s.camelize.constantize
+        raise Error, "#{klass} is not a RailsAgents::Tool" unless resolved < Tool
+        resolved
+      else
+        klass
+      end
+    end
+
+    def definitions = @tools.map(&:definition)
+    def find(name) = @tools.find { |t| t.tool_name == name.to_s }
+    def execute(name, arguments)
+      tool_class = find(name)
+      raise Error, "Unknown tool: #{name}" unless tool_class
+      tool_class.new.call(**arguments.transform_keys(&:to_sym))
+    end
+
+    def +(other) = self.class.new(*@tools, *other.instance_variable_get(:@tools))
+  end
+end

data/lib/rails_agents/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  VERSION = "0.1.0"
+end

data/lib/rails_agents.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "json"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/generators")
+# Bundler auto-requires gem "rails-agent-stack" as rails/agent/stack —
+# keep that shim off Zeitwerk so it does not define a stub Rails module.
+loader.ignore("#{__dir__}/rails")
+loader.inflector.inflect(
+  "openai" => "OpenAI",
+  "openai_compatible" => "OpenAICompatible",
+  "anthropic" => "Anthropic",
+  "open_router" => "OpenRouter"
+)
+loader.setup
+
+require_relative "rails_agents/message"
+require_relative "rails_agents/result"
+require_relative "rails_agents/error"
+require_relative "rails_agents/skill_declaration"
+require_relative "rails_agents/generated_file"
+require_relative "rails_agents/providers/openai_compatible"
+
+module RailsAgents
+  class << self
+    attr_writer :config
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def tools(*classes)
+      ToolSet.use(*classes)
+    end
+  end
+end
+
+require_relative "rails_agents/version"

data/rails-agent-stack.gemspec

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails_agents/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rails-agent-stack"
+  spec.version = RailsAgents::VERSION
+  spec.authors = ["Tiny Bubble Company"]
+  spec.email = ["hello@tinybubble.company"]
+
+  spec.summary = "Dead-simple AI agents for Rails — speed to production, not framework noise"
+  spec.description = <<~DESC.gsub(/\s+/, " ").strip
+    Rails Agents (gem: rails-agent-stack) is the simplest way to build AI agents
+    in Ruby on Rails. Define an LLM agent as a plain Ruby class, attach your app
+    code as tools, add skills like web search or spreadsheets, and call .run —
+    minutes to production, not days of framework setup.
+
+    Built for developers searching for Rails AI agents, Ruby LLM agents,
+    OpenAI / Anthropic / Claude / GPT tool-calling agents, OpenRouter and
+    Grok (xAI) integrations, agentic workflows, RAG helpers, and a lighter
+    alternative to RubyLLM, LangChain, or rolling your own multi-turn tool loop.
+
+    One mental model: RailsAgents::Agent. No dashboards, no cloud lock-in,
+    no agent lifecycle UI — just provider, model, description, tools, and skills.
+  DESC
+
+  spec.homepage = "https://tiny-bubble-company.github.io/rails-agents/"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/Tiny-Bubble-Company/rails-agents",
+    "changelog_uri" => "https://github.com/Tiny-Bubble-Company/rails-agents/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://tiny-bubble-company.github.io/rails-agents/",
+    "bug_tracker_uri" => "https://github.com/Tiny-Bubble-Company/rails-agents/issues",
+    "rubygems_mfa_required" => "true",
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["{app,lib}/**/*", "README.md", "CHANGELOG.md", "MIT-LICENSE", "rails-agent-stack.gemspec"]
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", ">= 2.9", "< 3"
+  spec.add_dependency "rails", ">= 7.1", "< 9"
+  spec.add_dependency "zeitwerk", ">= 2.6", "< 3"
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: rails-agent-stack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tiny Bubble Company
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: 'Rails Agents (gem: rails-agent-stack) is the simplest way to build AI
+  agents in Ruby on Rails. Define an LLM agent as a plain Ruby class, attach your
+  app code as tools, add skills like web search or spreadsheets, and call .run — minutes
+  to production, not days of framework setup. Built for developers searching for Rails
+  AI agents, Ruby LLM agents, OpenAI / Anthropic / Claude / GPT tool-calling agents,
+  OpenRouter and Grok (xAI) integrations, agentic workflows, RAG helpers, and a lighter
+  alternative to RubyLLM, LangChain, or rolling your own multi-turn tool loop. One
+  mental model: RailsAgents::Agent. No dashboards, no cloud lock-in, no agent lifecycle
+  UI — just provider, model, description, tools, and skills.'
+email:
+- hello@tinybubble.company
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- lib/generators/rails_agents/install_generator.rb
+- lib/generators/rails_agents/templates/initializer.rb
+- lib/rails/agent/stack.rb
+- lib/rails_agents.rb
+- lib/rails_agents/agent.rb
+- lib/rails_agents/configuration.rb
+- lib/rails_agents/error.rb
+- lib/rails_agents/generated_file.rb
+- lib/rails_agents/message.rb
+- lib/rails_agents/providers/anthropic.rb
+- lib/rails_agents/providers/anthropic/files.rb
+- lib/rails_agents/providers/base.rb
+- lib/rails_agents/providers/grok.rb
+- lib/rails_agents/providers/open_router.rb
+- lib/rails_agents/providers/openai.rb
+- lib/rails_agents/providers/openai_compatible.rb
+- lib/rails_agents/railtie.rb
+- lib/rails_agents/result.rb
+- lib/rails_agents/runner.rb
+- lib/rails_agents/skill.rb
+- lib/rails_agents/skill_declaration.rb
+- lib/rails_agents/skill_set.rb
+- lib/rails_agents/skills/anthropic_content.rb
+- lib/rails_agents/skills/portable/web_fetch.rb
+- lib/rails_agents/skills/portable/web_search.rb
+- lib/rails_agents/skills/registry.rb
+- lib/rails_agents/tool.rb
+- lib/rails_agents/tool_set.rb
+- lib/rails_agents/version.rb
+- rails-agent-stack.gemspec
+homepage: https://tiny-bubble-company.github.io/rails-agents/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://tiny-bubble-company.github.io/rails-agents/
+  source_code_uri: https://github.com/Tiny-Bubble-Company/rails-agents
+  changelog_uri: https://github.com/Tiny-Bubble-Company/rails-agents/blob/main/CHANGELOG.md
+  documentation_uri: https://tiny-bubble-company.github.io/rails-agents/
+  bug_tracker_uri: https://github.com/Tiny-Bubble-Company/rails-agents/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Dead-simple AI agents for Rails — speed to production, not framework noise
+test_files: []