easy_talk 3.3.0 → 3.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f11b7be6e0fa32087d5be57be3d3e37d5bd5b96cc61ae8626b33d41a420e401
-  data.tar.gz: 82ba98f220e8e75e3bb3e208a595a168f188c226a130e88f13991da9a386cfc6
+  metadata.gz: f1b72ef842cb6e49f4cbc0d1eab096e737f26c118e715170c35e791ceb28a0cd
+  data.tar.gz: 800ce6db8a8d0607589250fb76a0834bc1372de11617f2746abad2c00496bc77
 SHA512:
-  metadata.gz: 90fb93ef486adb8151e883e6929437be2f52bdbe4a51bb45485006884a983b80ce9f10de1d14b313031be4b8126d6fe21c3bd54a998863543a1be1d752c124d9
-  data.tar.gz: 2ff9102ba57ae6738cb79511fdd095b5f798a760c009b10d2b5577c30575f04d94dfb11e410036e566971d92e27e2c4bc2d17336e44c64f9d35b966bbe1b4960
+  metadata.gz: 1cb143e9d16027929bcaf119cdcc12254fd4324f2f902a493be7a55095cfce1f8d721bd44c5233fb5ef62cde19aab3017f6fdc78cb66c57ab670a304293b6fb0
+  data.tar.gz: 2968e2ab36843d8237759d9b7528cbe9a72388123b677b8c8117c27192c51d50f577df884a0a96d9cc7e308f2119e2485bcbf0b13bb5742675fb5cd1338ae31a

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [3.3.1] - 2026-02-03
+
+### Added
+
+- **RubyLLM Compatibility Extension**: Seamless integration between EasyTalk models and RubyLLM's tool and structured output features (#122)
+  - New `RubyLLMCompatibility` module adds class method `to_json_schema` for `with_schema` support
+  - New `RubyLLMToolOverrides` module for classes inheriting from `RubyLLM::Tool`
+  - Overrides `description` and `params_schema` methods to use EasyTalk schema definitions
+  - Automatically included when using `EasyTalk::Model`
+  - Tools inherit from `RubyLLM::Tool` directly, gaining full access to features like `halt`, `call`, `provider_params`
+  - New example files: `examples/ruby_llm/tools_integration.rb`, `examples/ruby_llm/structured_output.rb`
+
+### Changed
+
+- **Documentation**: Updated README with improved examples and documentation
+
 ## [3.3.0] - 2026-01-12
 
 ### Added

data/README.md

@@ -52,13 +52,43 @@ EasyTalk makes the schema definition the single source of truth, so you can:
   - **RFC 7807** problem details
   - **JSON:API** error objects
 
-- **LLM tool/function schemas without a second schema layer**  
-  Use the same contract to generate JSON Schema for function/tool calling.
+- **LLM tool/function schemas without a second schema layer**
+  Use the same contract to generate JSON Schema for function/tool calling. See [RubyLLM Integration](#rubyllm-integration).
 
 EasyTalk is for teams who want their data contracts to be **correct, reusable, and boring** (the good kind of boring).
 
 ---
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Property constraints](#property-constraints)
+- [Core concepts](#core-concepts)
+  - [Required vs optional vs nullable](#required-vs-optional-vs-nullable-dont-get-tricked)
+  - [Nested models](#nested-models-and-automatic-instantiation)
+  - [Tuple arrays](#tuple-arrays-fixed-position-types)
+  - [Composition (AnyOf / OneOf / AllOf)](#composition-anyof--oneof--allof)
+- [Validations](#validations)
+  - [Automatic validations](#automatic-validations-default)
+  - [Per-model validation control](#per-model-validation-control)
+  - [Per-property validation control](#per-property-validation-control)
+  - [Validation adapters](#validation-adapters)
+- [Error formatting](#error-formatting)
+- [Schema-only mode](#schema-only-mode)
+- [RubyLLM Integration](#rubyllm-integration)
+- [Configuration highlights](#configuration-highlights)
+- [Advanced topics](#advanced-topics)
+  - [JSON Schema drafts, `$id`, and `$ref`](#json-schema-drafts-id-and-ref)
+  - [Additional properties with types](#additional-properties-with-types)
+  - [Object-level constraints](#object-level-constraints)
+  - [Custom type builders](#custom-type-builders)
+- [Known limitations](#known-limitations)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
 ## Installation
 
 ### Requirements
@@ -80,6 +110,14 @@ bundle install
 
 ## Quick start
 
+<table>
+<tr>
+<th>EasyTalk Model</th>
+<th>Generated JSON Schema</th>
+</tr>
+<tr>
+<td>
+
 ```ruby
 require "easy_talk"
 
@@ -96,14 +134,10 @@ class User
     property :age, Integer, minimum: 18
   end
 end
-
-User.json_schema   # => Ruby Hash (JSON Schema)
-user = User.new(name: "A")  # invalid: min_length is 2
-user.valid?        # => false
-user.errors        # => ActiveModel::Errors
 ```
 
-**Generated JSON Schema:**
+</td>
+<td>
 
 ```json
 {
@@ -120,6 +154,17 @@ user.errors        # => ActiveModel::Errors
 }
 ```
 
+</td>
+</tr>
+</table>
+
+```ruby
+User.json_schema   # => Ruby Hash (JSON Schema)
+user = User.new(name: "A")  # invalid: min_length is 2
+user.valid?        # => false
+user.errors        # => ActiveModel::Errors
+```
+
 ---
 
 ## Property constraints
@@ -240,6 +285,14 @@ end
 
 Use `T::Tuple` for arrays where each position has a specific type (e.g., coordinates, CSV rows, database records):
 
+<table>
+<tr>
+<th>EasyTalk Model</th>
+<th>Generated JSON Schema</th>
+</tr>
+<tr>
+<td>
+
 ```ruby
 class GeoLocation
   include EasyTalk::Model
@@ -257,7 +310,8 @@ location = GeoLocation.new(
 )
 ```
 
-**Generated JSON Schema:**
+</td>
+<td>
 
 ```json
 {
@@ -273,6 +327,10 @@ location = GeoLocation.new(
 }
 ```
 
+</td>
+</tr>
+</table>
+
 **Mixed-type tuples:**
 
 ```ruby
@@ -469,6 +527,66 @@ Use this for documentation, OpenAPI generation, or when validation happens elsew
 
 ---
 
+## RubyLLM Integration
+
+EasyTalk integrates seamlessly with [RubyLLM](https://github.com/crmne/ruby_llm) for structured outputs and tool definitions.
+
+### Structured Outputs
+
+Use any EasyTalk model with RubyLLM's `with_schema` to get structured JSON responses:
+
+```ruby
+class Recipe
+  include EasyTalk::Model
+
+  define_schema do
+    description "A cooking recipe"
+    property :name, String, description: "Name of the dish"
+    property :ingredients, T::Array[String], description: "List of ingredients"
+    property :prep_time_minutes, Integer, description: "Preparation time in minutes"
+  end
+end
+
+chat = RubyLLM.chat.with_schema(Recipe)
+response = chat.ask("Give me a simple pasta recipe")
+
+# RubyLLM returns parsed JSON - instantiate with EasyTalk model
+recipe = Recipe.new(response.content)
+recipe.name           # => "Spaghetti Aglio e Olio"
+recipe.ingredients    # => ["spaghetti", "garlic", "olive oil", ...]
+```
+
+### Tools
+
+Create LLM tools by inheriting from `RubyLLM::Tool` and including `EasyTalk::Model`:
+
+```ruby
+class Weather < RubyLLM::Tool
+  include EasyTalk::Model
+
+  define_schema do
+    description 'Gets current weather for a location'
+    property :latitude, String, description: 'Latitude (e.g., 52.5200)'
+    property :longitude, String, description: 'Longitude (e.g., 13.4050)'
+  end
+
+  def execute(latitude:, longitude:)
+    # Fetch weather data from API...
+    { temperature: 22, conditions: "sunny" }
+  end
+end
+
+chat = RubyLLM.chat.with_tool(Weather)
+response = chat.ask("What's the weather in Berlin?")
+```
+
+This pattern gives you:
+- Full access to `RubyLLM::Tool` features (`halt`, `call`, etc.)
+- EasyTalk's schema DSL for parameter definitions
+- Automatic JSON Schema generation for the LLM
+
+---
+
 ## Configuration highlights
 
 ```ruby
@@ -517,6 +635,14 @@ end
 
 Use external URIs in `$ref` for modular, reusable schemas:
 
+<table>
+<tr>
+<th>EasyTalk Model</th>
+<th>Generated JSON Schema</th>
+</tr>
+<tr>
+<td>
+
 ```ruby
 EasyTalk.configure do |config|
   config.use_refs = true
@@ -544,20 +670,34 @@ class Customer
 end
 
 Customer.json_schema
-# =>
-# {
-#   "properties": {
-#     "address": { "$ref": "https://example.com/schemas/address" }
-#   },
-#   "$defs": {
-#     "Address": {
-#       "$id": "https://example.com/schemas/address",
-#       "properties": { "street": {...}, "city": {...} }
-#     }
-#   }
-# }
 ```
 
+</td>
+<td>
+
+```json
+{
+  "properties": {
+    "address": {
+      "$ref": "https://example.com/schemas/address"
+    }
+  },
+  "$defs": {
+    "Address": {
+      "$id": "https://example.com/schemas/address",
+      "properties": {
+        "street": { "type": "string" },
+        "city": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+</td>
+</tr>
+</table>
+
 **Explicit schema IDs:**
 
 ```ruby
@@ -608,6 +748,14 @@ config.as_json
 
 **With constraints:**
 
+<table>
+<tr>
+<th>EasyTalk Model</th>
+<th>Generated JSON Schema</th>
+</tr>
+<tr>
+<td>
+
 ```ruby
 class StrictConfig
   include EasyTalk::Model
@@ -615,22 +763,34 @@ class StrictConfig
   define_schema do
     property :id, Integer
     # Integer values between 0 and 100 only
-    additional_properties Integer, minimum: 0, maximum: 100
+    additional_properties Integer,
+      minimum: 0, maximum: 100
   end
 end
 
 StrictConfig.json_schema
-# =>
-# {
-#   "properties": { "id": { "type": "integer" } },
-#   "additionalProperties": {
-#     "type": "integer",
-#     "minimum": 0,
-#     "maximum": 100
-#   }
-# }
 ```
 
+</td>
+<td>
+
+```json
+{
+  "properties": {
+    "id": { "type": "integer" }
+  },
+  "additionalProperties": {
+    "type": "integer",
+    "minimum": 0,
+    "maximum": 100
+  }
+}
+```
+
+</td>
+</tr>
+</table>
+
 **Nested models as additional properties:**
 
 ```ruby

data/examples/ruby_llm/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# EasyTalk from the parent directory
+gem 'easy_talk', path: '../..'
+
+# RubyLLM for LLM interactions
+gem 'ruby_llm'
+
+# HTTP client for API calls (used in tools example)
+gem 'faraday'

data/examples/ruby_llm/structured_output.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'ruby_llm'
+require 'easy_talk'
+
+# Example: Structured Outputs
+# Demonstrates using EasyTalk models to generate structured JSON responses.
+
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+end
+
+# 1. Define the Schema using EasyTalk
+class Recipe
+  include EasyTalk::Model
+
+  define_schema do
+    description "A simple cooking recipe"
+    property :name, String, description: "Name of the dish"
+    property :ingredients, T::Array[String], description: "List of ingredients"
+    property :prep_time_minutes, Integer, description: "Preparation time in minutes"
+    property :steps, T::Array[String], description: "Step by step cooking instructions"
+  end
+end
+
+puts "--- Structured Output Example ---"
+
+# 2. Use the EasyTalk model as the output schema
+# RubyLLM uses the schema to force the LLM to reply with a matching JSON structure.
+# Our compatibility layer ensures 'Recipe' responds to to_json_schema as RubyLLM expects.
+chat = RubyLLM.chat.with_schema(Recipe)
+
+puts "User: Give me a simple spaghetti carbonara recipe."
+response = chat.ask "Give me a simple spaghetti carbonara recipe."
+
+# 3. Access the structured data
+# RubyLLM returns parsed JSON as a Hash, so we instantiate the model with it
+recipe = Recipe.new(response.content)
+
+puts "\nGenerated Recipe:"
+puts "Name: #{recipe.name}"
+puts "Time: #{recipe.prep_time_minutes} mins"
+puts "Ingredients:"
+recipe.ingredients.each { |ing| puts "- #{ing}" }
+puts "Steps:"
+recipe.steps.each_with_index { |step, i| puts "#{i + 1}. #{step}" }

data/examples/ruby_llm/tools_integration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'ruby_llm'
+require 'easy_talk'
+require 'faraday'
+
+# Example: Tools Integration
+# Demonstrates using EasyTalk models as Tools for RubyLLM.
+#
+# To create a tool, inherit from RubyLLM::Tool and include EasyTalk::Model.
+# This gives you:
+# - Full access to RubyLLM::Tool features like halt()
+# - EasyTalk's schema DSL for defining parameters
+# - Automatic integration with RubyLLM's with_tool method
+
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+end
+
+class Weather < RubyLLM::Tool
+  include EasyTalk::Model
+
+  define_schema do
+    description 'Gets current weather for a location'
+    property :latitude, String, description: 'Latitude (e.g., 52.5200)'
+    property :longitude, String, description: 'Longitude (e.g., 13.4050)'
+  end
+
+  def execute(latitude:, longitude:)
+    puts "Executing Weather Tool for #{latitude}, #{longitude}"
+    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
+    response = Faraday.get(url)
+    data = JSON.parse(response.body)
+    data.to_s
+  rescue StandardError => e
+    { error: e.message }
+  end
+end
+
+puts '--- Tools Integration Example ---'
+puts
+
+chat = RubyLLM.chat.with_tool(Weather)
+
+puts 'User: What is the weather in Berlin (Lat: 52.52, Long: 13.405)?'
+response = chat.ask 'What is the weather in Berlin (Lat: 52.52, Long: 13.405)?'
+
+puts "Assistant: #{response.content}"

data/lib/easy_talk/extensions/ruby_llm_compatibility.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module Extensions
+    # Class methods for RubyLLM compatibility.
+    # These are added to the model class via `extend`.
+    module RubyLLMCompatibility
+      # Returns a Hash representing the schema in a format compatible with RubyLLM.
+      # RubyLLM expects an object that responds to #to_json_schema and returns
+      # a hash with :name, :description, and :schema keys.
+      #
+      # @return [Hash] The RubyLLM-compatible schema representation
+      def to_json_schema
+        {
+          name: name,
+          description: schema_definition.schema[:description] || "Schema for #{name}",
+          schema: json_schema
+        }
+      end
+    end
+
+    # Overrides for classes that inherit from RubyLLM::Tool.
+    # Only overrides schema-related methods, allowing all other RubyLLM::Tool
+    # functionality (halt, call, etc.) to work normally.
+    #
+    # Usage:
+    #   class WeatherTool < RubyLLM::Tool
+    #     include EasyTalk::Model
+    #
+    #     define_schema do
+    #       description 'Gets current weather'
+    #       property :latitude, String
+    #       property :longitude, String
+    #     end
+    #
+    #     def execute(latitude:, longitude:)
+    #       # Can use halt() since we inherit from RubyLLM::Tool
+    #       halt "Weather at #{latitude}, #{longitude}"
+    #     end
+    #   end
+    module RubyLLMToolOverrides
+      # Override to use EasyTalk's schema description.
+      #
+      # @return [String] The tool description from EasyTalk schema
+      def description
+        schema_def = self.class.schema_definition
+        schema_def.schema[:description] || "Tool: #{self.class.name}"
+      end
+
+      # Override to use EasyTalk's JSON schema for parameters.
+      #
+      # @return [Hash] The JSON schema for parameters
+      def params_schema
+        self.class.json_schema
+      end
+    end
+  end
+end

data/lib/easy_talk/model.rb

@@ -12,6 +12,7 @@ require_relative 'builders/object_builder'
 require_relative 'schema_definition'
 require_relative 'validation_builder'
 require_relative 'error_formatter'
+require_relative 'extensions/ruby_llm_compatibility'
 
 module EasyTalk
   # The `Model` module is a mixin that provides functionality for defining and accessing the schema of a model.
@@ -38,12 +39,18 @@ module EasyTalk
   module Model
     def self.included(base)
       base.extend(ClassMethods)
+      base.extend(EasyTalk::Extensions::RubyLLMCompatibility) # Add class-level methods
 
       base.include ActiveModel::API
       base.include ActiveModel::Validations
       base.extend ActiveModel::Callbacks
       base.include(InstanceMethods)
       base.include(ErrorFormatter::InstanceMethods)
+
+      # If inheriting from RubyLLM::Tool, override schema methods to use EasyTalk's schema
+      return unless defined?(RubyLLM::Tool) && base < RubyLLM::Tool
+
+      base.include(EasyTalk::Extensions::RubyLLMToolOverrides)
     end
 
     # Instance methods mixed into models that include EasyTalk::Model
@@ -150,6 +157,14 @@ module EasyTalk
         to_hash.merge(@additional_properties)
       end
 
+      # Returns a Hash representing the schema in a format compatible with RubyLLM.
+      # Delegates to the class method. Required for RubyLLM's with_schema method.
+      #
+      # @return [Hash] The RubyLLM-compatible schema representation
+      def to_json_schema
+        self.class.to_json_schema
+      end
+
       # Allow comparison with hashes
       def ==(other)
         case other

data/lib/easy_talk/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_talk
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.3.1
 platform: ruby
 authors:
 - Sergio Bayona
@@ -106,6 +106,9 @@ files:
 - docs/primitive-schema-rfc.md
 - docs/property-types.markdown
 - docs/schema-definition.markdown
+- examples/ruby_llm/Gemfile
+- examples/ruby_llm/structured_output.rb
+- examples/ruby_llm/tools_integration.rb
 - lib/easy_talk.rb
 - lib/easy_talk/builders/base_builder.rb
 - lib/easy_talk/builders/boolean_builder.rb
@@ -132,6 +135,7 @@ files:
 - lib/easy_talk/error_formatter/rfc7807.rb
 - lib/easy_talk/errors.rb
 - lib/easy_talk/errors_helper.rb
+- lib/easy_talk/extensions/ruby_llm_compatibility.rb
 - lib/easy_talk/json_schema_equality.rb
 - lib/easy_talk/keywords.rb
 - lib/easy_talk/model.rb