rager 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c1c60d29be37b8a1f9ebb76d975257b26d89aa0345f3bdfb58290e61c82971
-  data.tar.gz: 47d3f41d9b7f9b08701c2b4b82e15cf7f86a7e3e4ffe9dced6e343ea28304597
+  metadata.gz: a240f204b0677aee45009f9357cea5e13b85eaa77dd9696db6e12e065f0144b4
+  data.tar.gz: 8d31692e3d8fe5d962ff4f2a9a94817a8886dd20f01eb72cbb24189deb490365
 SHA512:
-  metadata.gz: 6dfa77b1500bc0a2693141bff0c6551b72448d100f53f0e612b572d3b894ad5acc09f2cf3bb727d12141511bf902d28b3d43b2e359afc5d3fc9f172aae7caa06
-  data.tar.gz: d9522f23cd419a3b747f5e97e6097fc751008aedc3111954194de0253a24813a1919e0c5720cb653e51407e41173d80080461dadadb4590b716f638ea755444f
+  metadata.gz: 381d1ee7c8202be21536d209d3845039223709e7dd4e93c974f1970ce4b019f8538cac0bcb6cae7c8c15209e86bde9d6adb0e10d9e9b4546734744d4be7133dd
+  data.tar.gz: 34341e107e1018810723d9bdbd5f6e0b6fc69f66daf166860aec9f4513b29827479754ba84afe07cf5e9ece45cacf23c0e34f70f8fe896fd14c2b99d86a9f878

data/README.md

@@ -4,23 +4,65 @@
 [![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.
+
+Examples are available in the [`examples/`](./examples/) folder.
 
 ## Installation
 
-If you are using Bundler:
+Add this line to your application's Gemfile:
 
-```bash
-bundle add rager
+```ruby
+gem "rager", "~> 0.7.0"
 ```
 
-Otherwise you can add it to your Gemfile directly:
+Or use it in a standalone script (requires OPENAI_API_KEY set):
+
+```ruby
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "async-http", "~> 0.88.0"
+  gem "rager", "~> 0.7.0"
+end
+
+require "rager"
+
+Rager.configure do |config|
+  config.http_adapter = Rager::Http::Adapters::AsyncHttp.new
+end
+
+PROMPT = ARGV[0] || "Ruby programming"
 
-```Ruby
-gem "rager", "~> 0.4.0"
+Async do
+  ctx = Rager::Context.new
+  prompt = ctx.template("Tell me about the history of <%= topic %>",{topic: PROMPT})
+  chat = ctx.chat(prompt, stream: true)
+  chat.stream.each { |d| print d.content }
+end
 ```
 
+## Providers
+
+Modalities that take a URL parameter (chat, embedding, rerank) support compatible services, allowing you to use alternative providers that support the same interface.
+
+| Feature                | Providers        |
+| ---------------------- | ---------------- |
+| **Chat**               | `openai`         |
+| **Embedding**          | `openai`         |
+| **Image generation**   | `replicate`      |
+| **3D mesh generation** | `replicate`      |
+| **Reranking**          | `cohere`         |
+| **Search**             | `jina`           |
+| **Templating**         | `erb`,`mustache` |
+
+## Logging
+
+The main reason for creating yet another library is to have out-of-the-box logging for workflows and outcomes. The logged data can then be used for few-shot prompting and fine-tuning. This logging server is being developed at [`rager.cloud`](https://rager.cloud) and is closed while I work on it. Contact me if you would like access.
+
 ## License
 
 [MIT](./LICENSE.md)

data/lib/rager/chat/message.rb

@@ -6,8 +6,18 @@ require "sorbet-runtime"
 module Rager
   module Chat
     class Message < T::Struct
+      extend T::Sig
+
       const :role, MessageRole
       const :content, T.any(String, T::Array[MessageContent])
+
+      sig { params(options: T.untyped).returns(String) }
+      def to_json(options = nil)
+        {
+          role: role,
+          content: content
+        }.to_json(options)
+      end
     end
   end
 end

data/lib/rager/chat/message_content.rb

@@ -6,9 +6,16 @@ require "sorbet-runtime"
 module Rager
   module Chat
     class MessageContent < T::Struct
+      extend T::Sig
+
       const :type, MessageContentType, default: MessageContentType::Text
       const :image_type, T.nilable(MessageContentImageType)
       const :content, String
+
+      sig { params(options: T.untyped).returns(String) }
+      def to_json(options = nil)
+        serialize.to_json(options)
+      end
     end
   end
 end

data/lib/rager/chat/message_delta.rb

@@ -6,8 +6,15 @@ require "sorbet-runtime"
 module Rager
   module Chat
     class MessageDelta < T::Struct
+      extend T::Sig
+
       const :index, Integer, default: 0
       const :content, String
+
+      sig { params(options: T.untyped).returns(String) }
+      def to_json(options = nil)
+        serialize.to_json(options)
+      end
     end
   end
 end

data/lib/rager/chat/options.rb

@@ -10,20 +10,21 @@ module Rager
       extend T::Sig
       include Rager::Options
 
-      const :provider, String, default: "openai"
-      const :history, T::Array[Message], default: []
-      const :url, T.nilable(String)
-      const :api_key, T.nilable(String)
+      const :provider, Symbol, default: :openai
       const :model, T.nilable(String)
       const :stream, T.nilable(T::Boolean)
       const :n, T.nilable(Integer)
       const :temperature, T.nilable(Float)
+      const :max_tokens, T.nilable(Integer)
       const :system_prompt, T.nilable(String)
       const :schema, T.nilable(Dry::Schema::JSON)
       const :schema_name, T.nilable(String)
       const :seed, T.nilable(Integer)
+      const :url, T.nilable(String)
+      const :api_key, T.nilable(String)
+      const :timeout, T.nilable(Numeric)
 
-      sig { override.returns(T::Hash[String, T.untyped]) }
+      sig { override.returns(T::Hash[Symbol, T.untyped]) }
       def serialize_safe
         result = serialize
         result["api_key"] = "[REDACTED]" if result.key?("api_key")
@@ -35,15 +36,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
@@ -10,7 +11,8 @@ module Rager
       class Openai < Rager::Chat::Providers::Abstract
         extend T::Sig
 
-        OpenaiMessages = T.type_alias { T::Array[T::Hash[String, T.any(String, T::Array[T.untyped])]] }
+        OpenaiContentItem = T.type_alias { T::Hash[String, T.any(String, T::Hash[String, String])] }
+        OpenaiMessages = T.type_alias { T::Array[T::Hash[String, T.any(String, T::Array[OpenaiContentItem])]] }
 
         sig do
           override.params(
@@ -20,14 +22,24 @@ 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"
+          url = "#{base_url}/chat/completions"
+
+          headers = {
+            "Content-Type" => "application/json"
+          }.tap do |h|
+            h["Authorization"] = "Bearer #{api_key}" if api_key
+          end
 
           body = {
             model: options.model || "gpt-4.1",
-            messages: build_openai_messages(messages, options.history, options.system_prompt)
+            messages: build_openai_messages(messages, 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
 
@@ -43,20 +55,19 @@ module Rager
             end
           end
 
-          headers = {"Content-Type" => "application/json"}
-          headers["Authorization"] = "Bearer #{api_key}" if api_key
-
           request = Rager::Http::Request.new(
             verb: Rager::Http::Verb::Post,
-            url: options.url || ENV["OPENAI_URL"] || "https://api.openai.com/v1/chat/completions",
+            url: url,
             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)
@@ -64,39 +75,36 @@ module Rager
           end
         end
 
-        private
-
         sig do
           params(
             messages: T::Array[Rager::Chat::Message],
-            history: T::Array[Rager::Chat::Message],
             system_prompt: T.nilable(String)
           ).returns(OpenaiMessages)
         end
-        def build_openai_messages(messages, history, system_prompt)
-          result = T.let([], OpenaiMessages)
+        def build_openai_messages(messages, system_prompt)
+          output = T.let([], OpenaiMessages)
 
-          if history.empty? && system_prompt && !system_prompt.empty?
-            result << {"role" => "system", "content" => system_prompt}
+          if system_prompt
+            output << {"role" => "system", "content" => system_prompt}
           end
 
-          (history + messages).each do |message|
+          messages.each do |message|
             role = message.role.is_a?(String) ? message.role : message.role.serialize
             content = message.content
 
             case content
             when String
-              result << {"role" => role, "content" => content}
+              output << {"role" => role, "content" => content}
             when Array
               formatted_content = content.map { |item| format_content_item(item) }
-              result << {"role" => role, "content" => formatted_content}
+              output << {"role" => role, "content" => formatted_content}
             end
           end
 
-          result
+          output
         end
 
-        sig { params(item: Rager::Chat::MessageContent).returns(T::Hash[String, T.untyped]) }
+        sig { params(item: Rager::Chat::MessageContent).returns(OpenaiContentItem) }
         def format_content_item(item)
           case item.type
           when Rager::Chat::MessageContentType::Text
@@ -113,48 +121,56 @@ module Rager
           end
         end
 
-        sig { params(body: String).returns(T::Array[String]) }
+        sig { params(body: String).returns(Rager::Types::ChatNonStreamOutput) }
         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
-              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]"
-
-                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
-                  end
-                rescue JSON::ParserError
-                  next
-                end
+            buffer_parts = []
+            body.each do |chunk|
+              buffer_parts << chunk.force_encoding(Encoding::UTF_8)
+              buffer = buffer_parts.join
+              while (line = buffer.slice!(/.*\n/))
+                process_stream_line(line, yielder)
               end
+              buffer_parts = buffer.empty? ? [] : [buffer]
             end
 
-            body.each(&process_chunk)
-            process_chunk.call("\n") unless buffer.empty?
+            unless buffer_parts.empty?
+              process_stream_line(buffer_parts.join, yielder)
+            end
+          end
+        end
+
+        private
+
+        sig { params(line: String, yielder: Enumerator::Yielder).void.checked(:never) }
+        def process_stream_line(line, yielder)
+          line.delete_prefix!("data: ") or return
+          line.strip!
+          return if line.empty? || line == "[DONE]"
+
+          begin
+            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
+            nil
           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)
 
@@ -41,8 +42,6 @@ module Rager
           node.each { |item| make_strict_recursive!(item) }
         end
       end
-
-      private_class_method :make_strict_recursive!
     end
   end
 end

data/lib/rager/config.rb

@@ -7,40 +7,36 @@ module Rager
   class Config
     extend T::Sig
 
-    sig { returns(T.nilable(Rager::Logger)) }
-    attr_accessor :logger_type
-
     sig { returns(::Logger) }
     attr_accessor :logger
 
+    sig { returns(T::Boolean) }
+    attr_accessor :log_raise
+
+    sig { returns(Rager::LogStrategy) }
+    attr_accessor :log_strategy
+
+    sig { returns(Rager::Http::Adapters::Abstract) }
+    attr_accessor :http_adapter
+
     sig { returns(T.nilable(String)) }
     attr_accessor :url
 
     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))
-      @logger_type = T.let(nil, T.nilable(Rager::Logger))
       @logger = T.let(::Logger.new($stdout), ::Logger)
+      @log_raise = T.let(false, T::Boolean)
+      @log_strategy = T.let(Rager::LogStrategy::None, Rager::LogStrategy)
+      @http_adapter = T.let(Rager::Http::Adapters::NetHttp.new, Rager::Http::Adapters::Abstract)
       @url = T.let(nil, T.nilable(String))
       @api_key = T.let(nil, T.nilable(String))
-    end
-
-    sig { returns(Rager::Http::Adapters::Abstract) }
-    def http_adapter
-      @http_adapter ||= default_http_adapter
-    end
-
-    sig { params(http_adapter: Rager::Http::Adapters::Abstract).void }
-    attr_writer :http_adapter
-
-    private
-
-    sig { returns(Rager::Http::Adapters::Abstract) }
-    def default_http_adapter
-      Rager::Http::Adapters::AsyncHttp.new
+      @timeout = T.let(nil, T.nilable(Numeric))
     end
   end
 end