raix-rails 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 311c298f7aebaaa19979174f680dd21ff165ddb6e7187f622ea2e8d6e5c24e9a
-  data.tar.gz: 13932ec4de274b41eafeae99ef0a674328ab8bb984414ec6e84e8633a125b6c9
+  metadata.gz: 49d83bc8390b10829bb062e0bd107eb3e2773ca59e5d61bde85c8f783621a7f4
+  data.tar.gz: ed6ca5031a53dc185b91ef1e745d235258b7965642a18ec4e45940aa74eaa7df
 SHA512:
-  metadata.gz: ae9bcb3729056a8cb9440f0c9f6964fb054180535cd4ff96a8e44724728f67ac703c80c544deae12ec2accd492bbe37c5f25faac2a31b0653ca4cd0ce17fba03
-  data.tar.gz: cd5cc04616d616717cb6c52e518a5189e7ebede35f5896549c4d39feca64bb12083059668b0b715e14595ed4d1fd0b1c1fabd541e273c7ecec7a66761631d5f7
+  metadata.gz: cfca0e561cc16dda50d53f606fba7b394a7aa14e6e7ee6ceec4352a8522d9b39c042d4b04aaaf7675485366353d45b91898d9cc7ec8e3844cbf8edc58f29de56
+  data.tar.gz: 26344feccfa39fe084ecbdf5fca52150815e6f728c5b857123a59ecedc8318c0f9ee4546ee3b011165d2f9cd079ee1f6dbf05bc6c34206ae17dbdbb268e7db2a

data/README.md

@@ -10,16 +10,202 @@ At the moment, Raix natively supports use of either OpenAI or OpenRouter as its
 
 ### Chat Completions
 
-Raix consists of three modules that can be mixed in to Ruby classes to give them AI powers. The first (and mandatory) module is `ChatCompletion`, which provides a `chat_completion` method.
+Raix consists of three modules that can be mixed in to Ruby classes to give them AI powers. The first (and mandatory) module is `ChatCompletion`, which provides `transcript` and `chat_completion` methods.
+
+```ruby
+class MeaningOfLife
+  include Raix::ChatCompletion
+end
+
+>> ai = MeaningOfLife.new
+>> ai.transcript << { user: "What is the meaning of life?" }
+>> ai.chat_completion
+
+=> "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..."
+
+```
+
+#### 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.
+
+```ruby
+transcript << { user: "What is the meaning of life?" }
+```
+
+As mentioned, Raix also understands standard OpenAI messages hashes. The previous example could be written as:
+
+```ruby
+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.)
 
 ### Use of Tools/Functions
 
 The second (optional) module that you can add to your Ruby classes after `ChatCompletion` is `FunctionDispatch`. It lets you declare and implement functions to be called at the AI's discretion as part of a chat completion "loop" in a declarative, Rails-like "DSL" fashion.
 
+Most end-user facing AI components that include functions should be invoked using `chat_completion(loop: true)`, so that the results of each function call are added to the transcript and chat completion is triggered again. The looping will continue until the AI generates a plain text response.
+
+```ruby
+class WhatIsTheWeather
+  include Raix::ChatCompletion
+  include Raix::FunctionDispatch
+
+  function :check_weather, "Check the weather for a location", location: { type: "string" } do |arguments|
+    "The weather in #{arguments[:location]} is hot and sunny"
+  end
+end
+
+RSpec.describe WhatIsTheWeather do
+  subject { described_class.new }
+
+  it "can call a function and loop to provide text response" do
+    subject.transcript << { user: "What is the weather in Zipolite, Oaxaca?" }
+    response = subject.chat_completion(openai: "gpt-4o", loop: true)
+    expect(response).to include("hot and sunny")
+  end
+end
+```
+
+#### Manually Stopping a Loop
+
+To loop AI components that don't interact with end users, at least one function block should invoke `stop_looping!` whenever you're ready to stop processing.
+
+```ruby
+class OrderProcessor
+  include Raix::ChatCompletion
+  include Raix::FunctionDispatch
+
+  SYSTEM_DIRECTIVE = "You are an order processor, tasked with order validation, inventory check,
+                      payment processing, and shipping."
+
+  attr_accessor :order
+
+  def initialize(order)
+    self.order = order
+    transcript << { system: SYSTEM_DIRECTIVE }
+    transcript << { user: order.to_json }
+  end
+
+  def perform
+    # will continue looping until `stop_looping!` is called
+    chat_completion(loop: true)
+  end
+
+
+  # implementation of functions that can be called by the AI
+  # entirely at its discretion, depending on the needs of the order.
+  # The return value of each `perform` method will be added to the
+  # transcript of the conversation as a function result.
+
+  function :validate_order do
+    OrderValidationWorker.perform(@order)
+  end
+
+  function :check_inventory do
+    InventoryCheckWorker.perform(@order)
+  end
+
+  function :process_payment do
+    PaymentProcessingWorker.perform(@order)
+  end
+
+  function :schedule_shipping do
+    ShippingSchedulerWorker.perform(@order)
+  end
+
+  function :send_confirmation do
+    OrderConfirmationWorker.perform(@order)
+  end
+
+  function :finished_processing do
+    order.update!(transcript:, processed_at: Time.current)
+    stop_looping!
+  end
+end
+```
+
 ### Prompt Declarations
 
 The third (also optional) module that you can add mix in along with `ChatCompletion` is `PromptDeclarations`. It provides the ability to declare a "Prompt Chain" (series of prompts to be called in a sequence), and also features a declarative, Rails-like "DSL" of its own. Prompts can be defined inline or delegate to callable prompt objects, which themselves implement `ChatCompletion`.
 
+The following example is a rough excerpt of the main "Conversation Loop" in Olympia, which pre-processes user messages to check for
+the presence of URLs and scan memory before submitting as a prompt to GPT-4. Note that prompt declarations are executed in the order
+that they are declared. The `FetchUrlCheck` callable prompt class is included for instructional purposes. Note that it is passed the
+an instance of the object that is calling it in its initializer as its `context`. The passing of context means that you can assemble
+composite prompt structures of arbitrary depth.
+
+```ruby
+class PromptSubscriber
+  include Raix::ChatCompletion
+  include Raix::PromptDeclarations
+
+  attr_accessor :conversation, :bot_message, :user_message
+
+  # many other declarations ommitted...
+
+  prompt call: FetchUrlCheck
+
+  prompt call: MemoryScan
+
+  prompt text: -> { user_message.content }, stream: -> { ReplyStream.new(self) }, until: -> { bot_message.complete? }
+
+  def initialize(conversation)
+    self.conversation = conversation
+  end
+
+  def message_created(user_message)
+    self.user_message = user_message
+    self.bot_message = conversation.bot_message!(responding_to: user_message)
+
+    chat_completion(loop: true, openai: "gpt-4o")
+  end
+
+  ...
+
+end
+
+class FetchUrlCheck
+  include ChatCompletion
+  include FunctionDispatch
+
+  REGEX = %r{\b(?:http(s)?://)?(?:www\.)?[a-zA-Z0-9-]+(\.[a-zA-Z]{2,})+(/[^\s]*)?\b}
+
+  attr_accessor :context, :conversation
+
+  delegate :user_message, to: :context
+  delegate :content, to: :user_message
+
+  def initialize(context)
+    self.context = context
+    self.conversation = context.conversation
+    self.model = "anthropic/claude-3-haiku"
+  end
+
+  def call
+    return unless content&.match?(REGEX)
+
+    transcript << { system: "Call the `fetch` function if the user mentions a website, otherwise say nil" }
+    transcript << { user: content }
+
+    chat_completion # TODO: consider looping to fetch more than one URL per user message
+  end
+
+  function :fetch, "Gets the plain text contents of a web page", url: { type: "string" } do |arguments|
+    Tools::FetchUrl.fetch(arguments[:url]).tap do |result|
+      parent = conversation.function_call!("fetch_url", arguments, parent: user_message)
+      conversation.function_result!("fetch_url", result, parent:)
+    end
+  end
+
+```
+
+Notably, Olympia does not use the `FunctionDispatch` module in its primary conversation loop because it does not have a fixed set of tools that are included in every single prompt. Functions are made available dynamically based on a number of factors including the user's plan tier and capabilities of the assistant with whom the user is conversing.
+
+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.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/lib/raix/function_dispatch.rb

@@ -97,6 +97,13 @@ module Raix
       super
     end
 
+    # Stops the looping of chat completion after function calls.
+    # Useful for manually halting processing in workflow components
+    # that do not require a final text response to an end user.
+    def stop_looping!
+      self.loop = false
+    end
+
     def tools
       self.class.functions.map { |function| { type: "function", function: } }
     end

data/lib/raix/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Raix
   module Rails
-    VERSION = "0.3.0"
+    VERSION = "0.3.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raix-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Obie Fernandez