ruby_llm-schema 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af385c490955340f248b031be93c2f3667b8bb3163b705469d0cfce7d18e428f
-  data.tar.gz: 3636b4f7d55eabf5399396f8a708d26d611f2afb6bd9677bb6a1a189b9fe03ef
+  metadata.gz: 4706281dcd180f4d6e2b385cc42b79d73629d8eb8a7b5723ddde3b2786a5022e
+  data.tar.gz: eb083d6fa029a0b107f7a728c86e9f8342a1b9d0c3d0a46d8d4d33adaacd756a
 SHA512:
-  metadata.gz: 9db25536a6c7f3cb32a6cba0e91d88665833f25e6ea51f630be4ea18aa8d50ab7809e13e31d3dce4f0cd757be36754dca6fd3063832a6dd9a91129c07903087d
-  data.tar.gz: 486daf28cc008eda346b7c4c1b33f5723fac2f50947ae8197fba8fa6a23d9f50921a36533c37f60942cde6b5f030260045a779066546581d67b209fd76867818
+  metadata.gz: bc52ea4b47664561909278ece104676ae5053572aa791fe6985deb1ecdf40421e49b3b02529ba2a02cbb1df068484d6d162ec0d4c8d525105111ced98451fcbf
+  data.tar.gz: df555cdab1fb1c786ee0425fb5a1c0dd61bd5ed6c35dfc53bb355cdad27b462c5dbd84cb5d8fb32db6fdbe2c364916f0c8d2ed32565bff87c8ca17b79915ee03

data/README.md

@@ -2,6 +2,17 @@
 
 A Ruby DSL for creating JSON schemas with a clean, Rails-inspired API. Perfect for defining structured data schemas for LLM function calling or structured outputs.
 
+## Use Cases
+
+Structured output is a powerful tool for LLMs to generate consistent and predictable responses.
+
+Some ideal use cases:
+
+- Extracting *metadata, topics, and summary* from articles or blog posts
+- Organizing unstructured feedback or reviews with *sentiment and summary* 
+- Defining structured *actions* from user messages or emails
+- Extracting *entities and relationships* from documents
+
 ### Simple Example
 
 ```ruby
@@ -122,29 +133,83 @@ end
 puts person_schema.to_json
 ```
 
-## Field Types
+## Schema Property Types
+
+A schema is a collection of properties, which can be of different types. Each type has its own set of properties you can set.
+
+All property types can (along with the required `name` key) be set with a `description` and a `required` flag (default is `true`).
+
+```ruby
+string :name, description: "Person's full name"
+number :age, description: "Person's age", required: false
+boolean :is_active, description: "Whether the person is active"
+null :placeholder, description: "A placeholder property"
+```
+
+⚠️ Please consult the LLM provider documentation for any limitations or restrictions. For example, as of now, OpenAI requires all properties to be required. In that case, you can use the `any_of` method to make a property optional.
+
+```ruby
+any_of :name, description: "Person's full name" do
+  string
+  null
+end
+```
+
+### Strings
+
+String types support the following properties:
+
+- `enum`: an array of allowed values (e.g. `enum: ["on", "off"]`)
+- `pattern`: a regex pattern (e.g. `pattern: "\\d+"`)
+- `format`: a format string (e.g. `format: "email"`)
+- `min_length`: the minimum length of the string (e.g. `min_length: 3`)
+- `max_length`: the maximum length of the string (e.g. `max_length: 10`)
+
+Please consult the LLM provider documentation for the available formats and patterns.
+
+```ruby
+string :name, description: "Person's full name"
+string :email, format: "email"
+string :phone, pattern: "\\d+"
+string :status, enum: ["on", "off"]
+string :code, min_length: 3, max_length: 10
+```
+
+### Numbers
 
-### Primitive Types
+Number types support the following properties:
+
+- `multiple_of`: a multiple of the number (e.g. `multiple_of: 0.01`)
+- `minimum`: the minimum value of the number (e.g. `minimum: 0`)
+- `maximum`: the maximum value of the number (e.g. `maximum: 100`)
 
 ```ruby
-string :name                          # Required string
-string :title, required: false        # Optional string
-string :status, enum: ["on", "off"]   # String with enum values
-string :email, format: "email"        # String with format validation
-string :code, min_length: 3, max_length: 10  # String with length constraints
-string :pattern_field, pattern: "\\d+"  # String with regex pattern
+number :price, minimum: 0, maximum: 100
+number :amount, multiple_of: 0.01
+```
 
-number :count                         # Required number
-number :price, minimum: 0, maximum: 100  # Number with range constraints
-number :amount, multiple_of: 0.01     # Number with precision constraints
+### Booleans
 
-integer :id                           # Required integer
-boolean :active                       # Required boolean
-null :placeholder                     # Null type
+```ruby
+boolean :is_active
 ```
 
+Boolean types doesn't support any additional properties.
+
+### Null
+
+```ruby
+null :placeholder
+```
+
+Null types doesn't support any additional properties.
+
 ### Arrays
 
+An array is a list of items. You can set the type of the items in the array with the `of` option or by passing a block with the `object` method.
+
+An array can have a `min_items` and `max_items` option to set the minimum and maximum number of items in the array.
+
 ```ruby
 array :tags, of: :string              # Array of strings
 array :scores, of: :number            # Array of numbers
@@ -160,6 +225,8 @@ end
 
 ### Objects
 
+Objects types expect a block with the properties of the object.
+
 ```ruby
 object :user do
   string :name
@@ -174,6 +241,8 @@ end
 
 ### Union Types (anyOf)
 
+Union types are a way to specify that a property can be one of several types.
+
 ```ruby
 any_of :value do
   string
@@ -189,6 +258,8 @@ end
 
 ### Schema Definitions and References
 
+You can define sub-schemas and reference them in other schemas.
+
 ```ruby
 class MySchema < RubyLLM::Schema
   define :location do

data/Rakefile

@@ -3,3 +3,10 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "standard/rake"
+
+# Load custom tasks
+Dir.glob("lib/tasks/**/*.rake").each { |r| load r }
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[standard spec]

data/lib/ruby_llm/schema/dsl.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Schema
+    module DSL
+      # Primitive type methods
+      def string(name = nil, enum: nil, description: nil, required: true, min_length: nil, max_length: nil, pattern: nil, format: nil)
+        options = {
+          enum: enum,
+          description: description,
+          minLength: min_length,
+          maxLength: max_length,
+          pattern: pattern,
+          format: format
+        }.compact
+
+        add_property(name, build_property_schema(:string, **options), required: required)
+      end
+
+      def number(name = nil, description: nil, required: true, minimum: nil, maximum: nil, multiple_of: nil)
+        options = {
+          description: description,
+          minimum: minimum,
+          maximum: maximum,
+          multipleOf: multiple_of
+        }.compact
+
+        add_property(name, build_property_schema(:number, **options), required: required)
+      end
+
+      def integer(name = nil, description: nil, required: true)
+        add_property(name, build_property_schema(:integer, description: description), required: required)
+      end
+
+      def boolean(name = nil, description: nil, required: true)
+        add_property(name, build_property_schema(:boolean, description: description), required: required)
+      end
+
+      def null(name = nil, description: nil, required: true)
+        add_property(name, build_property_schema(:null, description: description), required: required)
+      end
+
+      # Complex type methods
+      def object(name = nil, description: nil, required: true, &block)
+        add_property(name, build_property_schema(:object, description: description, &block), required: required)
+      end
+
+      def array(name, of: nil, description: nil, required: true, min_items: nil, max_items: nil, &block)
+        items = determine_array_items(of, &block)
+
+        add_property(name, {
+          type: "array",
+          description: description,
+          items: items,
+          minItems: min_items,
+          maxItems: max_items
+        }.compact, required: required)
+      end
+
+      def any_of(name = nil, required: true, description: nil, &block)
+        schemas = collect_property_schemas_from_block(&block)
+
+        add_property(name, {
+          description: description,
+          anyOf: schemas
+        }.compact, required: required)
+      end
+
+      def optional(name, description: nil, &block)
+        any_of(name, description: description) do
+          instance_eval(&block)
+          null
+        end
+      end
+
+      # Schema definition and reference methods
+      def define(name, &)
+        sub_schema = Class.new(Schema)
+        sub_schema.class_eval(&)
+
+        definitions[name] = {
+          type: "object",
+          properties: sub_schema.properties,
+          required: sub_schema.required_properties
+        }
+      end
+
+      def reference(schema_name)
+        {"$ref" => "#/$defs/#{schema_name}"}
+      end
+
+      # Schema building methods
+      def build_property_schema(type, **options, &)
+        case type
+        when :string
+          {
+            type: "string",
+            enum: options[:enum],
+            description: options[:description],
+            minLength: options[:minLength],
+            maxLength: options[:maxLength],
+            pattern: options[:pattern],
+            format: options[:format]
+          }.compact
+        when :number
+          {
+            type: "number",
+            description: options[:description],
+            minimum: options[:minimum],
+            maximum: options[:maximum],
+            multipleOf: options[:multipleOf]
+          }.compact
+        when :integer
+          {
+            type: "integer",
+            description: options[:description],
+            minimum: options[:minimum],
+            maximum: options[:maximum],
+            multipleOf: options[:multipleOf]
+          }.compact
+        when :boolean
+          {type: "boolean", description: options[:description]}.compact
+        when :null
+          {type: "null", description: options[:description]}.compact
+        when :object
+          sub_schema = Class.new(Schema)
+          sub_schema.class_eval(&)
+
+          {
+            type: "object",
+            properties: sub_schema.properties,
+            required: sub_schema.required_properties,
+            additionalProperties: additional_properties,
+            description: options[:description]
+          }.compact
+        when :any_of
+          schemas = collect_property_schemas_from_block(&)
+          {
+            anyOf: schemas
+          }.compact
+        else
+          raise InvalidSchemaTypeError, type
+        end
+      end
+
+      private
+
+      def add_property(name, definition, required:)
+        properties[name.to_sym] = definition
+        required_properties << name.to_sym if required
+      end
+
+      def determine_array_items(of, &)
+        return collect_property_schemas_from_block(&).first if block_given?
+        return build_property_schema(of) if primitive_type?(of)
+        return reference(of) if of.is_a?(Symbol)
+
+        raise InvalidArrayTypeError, of
+      end
+
+      def collect_property_schemas_from_block(&block)
+        schemas = []
+        schema_builder = self  # Capture the current context that has build_property_schema
+
+        context = Object.new
+        context.define_singleton_method(:string) { |name = nil, **options| schemas << schema_builder.build_property_schema(:string, **options) }
+        context.define_singleton_method(:number) { |name = nil, **options| schemas << schema_builder.build_property_schema(:number, **options) }
+        context.define_singleton_method(:integer) { |name = nil, **options| schemas << schema_builder.build_property_schema(:integer, **options) }
+        context.define_singleton_method(:boolean) { |name = nil, **options| schemas << schema_builder.build_property_schema(:boolean, **options) }
+        context.define_singleton_method(:null) { |name = nil, **options| schemas << schema_builder.build_property_schema(:null, **options) }
+        context.define_singleton_method(:object) { |name = nil, **options, &blk| schemas << schema_builder.build_property_schema(:object, **options, &blk) }
+        context.define_singleton_method(:any_of) { |name = nil, **options, &blk| schemas << schema_builder.build_property_schema(:any_of, **options, &blk) }
+
+        context.instance_eval(&block)
+        schemas
+      end
+
+      def primitive_type?(type)
+        type.is_a?(Symbol) && PRIMITIVE_TYPES.include?(type)
+      end
+    end
+  end
+end

data/lib/ruby_llm/schema/helpers.rb

@@ -7,4 +7,4 @@ module RubyLLM
       schema_class.new(name, description: description)
     end
   end
-end 
+end

data/lib/ruby_llm/schema/json_output.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Schema
+    module JsonOutput
+      def to_json_schema
+        validate!  # Validate schema before generating JSON
+
+        {
+          name: @name,
+          description: @description || self.class.description,
+          schema: {
+            :type => "object",
+            :properties => self.class.properties,
+            :required => self.class.required_properties,
+            :additionalProperties => self.class.additional_properties,
+            :strict => self.class.strict,
+            "$defs" => self.class.definitions
+          }
+        }
+      end
+
+      def to_json(*_args)
+        validate!  # Validate schema before generating JSON string
+        JSON.pretty_generate(to_json_schema)
+      end
+    end
+  end
+end

data/lib/ruby_llm/schema/validator.rb

@@ -32,7 +32,7 @@ module RubyLLM
 
         # Initialize all nodes as WHITE (no mark)
         marks = Hash.new { WHITE }
-        
+
         # Visit each unmarked node
         definitions.each_key do |node|
           visit(node, definitions, marks) if marks[node] == WHITE
@@ -43,7 +43,7 @@ module RubyLLM
       def visit(node, definitions, marks)
         # If node has a permanent mark, return
         return if marks[node] == BLACK
-        
+
         # If node has a temporary mark, we found a cycle
         if marks[node] == GRAY
           raise ValidationError, "Circular reference detected involving '#{node}'"
@@ -51,7 +51,7 @@ module RubyLLM
 
         # Mark node with temporary mark
         marks[node] = GRAY
-        
+
         # Visit all adjacent nodes (dependencies)
         definition = definitions[node]
         if definition && definition[:properties]
@@ -62,14 +62,14 @@ module RubyLLM
             end
           end
         end
-        
+
         # Mark node with permanent mark
         marks[node] = BLACK
       end
 
       def extract_references(property)
         references = []
-        
+
         case property
         when Hash
           if property["$ref"]
@@ -92,4 +92,4 @@ module RubyLLM
       end
     end
   end
-end 
+end

data/lib/ruby_llm/schema/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLlm
   class Schema
-    VERSION = "0.1.5"
+    VERSION = "0.1.7"
   end
 end

data/lib/ruby_llm/schema.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 require_relative "schema/version"
-require_relative "schema/property_schema_collector"
 require_relative "schema/errors"
 require_relative "schema/helpers"
 require_relative "schema/validator"
+require_relative "schema/dsl"
+require_relative "schema/json_output"
 require "json"
-require "set"
 
 module RubyLLM
   class Schema
+    extend DSL
+    include JsonOutput
+
     PRIMITIVE_TYPES = %i[string number integer boolean null].freeze
 
     class << self
@@ -19,104 +22,6 @@ module RubyLLM
         schema_class
       end
 
-      def description(description = nil)
-        @description = description if description
-        @description
-      end
-
-      def additional_properties(value = nil)
-        return @additional_properties ||= false if value.nil?
-        @additional_properties = value
-      end
-
-      def strict(value = nil)
-        return @strict ||= true if value.nil?
-        @strict = value
-      end
-
-      def string(name = nil, enum: nil, description: nil, required: true, min_length: nil, max_length: nil, pattern: nil, format: nil)
-        options = {
-          enum: enum,
-          description: description,
-          minLength: min_length,
-          maxLength: max_length,
-          pattern: pattern,
-          format: format
-        }.compact
-        
-        add_property(name, build_property_schema(:string, **options), required: required)
-      end
-
-      def number(name = nil, description: nil, required: true, minimum: nil, maximum: nil, multiple_of: nil)
-        options = {
-          description: description,
-          minimum: minimum,
-          maximum: maximum,
-          multipleOf: multiple_of
-        }.compact
-        
-        add_property(name, build_property_schema(:number, **options), required: required)
-      end
-
-      def integer(name = nil, description: nil, required: true)
-        add_property(name, build_property_schema(:integer, description: description), required: required)
-      end
-
-      def boolean(name = nil, description: nil, required: true)
-        add_property(name, build_property_schema(:boolean, description: description), required: required)
-      end
-
-      def null(name = nil, description: nil, required: true)
-        add_property(name, build_property_schema(:null, description: description), required: required)
-      end
-
-      def object(name = nil, description: nil, required: true, &block)
-        add_property(name, build_property_schema(:object, description: description, &block), required: required)
-      end
-
-      def array(name, of: nil, description: nil, required: true, min_items: nil, max_items: nil, &block)
-        items = determine_array_items(of, &block)
-
-        add_property(name, {
-          type: "array",
-          description: description,
-          items: items,
-          minItems: min_items,
-          maxItems: max_items
-        }.compact, required: required)
-      end
-
-      def any_of(name, required: true, description: nil, &block)
-        schemas = collect_property_schemas_from_block(&block)
-
-        add_property(name, {
-          description: description,
-          anyOf: schemas
-        }.compact, required: required)
-      end
-
-      def optional(name, description: nil, &block)
-        any_of(name, description: description) do
-          instance_eval(&block)
-          null
-        end
-      end
-
-      def define(name, &)
-        sub_schema = Class.new(Schema)
-        sub_schema.class_eval(&)
-
-        definitions[name] = {
-          type: "object",
-          properties: sub_schema.properties,
-          required: sub_schema.required_properties
-        }
-      end
-
-      def reference(schema_name)
-        {"$ref" => "#/$defs/#{schema_name}"}
-      end
-
       def properties
         @properties ||= {}
       end
@@ -129,52 +34,21 @@ module RubyLLM
         @definitions ||= {}
       end
 
-      def build_property_schema(type, **options, &)
-        case type
-        when :string
-          {
-            type: "string",
-            enum: options[:enum],
-            description: options[:description],
-            minLength: options[:minLength],
-            maxLength: options[:maxLength],
-            pattern: options[:pattern],
-            format: options[:format]
-          }.compact
-        when :number
-          {
-            type: "number",
-            description: options[:description],
-            minimum: options[:minimum],
-            maximum: options[:maximum],
-            multipleOf: options[:multipleOf]
-          }.compact
-        when :integer
-          {
-            type: "integer",
-            description: options[:description],
-            minimum: options[:minimum],
-            maximum: options[:maximum],
-            multipleOf: options[:multipleOf]
-          }.compact
-        when :boolean
-          {type: "boolean", description: options[:description]}.compact
-        when :null
-          {type: "null", description: options[:description]}.compact
-        when :object
-          sub_schema = Class.new(Schema)
-          sub_schema.class_eval(&)
+      def description(description = nil)
+        @description = description if description
+        @description
+      end
+
+      def additional_properties(value = nil)
+        return @additional_properties ||= false if value.nil?
+        @additional_properties = value
+      end
 
-          {
-            type: "object",
-            properties: sub_schema.properties,
-            required: sub_schema.required_properties,
-            additionalProperties: additional_properties,
-            description: options[:description]
-          }.compact
-        else
-          raise InvalidSchemaTypeError, type
+      def strict(value = nil)
+        if value.nil?
+          return @strict.nil? ? (@strict = true) : @strict
         end
+        @strict = value
       end
 
       def validate!
@@ -186,31 +60,6 @@ module RubyLLM
         validator = Validator.new(self)
         validator.valid?
       end
-
-      private
-
-      def add_property(name, definition, required:)
-        properties[name.to_sym] = definition
-        required_properties << name.to_sym if required
-      end
-
-      def determine_array_items(of, &)
-        return collect_property_schemas_from_block(&).first if block_given?
-        return build_property_schema(of) if primitive_type?(of)
-        return reference(of) if of.is_a?(Symbol)
-
-        raise InvalidArrayTypeError, of
-      end
-
-      def collect_property_schemas_from_block(&)
-        collector = PropertySchemaCollector.new
-        collector.collect(&)
-        collector.schemas
-      end
-
-      def primitive_type?(type)
-        type.is_a?(Symbol) && PRIMITIVE_TYPES.include?(type)
-      end
     end
 
     def initialize(name = nil, description: nil)
@@ -218,28 +67,6 @@ module RubyLLM
       @description = description
     end
 
-    def to_json_schema
-      validate!  # Validate schema before generating JSON
-      
-      {
-        name: @name,
-        description: @description,
-        schema: {
-          :type => "object",
-          :properties => self.class.properties,
-          :required => self.class.required_properties,
-          :additionalProperties => self.class.additional_properties,
-          :strict => self.class.strict,
-          "$defs" => self.class.definitions
-        }
-      }
-    end
-
-    def to_json(*_args)
-      validate!  # Validate schema before generating JSON string
-      JSON.pretty_generate(to_json_schema)
-    end
-
     def validate!
       self.class.validate!
     end
@@ -250,7 +77,7 @@ module RubyLLM
 
     def method_missing(method_name, ...)
       if respond_to_missing?(method_name)
-        send(method_name, ...)
+        self.class.send(method_name, ...)
       else
         super
       end

data/lib/tasks/release.rake

@@ -1,13 +1,22 @@
 namespace :release do
   desc "Release a new version of the gem"
-  task :version do
+  task :version, [:message] do |t, args|
     # Load the current version from version.rb
-    require_relative '../../lib/ruby_llm/schema/version'
+    require_relative "../../lib/ruby_llm/schema/version"
     version = RubyLlm::Schema::VERSION
-    
+
     puts "Releasing version #{version}..."
-    
-    system "git tag v#{version}"
+
+    # Create git tag with optional message
+    # rake release:version["Fix critical bug in schema validation"]
+    if args[:message]
+      system "git tag -a v#{version} -m \"#{args[:message]}\""
+      puts "Created annotated tag v#{version} with message: #{args[:message]}"
+    else
+      system "git tag v#{version}"
+      puts "Created lightweight tag v#{version}"
+    end
+
     system "git push origin main"
     system "git push origin v#{version}"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-schema
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Daniel Friis
 bindir: exe
 cert_chain: []
-date: 2025-08-08 00:00:00.000000000 Z
+date: 2025-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -48,9 +48,10 @@ files:
 - README.md
 - Rakefile
 - lib/ruby_llm/schema.rb
+- lib/ruby_llm/schema/dsl.rb
 - lib/ruby_llm/schema/errors.rb
 - lib/ruby_llm/schema/helpers.rb
-- lib/ruby_llm/schema/property_schema_collector.rb
+- lib/ruby_llm/schema/json_output.rb
 - lib/ruby_llm/schema/validator.rb
 - lib/ruby_llm/schema/version.rb
 - lib/tasks/release.rake

data/lib/ruby_llm/schema/property_schema_collector.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  class Schema
-    class PropertySchemaCollector
-      attr_reader :schemas
-
-      def initialize
-        @schemas = []
-      end
-
-      def collect(&)
-        instance_eval(&)
-      end
-
-      def string(**options)
-        @schemas << Schema.build_property_schema(:string, **options)
-      end
-
-      def number(**options)
-        @schemas << Schema.build_property_schema(:number, **options)
-      end
-
-      def integer(**options)
-        @schemas << Schema.build_property_schema(:integer, **options)
-      end
-
-      def boolean(**options)
-        @schemas << Schema.build_property_schema(:boolean, **options)
-      end
-
-      def null(**options)
-        @schemas << Schema.build_property_schema(:null, **options)
-      end
-
-      def object(...)
-        @schemas << Schema.build_property_schema(:object, ...)
-      end
-    end
-  end
-end