easy_talk 3.3.0 → 3.3.2

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/model.rb

@@ -8,10 +8,10 @@ require 'active_support/time'
 require 'active_support/concern'
 require 'active_support/json'
 require 'active_model'
-require_relative 'builders/object_builder'
-require_relative 'schema_definition'
+require_relative 'schema_base'
 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.
@@ -38,150 +38,45 @@ 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
     module InstanceMethods
+      include SchemaBase::InstanceMethods
+
       def initialize(attributes = {})
         @additional_properties = {}
         provided_keys = attributes.keys.to_set(&:to_sym)
 
-        super # Perform initial mass assignment
+        super # Perform initial mass assignment via ActiveModel::API
 
-        schema_def = self.class.schema_definition
-        return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
-
-        (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
-          process_property_initialization(prop_name, prop_definition, provided_keys)
-        end
+        initialize_schema_properties(provided_keys)
       end
 
-      private
-
-      def process_property_initialization(prop_name, prop_definition, provided_keys)
-        defined_type = prop_definition[:type]
-        nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
-
-        apply_default_value(prop_name, prop_definition, provided_keys)
-
-        current_value = public_send(prop_name)
-        return if nilable_type && current_value.nil?
-
-        defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
-        instantiate_nested_models(prop_name, defined_type, current_value)
-      end
-
-      def apply_default_value(prop_name, prop_definition, provided_keys)
-        return if provided_keys.include?(prop_name)
-
-        default_value = prop_definition.dig(:constraints, :default)
-        public_send("#{prop_name}=", default_value) unless default_value.nil?
-      end
-
-      def instantiate_nested_models(prop_name, defined_type, current_value)
-        # Single nested model: convert Hash to model instance
-        if defined_type.is_a?(Class) && defined_type.include?(EasyTalk::Model) && current_value.is_a?(Hash)
-          public_send("#{prop_name}=", defined_type.new(current_value))
-          return
-        end
-
-        # Array of nested models: convert Hash items to model instances
-        instantiate_array_items(prop_name, defined_type, current_value)
-      end
-
-      def instantiate_array_items(prop_name, defined_type, current_value)
-        return unless defined_type.is_a?(T::Types::TypedArray) && current_value.is_a?(Array)
-
-        item_type = defined_type.type.respond_to?(:raw_type) ? defined_type.type.raw_type : nil
-        return unless item_type.is_a?(Class) && item_type.include?(EasyTalk::Model)
-
-        instantiated = current_value.map { |item| item.is_a?(Hash) ? item_type.new(item) : item }
-        public_send("#{prop_name}=", instantiated)
-      end
-
-      public
-
-      def method_missing(method_name, *args)
-        method_string = method_name.to_s
-        if method_string.end_with?('=')
-          property_name = method_string.chomp('=')
-          if self.class.additional_properties_allowed?
-            @additional_properties[property_name] = args.first
-          else
-            super
-          end
-        elsif self.class.additional_properties_allowed? && @additional_properties.key?(method_string)
-          @additional_properties[method_string]
-        else
-          super
-        end
-      end
-
-      def respond_to_missing?(method_name, include_private = false)
-        return super unless self.class.additional_properties_allowed?
-
-        method_string = method_name.to_s
-        method_string.end_with?('=') || @additional_properties.key?(method_string) || super
-      end
-
-      # Add to_hash method to convert defined properties to hash
-      def to_hash
-        properties_to_include = (self.class.schema_definition.schema[:properties] || {}).keys
-        return {} if properties_to_include.empty?
-
-        properties_to_include.each_with_object({}) do |prop, hash|
-          hash[prop.to_s] = send(prop)
-        end
-      end
-
-      # Override as_json to include both defined and additional properties
-      def as_json(_options = {})
-        to_hash.merge(@additional_properties)
-      end
-
-      # to_h includes both defined and additional properties
-      def to_h
-        to_hash.merge(@additional_properties)
-      end
-
-      # Allow comparison with hashes
-      def ==(other)
-        case other
-        when Hash
-          # Convert both to comparable format for comparison
-          self_hash = (self.class.schema_definition.schema[:properties] || {}).keys.each_with_object({}) do |prop, hash|
-            hash[prop] = send(prop)
-          end
-
-          # Handle both symbol and string keys in the other hash
-          other_normalized = other.transform_keys(&:to_sym)
-          self_hash == other_normalized
-        else
-          super
-        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
     end
 
     # Module containing class-level methods for defining and accessing the schema of a model.
     module ClassMethods
-      include SchemaMethods
-
-      # Returns the schema for the model.
-      #
-      # @return [Schema] The schema for the model.
-      def schema
-        @schema ||= if defined?(@schema_definition) && @schema_definition
-                      build_schema(@schema_definition)
-                    else
-                      {}
-                    end
-      end
+      include SchemaBase::ClassMethods
 
       # Define the schema for the model using the provided block.
       #
@@ -205,22 +100,11 @@ module EasyTalk
       #     property :name, String
       #   end
       def define_schema(options = {}, &)
-        raise ArgumentError, 'The class must have a name' unless name.present?
-
-        @schema_definition = SchemaDefinition.new(name)
-        @schema_definition.klass = self # Pass the model class to the schema definition
-        @schema_definition.instance_eval(&)
+        super(&)
 
         # Store validation options for this model
         @validation_options = normalize_validation_options(options)
 
-        # Define accessors immediately based on schema_definition
-        defined_properties = (@schema_definition.schema[:properties] || {}).keys
-        attr_accessor(*defined_properties)
-
-        # 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
 
@@ -232,6 +116,19 @@ module EasyTalk
 
       private
 
+      # Reset all memoized schema state and clear previously registered
+      # ActiveModel validators so a second define_schema call is never ignored.
+      def clear_schema_state!
+        super
+        @schema_level_validations_applied = false
+        @validated_properties = Set.new
+
+        return unless @schema_definition
+
+        reset_callbacks(:validate)
+        _validators.clear
+      end
+
       # Normalize validation options from various input formats.
       #
       # @param options [Hash] The options hash from define_schema
@@ -298,37 +195,6 @@ module EasyTalk
           @schema_level_validations_applied = true
         end
       end
-
-      public
-
-      # Returns the unvalidated schema definition for the model.
-      #
-      # @return [SchemaDefinition] The unvalidated schema definition for the model.
-      def schema_definition
-        @schema_definition ||= {}
-      end
-
-      def additional_properties_allowed?
-        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
-      #
-      # @return [Array<Symbol>] Array of property names as symbols
-      def properties
-        (@schema_definition&.schema&.dig(:properties) || {}).keys
-      end
-
-      # Builds the schema using the provided schema definition.
-      # This is the convergence point for all schema generation.
-      #
-      # @param schema_definition [SchemaDefinition] The schema definition.
-      # @return [Schema] The validated schema.
-      def build_schema(schema_definition)
-        Builders::ObjectBuilder.new(schema_definition).build
-      end
     end
   end
 end

data/lib/easy_talk/property.rb

@@ -112,9 +112,8 @@ module EasyTalk
         args = is_collection ? [name, type, constraints] : [name, constraints]
         builder_class.new(*args).build
       elsif type.respond_to?(:schema)
-        # merge the top-level constraints from *this* property
-        # e.g. :title, :description, :default, etc
-        type.schema.merge!(constraints)
+        # deep_dup so nested hashes in the cached schema aren't shared with the result
+        EasyTalk.deep_dup(type.schema).merge(constraints)
       else
         raise UnknownTypeError,
               "Unknown type '#{type.inspect}' for property '#{name}'. " \

data/lib/easy_talk/schema.rb

@@ -7,8 +7,7 @@ require 'active_support/core_ext'
 require 'active_support/time'
 require 'active_support/concern'
 require 'active_support/json'
-require_relative 'builders/object_builder'
-require_relative 'schema_definition'
+require_relative 'schema_base'
 
 module EasyTalk
   # A lightweight module for schema generation without ActiveModel validations.
@@ -50,150 +49,41 @@ module EasyTalk
 
     # Instance methods for schema-only models.
     module InstanceMethods
+      include SchemaBase::InstanceMethods
+
       # Initialize the schema object with attributes.
+      # Performs manual attribute assignment (no ActiveModel) then applies
+      # defaults and nested model instantiation via the shared base.
       #
       # @param attributes [Hash] The attributes to set
       def initialize(attributes = {})
         @additional_properties = {}
-        schema_def = self.class.schema_definition
-
-        return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
-
-        (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
-          value = attributes[prop_name] || attributes[prop_name.to_s]
-
-          # Handle default values
-          if value.nil? && !attributes.key?(prop_name) && !attributes.key?(prop_name.to_s)
-            default_value = prop_definition.dig(:constraints, :default)
-            value = default_value unless default_value.nil?
-          end
-
-          # Handle nested EasyTalk::Schema or EasyTalk::Model objects
-          defined_type = prop_definition[:type]
-          nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
-          defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
-
-          if defined_type.is_a?(Class) &&
-             (defined_type.include?(EasyTalk::Schema) || defined_type.include?(EasyTalk::Model)) &&
-             value.is_a?(Hash)
-            value = defined_type.new(value)
-          end
-
-          instance_variable_set("@#{prop_name}", value)
-        end
-      end
+        provided_keys = Set.new
 
-      # Convert defined properties to a hash.
-      #
-      # @return [Hash] The properties as a hash
-      def to_hash
-        properties_to_include = (self.class.schema_definition.schema[:properties] || {}).keys
-        return {} if properties_to_include.empty?
-
-        properties_to_include.each_with_object({}) do |prop, hash|
-          hash[prop.to_s] = send(prop)
-        end
+        assign_schema_attributes(attributes, provided_keys)
+        initialize_schema_properties(provided_keys)
       end
 
-      # Convert to JSON-compatible hash including additional properties.
-      #
-      # @param _options [Hash] JSON options (ignored)
-      # @return [Hash] The combined hash
-      def as_json(_options = {})
-        to_hash.merge(@additional_properties)
-      end
+      private
 
-      # Convert to hash including additional properties.
-      #
-      # @return [Hash] The combined hash
-      def to_h
-        to_hash.merge(@additional_properties)
-      end
+      def assign_schema_attributes(attributes, provided_keys)
+        defined_properties = self.class.properties.to_set
 
-      # Allow comparison with hashes.
-      #
-      # @param other [Object] The object to compare with
-      # @return [Boolean] True if equal
-      def ==(other)
-        case other
-        when Hash
-          self_hash = (self.class.schema_definition.schema[:properties] || {}).keys.each_with_object({}) do |prop, hash|
-            hash[prop] = send(prop)
+        attributes.each do |key, value|
+          prop_name = key.to_sym
+          if defined_properties.include?(prop_name)
+            provided_keys << prop_name
+            public_send("#{prop_name}=", value)
+          elsif self.class.additional_properties_allowed?
+            @additional_properties[key.to_s] = value
           end
-          other_normalized = other.transform_keys(&:to_sym)
-          self_hash == other_normalized
-        else
-          super
         end
       end
     end
 
     # Class methods for schema-only models.
     module ClassMethods
-      include SchemaMethods
-
-      # Returns the schema for the model.
-      #
-      # @return [Hash] The schema for the model.
-      def schema
-        @schema ||= if defined?(@schema_definition) && @schema_definition
-                      build_schema(@schema_definition)
-                    else
-                      {}
-                    end
-      end
-
-      # Define the schema for the model using the provided block.
-      # Unlike EasyTalk::Model, this does NOT apply any validations.
-      #
-      # @yield The block to define the schema.
-      # @raise [ArgumentError] If the class does not have a name.
-      def define_schema(&)
-        raise ArgumentError, 'The class must have a name' unless name.present?
-
-        @schema_definition = SchemaDefinition.new(name)
-        @schema_definition.klass = self
-        @schema_definition.instance_eval(&)
-
-        # Define accessors for all properties
-        defined_properties = (@schema_definition.schema[:properties] || {}).keys
-        attr_accessor(*defined_properties)
-
-        # NO validations are applied - this is schema-only
-
-        @schema_definition
-      end
-
-      # Returns the schema definition for the model.
-      #
-      # @return [SchemaDefinition] The schema definition.
-      def schema_definition
-        @schema_definition ||= {}
-      end
-
-      # Check if additional properties are allowed.
-      #
-      # @return [Boolean] True if additional properties are allowed.
-      def additional_properties_allowed?
-        @schema_definition&.schema&.fetch(:additional_properties, false)
-      end
-
-      # Returns the property names defined in the schema.
-      #
-      # @return [Array<Symbol>] Array of property names as symbols.
-      def properties
-        (@schema_definition&.schema&.dig(:properties) || {}).keys
-      end
-
-      private
-
-      # Builds the schema using the provided schema definition.
-      #
-      # @param schema_definition [SchemaDefinition] The schema definition.
-      # @return [Hash] The built schema.
-      def build_schema(schema_definition)
-        Builders::ObjectBuilder.new(schema_definition).build
-      end
+      include SchemaBase::ClassMethods
     end
   end
 end

data/lib/easy_talk/schema_base.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative 'builders/object_builder'
+require_relative 'schema_definition'
+
+module EasyTalk
+  # Shared foundation for both EasyTalk::Schema and EasyTalk::Model.
+  #
+  # This module extracts the common instance and class methods so that
+  # Schema (lightweight, no validations) and Model (full ActiveModel
+  # validations) stay in sync without code duplication.
+  module SchemaBase
+    # Instance methods shared by Schema and Model.
+    #
+    # Each including module provides its own `initialize` that:
+    #   1. Sets `@additional_properties = {}`
+    #   2. Performs attribute assignment (manually or via ActiveModel)
+    #   3. Calls `initialize_schema_properties(provided_keys)`
+    module InstanceMethods
+      private
+
+      def initialize_schema_properties(provided_keys)
+        schema_def = self.class.schema_definition
+        return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
+
+        (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
+          process_property_initialization(prop_name, prop_definition, provided_keys)
+        end
+      end
+
+      def process_property_initialization(prop_name, prop_definition, provided_keys)
+        defined_type = prop_definition[:type]
+        nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
+
+        apply_default_value(prop_name, prop_definition, provided_keys)
+
+        current_value = public_send(prop_name)
+        return if nilable_type && current_value.nil?
+
+        defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
+        instantiate_nested_models(prop_name, defined_type, current_value)
+      end
+
+      def apply_default_value(prop_name, prop_definition, provided_keys)
+        return if provided_keys.include?(prop_name)
+
+        default_value = prop_definition.dig(:constraints, :default)
+        public_send("#{prop_name}=", EasyTalk.deep_dup(default_value)) unless default_value.nil?
+      end
+
+      def instantiate_nested_models(prop_name, defined_type, current_value)
+        if easy_talk_class?(defined_type) && current_value.is_a?(Hash)
+          public_send("#{prop_name}=", defined_type.new(current_value))
+          return
+        end
+
+        instantiate_array_items(prop_name, defined_type, current_value)
+      end
+
+      def easy_talk_class?(type)
+        type.is_a?(Class) && (
+          type.include?(EasyTalk::Model) || type.include?(EasyTalk::Schema)
+        )
+      end
+
+      def instantiate_array_items(prop_name, defined_type, current_value)
+        return unless defined_type.is_a?(T::Types::TypedArray) && current_value.is_a?(Array)
+
+        item_type = defined_type.type.respond_to?(:raw_type) ? defined_type.type.raw_type : nil
+        return unless easy_talk_class?(item_type)
+
+        instantiated = current_value.map { |item| item.is_a?(Hash) ? item_type.new(item) : item }
+        public_send("#{prop_name}=", instantiated)
+      end
+
+      public
+
+      def method_missing(method_name, *args)
+        method_string = method_name.to_s
+        if method_string.end_with?('=')
+          property_name = method_string.chomp('=')
+          if self.class.additional_properties_allowed?
+            @additional_properties[property_name] = args.first
+          else
+            super
+          end
+        elsif self.class.additional_properties_allowed? && @additional_properties.key?(method_string)
+          @additional_properties[method_string]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        return super unless self.class.additional_properties_allowed?
+
+        method_string = method_name.to_s
+        method_string.end_with?('=') || @additional_properties.key?(method_string) || super
+      end
+
+      def to_hash
+        properties_to_include = (self.class.schema_definition.schema[:properties] || {}).keys
+        return {} if properties_to_include.empty?
+
+        properties_to_include.to_h { |prop| [prop.to_s, send(prop)] }
+      end
+
+      def as_json(_options = {})
+        to_hash.merge(@additional_properties)
+      end
+
+      def to_h
+        to_hash.merge(@additional_properties)
+      end
+
+      def ==(other)
+        case other
+        when Hash
+          self_hash = (self.class.schema_definition.schema[:properties] || {}).keys.to_h { |prop| [prop, send(prop)] }
+          other_normalized = other.transform_keys(&:to_sym)
+          self_hash == other_normalized
+        else
+          super
+        end
+      end
+    end
+
+    # Class methods shared by Schema and Model.
+    module ClassMethods
+      include SchemaMethods
+
+      def schema
+        @schema ||= if defined?(@schema_definition) && @schema_definition
+                      build_schema(@schema_definition)
+                    else
+                      {}
+                    end
+      end
+
+      def define_schema(&)
+        raise ArgumentError, 'The class must have a name' unless name.present?
+
+        clear_schema_state!
+
+        @schema_definition = SchemaDefinition.new(name)
+        @schema_definition.klass = self
+        @schema_definition.instance_eval(&)
+
+        defined_properties = (@schema_definition.schema[:properties] || {}).keys
+        attr_accessor(*defined_properties)
+
+        @schema_definition
+      end
+
+      def schema_definition
+        @schema_definition ||= {}
+      end
+
+      def additional_properties_allowed?
+        ap = @schema_definition&.schema&.fetch(:additional_properties, false)
+        ap == true || ap.is_a?(Class) || ap.is_a?(Hash)
+      end
+
+      def properties
+        (@schema_definition&.schema&.dig(:properties) || {}).keys
+      end
+
+      private
+
+      def clear_schema_state!
+        @schema = nil
+        @json_schema = nil
+      end
+
+      def build_schema(schema_definition)
+        Builders::ObjectBuilder.new(schema_definition).build
+      end
+    end
+  end
+end