easy_talk 0.2.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4dbef0c74efa9996294e1aa20f5beef89d7d418df8be196cd794ece88c5ec67
-  data.tar.gz: 79b1c90879f26967e94e56317fff93e39bc1735e41a5c5975a3a922e556c2291
+  metadata.gz: fa39fe0359df9334a186807b3e67679b752806db59eb9b03829ec875c6382818
+  data.tar.gz: 150814754a0604fc0149bf042c73d798fe042935ffde11b52c2254ac765c05e8
 SHA512:
-  metadata.gz: 053a079d3b233f70bd62f63708c008b2da133d2210dfdde206708a588387ee844cab5e8409a5ac7afc635ccb909dbfd82b952e6608ec79333781f2278b9c56ce
-  data.tar.gz: 9af64bd32362f6518c2576aa793047b4252e47b18a92e0edfae9b937c92d56c63ba0582146ddc86823c0cacd98ead9e4ecb83f01624e22ad93cf58d36b42c4d0
+  metadata.gz: ea9d64a999260983afac690850ae5095b4e2d00583feb1a6dd4baa0a0cb377a82566dae1245e1b767e5ff79549f28e60209b43fa3d765a8b51c46ee6969425bd
+  data.tar.gz: 20e3bea29ad389126937924f431f8729be43b172f8f868ae5fc0189d729e1d19642a9fa0e74a34322e1acafd2b74c6b2fad20bb8f081c7ea504364a2daaf3d99

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [1.0.0] - 2024-06-01
+- Use `Hash` instead of `:object` for inline object schema definition.
+example:
+```ruby
+    property :email, Hash do
+        property :address, :string
+        property :verified, :boolean
+    end
+```
+- Loosen up the gemspec version requirement. Makes it flexible to use the library with future versions of Rails (i.e 8.*).
+- Removed JSONScheemer gem dependency. 
+- The library does not validate by default anymore. Validating an instance requires that you explicitly define ActiveModel validations in your EasyTalk model. See: https://github.com/sergiobayona/easy_talk/blob/main/spec/easy_talk/activemodel_integration_spec.rb.
+- Internal improvements to `EasyTalk::ObjectBuilder` class. No changes to the public API.
+- Expanded the test suite.
+
 ## [0.2.2] - 2024-05-17
 - Fixed a bug where optional properties were not excluded from the required list.
 

data/README.md

@@ -4,10 +4,9 @@ EasyTalk is a Ruby library that simplifies defining and generating JSON Schema d
 
 Key Features
 * Intuitive Schema Definition: Use Ruby classes and methods to define JSON Schema documents easily.
-* JSON Schema Compliance: Implements the JSON Schema specification to ensure compatibility and standards adherence.
-* LLM Function Support: Ideal for integrating with Large Language Models (LLMs) such as OpenAI's GPT-3.5-turbo and GPT-4. EasyTalk enables you to effortlessly create JSON Schema documents needed to describe the inputs and outputs of LLM function calls.
-* Validation: Validates JSON inputs and outputs against defined schemas to ensure they meet expected formats and types. Write custom validations using ActiveModel's validations.
-* Integration with ActiveModel: EasyTalk integrates with ActiveModel to provide additional functionality such as attribute assignment, introspections, validations, translation (i18n), and more.
+* LLM Function Support: Ideal for integrating with Large Language Models (LLMs) such as OpenAI’s GPT series. EasyTalk enables you to effortlessly create JSON Schema documents describing the inputs and outputs of LLM function calls.
+* Schema Composition: Define EasyTalk models and reference them in other EasyTalk models to create complex schemas.
+* Validation: Write validations using ActiveModel’s validations.
 
 Inspiration
 Inspired by Python's Pydantic library, EasyTalk brings similar functionality to the Ruby ecosystem, providing a Ruby-friendly approach to JSON Schema operations.
@@ -18,85 +17,78 @@ Example Use:
 class User
   include EasyTalk::Model
 
+  validates :name, :email, :group, presence: true
+  validates :age, numericality: { greater_than_or_equal_to: 18, less_than_or_equal_to: 100 }
+
   define_schema do
     title "User"
     description "A user of the system"
     property :name, String, description: "The user's name", title: "Full Name"
-    property :email, :object do
+    property :email, Hash do
       property :address, String, format: "email", description: "The user's email", title: "Email Address"
       property :verified, T::Boolean, description: "Whether the email is verified"
     end
-    property :group, String, enum: [1, 2, 3], default: 1, description: "The user's group"
+    property :group, Integer, enum: [1, 2, 3], default: 1, description: "The user's group"
     property :age, Integer, minimum: 18, maximum: 100, description: "The user's age"
-    property :tags, T::Array[String], min_items: 1, unique_item: true, description: "The user's tags"
+    property :tags, T::Array[String], min_items: 1, unique_items: true, description: "The user's tags"
   end
 end
 ```
 
-Calling `User.json_schema` will return the JSON Schema for the User class:
+Calling `User.json_schema` will return the Ruby representation of the JSON Schema for the `User` class:
 
-```json
+```ruby
 {
-    "title": "User",
-    "description": "A user of the system",
-    "type": "object",
-    "properties": {
-        "name": {
-            "title": "Full Name",
-            "description": "The user's name",
-            "type": "string"
-        },
-        "email": {
-            "type": "object",
-            "properties": {
-                "address": {
-                    "title": "Email Address",
-                    "description": "The user's email",
-                    "type": "string",
-                    "format": "email"
-                },
-                "verified": {
-                    "type": "boolean",
-                    "description": "Whether the email is verified"
-                }
-            },
-            "required": [
-                "address",
-                "verified"
-            ]
-        },
-        "group": {
-            "type": "number",
-            "enum": [1, 2, 3],
-            "default": 1,
-            "description": "The user's group"
-        },
-        "age": {
-            "type": "integer",
-            "minimum": 18,
-            "maximum": 100,
-            "description": "The user's age"
+  "type" => "object",
+  "title" => "User",
+  "description" => "A user of the system",
+  "properties" => {
+    "name" => {
+      "type" => "string", "title" => "Full Name", "description" => "The user's name"
+    },
+    "email" => {
+      "type" => "object",
+      "properties" => {
+        "address" => {
+          "type" => "string", "title" => "Email Address", "description" => "The user's email", "format" => "email"
         },
-        "tags": {
-            "type": "array",
-            "items": {
-                "type": "string"
-            },
-            "minItems": 1,
-            "uniqueItems": true,
-            "description": "The user's tags"
+        "verified" => {
+          "type" => "boolean", "description" => "Whether the email is verified"
         }
+      },
+      "required" => ["address", "verified"]
+    },
+    "group" => {
+      "type" => "integer", "description" => "The user's group", "enum" => [1, 2, 3], "default" => 1
+    },
+    "age" => {
+      "type" => "integer", "description" => "The user's age", "minimum" => 18, "maximum" => 100
     },
-    "required:": [
-        "name",
-        "email",
-        "group",
-        "age",
-        "tags"
-    ]
+    "tags" => {
+      "type" => "array",
+      "items" => { "type" => "string" },
+      "description" => "The user's tags",
+      "minItems" => 1,
+      "uniqueItems" => true
+    }
+  },
+  "required" => ["name", "email", "group", "age", "tags"]
 }
 ```
 
+Instantiate a User object and validate it with ActiveModel validations:
+
+```ruby
+user = User.new(name: "John Doe", email: { address: "john@test.com", verified: true }, group: 1, age: 25, tags: ["tag1", "tag2"])
+user.valid? # => true
+
+user.name = nil
+user.valid? # => false
+
+user.errors.full_messages # => ["Name can't be blank"]
+user.errors["name"]       # => ["can't be blank"]
+```
+
 ## Installation
 
  install the gem by running the following command in your terminal:
@@ -105,12 +97,20 @@ Calling `User.json_schema` will return the JSON Schema for the User class:
 
 ## Usage
 
-Simply include the `EasyTalk::Model` module in your Ruby class, define the schema using the `define_schema` block and call the `json_schema` class method to generate the JSON Schema document.
+Simply include the `EasyTalk::Model` module in your Ruby class, define the schema using the `define_schema` block, and call the `json_schema` class method to generate the JSON Schema document.
 
 
 ## Schema Definition
 
-In the example above, the `define_schema` method is used to add a description and a title to the schema document. The `property` method is used to define the properties of the schema document. The `property` method accepts the name of the property as a symbol, the type, which can be a generic Ruby type or a [Sorbet type](https://sorbet.org/docs/stdlib-generics), and a hash of constraints as options.
+In the example above, the define_schema method adds a title and description to the schema. The property method defines properties of the schema document. property accepts:
+
+* A name (symbol)
+* A type (generic Ruby type like String/Integer, a Sorbet type like T::Boolean, or one of the custom types like T::AnyOf[...])
+* A hash of constraints (e.g., minimum: 18, enum: [1, 2, 3], etc.)
+
+## Why Sortbet-style types?
+
+Ruby doesn’t natively allow complex types like Array[String] or Array[Integer]. Sorbet-style types let you define these compound types clearly. EasyTalk uses this style to handle property types such as T::Array[String] or T::AnyOf[ClassA, ClassB].
 
 ## Property Constraints
 
@@ -119,88 +119,89 @@ Property constraints are type-dependent. Refer to the [CONSTRAINTS.md](CONSTRAIN
 
 ## Schema Composition
 
-EasyTalk supports schema composition. You can define a schema for a nested object by defining a new class and including the `EasyTalk::Model` module. You can then reference the nested schema in the parent schema using the following special types:
+EasyTalk supports schema composition. You can define a schema for a nested object by defining a new class that includes `EasyTalk::Model`. You can then reference the nested schema in the parent using special types:
+
+T::OneOf[Model1, Model2, ...] — The property must match at least one of the specified schemas
+T::AnyOf[Model1, Model2, ...] — The property can match any of the specified schemas
+T::AllOf[Model1, Model2, ...] — The property must match all of the specified schemas
 
-- T::OneOf[Model1, Model2, ...] - The property must match at least one of the specified schemas.
-- T::AnyOf[Model1, Model2, ...] - The property can match any of the specified schemas.
-- T::AllOf[Model1, Model2, ...] - The property must match all of the specified schemas.
+Example: A Payment object that can be a credit card, PayPal, or bank transfer:
 
-Here is an example where we define a schema for a payment object that can be a credit card, a PayPal account, or a bank transfer. The first three classes represent the schemas for the different payment methods. The `Payment` class represents the schema for the payment object where the `Details` property can be any of the payment method schemas.
 
 ```ruby
-  class CreditCard
-    include EasyTalk::Model
-
-    define_schema do
-      property :CardNumber, String
-      property :CardType, String, enum: %w[Visa MasterCard AmericanExpress]
-      property :CardExpMonth, Integer, minimum: 1, maximum: 12
-      property :CardExpYear, Integer, minimum: Date.today.year, maximum: Date.today.year + 10
-      property :CardCVV, String, pattern: '^[0-9]{3,4}$'
-      additional_properties false
-    end
+class CreditCard
+  include EasyTalk::Model
+
+  define_schema do
+    property :CardNumber, String
+    property :CardType, String, enum: %w[Visa MasterCard AmericanExpress]
+    property :CardExpMonth, Integer, minimum: 1, maximum: 12
+    property :CardExpYear, Integer, minimum: Date.today.year, maximum: Date.today.year + 10
+    property :CardCVV, String, pattern: '^[0-9]{3,4}$'
+    additional_properties false
   end
+end
 
-  class Paypal
-    include EasyTalk::Model
+class Paypal
+  include EasyTalk::Model
 
-    define_schema do
-      property :PaypalEmail, String, format: 'email'
-      property :PaypalPasswordEncrypted, String
-      additional_properties false
-    end
+  define_schema do
+    property :PaypalEmail, String, format: 'email'
+    property :PaypalPasswordEncrypted, String
+    additional_properties false
   end
+end
 
-  class BankTransfer
-    include EasyTalk::Model
+class BankTransfer
+  include EasyTalk::Model
 
-    define_schema do
-      property :BankName, String
-      property :AccountNumber, String
-      property :RoutingNumber, String
-      property :AccountType, String, enum: %w[Checking Savings]
-      additional_properties false
-    end
+  define_schema do
+    property :BankName, String
+    property :AccountNumber, String
+    property :RoutingNumber, String
+    property :AccountType, String, enum: %w[Checking Savings]
+    additional_properties false
   end
+end
 
-  class Payment
-    include EasyTalk::Model
+class Payment
+  include EasyTalk::Model
 
-    define_schema do
-      title 'Payment'
-      description 'Payment info'
-      property :PaymentMethod, String, enum: %w[CreditCard Paypal BankTransfer]
-      property :Details, T::AnyOf[CreditCard, Paypal, BankTransfer]
-    end
+  define_schema do
+    title 'Payment'
+    description 'Payment info'
+    property :PaymentMethod, String, enum: %w[CreditCard Paypal BankTransfer]
+    property :Details, T::AnyOf[CreditCard, Paypal, BankTransfer]
   end
-
+end
 ```
 
 ## Type Checking and Schema Constraints
 
-EasyTalk uses [Sorbet](https://sorbet.org/) to perform type checking on the property constraint values. The `property` method accepts a type as the second argument. The type can be a Ruby class or a Sorbet type. For example, `String`, `Integer`, `T::Array[String]`, etc.
-
-EasyTalk raises an error if the constraint values do not match the property type. For example, if you specify the `enum` constraint with the values [1,2,3], but the property type is `String`, EasyTalk will raise a type error.
+EasyTalk uses a combination of standard Ruby types (`String`, `Integer`), Sorbet types (`T::Boolean`, `T::Array[String]`, etc.), and custom Sorbet-style types (`T::AnyOf[]`, `T::OneOf[]`) to perform basic type checking. For example:
 
-EasyTalk also raises an error if the constraints are not valid for the property type. For example, if you define a property with a `minimum` or a `maximum` constraint, but the type is `String`, EasyTalk will raise an error.
+If you specify `enum: [1,2,3]` but the property type is `String`, EasyTalk raises a type error.
+If you define `minimum: 1` on a `String` property, it raises an error because minimum applies only to numeric types.
 
 ## Schema Validation
 
-EasyTalk does not yet perform JSON validation. So far, it only aims to generate a valid JSON Schema document. You can use the `json_schema` method to generate the JSON Schema and use a JSON Schema validator library like [JSONSchemer](https://github.com/davishmcclurg/json_schemer) to validate JSON against. See https://json-schema.org/implementations#validators-ruby for a list of JSON Schema validator libraries for Ruby.
-
-The goal is to introduce JSON validation in the near future.
+You can instantiate an EasyTalk model with a hash of attributes and validate it using standard ActiveModel validations. EasyTalk does not automatically validate instances; you must explicitly define ActiveModel validations in your EasyTalk model. See [spec/easy_talk/activemodel_integration_spec.rb](ActiveModel Integration Spec) for examples.
 
 ## JSON Schema Specifications
 
-EasyTalk is currently very loose about JSON Schema specifications. It does not enforce the use of the latest JSON Schema specifications. Support for the dictionary of JSON Schema keywords varies depending on the keyword. The goal is to have robust support for the latest JSON Schema specifications in the near future.
+EasyTalk is currently loose about JSON Schema versions. It doesn’t strictly enforce or adhere to any particular version of the specification. The goal is to add more robust support for the latest JSON Schema specs in the future.
 
-To learn about the current EasyTalk capabilities, take a look at the [spec/easy_talk/examples](https://github.com/sergiobayona/easy_talk/tree/main/spec/easy_talk/examples) folder. The examples are used to test the JSON Schema generation.
+To learn about current capabilities, see the [spec/easy_talk/examples](https://github.com/sergiobayona/easy_talk/tree/main/spec/easy_talk/examples) folder. The examples illustrate how EasyTalk generates JSON Schema in different scenarios.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that lets you experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run:
+
+```bash
+bundle exec rake install
+```
 
 ## Contributing
 

data/lib/easy_talk/builders/object_builder.rb

@@ -1,15 +1,21 @@
-# frozen_string_literal: true
-
 require_relative 'base_builder'
+require 'set'
 
 module EasyTalk
   module Builders
-    # Builder class for json schema objects.
+    #
+    # ObjectBuilder is responsible for turning a SchemaDefinition of an "object" type
+    # into a validated JSON Schema hash. It:
+    #
+    # 1) Recursively processes the schema’s :properties,
+    # 2) Determines which properties are required (unless nilable or optional),
+    # 3) Handles sub-schema composition (allOf, anyOf, oneOf, not),
+    # 4) Produces the final object-level schema hash.
+    #
     class ObjectBuilder < BaseBuilder
       extend T::Sig
 
-      attr_reader :schema
-
+      # Required by BaseBuilder: recognized schema options for "object" types
       VALID_OPTIONS = {
         properties: { type: T::Hash[T.any(Symbol, String), T.untyped], key: :properties },
         additional_properties: { type: T::Boolean, key: :additionalProperties },
@@ -24,83 +30,173 @@ module EasyTalk
 
       sig { params(schema_definition: EasyTalk::SchemaDefinition).void }
       def initialize(schema_definition)
+        # Keep a reference to the original schema definition
         @schema_definition = schema_definition
-        @schema = schema_definition.schema.dup
-        @required_properties = []
-        name = schema_definition.name ? schema_definition.name.to_sym : :klass
-        super(name, { type: 'object' }, options, VALID_OPTIONS)
+        # Duplicate the raw schema hash so we can mutate it safely
+        @original_schema = schema_definition.schema.dup
+
+        # We'll collect required property names in this Set
+        @required_properties = Set.new
+
+        # Usually the name is a string (class name). Fallback to :klass if nil.
+        name_for_builder = schema_definition.name ? schema_definition.name.to_sym : :klass
+
+        # Build the base structure: { type: 'object' } plus any top-level options
+        super(
+          name_for_builder,
+          { type: 'object' },    # minimal "object" structure
+          build_options_hash,    # method below merges & cleans final top-level keys
+          VALID_OPTIONS
+        )
       end
 
       private
 
-      def properties_from_schema_definition
-        @properties_from_schema_definition ||= begin
-          properties = schema.delete(:properties) || {}
-          properties.each_with_object({}) do |(property_name, options), context|
-            add_required_property(property_name, options)
-            context[property_name] = build_property(property_name, options)
+      ##
+      # Main aggregator: merges the top-level schema keys (like :properties, :subschemas)
+      # into a single hash that we’ll feed to BaseBuilder.
+      def build_options_hash
+        # Start with a copy of the raw schema
+        merged = @original_schema.dup
+
+        # Extract and build sub-schemas first (handles allOf/anyOf/oneOf references, etc.)
+        process_subschemas(merged)
+
+        # Build :properties into a final form (and find "required" props)
+        merged[:properties] = build_properties(merged.delete(:properties))
+
+        # Populate the final "required" array from @required_properties
+        merged[:required] = @required_properties.to_a if @required_properties.any?
+
+        # Prune empty or nil values so we don't produce stuff like "properties": {} unnecessarily
+        merged.reject! { |_k, v| v.nil? || v == {} || v == [] }
+
+        merged
+      end
+
+      ##
+      # Given the property definitions hash, produce a new hash of
+      # { property_name => [Property or nested schema builder result] }.
+      #
+      def build_properties(properties_hash)
+        return {} unless properties_hash.is_a?(Hash)
+
+        # Cache with a key based on property name and its full configuration
+        @properties_cache ||= {}
+
+        properties_hash.each_with_object({}) do |(prop_name, prop_options), result|
+          cache_key = [prop_name, prop_options].hash
+
+          # Use cache if the exact property and configuration have been processed before
+          @properties_cache[cache_key] ||= begin
+            mark_required_unless_optional(prop_name, prop_options)
+            build_property(prop_name, prop_options)
           end
+
+          result[prop_name] = @properties_cache[cache_key]
         end
       end
 
-      # rubocop:disable Style/DoubleNegation
-      def add_required_property(property_name, options)
-        return if options.is_a?(Hash) && !!(options[:type].respond_to?(:nilable?) && options[:type].nilable?)
-        return if options.respond_to?(:optional?) && options.optional?
-        return if options.is_a?(Hash) && options.dig(:constraints, :optional)
+      ##
+      # Decide if a property should be required. If it's optional or nilable,
+      # we won't include it in the "required" array.
+      #
+      def mark_required_unless_optional(prop_name, prop_options)
+        return if property_optional?(prop_options)
+
+        @required_properties.add(prop_name)
+      end
+
+      ##
+      # Returns true if the property is declared optional or is T.nilable(...).
+      #
+      def property_optional?(prop_options)
+        # For convenience, treat :type as an object
+        type_obj = prop_options[:type]
+
+        # Check Sorbet's nilable (like T.nilable(String))
+        return true if type_obj.respond_to?(:nilable?) && type_obj.nilable?
+
+        # Check constraints[:optional]
+        return true if prop_options.dig(:constraints, :optional)
 
-        @required_properties << property_name
+        false
       end
-      # rubocop:enable Style/DoubleNegation
 
-      def build_property(property_name, options)
+      ##
+      # Builds a single property. Could be a nested schema if it has sub-properties,
+      # or a standard scalar property (String, Integer, etc.).
+      #
+      def build_property(prop_name, prop_options)
         @property_cache ||= {}
 
-        @property_cache[property_name] ||= if options.is_a?(EasyTalk::SchemaDefinition)
-                                             ObjectBuilder.new(options).build
-                                           else
-                                             handle_option_type(options)
-                                             Property.new(property_name, options[:type], options[:constraints])
-                                           end
+        # Memoize so we only build each property once
+        @property_cache[prop_name] ||= if prop_options[:properties]
+                                         # This indicates block-style definition => nested schema
+                                         nested_schema_builder(prop_options)
+                                       else
+                                         # Normal property: e.g. { type: String, constraints: {...} }
+                                         handle_nilable_type(prop_options)
+                                         Property.new(prop_name, prop_options[:type], prop_options[:constraints])
+                                       end
       end
 
-      def handle_option_type(options)
-        if options[:type].respond_to?(:nilable?) && options[:type].nilable? && options[:type].unwrap_nilable.class != T::Types::TypedArray
-          options[:type] = options[:type].unwrap_nilable.raw_type
-        end
+      ##
+      # Build a child schema by calling another ObjectBuilder on the nested SchemaDefinition.
+      #
+      def nested_schema_builder(prop_options)
+        child_schema_def = prop_options[:properties]
+        # If user used T.nilable(...) with a block, unwrap the nilable
+        handle_nilable_type(prop_options)
+        ObjectBuilder.new(child_schema_def).build
       end
 
-      def subschemas_from_schema_definition
-        @subschemas_from_schema_definition ||= begin
-          subschemas = schema.delete(:subschemas) || []
-          subschemas.each do |subschema|
-            add_definitions(subschema)
-            add_references(subschema)
-          end
-        end
+      ##
+      # If the type is T.nilable(SomeType), unwrap it so we produce the correct schema.
+      # This logic is borrowed from the old #handle_option_type method.
+      #
+      def handle_nilable_type(prop_options)
+        type_obj = prop_options[:type]
+        return unless type_obj.respond_to?(:nilable?) && type_obj.nilable?
+
+        # If the underlying raw_type isn't T::Types::TypedArray, then we unwrap it
+        return unless type_obj.unwrap_nilable.class != T::Types::TypedArray
+
+        prop_options[:type] = type_obj.unwrap_nilable.raw_type
       end
 
-      def add_definitions(subschema)
-        definitions = subschema.items.each_with_object({}) do |item, hash|
-          hash[item.name] = item.schema
+      ##
+      # Process top-level composition keywords (e.g. allOf, anyOf, oneOf),
+      # converting them to definitions + references if appropriate.
+      #
+      def process_subschemas(schema_hash)
+        subschemas = schema_hash.delete(:subschemas) || []
+        subschemas.each do |subschema|
+          add_defs_from_subschema(schema_hash, subschema)
+          add_refs_from_subschema(schema_hash, subschema)
         end
-        schema[:defs] = definitions
       end
 
-      def add_references(subschema)
-        references = subschema.items.map do |item|
-          { '$ref': item.ref_template }
+      ##
+      # For each item in the composer, add it to :defs so that we can reference it later.
+      #
+      def add_defs_from_subschema(schema_hash, subschema)
+        # Build up a hash of class_name => schema for each sub-item
+        definitions = subschema.items.each_with_object({}) do |item, acc|
+          acc[item.name] = item.schema
         end
-        schema[subschema.name] = references
+        # Merge or create :defs
+        existing_defs = schema_hash[:defs] || {}
+        schema_hash[:defs] = existing_defs.merge(definitions)
       end
 
-      def options
-        @options = schema
-        subschemas_from_schema_definition
-        @options[:properties] = properties_from_schema_definition
-        @options[:required] = @required_properties
-        @options.reject! { |_key, value| [nil, [], {}].include?(value) }
-        @options
+      ##
+      # Add references to the schema for each sub-item in the composer
+      # e.g. { "$ref": "#/$defs/SomeClass" }
+      #
+      def add_refs_from_subschema(schema_hash, subschema)
+        references = subschema.items.map { |item| { '$ref': item.ref_template } }
+        schema_hash[subschema.name] = references
       end
     end
   end

data/lib/easy_talk/model.rb

@@ -7,8 +7,6 @@ require 'active_support/time'
 require 'active_support/concern'
 require 'active_support/json'
 require 'active_model'
-require 'json_schemer'
-require_relative 'schema_errors_mapper'
 require_relative 'builders/object_builder'
 require_relative 'schema_definition'
 
@@ -39,30 +37,9 @@ module EasyTalk
       base.include ActiveModel::API # Include ActiveModel::API in the class including EasyTalk::Model
       base.include ActiveModel::Validations
       base.extend ActiveModel::Callbacks
-      base.validates_with SchemaValidator
       base.extend(ClassMethods)
     end
 
-    class SchemaValidator < ActiveModel::Validator
-      def validate(record)
-        result = schema_validation(record)
-        result.errors.each do |key, error_msg|
-          record.errors.add key.to_sym, error_msg
-        end
-      end
-
-      def schema_validation(record)
-        schema = JSONSchemer.schema(record.class.json_schema)
-        errors = schema.validate(record.properties)
-        SchemaErrorsMapper.new(errors)
-      end
-    end
-
-    # Returns the properties of the model as a hash with symbolized keys.
-    def properties
-      as_json.symbolize_keys!
-    end
-
     # Module containing class-level methods for defining and accessing the schema of a model.
     module ClassMethods
       # Returns the schema for the model.
@@ -72,13 +49,6 @@ module EasyTalk
         @schema ||= build_schema(schema_definition)
       end
 
-      # Returns true if the class inherits a schema.
-      #
-      # @return [Boolean] `true` if the class inherits a schema, `false` otherwise.
-      def inherits_schema?
-        false
-      end
-
       # Returns the reference template for the model.
       #
       # @return [String] The reference template for the model.
@@ -86,13 +56,6 @@ module EasyTalk
         "#/$defs/#{name}"
       end
 
-      # Returns the name of the model as a human-readable function name.
-      #
-      # @return [String] The human-readable function name of the model.
-      def function_name
-        name.humanize.titleize
-      end
-
       def properties
         @properties ||= begin
           return unless schema[:properties].present?
@@ -119,7 +82,7 @@ module EasyTalk
         @schema_definition.instance_eval(&block)
         attr_accessor(*properties)
 
-        @schema_defintion
+        @schema_definition
       end
 
       # Returns the unvalidated schema definition for the model.

data/lib/easy_talk/schema_definition.rb

@@ -3,12 +3,14 @@
 require_relative 'keywords'
 
 module EasyTalk
+  class InvalidPropertyNameError < StandardError; end
   #
   #= 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
@@ -35,18 +37,30 @@ module EasyTalk
     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)
+    def property(name, type, constraints = {}, &blk)
+      validate_property_name(name)
       @schema[:properties] ||= {}
 
       if block_given?
-        property_schema = SchemaDefinition.new(name, constraints)
+        property_schema = SchemaDefinition.new(name)
         property_schema.instance_eval(&blk)
-        @schema[:properties][name] = property_schema
+
+        @schema[:properties][name] = {
+          type:,
+          constraints:,
+          properties: property_schema
+        }
       else
         @schema[:properties][name] = { type:, constraints: }
       end
     end
 
+    def validate_property_name(name)
+      unless 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
+    end
+
     def optional?
       @schema[:optional]
     end

data/lib/easy_talk/tools/function_builder.rb

@@ -5,23 +5,35 @@ module EasyTalk
     # 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
-      # 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 self.new(model)
-        {
-          type: 'function',
-          function: {
-            name: model.function_name,
-            description: generate_description(model),
-            parameters: model.json_schema
+      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
+        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)
 
-      def self.generate_description(model)
-        "Correctly extracted `#{model.name}` with all the required parameters with correct types"
+            model.instructions
+          else
+            "Correctly extracted `#{model.name}` with all the required parameters and correct types."
+          end
+        end
       end
     end
   end

data/lib/easy_talk/version.rb

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

metadata

@@ -1,69 +1,54 @@
 --- !ruby/object:Gem::Specification
 name: easy_talk
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Sergio Bayona
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-17 00:00:00.000000000 Z
+date: 2025-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '7.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '7.0'
-- !ruby/object:Gem::Dependency
-  name: json_schemer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.5'
 - !ruby/object:Gem::Dependency
@@ -84,98 +69,98 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '13.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '13.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rspec-json_expectations
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rspec-mocks
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.13'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.21'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.21'
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.6'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.29'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.29'
 description: Generate json-schema from plain Ruby classes.
@@ -220,7 +205,6 @@ files:
 - lib/easy_talk/model.rb
 - lib/easy_talk/property.rb
 - lib/easy_talk/schema_definition.rb
-- lib/easy_talk/schema_errors_mapper.rb
 - lib/easy_talk/sorbet_extension.rb
 - lib/easy_talk/tools/function_builder.rb
 - lib/easy_talk/types/all_of.rb
@@ -236,7 +220,6 @@ metadata:
   homepage_uri: https://github.com/sergiobayona/easy_talk
   source_code_uri: https://github.com/sergiobayona/easy_talk
   changelog_uri: https://github.com/sergiobayona/easy_talk/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -251,8 +234,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Generate json-schema from Ruby classes.
 test_files: []

data/lib/easy_talk/schema_errors_mapper.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module EasyTalk
-  class SchemaErrorsMapper
-    def initialize(errors)
-      @errors = errors.to_a
-    end
-
-    def errors
-      @errors.each_with_object({}) do |error, hash|
-        if error['data_pointer'].present?
-          key = error['data_pointer'].split('/').compact_blank.join('.')
-          hash[key] = error['error']
-        else
-          error['details']['missing_keys'].each do |missing_key|
-            message = "#{error['error'].split(':').first}: #{missing_key}"
-            hash[missing_key] = message
-          end
-        end
-      end
-    end
-  end
-end