instruct 0.1.0a1

data/lib/instruct/llms/openai/middleware.rb

@@ -0,0 +1,52 @@
+class Instruct::OpenAI
+  class Middleware
+    include Instruct::Serializable
+    set_instruct_class_id 101
+    CLIENT_PARAMS = %i[api_type api_version access_token organization_id uri_base request_timeout extra_headers].freeze
+    REQUEST_PARAMS = %i[store metadata frequency_penalty logit_bias logprobs top_logprobs max_completion_tokens n prediction presence_penalty response_format seed service_tier stop stream_options temperature top_p user].freeze
+
+    def call(req, _next:)
+      raise Instruct::Todo, "Non text modalities not supported yet, consider opening a pull request" if req.env[:modalities] && (req.env[:modalities] != [:text] || req.env[:modalities] != ["text"])
+      raise Instruct::Todo, "Tools are not supported yet, consider opening a pull request" if req.env[:tools] || req.env[:tool_choice] || req.env[:parallel_tool_calls] || req.env[:function_call] || req.env[:functions]
+
+      # Extract client options
+      client_options = filter_env_keys(req, CLIENT_PARAMS)
+      req.env[:openai_client_opts] = client_options
+      #
+      # Handle stop_chars conversion
+      if req.env[:stop_chars].is_a?(String)
+        req.env[:stop] = req.env[:stop_chars].split('')
+      end
+
+      # Extract request options
+      request_options = filter_env_keys(req, REQUEST_PARAMS)
+      req.env[:openai_args] = request_options
+
+      # Handle deprecated arguments
+      deprecated_args = [:max_tokens, :function_call, :functions]
+      req.env[:openai_deprecated_args] = filter_env_keys(req, deprecated_args)
+
+
+      req.add_prompt_transform do |attr_str|
+        transform(attr_str)
+      end
+
+      _next.call(req)
+    end
+
+    def transform(prompt_obj)
+      if prompt_obj.is_a?(Hash) && prompt_obj[:messages].is_a?(Array)
+        prompt_obj[:messages].map! do |message|
+          { role: message.keys.first, content: message.values.first.to_s }
+        end
+      end
+      prompt_obj
+    end
+
+    private
+
+    def filter_env_keys(req, keys)
+      req.env.select { |k, _| keys.include?(k) }
+    end
+  end
+end

data/lib/instruct/middleware/chat_completion_middleware.rb

@@ -0,0 +1,90 @@
+module Instruct
+  # Converts prompt plain text entries into role-based conversation entries
+  # See {file:docs/prompt-completion-middleware.md#label-Chat+Completion+Middleware}
+  class ChatCompletionMiddleware
+    include Instruct::Serializable
+    set_instruct_class_id 4
+
+    def initialize(roles: [:system, :user, :assistant])
+      @roles = roles
+    end
+
+    def call(req, _next:)
+      role_changes = []
+
+      control_str = req.prompt.filter do | attrs |
+        attrs[:safe] == true
+      end
+
+      # scan the control string for role changes, defined
+      # as newlines followed by whitespace, then a role name,
+      # then a colon, then an optional single space which is chomped.
+      role_change_re = /(?:^|\n)\s*(\w+):\s?/
+      control_str.scan(role_change_re) do |match|
+        range_of_full_match = Regexp.last_match.offset(0)
+
+        ranges = control_str.original_ranges_for(range_of_full_match[0]..range_of_full_match[1] - 1)
+        start = ranges.first.first
+        finish = ranges.last.last
+
+
+        role = match[0].to_sym
+        if @roles.include?(role)
+          role_changes << { role: role, control_start: start, control_finish: finish }
+        end
+      end
+
+      start_pos = 0
+      role = @roles.first
+      # TODO: we want to make it so that if no role changes are defined we fallback to the
+      # default user role, and use the system: to define the system arg.
+      role_changes.each do |change|
+        if change[:control_start] > start_pos
+          if role == :system
+            req.env[:system_from_prompt] = req.prompt[start_pos...change[:control_start]]
+          end
+          req.prompt.add_attrs(start_pos...change[:control_start], role: role)
+        end
+        start_pos = change[:control_finish] + 1
+        role = change[:role]
+      end
+      if role == :system
+        req.env[:system_from_prompt] = req.prompt[start_pos...req.prompt.length]
+      end
+      req.prompt.add_attrs(start_pos...req.prompt.length, role: role)
+
+      req.add_prompt_transform do | attr_str |
+        transform(attr_str)
+      end
+
+      if req.prompt.attrs_at(req.prompt.length - 1)[:role] != :assistant && @roles.include?(:assistant)
+        req.prompt.safe_concat(Prompt.new("\nassistant: ", source: :chat_completion_middleware))
+      end
+
+      # need to work out pos of each entry in text prompt
+      _next.call(req)
+    end
+
+    def transform(prompt_str)
+      # TODO: once there is an attributed string presenter
+      # we can replace this
+      messages = []
+      message_range = 0...0
+      role = nil
+      prompt_str.each_char.with_index do |char, idx|
+        prompt_attrs = prompt_str.attrs_at(idx)
+        if prompt_attrs[:role] != role
+          messages << { role => prompt_str[message_range].remove_attrs(:role) } unless message_range.size.zero? || role.nil?
+          role = prompt_attrs[:role]
+          message_range = idx...idx
+        end
+        message_range = message_range.first..idx
+      end
+      messages << { role => prompt_str[message_range].remove_attrs(:role) } unless message_range.size.zero? || role.nil?
+      { messages: messages }
+    end
+
+
+
+  end
+end

data/lib/instruct/middleware/chomp_middleware.rb

@@ -0,0 +1,56 @@
+module Instruct
+  # This middleware hides the whitespace at the end of the current prompt by
+  # adding a chomp_hide attribute to the whitespace with the id of the current
+  # request. The prompt_transform then removes the whitespace from the prompt
+  #
+  # object removes characters marked with chomp_hide for the same request.
+  # have the same whitespace at the beginning, the chomp_hide attribute is
+  # removed from the prompt. If the response does have the same whitespace
+  # it is chomped from the response.
+  class ChompMiddleware
+    include Instruct::Serializable
+    set_instruct_class_id 5
+
+    def call(req, _next:)
+
+      whitespace = ''
+      # TODO, this should only be for non-hidden whitespace
+      req.prompt.to_s.match(/(\s+)$/) do |match|
+        whitespace = match[0]
+      end
+      range = req.prompt.length - whitespace.length...req.prompt.length
+
+      req.prompt.add_attrs(range, chomped: req.id)
+      req.prompt.hide_range_from_prompt(range, by: self.class)
+
+
+      # TODO: maybe we work out a way to pause the stream from
+      # hitting upstream handles until it feels good about it
+      trimming_whitespace = true
+      unhidden = false
+      req.add_stream_handler do |completion, chunk|
+        if range.size.positive? && !unhidden
+          req.prompt.unhide_range_from_prompt(range, by: self.class)
+          unhidden = true
+        end
+        next completion if !trimming_whitespace
+        next false if completion.length < whitespace.length && whitespace.start_with?(completion.to_s)
+        # this will stop all upstream handlers, generally not a great idea, but
+        # for this middleware it is fine
+        if completion.length >= whitespace.length
+          trimming_whitespace = false
+          if completion.start_with?(whitespace)
+            completion[...whitespace.length] = ''
+            next false if completion.empty?
+          end
+        end
+        completion
+      end
+
+      _next.call(req)
+
+    end
+
+
+  end
+end

data/lib/instruct/model.rb

@@ -0,0 +1,21 @@
+module Instruct
+  module Model
+    def self.from_string_or_model(model)
+      if model.class == String
+        self.from_string(model)
+      elsif model.respond_to?(:call)
+        model
+      else
+        raise ArgumentError, "Model must be a model name string or respond to call."
+      end
+    end
+
+    def self.from_string(string, **kwargs)
+      if string.include?("claude") || string.include?("anthropic")
+        Instruct::Anthropic.new(string, **kwargs)
+      else
+        Instruct::OpenAI.new(string, **kwargs)
+      end
+    end
+  end
+end

data/lib/instruct/prompt.rb

@@ -0,0 +1,217 @@
+module Instruct
+  class Prompt < AttributedString
+    include Instruct::Serializable
+    set_instruct_class_id 1
+
+
+    def call(**kwargs, &streaming_block)
+      raise ArgumentError, "cannot add prompt to call on prompt" if kwargs[:prompt]
+
+      prompt = Prompt.new
+
+      gens, substrings = split_substrings_and_gen_attachments
+      results = []
+
+      gens.each_with_index do |gen, i|
+        prompt += substrings[i]
+        gen.prompt = prompt
+        completion = gen.call(**kwargs, &streaming_block)
+        prompt += completion
+        results << completion
+      end
+
+      results.length > 1 ? results : results.first
+    end
+
+
+    def +(other, *args, apply_completions: true)
+      self.dup.concat(other, *args, apply_completions:)
+    end
+
+    # Unlike normal strings << is not the same as concat. << first performs the concat, then runs call on the
+    # new prompt, before adding the result to the prompt.
+    def <<(other, *args, **kwargs)
+      concat(other, *args, perform_call: true, apply_completions: true, **kwargs)
+    end
+
+    def safe_concat(string)
+      string = Prompt.new(string, safe: true) if string.is_a?(String)
+      concat(string)
+    end
+
+    def concat(other, *args, perform_call: false, apply_completions: false)
+      if other.is_a?(Array) && other.all? { |obj| obj.is_a?(Prompt::Completion) } && !other.empty?
+        return concat(*(other + args), perform_call:, apply_completions: )
+      end
+      if other.is_a?(Prompt::Completion) && apply_completions
+        other.apply_to_prompt(self)
+      else
+        super(other)
+      end
+      if args.size.positive?
+        return self.concat(*args, perform_call: perform_call, apply_completions: apply_completions)
+      end
+      if perform_call && result = self.call
+        self.concat(result, perform_call: false, apply_completions: true)
+      else
+        self
+      end
+    end
+
+    def split_substrings_and_gen_attachments
+      gens = []
+      substrings = []
+      deferred_gens = self.attachments_with_positions.filter { |obj| obj[:attachment].is_a?(Instruct::Gen) }
+      next_substring_index = 0
+      deferred_gens.each do |obj|
+        position = obj[:position]
+        substrings << self[next_substring_index..position]
+        gens << obj[:attachment]
+        next_substring_index = position + 1
+      end
+      substrings << self[next_substring_index..self.length - 1] if next_substring_index <= self.length - 1
+      return [gens, substrings]
+    end
+
+    def hide_range_from_prompt(range, by:)
+      add_attrs(range, "hidden_#{by}": true)
+    end
+
+    def unhide_range_from_prompt(range, by:)
+      remove_attrs(range, "hidden_#{by}".to_sym)
+    end
+
+    def prompt_object
+      prompt_object = self.dup
+      hidden_chars = prompt_object.filter do |attrs|
+        len_hidden_attrs(attrs).positive?
+      end
+      return prompt_object if hidden_chars.empty?
+      ranges = hidden_chars.original_ranges_for(0..hidden_chars.length - 1)
+      ranges.each do |range|
+        prompt_object[range] = ''
+      end
+      prompt_object
+    end
+
+
+    def to_s(gen: :emoji)
+      string = super()
+      deferred_gens = self.attachments_with_positions.filter { |obj| obj[:attachment].is_a?(Instruct::Gen) }
+      deferred_gens.each do |obj|
+        position = obj[:position]
+        case gen
+        when :no_change
+        when :hide
+          string[position] = ''
+        when :expand
+          string[position] = obj[:attachment].to_s
+        when :emoji
+          string[position] =  "💬"
+        end
+      end
+      string
+    end
+
+    def captured(key)
+      return nil unless @captured
+      @captured[key]
+    end
+
+    def capture(key, **kwargs)
+      # TODO: attributed string should support -1
+      last_attachment = self.attachment_at(self.length - 1)
+      if last_attachment.is_a?(Instruct::Gen)
+        last_attachment.capture(key, **kwargs)
+      else
+       raise ArgumentError, "Cannot capture on a prompt that does not end with a Gen"
+      end
+      self
+    end
+
+    private
+
+    def add_captured(value, key, list_key)
+      @captured ||= {}
+      if key
+        @captured[key] = value
+      end
+      if list_key
+        @captured[list_key] ||= [@captured[list_key]].compact
+        @captured[list_key] << value
+      end
+    end
+
+    def len_hidden_attrs(attrs)
+      attrs.keys.filter { |key| key.to_s.start_with?('hidden_') }.length
+    end
+
+
+    # When a generated result is added to or concatted to a prompt, the
+    # prompt replaces its contents with modified prompt if
+    # the original prompt is the same as the prompt. This enables
+    # middleware to make modifications to the prompt that persist
+    # only when the result is added to the prompt. In all other cases,
+    # the prompt is not modified and the result is the normal result.
+    class Completion < AttributedString
+      include Instruct::Serializable
+      set_instruct_class_id 3
+      attr_reader :prompt
+
+      def apply_to_prompt(prompt_for_update)
+        deferred_gens = prompt_for_update.attachments_with_positions.filter { |obj| obj[:attachment].is_a?(Instruct::Gen) }
+        first_gen = deferred_gens.first
+        if first_gen.nil?
+          return prompt_for_update.replace(prompt_for_update.+(self, apply_completions: false))
+        end
+        # if the prompt_for_update matches the prompt, we replace the prompt_for_update with the updated prompt_for_update
+        # otherwise we just append the updated prompt_for_update to the prompt_for_update
+        # in both cases we remove the gen attachment
+        if (first_gen && prompt_for_update[..first_gen[:position]] == prompt) || (first_gen.nil? && prompt_for_update == prompt)
+          prompt_for_update.send(:add_captured, self, @key, @list_key)
+          prompt_for_update[..first_gen[:position]] = @updated_prompt.+(self, apply_completions: false)
+        else
+          prompt_for_update[first_gen[:position]] = self
+        end
+        prompt_for_update
+      end
+
+      def +(other)
+        return super unless other.is_a?(Prompt)
+        Prompt.new + self + other
+      end
+
+      # Returns the latest chunk in the completion unless a chunk argument is provided
+      def get_chunk(chunk = self.attrs_at(self.length - 1).fetch(:stream_chunk, nil))
+        filtered = self.filter { |attrs| attrs[:stream_chunk] == chunk }
+        ranges = filtered.original_ranges_for(0..(filtered.length - 1))
+        ranges.map { |range| self[range] }.join
+      end
+
+      def _prepare_for_return(prompt:, updated_prompt:, captured_key:, captured_list_key:)
+        @prompt = prompt
+        @updated_prompt = updated_prompt
+        @key = captured_key
+        @list_key = captured_list_key
+      end
+
+
+      private
+
+      def first_gen(prompt)
+        return nil if deferred_gens.empty?
+        deferred_gens
+      end
+
+
+      def captured=(key, list_key)
+        @key, @list_key = key, list_key
+      end
+
+    end
+
+    private
+
+
+  end
+end

data/lib/instruct/rails/active_job_object_serializer.rb

@@ -0,0 +1,23 @@
+require "active_job"
+
+module Instruct::Rails
+  class ActiveJobObjectSerializer < ActiveJob::Serializers::ObjectSerializer
+    def self.serialize(prompt)
+      super({"value" => Instruct::Serializer.dump(prompt)})
+    end
+
+    def self.deserialize(hash)
+      Instruct::Serializer.load(hash["value"])
+    end
+
+    def self.serialize?(object)
+      # Allow prompts and completions to be serialized
+      return true if object.is_a?(Instruct::Prompt) || object.is_a?(Instruct::Prompt::Completion)
+
+      # Allow models to be serialized
+      return true if Instruct.openai_loaded && object.is_a?(OpenAI)
+      return true if Anthropic.anthropic_loaded && object.is_a?(Anthropic)
+      false
+    end
+  end
+end

data/lib/instruct/rails/active_record_coders.rb

@@ -0,0 +1,36 @@
+module Instruct::Rails
+  module SerializableModel
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    module ClassMethods
+      def dump(value)
+        Instruct::Serializer.dump(value)
+      end
+      def load(data)
+        Instruct::Serializer.load(data)
+      end
+    end
+  end
+end
+
+
+class Instruct::Prompt
+  include Instruct::Rails::SerializableModel
+end
+
+class Instruct::Prompt::Completion
+  include Instruct::Rails::SerializableModel
+end
+
+if defined? Instuct::OpenAI
+  class Instruct::OpenAI
+    include Instruct::Rails::SerializableModel
+  end
+end
+
+if defined? Instruct::Anthropic
+  class Instruct::Anthropic
+    include Instruct::Rails::SerializableModel
+  end
+end

data/lib/instruct/railtie.rb

@@ -0,0 +1,15 @@
+require "rails"
+
+module Instruct::Rails
+  class Railtie < Rails::Railtie
+    initializer "instruct.active_record_serializers" do
+      require_relative "rails/active_record_coders"
+    end
+    initializer "instruct.active_job.custom_serializers" do
+      require_relative "rails/active_job_object_serializer"
+      config.after_initialize do
+        ActiveJob::Serializers.add_serializers(Instruct::Rails::ActiveJobObjectSerializer)
+      end
+    end
+  end
+end

data/lib/instruct/utils/middleware_chain.rb

@@ -0,0 +1,48 @@
+module Instruct
+  # Handles executing middleware chain. We use this class to coordinate as it allows us to
+  # make modifications inbetween middleware
+  class MiddlewareChain
+    include Instruct::Serializable
+
+    # @param middlewares [Array<#call(req, _next::), MiddlewareChain>] An array of middleware objects. This can be a mix of classes, instances, procs, or other middleware chains.
+    def initialize(middlewares:)
+      raise ArgumentError, "Middlewares must be an array, not #{middlewares.inspect}" unless middlewares.is_a?(Array)
+      @middlewares = middlewares
+    end
+
+    # Duplicates the middleware chain.
+    def dup
+      self.class.new(middlewares: @middlewares.dup)
+    end
+
+    # Executes the middleware chain with the given request object.
+    def execute(req)
+      raise RuntimeError, "Cannot call execute_* recursively or concurrently" if @stack_ptr
+      @stack_ptr = -1
+      resp = call(req)
+      @stack_ptr = nil
+      resp
+    end
+
+    # @api private
+    # Don't use. This is internally used to call the _next: middleware in the chain.
+    def call(req)
+      raise RuntimeError, "Cannot use .call directly, use .execute" if @stack_ptr.nil?
+
+      @stack_ptr += 1
+
+      if @stack_ptr >= @middlewares.size
+        raise RuntimeError, "Middleware chain exhausted, last object should not have called _next:"
+      end
+
+      middleware = @middlewares[@stack_ptr]
+
+      if middleware.is_a?(Class) && !middleware.respond_to?(:call)
+        middleware = middleware.new
+      end
+
+      middleware.is_a?(Instruct::MiddlewareChain) ? middleware.execute(req) : middleware.call(req, _next: self)
+    end
+
+  end
+end

data/lib/instruct/utils/serializable_with_version.rb

@@ -0,0 +1,73 @@
+require 'psych'
+
+module Instruct
+
+  module Serializable
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@_instruct_serializer_version, 1) unless base.instance_variable_defined?(:@_instruct_serializer_version)
+      base.instance_variable_set(:@_instruct_serializer_class_id, base.name.hash) unless base.instance_variable_defined?(:@_instruct_serializer_class_id)
+      Serializer::ClassRegistry.register(base.instruct_class_id, base)
+    end
+
+    module ClassMethods
+      def instruct_class_id
+        @_instruct_serializer_class_id
+      end
+
+      def instruct_class_version
+        @_instruct_serializer_version
+      end
+
+      def set_instruct_class_id(id)
+        @_instruct_serializer_class_id = id
+        Serializer::ClassRegistry.register(@_instruct_serializer_class_id, self)
+      end
+
+      def set_instruct_class_id_from_original_name(name)
+        set_instruct_class_id(name.hash)
+      end
+
+      def set_instruct_class_version(v)
+        @_instruct_serializer_version = v
+      end
+
+      def migrate_data!(data, from:, to:)
+        # no-op by default
+      end
+    end
+
+    def encode_with(coder)
+      coder.tag = "!ruby/instruct:#{self.class.instruct_class_id}@#{self.class.instruct_class_version}"
+      coder["data"] = instance_vars_to_hash
+      # TODO: consider calling the old encode_with method if defined
+      # and then this special case can be moved to prompt
+      coder["str"] = self.to_s(gen: :nochange) if self.is_a? Prompt
+      coder["str"] = self.to_s if coder["str"].nil? && self.is_a?(String)
+    end
+
+    def init_with(coder)
+      version = coder["version"]
+      if self.is_a? String
+        replace(coder["str"])
+      end
+      data = coder["data"] || {}
+
+
+      if version < self.class.instruct_class_version
+        self.class.migrate_data!(data, from: version, to: self.class.instruct_class_version)
+      end
+      hash_to_instance_vars(data)
+    end
+
+    private
+
+    def instance_vars_to_hash
+      Hash[instance_variables.map { |ivar| [ivar.to_s.sub('@', ''), instance_variable_get(ivar)] }]
+    end
+
+    def hash_to_instance_vars(data)
+      data.each { |k, v| instance_variable_set("@#{k}", v) }
+    end
+  end
+end