raix 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd88f295667264948d2710fb7eb0bcd74e5ab0177e76678314c34958e79fa6bd
-  data.tar.gz: b86495b4b67c5259915a7ef20502005d90ededf6be991821703d1d83e876c572
+  metadata.gz: 50d0de4d7ec7fdd83776e539dbed2cc73ba3097c96752050eb768163dd5f510a
+  data.tar.gz: c82955632f789a0683e30553ecc8aef8b2f96aa4bc003e0b2e12953e6698adf9
 SHA512:
-  metadata.gz: cf1982b065312860c046a363486169a3d4572b65bd5ded3e82e270e3cbb689a173d6ff94cbcc897d6d8e5f27ef7e6558193ea3b266c18cc5bd1a8f2ca54fa6cd
-  data.tar.gz: 58eb7f54eb7d3a2656dbdd3e44a977c04b1dfb5ef5f7bd549ece96ecce9a931007edea5d364f189a1916883838c6a674e794799365914a1a5cab2402994da5f1
+  metadata.gz: 48977e0c2265105f22da2c1508a1aced37337ab1a914c7297bca4995cc94d6839708a51edb9f63222e4531bc0dccce305448ad70f78a858f30d7f581ae289114
+  data.tar.gz: c52f4078787b2570a6a11eb92e0a0f6172a09e083219d0b8562349fee4efc14012674e25591ef2839e41fd2675bfc834361bf1a64d3b74614854ce944b6cf8ab

data/CHANGELOG.md

@@ -18,3 +18,6 @@
 
 ## [0.4.2] - 2024-11-05
 - adds support for [Predicted Outputs](https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs) with the `prediction` option for OpenAI
+
+## [0.4.3] - 2024-11-11
+- adds support for `Predicate` module

data/Gemfile

@@ -22,3 +22,8 @@ group :development do
   gem "sorbet"
   gem "tapioca", require: false
 end
+
+group :test do
+  gem "vcr"
+  gem "webmock"
+end

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    raix (0.4.2)
+    raix (0.4.3)
       activesupport (>= 6.0)
       open_router (~> 0.2)
+      ruby-openai (~> 7.0)
 
 GEM
   remote: https://rubygems.org/
@@ -18,6 +19,8 @@ GEM
       minitest (>= 5.1)
       mutex_m
       tzinfo (~> 2.0)
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
     backport (1.2.0)
     base64 (0.2.0)
@@ -26,6 +29,8 @@ GEM
     coderay (1.1.3)
     concurrent-ruby (1.3.3)
     connection_pool (2.4.1)
+    crack (0.4.5)
+      rexml
     diff-lcs (1.5.1)
     dotenv (3.1.2)
     drb (2.2.1)
@@ -57,6 +62,7 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
+    hashdiff (1.0.1)
     i18n (1.14.5)
       concurrent-ruby (~> 1.0)
     jaro_winkler (1.6.0)
@@ -98,6 +104,7 @@ GEM
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
+    public_suffix (5.0.5)
     racc (1.7.3)
     rainbow (3.1.1)
     rake (13.2.0)
@@ -191,6 +198,11 @@ GEM
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.5.0)
     uri (0.13.0)
+    vcr (6.2.0)
+    webmock (3.18.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
     yard (0.9.36)
     yard-sorbet (0.8.1)
       sorbet-runtime (>= 0.5)
@@ -217,6 +229,8 @@ DEPENDENCIES
   solargraph-rails (~> 0.2.0.pre)
   sorbet
   tapioca
+  vcr
+  webmock
 
 BUNDLED WITH
    2.4.12

data/Guardfile

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# NOTE: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w[erb haml slim])
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.call("routing/#{m[1]}_routing"),
+      rspec.spec.call("controllers/#{m[1]}_controller"),
+      rspec.spec.call("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.call("features/#{m[1]}") }
+  watch(rails.layouts)       { |m| rspec.spec.call("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  end
+end

data/README.md

@@ -238,6 +238,77 @@ Notably, Olympia does not use the `FunctionDispatch` module in its primary conve
 
 Streaming of the AI's response to the end user is handled by the `ReplyStream` class, passed to the final prompt declaration as its `stream` parameter. [Patterns of Application Development Using AI](https://leanpub.com/patterns-of-application-development-using-ai) devotes a whole chapter to describing how to write your own `ReplyStream` class.
 
+## Predicate Module
+
+The `Raix::Predicate` module provides a simple way to handle yes/no/maybe questions using AI chat completion. It allows you to define blocks that handle different types of responses with their explanations. It is one of the concrete patterns described in the "Discrete Components" chapter of [Patterns of Application Development Using AI](https://leanpub.com/patterns-of-application-development-using-ai).
+
+### Usage
+
+Include the `Raix::Predicate` module in your class and define handlers using block syntax:
+
+```ruby
+class Question
+  include Raix::Predicate
+
+  yes? do |explanation|
+    puts "Affirmative: #{explanation}"
+  end
+
+  no? do |explanation|
+    puts "Negative: #{explanation}"
+  end
+
+  maybe? do |explanation|
+    puts "Uncertain: #{explanation}"
+  end
+end
+
+question = Question.new
+question.ask("Is Ruby a programming language?")
+# => Affirmative: Yes, Ruby is a dynamic, object-oriented programming language...
+```
+
+### Features
+
+- Define handlers for yes, no, and/or maybe responses using the declarative class level block syntax.
+- At least one handler (yes, no, or maybe) must be defined.
+- Handlers receive the full AI response including explanation as an argument.
+- Responses always start with "Yes, ", "No, ", or "Maybe, " followed by an explanation.
+- Make sure to ask a question that can be answered with yes, no, or maybe (otherwise the results are indeterminate).
+
+### Example with Single Handler
+
+You can define only the handlers you need:
+
+```ruby
+class SimpleQuestion
+  include Raix::Predicate
+
+  # Only handle positive responses
+  yes? do |explanation|
+    puts "✅ #{explanation}"
+  end
+end
+
+question = SimpleQuestion.new
+question.ask("Is 2 + 2 = 4?")
+# => ✅ Yes, 2 + 2 equals 4, this is a fundamental mathematical fact.
+```
+
+### Error Handling
+
+The module will raise a RuntimeError if you attempt to ask a question without defining any response handlers:
+
+```ruby
+class InvalidQuestion
+  include Raix::Predicate
+end
+
+question = InvalidQuestion.new
+question.ask("Any question")
+# => RuntimeError: Please define a yes and/or no block
+```
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/lib/raix/chat_completion.rb

@@ -12,10 +12,22 @@ module Raix
   # with the OpenRouter Chat Completion API via its client. The module includes a few
   # methods that allow you to build a transcript of messages and then send them to
   # the API for completion. The API will return a response that you can use however
-  # you see fit. If the response includes a function call, the module will dispatch
-  # the function call and return the result. Which implies that function calls need
-  # to be defined on the class that includes this module. (Note: You should probably
-  # use the `FunctionDispatch` module to define functions instead of doing it manually.)
+  # you see fit.
+  #
+  # If the response includes a function call, the module will dispatch the function
+  # call and return the result. Which implies that function calls need to be defined
+  # on the class that includes this module. The `FunctionDispatch` module provides a
+  # Rails-like DSL for declaring and implementing tool functions at the top of your
+  # class instead of having to manually implement them as instance methods. The
+  # primary benefit of using the `FunctionDispatch` module is that it handles
+  # adding the function call results to the ongoing conversation transcript for you.
+  # It also triggers a new chat completion automatically if you've set the `loop`
+  # option to `true`, which is useful for implementing conversational chatbots that
+  # include tool calls.
+  #
+  # Note that some AI models can make more than a single tool function call in a
+  # single response. When that happens, the module will dispatch all of the function
+  # calls sequentially and return an array of results.
   module ChatCompletion
     extend ActiveSupport::Concern
 
@@ -92,13 +104,13 @@ module Raix
         # TODO: add a standardized callback hook for usage events
         # broadcast(:usage_event, usage_subject, self.class.name.to_s, response, premium?)
 
-        # TODO: handle parallel tool calls
-        if (function = response.dig("choices", 0, "message", "tool_calls", 0, "function"))
-          @current_function = function["name"]
-          # dispatch the called function
-          arguments = JSON.parse(function["arguments"].presence || "{}")
-          arguments[:bot_message] = bot_message if respond_to?(:bot_message)
-          return send(function["name"], arguments.with_indifferent_access)
+        tool_calls = response.dig("choices", 0, "message", "tool_calls") || []
+        if tool_calls.any?
+          return tool_calls.map do |tool_call|
+            # dispatch the called function
+            arguments = JSON.parse(tool_call["function"]["arguments"].presence || "{}")
+            send(tool_call["function"]["name"], arguments.with_indifferent_access)
+          end
         end
 
         response.tap do |res|

data/lib/raix/predicate.rb

@@ -0,0 +1,64 @@
+# 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.
+  #
+  # @example
+  #   class Question
+  #     include Raix::Predicate
+  #
+  #     yes do |explanation|
+  #       puts "Yes: #{explanation}"
+  #     end
+  #
+  #     no do |explanation|
+  #       puts "No: #{explanation}"
+  #     end
+  #   end
+  #
+  #   question = Question.new
+  #   question.ask("Is Ruby a programming language?")
+  module Predicate
+    include ChatCompletion
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def ask(question)
+      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.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 response.downcase.start_with?("maybe,")
+          instance_exec(response, &self.class.maybe_block) if self.class.maybe_block
+        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/version.rb

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

data/raix.gemspec

@@ -30,4 +30,5 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "activesupport", ">= 6.0"
   spec.add_dependency "open_router", "~> 0.2"
+  spec.add_dependency "ruby-openai", "~> 7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.4
 platform: ruby
 authors:
 - Obie Fernandez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-05 00:00:00.000000000 Z
+date: 2024-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: ruby-openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
 description:
 email:
 - obiefernandez@gmail.com
@@ -52,6 +66,7 @@ files:
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -59,6 +74,7 @@ files:
 - lib/raix/chat_completion.rb
 - lib/raix/function_dispatch.rb
 - lib/raix/message_adapters/base.rb
+- lib/raix/predicate.rb
 - lib/raix/prompt_declarations.rb
 - lib/raix/response_format.rb
 - lib/raix/version.rb