dspy-schema 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf1a5bda9480f0a5fd8e00f80949debb6bcd99e0ee014e767dc5ed7ac02440f1
-  data.tar.gz: a7c318b77fef71636125958148203960d9737897f1eed656471fbe03dd43c406
+  metadata.gz: 07bb909aa6d3d5065e55d8cdd1c58f35e4b8ad8e013d209c4823bba500ebe485
+  data.tar.gz: 38ea70e51a81083e1434f07340d26a035d870f23e86addee2f5b8c0a028fb36e
 SHA512:
-  metadata.gz: 8bf44b28876109783dc9570919f2a99f1a48a3b96823aec379f2a10b48ea84d281be226afb9a450a119a81f1721e9e37a990b5edf38b0aadc643f2cf94f49915
-  data.tar.gz: 3a34993c5c3252c63642a6892eed12e172d139dc834e53d04e7b79424e21f5f0d3ae245ef479dd6b013adec699f4d206daccf29864837db99231a853afc7f9c6
+  metadata.gz: 9a9550cd63444d7eafef8ef67519bdf098b44e901bd99a320ba387df45e8897fa1aff912f0d23ab94ba3ce32d4a419bbed2e95e9968e3300ff6eee6d17071404
+  data.tar.gz: a7efc3c28890e11ceee185ba678f4c346cb4909240c67fcff5cbfbd718e0d066e5e02c3d8d70fbfa5ca4563ae4bb9c476d625c8d0ec9744fe99dd4a83c92816b

data/README.md

@@ -3,78 +3,97 @@
 [![Gem Version](https://img.shields.io/gem/v/dspy)](https://rubygems.org/gems/dspy)
 [![Total Downloads](https://img.shields.io/gem/dt/dspy)](https://rubygems.org/gems/dspy)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/vicentereig/dspy.rb/ruby.yml?branch=main&label=build)](https://github.com/vicentereig/dspy.rb/actions/workflows/ruby.yml)
-[![Documentation](https://img.shields.io/badge/docs-vicentereig.github.io%2Fdspy.rb-blue)](https://vicentereig.github.io/dspy.rb/)
+[![Documentation](https://img.shields.io/badge/docs-oss.vicente.services%2Fdspy.rb-blue)](https://oss.vicente.services/dspy.rb/)
+[![Discord](https://img.shields.io/discord/1161519468141355160?label=discord&logo=discord&logoColor=white)](https://discord.gg/zWBhrMqn)
 
-> [!NOTE]
-> The core Prompt Engineering Framework is production-ready with
-> comprehensive documentation. I am focusing now on educational content on systematic Prompt Optimization and Context Engineering.
-> Your feedback is invaluable. if you encounter issues, please open an [issue](https://github.com/vicentereig/dspy.rb/issues). If you have suggestions, open a [new thread](https://github.com/vicentereig/dspy.rb/discussions).  
-> 
-> If you want to contribute, feel free to reach out to me to coordinate efforts: hey at vicente.services
->
-> And, yes, this is 100% a legit project. :) 
+**Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
 
+DSPy.rb is the Ruby port of Stanford's [DSPy](https://dspy.ai). Instead of wrestling with brittle prompt strings, you define typed signatures and let the framework handle the rest. Prompts become functions. LLM calls become predictable.
 
-**Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
+```ruby
+require 'dspy'
 
-The Ruby framework for programming with large language models. DSPy.rb brings structured LLM programming to Ruby developers, programmatic Prompt Engineering and Context Engineering. 
-Instead of wrestling with prompt strings and parsing responses, you define typed signatures using idiomatic Ruby to compose and decompose AI Worklows and AI Agents.
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
+end
 
-**Prompts are the just Functions.** Traditional prompting is like writing code with string concatenation: it works until it doesn't. DSPy.rb brings you 
-the programming approach pioneered by [dspy.ai](https://dspy.ai/): instead of crafting fragile prompts, you define modular 
-signatures and let the framework handle the messy details.
+class Summarize < DSPy::Signature
+  description "Summarize the given text in one sentence."
 
-DSPy.rb is an idiomatic Ruby surgical port of Stanford's [DSPy framework](https://github.com/stanfordnlp/dspy). While implementing 
-the core concepts of signatures, predictors, and the main optimization algorithms from the original Python library, DSPy.rb embraces Ruby 
-conventions and adds Ruby-specific innovations like Sorbet-base Typed system, ReAct loops, and production-ready integrations like non-blocking Open Telemetry Instrumentation.
+  input do
+    const :text, String
+  end
 
-**What you get?** Ruby LLM applications that actually scale and don't break when you sneeze.
+  output do
+    const :summary, String
+  end
+end
 
-Check the [examples](examples/) and take them for a spin!
+summarizer = DSPy::Predict.new(Summarize)
+result = summarizer.call(text: "DSPy.rb brings structured LLM programming to Ruby...")
+puts result.summary
+```
 
-## Your First DSPy Program
-### Installation
+That's it. No prompt templates. No JSON parsing. No prayer-based error handling.
 
-Add to your Gemfile:
+## Installation
 
 ```ruby
+# Gemfile
 gem 'dspy'
+gem 'dspy-openai'     # For OpenAI, OpenRouter, or Ollama
+# gem 'dspy-anthropic' # For Claude
+# gem 'dspy-gemini'    # For Gemini
+# gem 'dspy-ruby_llm'  # For 12+ providers via RubyLLM
 ```
 
-and
-
 ```bash
 bundle install
 ```
 
-### Optional Sibling Gems
-
-DSPy.rb ships multiple gems from this monorepo so you only install what you need. Add these alongside `dspy`:
-
-| Gem | Description |
-| --- | --- |
-| `dspy-schema` | Exposes `DSPy::TypeSystem::SorbetJsonSchema` so other projects (e.g., exa-ruby) can convert Sorbet types to JSON Schema without pulling the full DSPy stack. |
-| `dspy-code_act` | Think-Code-Observe agents that can synthesize and execute Ruby code safely. |
-| `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. |
-| `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. |
-| `dspy-miprov2` | Bayesian optimization + Gaussian Process backend for the MIPROv2 teleprompter. |
-| `gepa` | GEPA optimizer core (Pareto engine, telemetry, reflective proposer) shared with `dspy-gepa`. |
+## Quick Start
 
-Set the matching `DSPY_WITH_*` environment variables (see `Gemfile`) to include or exclude each sibling gem when running Bundler locally.
-### Your First Reliable Predictor
+### Configure Your LLM
 
 ```ruby
-
-# Configure DSPy globablly to use your fave LLM - you can override this on an instance levle. 
+# OpenAI
 DSPy.configure do |c|
   c.lm = DSPy::LM.new('openai/gpt-4o-mini',
                       api_key: ENV['OPENAI_API_KEY'],
-                      structured_outputs: true)  # Enable OpenAI's native JSON mode
+                      structured_outputs: true)
+end
+
+# Anthropic Claude
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514',
+                      api_key: ENV['ANTHROPIC_API_KEY'])
 end
 
-# Define a signature for sentiment classification - instead of writing a full prompt!
+# Google Gemini
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
+                      api_key: ENV['GEMINI_API_KEY'])
+end
+
+# Ollama (local, free)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('ollama/llama3.2')
+end
+
+# OpenRouter (200+ models)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
+                      api_key: ENV['OPENROUTER_API_KEY'])
+end
+```
+
+### Define a Signature
+
+Signatures are typed contracts for LLM operations. Define inputs, outputs, and let DSPy handle the prompt:
+
+```ruby
 class Classify < DSPy::Signature
-  description "Classify sentiment of a given sentence." # sets the goal of the underlying prompt
+  description "Classify sentiment of a given sentence."
 
   class Sentiment < T::Enum
     enums do
@@ -83,182 +102,130 @@ class Classify < DSPy::Signature
       Neutral = new('neutral')
     end
   end
-  
-  # Structured Inputs: makes sure you are sending only valid prompt inputs to your model
+
   input do
     const :sentence, String, description: 'The sentence to analyze'
   end
 
-  # Structured Outputs: your predictor will validate the output of the model too.
   output do
-    const :sentiment, Sentiment, description: 'The sentiment of the sentence'
-    const :confidence, Float, description: 'A number between 0.0 and 1.0'
+    const :sentiment, Sentiment
+    const :confidence, Float
   end
 end
 
-# Wire it to the simplest prompting technique - a Predictn.
-classify = DSPy::Predict.new(Classify)
-# it may raise an error if you mess the inputs or your LLM messes the outputs.
-result = classify.call(sentence: "This book was super fun to read!")
+classifier = DSPy::Predict.new(Classify)
+result = classifier.call(sentence: "This book was super fun to read!")
 
-puts result.sentiment    # => #<Sentiment::Positive>  
-puts result.confidence   # => 0.85
+result.sentiment    # => #<Sentiment::Positive>
+result.confidence   # => 0.92
 ```
 
-### Access to 200+ Models Across 5 Providers
+### Chain of Thought
 
-DSPy.rb provides unified access to major LLM providers with provider-specific optimizations:
+For complex reasoning, use `ChainOfThought` to get step-by-step explanations:
 
 ```ruby
-# OpenAI (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-                      api_key: ENV['OPENAI_API_KEY'],
-                      structured_outputs: true)  # Native JSON mode
-end
+solver = DSPy::ChainOfThought.new(MathProblem)
+result = solver.call(problem: "If a train travels 120km in 2 hours, what's its speed?")
 
-# Google Gemini (Gemini 1.5 Pro, Flash, Gemini 2.0, etc.)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
-                      api_key: ENV['GEMINI_API_KEY'],
-                      structured_outputs: true)  # Native structured outputs
-end
+result.reasoning  # => "Speed = Distance / Time = 120km / 2h = 60km/h"
+result.answer     # => "60 km/h"
+```
 
-# Anthropic Claude (Claude 3.5, Claude 4, etc.)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-5-20250929',
-                      api_key: ENV['ANTHROPIC_API_KEY'],
-                      structured_outputs: true)  # Tool-based extraction (default)
-end
+### ReAct Agents
 
-# Ollama - Run any local model (Llama, Mistral, Gemma, etc.)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('ollama/llama3.2')  # Free, runs locally, no API key needed
-end
+Build agents that use tools to accomplish tasks:
 
-# OpenRouter - Access to 200+ models from multiple providers
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
-                      api_key: ENV['OPENROUTER_API_KEY'])
+```ruby
+class SearchTool < DSPy::Tools::Tool
+  tool_name "search"
+  description "Search for information"
+
+  input do
+    const :query, String
+  end
+
+  output do
+    const :results, T::Array[String]
+  end
+
+  def call(query:)
+    # Your search implementation
+    { results: ["Result 1", "Result 2"] }
+  end
 end
+
+toolset = DSPy::Tools::Toolset.new(tools: [SearchTool.new])
+agent = DSPy::ReAct.new(signature: ResearchTask, tools: toolset, max_iterations: 5)
+result = agent.call(question: "What's the latest on Ruby 3.4?")
 ```
 
-## What You Get
-
-**Developer Experience:**
-- LLM provider support using official Ruby clients:
-  - [OpenAI Ruby](https://github.com/openai/openai-ruby) with vision model support
-  - [Anthropic Ruby SDK](https://github.com/anthropics/anthropic-sdk-ruby) with multimodal capabilities
-  - [Google Gemini API](https://ai.google.dev/) with native structured outputs
-  - [Ollama](https://ollama.com/) via OpenAI compatibility layer for local models
-- **Multimodal Support** - Complete image analysis with DSPy::Image, type-safe bounding boxes, vision-capable models
-- Runtime type checking with [Sorbet](https://sorbet.org/) including T::Enum and union types
-- Type-safe tool definitions for ReAct agents
-- Comprehensive instrumentation and observability
-
-**Core Building Blocks:**
-- **Signatures** - Define input/output schemas using Sorbet types with T::Enum and union type support
-- **Predict** - LLM completion with structured data extraction and multimodal support
-- **Chain of Thought** - Step-by-step reasoning for complex problems with automatic prompt optimization
-- **ReAct** - Tool-using agents with type-safe tool definitions and error recovery
-- **Module Composition** - Combine multiple LLM calls into production-ready workflows
-
-**Optimization & Evaluation:**
-- **Prompt Objects** - Manipulate prompts as first-class objects instead of strings
-- **Typed Examples** - Type-safe training data with automatic validation
-- **Evaluation Framework** - Advanced metrics beyond simple accuracy with error-resilient pipelines
-- **MIPROv2 Optimization** - Advanced Bayesian optimization with Gaussian Processes, multiple optimization strategies, auto-config presets, and storage persistence
-
-**Production Features:**
-- **Reliable JSON Extraction** - Native structured outputs for OpenAI and Gemini, Anthropic tool-based extraction, and automatic strategy selection with fallback
-- **Type-Safe Configuration** - Strategy enums with automatic provider optimization (Strict/Compatible modes)
-- **Smart Retry Logic** - Progressive fallback with exponential backoff for handling transient failures
-- **Zero-Config Langfuse Integration** - Set env vars and get automatic OpenTelemetry traces in Langfuse
-- **Performance Caching** - Schema and capability caching for faster repeated operations
-- **File-based Storage** - Optimization result persistence with versioning
-- **Structured Logging** - JSON and key=value formats with span tracking
-
-## Recent Achievements
-
-DSPy.rb has rapidly evolved from experimental to production-ready:
-
-### Foundation
-- ✅ **JSON Parsing Reliability** - Native OpenAI structured outputs with adaptive retry logic and schema-aware fallbacks
-- ✅ **Type-Safe Strategy Configuration** - Provider-optimized strategy selection and enum-backed optimizer presets
-- ✅ **Core Module System** - Predict, ChainOfThought, ReAct with type safety (add `dspy-code_act` for Think-Code-Observe agents)
-- ✅ **Production Observability** - OpenTelemetry, New Relic, and Langfuse integration
-- ✅ **Advanced Optimization** - MIPROv2 with Bayesian optimization, Gaussian Processes, and multi-mode search
-
-### Recent Advances
-- ✅ **MIPROv2 ADE Integrity (v0.29.1)** - Stratified train/val/test splits, honest precision accounting, and enum-driven `--auto` presets with integration coverage
-- ✅ **Instruction Deduplication (v0.29.1)** - Candidate generation now filters repeated programs so optimization logs highlight unique strategies
-- ✅ **GEPA Teleprompter (v0.29.0)** - Genetic-Pareto reflective prompt evolution with merge proposer scheduling, reflective mutation, and ADE demo parity
-- ✅ **Optimizer Utilities Parity (v0.29.0)** - Bootstrap strategies, dataset summaries, and Layer 3 utilities unlock multi-predictor programs on Ruby
-- ✅ **Observability Hardening (v0.29.0)** - OTLP exporter runs on a single-thread executor preventing frozen SSL contexts without blocking spans
-- ✅ **Documentation Refresh (v0.29.x)** - New GEPA guide plus ADE optimization docs covering presets, stratified splits, and error-handling defaults
-
-**Current Focus Areas:**
-
-### Production Readiness
-- 🚧 **Production Patterns** - Real-world usage validation and performance optimization
-- 🚧 **Ruby Ecosystem Integration** - Rails integration, Sidekiq compatibility, deployment patterns
-
-### Community & Adoption
-- 🚧 **Community Examples** - Real-world applications and case studies
-- 🚧 **Contributor Experience** - Making it easier to contribute and extend
-- 🚧 **Performance Benchmarks** - Comparative analysis vs other frameworks
-
-**v1.0 Philosophy:**
-v1.0 will be released after extensive production battle-testing, not after checking off features.
-The API is already stable - v1.0 represents confidence in production reliability backed by real-world validation.
+## What's Included
+
+**Core Modules**: Predict, ChainOfThought, ReAct agents, and composable pipelines.
+
+**Type Safety**: Sorbet-based runtime validation. Enums, unions, nested structs—all work.
+
+**Multimodal**: Image analysis with `DSPy::Image` for vision-capable models.
+
+**Observability**: Zero-config Langfuse integration via OpenTelemetry. Non-blocking, production-ready.
 
+**Optimization**: MIPROv2 (Bayesian optimization) and GEPA (genetic evolution) for prompt tuning.
+
+**Provider Support**: OpenAI, Anthropic, Gemini, Ollama, and OpenRouter via official SDKs.
 
 ## Documentation
 
-📖 **[Complete Documentation Website](https://vicentereig.github.io/dspy.rb/)**
+**[Full Documentation](https://oss.vicente.services/dspy.rb/)** — Getting started, core concepts, advanced patterns.
 
-### LLM-Friendly Documentation
+**[llms.txt](https://oss.vicente.services/dspy.rb/llms.txt)** — LLM-friendly reference for AI assistants.
 
-For LLMs and AI assistants working with DSPy.rb:
-- **[llms.txt](https://vicentereig.github.io/dspy.rb/llms.txt)** - Concise reference optimized for LLMs
-- **[llms-full.txt](https://vicentereig.github.io/dspy.rb/llms-full.txt)** - Comprehensive API documentation
+### Claude Skill
 
-### Getting Started
-- **[Installation & Setup](docs/src/getting-started/installation.md)** - Detailed installation and configuration
-- **[Quick Start Guide](docs/src/getting-started/quick-start.md)** - Your first DSPy programs
-- **[Core Concepts](docs/src/getting-started/core-concepts.md)** - Understanding signatures, predictors, and modules
+A [Claude Skill](https://github.com/vicentereig/dspy-rb-skill) is available to help you build DSPy.rb applications:
 
-### Prompt Engineering
-- **[Signatures & Types](docs/src/core-concepts/signatures.md)** - Define typed interfaces for LLM operations
-- **[Predictors](docs/src/core-concepts/predictors.md)** - Predict, ChainOfThought, ReAct, and more
-- **[Modules & Pipelines](docs/src/core-concepts/modules.md)** - Compose complex multi-stage workflows
-- **[Multimodal Support](docs/src/core-concepts/multimodal.md)** - Image analysis with vision-capable models
-- **[Examples & Validation](docs/src/core-concepts/examples.md)** - Type-safe training data
-- **[Rich Types](docs/src/advanced/complex-types.md)** - Sorbet type integration with automatic coercion for structs, enums, and arrays
-- **[Composable Pipelines](docs/src/advanced/pipelines.md)** - Manual module composition patterns
+```bash
+# Claude Code
+git clone https://github.com/vicentereig/dspy-rb-skill ~/.claude/skills/dspy-rb
+```
 
-### Prompt Optimization
-- **[Evaluation Framework](docs/src/optimization/evaluation.md)** - Advanced metrics beyond simple accuracy
-- **[Prompt Optimization](docs/src/optimization/prompt-optimization.md)** - Manipulate prompts as objects
-- **[MIPROv2 Optimizer](docs/src/optimization/miprov2.md)** - Advanced Bayesian optimization with Gaussian Processes
-- **[GEPA Optimizer](docs/src/optimization/gepa.md)** *(beta)* - Reflective mutation with optional reflection LMs
+For Claude.ai Pro/Max, download the [skill ZIP](https://github.com/vicentereig/dspy-rb-skill/archive/refs/heads/main.zip) and upload via Settings > Skills.
 
-### Context Engineering
-- **[Tools](docs/src/core-concepts/toolsets.md)** - Tool wieldint agents.
-- **[Agentic Memory](docs/src/core-concepts/memory.md)** - Memory Tools & Agentic Loops
-- **[RAG Patterns](docs/src/advanced/rag.md)** - Manual RAG implementation with external services
+## Examples
 
-### Production Features
-- **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration with a dedicated export worker that never blocks your LLMs
-- **[Storage System](docs/src/production/storage.md)** - Persistence and optimization result storage
-- **[Custom Metrics](docs/src/advanced/custom-metrics.md)** - Proc-based evaluation logic 
+The [examples/](examples/) directory has runnable code for common patterns:
 
+- Sentiment classification
+- ReAct agents with tools
+- Image analysis
+- Prompt optimization
 
+```bash
+bundle exec ruby examples/first_predictor.rb
+```
 
+## Optional Gems
 
+DSPy.rb ships sibling gems for features with heavier dependencies. Add them as needed:
 
+| Gem | What it does |
+| --- | --- |
+| `dspy-datasets` | Dataset helpers, Parquet/Polars tooling |
+| `dspy-evals` | Evaluation harness with metrics and callbacks |
+| `dspy-miprov2` | Bayesian optimization for prompt tuning |
+| `dspy-gepa` | Genetic-Pareto prompt evolution |
+| `dspy-o11y-langfuse` | Auto-configure Langfuse tracing |
+| `dspy-code_act` | Think-Code-Observe agents |
+| `dspy-deep_search` | Production DeepSearch with Exa |
+
+See [the full list](https://oss.vicente.services/dspy.rb/getting-started/installation/) in the docs.
 
+## Contributing
 
+Feedback is invaluable. If you encounter issues, [open an issue](https://github.com/vicentereig/dspy.rb/issues). For suggestions, [start a discussion](https://github.com/vicentereig/dspy.rb/discussions).
+
+Want to contribute code? Reach out: hey at vicente.services
 
 ## License
-This project is licensed under the MIT License.
+
+MIT License.

data/lib/dspy/schema/sorbet_json_schema.rb

@@ -12,10 +12,33 @@ module DSPy
       extend T::Sig
       extend T::Helpers
 
+      # Result type that includes both schema and any accumulated definitions
+      class SchemaResult < T::Struct
+        const :schema, T::Hash[Symbol, T.untyped]
+        const :definitions, T::Hash[String, T::Hash[Symbol, T.untyped]], default: {}
+      end
+
+      # Convert a Sorbet type to JSON Schema format with definitions tracking
+      # Returns a SchemaResult with the schema and any $defs needed
+      sig { params(type: T.untyped, visited: T.nilable(T::Set[T.untyped]), definitions: T.nilable(T::Hash[String, T::Hash[Symbol, T.untyped]])).returns(SchemaResult) }
+      def self.type_to_json_schema_with_defs(type, visited = nil, definitions = nil)
+        visited ||= Set.new
+        definitions ||= {}
+        schema = type_to_json_schema_internal(type, visited, definitions)
+        SchemaResult.new(schema: schema, definitions: definitions)
+      end
+
       # Convert a Sorbet type to JSON Schema format
+      # For backward compatibility, this method returns just the schema hash
       sig { params(type: T.untyped, visited: T.nilable(T::Set[T.untyped])).returns(T::Hash[Symbol, T.untyped]) }
       def self.type_to_json_schema(type, visited = nil)
         visited ||= Set.new
+        type_to_json_schema_internal(type, visited, {})
+      end
+
+      # Internal implementation that tracks definitions
+      sig { params(type: T.untyped, visited: T::Set[T.untyped], definitions: T::Hash[String, T::Hash[Symbol, T.untyped]]).returns(T::Hash[Symbol, T.untyped]) }
+      def self.type_to_json_schema_internal(type, visited, definitions)
         
         # Handle T::Boolean type alias first
         if type == T::Boolean
@@ -24,7 +47,7 @@ module DSPy
 
         # Handle type aliases by resolving to their underlying type
         if type.is_a?(T::Private::Types::TypeAlias)
-          return self.type_to_json_schema(type.aliased_type, visited)
+          return type_to_json_schema_internal(type.aliased_type, visited, definitions)
         end
 
         # Handle raw class types first
@@ -54,12 +77,13 @@ module DSPy
             # Check for recursion
             if visited.include?(type)
               # Return a reference to avoid infinite recursion
+              # Use #/$defs/ format for OpenAI/Gemini compatibility
+              simple_name = type.name.split('::').last
               {
-                "$ref" => "#/definitions/#{type.name.split('::').last}",
-                description: "Recursive reference to #{type.name}"
+                "$ref" => "#/$defs/#{simple_name}"
               }
             else
-              self.generate_struct_schema(type, visited)
+              generate_struct_schema_internal(type, visited, definitions)
             end
           else
             { type: "string" }  # Default fallback
@@ -93,12 +117,13 @@ module DSPy
             elsif type.raw_type < T::Struct
               # Handle custom T::Struct classes
               if visited.include?(type.raw_type)
+                # Use #/$defs/ format for OpenAI/Gemini compatibility
+                simple_name = type.raw_type.name.split('::').last
                 {
-                  "$ref" => "#/definitions/#{type.raw_type.name.split('::').last}",
-                  description: "Recursive reference to #{type.raw_type.name}"
+                  "$ref" => "#/$defs/#{simple_name}"
                 }
               else
-                generate_struct_schema(type.raw_type, visited)
+                generate_struct_schema_internal(type.raw_type, visited, definitions)
               end
             else
               { type: "string" }  # Default fallback
@@ -108,29 +133,30 @@ module DSPy
           # Handle arrays properly with nested item type
           {
             type: "array",
-            items: self.type_to_json_schema(type.type, visited)
+            items: type_to_json_schema_internal(type.type, visited, definitions)
           }
         elsif type.is_a?(T::Types::TypedHash)
           # Handle hashes as objects with additionalProperties
           # TypedHash has keys and values methods to access its key and value types
-          key_schema = self.type_to_json_schema(type.keys, visited)
-          value_schema = self.type_to_json_schema(type.values, visited)
-          
-          # Create a more descriptive schema for nested structures
+          # Note: propertyNames is NOT supported by OpenAI structured outputs, so we omit it
+          value_schema = type_to_json_schema_internal(type.values, visited, definitions)
+          key_type_desc = type.keys.respond_to?(:raw_type) ? type.keys.raw_type.to_s : "string"
+          value_type_desc = value_schema[:description] || value_schema[:type].to_s
+
+          # Create a schema compatible with OpenAI structured outputs
           {
             type: "object",
-            propertyNames: key_schema,  # Describe key constraints
             additionalProperties: value_schema,
-            # Add a more explicit description of the expected structure
-            description: "A mapping where keys are #{key_schema[:type]}s and values are #{value_schema[:description] || value_schema[:type]}s"
+            # Description explains the expected structure without using propertyNames
+            description: "A mapping where keys are #{key_type_desc}s and values are #{value_type_desc}s"
           }
         elsif type.is_a?(T::Types::FixedHash)
           # Handle fixed hashes (from type aliases like { "key" => Type })
           properties = {}
           required = []
-          
+
           type.types.each do |key, value_type|
-            properties[key] = self.type_to_json_schema(value_type, visited)
+            properties[key] = type_to_json_schema_internal(value_type, visited, definitions)
             required << key
           end
           
@@ -154,9 +180,9 @@ module DSPy
               !(t.respond_to?(:raw_type) && t.raw_type == NilClass) &&
               !(t.respond_to?(:name) && t.name == "NilClass")
             end
-            
+
             if non_nil_type
-              base_schema = self.type_to_json_schema(non_nil_type, visited)
+              base_schema = type_to_json_schema_internal(non_nil_type, visited, definitions)
               if base_schema[:type].is_a?(String)
                 # Convert single type to array with null
                 { type: [base_schema[:type], "null"] }.merge(base_schema.except(:type))
@@ -169,16 +195,16 @@ module DSPy
             end
           else
             # Not nilable SimplePairUnion - this is a regular T.any() union
-            # Generate oneOf schema for all types
+            # Generate anyOf schema for all types (oneOf not supported by Anthropic strict mode)
             if type.respond_to?(:types) && type.types.length > 1
               {
-                oneOf: type.types.map { |t| self.type_to_json_schema(t, visited) },
+                anyOf: type.types.map { |t| type_to_json_schema_internal(t, visited, definitions) },
                 description: "Union of multiple types"
               }
             else
               # Single type or fallback
               first_type = type.respond_to?(:types) ? type.types.first : type
-              self.type_to_json_schema(first_type, visited)
+              type_to_json_schema_internal(first_type, visited, definitions)
             end
           end
         elsif type.is_a?(T::Types::Union)
@@ -199,7 +225,7 @@ module DSPy
           
           if non_nil_types.size == 1 && is_nilable
             # This is T.nilable(SomeType) - generate proper schema with null allowed
-            base_schema = self.type_to_json_schema(non_nil_types.first, visited)
+            base_schema = type_to_json_schema_internal(non_nil_types.first, visited, definitions)
             if base_schema[:type].is_a?(String)
               # Convert single type to array with null
               { type: [base_schema[:type], "null"] }.merge(base_schema.except(:type))
@@ -209,16 +235,16 @@ module DSPy
             end
           elsif non_nil_types.size == 1
             # Non-nilable single type union (shouldn't happen in practice)
-            self.type_to_json_schema(non_nil_types.first, visited)
+            type_to_json_schema_internal(non_nil_types.first, visited, definitions)
           elsif non_nil_types.size > 1
-            # Handle complex unions with oneOf for better JSON schema compliance
+            # Handle complex unions with anyOf (oneOf not supported by Anthropic strict mode)
             base_schema = {
-              oneOf: non_nil_types.map { |t| self.type_to_json_schema(t, visited) },
+              anyOf: non_nil_types.map { |t| type_to_json_schema_internal(t, visited, definitions) },
               description: "Union of multiple types"
             }
             if is_nilable
               # Add null as an option for complex nilable unions
-              base_schema[:oneOf] << { type: "null" }
+              base_schema[:anyOf] << { type: "null" }
             end
             base_schema
           else
@@ -236,12 +262,31 @@ module DSPy
       end
 
       # Generate JSON schema for custom T::Struct classes
+      # For backward compatibility, this returns just the schema hash
       sig { params(struct_class: T.class_of(T::Struct), visited: T.nilable(T::Set[T.untyped])).returns(T::Hash[Symbol, T.untyped]) }
       def self.generate_struct_schema(struct_class, visited = nil)
         visited ||= Set.new
-        
+        generate_struct_schema_internal(struct_class, visited, {})
+      end
+
+      # Generate JSON schema with $defs tracking
+      # Returns a SchemaResult with schema and accumulated definitions
+      sig { params(struct_class: T.class_of(T::Struct), visited: T.nilable(T::Set[T.untyped]), definitions: T.nilable(T::Hash[String, T::Hash[Symbol, T.untyped]])).returns(SchemaResult) }
+      def self.generate_struct_schema_with_defs(struct_class, visited = nil, definitions = nil)
+        visited ||= Set.new
+        definitions ||= {}
+        schema = generate_struct_schema_internal(struct_class, visited, definitions)
+        SchemaResult.new(schema: schema, definitions: definitions)
+      end
+
+      # Internal implementation that tracks definitions for $defs
+      sig { params(struct_class: T.class_of(T::Struct), visited: T::Set[T.untyped], definitions: T::Hash[String, T::Hash[Symbol, T.untyped]]).returns(T::Hash[Symbol, T.untyped]) }
+      def self.generate_struct_schema_internal(struct_class, visited, definitions)
         return { type: "string", description: "Struct (schema introspection not available)" } unless struct_class.respond_to?(:props)
 
+        struct_name = struct_class.name || "Struct#{format('%x', struct_class.object_id)}"
+        simple_name = struct_name.split('::').last || struct_name
+
         # Add this struct to visited set to detect recursion
         visited.add(struct_class)
 
@@ -257,14 +302,24 @@ module DSPy
         # Add automatic _type field for type detection
         properties[:_type] = {
           type: "string",
-          const: struct_class.name.split('::').last  # Use the simple class name
+          const: simple_name  # Use the simple class name
         }
         required << "_type"
 
+        # Get field descriptions if the struct supports them (via DSPy::Ext::StructDescriptions)
+        field_descs = struct_class.respond_to?(:field_descriptions) ? struct_class.field_descriptions : {}
+
         struct_class.props.each do |prop_name, prop_info|
           prop_type = prop_info[:type_object] || prop_info[:type]
-          properties[prop_name] = self.type_to_json_schema(prop_type, visited)
-          
+          prop_schema = type_to_json_schema_internal(prop_type, visited, definitions)
+
+          # Add field description if available
+          if field_descs[prop_name]
+            prop_schema[:description] = field_descs[prop_name]
+          end
+
+          properties[prop_name] = prop_schema
+
           # A field is required if it's not fully optional
           # fully_optional is true for nilable prop fields
           # immutable const fields are required unless nilable
@@ -276,12 +331,19 @@ module DSPy
         # Remove this struct from visited set after processing
         visited.delete(struct_class)
 
-        {
+        schema = {
           type: "object",
           properties: properties,
           required: required,
-          description: "#{struct_class.name} struct"
+          description: "#{struct_name} struct",
+          additionalProperties: false
         }
+
+        # Add this struct's schema to definitions for $defs
+        # This allows recursive references to be resolved
+        definitions[simple_name] = schema
+
+        schema
       end
 
       private

data/lib/dspy/schema/sorbet_toon_adapter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'sorbet/toon'
+
+require_relative '../lm/errors'
+
+module DSPy
+  module Schema
+    module SorbetToonAdapter
+      extend T::Sig
+
+      module_function
+
+      sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), values: T::Hash[Symbol, T.untyped]).returns(String) }
+      def render_input(signature_class, values)
+        Sorbet::Toon.encode(
+          values,
+          signature: signature_class,
+          role: :input
+        )
+      end
+
+      sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), values: T::Hash[Symbol, T.untyped]).returns(String) }
+      def render_expected_output(signature_class, values)
+        Sorbet::Toon.encode(
+          values,
+          signature: signature_class,
+          role: :output
+        )
+      end
+
+      sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), toon_string: String).returns(T.untyped) }
+      def parse_output(signature_class, toon_string)
+        payload = strip_code_fences(toon_string)
+
+        Sorbet::Toon.decode(
+          payload,
+          signature: signature_class,
+          role: :output,
+          strict: false
+        )
+      rescue Sorbet::Toon::DecodeError => e
+        log_decode_error(payload, e)
+        raise DSPy::LM::AdapterError,
+              "Failed to parse TOON response: #{e.message}. Ensure the model replies with a ```toon``` block using the schema described in the system prompt."
+      end
+
+      sig { params(text: T.nilable(String)).returns(String) }
+      def strip_code_fences(text)
+        return '' if text.nil?
+
+        match = text.match(/```(?:toon)?\s*(.*?)```/m)
+        return match[1].strip if match
+
+        text.strip
+      end
+
+      sig { params(payload: String, error: StandardError).void }
+      def log_decode_error(payload, error)
+        logger = DSPy.logger if DSPy.respond_to?(:logger)
+        return unless logger.respond_to?(:warn)
+
+        preview = payload.to_s.lines.first(5).join
+        logger.warn(
+          event: 'toon.decode_error',
+          error: error.message,
+          preview: preview,
+          length: payload.to_s.length
+        )
+      end
+
+      sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), role: Symbol).returns(String) }
+      def field_guidance(signature_class, role)
+        return '' unless signature_class
+
+        Sorbet::Toon::SignatureFormatter.describe_signature(signature_class, role)
+      end
+    end
+  end
+end

data/lib/dspy/schema/version.rb

@@ -2,6 +2,6 @@
 
 module DSPy
   module Schema
-    VERSION = "1.0.0"
+    VERSION = "1.0.2"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy-schema
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 bindir: bin
 cert_chain: []
-date: 2025-10-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -35,6 +35,7 @@ files:
 - README.md
 - lib/dspy/schema.rb
 - lib/dspy/schema/sorbet_json_schema.rb
+- lib/dspy/schema/sorbet_toon_adapter.rb
 - lib/dspy/schema/version.rb
 homepage: https://github.com/vicentereig/dspy.rb
 licenses:
@@ -55,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Sorbet to JSON Schema conversion utilities reused by DSPy.rb.
 test_files: []