dspy-o11y 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9d96b5a425cbf761e71df7be01407396fee6dfc8f840861ff6d041f7aeaecab9
+  data.tar.gz: 139dcc9aff3e2e4a63e168c2d8d58ab6ce4f675b8de766585e4631d6a3bb475b
+SHA512:
+  metadata.gz: 976d74d47091190adf36bab23587219a3f83efbeeba41bf5dcc330737b0f91ddb96223425e17d251127d4ac2432c6f87e19fc86533b6576cb56d3ba5a537adf9
+  data.tar.gz: 975621400a7c677a44b499c741d7f2be65316f3ec91473c18d2ea8fda1291ba6b2b4e2c82178a24e854039df3ee56a70c611f353782f78382d0dd2b88d0a61e8

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`).
+### 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/o11y/async_span_processor.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+require 'thread'
+require 'opentelemetry/sdk'
+require 'opentelemetry/sdk/trace/export'
+
+module DSPy
+  class Observability
+    # AsyncSpanProcessor provides non-blocking span export using concurrent-ruby.
+    # Spans are queued and exported on a dedicated single-thread executor to avoid blocking clients.
+    # Implements the same interface as OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor
+    class AsyncSpanProcessor
+      # Default configuration values
+      DEFAULT_QUEUE_SIZE = 1000
+      DEFAULT_EXPORT_INTERVAL = 60.0  # seconds
+      DEFAULT_EXPORT_BATCH_SIZE = 100
+      DEFAULT_SHUTDOWN_TIMEOUT = 10.0  # seconds
+      DEFAULT_MAX_RETRIES = 3
+
+      def initialize(
+        exporter,
+        queue_size: DEFAULT_QUEUE_SIZE,
+        export_interval: DEFAULT_EXPORT_INTERVAL,
+        export_batch_size: DEFAULT_EXPORT_BATCH_SIZE,
+        shutdown_timeout: DEFAULT_SHUTDOWN_TIMEOUT,
+        max_retries: DEFAULT_MAX_RETRIES
+      )
+        @exporter = exporter
+        @queue_size = queue_size
+        @export_interval = export_interval
+        @export_batch_size = export_batch_size
+        @shutdown_timeout = shutdown_timeout
+        @max_retries = max_retries
+        @export_executor = Concurrent::SingleThreadExecutor.new
+
+        # Use thread-safe queue for cross-fiber communication
+        @queue = Thread::Queue.new
+        @shutdown_requested = false
+        @timer_thread = nil
+
+        start_export_task
+      end
+
+      def on_start(span, parent_context)
+        # Non-blocking - no operation needed on span start
+      end
+
+      def on_finish(span)
+        # Only process sampled spans to match BatchSpanProcessor behavior
+        return unless span.context.trace_flags.sampled?
+
+        # Non-blocking enqueue with overflow protection
+        # Note: on_finish is only called for already ended spans
+        begin
+          # Check queue size (non-blocking)
+          if @queue.size >= @queue_size
+            # Drop oldest span
+            begin
+              dropped_span = @queue.pop(true) # non-blocking pop
+              DSPy.log('observability.span_dropped',
+                       reason: 'queue_full',
+                       queue_size: @queue_size)
+            rescue ThreadError
+              # Queue was empty, continue
+            end
+          end
+
+          @queue.push(span)
+          
+          # Log span queuing activity
+          DSPy.log('observability.span_queued', queue_size: @queue.size)
+
+          # Trigger immediate export if batch size reached
+          trigger_export_if_batch_full
+        rescue => e
+          DSPy.log('observability.enqueue_error', error: e.message)
+        end
+      end
+
+      def shutdown(timeout: nil)
+        timeout ||= @shutdown_timeout
+        @shutdown_requested = true
+
+        begin
+          # Export any remaining spans
+          result = export_remaining_spans(timeout: timeout, export_all: true)
+
+          future = Concurrent::Promises.future_on(@export_executor) do
+            @exporter.shutdown(timeout: timeout)
+          end
+          future.value!(timeout)
+
+          result
+        rescue => e
+          DSPy.log('observability.shutdown_error', error: e.message, class: e.class.name)
+          OpenTelemetry::SDK::Trace::Export::FAILURE
+        ensure
+          begin
+            @timer_thread&.join(timeout)
+            @timer_thread&.kill if @timer_thread&.alive?
+          rescue StandardError
+            # ignore timer shutdown issues
+          end
+          @export_executor.shutdown
+          unless @export_executor.wait_for_termination(timeout)
+            @export_executor.kill
+          end
+        end
+      end
+
+      def force_flush(timeout: nil)
+        return OpenTelemetry::SDK::Trace::Export::SUCCESS if @queue.empty?
+
+        export_remaining_spans(timeout: timeout, export_all: true)
+      end
+
+      private
+
+      def start_export_task
+        return if @export_interval <= 0 # Disable timer for testing
+        return if ENV['DSPY_DISABLE_OBSERVABILITY'] == 'true' # Skip in tests
+
+        @timer_thread = Thread.new do
+          loop do
+            break if @shutdown_requested
+
+            sleep(@export_interval)
+            break if @shutdown_requested
+            next if @queue.empty?
+
+            schedule_async_export(export_all: true)
+          end
+        rescue => e
+          DSPy.log('observability.export_task_error', error: e.message, class: e.class.name)
+        end
+      end
+
+      def trigger_export_if_batch_full
+        return if @queue.size < @export_batch_size
+        return if ENV['DSPY_DISABLE_OBSERVABILITY'] == 'true' # Skip in tests
+        schedule_async_export(export_all: false)
+      end
+
+      def export_remaining_spans(timeout: nil, export_all: true)
+        return OpenTelemetry::SDK::Trace::Export::SUCCESS if @queue.empty?
+
+        future = Concurrent::Promises.future_on(@export_executor) do
+          export_queued_spans_internal(export_all: export_all)
+        end
+
+        future.value!(timeout || @shutdown_timeout)
+      rescue => e
+        DSPy.log('observability.export_error', error: e.message, class: e.class.name)
+        OpenTelemetry::SDK::Trace::Export::FAILURE
+      end
+
+      def schedule_async_export(export_all: false)
+        return if @shutdown_requested
+
+        @export_executor.post do
+          export_queued_spans_internal(export_all: export_all)
+        rescue => e
+          DSPy.log('observability.batch_export_error', error: e.message, class: e.class.name)
+        end
+      end
+
+      def export_queued_spans
+        export_queued_spans_internal(export_all: false)
+      end
+
+      def export_queued_spans_internal(export_all: false)
+        result = OpenTelemetry::SDK::Trace::Export::SUCCESS
+
+        loop do
+          spans = dequeue_spans(export_all ? @queue_size : @export_batch_size)
+          break if spans.empty?
+
+          result = export_spans_with_retry(spans)
+          break if result == OpenTelemetry::SDK::Trace::Export::FAILURE
+
+          break unless export_all || @queue.size >= @export_batch_size
+        end
+
+        result
+      end
+
+      def dequeue_spans(limit)
+        spans = []
+
+        limit.times do
+          begin
+            spans << @queue.pop(true) # non-blocking pop
+          rescue ThreadError
+            break
+          end
+        end
+
+        spans
+      end
+
+      def export_spans_with_retry(spans)
+        retries = 0
+
+        # Convert spans to SpanData objects (required by OTLP exporter)
+        span_data_batch = spans.map(&:to_span_data)
+        
+        # Log export attempt
+        DSPy.log('observability.export_attempt',
+                 spans_count: span_data_batch.size,
+                 batch_size: span_data_batch.size)
+
+        loop do
+          result = @exporter.export(span_data_batch, timeout: @shutdown_timeout)
+
+          case result
+          when OpenTelemetry::SDK::Trace::Export::SUCCESS
+            DSPy.log('observability.export_success',
+                     spans_count: span_data_batch.size,
+                     export_result: 'SUCCESS')
+            return result
+          when OpenTelemetry::SDK::Trace::Export::FAILURE
+            retries += 1
+            if retries <= @max_retries
+              backoff_seconds = 0.1 * (2 ** retries)
+              DSPy.log('observability.export_retry',
+                       attempt: retries,
+                       spans_count: span_data_batch.size,
+                       backoff_seconds: backoff_seconds)
+              # Exponential backoff
+              sleep(backoff_seconds)
+              next
+            else
+              DSPy.log('observability.export_failed',
+                       spans_count: span_data_batch.size,
+                       retries: retries)
+              return result
+            end
+          else
+            return result
+          end
+        end
+      rescue => e
+        DSPy.log('observability.export_error', error: e.message, class: e.class.name)
+        OpenTelemetry::SDK::Trace::Export::FAILURE
+      end
+
+    end
+  end
+end

data/lib/dspy/o11y/langfuse/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DSPy
+  module O11y
+    module Langfuse
+      VERSION = '1.0.0'
+    end
+  end
+end

data/lib/dspy/o11y/langfuse.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'net/http'
+require 'openssl'
+require 'dspy/o11y'
+require_relative 'langfuse/version'
+
+module DSPy
+  class Observability
+    module Adapters
+      module Langfuse
+        module_function
+
+        def register!
+          DSPy::Observability.register_configurator(:langfuse) do |obs|
+            configure(obs)
+          end
+        end
+
+        def configure(obs)
+          return obs.disable!(reason: 'Explicitly disabled via DSPY_DISABLE_OBSERVABILITY') if ENV['DSPY_DISABLE_OBSERVABILITY'] == 'true'
+
+          public_key = ENV['LANGFUSE_PUBLIC_KEY']
+          secret_key = ENV['LANGFUSE_SECRET_KEY']
+
+          if test_environment? && !(public_key && secret_key)
+            return obs.disable!(reason: 'Test environment detected - OTLP disabled')
+          end
+
+          return false unless public_key && secret_key
+
+          require_opentelemetry!
+          patch_frozen_ssl_context_for_otlp!
+
+          endpoint = langfuse_endpoint
+          auth_string = Base64.strict_encode64("#{public_key}:#{secret_key}")
+
+          OpenTelemetry::SDK.configure do |config|
+            config.service_name = 'dspy-ruby'
+            config.service_version = DSPy::VERSION
+
+            exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
+              endpoint: endpoint,
+              headers: {
+                'Authorization' => "Basic #{auth_string}",
+                'Content-Type' => 'application/x-protobuf'
+              },
+              compression: 'gzip'
+            )
+
+            async_config = {
+              queue_size: (ENV['DSPY_TELEMETRY_QUEUE_SIZE'] || DSPy::Observability::AsyncSpanProcessor::DEFAULT_QUEUE_SIZE).to_i,
+              export_interval: (ENV['DSPY_TELEMETRY_EXPORT_INTERVAL'] || DSPy::Observability::AsyncSpanProcessor::DEFAULT_EXPORT_INTERVAL).to_f,
+              export_batch_size: (ENV['DSPY_TELEMETRY_BATCH_SIZE'] || DSPy::Observability::AsyncSpanProcessor::DEFAULT_EXPORT_BATCH_SIZE).to_i,
+              shutdown_timeout: (ENV['DSPY_TELEMETRY_SHUTDOWN_TIMEOUT'] || DSPy::Observability::AsyncSpanProcessor::DEFAULT_SHUTDOWN_TIMEOUT).to_f
+            }
+
+            config.add_span_processor(
+              DSPy::Observability::AsyncSpanProcessor.new(exporter, **async_config)
+            )
+
+            config.resource = OpenTelemetry::SDK::Resources::Resource.create({
+              'service.name' => 'dspy-ruby',
+              'service.version' => DSPy::VERSION,
+              'telemetry.sdk.name' => 'opentelemetry',
+              'telemetry.sdk.language' => 'ruby'
+            })
+          end
+
+          tracer = OpenTelemetry.tracer_provider.tracer('dspy', DSPy::VERSION)
+          obs.enable!(tracer: tracer, endpoint: endpoint)
+          true
+        rescue LoadError
+          obs.disable!(reason: 'OpenTelemetry gems not available')
+          false
+        rescue StandardError => e
+          DSPy.log('observability.error', error: e.message, adapter: 'langfuse', class: e.class.name)
+          obs.disable!
+          false
+        end
+
+        def test_environment?
+          ENV['RACK_ENV'] == 'test' || ENV['RAILS_ENV'] == 'test' || defined?(RSpec)
+        end
+        private_class_method :test_environment?
+
+        def require_opentelemetry!
+          DSPy::Observability.require_dependency('opentelemetry/sdk')
+          DSPy::Observability.require_dependency('opentelemetry/exporter/otlp')
+        end
+        private_class_method :require_opentelemetry!
+
+        def langfuse_endpoint
+          host = ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+          "#{host}/api/public/otel/v1/traces"
+        end
+        private_class_method :langfuse_endpoint
+
+        def patch_frozen_ssl_context_for_otlp!
+          return unless defined?(OpenTelemetry::Exporter::OTLP::Exporter)
+
+          exporter = OpenTelemetry::Exporter::OTLP::Exporter
+          keep_alive_timeout = exporter.const_get(:KEEP_ALIVE_TIMEOUT)
+          return if exporter.instance_variable_defined?(:@_dspy_ssl_patch_applied)
+
+          exporter.class_eval do
+            define_method(:http_connection) do |uri, ssl_verify_mode, certificate_file, client_certificate_file, client_key_file|
+              http = Net::HTTP.new(uri.host, uri.port)
+              use_ssl = uri.scheme == 'https'
+              http.use_ssl = use_ssl
+
+              if use_ssl && http.respond_to?(:ssl_context) && http.ssl_context&.frozen?
+                http.instance_variable_set(:@ssl_context, OpenSSL::SSL::SSLContext.new)
+              end
+
+              http.verify_mode = ssl_verify_mode
+              http.ca_file = certificate_file unless certificate_file.nil?
+              http.cert = OpenSSL::X509::Certificate.new(File.read(client_certificate_file)) unless client_certificate_file.nil?
+              http.key = OpenSSL::PKey::RSA.new(File.read(client_key_file)) unless client_key_file.nil?
+              http.keep_alive_timeout = keep_alive_timeout
+              http
+            end
+          end
+
+          exporter.instance_variable_set(:@_dspy_ssl_patch_applied, true)
+        end
+        private_class_method :patch_frozen_ssl_context_for_otlp!
+      end
+    end
+  end
+end
+
+DSPy::Observability::Adapters::Langfuse.register!

data/lib/dspy/o11y/observability.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module DSPy
+  class Observability
+    class << self
+      attr_reader :tracer, :endpoint
+
+      def register_configurator(name, &block)
+        configurators[name.to_sym] = block
+      end
+
+      def configure!(adapter: nil)
+        reset!
+
+        blocks = if adapter
+          block = configurators[adapter.to_sym]
+          block ? [block] : []
+        else
+          configurators.values
+        end
+
+        return false if blocks.empty?
+
+        blocks.each do |config|
+          begin
+            result = config.call(self)
+            return true if result || enabled?
+          rescue StandardError => e
+            DSPy.log('observability.error', error: e.message, adapter: adapter)
+          end
+        end
+
+        false
+      end
+
+      def enabled?
+        @enabled == true
+      end
+
+      def enable!(tracer:, endpoint: nil)
+        @tracer = tracer
+        @endpoint = endpoint
+        @enabled = true
+      end
+
+      def disable!(reason: nil)
+        @enabled = false
+        @tracer = nil
+        @endpoint = nil
+        DSPy.log('observability.disabled', reason: reason) if reason
+      end
+
+      def start_span(operation_name, attributes = {})
+        return nil unless enabled? && tracer
+
+        string_attributes = attributes.transform_keys(&:to_s)
+                                     .reject { |_, v| v.nil? }
+        string_attributes['operation.name'] = operation_name
+
+        tracer.start_span(
+          operation_name,
+          kind: :internal,
+          attributes: string_attributes
+        )
+      rescue StandardError => e
+        DSPy.log('observability.span_error', error: e.message, operation: operation_name)
+        nil
+      end
+
+      def finish_span(span)
+        return unless span
+
+        span.finish
+      rescue StandardError => e
+        DSPy.log('observability.span_finish_error', error: e.message)
+      end
+
+      def flush!
+        return unless enabled?
+        return unless defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:tracer_provider)
+
+        OpenTelemetry.tracer_provider.force_flush
+      rescue StandardError => e
+        DSPy.log('observability.flush_error', error: e.message)
+      end
+
+      def reset!
+        if defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:tracer_provider) && (provider = OpenTelemetry.tracer_provider)
+          begin
+            provider.shutdown(timeout: 1.0) if provider.respond_to?(:shutdown)
+          rescue StandardError => e
+            DSPy.log('observability.shutdown_error', error: e.message)
+          end
+        end
+
+        @enabled = false
+        @tracer = nil
+        @endpoint = nil
+      end
+
+      def configurators
+        @configurators ||= {}
+      end
+
+      def require_dependency(lib)
+        require lib
+      end
+    end
+  end
+end

data/lib/dspy/o11y/observation_type.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  # Langfuse observation types as a T::Enum for type safety
+  # Maps to the official Langfuse observation types: https://langfuse.com/docs/observability/features/observation-types
+  class ObservationType < T::Enum
+    enums do
+      # LLM generation calls - used for direct model inference
+      Generation = new('generation')
+      
+      # Agent operations - decision-making processes using tools/LLM guidance
+      Agent = new('agent')
+      
+      # External tool calls (APIs, functions, etc.)
+      Tool = new('tool')
+      
+      # Chains linking different application steps/components
+      Chain = new('chain')
+      
+      # Data retrieval operations (vector stores, databases, memory search)
+      Retriever = new('retriever')
+      
+      # Embedding generation calls
+      Embedding = new('embedding')
+      
+      # Functions that assess quality/relevance of outputs
+      Evaluator = new('evaluator')
+      
+      # Generic spans for durations of work units
+      Span = new('span')
+      
+      # Discrete events/moments in time
+      Event = new('event')
+    end
+
+    # Get the appropriate observation type for a DSPy module class
+    sig { params(module_class: T.untyped).returns(ObservationType) }
+    def self.for_module_class(module_class)
+      case module_class.name
+      when /ReAct/, /CodeAct/
+        Agent
+      when /ChainOfThought/
+        Chain
+      when /Evaluator/
+        Evaluator
+      else
+        Span
+      end
+    end
+
+    # Returns the langfuse attribute key and value as an array
+    sig { returns([String, String]) }
+    def langfuse_attribute
+      ['langfuse.observation.type', serialize]
+    end
+
+    # Returns a hash with the langfuse attribute for easy merging
+    sig { returns(T::Hash[String, String]) }
+    def langfuse_attributes
+      { 'langfuse.observation.type' => serialize }
+    end
+  end
+end

data/lib/dspy/o11y/version.rb

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

data/lib/dspy/o11y.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'o11y/version'
+require_relative 'o11y/observability'
+require_relative 'o11y/observation_type'
+require_relative 'o11y/async_span_processor'

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: dspy-o11y
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Vicente Reig Rincón de Arellano
+bindir: bin
+cert_chain: []
+date: 2025-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dspy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.29.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.29.1
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: Provides DSPy::Observability, AsyncSpanProcessor, and ObservationType
+  so instrumentation can be enabled independently from the main DSPy gem.
+email:
+- hey@vicente.services
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dspy/o11y.rb
+- lib/dspy/o11y/async_span_processor.rb
+- lib/dspy/o11y/langfuse.rb
+- lib/dspy/o11y/langfuse/version.rb
+- lib/dspy/o11y/observability.rb
+- lib/dspy/o11y/observation_type.rb
+- lib/dspy/o11y/version.rb
+homepage: https://github.com/vicentereig/dspy.rb
+licenses:
+- MIT
+metadata:
+  github_repo: git@github.com:vicentereig/dspy.rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.5
+specification_version: 4
+summary: Observability core (spans, context hooks, and telemetry helpers) for DSPy.rb.
+test_files: []