raix 0.7.1 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a2990e8225edcfbcc5007aae41a0dd69987bff18bd085bb9c486561e5597044
-  data.tar.gz: 60ef3efa8eb6cbe1b445afd09fc65a4b1d6fc62c872588956baee46b511d79d3
+  metadata.gz: 90b0072e3af33e82ccfb040554e9645920e34b4477457ba79335582c9325a7bd
+  data.tar.gz: beeb6e0b98b473597d2191b5005fc89cb57fe69633cfe1e8927a6c1c0f61048f
 SHA512:
-  metadata.gz: dfa0a7dfed2782d49c95f749c847b024ef41097b4ab318b34f9eabbfd9f754cf49c6eb859c1b14534332efea930d707df457e2d24a4c1f30f043d7dacb3c801c
-  data.tar.gz: 2e291a98b2ed5e25c2381a30d609e4277cb94458531c03e77b79fc95e70ee92e40c0d9cacb31809a1f7acca860550e4d02698856321869144dc56a4d794ea3d8
+  metadata.gz: cbc28460d07263899c0e45be8ccfd3fa522b3162ad2a53d640c1ff0cccb6c7d96f7ab4bef2afa809d47733a98a4a502602b78a6c53918e676955da9d88220f69
+  data.tar.gz: d5e4f7dedaeb3ab2de64168f17a9de920a18894d5acfff22c0e00b870bdf96c77478130a61d47f82f7cc01a566b1cbc95f41fb43241cb3ece24c743b80993fed

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## [0.7] - 2024-04-02
+## [0.7.3] - 2025-04-23
+
+## [0.7.2] - 2025-04-19
+- adds support for `messages` parameter in `chat_completion` to override the transcript
+- fixes potential race conditions in parallel chat completion calls by duplicating transcript
+
+## [0.7.1] - 2025-04-10
+- adds support for JSON response format with automatic parsing
+- improves error handling for JSON parsing failures
+
+## [0.7] - 2025-04-02
 - adds support for `until` condition in `PromptDeclarations` to control prompt looping
 - adds support for `if` and `unless` conditions in `PromptDeclarations` to control prompt execution
 - adds support for `success` callback in `PromptDeclarations` to handle prompt responses
@@ -22,39 +32,38 @@
 - adds `save_response` option to `chat_completion` to control transcript updates
 - fixes potential race conditions in transcript handling
 
-## [0.1.0] - 2024-04-03
+## [0.4.8] - 2024-11-12
+- adds documentation for `Predicate` maybe handler
+- logs to stdout when a response is unhandled by `Predicate`
 
-- Initial release, placeholder gem
+## [0.4.7] - 2024-11-12
+- adds missing requires `raix/predicate` so that it can be used in a Rails app automatically
+- adds missing openai support for `Predicate`
 
-## [0.2.0] - tbd
-- adds `ChatCompletion` module
-- adds `PromptDeclarations` module
-- adds `FunctionDispatch` module
+## [0.4.5] - 2024-11-11
+- adds support for `ResponseFormat`
+- added some missing requires to support String#squish
 
-## [0.3.2] - 2024-06-29
-- adds support for streaming
+## [0.4.4] - 2024-11-11
+- adds support for multiple tool calls in a single response
 
-## [0.4.0] - 2024-10-18
-- adds support for Anthropic-style prompt caching
-- defaults to `max_completion_tokens` when using OpenAI directly
+## [0.4.3] - 2024-11-11
+- adds support for `Predicate` module
 
 ## [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
-
-## [0.4.4] - 2024-11-11
-- adds support for multiple tool calls in a single response
+## [0.4.0] - 2024-10-18
+- adds support for Anthropic-style prompt caching
+- defaults to `max_completion_tokens` when using OpenAI directly
 
-## [0.4.5] - 2024-11-11
-- adds support for `ResponseFormat`
-- added some missing requires to support String#squish
+## [0.3.2] - 2024-06-29
+- adds support for streaming
 
-## [0.4.7] - 2024-11-12
-- adds missing requires `raix/predicate` so that it can be used in a Rails app automatically
-- adds missing openai support for `Predicate`
+## [0.2.0] - tbd
+- adds `ChatCompletion` module
+- adds `PromptDeclarations` module
+- adds `FunctionDispatch` module
 
-## [0.4.8] - 2024-11-12
-- adds documentation for `Predicate` maybe handler
-- logs to stdout when a response is unhandled by `Predicate`
+## [0.1.0] - 2024-04-03
+- Initial release, placeholder gem

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    raix (0.7.1)
+    raix (0.7.3)
       activesupport (>= 6.0)
       open_router (~> 0.2)
       ruby-openai (~> 7.0)
@@ -211,6 +211,7 @@ GEM
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
+  arm64-darwin-23
   arm64-darwin-24
   x86_64-linux
 

data/README.md

@@ -4,7 +4,7 @@
 
 Raix (pronounced "ray" because the x is silent) is a library that gives you everything you need to add discrete large-language model (LLM) AI components to your Ruby applications. Raix consists of proven code that has been extracted from [Olympia](https://olympia.chat), the world's leading virtual AI team platform, and probably one of the biggest and most successful AI chat projects written completely in Ruby.
 
-Understanding the how to use discrete AI components in otherwise normal code is key to productively leveraging Raix, and the subject of a book written by Raix's author Obie Fernandez, titled [Patterns of Application Development Using AI](https://leanpub.com/patterns-of-application-development-using-ai). You can easily support the ongoing development of this project by buying the book at Leanpub.
+Understanding how to use discrete AI components in otherwise normal code is key to productively leveraging Raix, and the subject of a book written by Raix's author Obie Fernandez, titled [Patterns of Application Development Using AI](https://leanpub.com/patterns-of-application-development-using-ai). You can easily support the ongoing development of this project by buying the book at Leanpub.
 
 At the moment, Raix natively supports use of either OpenAI or OpenRouter as its underlying AI provider. Eventually you will be able to specify your AI provider via an adapter, kind of like ActiveRecord maps to databases. Note that you can also use Raix to add AI capabilities to non-Rails applications as long as you include ActiveSupport as a dependency. Extracting the base code to its own standalone library without Rails dependencies is on the roadmap, but not a high priority.
 
@@ -23,6 +23,7 @@ end
 
 => "The question of the meaning of life is one of the most profound and enduring inquiries in philosophy, religion, and science.
     Different perspectives offer various answers..."
+```
 
 By default, Raix will automatically add the AI's response to the transcript. This behavior can be controlled with the `save_response` parameter, which defaults to `true`. You may want to set it to `false` when making multiple chat completion calls during the lifecycle of a single object (whether sequentially or in parallel) and want to manage the transcript updates yourself:
 
@@ -32,7 +33,7 @@ By default, Raix will automatically add the AI's response to the transcript. Thi
 
 #### Transcript Format
 
-The transcript accepts both abbreviated and standard OpenAI message hash formats. The abbreviated format, suitable for system, assistant, and user messages is simply a mapping of `role => content`, as show in the example above.
+The transcript accepts both abbreviated and standard OpenAI message hash formats. The abbreviated format, suitable for system, assistant, and user messages is simply a mapping of `role => content`, as shown in the example above.
 
 ```ruby
 transcript << { user: "What is the meaning of life?" }
@@ -46,6 +47,12 @@ transcript << { role: "user", content: "What is the meaning of life?" }
 
 One of the advantages of OpenRouter and the reason that it is used by default by this library is that it handles mapping message formats from the OpenAI standard to whatever other model you're wanting to use (Anthropic, Cohere, etc.)
 
+Note that it's possible to override the current object's transcript by passing a `messages` array to `chat_completion`. This allows for multiple threads to share a single conversation context in parallel, by deferring when they write their responses back to the transcript.
+
+```
+chat_completion(openai: "gpt-4.1-nano", messages: [{ user: "What is the meaning of life?" }])
+```
+
 ### Predicted Outputs
 
 Raix supports [Predicted Outputs](https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs) with the `prediction` parameter for OpenAI.
@@ -56,7 +63,7 @@ Raix supports [Predicted Outputs](https://platform.openai.com/docs/guides/latenc
 
 ### Prompt Caching
 
-Raix supports [Anthropic-style prompt caching](https://openrouter.ai/docs/prompt-caching#anthropic-claude) when using Anthropic's Claud family of models. You can specify a `cache_at` parameter when doing a chat completion. If the character count for the content of a particular message is longer than the cache_at parameter, it will be sent to Anthropic as a multipart message with a cache control "breakpoint" set to "ephemeral".
+Raix supports [Anthropic-style prompt caching](https://openrouter.ai/docs/prompt-caching#anthropic-claude) when using Anthropic's Claude family of models. You can specify a `cache_at` parameter when doing a chat completion. If the character count for the content of a particular message is longer than the cache_at parameter, it will be sent to Anthropic as a multipart message with a cache control "breakpoint" set to "ephemeral".
 
 Note that there is a limit of four breakpoints, and the cache will expire within five minutes. Therefore, it is recommended to reserve the cache breakpoints for large bodies of text, such as character cards, CSV data, RAG data, book chapters, etc. Raix does not enforce a limit on the number of breakpoints, which means that you might get an error if you try to cache too many messages.
 
@@ -239,7 +246,7 @@ class PromptSubscriber
 
   attr_accessor :conversation, :bot_message, :user_message
 
-  # many other declarations ommitted...
+  # many other declarations omitted...
 
   prompt call: FetchUrlCheck
 
@@ -563,13 +570,13 @@ You will also need to configure the OpenRouter API access token as per the instr
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-Specs require `OR_ACCESS_TOKEN` and `OAI_ACCESS_TOKEN` environment variables, for access to OpenRouter and OpenAI, respectively. You can add those keys to a local unversionsed `.env` file and they will be picked up by the `dotenv` gem.
+Specs require `OR_ACCESS_TOKEN` and `OAI_ACCESS_TOKEN` environment variables, for access to OpenRouter and OpenAI, respectively. You can add those keys to a local unversioned `.env` file and they will be picked up by the `dotenv` gem.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[OlympiaAI]/raix. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[OlympiaAI]/raix/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/OlympiaAI/raix. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/OlympiaAI/raix/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -577,4 +584,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Raix project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[OlympiaAI]/raix/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Raix project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/OlympiaAI/raix/blob/main/CODE_OF_CONDUCT.md).

data/lib/raix/chat_completion.rb

@@ -43,8 +43,9 @@ module Raix
     # @option params [Boolean] :json (false) Whether to return the parse the response as a JSON object. Will search for <json> tags in the response first, then fall back to the default JSON parsing of the entire response.
     # @option params [Boolean] :openai (false) Whether to use OpenAI's API instead of OpenRouter's.
     # @option params [Boolean] :raw (false) Whether to return the raw response or dig the text content.
+    # @option params [Array] :messages (nil) An array of messages to use instead of the transcript.
     # @return [String|Hash] The completed chat response.
-    def chat_completion(params: {}, loop: false, json: false, raw: false, openai: false, save_response: true)
+    def chat_completion(params: {}, loop: false, json: false, raw: false, openai: false, save_response: true, messages: nil)
       # set params to default values if not provided
       params[:cache_at] ||= cache_at.presence
       params[:frequency_penalty] ||= frequency_penalty.presence
@@ -68,13 +69,17 @@ module Raix
       params[:top_logprobs] ||= top_logprobs.presence
       params[:top_p] ||= top_p.presence
 
+      json = true if params[:response_format].is_a?(Raix::ResponseFormat)
+
       if json
         unless openai
           params[:provider] ||= {}
           params[:provider][:require_parameters] = true
         end
-        params[:response_format] ||= {}
-        params[:response_format][:type] = "json_object"
+        if params[:response_format].blank?
+          params[:response_format] ||= {}
+          params[:response_format][:type] = "json_object"
+        end
       end
 
       # used by FunctionDispatch
@@ -87,7 +92,9 @@ module Raix
 
       # duplicate the transcript to avoid race conditions in situations where
       # chat_completion is called multiple times in parallel
-      messages = transcript.flatten.compact.map { |msg| adapter.transform(msg) }.dup
+      # TODO: Defensive programming, ensure messages is an array
+      messages ||= transcript.flatten.compact
+      messages = messages.map { |msg| adapter.transform(msg) }.dup
       raise "Can't complete an empty transcript" if messages.blank?
 
       begin

data/lib/raix/function_dispatch.rb

@@ -56,27 +56,31 @@ module Raix
 
         define_method(name) do |arguments|
           id = SecureRandom.uuid[0, 23]
-          transcript << {
-            role: "assistant",
-            content: nil,
-            tool_calls: [
+          instance_exec(arguments, &block).tap do |content|
+            # add in one operation to prevent race condition and potential wrong
+            # interleaving of tool calls in multi-threaded environments
+            transcript << [
+              {
+                role: "assistant",
+                content: nil,
+                tool_calls: [
+                  {
+                    id:,
+                    type: "function",
+                    function: {
+                      name:,
+                      arguments: arguments.to_json
+                    }
+                  }
+                ]
+              },
               {
-                id:,
-                type: "function",
-                function: {
-                  name:,
-                  arguments: arguments.to_json
-                }
+                role: "tool",
+                tool_call_id: id,
+                name:,
+                content: content.to_s
               }
             ]
-          }
-          instance_exec(arguments, &block).tap do |content|
-            transcript << {
-              role: "tool",
-              tool_call_id: id,
-              name:,
-              content: content.to_s
-            }
             # TODO: add on_error handler as optional parameter to function
           end
 

data/lib/raix/response_format.rb

@@ -50,16 +50,20 @@ module Raix
       {}.tap do |response|
         case input
         when Array
-          properties = {}
-          input.each { |item| properties.merge!(decode(item)) }
-
           response[:type] = "array"
-          response[:items] = {
-            type: "object",
-            properties:,
-            required: properties.keys.select { |key| properties[key].delete(:required) },
-            additionalProperties: false
-          }
+
+          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)

data/lib/raix/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: raix
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.3
 platform: ruby
 authors:
 - Obie Fernandez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-14 00:00:00.000000000 Z
+date: 2025-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport