dspy 0.29.1 → 0.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42a6bfa4a1e0fe7b7dd38e3a2fe017959365f566248319e1deec6cadcd06efc3
-  data.tar.gz: ffceb724c96e7803ec7531bf52c12f502266e21d4ab9bcf534a8005e59835883
+  metadata.gz: 0bdf656ce5715a455d3fb36427878ae507d8d4bd9a7f092a6b9752196f9ebc4b
+  data.tar.gz: cd21540e0eea82c1567c085b9ef2fd5c2d9742cd1ff08f855a16f4109893ebb2
 SHA512:
-  metadata.gz: 2d81f0ab86954523f8b3511f3105f8005b9709f0a46fb08f0403dcac841c70efcfbff90dcdedccaf322554280f62bdbab6a36be34d0e787f01734d8ee2219bf6
-  data.tar.gz: 31d048ad3d7493be0c52a24729d033ce58a891039c180945aa80d54afb7a529b6e420ccfc49fdab32ef00803483ecbb63dd2c2bd9d15f569c44debfdfd6dea0c
+  metadata.gz: 992c191cbc6bbdd1bc770a83d4a1151869c4f57a20d7236a19b0add9c50329ec2dea901fe440488b2194fe96951d729c4509d33a9df8fb6c2dc7154c570e9c00
+  data.tar.gz: 82e67a674db952801adf40407d34daf0e2808f4c1b4d99da60f63c33fd2033b7f5a2deaefe63ea91bf4bcc7129e7580772877df3ca3b69bf9894d2454a5bdf38

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

@@ -5,26 +5,62 @@
 [![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. 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.
+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 optimization from the original Python library, DSPy.rb embraces Ruby 
-conventions and adds Ruby-specific innovations like CodeAct agents and enhanced production instrumentation.
+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.
 
-The result? 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
-# Define a signature for sentiment classification
+gem 'dspy'
+```
+
+and
+
+```bash
+bundle install
+```
+
+### 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."
+  description "Classify sentiment of a given sentence." # sets the goal of the underlying prompt
 
   class Sentiment < T::Enum
     enums do
@@ -33,26 +69,83 @@ 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
+    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
-    const :confidence, Float
+    const :sentiment, Sentiment, description: 'The sentiment of the sentence'
+    const :confidence, Float, description: 'A number between 0.0 and 1.0'
   end
 end
 
-# Configure DSPy with your LLM
+# 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
+```
+
+### Sibling Gems
+
+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`:
+
+| Gem | Description | Status |
+| --- | --- | --- |
+| `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) |
+| `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) |
+| `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. (Toggle via `DSPY_WITH_DATASETS`.) | **Stable** (v1.0.0) |
+| `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. (Toggle via `DSPY_WITH_EVALS`.) | **Stable** (v1.0.0) |
+| `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) |
+| `dspy-gepa` | `DSPy::Teleprompt::GEPA`, reflection loops, experiment tracking, telemetry adapters. (Install or set `DSPY_WITH_GEPA=1`.) | **Stable** (v1.0.0) |
+| `gepa` | GEPA optimizer core (Pareto engine, telemetry, reflective proposer). | **Stable** (v1.0.0) |
+| `dspy-o11y` | Core observability APIs: `DSPy::Observability`, async span processor, observation types. (Install or set `DSPY_WITH_O11Y=1`.) | **Stable** (v1.0.0) |
+| `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) |
+
+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.
+### 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', 
+  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
 
-# Create the predictor and run inference
+# 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>  
@@ -99,12 +192,22 @@ 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
-- **CodeAct** - Dynamic code execution agents for programming tasks
 - **Module Composition** - Combine multiple LLM calls into production-ready workflows
 
 **Optimization & Evaluation:**
@@ -122,24 +225,40 @@ end
 - **File-based Storage** - Optimization result persistence with versioning
 - **Structured Logging** - JSON and key=value formats with span tracking
 
-**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
+## Recent Achievements
+
+DSPy.rb has rapidly evolved from experimental to production-ready:
 
-## Development Status
+### 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
 
-DSPy.rb is actively developed and approaching stability. The core framework is production-ready with 
-comprehensive documentation, but I'm battle-testing features through the 0.x series before committing 
-to a stable v1.0 API. 
+### 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.
 
-Real-world usage feedback is invaluable - if you encounter issues or have suggestions, please open a GitHub issue!
 
 ## Documentation
 
@@ -156,92 +275,37 @@ For LLMs and AI assistants working with DSPy.rb:
 - **[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
 
-### Core Features
+### 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
 
-### Optimization
+### 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
 
-### Production Features
-- **[Storage System](docs/src/production/storage.md)** - Persistence and optimization result storage
-- **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration with a dedicated export worker that never blocks your LLMs
-
-### Advanced Usage
-- **[Complex Types](docs/src/advanced/complex-types.md)** - Sorbet type integration with automatic coercion for structs, enums, and arrays
-- **[Manual Pipelines](docs/src/advanced/pipelines.md)** - Manual module composition patterns
+### 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
-- **[Custom Metrics](docs/src/advanced/custom-metrics.md)** - Proc-based evaluation logic
 
-## Quick Start
-
-### Installation
-
-Add to your Gemfile:
-
-```ruby
-gem 'dspy'
-```
-
-Then run:
-
-```bash
-bundle install
-```
-
-## Recent Achievements
-
-DSPy.rb has rapidly evolved from experimental to production-ready:
-
-### Foundation
-- ✅ **JSON Parsing Reliability** - Native OpenAI structured outputs, strategy selection, retry logic
-- ✅ **Type-Safe Strategy Configuration** - Provider-optimized automatic strategy selection  
-- ✅ **Core Module System** - Predict, ChainOfThought, ReAct, CodeAct with type safety
-- ✅ **Production Observability** - OpenTelemetry, New Relic, and Langfuse integration
-- ✅ **Advanced Optimization** - MIPROv2 with Bayesian optimization, Gaussian Processes, and multiple strategies
-
-### Recent Advances  
-- ✅ **Enhanced Langfuse Integration (v0.25.0)** - Comprehensive OpenTelemetry span reporting with proper input/output, hierarchical nesting, accurate timing, and observation types
-- ✅ **Comprehensive Multimodal Framework** - Complete image analysis with `DSPy::Image`, type-safe bounding boxes, vision model integration
-- ✅ **Advanced Type System** - `T::Enum` integration, union types for agentic workflows, complex type coercion
-- ✅ **Production-Ready Evaluation** - Multi-factor metrics beyond accuracy, error-resilient evaluation pipelines
-- ✅ **Documentation Ecosystem** - `llms.txt` for AI assistants, ADRs, blog articles, comprehensive examples
-- ✅ **API Maturation** - Simplified idiomatic patterns, better error handling, production-proven designs
+### 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 
 
-## Roadmap - Production Battle-Testing Toward v1.0
 
-DSPy.rb has transitioned from **feature building** to **production validation**. The core framework is
-feature-complete and stable - now I'm focusing on real-world usage patterns, performance optimization, 
-and ecosystem integration.
 
-**Current Focus Areas:**
 
-### Production Readiness
-- 🚧 **Production Patterns** - Real-world usage validation and performance optimization
-- 🚧 **Ruby Ecosystem Integration** - Rails integration, Sidekiq compatibility, deployment patterns
-- 🚧 **Scale Testing** - High-volume usage, memory management, connection pooling
-- 🚧 **Error Recovery** - Robust failure handling patterns for production environments
 
-### Ecosystem Expansion  
-- 🚧 **Model Context Protocol (MCP)** - Integration with MCP ecosystem
-- 🚧 **Additional Provider Support** - Azure OpenAI, local models beyond Ollama
-- 🚧 **Tool Ecosystem** - Expanded tool integrations for ReAct agents
 
-### 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.
 
 ## License
-
 This project is licensed under the MIT License.

data/lib/dspy/callbacks.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'set'
 require 'sorbet-runtime'
 
 module DSPy
@@ -42,48 +43,60 @@ module DSPy
     end
 
     module ClassMethods
+      # Configures a method to expose before callbacks.
+      #
+      # @param method_name [Symbol] the target method.
+      # @param wrap [Boolean] When true (default), the method is transparently wrapped so callbacks
+      #   run automatically on every invocation. Pass false when you plan to trigger callbacks
+      #   manually (e.g., to interleave custom spans or thread management). Manual targets are
+      #   never re-wrapped, so execution order stays entirely in your control.
       # Creates a before callback hook for the specified method
       #
       # @param method_name [Symbol] the method to add callback support to
-      def create_before_callback(method_name)
-        mark_method_has_callbacks(method_name)
+      def create_before_callback(method_name, wrap: true)
+        mark_method_has_callbacks(method_name, wrap: wrap)
         ensure_callback_method_defined(:before, method_name)
-        wrap_method_with_callbacks(method_name)
+        wrap_method_with_callbacks(method_name) if wrap
       end
 
       # Creates an after callback hook for the specified method
       #
       # @param method_name [Symbol] the method to add callback support to
-      def create_after_callback(method_name)
-        mark_method_has_callbacks(method_name)
+      def create_after_callback(method_name, wrap: true)
+        mark_method_has_callbacks(method_name, wrap: wrap)
         ensure_callback_method_defined(:after, method_name)
-        wrap_method_with_callbacks(method_name)
+        wrap_method_with_callbacks(method_name) if wrap
       end
 
       # Creates an around callback hook for the specified method
       #
       # @param method_name [Symbol] the method to add callback support to
-      def create_around_callback(method_name)
-        mark_method_has_callbacks(method_name)
+      def create_around_callback(method_name, wrap: true)
+        mark_method_has_callbacks(method_name, wrap: wrap)
         ensure_callback_method_defined(:around, method_name)
-        wrap_method_with_callbacks(method_name)
+        wrap_method_with_callbacks(method_name) if wrap
       end
 
       private
 
       # Ensures the callback registration method exists
       def ensure_callback_method_defined(type, target_method_name)
+        set_default_callback_target(type, target_method_name)
+
         return if singleton_class.method_defined?(type)
 
-        define_singleton_method(type) do |callback_method|
-          register_callback(type, target_method_name, callback_method)
+        define_singleton_method(type) do |callback_method = nil, target: default_callback_target(type), &block|
+          callback = callback_method || block
+          raise ArgumentError, "No callback provided for #{type}" unless callback
+
+          register_callback(type, target || default_callback_target(type), callback)
         end
       end
 
       # Registers a callback for execution
-      def register_callback(type, method_name, callback_method)
+      def register_callback(type, method_name, callback)
         own_callbacks_for(method_name)[type] ||= []
-        own_callbacks_for(method_name)[type] << callback_method
+        own_callbacks_for(method_name)[type] << callback
       end
 
       # Returns own callbacks (not including parent)
@@ -93,8 +106,9 @@ module DSPy
       end
 
       # Marks that a method has callback support (even if no callbacks registered yet)
-      def mark_method_has_callbacks(method_name)
+      def mark_method_has_callbacks(method_name, wrap: true)
         own_callbacks_for(method_name)
+        manual_callback_targets << method_name unless wrap
       end
 
       # Returns the callback registry for a method
@@ -164,6 +178,7 @@ module DSPy
 
         return unless has_callback_support
         return if method_wrapped?(method_name)
+        return if manual_callback_targets.include?(method_name)
 
         wrap_method_with_callbacks(method_name)
       end
@@ -191,29 +206,88 @@ module DSPy
       def method_wrapped?(method_name)
         @wrapped_methods&.include?(method_name)
       end
+
+      def manual_callback_targets
+        @manual_callback_targets ||= Set.new
+      end
+
+      def callback_defaults
+        @callback_defaults ||= {}
+      end
+
+      def set_default_callback_target(type, method_name)
+        callback_defaults[type] ||= method_name
+      end
+
+      def default_callback_target(type)
+        callback_defaults[type] || begin
+          if superclass.respond_to?(:default_callback_target, true)
+            superclass.send(:default_callback_target, type)
+          end
+        end
+      end
     end
 
     private
 
     # Executes callbacks of a specific type
-    def run_callbacks(type, method_name)
+    def run_callbacks(type, method_name, payload = nil)
       callbacks = self.class.send(:callbacks_for, method_name)[type]
       return unless callbacks
 
-      callbacks.each do |callback_method|
-        send(callback_method)
+      callbacks.each do |callback|
+        case callback
+        when Symbol
+          method_obj = method(callback)
+          if method_obj.arity.zero?
+            send(callback)
+          else
+            send(callback, payload)
+          end
+        when Proc
+          if callback.arity.zero?
+            instance_exec(&callback)
+          else
+            instance_exec(payload, &callback)
+          end
+        else
+          callback.call(payload)
+        end
       end
     end
 
     # Executes method with around callbacks
     def execute_with_around_callbacks(method_name, original_method, *args, **kwargs, &block)
       callbacks = self.class.send(:callbacks_for, method_name)[:around]
+      args_copy = args.dup
+      kwargs_copy = kwargs.dup
 
       # Build callback chain from innermost (original method) to outermost
       chain = callbacks.reverse.inject(
         -> { original_method.bind(self).call(*args, **kwargs, &block) }
-      ) do |inner, callback_method|
-        -> { send(callback_method) { inner.call } }
+      ) do |inner, callback|
+        if callback.is_a?(Proc)
+          -> do
+            next_proc = -> { inner.call }
+            proc_arity = callback.arity
+            expects_extra = proc_arity.abs > 1
+
+            if expects_extra
+              instance_exec(next_proc, args_copy, kwargs_copy, &callback)
+            else
+              instance_exec(next_proc, &callback)
+            end
+          end
+        else
+          -> do
+            method_obj = method(callback)
+            if method_obj.arity.zero?
+              send(callback) { inner.call }
+            else
+              send(callback, args_copy, kwargs_copy) { inner.call }
+            end
+          end
+        end
       end
 
       chain.call