rager 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c1c60d29be37b8a1f9ebb76d975257b26d89aa0345f3bdfb58290e61c82971
-  data.tar.gz: 47d3f41d9b7f9b08701c2b4b82e15cf7f86a7e3e4ffe9dced6e343ea28304597
+  metadata.gz: 2036814b6f6bbe713486b60918b0d75222416ecf90eeb2e0fbf139c44d2d8c1f
+  data.tar.gz: d6e112b1c3d1189df8957aa219a0cee7d86735b4198ec355680fab25215e33aa
 SHA512:
-  metadata.gz: 6dfa77b1500bc0a2693141bff0c6551b72448d100f53f0e612b572d3b894ad5acc09f2cf3bb727d12141511bf902d28b3d43b2e359afc5d3fc9f172aae7caa06
-  data.tar.gz: d9522f23cd419a3b747f5e97e6097fc751008aedc3111954194de0253a24813a1919e0c5720cb653e51407e41173d80080461dadadb4590b716f638ea755444f
+  metadata.gz: f3c65b99f301a2e617a86c1bbd2ae3149cd1a7a473d688936f66e4321eaf1ead643f58e9d387dd7d9cb314e15188a4577f710188da3082c5753229a1ae8998bf
+  data.tar.gz: 80e6f853ccdee991e19ba3f921fc6b10023cc2c2620d92ccc40f9b796cd5037d2ddad694834d0df4e9ed5aa9fdd84554c97a8afc2b311c95f7cb94c565a56f95

data/README.md

@@ -4,23 +4,66 @@
 [![publish](https://github.com/mvkvc/rager_rb/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/mvkvc/rager_rb/actions/workflows/publish.yml)
 [![test](https://github.com/mvkvc/rager_rb/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/mvkvc/rager_rb/actions/workflows/test.yml)
 [![lint](https://github.com/mvkvc/rager_rb/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/mvkvc/rager_rb/actions/workflows/lint.yml)
+[![docs](https://github.com/mvkvc/rager_rb/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/mvkvc/rager_rb/actions/workflows/docs.yml)
 
-Build continuously improving AI applications.
+Build continuously improving generative workflows.
+
+## Providers
+
+| Feature                | Providers                      |
+| ---------------------- | ------------------------------ |
+| **Chat**               | `openai` (and compatible APIs) |
+| **Embedding**          | `openai` (and compatible APIs) |
+| **Image generation**   | `replicate`                    |
+| **3D mesh generation** | `replicate`                    |
+| **Rerank**             | `cohere` (and compatible APIs) |
+| **Search**             | `jina`                         |
+| **Templating**         | `erb` (built-in)               |
+
+## Logging
+
+The main reason for developing yet another library is to have an out-of-the-box compatible logging server that tracks AI workflows and outcomes. This data can be used to generate high-quality examples for few-shot prompting and fine-tuning. That server will be released soon, check back here for updates.
 
 ## Installation
 
-If you are using Bundler:
+Add this line to your application’s Gemfile:
 
-```bash
-bundle add rager
+```ruby
+gem "rager", "~> 0.6.0"
 ```
 
-Otherwise you can add it to your Gemfile directly:
+Or use it in a standalone script (example uses OPENAI_API_KEY env var):
+
+```ruby
+#!/usr/bin/env ruby
 
-```Ruby
-gem "rager", "~> 0.4.0"
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "async-http", "~> 0.88.0"
+  gem "rager", "~> 0.6.0"
+end
+
+require "rager"
+
+Rager.configure do |config|
+  config.http_adapter = Rager::Http::Adapters::AsyncHttp.new
+end
+
+Async do
+  ctx = Rager::Context.new
+  prompt = ctx.template(
+    "Tell me about the history of <%= topic %>:\n",
+    {topic: "Ruby programming"}
+  )
+  chat = ctx.chat(prompt, stream: true)
+  chat.out.each { |d| print d.content }
+end
 ```
 
+This library makes extensive use of `sorbet-runtime` for runtime type checking. To learn more, including how to disable it, please see the official Sorbet [documentation](https://sorbet.org/docs/overview).
+
 ## License
 
 [MIT](./LICENSE.md)

data/lib/rager/chat/options.rb

@@ -15,13 +15,15 @@ module Rager
       const :url, T.nilable(String)
       const :api_key, T.nilable(String)
       const :model, T.nilable(String)
-      const :stream, T.nilable(T::Boolean)
       const :n, T.nilable(Integer)
+      const :max_tokens, T.nilable(Integer)
       const :temperature, T.nilable(Float)
       const :system_prompt, T.nilable(String)
       const :schema, T.nilable(Dry::Schema::JSON)
       const :schema_name, T.nilable(String)
+      const :stream, T.nilable(T::Boolean)
       const :seed, T.nilable(Integer)
+      const :timeout, T.nilable(Numeric)
 
       sig { override.returns(T::Hash[String, T.untyped]) }
       def serialize_safe
@@ -35,15 +37,17 @@ module Rager
       def validate
         if stream && schema
           raise Rager::Errors::OptionsError.new(
-            invalid_keys: %w[stream schema],
-            description: "You cannot use streaming with structured outputs"
+            self,
+            ["stream", "schema"],
+            details: "You cannot use streaming with structured outputs"
           )
         end
 
         if schema && schema_name.nil?
           raise Rager::Errors::OptionsError.new(
-            invalid_keys: %w[schema schema_name],
-            description: "You must provide a schema name when using structured outputs"
+            self,
+            ["schema", "schema_name"],
+            details: "You must provide a schema name when using structured outputs"
           )
         end
       end

data/lib/rager/chat/providers/openai.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "json"
+
 require "sorbet-runtime"
 
 module Rager
@@ -20,14 +21,17 @@ module Rager
         end
         def chat(messages, options)
           api_key = options.api_key || ENV["OPENAI_API_KEY"]
-          raise Rager::Errors::MissingCredentialsError.new("OpenAI", "OPENAI_API_KEY") if api_key.nil?
+          raise Rager::Errors::CredentialsError.new("OpenAI", env_var: ["OPENAI_API_KEY"]) if api_key.nil?
+
+          base_url = options.url || ENV["OPENAI_URL"] || "https://api.openai.com/v1"
 
           body = {
             model: options.model || "gpt-4.1",
             messages: build_openai_messages(messages, options.history, options.system_prompt)
           }.tap do |b|
-            b[:temperature] = options.temperature if options.temperature
             b[:n] = options.n if options.n
+            b[:max_tokens] = options.max_tokens if options.max_tokens
+            b[:temperature] = options.temperature if options.temperature
             b[:stream] = options.stream if options.stream
             b[:seed] = options.seed if options.seed
 
@@ -48,15 +52,17 @@ module Rager
 
           request = Rager::Http::Request.new(
             verb: Rager::Http::Verb::Post,
-            url: options.url || ENV["OPENAI_URL"] || "https://api.openai.com/v1/chat/completions",
+            url: "#{base_url}/chat/completions",
             headers: headers,
-            body: body.to_json
+            body: body.to_json,
+            streaming: options.stream || false,
+            timeout: options.timeout || Rager.config.timeout
           )
 
           response = Rager.config.http_adapter.make_request(request)
           response_body = T.must(response.body)
 
-          raise Rager::Errors::HttpError.new(Rager.config.http_adapter, response.status, T.cast(response_body, String)) if response.status != 200
+          raise Rager::Errors::HttpError.new(Rager.config.http_adapter, request.url, response.status, body: T.cast(response_body, String)) if response.status != 200
 
           case response_body
           when String then handle_non_stream_body(response_body)
@@ -113,48 +119,43 @@ module Rager
           end
         end
 
-        sig { params(body: String).returns(T::Array[String]) }
+        sig { params(body: String).returns(Rager::Types::ChatNonStream) }
         def handle_non_stream_body(body)
           response_data = JSON.parse(body)
           return [] unless response_data.key?("choices") && response_data["choices"].is_a?(Array)
 
-          response_data["choices"].filter_map do |choice|
+          result = response_data["choices"].filter_map do |choice|
             text = choice.dig("message", "content").to_s
             text unless text.empty?
           end
+
+          result.one? ? result.first : result
         rescue JSON::ParserError
-          raise Rager::Errors::ParseError.new("OpenAI response body is not valid JSON", body)
+          raise Rager::Errors::ParseError.new(body, details: "OpenAI response body is not valid JSON")
         end
 
         sig { params(body: T::Enumerator[String]).returns(T::Enumerator[Rager::Chat::MessageDelta]) }
         def handle_stream_body(body)
           Enumerator.new do |yielder|
             buffer = +""
-
-            process_chunk = ->(chunk) do
+            body.each do |chunk|
               buffer << chunk
-              while (match = buffer.match(/\Adata: (.*?)\n\n|\Adata: (.*?)\n/))
-                buffer.delete_prefix!(T.must(match[0]))
-                data_line = match[1] || match[2]
-
-                next if data_line.nil? || data_line.strip.empty? || data_line.strip == "[DONE]"
+              while (line = buffer.slice!(/.*\n/))
+                line.delete_prefix!("data: ") or next
+                line.strip!
+                next if line.empty? || line == "[DONE]"
 
                 begin
-                  data = JSON.parse(data_line)
-                  next unless data.key?("choices") && data["choices"].is_a?(Array)
-
-                  data["choices"].each do |choice|
-                    delta = choice.dig("delta", "content")
-                    yielder << Rager::Chat::MessageDelta.new(index: choice.dig("index") || 0, content: delta) if delta
+                  JSON.parse(line).dig("choices")&.each do |choice|
+                    if (content = choice.dig("delta", "content"))
+                      yielder << Rager::Chat::MessageDelta.new(index: choice["index"] || 0, content: content)
+                    end
                   end
-                rescue JSON::ParserError
-                  next
+                rescue
+                  nil
                 end
               end
             end
-
-            body.each(&process_chunk)
-            process_chunk.call("\n") unless buffer.empty?
           end
         end
       end

data/lib/rager/chat/schema.rb

@@ -1,8 +1,9 @@
 # typed: strict
 # frozen_string_literal: true
 
-require "dry-schema"
 require "json"
+
+require "dry-schema"
 require "sorbet-runtime"
 
 Dry::Schema.load_extensions(:json_schema)
@@ -15,7 +16,7 @@ module Rager
       sig { params(schema: Dry::Schema::JSON).returns(T::Hash[Symbol, T.untyped]) }
       def self.dry_schema_to_json_schema(schema)
         json_schema_original = schema.json_schema
-        json_schema = JSON.parse(JSON.generate(json_schema_original).force_encoding("UTF-8"))
+        json_schema = JSON.parse(JSON.generate(json_schema_original))
 
         make_strict_recursive!(json_schema)
 

data/lib/rager/config.rb

@@ -19,6 +19,9 @@ module Rager
     sig { returns(T.nilable(String)) }
     attr_accessor :api_key
 
+    sig { returns(T.nilable(Numeric)) }
+    attr_accessor :timeout
+
     sig { void }
     def initialize
       @http_adapter = T.let(nil, T.nilable(Rager::Http::Adapters::Abstract))
@@ -26,6 +29,7 @@ module Rager
       @logger = T.let(::Logger.new($stdout), ::Logger)
       @url = T.let(nil, T.nilable(String))
       @api_key = T.let(nil, T.nilable(String))
+      @timeout = T.let(nil, T.nilable(Numeric))
     end
 
     sig { returns(Rager::Http::Adapters::Abstract) }
@@ -40,7 +44,7 @@ module Rager
 
     sig { returns(Rager::Http::Adapters::Abstract) }
     def default_http_adapter
-      Rager::Http::Adapters::AsyncHttp.new
+      Rager::Http::Adapters::NetHttp.new
     end
   end
 end

data/lib/rager/context.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
+
 require "sorbet-runtime"
 
 module Rager
@@ -14,58 +15,76 @@ module Rager
     sig { returns(T.nilable(String)) }
     attr_reader :name
 
-    sig { params(id: T.nilable(String), name: T.nilable(String)).void }
-    def initialize(id: nil, name: nil)
+    sig { returns(Integer) }
+    attr_reader :max_retries
+
+    sig { returns(Float) }
+    attr_reader :backoff
+
+    sig { params(id: T.nilable(String), name: T.nilable(String), max_retries: T.nilable(Integer), backoff: T.nilable(Float)).void }
+    def initialize(id: nil, name: nil, max_retries: nil, backoff: nil)
       @id = T.let(id || SecureRandom.uuid, String)
       @name = T.let(name, T.nilable(String))
+      @max_retries = T.let(max_retries || 0, Integer)
+      @backoff = T.let(backoff || 1.0, Float)
     end
 
     sig do
       params(
-        messages: T.any(String, Rager::Types::ChatInput),
+        messages: T.any(String, Rager::Types::ChatInput, Rager::Result),
         kwargs: T.untyped
       ).returns(Rager::Result)
     end
     def chat(messages, **kwargs)
-      if messages.is_a?(String)
-        messages = [
-          Rager::Chat::Message.new(
-            role: Rager::Chat::MessageRole::User,
-            content: messages
-          )
-        ]
-      end
-
       execute(
         Rager::Operation::Chat,
         Rager::Chat::Options,
         kwargs,
         messages
-      ) { |options| Chat.chat(messages, options) }
+      ) { |options, normalized_input|
+        final_input = if normalized_input.is_a?(String)
+          [
+            Rager::Chat::Message.new(
+              role: Rager::Chat::MessageRole::User,
+              content: normalized_input
+            )
+          ]
+        else
+          normalized_input
+        end
+
+        provider = Rager::Providers.get_provider(:chat, options.provider, options)
+        provider.chat(final_input, options)
+      }
     end
 
     sig do
       params(
-        text: T.any(String, Rager::Types::EmbedInput),
+        text: T.any(String, Rager::Types::EmbedInput, Rager::Result),
         kwargs: T.untyped
       ).returns(Rager::Result)
     end
     def embed(text, **kwargs)
-      if text.is_a?(String)
-        text = [text]
-      end
-
       execute(
         Rager::Operation::Embed,
         Rager::Embed::Options,
         kwargs,
         text
-      ) { |options| Embed.embed(text, options) }
+      ) { |options, normalized_input|
+        final_input = if normalized_input.is_a?(String)
+          [normalized_input]
+        else
+          normalized_input
+        end
+
+        provider = Rager::Providers.get_provider(:embed, options.provider, options)
+        provider.embed(final_input, options)
+      }
     end
 
     sig do
       params(
-        prompt: Rager::Types::ImageGenInput,
+        prompt: T.any(Rager::Types::ImageGenInput, Rager::Result),
         kwargs: T.untyped
       ).returns(Rager::Result)
     end
@@ -75,12 +94,15 @@ module Rager
         Rager::ImageGen::Options,
         kwargs,
         prompt
-      ) { |options| ImageGen.image_gen(prompt, options) }
+      ) { |options, normalized_input|
+        provider = Rager::Providers.get_provider(:image_gen, options.provider, options)
+        provider.image_gen(T.cast(normalized_input, Rager::Types::ImageGenInput), options)
+      }
     end
 
     sig do
       params(
-        prompt: Rager::Types::MeshGenInput,
+        prompt: T.any(Rager::Types::MeshGenInput, Rager::Result),
         kwargs: T.untyped
       ).returns(Rager::Result)
     end
@@ -90,27 +112,35 @@ module Rager
         Rager::MeshGen::Options,
         kwargs,
         prompt
-      ) { |options| MeshGen.mesh_gen(prompt, options) }
+      ) { |options, normalized_input|
+        provider = Rager::Providers.get_provider(:mesh_gen, options.provider, options)
+        provider.mesh_gen(T.cast(normalized_input, Rager::Types::MeshGenInput), options)
+      }
     end
 
     sig do
       params(
-        query: Rager::Types::RerankInput,
+        query: T.any(String, Rager::Result),
+        documents: T.any(T::Array[String], Rager::Result),
         kwargs: T.untyped
       ).returns(Rager::Result)
     end
-    def rerank(query, **kwargs)
+    def rerank(query, documents, **kwargs)
       execute(
         Rager::Operation::Rerank,
         Rager::Rerank::Options,
         kwargs,
-        query
-      ) { |options| Rager::Rerank.rerank(query, options) }
+        {query: query, documents: documents}
+      ) { |options, normalized_input|
+        provider = Rager::Providers.get_provider(:rerank, options.provider, options)
+        input_hash = T.cast(normalized_input, T::Hash[Symbol, T.untyped])
+        provider.rerank(input_hash[:query], input_hash[:documents], options)
+      }
     end
 
     sig do
       params(
-        query: Rager::Types::SearchInput,
+        query: T.any(Rager::Types::SearchInput, Rager::Result),
         kwargs: T.untyped
       ).returns(Rager::Result)
     end
@@ -120,22 +150,30 @@ module Rager
         Rager::Search::Options,
         kwargs,
         query
-      ) { |options| Search.search(query, options) }
+      ) { |options, normalized_input|
+        provider = Rager::Providers.get_provider(:search, options.provider, options)
+        provider.search(T.cast(normalized_input, Rager::Types::SearchInput), options)
+      }
     end
 
     sig do
       params(
-        input: Rager::Types::TemplateInput,
+        template: T.any(String, Rager::Result),
+        variables: T.any(T::Hash[Symbol, T.untyped], Rager::Result),
         kwargs: T.untyped
       ).returns(Rager::Result)
     end
-    def template(input, **kwargs)
+    def template(template, variables, **kwargs)
       execute(
         Rager::Operation::Template,
         Rager::Template::Options,
         kwargs,
-        input
-      ) { |options| Template.template(input, options) }
+        {template: template, variables: variables}
+      ) { |options, normalized_input|
+        provider = Rager::Providers.get_provider(:template, options.provider, options)
+        input_hash = T.cast(normalized_input, T::Hash[Symbol, T.untyped])
+        provider.template(input_hash[:template], input_hash[:variables], options)
+      }
     end
 
     private
@@ -145,53 +183,128 @@ module Rager
         operation: Rager::Operation,
         options_struct: T::Class[Rager::Options],
         kwargs: T.untyped,
-        input: Rager::Types::Input,
-        block: T.proc.params(options: T.untyped).returns(T.untyped)
+        input: T.any(Rager::Types::Input, Rager::Result, T::Hash[Symbol, T.untyped]),
+        block: T.proc.params(options: T.untyped, normalized_input: Rager::Types::Input).returns(T.untyped)
       ).returns(Rager::Result)
     end
     def execute(operation, options_struct, kwargs, input, &block)
       name = kwargs.delete(:name)
-      iids = kwargs.delete(:iids)
+      tags = kwargs.delete(:tags) || []
+
+      existing_input_ids = kwargs.delete(:input_ids) || []
+      normalized_input, new_input_ids = normalize_input(input)
+      input_ids = (existing_input_ids + new_input_ids).uniq
 
       options = options_struct.new(**kwargs)
       options.validate
 
       start_time = Time.now
+      errors = []
+      attempt = 0
 
       begin
-        output = yield(options)
+        output = yield(options, normalized_input)
 
         Result.new(
           id: SecureRandom.uuid,
           context_id: @id,
           operation: operation,
-          input: input,
+          input: normalized_input,
           output: output,
           options: options,
           start_time: start_time.to_i,
           end_time: Time.now.to_i,
           name: name,
           context_name: @name,
-          iids: iids,
-          error: nil
+          tags: tags,
+          input_ids: input_ids,
+          errors: errors,
+          attempt: attempt
         ).tap(&:log)
       rescue => e
-        Result.new(
-          id: SecureRandom.uuid,
-          context_id: @id,
-          operation: operation,
-          input: input,
-          output: nil,
-          options: options,
-          start_time: start_time.to_i,
-          end_time: Time.now.to_i,
-          name: name,
-          context_name: @name,
-          iids: iids,
-          error: e.message
-        ).tap(&:log)
+        errors << e.message
+        attempt += 1
+
+        if attempt < @max_retries
+          delay = @backoff * 2**attempt
+          Rager::Utils::Http.sleep(delay)
+          retry
+        else
+          Result.new(
+            id: SecureRandom.uuid,
+            context_id: @id,
+            operation: operation,
+            input: normalized_input,
+            output: nil,
+            options: options,
+            start_time: start_time.to_i,
+            end_time: Time.now.to_i,
+            name: name,
+            context_name: @name,
+            tags: tags,
+            input_ids: input_ids,
+            errors: errors,
+            attempt: attempt
+          ).tap(&:log)
+
+          raise e
+        end
+      end
+    end
+
+    sig { params(input: T.untyped, ids: T::Array[String]).returns([T.untyped, T::Array[String]]) }
+    def normalize_input(input, ids: [])
+      case input
+      when Rager::Result
+        ids << input.id unless ids.include?(input.id)
+
+        materialized_output = input.mat
+        normalized_output = case materialized_output
+        when Rager::Search::Output
+          materialized_output.contents
+        when Rager::Rerank::Output
+          materialized_output.documents
+        else
+          materialized_output
+        end
+
+        [normalized_output, ids]
+      when Hash
+        normalized_hash = {}
+        input.each do |key, value|
+          normalized_value, ids = normalize_input(value, ids: ids)
+          normalized_hash[key] = normalized_value
+        end
+        [normalized_hash, ids]
+      when Array
+        normalized_array = []
+        input.each do |item|
+          normalized_item, ids = normalize_input(item, ids: ids)
+          normalized_array << normalized_item
+        end
+        [normalized_array, ids]
+      else
+        [input, ids]
+      end
+    end
+
+    sig { returns(String) }
+    def to_json
+      {
+        id: @id,
+        name: @name,
+        max_retries: @max_retries,
+        backoff: @backoff
+      }.to_json
+    end
 
-        raise e
+    sig { params(json: String, id: T.nilable(String), name: T.nilable(String), max_retries: T.nilable(Integer), backoff: T.nilable(Float)).returns(Rager::Context) }
+    def from_json(json, id: nil, name: nil, max_retries: nil, backoff: nil)
+      JSON.parse(json, symbolize_names: true).tap do |data|
+        @id = id || data[:id]
+        @name = name || data[:name]
+        @max_retries = max_retries || data[:max_retries]
+        @backoff = backoff || data[:backoff]
       end
     end
   end

data/lib/rager/embed/options.rb

@@ -14,6 +14,7 @@ module Rager
       const :model, T.nilable(String)
       const :api_key, T.nilable(String)
       const :seed, T.nilable(Integer)
+      const :timeout, T.nilable(Numeric)
     end
   end
 end