ruby_llm-schema 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fceccc2292efb7c17ce5457a08d6a18ddc3debd920052a1d8e368d74e450547e
-  data.tar.gz: b16fafc541af3b9f1a1e3a96f81be21175a380606f2e40325afa29d76108daea
+  metadata.gz: 21c3e0ee2e5a1034eb571749cc2f27af5db9e4abaf07e2df677325f9270db6f1
+  data.tar.gz: 57db5c67a751f4e31f1ed2d56bba8bac76ddb989fee7b49add969b1c50be844e
 SHA512:
-  metadata.gz: 984b11c9fcfcaf68f0892a9a7b9c10064436aa59279f0a0992ebae5c6d20fbcfd1e6afbef8376bf7a9239aaaea246dd9f8c7f6a3d9521509789c8e334e3e0363
-  data.tar.gz: e9658cff5e3e1f0912eab47fe8438a5dfd5bf52928dd0198ff39131ecf1aeb5d3b2a8e08344feab0b363ed6a9a27747c1489fcfadefd8f30af4d03c77fb601d8
+  metadata.gz: cd93b24110859806ee43a5a794353849e51273797696d84469b998c69d9e93e761ef817ede4d89377e34e227f8b6115d2e9133d58496bfcb2399f7720e4087e3
+  data.tar.gz: 1153950f2917a95e00744cb832a2c3ce7b1bd61965314f5652dc4337333d3b9f258d52b01257e62739b997bbd6ede840c9a7adfcd339477dc996bca093bf2a0d

data/README.md

@@ -1,8 +1,9 @@
 # RubyLLM::Schema
 
 [![Gem Version](https://badge.fury.io/rb/ruby_llm-schema.svg)](https://rubygems.org/gems/ruby_llm-schema)
-[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/crmne/ruby_llm-schema/blob/main/LICENSE)
-[![CI](https://github.com/crmne/ruby_llm-schema/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/crmne/ruby_llm-schema/actions/workflows/main.yml)
+[![Gem Downloads](https://img.shields.io/gem/dt/ruby_llm-schema)](https://rubygems.org/gems/ruby_llm-schema)
+[![codecov](https://codecov.io/gh/crmne/ruby_llm-schema/branch/main/graph/badge.svg)](https://codecov.io/gh/crmne/ruby_llm-schema)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
 
 A Ruby DSL for creating JSON schemas with a clean, Rails-inspired API.
 
@@ -443,6 +444,65 @@ schema.to_json_schema
 # }
 ```
 
+### Dependencies
+
+Use `requires:` inline or `dependent` block to express that the presence of one property requires others. Maps to [`dependentRequired`](https://json-schema.org/understanding-json-schema/reference/conditionals#dependentRequired) (Draft 2019-09) and [`dependentSchemas`](https://json-schema.org/understanding-json-schema/reference/conditionals#dependentSchemas) (Draft 2019-09). Check your provider's documentation for compatibility.
+
+```ruby
+class PaymentSchema < RubyLLM::Schema
+  string :name
+  number :credit_card, required: false, requires: %i[billing_address cvv]
+  string :billing_address, required: false
+  string :cvv, required: false
+end
+```
+
+Use a `dependent` block when you also need validations — this upgrades the output to `dependentSchemas`:
+
+```ruby
+dependent :credit_card do
+  requires :billing_address
+  validates :billing_address, type: :string, min_length: 1
+end
+```
+
+### Conditionals
+
+Use `given` to add [JSON Schema `if`/`then`/`else`](https://json-schema.org/understanding-json-schema/reference/conditionals#ifthenelse) (Draft 7) rules. Condition values are automatically coerced: strings → `const`, arrays → `enum`, regexps → `pattern`, hashes → raw schema.
+
+```ruby
+class OrderSchema < RubyLLM::Schema
+  string :status, enum: ["pending", "shipped", "cancelled"]
+  string :tracking_number, required: false
+  string :cancellation_reason, required: false
+
+  given status: "shipped" do
+    requires :tracking_number
+  end
+
+  given status: "cancelled" do
+    requires :cancellation_reason
+    validates :cancellation_reason, type: :string, min_length: 1
+  end
+end
+```
+
+`validates` supports: `type:`, `not_value:`, `min_length:`, `max_length:`, `pattern:` (string or regexp), `enum:`, `const:`, `minimum:`, `maximum:`.
+
+Use `otherwise` for an `else` branch:
+
+```ruby
+given domestic: true do
+  requires :state
+
+  otherwise do
+    requires :country
+  end
+end
+```
+
+Conditions propagate through nested schemas via `of:`.
+
 ## JSON Output
 
 ```ruby

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

@@ -4,20 +4,20 @@ 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)
+        def object(name, description: nil, required: true, requires: nil, **options, &block)
+          add_property(name, object_schema(description: description, **options, &block), required: required, requires: requires)
         end
 
-        def array(name, description: nil, required: true, **options, &block)
-          add_property(name, array_schema(description: description, **options, &block), required: required)
+        def array(name, description: nil, required: true, requires: nil, **options, &block)
+          add_property(name, array_schema(description: description, **options, &block), required: required, requires: requires)
         end
 
-        def any_of(name, description: nil, required: true, **options, &block)
-          add_property(name, any_of_schema(description: description, **options, &block), required: required)
+        def any_of(name, description: nil, required: true, requires: nil, **options, &block)
+          add_property(name, any_of_schema(description: description, **options, &block), required: required, requires: requires)
         end
 
-        def one_of(name, description: nil, required: true, **options, &block)
-          add_property(name, one_of_schema(description: description, **options, &block), required: required)
+        def one_of(name, description: nil, required: true, requires: nil, **options, &block)
+          add_property(name, one_of_schema(description: description, **options, &block), required: required, requires: requires)
         end
 
         def optional(name, description: nil, &block)

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

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Schema
+    module DSL
+      module Conditionals
+        def conditions
+          @conditions ||= []
+        end
+
+        def dependencies
+          @dependencies ||= {}
+        end
+
+        def dependent(property, &block)
+          builder = ConditionalBuilder.new
+          builder.instance_eval(&block)
+
+          dependencies[property.to_s] = builder
+        end
+
+        def given(**properties, &block)
+          raise ArgumentError, "given requires at least one property condition" if properties.empty?
+
+          if_schema = {
+            properties: properties.transform_keys(&:to_s).transform_values { |v| coerce_condition(v) },
+            required: properties.keys.map(&:to_s)
+          }
+
+          then_builder = ConditionalBuilder.new
+          else_builder = ConditionalBuilder.new
+
+          context = ConditionalContext.new(then_builder, else_builder)
+          context.instance_eval(&block)
+
+          condition = {if: if_schema, then: then_builder.to_schema}
+          condition[:else] = else_builder.to_schema unless else_builder.empty?
+
+          conditions << condition
+        end
+
+        private
+
+        def merge_conditions(schema, schema_class)
+          if schema_class.respond_to?(:conditions) && schema_class.conditions.any?
+            if schema_class.conditions.length == 1
+              schema.merge!(schema_class.conditions.first)
+            else
+              schema[:allOf] = schema_class.conditions
+            end
+          end
+
+          if schema_class.respond_to?(:dependencies) && schema_class.dependencies.any?
+            dependent_required = {}
+            dependent_schemas = {}
+
+            schema_class.dependencies.each do |property, builder|
+              if builder.validations_empty?
+                dependent_required[property] = builder.required_fields
+              else
+                dependent_schemas[property] = builder.to_schema
+              end
+            end
+
+            schema[:dependentRequired] = dependent_required if dependent_required.any?
+            schema[:dependentSchemas] = dependent_schemas if dependent_schemas.any?
+          end
+
+          schema
+        end
+
+        def coerce_condition(value)
+          case value
+          when Array then {enum: value}
+          when Regexp then {pattern: value.source}
+          when Hash then value
+          else {const: value}
+          end
+        end
+      end
+
+      class ConditionalContext
+        def initialize(then_builder, else_builder)
+          @then_builder = then_builder
+          @else_builder = else_builder
+        end
+
+        def requires(*fields)
+          @then_builder.requires(*fields)
+        end
+
+        def validates(field, **options)
+          @then_builder.validates(field, **options)
+        end
+
+        def otherwise(&block)
+          @else_builder.instance_eval(&block)
+        end
+      end
+
+      class ConditionalBuilder
+        def requires(*fields)
+          required.concat(fields.map(&:to_s))
+        end
+
+        VALIDATES_KEY_MAP = {
+          type: :type,
+          const: :const,
+          enum: :enum,
+          not_value: :not,
+          min_length: :minLength,
+          max_length: :maxLength,
+          pattern: :pattern,
+          minimum: :minimum,
+          maximum: :maximum
+        }.freeze
+
+        def validates(field, **options)
+          constraints = {}
+
+          options.each do |key, value|
+            schema_key = VALIDATES_KEY_MAP[key]
+            raise ArgumentError, "unknown validates option: #{key.inspect}" unless schema_key
+
+            case key
+            when :type then constraints[:type] = value.to_s
+            when :not_value then constraints[:not] = {const: value}
+            when :pattern then constraints[:pattern] = value.is_a?(Regexp) ? value.source : value
+            else constraints[schema_key] = value
+            end
+          end
+
+          validations[field.to_s] = constraints
+        end
+
+        def to_schema
+          schema = {}
+
+          schema[:required] = required if required.any?
+          schema[:properties] = validations if validations.any?
+
+          schema
+        end
+
+        def empty?
+          required.empty? && validations.empty?
+        end
+
+        def required_fields
+          required.dup
+        end
+
+        def validations_empty?
+          validations.empty?
+        end
+
+        private
+
+        def required
+          @required ||= []
+        end
+
+        def validations
+          @validations ||= {}
+        end
+      end
+    end
+  end
+end

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

@@ -4,24 +4,24 @@ 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)
+        def string(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, string_schema(description: description, **options), required: required, requires: requires)
         end
 
-        def number(name, description: nil, required: true, **options)
-          add_property(name, number_schema(description: description, **options), required: required)
+        def number(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, number_schema(description: description, **options), required: required, requires: requires)
         end
 
-        def integer(name, description: nil, required: true, **options)
-          add_property(name, integer_schema(description: description, **options), required: required)
+        def integer(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, integer_schema(description: description, **options), required: required, requires: requires)
         end
 
-        def boolean(name, description: nil, required: true, **options)
-          add_property(name, boolean_schema(description: description, **options), required: required)
+        def boolean(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, boolean_schema(description: description, **options), required: required, requires: requires)
         end
 
-        def null(name, description: nil, required: true, **options)
-          add_property(name, null_schema(description: description, **options), required: required)
+        def null(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, null_schema(description: description, **options), required: required, requires: requires)
         end
       end
     end

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

@@ -64,13 +64,15 @@ module RubyLLM
               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
-              {
+              schema = {
                 type: "object",
                 properties: sub_schema.properties,
                 required: sub_schema.required_properties,
                 additionalProperties: sub_schema.additional_properties,
                 description: description
               }.compact
+
+              merge_conditions(schema, sub_schema)
             end
           end
         end
@@ -180,7 +182,10 @@ module RubyLLM
                           else
                             schema_class_or_instance.instance_variable_get(:@description) || schema_class.description
                           end
+
             schema[:description] = description if description
+
+            merge_conditions(schema, schema_class)
           end
         end
       end

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

@@ -9,12 +9,16 @@ module RubyLLM
           sub_schema = Class.new(Schema)
           sub_schema.class_eval(&)
 
-          definitions[name] = {
+          schema = {
             type: "object",
             properties: sub_schema.properties,
             required: sub_schema.required_properties,
             additionalProperties: sub_schema.additional_properties
           }
+
+          merge_conditions(schema, sub_schema)
+
+          definitions[name] = schema
         end
 
         def reference(schema_name)
@@ -27,7 +31,7 @@ module RubyLLM
 
         private
 
-        def add_property(name, definition, required:)
+        def add_property(name, definition, required:, requires: nil)
           property_name = name.to_sym
 
           properties[property_name] = definition
@@ -37,6 +41,12 @@ module RubyLLM
             required_properties.delete(property_name)
           end
 
+          if requires
+            builder = ConditionalBuilder.new
+            builder.requires(*Array(requires))
+            dependencies[name.to_s] = builder
+          end
+
           nil
         end
 

data/lib/ruby_llm/schema/dsl.rb

@@ -3,6 +3,7 @@
 require_relative "dsl/schema_builders"
 require_relative "dsl/primitive_types"
 require_relative "dsl/complex_types"
+require_relative "dsl/conditionals"
 require_relative "dsl/utilities"
 
 module RubyLLM
@@ -11,6 +12,7 @@ module RubyLLM
       include SchemaBuilders
       include PrimitiveTypes
       include ComplexTypes
+      include Conditionals
       include Utilities
     end
   end

data/lib/ruby_llm/schema/json_output.rb

@@ -18,6 +18,8 @@ module RubyLLM
         # Only include $defs if there are definitions
         schema_hash["$defs"] = self.class.definitions unless self.class.definitions.empty?
 
+        self.class.send(:merge_conditions, schema_hash, self.class)
+
         {
           name: @name,
           description: @description || self.class.description,

data/lib/ruby_llm/schema/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   class Schema
-    VERSION = '0.3.1'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-schema
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Daniel Friis
@@ -22,6 +22,7 @@ files:
 - lib/ruby_llm/schema.rb
 - lib/ruby_llm/schema/dsl.rb
 - lib/ruby_llm/schema/dsl/complex_types.rb
+- lib/ruby_llm/schema/dsl/conditionals.rb
 - lib/ruby_llm/schema/dsl/primitive_types.rb
 - lib/ruby_llm/schema/dsl/schema_builders.rb
 - lib/ruby_llm/schema/dsl/utilities.rb