easy_talk 1.0.4 → 3.0.0

data/README.md

@@ -1,5 +1,8 @@
 # EasyTalk
 
+[![Gem Version](https://badge.fury.io/rb/easy_talk.svg)](https://badge.fury.io/rb/easy_talk)
+[![Ruby](https://github.com/sergiobayona/easy_talk/actions/workflows/dev-build.yml/badge.svg)](https://github.com/sergiobayona/easy_talk/actions/workflows/dev-build.yml)
+
 ## Introduction
 
 ### What is EasyTalk?
@@ -7,10 +10,12 @@ EasyTalk is a Ruby library that simplifies defining and generating JSON Schema.
 
 ### Key Features
 * **Intuitive Schema Definition**: Use Ruby classes and methods to define JSON Schema documents easily.
-* **Works for plain Ruby classes and ActiveRecord models**: Integrate with existing code or build from scratch.
+* **Automatic ActiveModel Validations**: Schema constraints automatically generate corresponding ActiveModel validations (configurable).
+* **Works for plain Ruby classes and ActiveModel classes**: Integrate with existing code or build from scratch.
 * **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.
+* **Enhanced Model Integration**: Automatic instantiation of nested EasyTalk models from hash attributes.
+* **Flexible Configuration**: Global and per-model configuration options for fine-tuned control.
 
 ### Use Cases
 - API request/response validation
@@ -26,8 +31,39 @@ Inspired by Python's Pydantic library, EasyTalk brings similar functionality to
 
 ### Requirements
 - Ruby 3.2 or higher
-- ActiveModel 7.0 or higher
-- ActiveSupport 7.0 or higher
+
+### Version 2.0.0 Breaking Changes
+
+⚠️ **IMPORTANT**: Version 2.0.0 includes breaking changes. Please review before upgrading:
+
+- **Removed**: Block-style nested object definitions (using `Hash do ... end`)
+- **Migration**: Use class references instead of inline Hash definitions
+
+```ruby
+# ❌ No longer supported (v1.x style)
+define_schema do
+  property :address, Hash do
+    property :street, String
+    property :city, String
+  end
+end
+
+# ✅ New approach (v2.x style)
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :street, String
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :address, Address  # Reference the class directly
+  end
+end
+```
 
 ### Installation Steps
 Add EasyTalk to your application's Gemfile:
@@ -109,10 +145,11 @@ Creating and validating an instance of your model:
 
 ```ruby
 user = User.new(name: "John Doe", email: "john@example.com", age: 25)
-user.valid? # => true
+user.valid? # => true (automatically validates based on schema constraints)
 
 user.age = 17
-user.valid? # => false
+user.valid? # => false (violates minimum: 18 constraint)
+user.errors[:age] # => ["must be greater than or equal to 18"]
 ```
 
 ## Core Concepts
@@ -143,7 +180,6 @@ EasyTalk supports standard Ruby types directly:
 - `Float`: Floating-point numbers
 - `Date`: Date values
 - `DateTime`: Date and time values
-- `Hash`: Object/dictionary values
 
 #### Sorbet-Style Types
 For complex types, EasyTalk uses Sorbet-style type notation:
@@ -184,25 +220,57 @@ end
 
 In this example, `name` is required but `middle_name` is optional.
 
-### Schema Validation
-EasyTalk models include ActiveModel validations. You can validate your models using the standard ActiveModel validation methods:
+### Automatic Validation Generation
+EasyTalk automatically generates ActiveModel validations from your schema constraints. This feature is enabled by default but can be configured:
+
+```ruby
+class User
+  include EasyTalk::Model
+  
+  define_schema do
+    property :name, String, min_length: 2, max_length: 50
+    property :email, String, format: "email"
+    property :age, Integer, minimum: 18, maximum: 120
+    property :status, String, enum: ["active", "inactive", "pending"]
+  end
+  # Validations are automatically generated:
+  # validates :name, presence: true, length: { minimum: 2, maximum: 50 }
+  # validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  # validates :age, presence: true, numericality: { greater_than_or_equal_to: 18, less_than_or_equal_to: 120 }
+  # validates :status, presence: true, inclusion: { in: ["active", "inactive", "pending"] }
+end
+
+user = User.new(name: "Jo", email: "invalid-email", age: 17)
+user.valid? # => false
+user.errors.full_messages 
+# => ["Name is too short (minimum is 2 characters)", 
+#     "Email is invalid", 
+#     "Age must be greater than or equal to 18"]
+```
+
+### Manual Validation Overrides
+You can still add manual validations alongside automatic ones:
 
 ```ruby
 class User
   include EasyTalk::Model
   
-  validates :name, presence: true
-  validates :age, numericality: { greater_than_or_equal_to: 18 }
+  # Custom validation in addition to automatic ones
+  validates :email, uniqueness: true
+  validate :complex_business_rule
   
   define_schema do
     property :name, String
+    property :email, String, format: "email"
     property :age, Integer, minimum: 18
   end
+  
+  private
+  
+  def complex_business_rule
+    # Custom validation logic
+  end
 end
-
-user = User.new(name: "John", age: 17)
-user.valid? # => false
-user.errors.full_messages # => ["Age must be greater than or equal to 18"]
 ```
 
 ## Defining Schemas
@@ -230,16 +298,6 @@ property :name, String, description: "The person's name", title: "Full Name"
 property :age, Integer, minimum: 0, maximum: 120, description: "The person's age"
 ```
 
-### Nested Objects
-You can define nested objects using a block:
-
-```ruby
-property :email, Hash do
-  property :address, String, format: "email"
-  property :verified, T::Boolean
-end
-```
-
 ### Arrays and Collections
 Arrays can be defined using the `T::Array` type:
 
@@ -254,22 +312,38 @@ You can also define arrays of complex types:
 property :addresses, T::Array[Address], description: "List of addresses"
 ```
 
-### Constraints and Validations
-Constraints can be added to properties and are used for schema generation:
+### Constraints and Automatic Validations
+Constraints are added to properties and are used for both schema generation and automatic validation generation:
 
 ```ruby
-property :name, String, min_length: 2, max_length: 50
-property :email, String, format: "email"
-property :category, String, enum: ["A", "B", "C"], default: "A"
+define_schema do
+  property :name, String, min_length: 2, max_length: 50
+  property :email, String, format: "email"
+  property :category, String, enum: ["A", "B", "C"]
+  property :score, Float, minimum: 0.0, maximum: 100.0
+  property :tags, T::Array[String], min_items: 1, max_items: 10
+end
+# Automatically generates equivalent ActiveModel validations:
+# validates :name, presence: true, length: { minimum: 2, maximum: 50 }
+# validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+# validates :category, presence: true, inclusion: { in: ["A", "B", "C"] }
+# validates :score, presence: true, numericality: { greater_than_or_equal_to: 0.0, less_than_or_equal_to: 100.0 }
+# validates :tags, presence: true, length: { minimum: 1, maximum: 10 }
 ```
 
-For validation, you can use ActiveModel validations:
+### Supported Constraint-to-Validation Mappings
 
-```ruby
-validates :name, presence: true, length: { minimum: 2, maximum: 50 }
-validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
-validates :category, inclusion: { in: ["A", "B", "C"] }
-```
+| Constraint | Validation Generated |
+|------------|---------------------|
+| `min_length`, `max_length` | `length: { minimum: X, maximum: Y }` |
+| `minimum`, `maximum` | `numericality: { greater_than_or_equal_to: X, less_than_or_equal_to: Y }` |
+| `format: "email"` | `format: { with: URI::MailTo::EMAIL_REGEXP }` |
+| `format: "url"` or `format: "uri"` | `format: { with: URI::regexp }` |
+| `pattern: /regex/` | `format: { with: /regex/ }` |
+| `enum: [...]` | `inclusion: { in: [...] }` |
+| `min_items`, `max_items` (arrays) | `length: { minimum: X, maximum: Y }` |
+| `optional: true` | Skips presence validation |
+| `T.nilable(Type)` | Allows nil values, skips presence validation |
 
 ### Additional Properties
 By default, EasyTalk models do not allow additional properties beyond those defined in the schema. You can change this behavior using the `additional_properties` keyword:
@@ -373,20 +447,21 @@ end
 
 ## ActiveModel Integration
 
-### Validations
-EasyTalk models include ActiveModel validations:
+### Enhanced Validation System
+EasyTalk models include comprehensive ActiveModel validation support with automatic generation:
 
 ```ruby
 class User
   include EasyTalk::Model
   
-  validates :age, comparison: { greater_than: 21 }
-  validates :height, presence: true, numericality: { greater_than: 0 }
+  # Manual validations work alongside automatic ones
+  validates :age, comparison: { greater_than: 21 }  # Additional business rule
+  validates :height, numericality: { greater_than: 0 }  # Overrides auto-validation
   
   define_schema do
-    property :name, String
-    property :age, Integer
-    property :height, Float
+    property :name, String, min_length: 2  # Auto-generates presence + length validations
+    property :age, Integer, minimum: 18   # Auto-generates presence + numericality validations
+    property :height, Float               # Auto-generates presence validation (overridden above)
   end
 end
 ```
@@ -395,10 +470,11 @@ end
 You can access validation errors using the standard ActiveModel methods:
 
 ```ruby
-user = User.new(name: "Jim", age: 18, height: -5.9)
+user = User.new(name: "J", age: 18, height: -5.9)
 user.valid? # => false
-user.errors[:age] # => ["must be greater than 21"]
-user.errors[:height] # => ["must be greater than 0"]
+user.errors[:name] # => ["is too short (minimum is 2 characters)"]
+user.errors[:age] # => ["must be greater than 21"] # Custom validation
+user.errors[:height] # => ["must be greater than 0"] # Overridden validation
 ```
 
 ### Model Attributes
@@ -411,123 +487,35 @@ user.age = 30
 puts user.name # => "John"
 ```
 
-You can also initialize a model with a hash of attributes:
+You can also initialize a model with a hash of attributes, including nested EasyTalk models:
 
 ```ruby
 user = User.new(name: "John", age: 30, height: 5.9)
-```
-
-## ActiveRecord Integration
-
-### Automatic Schema Generation
-For ActiveRecord models, EasyTalk automatically generates a schema based on the database columns:
-
-```ruby
-class Product < ActiveRecord::Base
-  include EasyTalk::Model
-end
-```
-
-This will create a schema with properties for each column in the `products` table.
 
-### Enhancing Generated Schemas
-You can enhance the auto-generated schema with the `enhance_schema` method:
-
-```ruby
-class Product < ActiveRecord::Base
-  include EasyTalk::Model
-  
-  enhance_schema({
-    title: "Retail Product",
-    description: "A product available for purchase",
-    properties: {
-      name: {
-        description: "Product display name",
-        title: "Product Name"
-      },
-      price: {
-        description: "Retail price in USD"
-      }
-    }
-  })
-end
-```
-
-### Column Exclusion Options
-EasyTalk provides several ways to exclude columns from your JSON schema:
-
-#### 1. Global Configuration
-
-```ruby
-EasyTalk.configure do |config|
-  # Exclude specific columns by name from all models
-  config.excluded_columns = [:created_at, :updated_at, :deleted_at]
-  
-  # Exclude all foreign key columns (columns ending with '_id')
-  config.exclude_foreign_keys = true   # Default: false
-  
-  # Exclude all primary key columns ('id')
-  config.exclude_primary_key = true    # Default: true
-  
-  # Exclude timestamp columns ('created_at', 'updated_at')
-  config.exclude_timestamps = true     # Default: true
-  
-  # Exclude all association properties
-  config.exclude_associations = true   # Default: false
-end
-```
-
-#### 2. Model-Specific Column Ignoring
-
-```ruby
-class Product < ActiveRecord::Base
-  include EasyTalk::Model
-  
-  enhance_schema({
-    ignore: [:internal_ref_id, :legacy_code]  # Model-specific exclusions
-  })
-end
-```
-
-### Virtual Properties
-You can add properties that don't exist as database columns:
-
-```ruby
-class Product < ActiveRecord::Base
+# NEW in v2.0.0: Automatic nested model instantiation
+class Address
   include EasyTalk::Model
-  
-  enhance_schema({
-    properties: {
-      full_details: {
-        virtual: true,
-        type: :string,
-        description: "Complete product information"
-      }
-    }
-  })
+  define_schema do
+    property :street, String
+    property :city, String
+  end
 end
-```
 
-### Associations and Foreign Keys
-By default, EasyTalk includes your model's associations in the schema:
-
-```ruby
-class Product < ActiveRecord::Base
+class User
   include EasyTalk::Model
-  belongs_to :category
-  has_many :reviews
+  define_schema do
+    property :name, String
+    property :address, Address
+  end
 end
-```
-
-This will include `category` (as an object) and `reviews` (as an array) in the schema.
-
-You can control this behavior with configuration:
 
-```ruby
-EasyTalk.configure do |config|
-  config.exclude_associations = true    # Don't include associations  
-  config.exclude_foreign_keys = true    # Don't include foreign key columns
-end
+# Hash attributes automatically instantiate nested models
+user = User.new(
+  name: "John",
+  address: { street: "123 Main St", city: "Boston" }
+)
+user.address.class # => Address (automatically instantiated)
+user.address.street # => "123 Main St"
 ```
 
 ## Advanced Features
@@ -597,79 +585,99 @@ You can configure EasyTalk globally:
 
 ```ruby
 EasyTalk.configure do |config|
-  config.excluded_columns = [:created_at, :updated_at, :deleted_at]
-  config.exclude_foreign_keys = true
-  config.exclude_primary_key = true
-  config.exclude_timestamps = true
-  config.exclude_associations = false
-  config.default_additional_properties = false
+  # Schema behavior options
+  config.default_additional_properties = false  # Control additional properties on all models
+  config.nilable_is_optional = false           # Makes T.nilable properties also optional
+  config.auto_validations = true               # Automatically generate ActiveModel validations
 end
 ```
 
-### Per-Model Configuration
-Some settings can be configured per model:
+### Automatic Validation Configuration
+The new `auto_validations` option (enabled by default) automatically generates ActiveModel validations from your schema constraints:
 
 ```ruby
-class Product < ActiveRecord::Base
+# Disable automatic validations globally
+EasyTalk.configure do |config|
+  config.auto_validations = false
+end
+
+# Now you must manually define validations
+class User
   include EasyTalk::Model
   
-  enhance_schema({
-    additionalProperties: true,
-    ignore: [:internal_ref_id, :legacy_code]
-  })
+  validates :name, presence: true, length: { minimum: 2 }
+  validates :age, presence: true, numericality: { greater_than_or_equal_to: 18 }
+  
+  define_schema do
+    property :name, String, min_length: 2
+    property :age, Integer, minimum: 18
+  end
 end
 ```
 
-### Exclusion Rules
-Columns are excluded based on the following rules (in order of precedence):
-
-1. Explicitly listed in `excluded_columns` global setting
-2. Listed in the model's `schema_enhancements[:ignore]` array
-3. Is a primary key when `exclude_primary_key` is true (default)
-4. Is a timestamp column when `exclude_timestamps` is true (default)
-5. Matches a foreign key pattern when `exclude_foreign_keys` is true
-
-### Customizing Output
-You can customize the JSON Schema output by enhancing the schema:
+### Per-Model Configuration
+You can configure additional properties for individual models:
 
 ```ruby
-class User < ActiveRecord::Base
+class User
   include EasyTalk::Model
   
-  enhance_schema({
-    title: "User Account",
-    description: "User account information",
-    properties: {
-      name: {
-        title: "Full Name",
-        description: "User's full name"
-      }
-    }
-  })
+  define_schema do
+    title "User"
+    additional_properties true  # Allow arbitrary additional properties on this model
+    property :name, String
+    property :email, String, format: "email"
+  end
 end
 ```
 
 ## Examples
 
-### User Registration
+### User Registration (with Auto-Validations)
 
 ```ruby
 class User
   include EasyTalk::Model
 
-  validates :name, :email, :password, presence: true
-  validates :password, length: { minimum: 8 }
-  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  # Additional custom validations beyond automatic ones
+  validates :email, uniqueness: true
+  validates :password, confirmation: true
 
   define_schema do
     title "User Registration"
     description "User registration information"
-    property :name, String, description: "User's full name"
+    property :name, String, min_length: 2, max_length: 100, description: "User's full name"
     property :email, String, format: "email", description: "User's email address"
-    property :password, String, min_length: 8, description: "User's password"
-    property :notify, T::Boolean, default: true, description: "Whether to send notifications"
+    property :password, String, min_length: 8, max_length: 128, description: "User's password"
+    property :notify, T::Boolean, optional: true, description: "Whether to send notifications"
   end
+  # Auto-generated validations:
+  # validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+  # validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  # validates :password, presence: true, length: { minimum: 8, maximum: 128 }
+  # validates :notify, inclusion: { in: [true, false] } - only if present (optional: true)
 end
+
+# Usage with automatic validation
+user = User.new(
+  name: "John Doe",
+  email: "john@example.com",
+  password: "secretpassword123",
+  notify: true
+)
+user.valid? # => true (assuming email is unique)
+
+# Invalid data triggers auto-generated validations
+invalid_user = User.new(
+  name: "J",                    # Too short
+  email: "invalid-email",      # Invalid format
+  password: "123"               # Too short
+)
+invalid_user.valid? # => false
+invalid_user.errors.full_messages
+# => ["Name is too short (minimum is 2 characters)",
+#     "Email is invalid",
+#     "Password is too short (minimum is 8 characters)"]
 ```
 
 ### Payment Processing
@@ -852,13 +860,16 @@ property :status, String, enum: ["active", "inactive", "pending"]
 
 ### Best Practices
 
-1. Define clear property names and descriptions
-2. Use appropriate types for each property
-3. Add validations for important business rules
-4. Keep schemas focused and modular
-5. Reuse models when appropriate
-6. Use explicit types instead of relying on inference
-7. Test your schemas with sample data
+1. **Define clear property names and descriptions** for better documentation
+2. **Use appropriate types** for each property with proper constraints
+3. **Leverage automatic validations** by defining schema constraints instead of manual validations
+4. **Keep schemas focused and modular** - extract nested objects to separate classes
+5. **Reuse models when appropriate** instead of duplicating schema definitions
+6. **Use explicit types** instead of relying on inference
+7. **Test your schemas with sample data** to ensure validations work as expected
+8. **Configure auto-validations globally** to maintain consistency across your application
+9. **Use nullable_optional_property** for fields that can be omitted or null
+10. **Document breaking changes** when updating schema definitions
 
 # Nullable vs Optional Properties in EasyTalk
 
@@ -983,14 +994,6 @@ class UserProfile
     
     # Optional and nullable (can be omitted, can be null if present)
     nullable_optional_property :bio, String
-    
-    # Nested object with mixed property types
-    property :address, Hash do
-      property :street, String # Required
-      property :city, String # Required
-      property :state, String, optional: true # Optional
-      nullable_optional_property :zip, String # Optional and nullable
-    end
   end
 end
 ```
@@ -1041,6 +1044,102 @@ We recommend updating your schema definitions to explicitly declare which proper
 | `property :p, String, optional: true` | No | No | `{ "properties": { "p": { "type": "string" } } }` |
 | `nullable_optional_property :p, String` | No | Yes | `{ "properties": { "p": { "type": ["string", "null"] } } }` |
 
+## Migration Guide from v1.x to v2.0
+
+### Breaking Changes Summary
+
+1. **Removed Block-Style Sub-Schemas**: Hash-based nested definitions are no longer supported
+2. **Enhanced Validation System**: Automatic validation generation is now enabled by default
+3. **Improved Model Initialization**: Better support for nested model instantiation
+
+### Migration Steps
+
+#### 1. Replace Hash-based Nested Schemas
+
+```ruby
+# OLD (v1.x) - No longer works
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :address, Hash do
+      property :street, String
+      property :city, String
+    end
+  end
+end
+
+# NEW (v2.x) - Extract to separate classes
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :street, String
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :address, Address
+  end
+end
+```
+
+#### 2. Review Automatic Validations
+
+With `auto_validations: true` (default), you may need to remove redundant manual validations:
+
+```ruby
+# OLD (v1.x) - Manual validations required
+class User
+  include EasyTalk::Model
+  
+  validates :name, presence: true, length: { minimum: 2 }
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  
+  define_schema do
+    property :name, String
+    property :email, String
+  end
+end
+
+# NEW (v2.x) - Automatic validations from constraints
+class User
+  include EasyTalk::Model
+  
+  # Only add validations not covered by schema constraints
+  validates :email, uniqueness: true
+  
+  define_schema do
+    property :name, String, min_length: 2     # Auto-generates presence + length
+    property :email, String, format: "email"  # Auto-generates presence + format
+  end
+end
+```
+
+#### 3. Configuration Updates
+
+Review your configuration for new options:
+
+```ruby
+EasyTalk.configure do |config|
+  # New option in v2.0
+  config.auto_validations = true  # Enable/disable automatic validation generation
+  
+  # Existing options (unchanged)
+  config.nilable_is_optional = false
+  config.default_additional_properties = false
+  # ... other existing config
+end
+```
+
+### Compatibility Notes
+
+- **Ruby Version**: Still requires Ruby 3.2+
+- **Dependencies**: Core dependencies remain the same
+- **JSON Schema Output**: No changes to generated schemas
+- **ActiveModel Integration**: Fully backward compatible
+
 ## Development and Contributing
 
 ### Setting Up the Development Environment
@@ -1059,6 +1158,13 @@ Run the test suite with:
 bundle exec rake spec
 ```
 
+### Code Quality
+Run the linter:
+
+```bash
+bundle exec rubocop
+```
+
 ### Contributing Guidelines
 Bug reports and pull requests are welcome on GitHub at https://github.com/sergiobayona/easy_talk.