dspy-gepa 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e10764f9e3ab0f02357872a5a321c6bc441887f368e7f10f45133d2e8bdc7654
+  data.tar.gz: dc0246817a8c6eef2e077265f455faead3169197b9c9fed8ebee60307533827b
+SHA512:
+  metadata.gz: 83f3f9b98b8ce979037396652eaa155ea53e31e1bb5ae8c0e813adeb56e2be48072b9c6656f780413b94d59c37553a389f8d3d4d3528e3ab32be090bc8ea1871
+  data.tar.gz: 1988ebec7b7ce2383501e7d8610bda3d13777e73c871a59d290eaf02089b450606271cacfc0707d9e3b58126ca1fb4424efe04c93c8c1a77537d192c84ef33f3

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,267 @@
+# 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 | Status |
+| --- | --- | --- |
+| `dspy-schema` | Exposes `DSPy::TypeSystem::SorbetJsonSchema` for downstream reuse. | **Stable** (v1.0.0) |
+| `dspy-code_act` | Think-Code-Observe agents that synthesize and execute Ruby safely. | Preview (0.x) |
+| `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. | Preview (0.x) |
+| `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. | Preview (0.x) |
+| `dspy-miprov2` | Bayesian optimization + Gaussian Process backend for the MIPROv2 teleprompter. | Preview (0.x) |
+| `dspy-gepa` | `DSPy::Teleprompt::GEPA`, reflection loops, experiment tracking, telemetry adapters. | Preview (mirrors `dspy` version) |
+| `gepa` | GEPA optimizer core (Pareto engine, telemetry, reflective proposer). | Preview (mirrors `dspy` version) |
+| `dspy-o11y` | Core observability APIs: `DSPy::Observability`, async span processor, observation types. | **Stable** (v1.0.0) |
+| `dspy-o11y-langfuse` | Auto-configures DSPy observability to stream spans to Langfuse via OTLP. | **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 `docs/core-concepts/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',
+                      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/gepa/teleprompt.rb

@@ -0,0 +1,531 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'set'
+require 'sorbet-runtime'
+require 'dspy/teleprompt/teleprompter'
+require 'dspy/teleprompt/utils'
+require 'dspy/teleprompt/instruction_updates'
+require 'gepa'
+
+module DSPy
+  module Teleprompt
+    class GEPA < Teleprompter
+      extend T::Sig
+      DEFAULT_CONFIG = {
+        max_metric_calls: 32,
+        minibatch_size: 2,
+        perfect_score: 1.0,
+        skip_perfect_score: true,
+        use_merge: true,
+        max_merge_invocations: 5
+      }.freeze
+
+      def self.configure
+        yield(default_config) if block_given?
+      end
+
+      def self.default_config
+        @default_config ||= DEFAULT_CONFIG.dup
+      end
+
+      class NullExperimentTracker
+        extend T::Sig
+        attr_reader :events
+
+        def initialize
+          @events = []
+        end
+
+        sig { params(metrics: T::Hash[Symbol, T.untyped], step: T.nilable(Integer)).void }
+        def log_metrics(metrics, step: nil)
+          @events << { metrics: metrics, step: step }
+        end
+      end
+
+      class NullLogger
+        extend T::Sig
+        attr_reader :messages
+
+        def initialize
+          @messages = []
+        end
+
+        sig { params(message: String).void }
+        def log(message)
+          @messages << message
+          DSPy.log('gepa.log', message: message)
+        end
+      end
+
+      class PredictAdapter
+        extend T::Sig
+
+        ReflectionLMType = T.type_alias do
+          T.any(DSPy::ReflectionLM, T.proc.params(arg0: String).returns(String))
+        end
+
+        FeedbackFnType = T.type_alias do
+          T.proc.params(
+            predictor_output: T.untyped,
+            predictor_inputs: T::Hash[T.any(String, Symbol), T.untyped],
+            module_inputs: DSPy::Example,
+            module_outputs: T.untyped,
+            captured_trace: T::Array[T::Hash[Symbol, T.untyped]]
+          ).returns(T.untyped)
+        end
+
+        sig do
+          params(
+            student: DSPy::Module,
+            metric: T.proc.params(arg0: DSPy::Example, arg1: T.untyped).returns(T.untyped),
+            reflection_lm: T.nilable(ReflectionLMType),
+            feedback_map: T::Hash[String, FeedbackFnType]
+          ).void
+        end
+        def initialize(student, metric, reflection_lm: nil, feedback_map: {})
+          @student = student
+          @metric = metric
+          @reflection_lm = reflection_lm
+          @feedback_map = feedback_map.transform_keys(&:to_s)
+
+          @predictor_entries = resolve_predictors(@student)
+          @predictor_names = @predictor_entries.map(&:first)
+        end
+
+        sig { returns(T::Hash[String, String]) }
+        def seed_candidate
+          @predictor_entries.each_with_object({}) do |(name, predictor), memo|
+            memo[name] = extract_instruction(predictor)
+          end
+        end
+
+        sig do
+          params(candidate: T::Hash[String, String], recorder: T.nilable(T.untyped)).returns(DSPy::Module)
+        end
+        def build_program(candidate, recorder: nil)
+          program = clone_module(@student)
+          duplicate_predictors!(program)
+
+          predictor_map = resolve_predictors(program).to_h
+          candidate.each do |name, new_instruction|
+            predictor = predictor_map[name]
+            next unless predictor
+
+            program, updated = InstructionUpdates.apply_instruction(program, predictor, new_instruction)
+
+            predictor_map[name] = updated
+          end
+
+          wrap_predictors_for_tracing!(program, recorder: recorder) if recorder
+          program
+        end
+
+        sig do
+          params(
+            batch: T::Array[DSPy::Example],
+            candidate: T::Hash[String, String],
+            capture_traces: T::Boolean
+          ).returns(::GEPA::Core::EvaluationBatch)
+        end
+        def evaluate(batch, candidate, capture_traces: false)
+          recorder = capture_traces ? TraceRecorder.new : nil
+          program = build_program(candidate, recorder: recorder)
+
+          if capture_traces
+            trajectories = batch.map do |example|
+              recorder&.start_example
+              prediction = program.call(**example.input_values)
+              result = @metric.call(example, prediction)
+              score, feedback = extract_score_and_feedback(result)
+              trace_entries = recorder ? recorder.finish_example : []
+
+              {
+                example: example,
+                prediction: prediction,
+                score: score,
+                feedback: feedback,
+                trace: trace_entries
+              }
+            end
+
+            scores = trajectories.map { |row| row[:score] }
+            outputs = trajectories.map { |row| row[:prediction] }
+            ::GEPA::Core::EvaluationBatch.new(outputs: outputs, scores: scores, trajectories: trajectories)
+          else
+            evaluator = DSPy::Evals.new(program, metric: nil, num_threads: nil, max_errors: batch.length * 100, provide_traceback: false)
+            results = batch.map do |example|
+              prediction = program.call(**example.input_values)
+              result = @metric.call(example, prediction)
+              score, = extract_score_and_feedback(result)
+              [prediction, score]
+            end
+            outputs = results.map(&:first)
+            scores = results.map(&:last)
+            ::GEPA::Core::EvaluationBatch.new(outputs: outputs, scores: scores, trajectories: nil)
+          end
+        end
+
+        sig do
+          params(
+            candidate: T::Hash[String, String],
+            eval_batch: ::GEPA::Core::EvaluationBatch,
+            components_to_update: T::Array[String]
+          ).returns(T::Hash[String, T::Array[T::Hash[String, T.untyped]]])
+        end
+        def make_reflective_dataset(candidate, eval_batch, components_to_update)
+          return {} unless eval_batch.trajectories
+
+          components_to_update.each_with_object({}) do |component, memo|
+            rows = eval_batch.trajectories.flat_map do |trajectory|
+              example = trajectory[:example]
+              expected = serialize_struct(example.expected)
+              actual_program_output = serialize_prediction(trajectory[:prediction])
+              diff = build_diff(expected, actual_program_output)
+              default_feedback = trajectory[:feedback] || "Score: #{trajectory[:score]}"
+              default_score = trajectory[:score]
+              full_trace = Array(trajectory[:trace])
+
+              full_trace.filter_map do |entry|
+                next unless entry[:predictor_name] == component
+
+                raw_inputs = entry[:inputs] || {}
+                raw_output = entry[:output]
+                inputs = serialize_struct(raw_inputs)
+                outputs = serialize_prediction(raw_output)
+
+                feedback_text = default_feedback
+                score_value = default_score
+                score_overridden = false
+
+                if (feedback_fn = @feedback_map[component])
+                  feedback_result = feedback_fn.call(
+                    predictor_output: raw_output,
+                    predictor_inputs: raw_inputs,
+                    module_inputs: example,
+                    module_outputs: trajectory[:prediction],
+                    captured_trace: full_trace
+                  )
+                  override_score, override_feedback = extract_score_and_feedback(feedback_result)
+                  feedback_text = override_feedback if override_feedback
+                  unless override_score.nil?
+                    score_value = override_score
+                    score_overridden = true
+                  end
+                end
+
+                row = {
+                  'Inputs' => inputs,
+                  'Expected' => expected,
+                  'Generated Outputs' => outputs,
+                  'Diff' => diff,
+                  'Feedback' => feedback_text
+                }
+                row['Score'] = score_value if score_overridden
+                row
+              end
+            end
+            memo[component] = rows unless rows.empty?
+          end
+        end
+
+        sig do
+          params(
+            candidate: T::Hash[String, String],
+            reflective_dataset: T::Hash[String, T::Array[T::Hash[String, T.untyped]]],
+            components_to_update: T::Array[String]
+          ).returns(T::Hash[String, String])
+        end
+        def propose_new_texts(candidate, reflective_dataset, components_to_update)
+          if @reflection_lm
+            components_to_update.to_h do |name|
+              response = ::GEPA::Strategies::InstructionProposalSignature.run(
+                @reflection_lm,
+                {
+                  'current_instruction_doc' => candidate[name],
+                  'dataset_with_feedback' => reflective_dataset.fetch(name, [])
+                }
+              )
+              [name, response.fetch('new_instruction')]
+            end
+          else
+            components_to_update.to_h do |name|
+              [name, "#{candidate[name]} improved"]
+            end
+          end
+        end
+
+        private
+
+        sig { params(program: DSPy::Module).returns(T::Array[[String, DSPy::Module]]) }
+        def resolve_predictors(program)
+          pairs = program.named_predictors
+          pairs = [['self', program]] if pairs.empty?
+          pairs
+        end
+
+        sig { params(mod: DSPy::Module).returns(DSPy::Module) }
+        def clone_module(mod)
+          safe_clone(mod)
+        end
+
+        sig { params(program: DSPy::Module).void }
+        def duplicate_predictors!(program)
+          resolve_predictors(program).each do |name, predictor|
+            next unless @predictor_names.include?(name)
+            next if predictor.equal?(program)
+            clone = safe_clone(predictor)
+            InstructionUpdates.replace_reference(program, predictor, clone)
+          end
+        end
+
+        sig { params(program: DSPy::Module, recorder: T.nilable(T.untyped)).void }
+        def wrap_predictors_for_tracing!(program, recorder: nil)
+          return unless recorder
+
+          resolve_predictors(program).each do |name, predictor|
+            wrap_predictor_for_tracing(program, predictor, name, recorder)
+          end
+        end
+
+        sig { params(program: DSPy::Module, predictor: DSPy::Module, name: String, recorder: T.untyped).void }
+        def wrap_predictor_for_tracing(program, predictor, name, recorder)
+          original_forward = predictor.method(:forward_untyped)
+          recorder_ref = recorder
+          predictor_name = name
+
+          predictor.define_singleton_method(:forward_untyped) do |**input_values|
+            result = original_forward.call(**input_values)
+            recorder_ref.record(
+              predictor_name: predictor_name,
+              inputs: input_values.dup,
+              output: result
+            )
+            result
+          end
+        end
+
+        # instruction update helpers handled by InstructionUpdates
+
+        sig { params(object: T.untyped).returns(T.untyped) }
+        def safe_clone(object)
+          object.clone
+        rescue TypeError
+          object.dup
+        end
+
+        class TraceRecorder
+          def initialize
+            @current_trace = nil
+          end
+
+          def start_example
+            @current_trace = []
+          end
+
+          def record(entry)
+            return unless @current_trace
+            @current_trace << entry
+          end
+
+          def finish_example
+            trace = @current_trace || []
+            @current_trace = nil
+            trace
+          end
+        end
+
+        sig { params(program: DSPy::Module).returns(String) }
+        def extract_instruction(program)
+          if program.respond_to?(:prompt) && program.prompt.respond_to?(:instruction)
+            program.prompt.instruction
+          elsif program.respond_to?(:instruction)
+            program.instruction
+          else
+            raise ArgumentError, "Program must expose prompt.instruction or #instruction"
+          end
+        end
+
+        sig { params(struct: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+        def serialize_struct(struct)
+          if struct.respond_to?(:to_h)
+            struct.to_h
+          elsif struct.instance_variables.any?
+            struct.instance_variables.each_with_object({}) do |ivar, memo|
+              key = ivar.to_s.delete_prefix('@').to_sym
+              memo[key] = struct.instance_variable_get(ivar)
+            end
+          else
+            {}
+          end
+        end
+
+        sig { params(prediction: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+        def serialize_prediction(prediction)
+          case prediction
+          when DSPy::Prediction
+            prediction.to_h
+          when Hash
+            prediction
+          else
+            serialize_struct(prediction)
+          end
+        end
+
+        sig { params(expected: T::Hash[Symbol, T.untyped], actual: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+        def build_diff(expected, actual)
+          keys = expected.keys | actual.keys
+          keys.each_with_object({}) do |key, memo|
+            exp = expected[key]
+            act = actual[key]
+            next if exp == act
+
+            memo[key] = { expected: exp, actual: act }
+          end
+        end
+
+        sig { params(result: T.untyped).returns([Float, T.nilable(String)]) }
+        def extract_score_and_feedback(result)
+          case result
+          when DSPy::Prediction
+            score = result.respond_to?(:score) ? result.score : 0.0
+            feedback = result.respond_to?(:feedback) ? result.feedback : nil
+            [score.to_f, feedback]
+          when Hash
+            [result[:score].to_f, result[:feedback]]
+          else
+            [result.to_f, nil]
+          end
+        end
+      end
+
+      sig do
+        params(
+          metric: T.proc.params(arg0: DSPy::Example, arg1: T.untyped).returns(T.untyped),
+          reflection_lm: T.nilable(T.untyped),
+          feedback_map: T.nilable(T::Hash[String, PredictAdapter::FeedbackFnType]),
+          adapter_builder: T.nilable(T.proc.returns(T.untyped)),
+          config: T.nilable(T::Hash[Symbol, T.untyped]),
+          experiment_tracker: T.nilable(T.untyped)
+        ).void
+      end
+      def initialize(metric:, reflection_lm: nil, feedback_map: nil, adapter_builder: nil, config: nil, experiment_tracker: nil)
+        super(metric: metric)
+        @metric = metric
+        @reflection_lm = reflection_lm
+        @feedback_map = (feedback_map || {}).transform_keys(&:to_s)
+        @adapter_builder = adapter_builder || method(:build_adapter)
+        @gepa_config = self.class.default_config.merge(config || {})
+        @experiment_tracker = experiment_tracker
+      end
+
+      sig do
+        override.params(
+          program: DSPy::Module,
+          trainset: T::Array[T.untyped],
+          valset: T.nilable(T::Array[T.untyped])
+        ).returns(OptimizationResult)
+      end
+      def compile(program, trainset:, valset: nil)
+        validate_inputs(program, trainset, valset)
+
+        typed_trainset = ensure_typed_examples(trainset)
+        typed_valset = valset ? ensure_typed_examples(valset) : typed_trainset
+
+        adapter = @adapter_builder.call(
+          program,
+          @metric,
+          reflection_lm: @reflection_lm,
+          feedback_map: @feedback_map
+        )
+        seed_candidate = adapter.seed_candidate
+
+        cand_selector = ::GEPA::Strategies::ParetoCandidateSelector.new
+        comp_selector = ::GEPA::Strategies::RoundRobinReflectionComponentSelector.new
+        batch_sampler = ::GEPA::Strategies::EpochShuffledBatchSampler.new([@gepa_config[:minibatch_size], typed_trainset.size].min)
+
+        telemetry_context = ::GEPA::Telemetry.build_context
+
+        logger = ::GEPA::Logging::BufferingLogger.new
+        tracker = @experiment_tracker || ::GEPA::Logging::ExperimentTracker.new
+
+        reflective = ::GEPA::Proposer::ReflectiveMutationProposer.new(
+          logger: logger,
+          trainset: typed_trainset,
+          adapter: adapter,
+          candidate_selector: cand_selector,
+          module_selector: comp_selector,
+          batch_sampler: batch_sampler,
+          perfect_score: @gepa_config[:perfect_score],
+          skip_perfect_score: @gepa_config[:skip_perfect_score],
+          experiment_tracker: tracker,
+          reflection_lm: nil,
+          telemetry: telemetry_context
+        )
+
+        evaluator = lambda do |dataset, candidate|
+          batch = adapter.evaluate(dataset, candidate, capture_traces: false)
+          [batch.outputs, batch.scores]
+        end
+
+        merge_proposer = nil
+        if @gepa_config[:use_merge]
+          merge_proposer = ::GEPA::Proposer::MergeProposer.new(
+            logger: logger,
+            valset: typed_valset,
+            evaluator: evaluator,
+            use_merge: true,
+            max_merge_invocations: @gepa_config[:max_merge_invocations],
+            rng: Random.new(0),
+            telemetry: telemetry_context
+          )
+        end
+
+        engine = ::GEPA::Core::Engine.new(
+          evaluator: evaluator,
+          valset: typed_valset,
+          seed_candidate: seed_candidate,
+          max_metric_calls: @gepa_config[:max_metric_calls],
+          perfect_score: @gepa_config[:perfect_score],
+          seed: 0,
+          reflective_proposer: reflective,
+          logger: logger,
+          experiment_tracker: tracker,
+          merge_proposer: merge_proposer,
+          run_dir: nil,
+          track_best_outputs: false,
+          display_progress_bar: false,
+          telemetry: telemetry_context,
+          raise_on_exception: true
+        )
+
+        state = engine.run
+        result = ::GEPA::Core::Result.from_state(state)
+        best_program = adapter.build_program(result.best_candidate)
+
+        OptimizationResult.new(
+          optimized_program: best_program,
+          scores: { best: result.val_aggregate_scores[result.best_idx] },
+          history: { total_candidates: result.num_candidates },
+          best_score_name: 'best',
+          best_score_value: result.val_aggregate_scores[result.best_idx],
+          metadata: { candidates: result.num_candidates }
+        )
+      end
+
+      private
+
+      sig do
+        params(
+          program: DSPy::Module,
+          metric: T.proc.params(arg0: DSPy::Example, arg1: T.untyped).returns(T.untyped),
+          reflection_lm: T.nilable(T.untyped),
+          feedback_map: T::Hash[String, PredictAdapter::FeedbackFnType]
+        ).returns(PredictAdapter)
+      end
+      def build_adapter(program, metric, reflection_lm: nil, feedback_map: {})
+        PredictAdapter.new(program, metric, reflection_lm: reflection_lm, feedback_map: feedback_map)
+      end
+    end
+  end
+end

data/lib/dspy/gepa/version.rb

@@ -0,0 +1,10 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../version'
+
+module DSPy
+  module GEPA
+    VERSION = '1.0.0'
+  end
+end

data/lib/dspy/gepa.rb

@@ -0,0 +1,5 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'gepa/version'
+require_relative 'gepa/teleprompt'

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: dspy-gepa
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Vicente Reig Rincón de Arellano
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dspy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+- !ruby/object:Gem::Dependency
+  name: gepa
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+description: Ships DSPy::Teleprompt::GEPA plus reflective adapters, experiment tracking,
+  and telemetry hooks built on top of the GEPA optimizer core gem.
+email:
+- hey@vicente.services
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dspy/gepa.rb
+- lib/dspy/gepa/teleprompt.rb
+- lib/dspy/gepa/version.rb
+homepage: https://github.com/vicentereig/dspy.rb
+licenses:
+- MIT
+metadata:
+  github_repo: git@github.com:vicentereig/dspy.rb
+post_install_message: 
+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.0.3.1
+signing_key: 
+specification_version: 4
+summary: GEPA teleprompter integration for DSPy.rb.
+test_files: []