raix-openai-eight 1.0.1

data/lib/raix/mcp.rb

@@ -0,0 +1,255 @@
+# Simple integration layer that lets Raix classes declare an MCP server
+# with a single DSL call:
+#
+#   mcp "https://my-server.example.com/sse"
+#
+# The concern fetches the remote server's tool list (via JSON‑RPC 2.0
+# `tools/list`) and exposes each remote tool as if it were an inline
+# `function` declared with Raix::FunctionDispatch.  When the tool is
+# invoked by the model, the generated instance method forwards the
+# request to the remote server using `tools/call`, captures the result,
+# and appends the appropriate messages to the transcript so that the
+# conversation history stays consistent.
+
+require "active_support/concern"
+require "active_support/inflector"
+require "securerandom"
+require "uri"
+
+require_relative "../mcp/sse_client"
+require_relative "../mcp/stdio_client"
+
+module Raix
+  # Model Context Protocol integration for Raix
+  #
+  # Allows declaring MCP servers with a simple DSL that automatically:
+  # - Queries tools from the remote server
+  # - Exposes each tool as a function callable by LLMs
+  # - Handles transcript recording and response processing
+  module MCP
+    extend ActiveSupport::Concern
+
+    # Error raised when there's a protocol-level error in MCP communication
+    class ProtocolError < StandardError; end
+
+    JSONRPC_VERSION = "2.0".freeze
+
+    class_methods do
+      # Declare an MCP server by URL, using the SSE transport.
+      #
+      #   sse_mcp "https://server.example.com/sse",
+      #           headers: { "Authorization" => "Bearer <token>" },
+      #           only: [:get_issue]
+      #
+      def sse_mcp(url, headers: {}, only: nil, except: nil)
+        mcp(only:, except:, client: MCP::SseClient.new(url, headers:))
+      end
+
+      # Declare an MCP server by command line arguments, and environment variables  ,
+      # using the stdio transport.
+      #
+      #   stdio_mcp "docker", "run", "-i", "--rm",
+      #             "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
+      #             "ghcr.io/github/github-mcp-server",
+      #             env: { GITHUB_PERSONAL_ACCESS_TOKEN: "${input:github_token}" },
+      #             only: [:github_search]
+      #
+      def stdio_mcp(*args, env: {}, only: nil, except: nil)
+        mcp(only:, except:, client: MCP::StdioClient.new(*args, env))
+      end
+
+      # Declare an MCP server, using the given client.
+      #
+      #   mcp client: MCP::SseClient.new("https://server.example.com/sse")
+      #
+      # This will automatically:
+      #   • query `tools/list` on the server
+      #   • register each remote tool with FunctionDispatch so that the
+      #     OpenAI / OpenRouter request body includes its JSON‑Schema
+      #   • define an instance method for each tool that forwards the
+      #     call to the server and appends the proper messages to the
+      #     transcript.
+      # NOTE TO SELF: NEVER MOCK SERVER RESPONSES! THIS MUST WORK WITH REAL SERVERS!
+      def mcp(client:, only: nil, except: nil)
+        @mcp_servers ||= {}
+
+        return if @mcp_servers.key?(client.unique_key) # avoid duplicate definitions
+
+        # Fetch tools
+        tools = client.tools
+
+        if tools.empty?
+          # puts "[MCP DEBUG] No tools found from MCP server at #{url}"
+          client.close
+          return nil
+        end
+
+        # Apply filters
+        filtered_tools = if only.present?
+                           only_symbols = Array(only).map(&:to_sym)
+                           tools.select { |tool| only_symbols.include?(tool.name.to_sym) }
+                         elsif except.present?
+                           except_symbols = Array(except).map(&:to_sym)
+                           tools.reject { |tool| except_symbols.include?(tool.name.to_sym) }
+                         else
+                           tools
+                         end
+
+        # Ensure FunctionDispatch is included in the class
+        include FunctionDispatch unless included_modules.include?(FunctionDispatch)
+        # puts "[MCP DEBUG] FunctionDispatch included in #{name}"
+
+        filtered_tools.each do |tool|
+          remote_name = tool.name
+          # TODO: Revisit later whether this much context is needed in the function name
+          local_name = :"#{remote_name}_#{client.unique_key}"
+
+          description = tool.description
+          input_schema = tool.input_schema || {}
+
+          # --- register with FunctionDispatch (adds to .functions)
+          function(local_name, description, **{}) # placeholder parameters replaced next
+          latest_definition = functions.last
+          latest_definition[:parameters] = input_schema.deep_symbolize_keys || {}
+
+          # Required by OpenAI
+          latest_definition[:parameters][:properties] ||= {}
+
+          # Store the schema for type coercion
+          tool_schemas = @tool_schemas ||= {}
+          tool_schemas[local_name] = input_schema
+
+          # --- define an instance method that proxies to the server
+          define_method(local_name) do |arguments, _cache|
+            arguments ||= {}
+
+            # Coerce argument types based on the input schema
+            stored_schema = self.class.instance_variable_get(:@tool_schemas)&.dig(local_name)
+            coerced_arguments = coerce_arguments(arguments, stored_schema)
+
+            content_text = client.call_tool(remote_name, **coerced_arguments)
+            call_id = SecureRandom.uuid
+
+            # Mirror FunctionDispatch transcript behaviour
+            transcript << [
+              {
+                role: "assistant",
+                content: nil,
+                tool_calls: [
+                  {
+                    id: call_id,
+                    type: "function",
+                    function: {
+                      name: local_name.to_s,
+                      arguments: arguments.to_json
+                    }
+                  }
+                ]
+              },
+              {
+                role: "tool",
+                tool_call_id: call_id,
+                name: local_name.to_s,
+                content: content_text
+              }
+            ]
+
+            # Return the content - ChatCompletion will automatically continue
+            # the conversation after tool execution
+            content_text
+          end
+        end
+
+        # Store the URL, tools, and client for future use
+        @mcp_servers[client.unique_key] = { tools: filtered_tools, client: }
+      end
+    end
+
+    private
+
+    # Coerce argument types based on the JSON schema
+    def coerce_arguments(arguments, schema)
+      return arguments unless schema.is_a?(Hash) && schema["properties"].is_a?(Hash)
+
+      coerced = {}
+      schema["properties"].each do |key, prop_schema|
+        value = if arguments.key?(key)
+                  arguments[key]
+                elsif arguments.key?(key.to_sym)
+                  arguments[key.to_sym]
+                end
+        next if value.nil?
+
+        coerced[key] = coerce_value(value, prop_schema)
+      end
+
+      # Include any additional arguments not in the schema
+      arguments.each do |key, value|
+        key_str = key.to_s
+        coerced[key_str] = value unless coerced.key?(key_str)
+      end
+
+      coerced.with_indifferent_access
+    end
+
+    # Coerce a single value based on its schema
+    def coerce_value(value, schema)
+      return value unless schema.is_a?(Hash)
+
+      case schema["type"]
+      when "number", "integer"
+        if value.is_a?(String) && value.match?(/\A-?\d+(\.\d+)?\z/)
+          schema["type"] == "integer" ? value.to_i : value.to_f
+        else
+          value
+        end
+      when "boolean"
+        case value
+        when "true", true then true
+        when "false", false then false
+        else value
+        end
+      when "array"
+        array_value = begin
+          value.is_a?(String) ? JSON.parse(value) : value
+        rescue JSON::ParserError
+          value
+        end
+
+        # If there's an items schema, coerce each element
+        if array_value.is_a?(Array) && schema["items"]
+          array_value.map { |item| coerce_value(item, schema["items"]) }
+        else
+          array_value
+        end
+      when "object"
+        object_value = begin
+          value.is_a?(String) ? JSON.parse(value) : value
+        rescue JSON::ParserError
+          value
+        end
+
+        # If there are properties defined, coerce them recursively
+        if object_value.is_a?(Hash) && schema["properties"]
+          coerced_object = {}
+          schema["properties"].each do |prop_key, prop_schema|
+            prop_value = object_value[prop_key] || object_value[prop_key.to_sym]
+            coerced_object[prop_key] = coerce_value(prop_value, prop_schema) unless prop_value.nil?
+          end
+
+          # Include any additional properties not in the schema
+          object_value.each do |obj_key, obj_value|
+            obj_key_str = obj_key.to_s
+            coerced_object[obj_key_str] = obj_value unless coerced_object.key?(obj_key_str)
+          end
+
+          coerced_object
+        else
+          object_value
+        end
+      else
+        value
+      end
+    end
+  end
+end

data/lib/raix/message_adapters/base.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+
+module Raix
+  module MessageAdapters
+    # Transforms messages into the format expected by the OpenAI API
+    class Base
+      attr_accessor :context
+
+      delegate :cache_at, :model, to: :context
+
+      def initialize(context)
+        @context = context
+      end
+
+      def transform(message)
+        return message if message[:role].present?
+
+        if message[:function].present?
+          { role: "assistant", name: message.dig(:function, :name), content: message.dig(:function, :arguments).to_json }
+        elsif message[:result].present?
+          { role: "function", name: message[:name], content: message[:result] }
+        else
+          content(message)
+        end
+      end
+
+      protected
+
+      def content(message)
+        case message
+        in { system: content }
+          { role: "system", content: }
+        in { user: content }
+          { role: "user", content: }
+        in { assistant: content }
+          { role: "assistant", content: }
+        else
+          raise ArgumentError, "Invalid message format: #{message.inspect}"
+        end.tap do |msg|
+          # convert to anthropic multipart format if model is claude-3 and cache_at is set
+          if model.to_s.include?("anthropic/claude-3") && cache_at && msg[:content].to_s.length > cache_at.to_i
+            msg[:content] = [{ type: "text", text: msg[:content], cache_control: { type: "ephemeral" } }]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/raix/predicate.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Raix
+  # A module for handling yes/no questions using AI chat completion.
+  # When included in a class, it provides methods to define handlers for
+  # yes and no responses. All handlers are optional. Any response that
+  # does not begin with "yes, " or "no, " will be considered a maybe.
+  #
+  # @example
+  #   class Question
+  #     include Raix::Predicate
+  #
+  #     yes? do |explanation|
+  #       puts "Yes: #{explanation}"
+  #     end
+  #
+  #     no? do |explanation|
+  #       puts "No: #{explanation}"
+  #     end
+  #
+  #     maybe? do |explanation|
+  #       puts "Maybe: #{explanation}"
+  #     end
+  #   end
+  #
+  #   question = Question.new
+  #   question.ask("Is Ruby a programming language?")
+  module Predicate
+    extend ActiveSupport::Concern
+    include ChatCompletion
+
+    def ask(question, openai: false)
+      raise "Please define a yes and/or no block" if self.class.yes_block.nil? && self.class.no_block.nil?
+
+      transcript << { system: "Always answer 'Yes, ', 'No, ', or 'Maybe, ' followed by a concise explanation!" }
+      transcript << { user: question }
+
+      chat_completion(openai:).tap do |response|
+        if response.downcase.start_with?("yes,")
+          instance_exec(response, &self.class.yes_block) if self.class.yes_block
+        elsif response.downcase.start_with?("no,")
+          instance_exec(response, &self.class.no_block) if self.class.no_block
+        elsif self.class.maybe_block
+          instance_exec(response, &self.class.maybe_block)
+        else
+          puts "[Raix::Predicate] Unhandled response: #{response}"
+        end
+      end
+    end
+
+    # Class methods added to the including class
+    module ClassMethods
+      attr_reader :yes_block, :no_block, :maybe_block
+
+      def yes?(&block)
+        @yes_block = block
+      end
+
+      def no?(&block)
+        @no_block = block
+      end
+
+      def maybe?(&block)
+        @maybe_block = block
+      end
+    end
+  end
+end

data/lib/raix/prompt_declarations.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+# This module provides a way to chain prompts and handle
+# user responses in a serialized manner, with support for
+# functions if the FunctionDispatch module is also included.
+module Raix
+  # The PromptDeclarations module provides a way to chain prompts and handle
+  # user responses in a serialized manner, with support for
+  # functions if the FunctionDispatch module is also included.
+  module PromptDeclarations
+    extend ActiveSupport::Concern
+
+    module ClassMethods # rubocop:disable Style/Documentation
+      # Adds a prompt to the list of prompts. At minimum, provide a `text` or `call` parameter.
+      #
+      # @param system [Proc] A lambda that generates the system message.
+      # @param call [ChatCompletion] A callable class that includes ChatCompletion. Will be passed a context object when initialized.
+      # @param text Accepts 1) a lambda that returns the prompt text, 2) a string, or 3) a symbol that references a method.
+      # @param stream [Proc] A lambda stream handler
+      # @param success [Proc] The block of code to execute when the prompt is answered.
+      # @param params [Hash] Additional parameters for the completion API call
+      # @param if [Proc] A lambda that determines if the prompt should be executed.
+      def prompt(system: nil, call: nil, text: nil, stream: nil, success: nil, params: {}, if: nil, unless: nil, until: nil)
+        name = Digest::SHA256.hexdigest(text.inspect)[0..7]
+        prompts << OpenStruct.new({ name:, system:, call:, text:, stream:, success:, if:, unless:, until:, params: })
+
+        define_method(name) do |response|
+          return response if success.nil?
+          return send(success, response) if success.is_a?(Symbol)
+
+          instance_exec(response, &success)
+        end
+      end
+
+      def prompts
+        @prompts ||= []
+      end
+    end
+
+    attr_reader :current_prompt, :last_response
+
+    MAX_LOOP_COUNT = 5
+
+    # Executes the chat completion process based on the class-level declared prompts.
+    # The response to each prompt is added to the transcript automatically and returned.
+    #
+    # Raises an error if there are not enough prompts defined.
+    #
+    # Uses system prompt in following order of priority:
+    #   - system lambda specified in the prompt declaration
+    #   - system_prompt instance method if defined
+    #   - system_prompt class-level declaration if defined
+    #
+    #  Prompts require a text lambda to be defined at minimum.
+    #  TODO: shortcut syntax passes just a string prompt if no other options are needed.
+    #
+    # @raise [RuntimeError] If no prompts are defined.
+    #
+    # @param prompt [String] The prompt to use for the chat completion.
+    # @param params [Hash] Parameters for the chat completion.
+    # @param raw [Boolean] Whether to return the raw response.
+    #
+    # TODO: SHOULD NOT HAVE A DIFFERENT INTERFACE THAN PARENT
+    def chat_completion(prompt = nil, params: {}, raw: false, openai: false)
+      raise "No prompts defined" unless self.class.prompts.present?
+
+      loop_count = 0
+
+      current_prompts = self.class.prompts.clone
+
+      while (@current_prompt = current_prompts.shift)
+        next if @current_prompt.if.present? && !instance_exec(&@current_prompt.if)
+        next if @current_prompt.unless.present? && instance_exec(&@current_prompt.unless)
+
+        input = case current_prompt.text
+                when Proc
+                  instance_exec(&current_prompt.text)
+                when String
+                  current_prompt.text
+                when Symbol
+                  send(current_prompt.text)
+                else
+                  last_response.presence || prompt
+                end
+
+        if current_prompt.call.present?
+          current_prompt.call.new(self).call(input).tap do |response|
+            if response.present?
+              transcript << { assistant: response }
+              @last_response = send(current_prompt.name, response)
+            end
+          end
+        else
+          __system_prompt = instance_exec(&current_prompt.system) if current_prompt.system.present? # rubocop:disable Lint/UnderscorePrefixedVariableName
+          __system_prompt ||= system_prompt if respond_to?(:system_prompt)
+          __system_prompt ||= self.class.system_prompt.presence
+          transcript << { system: __system_prompt } if __system_prompt
+          transcript << { user: instance_exec(&current_prompt.text) } # text is required
+
+          params = current_prompt.params.merge(params)
+
+          # set the stream if necessary
+          self.stream = instance_exec(&current_prompt.stream) if current_prompt.stream.present?
+
+          execute_ai_request(params:, raw:, openai:, transcript:, loop_count:)
+        end
+
+        next unless current_prompt.until.present? && !instance_exec(&current_prompt.until)
+
+        if loop_count >= MAX_LOOP_COUNT
+          warn "Max loop count reached in chat_completion. Forcing return."
+
+          return last_response
+        else
+          current_prompts.unshift(@current_prompt) # put it back at the front
+          loop_count += 1
+        end
+      end
+
+      last_response
+    end
+
+    def execute_ai_request(params:, raw:, openai:, transcript:, loop_count:)
+      chat_completion_from_superclass(params:, raw:, openai:).then do |response|
+        transcript << { assistant: response }
+        @last_response = send(current_prompt.name, response)
+        self.stream = nil # clear it again so it's not used for the next prompt
+      end
+    rescue StandardError => e
+      # Bubbles the error up the stack if no loops remain
+      raise e if loop_count >= MAX_LOOP_COUNT
+
+      sleep 1 # Wait before continuing
+    end
+
+    # Returns the model parameter of the current prompt or the default model.
+    #
+    # @return [Object] The model parameter of the current prompt or the default model.
+    def model
+      @current_prompt.params[:model] || super
+    end
+
+    # Returns the temperature parameter of the current prompt or the default temperature.
+    #
+    # @return [Float] The temperature parameter of the current prompt or the default temperature.
+    def temperature
+      @current_prompt.params[:temperature] || super
+    end
+
+    # Returns the max_tokens parameter of the current prompt or the default max_tokens.
+    #
+    # @return [Integer] The max_tokens parameter of the current prompt or the default max_tokens.
+    def max_tokens
+      @current_prompt.params[:max_tokens] || super
+    end
+
+    protected
+
+    # workaround for super.chat_completion, which is not available in ruby
+    def chat_completion_from_superclass(*, **kargs)
+      method(:chat_completion).super_method.call(*, **kargs)
+    end
+  end
+end

data/lib/raix/response_format.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/deep_dup"
+require "active_support/core_ext/string/filters"
+
+module Raix
+  # Handles the formatting of responses for AI interactions.
+  #
+  # This class is responsible for converting input data into a JSON schema
+  # that can be used to structure and validate AI responses. It supports
+  # nested structures and arrays, ensuring that the output conforms to
+  # the expected format for AI model interactions.
+  #
+  # @example
+  #   input = { name: { type: "string" }, age: { type: "integer" } }
+  #   format = ResponseFormat.new("PersonInfo", input)
+  #   schema = format.to_schema
+  #
+  # @attr_reader [String] name The name of the response format
+  # @attr_reader [Hash] input The input data to be formatted
+  class ResponseFormat
+    def initialize(name, input)
+      @name = name
+      @input = input
+    end
+
+    def to_json(*)
+      JSON.pretty_generate(to_schema)
+    end
+
+    def to_schema
+      {
+        type: "json_schema",
+        json_schema: {
+          name: @name,
+          schema: {
+            type: "object",
+            properties: decode(@input.deep_dup),
+            required: @input.keys,
+            additionalProperties: false
+          },
+          strict: true
+        }
+      }
+    end
+
+    private
+
+    def decode(input)
+      {}.tap do |response|
+        case input
+        when Array
+          response[:type] = "array"
+
+          if input.size == 1 && input.first.is_a?(String)
+            response[:items] = { type: input.first }
+          else
+            properties = {}
+            input.each { |item| properties.merge!(decode(item)) }
+            response[:items] = {
+              type: "object",
+              properties:,
+              required: properties.keys.select { |key| properties[key].delete(:required) },
+              additionalProperties: false
+            }
+          end
+        when Hash
+          input.each do |key, value|
+            response[key] = if value.is_a?(Hash) && value.key?(:type)
+                              value
+                            else
+                              decode(value)
+                            end
+          end
+        else
+          raise "Invalid input"
+        end
+      end
+    end
+  end
+end

data/lib/raix/version.rb

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

data/lib/raix.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "raix/version"
+require_relative "raix/configuration"
+require_relative "raix/chat_completion"
+require_relative "raix/function_dispatch"
+require_relative "raix/prompt_declarations"
+require_relative "raix/predicate"
+require_relative "raix/response_format"
+require_relative "raix/mcp"
+
+# The Raix module provides configuration options for the Raix gem.
+module Raix
+  class << self
+    attr_writer :configuration
+  end
+
+  # Returns the current configuration instance.
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Configures the Raix gem using a block.
+  def self.configure
+    yield(configuration)
+  end
+end

data/raix-openai-eight.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/raix/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "raix-openai-eight"
+  spec.version = Raix::VERSION
+  spec.authors = ["Paulo Arruda"]
+  spec.email = ["parrudaj@gmail.com"]
+
+  spec.summary = "Ruby AI eXtensions"
+  spec.homepage = "https://github.com/parrudaj/raix-openai-eight"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.2"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/parrudaj/raix-openai-eight"
+  spec.metadata["changelog_uri"] = "https://github.com/parrudaj/raix-openai-eight/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 6.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+  spec.add_dependency "open_router", "~> 0.2"
+  spec.add_dependency "ostruct"
+  spec.add_dependency "ruby-openai", "~> 8.1"
+end

data/sig/raix.rbs

@@ -0,0 +1,4 @@
+module Raix
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end