easy_talk 3.2.0 → 3.3.1

data/lib/easy_talk/configuration.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'naming_strategies'
 
 module EasyTalk
   class Configuration
+    extend T::Sig
+
     # JSON Schema draft version URIs
     SCHEMA_VERSIONS = {
       draft202012: 'https://json-schema.org/draft/2020-12/schema',
@@ -14,9 +17,11 @@ module EasyTalk
     }.freeze
 
     attr_accessor :default_additional_properties, :nilable_is_optional, :auto_validations, :schema_version, :schema_id,
-                  :use_refs, :validation_adapter, :default_error_format, :error_type_base_uri, :include_error_codes
+                  :use_refs, :validation_adapter, :default_error_format, :error_type_base_uri, :include_error_codes,
+                  :base_schema_uri, :auto_generate_ids, :prefer_external_refs
     attr_reader :property_naming_strategy
 
+    sig { void }
     def initialize
       @default_additional_properties = false
       @nilable_is_optional = false
@@ -28,16 +33,21 @@ module EasyTalk
       @default_error_format = :flat
       @error_type_base_uri = 'about:blank'
       @include_error_codes = true
+      @base_schema_uri = nil
+      @auto_generate_ids = false
+      @prefer_external_refs = false
       self.property_naming_strategy = :identity
     end
 
     # Returns the URI for the configured schema version, or nil if :none
+    sig { returns(T.nilable(String)) }
     def schema_uri
       return nil if @schema_version == :none
 
       SCHEMA_VERSIONS[@schema_version] || @schema_version.to_s
     end
 
+    sig { params(strategy: T.any(Symbol, T.proc.params(arg0: T.untyped).returns(Symbol))).void }
     def property_naming_strategy=(strategy)
       @property_naming_strategy = EasyTalk::NamingStrategies.derive_strategy(strategy)
     end
@@ -56,17 +66,22 @@ module EasyTalk
     #   EasyTalk.configure do |config|
     #     config.register_type Money, MoneySchemaBuilder
     #   end
+    sig { params(type_key: T.any(T::Class[T.anything], String, Symbol), builder_class: T.untyped, collection: T::Boolean).void }
     def register_type(type_key, builder_class, collection: false)
       EasyTalk::Builders::Registry.register(type_key, builder_class, collection: collection)
     end
   end
 
   class << self
+    extend T::Sig
+
+    sig { returns(Configuration) }
     def configuration
       @configuration ||= Configuration.new
     end
 
-    def configure
+    sig { params(block: T.proc.params(config: Configuration).void).void }
+    def configure(&block)
       yield(configuration)
     end
   end

data/lib/easy_talk/errors.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   class Error < StandardError; end

data/lib/easy_talk/errors_helper.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   # Helper module for generating consistent error messages
   module ErrorHelper
+    extend T::Sig
+
     def self.raise_constraint_error(property_name:, constraint_name:, expected:, got:)
       message = "Error in property '#{property_name}': Constraint '#{constraint_name}' expects #{expected}, " \
                 "but received #{got.inspect} (#{got.class})."

data/lib/easy_talk/extensions/ruby_llm_compatibility.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module Extensions
+    # Class methods for RubyLLM compatibility.
+    # These are added to the model class via `extend`.
+    module RubyLLMCompatibility
+      # Returns a Hash representing the schema in a format compatible with RubyLLM.
+      # RubyLLM expects an object that responds to #to_json_schema and returns
+      # a hash with :name, :description, and :schema keys.
+      #
+      # @return [Hash] The RubyLLM-compatible schema representation
+      def to_json_schema
+        {
+          name: name,
+          description: schema_definition.schema[:description] || "Schema for #{name}",
+          schema: json_schema
+        }
+      end
+    end
+
+    # Overrides for classes that inherit from RubyLLM::Tool.
+    # Only overrides schema-related methods, allowing all other RubyLLM::Tool
+    # functionality (halt, call, etc.) to work normally.
+    #
+    # Usage:
+    #   class WeatherTool < RubyLLM::Tool
+    #     include EasyTalk::Model
+    #
+    #     define_schema do
+    #       description 'Gets current weather'
+    #       property :latitude, String
+    #       property :longitude, String
+    #     end
+    #
+    #     def execute(latitude:, longitude:)
+    #       # Can use halt() since we inherit from RubyLLM::Tool
+    #       halt "Weather at #{latitude}, #{longitude}"
+    #     end
+    #   end
+    module RubyLLMToolOverrides
+      # Override to use EasyTalk's schema description.
+      #
+      # @return [String] The tool description from EasyTalk schema
+      def description
+        schema_def = self.class.schema_definition
+        schema_def.schema[:description] || "Tool: #{self.class.name}"
+      end
+
+      # Override to use EasyTalk's JSON schema for parameters.
+      #
+      # @return [Hash] The JSON schema for parameters
+      def params_schema
+        self.class.json_schema
+      end
+    end
+  end
+end

data/lib/easy_talk/json_schema_equality.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  # Implements JSON Schema equality semantics for comparing values.
+  #
+  # Per JSON Schema specification:
+  # - Objects with same keys/values in different order are equal
+  # - Numbers that are mathematically equal are equal (1 == 1.0)
+  # - Type matters for non-numbers (true != 1, false != 0)
+  module JsonSchemaEquality
+    # Maximum nesting depth to prevent SystemStackError on deeply nested structures
+    MAX_DEPTH = 100
+
+    class << self
+      # Check if an array contains duplicate values using JSON Schema equality.
+      # Uses a Set for O(n) performance and early termination on first duplicate.
+      def duplicates?(array)
+        seen = Set.new
+        array.any? { |item| !seen.add?(normalize(item)) }
+      end
+
+      # Normalize a value for JSON Schema equality comparison
+      # @param value [Object] The value to normalize
+      # @param depth [Integer] Current recursion depth (for stack overflow protection)
+      # @raise [ArgumentError] if nesting depth exceeds MAX_DEPTH
+      def normalize(value, depth = 0)
+        raise ArgumentError, "Nesting depth exceeds maximum of #{MAX_DEPTH}" if depth > MAX_DEPTH
+
+        case value
+        when Hash
+          # Convert keys to strings before sorting to handle mixed key types (Symbol/String)
+          # and ensure consistent, order-independent comparison (JSON only has string keys)
+          value.map { |k, v| [k.to_s, normalize(v, depth + 1)] }.sort
+        when Array
+          value.map { |item| normalize(item, depth + 1) }
+        when Integer, Float
+          # Normalize numbers to a canonical form for mathematical equality
+          value.to_r
+        else
+          # Booleans, strings, nil - preserve as-is (type matters)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/keywords.rb

@@ -7,7 +7,6 @@ module EasyTalk
     description
     type
     title
-    property
     required
     items
     additional_items

data/lib/easy_talk/model.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'json'
 require 'active_support'
@@ -11,6 +12,7 @@ require_relative 'builders/object_builder'
 require_relative 'schema_definition'
 require_relative 'validation_builder'
 require_relative 'error_formatter'
+require_relative 'extensions/ruby_llm_compatibility'
 
 module EasyTalk
   # The `Model` module is a mixin that provides functionality for defining and accessing the schema of a model.
@@ -37,12 +39,18 @@ module EasyTalk
   module Model
     def self.included(base)
       base.extend(ClassMethods)
+      base.extend(EasyTalk::Extensions::RubyLLMCompatibility) # Add class-level methods
 
       base.include ActiveModel::API
       base.include ActiveModel::Validations
       base.extend ActiveModel::Callbacks
       base.include(InstanceMethods)
       base.include(ErrorFormatter::InstanceMethods)
+
+      # If inheriting from RubyLLM::Tool, override schema methods to use EasyTalk's schema
+      return unless defined?(RubyLLM::Tool) && base < RubyLLM::Tool
+
+      base.include(EasyTalk::Extensions::RubyLLMToolOverrides)
     end
 
     # Instance methods mixed into models that include EasyTalk::Model
@@ -149,6 +157,14 @@ module EasyTalk
         to_hash.merge(@additional_properties)
       end
 
+      # Returns a Hash representing the schema in a format compatible with RubyLLM.
+      # Delegates to the class method. Required for RubyLLM's with_schema method.
+      #
+      # @return [Hash] The RubyLLM-compatible schema representation
+      def to_json_schema
+        self.class.to_json_schema
+      end
+
       # Allow comparison with hashes
       def ==(other)
         case other
@@ -220,6 +236,9 @@ module EasyTalk
         # Track which properties have had validations applied
         @validated_properties ||= Set.new
 
+        # Initialize mutex eagerly for thread-safe schema-level validation application
+        @schema_level_validation_lock = Mutex.new
+
         # Apply validations using the adapter system
         apply_schema_validations
 
@@ -273,6 +292,26 @@ module EasyTalk
           adapter.build_validations(self, prop_name, prop_def[:type], prop_def[:constraints])
           @validated_properties.add(prop_name)
         end
+
+        # Apply schema-level validations (min_properties, max_properties, dependent_required)
+        apply_schema_level_validations(adapter)
+      end
+
+      # Apply schema-level validations for object-level constraints.
+      # Uses double-checked locking for thread safety.
+      # The mutex is initialized eagerly in define_schema.
+      #
+      # @param adapter [Class] The validation adapter class
+      # @return [void]
+      def apply_schema_level_validations(adapter)
+        return if @schema_level_validations_applied
+
+        @schema_level_validation_lock.synchronize do
+          return if @schema_level_validations_applied
+
+          adapter.build_schema_validations(self, @schema_definition.schema)
+          @schema_level_validations_applied = true
+        end
       end
 
       public
@@ -285,7 +324,9 @@ module EasyTalk
       end
 
       def additional_properties_allowed?
-        @schema_definition&.schema&.fetch(:additional_properties, false)
+        ap = @schema_definition&.schema&.fetch(:additional_properties, false)
+        # Allow if true, or if it's a schema object (Class or Hash with type)
+        ap == true || ap.is_a?(Class) || ap.is_a?(Hash)
       end
 
       # Returns the property names defined in the schema

data/lib/easy_talk/model_helper.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   module ModelHelper
+    extend T::Sig
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
     def self.easytalk_model?(type)
       type.is_a?(Class) &&
         type.respond_to?(:schema) &&

data/lib/easy_talk/naming_strategies.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   module NamingStrategies
+    extend T::Sig
+
     IDENTITY = lambda(&:to_sym)
     SNAKE_CASE = ->(property_name) { property_name.to_s.underscore.to_sym }
     CAMEL_CASE = ->(property_name) { property_name.to_s.tr('-', '_').camelize(:lower).to_sym }
     PASCAL_CASE = ->(property_name) { property_name.to_s.tr('-', '_').camelize.to_sym }
 
+    sig { params(strategy: T.any(Symbol, T.proc.params(arg0: T.untyped).returns(Symbol))).returns(T.proc.params(arg0: T.untyped).returns(Symbol)) }
     def self.derive_strategy(strategy)
       if strategy.is_a?(Symbol)
         "EasyTalk::NamingStrategies::#{strategy.to_s.upcase}".constantize

data/lib/easy_talk/property.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'json'
 require_relative 'builders/integer_builder'
@@ -9,6 +10,7 @@ require_relative 'builders/string_builder'
 require_relative 'builders/temporal_builder'
 require_relative 'builders/composition_builder'
 require_relative 'builders/typed_array_builder'
+require_relative 'builders/tuple_builder'
 require_relative 'builders/union_builder'
 
 # EasyTalk module provides a DSL for building JSON Schema definitions.
@@ -99,6 +101,7 @@ module EasyTalk
     # @example Nested schema with $ref
     #   property = Property.new(:shipping_address, Address, ref: true)
     #   property.build  # => {"$ref"=>"#/$defs/Address", ...constraints}
+    sig { returns(T::Hash[Symbol, T.untyped]) }
     def build
       if nilable_type?
         build_nilable_schema
@@ -128,6 +131,7 @@ module EasyTalk
     #
     # @see #build
     # @see https://ruby-doc.org/stdlib-2.7.2/libdoc/json/rdoc/JSON.html#as_json-method
+    sig { params(_args: T.untyped).returns(T.untyped) }
     def as_json(*_args)
       build.as_json
     end
@@ -142,6 +146,7 @@ module EasyTalk
     # @return [Array(Class, Boolean), nil] A tuple of [builder_class, is_collection] or nil if none matches
     # @api private
     # @see Builders::Registry.resolve
+    sig { returns(T.nilable(T::Array[T.untyped])) }
     def find_builder_for_type
       Builders::Registry.resolve(type)
     end
@@ -153,6 +158,7 @@ module EasyTalk
     #
     # @return [Boolean] true if the type is nilable, false otherwise
     # @api private
+    sig { returns(T::Boolean) }
     def nilable_type?
       return false unless type.respond_to?(:types)
       return false unless type.types.all? { |t| t.respond_to?(:raw_type) }
@@ -167,6 +173,7 @@ module EasyTalk
     # @example
     #   # For a T.nilable(String) type:
     #   {"type"=>["string", "null"]}
+    sig { returns(T::Hash[Symbol, T.untyped]) }
     def build_nilable_schema
       # Extract the non-nil type from the Union
       actual_type = T::Utils::Nilable.get_underlying_type(type)

data/lib/easy_talk/ref_helper.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'model_helper'
 
 module EasyTalk
   module RefHelper
+    extend T::Sig
+
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
     def self.should_use_ref?(type, constraints)
       ModelHelper.easytalk_model?(type) && should_use_ref_for_type?(type, constraints)
     end
 
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
     def self.should_use_ref_for_type?(type, constraints)
       return false unless ModelHelper.easytalk_model?(type)
 
@@ -19,6 +24,7 @@ module EasyTalk
       end
     end
 
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
     def self.build_ref_schema(type, constraints)
       # Remove ref and optional from constraints as they're not JSON Schema keywords
       { '$ref': type.ref_template }.merge(constraints.except(:ref, :optional))

data/lib/easy_talk/schema.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'json'
 require 'active_support'

data/lib/easy_talk/schema_definition.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'keywords'
 require_relative 'types/composer'
@@ -19,28 +20,39 @@ module EasyTalk
     attr_reader :name, :schema
     attr_accessor :klass # Add accessor for the model class
 
+    sig { params(name: String, schema: T::Hash[Symbol, T.untyped]).void }
     def initialize(name, schema = {})
-      @schema = schema
-      @schema[:additional_properties] = false unless schema.key?(:additional_properties)
+      @schema = schema.dup
+      @schema[:additional_properties] = EasyTalk.configuration.default_additional_properties unless @schema.key?(:additional_properties)
       @name = name
       @klass = nil # Initialize klass to nil
       @property_naming_strategy = EasyTalk.configuration.property_naming_strategy
     end
 
     EasyTalk::KEYWORDS.each do |keyword|
-      define_method(keyword) do |*values|
-        @schema[keyword] = values.size > 1 ? values : values.first
+      if keyword == :additional_properties
+        # Special handling for additional_properties to support type + constraints syntax
+        define_method(keyword) do |*args|
+          value = parse_additional_properties_args(args)
+          @schema[keyword] = value
+        end
+      else
+        define_method(keyword) do |*values|
+          @schema[keyword] = values.size > 1 ? values : values.first
+        end
       end
     end
 
+    sig { params(subschemas: T.untyped).void }
     def compose(*subschemas)
       @schema[:subschemas] ||= []
       @schema[:subschemas] += subschemas
     end
 
-    def property(name, type, constraints = {}, &)
+    sig { params(name: T.any(Symbol, String), type: T.untyped, constraints: T::Hash[Symbol, T.untyped], block: T.nilable(T.proc.void)).void }
+    def property(name, type, constraints = {}, &block)
+      validate_property_name(name)
       constraints[:as] ||= @property_naming_strategy.call(name)
-      validate_property_name(constraints[:as])
       @schema[:properties] ||= {}
 
       if block_given?
@@ -51,6 +63,7 @@ module EasyTalk
       @schema[:properties][name] = { type:, constraints: }
     end
 
+    sig { params(name: T.any(Symbol, String)).void }
     def validate_property_name(name)
       return if name.to_s.match?(/^[A-Za-z_][A-Za-z0-9_]*$/)
 
@@ -59,11 +72,13 @@ module EasyTalk
       raise InvalidPropertyNameError, message
     end
 
+    sig { returns(T.nilable(T::Boolean)) }
     def optional?
       @schema[:optional]
     end
 
     # Helper method for nullable and optional properties
+    sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).void }
     def nullable_optional_property(name, type, constraints = {})
       # Ensure type is nilable
       nilable_type = if type.respond_to?(:nilable?) && type.nilable?
@@ -79,8 +94,39 @@ module EasyTalk
       property(name, nilable_type, constraints)
     end
 
+    sig { params(strategy: T.any(Symbol, T.proc.params(arg0: T.untyped).returns(Symbol))).void }
     def property_naming_strategy(strategy)
       @property_naming_strategy = EasyTalk::NamingStrategies.derive_strategy(strategy)
     end
+
+    private
+
+    # Parses arguments for additional_properties to support multiple syntaxes:
+    # - additional_properties true/false (boolean)
+    # - additional_properties String (type class)
+    # - additional_properties Integer, minimum: 0, maximum: 100 (type + constraints)
+    sig { params(args: T::Array[T.untyped]).returns(T.untyped) }
+    def parse_additional_properties_args(args)
+      return args.first if args.empty?
+
+      # Single boolean argument
+      first_arg = args.first
+      return first_arg if args.size == 1 && (first_arg.is_a?(TrueClass) || first_arg.is_a?(FalseClass))
+
+      # Single type class (String, Integer, custom model, etc.)
+      return first_arg if args.size == 1 && first_arg.is_a?(Class)
+
+      # Type + constraints: additional_properties Integer, minimum: 0, maximum: 100
+      # args = [Integer, { minimum: 0, maximum: 100 }] or [Integer, minimum: 0, maximum: 100]
+      if args.size >= 1 && args.first.is_a?(Class)
+        type = args.first
+        # Merge all hash arguments as constraints
+        constraints = args[1..].select { |arg| arg.is_a?(Hash) }.reduce({}, :merge)
+        return { type:, **constraints }
+      end
+
+      # Fallback: return as-is
+      args.first
+    end
   end
 end

data/lib/easy_talk/schema_methods.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   # Shared methods for JSON Schema generation.
@@ -14,10 +15,16 @@ module EasyTalk
   #
   module SchemaMethods
     # Returns the reference template for the model.
+    # When prefer_external_refs is enabled and the model has a schema ID,
+    # returns the external $id URI. Otherwise, returns the local $defs reference.
     #
     # @return [String] The reference template for the model.
     def ref_template
-      "#/$defs/#{name}"
+      config = EasyTalk.configuration
+
+      # Use external ref when configured and $id available, otherwise fall back to local $defs
+      schema_id = resolve_schema_id if config.prefer_external_refs
+      schema_id || "#/$defs/#{name}"
     end
 
     # Returns the JSON schema for the model.
@@ -62,19 +69,43 @@ module EasyTalk
       end
     end
 
-    # Resolves the schema ID from per-model setting or global config.
+    # Resolves the schema ID from per-model setting, auto-generation, or global config.
+    # Precedence order:
+    #   1. Per-model explicit schema_id (highest priority)
+    #   2. Auto-generated from base_schema_uri (middle priority)
+    #   3. Global schema_id (lowest priority)
     #
     # @return [String, nil] The schema ID.
     def resolve_schema_id
       model_id = @schema_definition&.schema&.dig(:schema_id)
 
+      # Per-model explicit ID takes precedence
       if model_id
         return nil if model_id == :none
 
-        model_id.to_s
-      else
-        EasyTalk.configuration.schema_id
+        return model_id.to_s
       end
+
+      # Auto-generate from base_schema_uri if enabled
+      config = EasyTalk.configuration
+      return generate_schema_id(config.base_schema_uri, name) if config.auto_generate_ids && config.base_schema_uri && name
+
+      # Fall back to global schema_id
+      config.schema_id
+    end
+
+    # Generates a schema ID from the base URI and model name.
+    # Normalizes the base URI and converts the model name to underscore case.
+    #
+    # @param base_uri [String] The base URI for schema IDs.
+    # @param model_name [String] The model class name.
+    # @return [String] The generated schema ID.
+    def generate_schema_id(base_uri, model_name)
+      # Normalize base URI (remove trailing slash)
+      base = base_uri.to_s.chomp('/')
+      # Convert model name to lowercase with underscores for URI segment
+      segment = model_name.to_s.underscore
+      "#{base}/#{segment}"
     end
   end
 end

data/lib/easy_talk/sorbet_extension.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 # This module provides additional functionality for working with Sorbet types.
 module SorbetExtension