dspy-schema 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf1a5bda9480f0a5fd8e00f80949debb6bcd99e0ee014e767dc5ed7ac02440f1
+  data.tar.gz: a7c318b77fef71636125958148203960d9737897f1eed656471fbe03dd43c406
+SHA512:
+  metadata.gz: 8bf44b28876109783dc9570919f2a99f1a48a3b96823aec379f2a10b48ea84d281be226afb9a450a119a81f1721e9e37a990b5edf38b0aadc643f2cf94f49915
+  data.tar.gz: 3a34993c5c3252c63642a6892eed12e172d139dc834e53d04e7b79424e21f5f0d3ae245ef479dd6b013adec699f4d206daccf29864837db99231a853afc7f9c6

data/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2025 Vicente Services SL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This project is a Ruby port of the original Python [DSPy library](https://github.com/stanfordnlp/dspy), which is licensed under the MIT License:
+
+MIT License
+
+Copyright (c) 2023 Stanford Future Data Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,264 @@
+# DSPy.rb
+
+[![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/)
+
+> [!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.**
+
+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.
+
+**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.
+
+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.
+
+**What you get?** Ruby LLM applications that actually scale and don't break when you sneeze.
+
+Check the [examples](examples/) and take them for a spin!
+
+## Your First DSPy Program
+### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'dspy'
+```
+
+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`. |
+
+Set the matching `DSPY_WITH_*` environment variables (see `Gemfile`) to include or exclude each sibling gem when running Bundler locally.
+### Your First Reliable Predictor
+
+```ruby
+
+# Configure DSPy globablly to use your fave LLM - you can override this on an instance levle. 
+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
+end
+
+# Define a signature for sentiment classification - instead of writing a full prompt!
+class Classify < DSPy::Signature
+  description "Classify sentiment of a given sentence." # sets the goal of the underlying prompt
+
+  class Sentiment < T::Enum
+    enums do
+      Positive = new('positive')
+      Negative = new('negative')
+      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'
+  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!")
+
+puts result.sentiment    # => #<Sentiment::Positive>  
+puts result.confidence   # => 0.85
+```
+
+### Access to 200+ Models Across 5 Providers
+
+DSPy.rb provides unified access to major LLM providers with provider-specific optimizations:
+
+```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
+
+# 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
+
+# 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
+
+# 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
+
+# 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'])
+end
+```
+
+## 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.
+
+
+## Documentation
+
+📖 **[Complete Documentation Website](https://vicentereig.github.io/dspy.rb/)**
+
+### LLM-Friendly Documentation
+
+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
+
+### 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
+
+### 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
+
+### 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
+
+### 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
+
+### 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 
+
+
+
+
+
+
+
+
+## License
+This project is licensed under the MIT License.

data/lib/dspy/schema/sorbet_json_schema.rb

@@ -0,0 +1,302 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'set'
+require 'sorbet-runtime'
+
+module DSPy
+  module TypeSystem
+    # Unified module for converting Sorbet types to JSON Schema
+    # Extracted from Signature class to ensure consistency across Tools, Toolsets, and Signatures
+    module SorbetJsonSchema
+      extend T::Sig
+      extend T::Helpers
+
+      # Convert a Sorbet type to JSON Schema format
+      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
+        
+        # Handle T::Boolean type alias first
+        if type == T::Boolean
+          return { type: "boolean" }
+        end
+
+        # 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)
+        end
+
+        # Handle raw class types first
+        if type.is_a?(Class)
+          if type < T::Enum
+            # Get all enum values
+            values = type.values.map(&:serialize)
+            { type: "string", enum: values }
+          elsif type == String
+            { type: "string" }
+          elsif type == Integer
+            { type: "integer" }
+          elsif type == Float
+            { type: "number" }
+          elsif type == Numeric
+            { type: "number" }
+          elsif type == Date
+            { type: "string", format: "date" }
+          elsif type == DateTime
+            { type: "string", format: "date-time" }
+          elsif type == Time
+            { type: "string", format: "date-time" }
+          elsif [TrueClass, FalseClass].include?(type)
+            { type: "boolean" }
+          elsif type < T::Struct
+            # Handle custom T::Struct classes by generating nested object schema
+            # Check for recursion
+            if visited.include?(type)
+              # Return a reference to avoid infinite recursion
+              {
+                "$ref" => "#/definitions/#{type.name.split('::').last}",
+                description: "Recursive reference to #{type.name}"
+              }
+            else
+              self.generate_struct_schema(type, visited)
+            end
+          else
+            { type: "string" }  # Default fallback
+          end
+        elsif type.is_a?(T::Types::Simple)
+          case type.raw_type.to_s
+          when "String"
+            { type: "string" }
+          when "Integer"
+            { type: "integer" }
+          when "Float"
+            { type: "number" }
+          when "Numeric"
+            { type: "number" }
+          when "Date"
+            { type: "string", format: "date" }
+          when "DateTime"
+            { type: "string", format: "date-time" }
+          when "Time"
+            { type: "string", format: "date-time" }
+          when "TrueClass", "FalseClass"
+            { type: "boolean" }
+          when "T::Boolean"
+            { type: "boolean" }
+          else
+            # Check if it's an enum
+            if type.raw_type < T::Enum
+              # Get all enum values
+              values = type.raw_type.values.map(&:serialize)
+              { type: "string", enum: values }
+            elsif type.raw_type < T::Struct
+              # Handle custom T::Struct classes
+              if visited.include?(type.raw_type)
+                {
+                  "$ref" => "#/definitions/#{type.raw_type.name.split('::').last}",
+                  description: "Recursive reference to #{type.raw_type.name}"
+                }
+              else
+                generate_struct_schema(type.raw_type, visited)
+              end
+            else
+              { type: "string" }  # Default fallback
+            end
+          end
+        elsif type.is_a?(T::Types::TypedArray)
+          # Handle arrays properly with nested item type
+          {
+            type: "array",
+            items: self.type_to_json_schema(type.type, visited)
+          }
+        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
+          {
+            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"
+          }
+        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)
+            required << key
+          end
+          
+          {
+            type: "object",
+            properties: properties,
+            required: required,
+            additionalProperties: false
+          }
+        elsif type.class.name == "T::Private::Types::SimplePairUnion"
+          # Handle T.nilable types (T::Private::Types::SimplePairUnion)
+          # This is the actual implementation of T.nilable(SomeType)
+          has_nil = type.respond_to?(:types) && type.types.any? do |t| 
+            (t.respond_to?(:raw_type) && t.raw_type == NilClass) ||
+            (t.respond_to?(:name) && t.name == "NilClass")
+          end
+          
+          if has_nil
+            # Find the non-nil type
+            non_nil_type = type.types.find do |t|
+              !(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)
+              if base_schema[:type].is_a?(String)
+                # Convert single type to array with null
+                { type: [base_schema[:type], "null"] }.merge(base_schema.except(:type))
+              else
+                # For complex schemas, use anyOf to allow null
+                { anyOf: [base_schema, { type: "null" }] }
+              end
+            else
+              { type: "string" } # Fallback
+            end
+          else
+            # Not nilable SimplePairUnion - this is a regular T.any() union
+            # Generate oneOf schema for all types
+            if type.respond_to?(:types) && type.types.length > 1
+              {
+                oneOf: type.types.map { |t| self.type_to_json_schema(t, visited) },
+                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)
+            end
+          end
+        elsif type.is_a?(T::Types::Union)
+          # Check if this is a nilable type (contains NilClass)
+          is_nilable = type.types.any? { |t| t == T::Utils.coerce(NilClass) }
+          non_nil_types = type.types.reject { |t| t == T::Utils.coerce(NilClass) }
+          
+          # Special case: check if we have TrueClass + FalseClass (T.nilable(T::Boolean))
+          if non_nil_types.size == 2 && is_nilable
+            true_class_type = non_nil_types.find { |t| t.respond_to?(:raw_type) && t.raw_type == TrueClass }
+            false_class_type = non_nil_types.find { |t| t.respond_to?(:raw_type) && t.raw_type == FalseClass }
+            
+            if true_class_type && false_class_type
+              # This is T.nilable(T::Boolean) - treat as nilable boolean
+              return { type: ["boolean", "null"] }
+            end
+          end
+          
+          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)
+            if base_schema[:type].is_a?(String)
+              # Convert single type to array with null
+              { type: [base_schema[:type], "null"] }.merge(base_schema.except(:type))
+            else
+              # For complex schemas, use anyOf to allow null
+              { anyOf: [base_schema, { type: "null" }] }
+            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)
+          elsif non_nil_types.size > 1
+            # Handle complex unions with oneOf for better JSON schema compliance
+            base_schema = {
+              oneOf: non_nil_types.map { |t| self.type_to_json_schema(t, visited) },
+              description: "Union of multiple types"
+            }
+            if is_nilable
+              # Add null as an option for complex nilable unions
+              base_schema[:oneOf] << { type: "null" }
+            end
+            base_schema
+          else
+            { type: "string" }  # Fallback for complex unions
+          end
+        elsif type.is_a?(T::Types::ClassOf)
+          # Handle T.class_of() types
+          {
+            type: "string",
+            description: "Class name (T.class_of type)"
+          }
+        else
+          { type: "string" }  # Default fallback
+        end
+      end
+
+      # Generate JSON schema for custom T::Struct classes
+      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
+        
+        return { type: "string", description: "Struct (schema introspection not available)" } unless struct_class.respond_to?(:props)
+
+        # Add this struct to visited set to detect recursion
+        visited.add(struct_class)
+
+        properties = {}
+        required = []
+
+        # Check if struct already has a _type field
+        if struct_class.props.key?(:_type)
+          raise DSPy::ValidationError, "_type field conflict: #{struct_class.name} already has a _type field defined. " \
+                                       "DSPy uses _type for automatic type detection in union types."
+        end
+
+        # Add automatic _type field for type detection
+        properties[:_type] = {
+          type: "string",
+          const: struct_class.name.split('::').last  # Use the simple class name
+        }
+        required << "_type"
+
+        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)
+          
+          # 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
+          unless prop_info[:fully_optional]
+            required << prop_name.to_s
+          end
+        end
+
+        # Remove this struct from visited set after processing
+        visited.delete(struct_class)
+
+        {
+          type: "object",
+          properties: properties,
+          required: required,
+          description: "#{struct_class.name} struct"
+        }
+      end
+
+      private
+
+      # Extensions to Hash for Rails-like except method if not available
+      # This ensures compatibility with the original code
+      unless Hash.method_defined?(:except)
+        Hash.class_eval do
+          def except(*keys)
+            dup.tap do |hash|
+              keys.each { |key| hash.delete(key) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dspy/schema/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DSPy
+  module Schema
+    VERSION = "1.0.0"
+  end
+end

data/lib/dspy/schema.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "schema/version"
+require_relative "schema/sorbet_json_schema"

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: dspy-schema
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Vicente Reig Rincón de Arellano
+bindir: bin
+cert_chain: []
+date: 2025-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+description: Provides DSPy::TypeSystem::SorbetJsonSchema without requiring the full
+  DSPy stack, enabling reuse in sibling gems and downstream projects.
+email:
+- hey@vicente.services
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dspy/schema.rb
+- lib/dspy/schema/sorbet_json_schema.rb
+- lib/dspy/schema/version.rb
+homepage: https://github.com/vicentereig/dspy.rb
+licenses:
+- MIT
+metadata:
+  github_repo: git@github.com:vicentereig/dspy.rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.5
+specification_version: 4
+summary: Sorbet to JSON Schema conversion utilities reused by DSPy.rb.
+test_files: []