dspy-schema 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 9f74029ea6216c0037bb06ceb6c7f59d97fb91b1eefa19eb1c7d44322b555394
4
- data.tar.gz: '08d2fe0cd462d3dc454184a3996c015e8182244c1ad8731780f18e58fbdbe03d'
3
+ metadata.gz: 07bb909aa6d3d5065e55d8cdd1c58f35e4b8ad8e013d209c4823bba500ebe485
4
+ data.tar.gz: 38ea70e51a81083e1434f07340d26a035d870f23e86addee2f5b8c0a028fb36e
5
5
  SHA512:
6
- metadata.gz: ebf9688e45cdc399cd5be6fc72a6b923c8e4bc261d33b0e94fef6e77bd556af4cae3ade15698303088d023ea9207a8317de27e69a7c8803dd10aa1d9c56d797a
7
- data.tar.gz: 746aaa4652c116c960f1be9bde5b6f9696c041ac3ac88622d1dcf23db4196b60ebd2686fdc58aebd8b62203ee6ce1cbe3a86946b31a22bf7252d8aac275481e4
6
+ metadata.gz: 9a9550cd63444d7eafef8ef67519bdf098b44e901bd99a320ba387df45e8897fa1aff912f0d23ab94ba3ce32d4a419bbed2e95e9968e3300ff6eee6d17071404
7
+ data.tar.gz: a7efc3c28890e11ceee185ba678f4c346cb4909240c67fcff5cbfbd718e0d066e5e02c3d8d70fbfa5ca4563ae4bb9c476d625c8d0ec9744fe99dd4a83c92816b
data/README.md CHANGED
@@ -3,61 +3,97 @@
3
3
  [![Gem Version](https://img.shields.io/gem/v/dspy)](https://rubygems.org/gems/dspy)
4
4
  [![Total Downloads](https://img.shields.io/gem/dt/dspy)](https://rubygems.org/gems/dspy)
5
5
  [![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)
6
- [![Documentation](https://img.shields.io/badge/docs-vicentereig.github.io%2Fdspy.rb-blue)](https://vicentereig.github.io/dspy.rb/)
6
+ [![Documentation](https://img.shields.io/badge/docs-oss.vicente.services%2Fdspy.rb-blue)](https://oss.vicente.services/dspy.rb/)
7
7
  [![Discord](https://img.shields.io/discord/1161519468141355160?label=discord&logo=discord&logoColor=white)](https://discord.gg/zWBhrMqn)
8
8
 
9
- > [!NOTE]
10
- > The core Prompt Engineering Framework is production-ready with
11
- > comprehensive documentation. I am focusing now on educational content on systematic Prompt Optimization and Context Engineering.
12
- > 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).
13
- >
14
- > If you want to contribute, feel free to reach out to me to coordinate efforts: hey at vicente.services
15
- >
16
- > And, yes, this is 100% a legit project. :)
9
+ **Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
17
10
 
11
+ 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.
18
12
 
19
- **Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
13
+ ```ruby
14
+ require 'dspy'
20
15
 
21
- DSPy.rb is the Ruby-first surgical port of Stanford's [DSPy framework](https://github.com/stanfordnlp/dspy). It delivers structured LLM programming, prompt engineering, and context engineering in the language we love. Instead of wrestling with brittle prompt strings, you define typed signatures in idiomatic Ruby and compose workflows and agents that actually behave.
16
+ DSPy.configure do |c|
17
+ c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
18
+ end
22
19
 
23
- **Prompts are 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/): define modular signatures and let the framework deal with the messy bits.
20
+ class Summarize < DSPy::Signature
21
+ description "Summarize the given text in one sentence."
24
22
 
25
- While we implement the same signatures, predictors, and optimization algorithms as the original library, DSPy.rb leans hard into Ruby conventions with Sorbet-based typing, ReAct loops, and production-ready integrations like non-blocking OpenTelemetry instrumentation.
23
+ input do
24
+ const :text, String
25
+ end
26
26
 
27
- **What you get?** Ruby LLM applications that scale and don't break when you sneeze.
27
+ output do
28
+ const :summary, String
29
+ end
30
+ end
28
31
 
29
- Check the [examples](examples/) and take them for a spin!
32
+ summarizer = DSPy::Predict.new(Summarize)
33
+ result = summarizer.call(text: "DSPy.rb brings structured LLM programming to Ruby...")
34
+ puts result.summary
35
+ ```
30
36
 
31
- ## Your First DSPy Program
32
- ### Installation
37
+ That's it. No prompt templates. No JSON parsing. No prayer-based error handling.
33
38
 
34
- Add to your Gemfile:
39
+ ## Installation
35
40
 
36
41
  ```ruby
42
+ # Gemfile
37
43
  gem 'dspy'
44
+ gem 'dspy-openai' # For OpenAI, OpenRouter, or Ollama
45
+ # gem 'dspy-anthropic' # For Claude
46
+ # gem 'dspy-gemini' # For Gemini
47
+ # gem 'dspy-ruby_llm' # For 12+ providers via RubyLLM
38
48
  ```
39
49
 
40
- and
41
-
42
50
  ```bash
43
51
  bundle install
44
52
  ```
45
53
 
46
- ### Your First Reliable Predictor
54
+ ## Quick Start
47
55
 
48
- ```ruby
49
- require 'dspy'
56
+ ### Configure Your LLM
50
57
 
51
- # Configure DSPy globally to use your fave LLM (you can override per predictor).
58
+ ```ruby
59
+ # OpenAI
52
60
  DSPy.configure do |c|
53
61
  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
54
62
  api_key: ENV['OPENAI_API_KEY'],
55
- structured_outputs: true) # Enable OpenAI's native JSON mode
63
+ structured_outputs: true)
64
+ end
65
+
66
+ # Anthropic Claude
67
+ DSPy.configure do |c|
68
+ c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514',
69
+ api_key: ENV['ANTHROPIC_API_KEY'])
56
70
  end
57
71
 
58
- # Define a signature for sentiment classification - instead of writing a full prompt!
72
+ # Google Gemini
73
+ DSPy.configure do |c|
74
+ c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
75
+ api_key: ENV['GEMINI_API_KEY'])
76
+ end
77
+
78
+ # Ollama (local, free)
79
+ DSPy.configure do |c|
80
+ c.lm = DSPy::LM.new('ollama/llama3.2')
81
+ end
82
+
83
+ # OpenRouter (200+ models)
84
+ DSPy.configure do |c|
85
+ c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
86
+ api_key: ENV['OPENROUTER_API_KEY'])
87
+ end
88
+ ```
89
+
90
+ ### Define a Signature
91
+
92
+ Signatures are typed contracts for LLM operations. Define inputs, outputs, and let DSPy handle the prompt:
93
+
94
+ ```ruby
59
95
  class Classify < DSPy::Signature
60
- description "Classify sentiment of a given sentence." # sets the goal of the underlying prompt
96
+ description "Classify sentiment of a given sentence."
61
97
 
62
98
  class Sentiment < T::Enum
63
99
  enums do
@@ -66,227 +102,130 @@ class Classify < DSPy::Signature
66
102
  Neutral = new('neutral')
67
103
  end
68
104
  end
69
-
70
- # Structured Inputs: makes sure you are sending only valid prompt inputs to your model
105
+
71
106
  input do
72
107
  const :sentence, String, description: 'The sentence to analyze'
73
108
  end
74
109
 
75
- # Structured Outputs: your predictor will validate the output of the model too.
76
110
  output do
77
- const :sentiment, Sentiment, description: 'The sentiment of the sentence'
78
- const :confidence, Float, description: 'A number between 0.0 and 1.0'
111
+ const :sentiment, Sentiment
112
+ const :confidence, Float
79
113
  end
80
114
  end
81
115
 
82
- # Wire it to the simplest prompting technique: a prediction loop.
83
- classify = DSPy::Predict.new(Classify)
84
- # it may raise an error if you mess the inputs or your LLM messes the outputs.
85
- result = classify.call(sentence: "This book was super fun to read!")
116
+ classifier = DSPy::Predict.new(Classify)
117
+ result = classifier.call(sentence: "This book was super fun to read!")
86
118
 
87
- puts result.sentiment # => #<Sentiment::Positive>
88
- puts result.confidence # => 0.85
119
+ result.sentiment # => #<Sentiment::Positive>
120
+ result.confidence # => 0.92
89
121
  ```
90
122
 
91
- Save this as `examples/first_predictor.rb` and run it with:
92
-
93
- ```bash
94
- bundle exec ruby examples/first_predictor.rb
95
- ```
123
+ ### Chain of Thought
96
124
 
97
- ### Sibling Gems
125
+ For complex reasoning, use `ChainOfThought` to get step-by-step explanations:
98
126
 
99
- DSPy.rb ships multiple gems from this monorepo so you can opt into features with heavier dependency trees (e.g., datasets pull in Polars/Arrow, MIPROv2 requires `numo-*` BLAS bindings) only when you need them. Add these alongside `dspy`:
127
+ ```ruby
128
+ solver = DSPy::ChainOfThought.new(MathProblem)
129
+ result = solver.call(problem: "If a train travels 120km in 2 hours, what's its speed?")
100
130
 
101
- | Gem | Description | Status |
102
- | --- | --- | --- |
103
- | `dspy-schema` | Exposes `DSPy::TypeSystem::SorbetJsonSchema` for downstream reuse. (Still required by the core `dspy` gem; extraction lets other projects depend on it directly.) | **Stable** (v1.0.0) |
104
- | `dspy-code_act` | Think-Code-Observe agents that synthesize and execute Ruby safely. (Add the gem or set `DSPY_WITH_CODE_ACT=1` before requiring `dspy/code_act`.) | **Stable** (v1.0.0) |
105
- | `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. (Toggle via `DSPY_WITH_DATASETS`.) | **Stable** (v1.0.0) |
106
- | `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. (Toggle via `DSPY_WITH_EVALS`.) | **Stable** (v1.0.0) |
107
- | `dspy-miprov2` | Bayesian optimization + Gaussian Process backend for the MIPROv2 teleprompter. (Install or export `DSPY_WITH_MIPROV2=1` before requiring the teleprompter.) | **Stable** (v1.0.0) |
108
- | `dspy-gepa` | `DSPy::Teleprompt::GEPA`, reflection loops, experiment tracking, telemetry adapters. (Install or set `DSPY_WITH_GEPA=1`.) | **Stable** (v1.0.0) |
109
- | `gepa` | GEPA optimizer core (Pareto engine, telemetry, reflective proposer). | **Stable** (v1.0.0) |
110
- | `dspy-o11y` | Core observability APIs: `DSPy::Observability`, async span processor, observation types. (Install or set `DSPY_WITH_O11Y=1`.) | **Stable** (v1.0.0) |
111
- | `dspy-o11y-langfuse` | Auto-configures DSPy observability to stream spans to Langfuse via OTLP. (Install or set `DSPY_WITH_O11Y_LANGFUSE=1`.) | **Stable** (v1.0.0) |
112
- | `dspy-deep_search` | Production DeepSearch loop with Exa-backed search/read, token budgeting, and instrumentation (Issue #163). | **Stable** (v1.0.0) |
113
- | `dspy-deep_research` | Planner/QA orchestration atop DeepSearch plus the memory supervisor used by the CLI example. | **Stable** (v1.0.0) |
131
+ result.reasoning # => "Speed = Distance / Time = 120km / 2h = 60km/h"
132
+ result.answer # => "60 km/h"
133
+ ```
114
134
 
115
- Set the matching `DSPY_WITH_*` environment variables (see `Gemfile`) to include or exclude each sibling gem when running Bundler locally (for example `DSPY_WITH_GEPA=1` or `DSPY_WITH_O11Y_LANGFUSE=1`). Refer to `adr/013-dependency-tree.md` for the full dependency map and roadmap.
116
- ### Access to 200+ Models Across 5 Providers
135
+ ### ReAct Agents
117
136
 
118
- DSPy.rb provides unified access to major LLM providers with provider-specific optimizations:
137
+ Build agents that use tools to accomplish tasks:
119
138
 
120
139
  ```ruby
121
- # OpenAI (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.)
122
- DSPy.configure do |c|
123
- c.lm = DSPy::LM.new('openai/gpt-4o-mini',
124
- api_key: ENV['OPENAI_API_KEY'],
125
- structured_outputs: true) # Native JSON mode
126
- end
140
+ class SearchTool < DSPy::Tools::Tool
141
+ tool_name "search"
142
+ description "Search for information"
127
143
 
128
- # Google Gemini (Gemini 1.5 Pro, Flash, Gemini 2.0, etc.)
129
- DSPy.configure do |c|
130
- c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
131
- api_key: ENV['GEMINI_API_KEY'],
132
- structured_outputs: true) # Native structured outputs
133
- end
144
+ input do
145
+ const :query, String
146
+ end
134
147
 
135
- # Anthropic Claude (Claude 3.5, Claude 4, etc.)
136
- DSPy.configure do |c|
137
- c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-5-20250929',
138
- api_key: ENV['ANTHROPIC_API_KEY'],
139
- structured_outputs: true) # Tool-based extraction (default)
140
- end
148
+ output do
149
+ const :results, T::Array[String]
150
+ end
141
151
 
142
- # Ollama - Run any local model (Llama, Mistral, Gemma, etc.)
143
- DSPy.configure do |c|
144
- c.lm = DSPy::LM.new('ollama/llama3.2') # Free, runs locally, no API key needed
152
+ def call(query:)
153
+ # Your search implementation
154
+ { results: ["Result 1", "Result 2"] }
155
+ end
145
156
  end
146
157
 
147
- # OpenRouter - Access to 200+ models from multiple providers
148
- DSPy.configure do |c|
149
- c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
150
- api_key: ENV['OPENROUTER_API_KEY'])
151
- end
158
+ toolset = DSPy::Tools::Toolset.new(tools: [SearchTool.new])
159
+ agent = DSPy::ReAct.new(signature: ResearchTask, tools: toolset, max_iterations: 5)
160
+ result = agent.call(question: "What's the latest on Ruby 3.4?")
152
161
  ```
153
162
 
154
- ## What You Get
155
-
156
- **Developer Experience:** Official clients, multimodal coverage, and observability baked in.
157
- <details>
158
- <summary>Expand for everything included</summary>
159
-
160
- - LLM provider support using official Ruby clients:
161
- - [OpenAI Ruby](https://github.com/openai/openai-ruby) with vision model support
162
- - [Anthropic Ruby SDK](https://github.com/anthropics/anthropic-sdk-ruby) with multimodal capabilities
163
- - [Google Gemini API](https://ai.google.dev/) with native structured outputs
164
- - [Ollama](https://ollama.com/) via OpenAI compatibility layer for local models
165
- - **Multimodal Support** - Complete image analysis with DSPy::Image, type-safe bounding boxes, vision-capable models
166
- - Runtime type checking with [Sorbet](https://sorbet.org/) including T::Enum and union types
167
- - Type-safe tool definitions for ReAct agents
168
- - Comprehensive instrumentation and observability
169
- </details>
170
-
171
- **Core Building Blocks:** Predictors, agents, and pipelines wired through type-safe signatures.
172
- <details>
173
- <summary>Expand for everything included</summary>
174
-
175
- - **Signatures** - Define input/output schemas using Sorbet types with T::Enum and union type support
176
- - **Predict** - LLM completion with structured data extraction and multimodal support
177
- - **Chain of Thought** - Step-by-step reasoning for complex problems with automatic prompt optimization
178
- - **ReAct** - Tool-using agents with type-safe tool definitions and error recovery
179
- - **Module Composition** - Combine multiple LLM calls into production-ready workflows
180
- </details>
181
-
182
- **Optimization & Evaluation:** Treat prompt optimization like a real ML workflow.
183
- <details>
184
- <summary>Expand for everything included</summary>
185
-
186
- - **Prompt Objects** - Manipulate prompts as first-class objects instead of strings
187
- - **Typed Examples** - Type-safe training data with automatic validation
188
- - **Evaluation Framework** - Advanced metrics beyond simple accuracy with error-resilient pipelines
189
- - **MIPROv2 Optimization** - Advanced Bayesian optimization with Gaussian Processes, multiple optimization strategies, auto-config presets, and storage persistence
190
- </details>
191
-
192
- **Production Features:** Hardened behaviors for teams shipping actual products.
193
- <details>
194
- <summary>Expand for everything included</summary>
195
-
196
- - **Reliable JSON Extraction** - Native structured outputs for OpenAI and Gemini, Anthropic tool-based extraction, and automatic strategy selection with fallback
197
- - **Type-Safe Configuration** - Strategy enums with automatic provider optimization (Strict/Compatible modes)
198
- - **Smart Retry Logic** - Progressive fallback with exponential backoff for handling transient failures
199
- - **Zero-Config Langfuse Integration** - Set env vars and get automatic OpenTelemetry traces in Langfuse
200
- - **Performance Caching** - Schema and capability caching for faster repeated operations
201
- - **File-based Storage** - Optimization result persistence with versioning
202
- - **Structured Logging** - JSON and key=value formats with span tracking
203
- </details>
204
-
205
- ## Recent Achievements
206
-
207
- DSPy.rb has gone from experimental to production-ready in three fast releases.
208
- <details>
209
- <summary>Expand for the full changelog highlights</summary>
210
-
211
- ### Foundation
212
- - ✅ **JSON Parsing Reliability** - Native OpenAI structured outputs with adaptive retry logic and schema-aware fallbacks
213
- - ✅ **Type-Safe Strategy Configuration** - Provider-optimized strategy selection and enum-backed optimizer presets
214
- - ✅ **Core Module System** - Predict, ChainOfThought, ReAct with type safety (add `dspy-code_act` for Think-Code-Observe agents)
215
- - ✅ **Production Observability** - OpenTelemetry, New Relic, and Langfuse integration
216
- - ✅ **Advanced Optimization** - MIPROv2 with Bayesian optimization, Gaussian Processes, and multi-mode search
217
-
218
- ### Recent Advances
219
- - ✅ **MIPROv2 ADE Integrity (v0.29.1)** - Stratified train/val/test splits, honest precision accounting, and enum-driven `--auto` presets with integration coverage
220
- - ✅ **Instruction Deduplication (v0.29.1)** - Candidate generation now filters repeated programs so optimization logs highlight unique strategies
221
- - ✅ **GEPA Teleprompter (v0.29.0)** - Genetic-Pareto reflective prompt evolution with merge proposer scheduling, reflective mutation, and ADE demo parity
222
- - ✅ **Optimizer Utilities Parity (v0.29.0)** - Bootstrap strategies, dataset summaries, and Layer 3 utilities unlock multi-predictor programs on Ruby
223
- - ✅ **Observability Hardening (v0.29.0)** - OTLP exporter runs on a single-thread executor preventing frozen SSL contexts without blocking spans
224
- - ✅ **Documentation Refresh (v0.29.x)** - New GEPA guide plus ADE optimization docs covering presets, stratified splits, and error-handling defaults
225
- </details>
226
-
227
- **Current Focus Areas:** Closing the loop on production patterns and community adoption ahead of v1.0.
228
- <details>
229
- <summary>Expand for the roadmap</summary>
230
-
231
- ### Production Readiness
232
- - 🚧 **Production Patterns** - Real-world usage validation and performance optimization
233
- - 🚧 **Ruby Ecosystem Integration** - Rails integration, Sidekiq compatibility, deployment patterns
234
-
235
- ### Community & Adoption
236
- - 🚧 **Community Examples** - Real-world applications and case studies
237
- - 🚧 **Contributor Experience** - Making it easier to contribute and extend
238
- - 🚧 **Performance Benchmarks** - Comparative analysis vs other frameworks
239
- </details>
240
-
241
- **v1.0 Philosophy:** v1.0 lands after battle-testing, not checkbox bingo. The API is already stable; the milestone marks production confidence.
163
+ ## What's Included
164
+
165
+ **Core Modules**: Predict, ChainOfThought, ReAct agents, and composable pipelines.
166
+
167
+ **Type Safety**: Sorbet-based runtime validation. Enums, unions, nested structs—all work.
168
+
169
+ **Multimodal**: Image analysis with `DSPy::Image` for vision-capable models.
170
+
171
+ **Observability**: Zero-config Langfuse integration via OpenTelemetry. Non-blocking, production-ready.
242
172
 
173
+ **Optimization**: MIPROv2 (Bayesian optimization) and GEPA (genetic evolution) for prompt tuning.
174
+
175
+ **Provider Support**: OpenAI, Anthropic, Gemini, Ollama, and OpenRouter via official SDKs.
243
176
 
244
177
  ## Documentation
245
178
 
246
- 📖 **[Complete Documentation Website](https://vicentereig.github.io/dspy.rb/)**
179
+ **[Full Documentation](https://oss.vicente.services/dspy.rb/)** — Getting started, core concepts, advanced patterns.
247
180
 
248
- ### LLM-Friendly Documentation
181
+ **[llms.txt](https://oss.vicente.services/dspy.rb/llms.txt)** LLM-friendly reference for AI assistants.
249
182
 
250
- For LLMs and AI assistants working with DSPy.rb:
251
- - **[llms.txt](https://vicentereig.github.io/dspy.rb/llms.txt)** - Concise reference optimized for LLMs
252
- - **[llms-full.txt](https://vicentereig.github.io/dspy.rb/llms-full.txt)** - Comprehensive API documentation
183
+ ### Claude Skill
253
184
 
254
- ### Getting Started
255
- - **[Installation & Setup](docs/src/getting-started/installation.md)** - Detailed installation and configuration
256
- - **[Quick Start Guide](docs/src/getting-started/quick-start.md)** - Your first DSPy programs
257
- - **[Core Concepts](docs/src/getting-started/core-concepts.md)** - Understanding signatures, predictors, and modules
185
+ A [Claude Skill](https://github.com/vicentereig/dspy-rb-skill) is available to help you build DSPy.rb applications:
258
186
 
259
- ### Prompt Engineering
260
- - **[Signatures & Types](docs/src/core-concepts/signatures.md)** - Define typed interfaces for LLM operations
261
- - **[Predictors](docs/src/core-concepts/predictors.md)** - Predict, ChainOfThought, ReAct, and more
262
- - **[Modules & Pipelines](docs/src/core-concepts/modules.md)** - Compose complex multi-stage workflows
263
- - **[Multimodal Support](docs/src/core-concepts/multimodal.md)** - Image analysis with vision-capable models
264
- - **[Examples & Validation](docs/src/core-concepts/examples.md)** - Type-safe training data
265
- - **[Rich Types](docs/src/advanced/complex-types.md)** - Sorbet type integration with automatic coercion for structs, enums, and arrays
266
- - **[Composable Pipelines](docs/src/advanced/pipelines.md)** - Manual module composition patterns
187
+ ```bash
188
+ # Claude Code
189
+ git clone https://github.com/vicentereig/dspy-rb-skill ~/.claude/skills/dspy-rb
190
+ ```
267
191
 
268
- ### Prompt Optimization
269
- - **[Evaluation Framework](docs/src/optimization/evaluation.md)** - Advanced metrics beyond simple accuracy
270
- - **[Prompt Optimization](docs/src/optimization/prompt-optimization.md)** - Manipulate prompts as objects
271
- - **[MIPROv2 Optimizer](docs/src/optimization/miprov2.md)** - Advanced Bayesian optimization with Gaussian Processes
272
- - **[GEPA Optimizer](docs/src/optimization/gepa.md)** *(beta)* - Reflective mutation with optional reflection LMs
192
+ 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.
273
193
 
274
- ### Context Engineering
275
- - **[Tools](docs/src/core-concepts/toolsets.md)** - Tool wieldint agents.
276
- - **[Agentic Memory](docs/src/core-concepts/memory.md)** - Memory Tools & Agentic Loops
277
- - **[RAG Patterns](docs/src/advanced/rag.md)** - Manual RAG implementation with external services
194
+ ## Examples
278
195
 
279
- ### Production Features
280
- - **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration with a dedicated export worker that never blocks your LLMs
281
- - **[Storage System](docs/src/production/storage.md)** - Persistence and optimization result storage
282
- - **[Custom Metrics](docs/src/advanced/custom-metrics.md)** - Proc-based evaluation logic
196
+ The [examples/](examples/) directory has runnable code for common patterns:
283
197
 
198
+ - Sentiment classification
199
+ - ReAct agents with tools
200
+ - Image analysis
201
+ - Prompt optimization
284
202
 
203
+ ```bash
204
+ bundle exec ruby examples/first_predictor.rb
205
+ ```
206
+
207
+ ## Optional Gems
285
208
 
209
+ DSPy.rb ships sibling gems for features with heavier dependencies. Add them as needed:
286
210
 
211
+ | Gem | What it does |
212
+ | --- | --- |
213
+ | `dspy-datasets` | Dataset helpers, Parquet/Polars tooling |
214
+ | `dspy-evals` | Evaluation harness with metrics and callbacks |
215
+ | `dspy-miprov2` | Bayesian optimization for prompt tuning |
216
+ | `dspy-gepa` | Genetic-Pareto prompt evolution |
217
+ | `dspy-o11y-langfuse` | Auto-configure Langfuse tracing |
218
+ | `dspy-code_act` | Think-Code-Observe agents |
219
+ | `dspy-deep_search` | Production DeepSearch with Exa |
287
220
 
221
+ See [the full list](https://oss.vicente.services/dspy.rb/getting-started/installation/) in the docs.
288
222
 
223
+ ## Contributing
289
224
 
225
+ 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).
226
+
227
+ Want to contribute code? Reach out: hey at vicente.services
290
228
 
291
229
  ## License
292
- This project is licensed under the MIT License.
230
+
231
+ MIT License.
@@ -12,10 +12,33 @@ module DSPy
12
12
  extend T::Sig
13
13
  extend T::Helpers
14
14
 
15
+ # Result type that includes both schema and any accumulated definitions
16
+ class SchemaResult < T::Struct
17
+ const :schema, T::Hash[Symbol, T.untyped]
18
+ const :definitions, T::Hash[String, T::Hash[Symbol, T.untyped]], default: {}
19
+ end
20
+
21
+ # Convert a Sorbet type to JSON Schema format with definitions tracking
22
+ # Returns a SchemaResult with the schema and any $defs needed
23
+ 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) }
24
+ def self.type_to_json_schema_with_defs(type, visited = nil, definitions = nil)
25
+ visited ||= Set.new
26
+ definitions ||= {}
27
+ schema = type_to_json_schema_internal(type, visited, definitions)
28
+ SchemaResult.new(schema: schema, definitions: definitions)
29
+ end
30
+
15
31
  # Convert a Sorbet type to JSON Schema format
32
+ # For backward compatibility, this method returns just the schema hash
16
33
  sig { params(type: T.untyped, visited: T.nilable(T::Set[T.untyped])).returns(T::Hash[Symbol, T.untyped]) }
17
34
  def self.type_to_json_schema(type, visited = nil)
18
35
  visited ||= Set.new
36
+ type_to_json_schema_internal(type, visited, {})
37
+ end
38
+
39
+ # Internal implementation that tracks definitions
40
+ 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]) }
41
+ def self.type_to_json_schema_internal(type, visited, definitions)
19
42
 
20
43
  # Handle T::Boolean type alias first
21
44
  if type == T::Boolean
@@ -24,7 +47,7 @@ module DSPy
24
47
 
25
48
  # Handle type aliases by resolving to their underlying type
26
49
  if type.is_a?(T::Private::Types::TypeAlias)
27
- return self.type_to_json_schema(type.aliased_type, visited)
50
+ return type_to_json_schema_internal(type.aliased_type, visited, definitions)
28
51
  end
29
52
 
30
53
  # Handle raw class types first
@@ -54,12 +77,13 @@ module DSPy
54
77
  # Check for recursion
55
78
  if visited.include?(type)
56
79
  # Return a reference to avoid infinite recursion
80
+ # Use #/$defs/ format for OpenAI/Gemini compatibility
81
+ simple_name = type.name.split('::').last
57
82
  {
58
- "$ref" => "#/definitions/#{type.name.split('::').last}",
59
- description: "Recursive reference to #{type.name}"
83
+ "$ref" => "#/$defs/#{simple_name}"
60
84
  }
61
85
  else
62
- self.generate_struct_schema(type, visited)
86
+ generate_struct_schema_internal(type, visited, definitions)
63
87
  end
64
88
  else
65
89
  { type: "string" } # Default fallback
@@ -93,12 +117,13 @@ module DSPy
93
117
  elsif type.raw_type < T::Struct
94
118
  # Handle custom T::Struct classes
95
119
  if visited.include?(type.raw_type)
120
+ # Use #/$defs/ format for OpenAI/Gemini compatibility
121
+ simple_name = type.raw_type.name.split('::').last
96
122
  {
97
- "$ref" => "#/definitions/#{type.raw_type.name.split('::').last}",
98
- description: "Recursive reference to #{type.raw_type.name}"
123
+ "$ref" => "#/$defs/#{simple_name}"
99
124
  }
100
125
  else
101
- generate_struct_schema(type.raw_type, visited)
126
+ generate_struct_schema_internal(type.raw_type, visited, definitions)
102
127
  end
103
128
  else
104
129
  { type: "string" } # Default fallback
@@ -108,29 +133,30 @@ module DSPy
108
133
  # Handle arrays properly with nested item type
109
134
  {
110
135
  type: "array",
111
- items: self.type_to_json_schema(type.type, visited)
136
+ items: type_to_json_schema_internal(type.type, visited, definitions)
112
137
  }
113
138
  elsif type.is_a?(T::Types::TypedHash)
114
139
  # Handle hashes as objects with additionalProperties
115
140
  # TypedHash has keys and values methods to access its key and value types
116
- key_schema = self.type_to_json_schema(type.keys, visited)
117
- value_schema = self.type_to_json_schema(type.values, visited)
118
-
119
- # Create a more descriptive schema for nested structures
141
+ # Note: propertyNames is NOT supported by OpenAI structured outputs, so we omit it
142
+ value_schema = type_to_json_schema_internal(type.values, visited, definitions)
143
+ key_type_desc = type.keys.respond_to?(:raw_type) ? type.keys.raw_type.to_s : "string"
144
+ value_type_desc = value_schema[:description] || value_schema[:type].to_s
145
+
146
+ # Create a schema compatible with OpenAI structured outputs
120
147
  {
121
148
  type: "object",
122
- propertyNames: key_schema, # Describe key constraints
123
149
  additionalProperties: value_schema,
124
- # Add a more explicit description of the expected structure
125
- description: "A mapping where keys are #{key_schema[:type]}s and values are #{value_schema[:description] || value_schema[:type]}s"
150
+ # Description explains the expected structure without using propertyNames
151
+ description: "A mapping where keys are #{key_type_desc}s and values are #{value_type_desc}s"
126
152
  }
127
153
  elsif type.is_a?(T::Types::FixedHash)
128
154
  # Handle fixed hashes (from type aliases like { "key" => Type })
129
155
  properties = {}
130
156
  required = []
131
-
157
+
132
158
  type.types.each do |key, value_type|
133
- properties[key] = self.type_to_json_schema(value_type, visited)
159
+ properties[key] = type_to_json_schema_internal(value_type, visited, definitions)
134
160
  required << key
135
161
  end
136
162
 
@@ -154,9 +180,9 @@ module DSPy
154
180
  !(t.respond_to?(:raw_type) && t.raw_type == NilClass) &&
155
181
  !(t.respond_to?(:name) && t.name == "NilClass")
156
182
  end
157
-
183
+
158
184
  if non_nil_type
159
- base_schema = self.type_to_json_schema(non_nil_type, visited)
185
+ base_schema = type_to_json_schema_internal(non_nil_type, visited, definitions)
160
186
  if base_schema[:type].is_a?(String)
161
187
  # Convert single type to array with null
162
188
  { type: [base_schema[:type], "null"] }.merge(base_schema.except(:type))
@@ -169,16 +195,16 @@ module DSPy
169
195
  end
170
196
  else
171
197
  # Not nilable SimplePairUnion - this is a regular T.any() union
172
- # Generate oneOf schema for all types
198
+ # Generate anyOf schema for all types (oneOf not supported by Anthropic strict mode)
173
199
  if type.respond_to?(:types) && type.types.length > 1
174
200
  {
175
- oneOf: type.types.map { |t| self.type_to_json_schema(t, visited) },
201
+ anyOf: type.types.map { |t| type_to_json_schema_internal(t, visited, definitions) },
176
202
  description: "Union of multiple types"
177
203
  }
178
204
  else
179
205
  # Single type or fallback
180
206
  first_type = type.respond_to?(:types) ? type.types.first : type
181
- self.type_to_json_schema(first_type, visited)
207
+ type_to_json_schema_internal(first_type, visited, definitions)
182
208
  end
183
209
  end
184
210
  elsif type.is_a?(T::Types::Union)
@@ -199,7 +225,7 @@ module DSPy
199
225
 
200
226
  if non_nil_types.size == 1 && is_nilable
201
227
  # This is T.nilable(SomeType) - generate proper schema with null allowed
202
- base_schema = self.type_to_json_schema(non_nil_types.first, visited)
228
+ base_schema = type_to_json_schema_internal(non_nil_types.first, visited, definitions)
203
229
  if base_schema[:type].is_a?(String)
204
230
  # Convert single type to array with null
205
231
  { type: [base_schema[:type], "null"] }.merge(base_schema.except(:type))
@@ -209,16 +235,16 @@ module DSPy
209
235
  end
210
236
  elsif non_nil_types.size == 1
211
237
  # Non-nilable single type union (shouldn't happen in practice)
212
- self.type_to_json_schema(non_nil_types.first, visited)
238
+ type_to_json_schema_internal(non_nil_types.first, visited, definitions)
213
239
  elsif non_nil_types.size > 1
214
- # Handle complex unions with oneOf for better JSON schema compliance
240
+ # Handle complex unions with anyOf (oneOf not supported by Anthropic strict mode)
215
241
  base_schema = {
216
- oneOf: non_nil_types.map { |t| self.type_to_json_schema(t, visited) },
242
+ anyOf: non_nil_types.map { |t| type_to_json_schema_internal(t, visited, definitions) },
217
243
  description: "Union of multiple types"
218
244
  }
219
245
  if is_nilable
220
246
  # Add null as an option for complex nilable unions
221
- base_schema[:oneOf] << { type: "null" }
247
+ base_schema[:anyOf] << { type: "null" }
222
248
  end
223
249
  base_schema
224
250
  else
@@ -236,12 +262,31 @@ module DSPy
236
262
  end
237
263
 
238
264
  # Generate JSON schema for custom T::Struct classes
265
+ # For backward compatibility, this returns just the schema hash
239
266
  sig { params(struct_class: T.class_of(T::Struct), visited: T.nilable(T::Set[T.untyped])).returns(T::Hash[Symbol, T.untyped]) }
240
267
  def self.generate_struct_schema(struct_class, visited = nil)
241
268
  visited ||= Set.new
242
-
269
+ generate_struct_schema_internal(struct_class, visited, {})
270
+ end
271
+
272
+ # Generate JSON schema with $defs tracking
273
+ # Returns a SchemaResult with schema and accumulated definitions
274
+ 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) }
275
+ def self.generate_struct_schema_with_defs(struct_class, visited = nil, definitions = nil)
276
+ visited ||= Set.new
277
+ definitions ||= {}
278
+ schema = generate_struct_schema_internal(struct_class, visited, definitions)
279
+ SchemaResult.new(schema: schema, definitions: definitions)
280
+ end
281
+
282
+ # Internal implementation that tracks definitions for $defs
283
+ 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]) }
284
+ def self.generate_struct_schema_internal(struct_class, visited, definitions)
243
285
  return { type: "string", description: "Struct (schema introspection not available)" } unless struct_class.respond_to?(:props)
244
286
 
287
+ struct_name = struct_class.name || "Struct#{format('%x', struct_class.object_id)}"
288
+ simple_name = struct_name.split('::').last || struct_name
289
+
245
290
  # Add this struct to visited set to detect recursion
246
291
  visited.add(struct_class)
247
292
 
@@ -257,14 +302,24 @@ module DSPy
257
302
  # Add automatic _type field for type detection
258
303
  properties[:_type] = {
259
304
  type: "string",
260
- const: struct_class.name.split('::').last # Use the simple class name
305
+ const: simple_name # Use the simple class name
261
306
  }
262
307
  required << "_type"
263
308
 
309
+ # Get field descriptions if the struct supports them (via DSPy::Ext::StructDescriptions)
310
+ field_descs = struct_class.respond_to?(:field_descriptions) ? struct_class.field_descriptions : {}
311
+
264
312
  struct_class.props.each do |prop_name, prop_info|
265
313
  prop_type = prop_info[:type_object] || prop_info[:type]
266
- properties[prop_name] = self.type_to_json_schema(prop_type, visited)
267
-
314
+ prop_schema = type_to_json_schema_internal(prop_type, visited, definitions)
315
+
316
+ # Add field description if available
317
+ if field_descs[prop_name]
318
+ prop_schema[:description] = field_descs[prop_name]
319
+ end
320
+
321
+ properties[prop_name] = prop_schema
322
+
268
323
  # A field is required if it's not fully optional
269
324
  # fully_optional is true for nilable prop fields
270
325
  # immutable const fields are required unless nilable
@@ -276,12 +331,19 @@ module DSPy
276
331
  # Remove this struct from visited set after processing
277
332
  visited.delete(struct_class)
278
333
 
279
- {
334
+ schema = {
280
335
  type: "object",
281
336
  properties: properties,
282
337
  required: required,
283
- description: "#{struct_class.name} struct"
338
+ description: "#{struct_name} struct",
339
+ additionalProperties: false
284
340
  }
341
+
342
+ # Add this struct's schema to definitions for $defs
343
+ # This allows recursive references to be resolved
344
+ definitions[simple_name] = schema
345
+
346
+ schema
285
347
  end
286
348
 
287
349
  private
@@ -0,0 +1,81 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'sorbet-runtime'
4
+ require 'sorbet/toon'
5
+
6
+ require_relative '../lm/errors'
7
+
8
+ module DSPy
9
+ module Schema
10
+ module SorbetToonAdapter
11
+ extend T::Sig
12
+
13
+ module_function
14
+
15
+ sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), values: T::Hash[Symbol, T.untyped]).returns(String) }
16
+ def render_input(signature_class, values)
17
+ Sorbet::Toon.encode(
18
+ values,
19
+ signature: signature_class,
20
+ role: :input
21
+ )
22
+ end
23
+
24
+ sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), values: T::Hash[Symbol, T.untyped]).returns(String) }
25
+ def render_expected_output(signature_class, values)
26
+ Sorbet::Toon.encode(
27
+ values,
28
+ signature: signature_class,
29
+ role: :output
30
+ )
31
+ end
32
+
33
+ sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), toon_string: String).returns(T.untyped) }
34
+ def parse_output(signature_class, toon_string)
35
+ payload = strip_code_fences(toon_string)
36
+
37
+ Sorbet::Toon.decode(
38
+ payload,
39
+ signature: signature_class,
40
+ role: :output,
41
+ strict: false
42
+ )
43
+ rescue Sorbet::Toon::DecodeError => e
44
+ log_decode_error(payload, e)
45
+ raise DSPy::LM::AdapterError,
46
+ "Failed to parse TOON response: #{e.message}. Ensure the model replies with a ```toon``` block using the schema described in the system prompt."
47
+ end
48
+
49
+ sig { params(text: T.nilable(String)).returns(String) }
50
+ def strip_code_fences(text)
51
+ return '' if text.nil?
52
+
53
+ match = text.match(/```(?:toon)?\s*(.*?)```/m)
54
+ return match[1].strip if match
55
+
56
+ text.strip
57
+ end
58
+
59
+ sig { params(payload: String, error: StandardError).void }
60
+ def log_decode_error(payload, error)
61
+ logger = DSPy.logger if DSPy.respond_to?(:logger)
62
+ return unless logger.respond_to?(:warn)
63
+
64
+ preview = payload.to_s.lines.first(5).join
65
+ logger.warn(
66
+ event: 'toon.decode_error',
67
+ error: error.message,
68
+ preview: preview,
69
+ length: payload.to_s.length
70
+ )
71
+ end
72
+
73
+ sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), role: Symbol).returns(String) }
74
+ def field_guidance(signature_class, role)
75
+ return '' unless signature_class
76
+
77
+ Sorbet::Toon::SignatureFormatter.describe_signature(signature_class, role)
78
+ end
79
+ end
80
+ end
81
+ end
@@ -2,6 +2,6 @@
2
2
 
3
3
  module DSPy
4
4
  module Schema
5
- VERSION = "1.0.1"
5
+ VERSION = "1.0.2"
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,14 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: dspy-schema
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.1
4
+ version: 1.0.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Vicente Reig Rincón de Arellano
8
- autorequire:
9
8
  bindir: bin
10
9
  cert_chain: []
11
- date: 2025-10-30 00:00:00.000000000 Z
10
+ date: 1980-01-02 00:00:00.000000000 Z
12
11
  dependencies:
13
12
  - !ruby/object:Gem::Dependency
14
13
  name: sorbet-runtime
@@ -36,13 +35,13 @@ files:
36
35
  - README.md
37
36
  - lib/dspy/schema.rb
38
37
  - lib/dspy/schema/sorbet_json_schema.rb
38
+ - lib/dspy/schema/sorbet_toon_adapter.rb
39
39
  - lib/dspy/schema/version.rb
40
40
  homepage: https://github.com/vicentereig/dspy.rb
41
41
  licenses:
42
42
  - MIT
43
43
  metadata:
44
44
  github_repo: git@github.com:vicentereig/dspy.rb
45
- post_install_message:
46
45
  rdoc_options: []
47
46
  require_paths:
48
47
  - lib
@@ -50,15 +49,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
50
49
  requirements:
51
50
  - - ">="
52
51
  - !ruby/object:Gem::Version
53
- version: 3.0.0
52
+ version: 3.3.0
54
53
  required_rubygems_version: !ruby/object:Gem::Requirement
55
54
  requirements:
56
55
  - - ">="
57
56
  - !ruby/object:Gem::Version
58
57
  version: '0'
59
58
  requirements: []
60
- rubygems_version: 3.0.3.1
61
- signing_key:
59
+ rubygems_version: 3.6.9
62
60
  specification_version: 4
63
61
  summary: Sorbet to JSON Schema conversion utilities reused by DSPy.rb.
64
62
  test_files: []