llm_ruby 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edf2b09bc3a9416193088298e41577369bf5198230c7278d6a832854f04c7e20
-  data.tar.gz: 735c0e1735d90e5c41a93d7e123bfe359c0a3525bf292ba46d0a6b8c23580c05
+  metadata.gz: d377d13dd257a9b4a6def17668d3bb3badf4692f9e865faba142d5189d746519
+  data.tar.gz: a201962fb8dd4f245face648cc433e127afcc22832cb1499da89db2bc2816d7e
 SHA512:
-  metadata.gz: d7509110f0f53028e6d6c6cc899ab31985748e2f5775be64286fc1a66659723953fee49f8ea70c1f797e9c7786bf401634d35f201d4b44d0f4abd11a22d691ed
-  data.tar.gz: 447086c9fed992e31db3e0bec1f9a92d0b52995ad899f11e9eeba0674eaf0a734918b4ee144a3b869ba6e61b7f2c73dcba2eaec5b602700d8c126a4de4c0ad33
+  metadata.gz: 10a190d6b7f4aa364c17d91b383a744fd490b94437ba4779c973e1f9bdc65d92f16d03c075d807d2a6aaf9509cf837736a0c48860c6ebc9d7c3dea6fb41eacd4
+  data.tar.gz: a3e63a044316a257c1e429bf85882c86ff78d3af193a87a978e4552f3464cdb417c7ada8aaf35a3556672ea6e79196812dada4c25c2f9a624466981b195c2ad3

data/README.md

@@ -1,5 +1,10 @@
 # LLMRuby
 
+[![Gem Version](https://badge.fury.io/rb/llm_ruby.svg)](https://badge.fury.io/rb/llm_ruby)
+![Workflow Status](https://github.com/agamble/llm_ruby/actions/workflows/main.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
 LLMRuby is a Ruby gem that provides a consistent interface for interacting with multiple Large Language Model (LLM) APIs. Most OpenAI, Anthropic and Gemini models are currently supported.
 
 ## Installation
@@ -166,6 +171,26 @@ export ANTHROPIC_API_KEY=your_api_key_here
 export GEMINI_API_KEY=your_api_key_here
 ```
 
+## Structured Outputs
+
+OpenAI and Gemini models can be configured to generate responses that adhere to a provided schema. Even though each use a different format for configuring this schema, `llm_ruby` can handle the translation for you, so that you can share a single schema definition across models.
+
+```ruby
+
+llm = LLM.from_string!("gpt-4o")
+
+# Create a client
+client = llm.client
+
+# Send a chat message
+response_format = LLM::Schema.new("test_schema", {"type" => "object", "properties" => {"name" => {"type" => "string"}, "age" => {"type" => "integer"}}, "additionalProperties" => false, "required" => ["name", "age"]})
+# or load the schema from a file: LLM::Schema.from_file('myschema.json')
+response = client.chat([{role: :user, content: "Hello, world!"}], response_format: response_format)
+
+response.structured_output[:name] # Alex
+response.structured_output_object.name # Alex
+```
+
 ## Development
 
 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.

data/lib/llm/clients/gemini/request.rb

@@ -14,9 +14,18 @@ class LLM
         end
 
         def params
+          generation_config = {}
+          if options[:response_format]
+            generation_config = {
+              responseMimeType: "application/json",
+              responseSchema: options[:response_format]&.gemini_response_format
+            }
+          end
+
           {
             systemInstruction: normalized_prompt,
-            contents: normalized_messages
+            contents: normalized_messages,
+            generationConfig: generation_config
           }
         end
 

data/lib/llm/clients/gemini/response.rb

@@ -12,7 +12,8 @@ class LLM
           LLM::Response.new(
             content: content,
             raw_response: parsed_response,
-            stop_reason: translated_stop_reason
+            stop_reason: translated_stop_reason,
+            structured_output: structured_output
           )
         end
 
@@ -48,6 +49,12 @@ class LLM
         def parsed_response
           raw_response.parsed_response
         end
+
+        def structured_output
+          @structured_output ||= JSON.parse(parsed_response.dig("candidates", 0, "content", "parts", 0, "text"))
+        rescue JSON::ParserError
+          nil
+        end
       end
     end
   end

data/lib/llm/clients/open_ai/response.rb

@@ -12,7 +12,8 @@ class LLM
           LLM::Response.new(
             content: content,
             raw_response: parsed_response,
-            stop_reason: normalize_stop_reason
+            stop_reason: normalize_stop_reason,
+            structured_output: structured_output
           )
         end
 
@@ -42,6 +43,12 @@ class LLM
         def parsed_response
           @raw_response.parsed_response
         end
+
+        def structured_output
+          @structured_output ||= JSON.parse(parsed_response.dig("choices", 0, "message", "content"))
+        rescue JSON::ParserError
+          nil
+        end
       end
     end
   end

data/lib/llm/clients/open_ai.rb

@@ -18,7 +18,7 @@ class LLM
           model: @llm.canonical_name,
           messages: messages,
           temperature: options[:temperature],
-          response_format: options[:response_format],
+          response_format: options[:response_format]&.response_format,
           max_tokens: options[:max_output_tokens],
           top_p: options[:top_p],
           stop: options[:stop_sequences],

data/lib/llm/info.rb

@@ -76,19 +76,22 @@ class LLM
         canonical_name: "gpt-4o",
         display_name: "GPT-4o",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "gpt-4o-mini",
         display_name: "GPT-4o Mini",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "gpt-4o-mini-2024-07-18",
         display_name: "GPT-4o Mini 2024-07-18",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "gpt-4o-2024-05-13",
@@ -100,13 +103,15 @@ class LLM
         canonical_name: "gpt-4o-2024-08-06",
         display_name: "GPT-4o 2024-08-06",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "gpt-4o-2024-11-20",
         display_name: "GPT-4o 2024-11-20",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "chatgpt-4o-latest",
@@ -118,13 +123,15 @@ class LLM
         canonical_name: "o1",
         display_name: "o1",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "o1-2024-12-17",
         display_name: "o1 2024-12-17",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "o1-preview",
@@ -154,13 +161,15 @@ class LLM
         canonical_name: "o3-mini",
         display_name: "o3 Mini",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "o3-mini-2025-01-31",
         display_name: "o3 Mini 2025-01-31",
         provider: :openai,
-        client_class: LLM::Clients::OpenAI
+        client_class: LLM::Clients::OpenAI,
+        supports_structured_outputs: true
       },
 
       # Anthropic Models
@@ -224,13 +233,15 @@ class LLM
         canonical_name: "gemini-2.0-flash",
         display_name: "Gemini 2.0 Flash",
         provider: :google,
-        client_class: LLM::Clients::Gemini
+        client_class: LLM::Clients::Gemini,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "gemini-2.0-flash-lite-preview-02-05",
         display_name: "Gemini 2.0 Flash Lite Preview 02-05",
         provider: :google,
-        client_class: LLM::Clients::Gemini
+        client_class: LLM::Clients::Gemini,
+        supports_structured_outputs: true
       },
       {
         canonical_name: "gemini-1.5-flash-8b",

data/lib/llm/response.rb

@@ -1,3 +1,11 @@
 # frozen_string_literal: true
 
-LLM::Response = Struct.new(:content, :raw_response, :stop_reason, keyword_init: true)
+require "ostruct"
+
+LLM::Response = Struct.new(:content, :raw_response, :stop_reason, :structured_output, keyword_init: true) do
+  def structured_output_object
+    return nil unless structured_output
+
+    OpenStruct.new(structured_output)
+  end
+end

data/lib/llm/schema.rb

@@ -0,0 +1,75 @@
+class LLM
+  class Schema
+    def initialize(name, schema)
+      @name = name
+      @schema = schema
+    end
+
+    def self.from_file(file_path)
+      new(File.basename(file_path, ".json"), JSON.parse(File.read(file_path)))
+    end
+
+    def response_format
+      {
+        type: "json_schema",
+        json_schema: {
+          name: @name,
+          strict: true,
+          schema: @schema
+        }
+      }
+    end
+
+    def gemini_response_format
+      transform_schema(@schema)
+    end
+
+    def transform_schema(schema)
+      # Initialize the result as an empty hash.
+      openapi_schema = {}
+
+      # Process the "type" field and handle nullability.
+      if schema.key?("type")
+        if schema["type"].is_a?(Array)
+          # Check for "null" in the type array to mark the schema as nullable.
+          if schema["type"].include?("null")
+            openapi_schema["nullable"] = true
+            # Remove "null" from the type array; if a single type remains, use that.
+            remaining_types = schema["type"] - ["null"]
+            openapi_schema["type"] = (remaining_types.size == 1) ? remaining_types.first : remaining_types
+          else
+            openapi_schema["type"] = schema["type"]
+          end
+        else
+          openapi_schema["type"] = schema["type"]
+        end
+      end
+
+      # Map simple fields directly: "format", "description", "enum", "maxItems", "minItems".
+      ["format", "description", "enum", "maxItems", "minItems"].each do |field|
+        openapi_schema[field] = schema[field] if schema.key?(field)
+      end
+
+      # Recursively process "properties" if present.
+      if schema.key?("properties") && schema["properties"].is_a?(Hash)
+        openapi_schema["properties"] = {}
+        schema["properties"].each do |prop, prop_schema|
+          openapi_schema["properties"][prop] = transform_schema(prop_schema)
+        end
+      end
+
+      # Copy "required" if present.
+      openapi_schema["required"] = schema["required"] if schema.key?("required")
+
+      # Copy "propertyOrdering" if present (non-standard field).
+      openapi_schema["propertyOrdering"] = schema["propertyOrdering"] if schema.key?("propertyOrdering")
+
+      # Recursively process "items" for array types.
+      if schema.key?("items")
+        openapi_schema["items"] = transform_schema(schema["items"])
+      end
+
+      openapi_schema
+    end
+  end
+end

data/lib/llm.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require "zeitwerk"
+
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "llm" => "LLM",
   "open_ai" => "OpenAI"
 )
+loader.ignore("#{__dir__}/llm_ruby.rb")
 loader.setup
 
 class LLM
@@ -15,6 +17,7 @@ class LLM
     @provider = model[:provider]
     @client_class = model[:client_class]
     @default_params = model[:additional_default_required_parameters] || {}
+    @supports_structured_outputs = model[:supports_structured_outputs] || false
   end
 
   def client
@@ -26,6 +29,10 @@ class LLM
     :provider,
     :default_params
 
+  def supports_structured_outputs?
+    @supports_structured_outputs
+  end
+
   private
 
   attr_reader :client_class

data/lib/llm_ruby.rb

@@ -0,0 +1 @@
+require "llm"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: llm_ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Alex Gamble
 bindir: exe
 cert_chain: []
-date: 2025-02-23 00:00:00.000000000 Z
+date: 2025-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -155,8 +155,10 @@ files:
 - lib/llm/info.rb
 - lib/llm/provider.rb
 - lib/llm/response.rb
+- lib/llm/schema.rb
 - lib/llm/stop_reason.rb
 - lib/llm/version.rb
+- lib/llm_ruby.rb
 homepage: https://github.com/agamble/llm_ruby
 licenses:
 - MIT