easy_talk 3.0.0 → 3.2.0

data/lib/easy_talk/property.rb

@@ -45,28 +45,6 @@ module EasyTalk
     # @return [Hash<Symbol, Object>] Additional constraints applied to the property
     attr_reader :constraints
 
-    # Mapping of Ruby type names to their corresponding schema builder classes.
-    # Each builder knows how to convert a specific Ruby type to JSON Schema.
-    #
-    # @api private
-    TYPE_TO_BUILDER = {
-      'String' => Builders::StringBuilder,
-      'Integer' => Builders::IntegerBuilder,
-      'Float' => Builders::NumberBuilder,
-      'BigDecimal' => Builders::NumberBuilder,
-      'T::Boolean' => Builders::BooleanBuilder,
-      'TrueClass' => Builders::BooleanBuilder,
-      'NilClass' => Builders::NullBuilder,
-      'Date' => Builders::TemporalBuilder::DateBuilder,
-      'DateTime' => Builders::TemporalBuilder::DatetimeBuilder,
-      'Time' => Builders::TemporalBuilder::TimeBuilder,
-      'anyOf' => Builders::CompositionBuilder::AnyOfBuilder,
-      'allOf' => Builders::CompositionBuilder::AllOfBuilder,
-      'oneOf' => Builders::CompositionBuilder::OneOfBuilder,
-      'T::Types::TypedArray' => Builders::TypedArrayBuilder,
-      'T::Types::Union' => Builders::UnionBuilder
-    }.freeze
-
     # Initializes a new instance of the Property class.
     #
     # @param name [Symbol] The name of the property
@@ -101,31 +79,43 @@ module EasyTalk
     # This method handles different types of properties:
     # - Nilable types (can be null)
     # - Types with dedicated builders
-    # - Types that implement their own schema method
+    # - Types that implement their own schema method (EasyTalk models)
     # - Default fallback to 'object' type
     #
+    # When use_refs is enabled (globally or per-property), EasyTalk models
+    # are referenced via $ref instead of being inlined.
+    #
     # @return [Hash] The complete JSON Schema property definition
     #
     # @example Simple string property
     #   property = Property.new(:name, 'String')
     #   property.build  # => {"type"=>"string"}
     #
-    # @example Complex nested schema
+    # @example Complex nested schema (inlined)
     #   address = Address.new  # A class with a .schema method
     #   property = Property.new(:shipping_address, address, description: "Shipping address")
     #   property.build  # => Address schema merged with the description constraint
+    #
+    # @example Nested schema with $ref
+    #   property = Property.new(:shipping_address, Address, ref: true)
+    #   property.build  # => {"$ref"=>"#/$defs/Address", ...constraints}
     def build
       if nilable_type?
         build_nilable_schema
-      elsif builder
-        args = builder.collection_type? ? [name, type, constraints] : [name, constraints]
-        builder.new(*args).build
+      elsif RefHelper.should_use_ref?(type, constraints)
+        RefHelper.build_ref_schema(type, constraints)
+      elsif (resolved = find_builder_for_type)
+        builder_class, is_collection = resolved
+        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)
       else
-        'object'
+        raise UnknownTypeError,
+              "Unknown type '#{type.inspect}' for property '#{name}'. " \
+              'Register a custom builder with EasyTalk.register_type or use a supported type.'
       end
     end
 
@@ -142,28 +132,18 @@ module EasyTalk
       build.as_json
     end
 
-    # Returns the builder class associated with the property type.
-    #
-    # The builder is responsible for converting the Ruby type to a JSON Schema type.
-    #
-    # @return [Class, nil] The builder class for this property's type, or nil if no dedicated builder exists
-    # @see #find_builder_for_type
-    def builder
-      @builder ||= find_builder_for_type
-    end
-
     private
 
-    # Finds the appropriate builder for the current type.
+    # Finds the appropriate builder for the current type using the Builders::Registry.
     #
-    # First checks if there's a builder for the class name, then falls back
-    # to checking if there's a builder for the type's name (if it responds to :name).
+    # The registry is checked for a matching builder based on the type's class name
+    # or the type's own name.
     #
-    # @return [Class, nil] The builder class for this type, or nil if none matches
+    # @return [Array(Class, Boolean), nil] A tuple of [builder_class, is_collection] or nil if none matches
     # @api private
+    # @see Builders::Registry.resolve
     def find_builder_for_type
-      TYPE_TO_BUILDER[type.class.name.to_s] ||
-        (type.respond_to?(:name) ? TYPE_TO_BUILDER[type.name.to_s] : nil)
+      Builders::Registry.resolve(type)
     end
 
     # Determines if the type is nilable (can be nil).
@@ -193,6 +173,14 @@ module EasyTalk
 
       return { type: 'null' } unless actual_type
 
+      # Check if the underlying type is an EasyTalk model that should use $ref
+      if RefHelper.should_use_ref_for_type?(actual_type, constraints)
+        # Use anyOf with $ref and null type
+        ref_constraints = constraints.except(:ref, :optional)
+        schema = { anyOf: [{ '$ref': actual_type.ref_template }, { type: 'null' }] }
+        return ref_constraints.empty? ? schema : schema.merge(ref_constraints)
+      end
+
       # Create a property with the actual type
       non_nil_schema = Property.new(name, actual_type, constraints).build
 

data/lib/easy_talk/ref_helper.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'model_helper'
+
+module EasyTalk
+  module RefHelper
+    def self.should_use_ref?(type, constraints)
+      ModelHelper.easytalk_model?(type) && should_use_ref_for_type?(type, constraints)
+    end
+
+    def self.should_use_ref_for_type?(type, constraints)
+      return false unless ModelHelper.easytalk_model?(type)
+
+      # Per-property constraint takes precedence
+      if constraints.key?(:ref)
+        constraints[:ref]
+      else
+        EasyTalk.configuration.use_refs
+      end
+    end
+
+    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))
+    end
+  end
+end

data/lib/easy_talk/schema.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'active_support'
+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'
+
+module EasyTalk
+  # A lightweight module for schema generation without ActiveModel validations.
+  #
+  # Use this module when you need JSON Schema generation without the overhead
+  # of ActiveModel validations. This is ideal for:
+  # - API documentation and OpenAPI spec generation
+  # - Schema-first design where validation happens elsewhere
+  # - High-performance scenarios where validation overhead is unwanted
+  # - Generating schemas for external systems
+  #
+  # Unlike EasyTalk::Model, this module does NOT include ActiveModel::API or
+  # ActiveModel::Validations, so instances will not respond to `valid?` or have
+  # validation errors.
+  #
+  # @example Basic usage
+  #   class ApiContract
+  #     include EasyTalk::Schema
+  #
+  #     define_schema do
+  #       title 'API Contract'
+  #       property :name, String, min_length: 2
+  #       property :age, Integer, minimum: 0
+  #     end
+  #   end
+  #
+  #   ApiContract.json_schema  # => { "type" => "object", ... }
+  #   contract = ApiContract.new(name: 'Test', age: 25)
+  #   contract.name # => 'Test'
+  #   contract.valid? # => NoMethodError (no ActiveModel)
+  #
+  # @see EasyTalk::Model For a full-featured module with validations
+  #
+  module Schema
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+
+    # Instance methods for schema-only models.
+    module InstanceMethods
+      # Initialize the schema object with attributes.
+      #
+      # @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
+
+      # 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
+      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
+
+      # Convert to hash including additional properties.
+      #
+      # @return [Hash] The combined hash
+      def to_h
+        to_hash.merge(@additional_properties)
+      end
+
+      # 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)
+          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
+    end
+  end
+end

data/lib/easy_talk/schema_definition.rb

@@ -24,6 +24,7 @@ module EasyTalk
       @schema[:additional_properties] = false 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|
@@ -38,7 +39,8 @@ module EasyTalk
     end
 
     def property(name, type, constraints = {}, &)
-      validate_property_name(name)
+      constraints[:as] ||= @property_naming_strategy.call(name)
+      validate_property_name(constraints[:as])
       @schema[:properties] ||= {}
 
       if block_given?
@@ -76,5 +78,9 @@ module EasyTalk
       # Call standard property method
       property(name, nilable_type, constraints)
     end
+
+    def property_naming_strategy(strategy)
+      @property_naming_strategy = EasyTalk::NamingStrategies.derive_strategy(strategy)
+    end
   end
 end

data/lib/easy_talk/schema_methods.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  # Shared methods for JSON Schema generation.
+  #
+  # This module provides common functionality for building JSON schemas,
+  # including $schema and $id resolution. It is included in both
+  # EasyTalk::Model and EasyTalk::Schema to avoid code duplication.
+  #
+  # @note Classes including this module must define:
+  #   - `name` - The class name (used in ref_template)
+  #   - `schema` - The built schema hash (used in json_schema)
+  #   - `@schema_definition` - Instance variable with schema metadata
+  #
+  module SchemaMethods
+    # Returns the reference template for the model.
+    #
+    # @return [String] The reference template for the model.
+    def ref_template
+      "#/$defs/#{name}"
+    end
+
+    # Returns the JSON schema for the model.
+    # This is the final output that includes the $schema keyword if configured.
+    #
+    # @return [Hash] The JSON schema for the model.
+    def json_schema
+      @json_schema ||= build_json_schema
+    end
+
+    private
+
+    # Builds the final JSON schema with optional $schema and $id keywords.
+    #
+    # @return [Hash] The JSON schema.
+    def build_json_schema
+      result = schema.as_json
+      schema_uri = resolve_schema_uri
+      id_uri = resolve_schema_id
+
+      prefix = {}
+      prefix['$schema'] = schema_uri if schema_uri
+      prefix['$id'] = id_uri if id_uri
+
+      return result if prefix.empty?
+
+      prefix.merge(result)
+    end
+
+    # Resolves the schema URI from per-model setting or global config.
+    #
+    # @return [String, nil] The schema URI.
+    def resolve_schema_uri
+      model_version = @schema_definition&.schema&.dig(:schema_version)
+
+      if model_version
+        return nil if model_version == :none
+
+        Configuration::SCHEMA_VERSIONS[model_version] || model_version.to_s
+      else
+        EasyTalk.configuration.schema_uri
+      end
+    end
+
+    # Resolves the schema ID from per-model setting or global config.
+    #
+    # @return [String, nil] The schema ID.
+    def resolve_schema_id
+      model_id = @schema_definition&.schema&.dig(:schema_id)
+
+      if model_id
+        return nil if model_id == :none
+
+        model_id.to_s
+      else
+        EasyTalk.configuration.schema_id
+      end
+    end
+  end
+end

data/lib/easy_talk/tools/function_builder.rb

@@ -27,7 +27,7 @@ module EasyTalk
 
         def generate_function_description(model)
           if model.respond_to?(:instructions)
-            raise Instructor::Error, 'The instructions must be a string' unless model.instructions.is_a?(String)
+            raise InvalidInstructionsError, 'The instructions must be a string' unless model.instructions.is_a?(String)
 
             model.instructions
           else

data/lib/easy_talk/type_introspection.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module EasyTalk
+  # Centralized module for robust type introspection.
+  #
+  # This module provides predicate methods for detecting types without relying
+  # on brittle string-based checks. It uses Sorbet's type system properly and
+  # handles edge cases gracefully.
+  #
+  # @example Checking if a type is boolean
+  #   TypeIntrospection.boolean_type?(T::Boolean) # => true
+  #   TypeIntrospection.boolean_type?(TrueClass)  # => true
+  #   TypeIntrospection.boolean_type?(String)     # => false
+  #
+  # @example Getting JSON Schema type
+  #   TypeIntrospection.json_schema_type(Integer) # => 'integer'
+  #   TypeIntrospection.json_schema_type(Float)   # => 'number'
+  #
+  module TypeIntrospection
+    # Mapping of Ruby classes to JSON Schema types
+    PRIMITIVE_TO_JSON_SCHEMA = {
+      String => 'string',
+      Integer => 'integer',
+      Float => 'number',
+      BigDecimal => 'number',
+      TrueClass => 'boolean',
+      FalseClass => 'boolean',
+      NilClass => 'null'
+    }.freeze
+
+    class << self
+      # Check if type represents a boolean (T::Boolean or TrueClass/FalseClass).
+      #
+      # @param type [Object] The type to check
+      # @return [Boolean] true if the type is a boolean type
+      #
+      # @example
+      #   boolean_type?(T::Boolean)  # => true
+      #   boolean_type?(TrueClass)   # => true
+      #   boolean_type?(FalseClass)  # => true
+      #   boolean_type?(String)      # => false
+      def boolean_type?(type)
+        return false if type.nil?
+        return true if [TrueClass, FalseClass].include?(type)
+        return true if type.respond_to?(:raw_type) && [TrueClass, FalseClass].include?(type.raw_type)
+
+        # Check for T::Boolean which is a TypeAlias with name 'T::Boolean'
+        return true if type.respond_to?(:name) && type.name == 'T::Boolean'
+
+        # Check for union types containing TrueClass and FalseClass
+        if type.respond_to?(:types)
+          type_classes = type.types.map { |t| t.respond_to?(:raw_type) ? t.raw_type : t }
+          return type_classes.sort_by(&:name) == [FalseClass, TrueClass].sort_by(&:name)
+        end
+
+        false
+      end
+
+      # Check if type is a typed array (T::Array[...]).
+      #
+      # @param type [Object] The type to check
+      # @return [Boolean] true if the type is a typed array
+      #
+      # @example
+      #   typed_array?(T::Array[String]) # => true
+      #   typed_array?(Array)            # => false
+      def typed_array?(type)
+        return false if type.nil?
+
+        type.is_a?(T::Types::TypedArray)
+      end
+
+      # Check if type is nilable (T.nilable(...)).
+      #
+      # @param type [Object] The type to check
+      # @return [Boolean] true if the type is nilable
+      #
+      # @example
+      #   nilable_type?(T.nilable(String)) # => true
+      #   nilable_type?(String)            # => false
+      def nilable_type?(type)
+        return false if type.nil?
+
+        type.respond_to?(:nilable?) && type.nilable?
+      end
+
+      # Check if type is a primitive Ruby type.
+      #
+      # @param type [Object] The type to check
+      # @return [Boolean] true if the type is a primitive
+      def primitive_type?(type)
+        return false if type.nil?
+
+        resolved = if type.is_a?(Class)
+                     type
+                   elsif type.respond_to?(:raw_type)
+                     type.raw_type
+                   end
+        PRIMITIVE_TO_JSON_SCHEMA.key?(resolved)
+      end
+
+      # Get JSON Schema type string for a Ruby type.
+      #
+      # @param type [Object] The type to convert
+      # @return [String] The JSON Schema type string
+      #
+      # @example
+      #   json_schema_type(Integer)    # => 'integer'
+      #   json_schema_type(Float)      # => 'number'
+      #   json_schema_type(BigDecimal) # => 'number'
+      #   json_schema_type(String)     # => 'string'
+      def json_schema_type(type)
+        return 'object' if type.nil?
+        return 'boolean' if boolean_type?(type)
+
+        resolved_class = if type.is_a?(Class)
+                           type
+                         elsif type.respond_to?(:raw_type)
+                           type.raw_type
+                         end
+
+        PRIMITIVE_TO_JSON_SCHEMA[resolved_class] || resolved_class&.name&.downcase || 'object'
+      end
+
+      # Get the Ruby class for a type, handling Sorbet types.
+      #
+      # @param type [Object] The type to resolve
+      # @return [Class, Array<Class>, nil] The resolved class or classes
+      #
+      # @example
+      #   get_type_class(String)           # => String
+      #   get_type_class(T::Boolean)       # => [TrueClass, FalseClass]
+      #   get_type_class(T::Array[String]) # => Array
+      def get_type_class(type)
+        return nil if type.nil?
+        return type if type.is_a?(Class)
+        return type.raw_type if type.respond_to?(:raw_type)
+        return Array if typed_array?(type)
+        return [TrueClass, FalseClass] if boolean_type?(type)
+
+        if nilable_type?(type)
+          inner = extract_inner_type(type)
+          return get_type_class(inner) if inner && inner != type
+        end
+
+        nil
+      end
+
+      # Extract inner type from nilable or complex types.
+      #
+      # @param type [Object] The type to unwrap
+      # @return [Object] The inner type, or the original type if not wrapped
+      #
+      # @example
+      #   extract_inner_type(T.nilable(String)) # => String
+      def extract_inner_type(type)
+        return type if type.nil?
+
+        if type.respond_to?(:unwrap_nilable)
+          unwrapped = type.unwrap_nilable
+          return unwrapped.respond_to?(:raw_type) ? unwrapped.raw_type : unwrapped
+        end
+
+        if type.respond_to?(:types)
+          non_nil = type.types.find do |t|
+            raw = t.respond_to?(:raw_type) ? t.raw_type : t
+            raw != NilClass
+          end
+          return non_nil.respond_to?(:raw_type) ? non_nil.raw_type : non_nil if non_nil
+        end
+
+        type
+      end
+    end
+  end
+end

data/lib/easy_talk/types/base_composer.rb

@@ -3,7 +3,7 @@
 module EasyTalk
   module Types
     # no-doc
-    class BaseComposer
+    class BaseComposer < T::Types::Base
       extend T::Sig
       extend T::Generic
 
@@ -16,6 +16,7 @@ module EasyTalk
       #
       # @param args [Array] the items to be assigned to the instance variable @items
       def initialize(*args)
+        super()
         @items = args
       end
     end

data/lib/easy_talk/types/composer.rb

@@ -16,6 +16,10 @@ module EasyTalk
         self.class.name
       end
 
+      def to_s
+        name.to_s
+      end
+
       # Represents a composition type that allows all of the specified types.
       class AllOf < Composer
         def self.name