Structured output & json mode

.gitignore

@@ -57,3 +57,4 @@ Gemfile.lock
 # .rubocop-https?--*
 
 repomix-output.*
+CLAUDE.md

README.md

@@ -36,6 +36,7 @@ RubyLLM fixes all that. One beautiful API for everything. One consistent format.
 - 🖼️ **Image generation** with DALL-E and other providers
 - 📊 **Embeddings** for vector search and semantic analysis
 - 🔧 **Tools** that let AI use your Ruby code
+- 📝 **Structured Output** with JSON schemas
 - 🚂 **Rails integration** to persist chats and messages with ActiveRecord
 - 🌊 **Streaming** responses with proper Ruby patterns
 

docs/_data/navigation.yml

@@ -21,6 +21,8 @@
       url: /guides/image-generation
     - title: Embeddings
       url: /guides/embeddings
+    - title: Structured Output
+      url: /guides/structured-output
     - title: Error Handling
       url: /guides/error-handling
     - title: Models

docs/guides/index.md

@@ -33,6 +33,9 @@ Learn how to generate images using DALL-E and other providers.
 ### [Embeddings]({% link guides/embeddings.md %})
 Explore how to create vector embeddings for semantic search and other applications.
 
+### [Structured Output]({% link guides/structured-output.md %})
+Learn how to use JSON schemas to get validated structured data from LLMs.
+
 ### [Error Handling]({% link guides/error-handling.md %})
 Master the techniques for robust error handling in AI applications.
 

docs/guides/rails.md

@@ -25,6 +25,7 @@ After reading this guide, you will know:
 *   How to set up ActiveRecord models for persisting chats and messages.
 *   How to use `acts_as_chat` and `acts_as_message`.
 *   How chat interactions automatically persist data.
+*   How to work with structured output in your Rails models.
 *   A basic approach for integrating streaming responses with Hotwire/Turbo Streams.
 
 ## Setup
@@ -174,6 +175,93 @@ system_message = chat_record.messages.find_by(role: :system)
 puts system_message.content # => "You are a concise Ruby expert."
 ```
 
+## Working with Structured Output
+{: .d-inline-block }
+
+New (v1.3.0)
+{: .label .label-green }
+
+RubyLLM supports structured output with JSON schema validation. This works seamlessly with Rails integration, allowing you to get and persist structured data from AI models. See the [Structured Output guide]({% link guides/structured-output.md %}) for more details on schemas and compatibility.
+
+### Database Considerations
+
+For best results with structured output, use a database that supports JSON data natively:
+
+```ruby
+# For PostgreSQL, use jsonb for the content column
+class CreateMessages < ActiveRecord::Migration[7.1]
+  def change
+    create_table :messages do |t|
+      t.references :chat, null: false, foreign_key: true
+      t.string :role
+      t.jsonb :content # Use jsonb instead of text for PostgreSQL
+      # ...other fields...
+    end
+  end
+end
+```
+
+For databases without native JSON support, you can use text columns with serialization:
+
+```ruby
+# app/models/message.rb
+class Message < ApplicationRecord
+  acts_as_message
+  serialize :content, JSON # Add this for text columns
+end
+```
+
+### Using Structured Output
+
+The `with_response_format` method is available on your `Chat` model thanks to `acts_as_chat`:
+
+```ruby
+# Make sure to use a model that supports structured output
+chat_record = Chat.create!(model_id: 'gpt-4.1-nano')
+
+# Define your JSON schema
+schema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    version: { type: "string" },
+    features: { 
+      type: "array", 
+      items: { type: "string" }
+    }
+  },
+  required: ["name", "version"]
+}
+
+begin
+  # Get structured data instead of plain text
+  response = chat_record.with_response_format(schema).ask("Tell me about Ruby")
+
+  # The response content is a Hash (or serialized JSON in text columns)
+  response.content # => {"name"=>"Ruby", "version"=>"3.2.0", "features"=>["Blocks", "Procs"]}
+
+  # You can access the persisted message as usual
+  message = chat_record.messages.where(role: 'assistant').last
+  message.content['name'] # => "Ruby"
+
+  # In your views, you can easily display structured data:
+  # <%= message.content['name'] %> <%= message.content['version'] %>
+  # <ul>
+  #   <% message.content['features'].each do |feature| %>
+  #     <li><%= feature %></li>
+  #   <% end %>
+  # </ul>
+rescue RubyLLM::UnsupportedStructuredOutputError => e
+  # Handle case where the model doesn't support structured output
+  puts "This model doesn't support structured output: #{e.message}"
+rescue RubyLLM::InvalidStructuredOutput => e
+  # Handle case where the model returns invalid JSON
+  puts "The model returned invalid JSON: #{e.message}"
+end
+```
+
+With this approach, you can build robust data-driven applications that leverage the structured output capabilities of AI models while properly handling errors.
+
 ## Streaming Responses with Hotwire/Turbo
 
 You can combine `acts_as_chat` with streaming and Turbo Streams for real-time UI updates. The persistence logic works seamlessly alongside the streaming block.
@@ -264,4 +352,5 @@ Your `Chat`, `Message`, and `ToolCall` models are standard ActiveRecord models.
 *   [Using Tools]({% link guides/tools.md %})
 *   [Streaming Responses]({% link guides/streaming.md %})
 *   [Working with Models]({% link guides/models.md %})
+*   [Structured Output]({% link guides/structured-output.md %})
 *   [Error Handling]({% link guides/error-handling.md %})

docs/guides/structured-output.md

@@ -0,0 +1,201 @@
+---
+layout: default
+title: Structured Output
+parent: Guides
+nav_order: 7
+---
+
+# Structured Output
+{: .no_toc .d-inline-block }
+
+New (v1.3.0)
+{: .label .label-green }
+
+Get structured, well-formatted data from language models by providing a JSON schema. Use the `with_response_format` method to ensure the AI returns data that matches your schema instead of free-form text.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+After reading this guide, you will know:
+
+*   How to use JSON schemas to get structured data from language models
+*   How to request simple JSON responses without a specific schema
+*   How to work with models that may not officially support structured output
+*   How to handle errors related to structured output
+*   Best practices for creating effective JSON schemas
+
+## Getting Structured Data with Schemas
+
+The most powerful way to get structured data is by providing a JSON schema that defines the exact format you need:
+
+```ruby
+# Define your JSON schema
+schema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    age: { type: "integer" },
+    interests: { type: "array", items: { type: "string" } }
+  },
+  required: ["name", "age", "interests"]
+}
+
+# Request data that follows this schema
+response = RubyLLM.chat(model: "gpt-4o")
+  .with_response_format(schema)
+  .ask("Create a profile for a Ruby developer")
+
+# Access the structured data as a Hash
+puts response.content["name"]      # => "Ruby Smith"
+puts response.content["age"]       # => 32
+puts response.content["interests"] # => ["Metaprogramming", "Rails", "Testing"]
+```
+
+RubyLLM intelligently adapts based on each model's capabilities:
+
+- For models with native schema support (like GPT-4o): Uses the provider's API-level schema validation
+- For other models: Automatically adds schema instructions to the system message
+
+## Simple JSON Mode
+
+When you just need well-formed JSON without a specific structure:
+
+```ruby
+response = RubyLLM.chat(model: "gpt-4.1-nano")
+  .with_response_format(:json)
+  .ask("Create a profile for a Ruby developer")
+
+# The response will be valid JSON but with a format chosen by the model
+puts response.content.keys # => ["name", "bio", "skills", "experience", "github"]
+```
+
+This simpler approach uses OpenAI's `response_format: {type: "json_object"}` parameter, guaranteeing valid JSON output without enforcing a specific schema structure.
+
+## Working with Unsupported Models
+
+To use structured output with models that don't officially support it, set `assume_supported: true`:
+
+```ruby
+response = RubyLLM.chat(model: "gemini-2.0-flash")
+  .with_response_format(schema, assume_supported: true)
+  .ask("Create a profile for a Ruby developer")
+```
+
+This bypasses compatibility checks and inserts the schema as system instructions. Most modern models can follow these instructions to produce properly formatted JSON, even without native schema support.
+
+## Error Handling
+
+RubyLLM provides specialized error classes for structured output that help you handle different types of issues:
+
+### UnsupportedStructuredOutputError
+
+Raised when a model doesn't support the structured output format and `assume_supported` is false:
+
+```ruby
+begin
+  # Try to use structured output with a model that doesn't support it
+  response = RubyLLM.chat(model: "gemini-2.0-flash")
+    .with_response_format(schema)
+    .ask("Create a profile for a Ruby developer")
+rescue RubyLLM::UnsupportedStructuredOutputError => e
+  puts "This model doesn't support structured output: #{e.message}"
+  # Fall back to non-structured output or a different model
+end
+```
+
+### InvalidStructuredOutput
+
+Raised if the model returns a response that can't be parsed as valid JSON:
+
+```ruby
+begin
+  response = RubyLLM.chat(model: "gpt-4o")
+    .with_response_format(schema)
+    .ask("Create a profile for a Ruby developer")
+rescue RubyLLM::InvalidStructuredOutput => e
+  puts "The model returned invalid JSON: #{e.message}"
+  # Handle the error, perhaps by retrying or using a simpler schema
+end
+```
+
+Note: RubyLLM checks that responses are valid JSON but doesn't verify schema conformance (required fields, data types, etc.). For full schema validation, use a library like `json-schema`.
+
+## With ActiveRecord and Rails
+
+For Rails integration details with structured output, please see the [Rails guide](rails.md#working-with-structured-output).
+
+## Best Practices for JSON Schemas
+
+When creating schemas for structured output, follow these guidelines:
+
+1. **Keep it simple**: Start with the minimum structure needed. More complex schemas can confuse the model.
+2. **Be specific with types**: Use appropriate JSON Schema types (`string`, `number`, `boolean`, `array`, `object`) for your data.
+3. **Include descriptions**: Add a `description` field to each property to help guide the model.
+4. **Mark required fields**: Use the `required` array to indicate which properties must be included.
+5. **Provide examples**: When possible, include `examples` for complex properties.
+6. **Test thoroughly**: Different models have varying levels of schema compliance.
+
+## Example: Complex Schema
+
+Here's an example of a more complex schema for inventory data:
+
+```ruby
+schema = {
+  type: "object",
+  properties: {
+    products: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { 
+            type: "string",
+            description: "Name of the product" 
+          },
+          price: { 
+            type: "number",
+            description: "Price in dollars" 
+          },
+          in_stock: { 
+            type: "boolean",
+            description: "Whether the item is currently available" 
+          },
+          categories: {
+            type: "array",
+            items: { type: "string" },
+            description: "List of categories this product belongs to"
+          }
+        },
+        required: ["name", "price", "in_stock"]
+      }
+    },
+    total_products: { 
+      type: "integer",
+      description: "Total number of products in inventory" 
+    }
+  },
+  required: ["products", "total_products"]
+}
+
+inventory = RubyLLM.chat(model: "gpt-4o")
+  .with_response_format(schema)
+  .ask("Create an inventory for a Ruby gem store")
+```
+
+## Limitations
+
+When working with structured output, be aware of these limitations:
+
+* Schema validation is only available at the API level for certain models (primarily OpenAI models)
+* RubyLLM validates that responses are valid JSON but doesn't verify schema conformance
+* For full schema validation, use a library like `json-schema` to verify output
+* Models may occasionally deviate from the schema despite instructions
+* Complex, deeply nested schemas may reduce compliance
+
+RubyLLM handles the complexity of supporting different model capabilities, so you can focus on your application logic rather than provider-specific implementation details.

docs/index.md

@@ -58,6 +58,7 @@ RubyLLM fixes all that. One beautiful API for everything. One consistent format.
 - 🖼️ **Image generation** with DALL-E and other providers
 - 📊 **Embeddings** for vector search and semantic analysis
 - 🔧 **Tools** that let AI use your Ruby code
+- 📝 **Structured Output** with JSON schema
 - 🚂 **Rails integration** to persist chats and messages with ActiveRecord
 - 🌊 **Streaming** responses with proper Ruby patterns
 
@@ -105,6 +106,23 @@ class Weather < RubyLLM::Tool
 end
 
 chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
+
+# Get structured output with JSON schema validation
+schema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    age: { type: "integer" },
+    interests: { 
+      type: "array", 
+      items: { type: "string" }
+    }
+  },
+  required: ["name", "age", "interests"]
+}
+
+# Returns a validated Hash instead of plain text
+user_data = chat.with_response_format(schema).ask("Create a profile for a Ruby developer")
 ```
 
 ## Quick start

lib/ruby_llm/active_record/acts_as.rb

@@ -114,6 +114,17 @@ def with_temperature(temperature)
         self
       end
 
+      # Specifies the response format for the chat (JSON mode or JSON schema)
+      # @param response_format [Hash, String, Symbol] The response format, either:
+      #   - :json for simple JSON mode
+      #   - JSON schema as a Hash or JSON string for schema-based output
+      # @param assume_supported [Boolean] Whether to assume the model supports the requested format (default: false)
+      # @return [self] Chainable chat instance
+      def with_response_format(response_format, assume_supported: false)
+        to_llm.with_response_format(response_format, assume_supported: assume_supported)
+        self
+      end
+
       def on_new_message(&)
         to_llm.on_new_message(&)
         self