ruby_llm-schema 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5965c9d64040358651a74d313d1bd50010378ca33b20ec46a26db8fb006e4e25
-  data.tar.gz: a4d9ac3040a6ce33fe0bbc4294166c00e8cafb5e87dcb336d47e1541b504dc12
+  metadata.gz: 5f012ca1be03cf52ab7ce3192e8b6054e970665aaf8f60d2ad962ec03a179535
+  data.tar.gz: 3edfb7c945fc88485d7eade5f4e2585135f9276b636bcf24bed52317f7a81880
 SHA512:
-  metadata.gz: d6ce13ba9d6164a794004fe1138f92ab8d141348d86b33163ad23c119425f252f57b585853ab73a21cff102de9cc403f8936f7b63d4b52d4a572795d8a340aad
-  data.tar.gz: 4edbb7d38e7fa1414a812d0fa87f6f20b24e19d2ceb1a151e476c1b330d2e6ac84cfc7faf4aa388858d322bbdaeccffcaa5002db4d19e5a68d5e263876b3db0f
+  metadata.gz: e57c7ef49715fe7f4ef0c02fa8166065f19dee3add0175a958d3748d3c3f9ba73105c2cc8954c3ccdfc5e429e3c480df552976ae62832da811ec25f2191a4731
+  data.tar.gz: e609b7e5f8c73790e07f2a96f979f6f43988730c8e8a0269d61e26d418649006fc07dd14a249063cc35fb8508f9648f3bd7bc40bb8002394be535ac864e6a17a

data/README.md

@@ -262,7 +262,7 @@ end
 
 ### Schema Definitions and References
 
-You can define sub-schemas and reference them in other schemas.
+You can define sub-schemas and reference them in other schemas, or reference the root schema to generate recursive schemas.
 
 ```ruby
 class MySchema < RubyLLM::Schema
@@ -281,6 +281,35 @@ class MySchema < RubyLLM::Schema
   object :user do
     reference :location
   end
+
+  # Using a reference to the root schema
+  object :ui_schema do
+    string :element, enum: ["input", "button"]
+    string :label
+    object :sub_schema, reference: :root
+  end
+end
+```
+
+### Nested Schemas
+
+You can embed existing schema classes directly within objects or arrays for reusable schema composition.
+
+```ruby
+class PersonSchema < RubyLLM::Schema
+  string :name
+  integer :age
+end
+
+class CompanySchema < RubyLLM::Schema
+  # Using 'of' parameter
+  object :ceo, of: PersonSchema
+  array :employees, of: PersonSchema
+  
+  # Using Schema.new in block
+  object :founder do
+    PersonSchema.new
+  end
 end
 ```
 

data/lib/ruby_llm/schema/dsl/complex_types.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Schema
+    module DSL
+      module ComplexTypes
+        def object(name, description: nil, required: true, **options, &block)
+          add_property(name, object_schema(description: description, **options, &block), required: required)
+        end
+
+        def array(name, description: nil, required: true, **options, &block)
+          add_property(name, array_schema(description: description, **options, &block), required: required)
+        end
+
+        def any_of(name, description: nil, required: true, **options, &block)
+          add_property(name, any_of_schema(description: description, **options, &block), required: required)
+        end
+
+        def optional(name, description: nil, &block)
+          any_of(name, description: description) do
+            instance_eval(&block)
+            null
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/schema/dsl/primitive_types.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Schema
+    module DSL
+      module PrimitiveTypes
+        def string(name, description: nil, required: true, **options)
+          add_property(name, string_schema(description: description, **options), required: required)
+        end
+
+        def number(name, description: nil, required: true, **options)
+          add_property(name, number_schema(description: description, **options), required: required)
+        end
+
+        def integer(name, description: nil, required: true, **options)
+          add_property(name, integer_schema(description: description, **options), required: required)
+        end
+
+        def boolean(name, description: nil, required: true, **options)
+          add_property(name, boolean_schema(description: description, **options), required: required)
+        end
+
+        def null(name, description: nil, required: true, **options)
+          add_property(name, null_schema(description: description, **options), required: required)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/schema/dsl/schema_builders.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Schema
+    module DSL
+      module SchemaBuilders
+        def string_schema(description: nil, enum: nil, min_length: nil, max_length: nil, pattern: nil, format: nil)
+          {
+            type: "string",
+            enum: enum,
+            description: description,
+            minLength: min_length,
+            maxLength: max_length,
+            pattern: pattern,
+            format: format
+          }.compact
+        end
+
+        def number_schema(description: nil, minimum: nil, maximum: nil, multiple_of: nil)
+          {
+            type: "number",
+            description: description,
+            minimum: minimum,
+            maximum: maximum,
+            multipleOf: multiple_of
+          }.compact
+        end
+
+        def integer_schema(description: nil, minimum: nil, maximum: nil, multiple_of: nil)
+          {
+            type: "integer",
+            description: description,
+            minimum: minimum,
+            maximum: maximum,
+            multipleOf: multiple_of
+          }.compact
+        end
+
+        def boolean_schema(description: nil)
+          {type: "boolean", description: description}.compact
+        end
+
+        def null_schema(description: nil)
+          {type: "null", description: description}.compact
+        end
+
+        def object_schema(description: nil, of: nil, reference: nil, &block)
+          if reference
+            warn "[DEPRECATION] The `reference` option will be deprecated. Please use `of` instead."
+            of = reference
+          end
+
+          if of
+            determine_object_reference(of, description)
+          else
+            sub_schema = Class.new(Schema)
+            result = sub_schema.class_eval(&block)
+
+            # If the block returned a reference and no properties were added, use the reference
+            if result.is_a?(Hash) && result["$ref"] && sub_schema.properties.empty?
+              result.merge(description ? {description: description} : {})
+            # If the block returned a Schema class or instance, convert it to inline schema
+            elsif schema_class?(result) && sub_schema.properties.empty?
+              schema_class_to_inline_schema(result).merge(description ? {description: description} : {})
+            # Block didn't return reference or schema, so we build an inline object schema
+            else
+              {
+                type: "object",
+                properties: sub_schema.properties,
+                required: sub_schema.required_properties,
+                additionalProperties: sub_schema.additional_properties,
+                description: description
+              }.compact
+            end
+          end
+        end
+
+        def array_schema(description: nil, of: nil, min_items: nil, max_items: nil, &block)
+          items = determine_array_items(of, &block)
+
+          {
+            type: "array",
+            description: description,
+            items: items,
+            minItems: min_items,
+            maxItems: max_items
+          }.compact
+        end
+
+        def any_of_schema(description: nil, &block)
+          schemas = collect_schemas_from_block(&block)
+
+          {
+            description: description,
+            anyOf: schemas
+          }.compact
+        end
+
+        private
+
+        def determine_array_items(of, &)
+          return collect_schemas_from_block(&).first if block_given?
+          return send("#{of}_schema") if primitive_type?(of)
+          return reference(of) if of.is_a?(Symbol)
+          return schema_class_to_inline_schema(of) if schema_class?(of)
+
+          raise InvalidArrayTypeError, "Invalid array type: #{of.inspect}. Must be a primitive type (:string, :number, etc.), a symbol reference, a Schema class, or a Schema instance."
+        end
+
+        def determine_object_reference(of, description = nil)
+          result = case of
+          when Symbol
+            reference(of)
+          when Class
+            if schema_class?(of)
+              schema_class_to_inline_schema(of)
+            else
+              raise InvalidObjectTypeError, "Invalid object type: #{of.inspect}. Class must inherit from RubyLLM::Schema."
+            end
+          else
+            if schema_class?(of)
+              schema_class_to_inline_schema(of)
+            else
+              raise InvalidObjectTypeError, "Invalid object type: #{of.inspect}. Must be a symbol reference, a Schema class, or a Schema instance."
+            end
+          end
+
+          description ? result.merge(description: description) : result
+        end
+
+        def collect_schemas_from_block(&block)
+          schemas = []
+          schema_builder = self
+
+          context = Object.new
+
+          # Dynamically create methods for all schema builders
+          schema_builder.methods.grep(/_schema$/).each do |schema_method|
+            type_name = schema_method.to_s.sub(/_schema$/, "")
+
+            context.define_singleton_method(type_name) do |name = nil, **options, &blk|
+              schemas << schema_builder.send(schema_method, **options, &blk)
+            end
+          end
+
+          # Allow Schema classes to be accessed in the context
+          context.define_singleton_method(:const_missing) do |name|
+            const_get(name) if const_defined?(name)
+          end
+
+          context.instance_eval(&block)
+          schemas
+        end
+
+        def schema_class_to_inline_schema(schema_class_or_instance)
+          # Handle both Schema classes and Schema instances
+          schema_class = if schema_class_or_instance.is_a?(Class)
+            schema_class_or_instance
+          else
+            schema_class_or_instance.class
+          end
+
+          # Directly convert schema class to inline object schema
+          {
+            type: "object",
+            properties: schema_class.properties,
+            required: schema_class.required_properties,
+            additionalProperties: schema_class.additional_properties
+          }.tap do |schema|
+            # For instances, prefer instance description over class description
+            description = if schema_class_or_instance.is_a?(Class)
+              schema_class.description
+            else
+              schema_class_or_instance.instance_variable_get(:@description) || schema_class.description
+            end
+            schema[:description] = description if description
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/schema/dsl/utilities.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Schema
+    module DSL
+      module Utilities
+        # 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,
+            additionalProperties: sub_schema.additional_properties
+          }
+        end
+
+        def reference(schema_name)
+          if schema_name == :root
+            {"$ref" => "#"}
+          else
+            {"$ref" => "#/$defs/#{schema_name}"}
+          end
+        end
+
+        private
+
+        def add_property(name, definition, required:)
+          properties[name.to_sym] = definition
+          required_properties << name.to_sym if required
+        end
+
+        def primitive_type?(type)
+          type.is_a?(Symbol) && PRIMITIVE_TYPES.include?(type)
+        end
+
+        def schema_class?(type)
+          (type.is_a?(Class) && type < Schema) || type.is_a?(Schema)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/schema/dsl.rb

@@ -1,194 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "dsl/schema_builders"
+require_relative "dsl/primitive_types"
+require_relative "dsl/complex_types"
+require_relative "dsl/utilities"
+
 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, reference: nil, description: nil, required: true, &block)
-        add_property(name, build_property_schema(:object, description: description, reference: reference, &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,
-          additionalProperties: sub_schema.additional_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
-          # If the reference option is provided, return the reference
-          return reference(options[:reference]) if options[:reference]
-
-          sub_schema = Class.new(Schema)
-
-          # Evaluate the block and capture the result
-          result = sub_schema.class_eval(&)
-
-          # If the block returned a reference and no properties were added, use the reference
-          if result.is_a?(Hash) && result["$ref"] && sub_schema.properties.empty?
-            result.merge(options[:description] ? {description: options[:description]} : {})
-          else
-            {
-              type: "object",
-              properties: sub_schema.properties,
-              required: sub_schema.required_properties,
-              additionalProperties: sub_schema.additional_properties,
-              description: options[:description]
-            }.compact
-          end
-        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
+      include SchemaBuilders
+      include PrimitiveTypes
+      include ComplexTypes
+      include Utilities
     end
   end
 end

data/lib/ruby_llm/schema/errors.rb

@@ -14,8 +14,15 @@ module RubyLLM
 
     # Raised when an invalid array type is specified
     class InvalidArrayTypeError < Error
-      def initialize(type)
-        super("Invalid array type: #{type}")
+      def initialize(message)
+        super
+      end
+    end
+
+    # Raised when an invalid object type is specified
+    class InvalidObjectTypeError < Error
+      def initialize(message)
+        super
       end
     end
 

data/lib/ruby_llm/schema/json_output.rb

@@ -6,17 +6,21 @@ module RubyLLM
       def to_json_schema
         validate!  # Validate schema before generating JSON
 
+        schema_hash = {
+          type: "object",
+          properties: self.class.properties,
+          required: self.class.required_properties,
+          additionalProperties: self.class.additional_properties,
+          strict: self.class.strict
+        }
+
+        # Only include $defs if there are definitions
+        schema_hash["$defs"] = self.class.definitions unless self.class.definitions.empty?
+
         {
           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
-          }
+          schema: schema_hash
         }
       end
 

data/lib/ruby_llm/schema/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLlm
   class Schema
-    VERSION = "0.1.9"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-schema
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniel Friis
 bindir: exe
 cert_chain: []
-date: 2025-08-22 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -49,6 +49,10 @@ files:
 - Rakefile
 - lib/ruby_llm/schema.rb
 - lib/ruby_llm/schema/dsl.rb
+- lib/ruby_llm/schema/dsl/complex_types.rb
+- lib/ruby_llm/schema/dsl/primitive_types.rb
+- lib/ruby_llm/schema/dsl/schema_builders.rb
+- lib/ruby_llm/schema/dsl/utilities.rb
 - lib/ruby_llm/schema/errors.rb
 - lib/ruby_llm/schema/helpers.rb
 - lib/ruby_llm/schema/json_output.rb