easy_talk_two 1.1.0

data/lib/easy_talk/model.rb

@@ -0,0 +1,197 @@
+# 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 'active_model'
+require_relative 'builders/object_builder'
+require_relative 'schema_definition'
+require_relative 'active_record_schema_builder'
+
+module EasyTalk
+  # The `Model` module is a mixin that provides functionality for defining and accessing the schema of a model.
+  #
+  # It includes methods for defining the schema, retrieving the schema definition,
+  # and generating the JSON schema for the model.
+  #
+  # Example usage:
+  #
+  #   class Person
+  #     include EasyTalk::Model
+  #
+  #     define_schema do
+  #       property :name, String, description: 'The person\'s name'
+  #       property :age, Integer, description: 'The person\'s age'
+  #     end
+  #   end
+  #
+  #   Person.json_schema #=> returns the JSON schema for Person
+  #   jim = Person.new(name: 'Jim', age: 30)
+  #   jim.valid? #=> returns true
+  #
+  # @see SchemaDefinition
+  module Model
+    def self.included(base)
+      base.include ActiveModel::API # Include ActiveModel::API in the class including EasyTalk::Model
+      base.include ActiveModel::Validations
+      base.extend ActiveModel::Callbacks
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+
+      # Apply ActiveRecord-specific functionality if appropriate
+      return unless defined?(ActiveRecord) && base.ancestors.include?(ActiveRecord::Base)
+
+      base.extend(ActiveRecordClassMethods)
+    end
+
+    module InstanceMethods
+      def initialize(attributes = {})
+        @additional_properties = {}
+        super
+      end
+
+      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)
+        method_string = method_name.to_s
+        method_string.end_with?('=') ? method_string.chomp('=') : method_string
+        self.class.additional_properties_allowed? || super
+      end
+
+      # Add to_hash method to convert defined properties to hash
+      def to_hash
+        return {} unless self.class.properties
+
+        self.class.properties.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
+    end
+
+    # Module containing class-level methods for defining and accessing the schema of a model.
+    module ClassMethods
+      # Returns the schema for the model.
+      #
+      # @return [Schema] The schema for the model.
+      def schema
+        @schema ||= if defined?(@schema_definition) && @schema_definition
+                      # Schema defined explicitly via define_schema
+                      build_schema(@schema_definition)
+                    elsif respond_to?(:active_record_schema_definition)
+                      # ActiveRecord model without explicit schema definition
+                      build_schema(active_record_schema_definition)
+                    else
+                      # Default case - empty schema
+                      {}
+                    end
+      end
+
+      # Returns the reference template for the model.
+      #
+      # @return [String] The reference template for the model.
+      def ref_template
+        "#/$defs/#{name}"
+      end
+
+      def properties
+        @properties ||= begin
+          return unless schema[:properties].present?
+
+          schema[:properties].keys.map(&:to_sym)
+        end
+      end
+
+      # Returns the JSON schema for the model.
+      #
+      # @return [Hash] The JSON schema for the model.
+      def json_schema
+        @json_schema ||= schema.as_json
+      end
+
+      # Define the schema for the model using the provided block.
+      #
+      # @yield The block to define the schema.
+      # @raise [ArgumentError] If the class does not have a name.
+      def define_schema(&block)
+        raise ArgumentError, 'The class must have a name' unless name.present?
+
+        @schema_definition = SchemaDefinition.new(name)
+        @schema_definition.instance_eval(&block)
+        attr_accessor(*properties)
+
+        @schema_definition
+      end
+
+      # 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?
+        @schema_definition&.schema&.fetch(:additional_properties, false)
+      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
+
+    # Module containing ActiveRecord-specific methods for schema generation
+    module ActiveRecordClassMethods
+      # Gets a SchemaDefinition that's built from the ActiveRecord database schema
+      #
+      # @return [SchemaDefinition] A schema definition built from the database
+      def active_record_schema_definition
+        @active_record_schema_definition ||= ActiveRecordSchemaBuilder.new(self).build_schema_definition
+      end
+
+      # Store enhancements to be applied to the schema
+      #
+      # @return [Hash] The schema enhancements
+      def schema_enhancements
+        @schema_enhancements ||= {}
+      end
+
+      # Enhance the generated schema with additional information
+      #
+      # @param enhancements [Hash] The schema enhancements
+      # @return [void]
+      def enhance_schema(enhancements)
+        @schema_enhancements = enhancements
+        # Clear cached values to force regeneration
+        @active_record_schema_definition = nil
+        @schema = nil
+        @json_schema = nil
+      end
+    end
+  end
+end

data/lib/easy_talk/property.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'builders/integer_builder'
+require_relative 'builders/number_builder'
+require_relative 'builders/boolean_builder'
+require_relative 'builders/null_builder'
+require_relative 'builders/string_builder'
+require_relative 'builders/temporal_builder'
+require_relative 'builders/composition_builder'
+require_relative 'builders/typed_array_builder'
+require_relative 'builders/union_builder'
+
+# frozen_string_literal: true
+
+# EasyTalk module provides classes for building JSON schema properties.
+#
+# This module contains the `Property` class, which is used to build a JSON schema property.
+# It also defines a constant `TYPE_TO_BUILDER` which maps property types to their respective builders.
+#
+# Example usage:
+#   property = EasyTalk::Property.new(:name, 'String', minLength: 3, maxLength: 50)
+#   property.build
+#
+# @see EasyTalk::Property
+module EasyTalk
+  # Property class for building a JSON schema property.
+  class Property
+    extend T::Sig
+    attr_reader :name, :type, :constraints
+
+    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.
+    # @param type [Object] The type of the property.
+    # @param constraints [Hash] The property constraints.
+    # @raise [ArgumentError] If the property type is missing.
+    sig do
+      params(name: Symbol, type: T.any(String, Object),
+             constraints: T::Hash[Symbol, T.untyped]).void
+    end
+    def initialize(name, type = nil, constraints = {})
+      @name = name
+      @type = type
+      @constraints = constraints
+      raise ArgumentError, 'property type is missing' if type.blank?
+    end
+
+    # Builds the property based on the specified type, constraints, and builder.
+    #
+    # If the type responds to the `schema` method, it returns the schema of the type.
+    # Otherwise, it returns 'object'.
+    #
+    # If a builder is specified, it uses the builder to build the property.
+    # The arguments passed to the builder depend on whether the builder is a collection type or not.
+    #
+    # @return [Object] The built property.
+    def build
+      if nilable_type?
+        build_nilable_schema
+      elsif builder
+        args = builder.collection_type? ? [name, type, constraints] : [name, constraints]
+        builder.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'
+      end
+    end
+
+    # Converts the object to a JSON representation.
+    #
+    # @param _args [Array] Optional arguments
+    # @return [Hash] The JSON representation of the object
+    def as_json(*_args)
+      build.as_json
+    end
+
+    # Returns the builder associated with the property type.
+    #
+    # The builder is responsible for constructing the property based on its type.
+    # It looks up the builder based on the type's class name or name.
+    #
+    # @return [Builder] The builder associated with the property type.
+    def builder
+      @builder ||= TYPE_TO_BUILDER[type.class.name.to_s] || TYPE_TO_BUILDER[type.name.to_s]
+    end
+
+    private
+
+    def nilable_type?
+      return unless type.respond_to?(:types)
+      return unless type.types.all? { |t| t.respond_to?(:raw_type) }
+
+      type.types.any? { |t| t.raw_type == NilClass }
+    end
+
+    def build_nilable_schema
+      # Extract the non-nil type from the Union
+      actual_type = type.types.find { |t| t != NilClass }
+
+      # Create a property with the actual type
+      non_nil_schema = Property.new(name, actual_type, constraints).build
+
+      # Merge the types into an array
+      non_nil_schema.merge(
+        type: [non_nil_schema[:type], 'null']
+      )
+    end
+  end
+end

data/lib/easy_talk/schema_definition.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'keywords'
+require_relative 'types/composer'
+
+module EasyTalk
+  #
+  #= EasyTalk \SchemaDefinition
+  # SchemaDefinition provides the methods for defining a schema within the define_schema block.
+  # The @schema is a hash that contains the unvalidated schema definition for the model.
+  # A SchemaDefinition instanace is the passed to the Builder.build_schema method to validate and compile the schema.
+  class SchemaDefinition
+    extend T::Sig
+    extend T::AnyOf
+    extend T::OneOf
+    extend T::AllOf
+
+    attr_reader :name, :schema
+
+    def initialize(name, schema = {})
+      @schema = schema
+      @schema[:additional_properties] = false unless schema.key?(:additional_properties)
+      @name = name
+    end
+
+    EasyTalk::KEYWORDS.each do |keyword|
+      define_method(keyword) do |*values|
+        @schema[keyword] = values.size > 1 ? values : values.first
+      end
+    end
+
+    def compose(*subschemas)
+      @schema[:subschemas] ||= []
+      @schema[:subschemas] += subschemas
+    end
+
+    sig do
+      params(name: T.any(Symbol, String), type: T.untyped, constraints: T.untyped, blk: T.nilable(T.proc.void)).void
+    end
+    def property(name, type, constraints = {}, &blk)
+      validate_property_name(name)
+      @schema[:properties] ||= {}
+
+      if block_given?
+        raise ArgumentError, 'Block-style sub-schemas are no longer supported. Use class references as types instead.'
+      end
+
+      @schema[:properties][name] = { type:, constraints: }
+    end
+
+    def validate_property_name(name)
+      return if name.to_s.match?(/^[A-Za-z_][A-Za-z0-9_]*$/)
+
+      raise InvalidPropertyNameError,
+            "Invalid property name '#{name}'. Must start with letter/underscore and contain only letters, numbers, underscores"
+    end
+
+    def optional?
+      @schema[:optional]
+    end
+
+    # Helper method for nullable and optional properties
+    def nullable_optional_property(name, type, constraints = {}, &blk)
+      # Ensure type is nilable
+      nilable_type = if type.respond_to?(:nilable?) && type.nilable?
+                       type
+                     else
+                       T.nilable(type)
+                     end
+
+      # Ensure constraints include optional: true
+      constraints = constraints.merge(optional: true)
+
+      # Call standard property method
+      property(name, nilable_type, constraints)
+    end
+  end
+end

data/lib/easy_talk/sorbet_extension.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# This module provides additional functionality for working with Sorbet types.
+module SorbetExtension
+  # Checks if the types in the collection include the NilClass type.
+  #
+  # @return [Boolean] true if the types include NilClass, false otherwise.
+  def nilable?
+    types.any? do |type|
+      type.respond_to?(:raw_type) && type.raw_type == NilClass
+    end
+  end
+end
+
+T::Types::Union.include SorbetExtension

data/lib/easy_talk/tools/function_builder.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module Tools
+    # FunctionBuilder is a module that builds a hash with the function type and function details.
+    # The return value is typically passed as argument to LLM function calling APIs.
+    module FunctionBuilder
+      class << self
+        # Creates a new function object based on the given model.
+        #
+        # @param [Model] model The EasyTalk model containing the function details.
+        # @return [Hash] The function object.
+        def new(model)
+          {
+            type: 'function',
+            function: {
+              name: generate_function_name(model),
+              description: generate_function_description(model),
+              parameters: model.json_schema
+            }
+          }
+        end
+
+        def generate_function_name(model)
+          model.schema.fetch(:title, model.name)
+        end
+
+        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)
+
+            model.instructions
+          else
+            "Correctly extracted `#{model.name}` with all the required parameters and correct types."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/types/base_composer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module Types
+    # no-doc
+    class BaseComposer
+      extend T::Sig
+      extend T::Generic
+
+      Elem = type_member
+
+      sig { returns(T::Array[Elem]) }
+      attr_reader :items
+
+      # Initializes a new instance of the BaseComposer class.
+      #
+      # @param args [Array] the items to be assigned to the instance variable @items
+      def initialize(*args)
+        @items = args
+      end
+    end
+  end
+end

data/lib/easy_talk/types/composer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'base_composer'
+
+module EasyTalk
+  module Types
+    # Base class for composition types
+    class Composer < BaseComposer
+      # Returns the name of the composition type.
+      def self.name
+        raise NotImplementedError, "#{self.class.name} must implement the name method"
+      end
+
+      # Returns the name of the composition type.
+      def name
+        self.class.name
+      end
+
+      # Represents a composition type that allows all of the specified types.
+      class AllOf < Composer
+        def self.name
+          :allOf
+        end
+
+        def name
+          :allOf
+        end
+      end
+
+      # Represents a composition type that allows any of the specified types.
+      class AnyOf < Composer
+        def self.name
+          :anyOf
+        end
+
+        def name
+          :anyOf
+        end
+      end
+
+      # Represents a composition type that allows one of the specified types.
+      class OneOf < Composer
+        def self.name
+          :oneOf
+        end
+
+        def name
+          :oneOf
+        end
+      end
+    end
+  end
+end
+
+# Shorthand module for accessing the AllOf composer
+module T
+  module AllOf
+    # Creates a new instance of `EasyTalk::Types::Composer::AllOf` with the given arguments.
+    #
+    # @param args [Array] the list of arguments to be passed to the constructor
+    # @return [EasyTalk::Types::Composer::AllOf] a new instance
+    def self.[](*args)
+      EasyTalk::Types::Composer::AllOf.new(*args)
+    end
+  end
+
+  # Shorthand module for accessing the AnyOf composer
+  module AnyOf
+    # Creates a new instance of `EasyTalk::Types::Composer::AnyOf` with the given arguments.
+    #
+    # @param args [Array] the list of arguments to be passed to the constructor
+    # @return [EasyTalk::Types::Composer::AnyOf] a new instance
+    def self.[](*args)
+      EasyTalk::Types::Composer::AnyOf.new(*args)
+    end
+  end
+
+  # Shorthand module for accessing the OneOf composer
+  module OneOf
+    # Creates a new instance of `EasyTalk::Types::Composer::OneOf` with the given arguments.
+    #
+    # @param args [Array] the list of arguments to be passed to the constructor
+    # @return [EasyTalk::Types::Composer::OneOf] a new instance
+    def self.[](*args)
+      EasyTalk::Types::Composer::OneOf.new(*args)
+    end
+  end
+end

data/lib/easy_talk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  VERSION = '1.1.0'
+end

data/lib/easy_talk.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# The EasyTalk module is the main namespace for the gem.
+module EasyTalk
+  require 'sorbet-runtime'
+  require 'easy_talk/sorbet_extension'
+  require 'easy_talk/errors'
+  require 'easy_talk/errors_helper'
+  require 'easy_talk/configuration'
+  require 'easy_talk/types/composer'
+  require 'easy_talk/model'
+  require 'easy_talk/property'
+  require 'easy_talk/schema_definition'
+  require 'easy_talk/tools/function_builder'
+  require 'easy_talk/version'
+
+  def self.assert_valid_property_options(property_name, options, *valid_keys)
+    valid_keys.flatten!
+    options.each_key do |k|
+      next if valid_keys.include?(k)
+
+      ErrorHelper.raise_unknown_option_error(property_name: property_name, option: options, valid_options: valid_keys)
+    end
+  end
+
+  def self.configure_nilable_behavior(nilable_is_optional = false)
+    configuration.nilable_is_optional = nilable_is_optional
+  end
+end