Module: DSPy

Extended by:
Dry::Configurable
Defined in:
lib/dspy/prediction.rb,
lib/dspy.rb,
lib/dspy/lm.rb,
lib/dspy/evals.rb,
lib/dspy/field.rb,
lib/dspy/image.rb,
lib/dspy/tools.rb,
lib/dspy/errors.rb,
lib/dspy/events.rb,
lib/dspy/memory.rb,
lib/dspy/module.rb,
lib/dspy/prompt.rb,
lib/dspy/re_act.rb,
lib/dspy/context.rb,
lib/dspy/example.rb,
lib/dspy/predict.rb,
lib/dspy/version.rb,
lib/dspy/lm/usage.rb,
lib/dspy/callbacks.rb,
lib/dspy/lm/errors.rb,
lib/dspy/signature.rb,
lib/dspy/lm/adapter.rb,
lib/dspy/lm/message.rb,
lib/dspy/tools/base.rb,
lib/dspy/lm/response.rb,
lib/dspy/events/types.rb,
lib/dspy/evals/version.rb,
lib/dspy/reflection_lm.rb,
lib/dspy/tools/toolset.rb,
lib/dspy/schema/version.rb,
lib/dspy/error_formatter.rb,
lib/dspy/schema_adapters.rb,
lib/dspy/type_serializer.rb,
lib/dspy/chain_of_thought.rb,
lib/dspy/few_shot_example.rb,
lib/dspy/lm/chat_strategy.rb,
lib/dspy/lm/json_strategy.rb,
lib/dspy/lm/vision_models.rb,
lib/dspy/ruby_llm/version.rb,
lib/dspy/teleprompt/utils.rb,
lib/dspy/events/subscribers.rb,
lib/dspy/lm/adapter_factory.rb,
lib/dspy/lm/message_builder.rb,
lib/dspy/memory/memory_store.rb,
lib/dspy/ruby_llm/guardrails.rb,
lib/dspy/utils/serialization.rb,
lib/dspy/memory/memory_record.rb,
lib/dspy/mixins/type_coercion.rb,
lib/dspy/tools/memory_toolset.rb,
lib/dspy/memory/memory_manager.rb,
lib/dspy/mixins/struct_builder.rb,
lib/dspy/memory/in_memory_store.rb,
lib/dspy/events/subscriber_mixin.rb,
lib/dspy/memory/embedding_engine.rb,
lib/dspy/memory/memory_compactor.rb,
lib/dspy/storage/program_storage.rb,
lib/dspy/storage/storage_manager.rb,
lib/dspy/support/warning_filters.rb,
lib/dspy/teleprompt/data_handler.rb,
lib/dspy/teleprompt/teleprompter.rb,
lib/dspy/tools/github_cli_toolset.rb,
lib/dspy/propose/grounded_proposer.rb,
lib/dspy/registry/registry_manager.rb,
lib/dspy/schema/sorbet_json_schema.rb,
lib/dspy/structured_outputs_prompt.rb,
lib/dspy/schema/sorbet_toon_adapter.rb,
lib/dspy/registry/signature_registry.rb,
lib/dspy/mixins/instruction_updatable.rb,
lib/dspy/memory/local_embedding_engine.rb,
lib/dspy/teleprompt/bootstrap_strategy.rb,
lib/dspy/tools/text_processing_toolset.rb,
lib/dspy/teleprompt/instruction_updates.rb,
lib/dspy/propose/dataset_summary_generator.rb,
lib/dspy/ruby_llm/lm/adapters/ruby_llm_adapter.rb

Overview

typed: strict frozen_string_literal: true

Defined Under Namespace

Modules: Callbacks, Events, Memory, Metrics, Mixins, Propose, Registry, RubyLLM, Schema, SchemaAdapters, Storage, Support, Teleprompt, Tools, TypeSystem, Utils Classes: ChainOfThought, ConfigurationError, Context, DeserializationError, Error, ErrorFormatter, Evals, EventRegistry, Example, FewShotExample, HistoryEntry, Image, InputField, InstructionUpdateError, LM, Module, NextStep, OutputField, Predict, Prediction, PredictionInvalidError, Prompt, ReAct, ReActObservationBase, ReflectionLM, Signature, StructuredOutputsPrompt, ThoughtBase, TypeSerializer, UnsupportedSchemaError, ValidationError

Constant Summary collapse

VERSION = 
"0.32.0"

Class Method Summary collapse

Class Method Details

.create_event_span(event_name, attributes) ⇒ Object 



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/dspy.rb', line 129

def self.create_event_span(event_name, attributes)
  return unless DSPy::Observability.enabled?
  return if INTERNAL_EVENTS.include?(event_name)

  begin
    # Flatten nested hashes for OpenTelemetry span attributes
    flattened_attributes = flatten_attributes(attributes)

    # Create and immediately finish a span for this event
    # Events are instant moments in time, not ongoing operations
    span = DSPy::Observability.start_span(event_name, flattened_attributes)
    DSPy::Observability.finish_span(span) if span
  rescue => e
    # Log error but don't let it break the event system
    # Use emit_log directly to avoid infinite recursion
    emit_log('event.span_creation_error', {
      error_class: e.class.name,
      error_message: e.message,
      event_name: event_name
    })
  end
end

.create_logger ⇒ Object 



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/dspy.rb', line 166

def self.create_logger
  env = ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'development'
  log_output = ENV['DSPY_LOG'] # Allow override

  case env
  when 'test'
    # Test: key=value format to log/test.log (or override)
    Dry.Logger(:dspy, formatter: :string) do |config|
      config.add_backend(stream: log_output || "log/test.log")
    end
  when 'development'
    # Development: key=value format to log/development.log (or override)
    Dry.Logger(:dspy, formatter: :string) do |config|
      config.add_backend(stream: log_output || "log/development.log")
    end
  when 'production', 'staging'
    # Production: JSON to STDOUT (or override)
    Dry.Logger(:dspy, formatter: :json) do |config|
      config.add_backend(stream: log_output || $stdout)
    end
  else
    # Fallback: key=value to STDOUT
    Dry.Logger(:dspy, formatter: :string) do |config|
      config.add_backend(stream: log_output || $stdout)
    end
  end
end

.current_lm ⇒ Object 



197
198
199
 
# File 'lib/dspy.rb', line 197

def self.current_lm
  Fiber[FIBER_LM_KEY] || config.lm
end

.emit_log(event_name, attributes) ⇒ Object 



101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/dspy.rb', line 101

def self.emit_log(event_name, attributes)
  return unless logger

  # Merge context automatically (but don't include span_stack)
  context = Context.current.dup
  context.delete(:span_stack)
  context.delete(:otel_span_stack)
  context.delete(:module_stack)
  attributes = context.merge(attributes)
  attributes[:event] = event_name

  # Use Dry::Logger's structured logging
  logger.info(attributes)
end

.event(event_name_or_object, attributes = {}) ⇒ Object

Emits a structured event that flows through DSPy’s event bus, fires any subscribed listeners, and creates OpenTelemetry spans when observability is enabled. Use this for anything that should be tracked, instrumented, or forwarded to Langfuse.



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/dspy.rb', line 52

def self.event(event_name_or_object, attributes = {})
  # Handle typed event objects
  if event_name_or_object.respond_to?(:name) && event_name_or_object.respond_to?(:to_attributes)
    event_obj = event_name_or_object
    event_name = event_obj.name
    attributes = event_obj.to_attributes

    # For LLM events, use OpenTelemetry semantic conventions for spans
    if event_obj.is_a?(DSPy::Events::LLMEvent)
      otel_attributes = event_obj.to_otel_attributes
      create_event_span(event_name, otel_attributes)
    else
      create_event_span(event_name, attributes)
    end
  else
    # Handle string event names (backward compatibility)
    event_name = event_name_or_object
    raise ArgumentError, "Event name cannot be nil" if event_name.nil?

    # Handle nil attributes
    attributes = {} if attributes.nil?

    # Create OpenTelemetry span for the event if observability is enabled
    create_event_span(event_name, attributes)
  end

  attributes = attributes.dup
  module_metadata = DSPy::Context.module_context_attributes
  attributes.merge!(module_metadata) unless module_metadata.empty?

  # Perform the actual logging (original DSPy.log behavior)
  # emit_log(event_name, attributes)

  # Notify event listeners
  events.notify(event_name, attributes)
end

.events ⇒ Object 



89
90
91
92
93
94
95
96
97
 
# File 'lib/dspy.rb', line 89

def self.events
  @event_registry ||= DSPy::EventRegistry.new.tap do |registry|
    # Subscribe logger to all events - use a proc that calls logger each time
    # to support mocking in tests
    registry.subscribe('*') { |event_name, attributes| 
      emit_log(event_name, attributes) if logger
    }
  end
end

.flatten_attributes(attributes, parent_key = '', result = {}) ⇒ Object 



152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/dspy.rb', line 152

def self.flatten_attributes(attributes, parent_key = '', result = {})
  attributes.each do |key, value|
    new_key = parent_key.empty? ? key.to_s : "#{parent_key}.#{key}"

    if value.is_a?(Hash)
      flatten_attributes(value, new_key, result)
    else
      result[new_key] = value
    end
  end

  result
end

.log(event_name, **attributes) ⇒ Object

Writes structured output to the configured logger. Use this for human-readable logs only—listeners and telemetry exporters are not triggered by ‘DSPy.log`. Prefer `DSPy.event` whenever you want consumers (or Langfuse/OpenTelemetry) to react to what happened.



37
38
39
40
41
42
43
44
45
46
 
# File 'lib/dspy.rb', line 37

def self.log(event_name, **attributes)
  # Return nil early if logger is not configured (backward compatibility)
  return nil unless logger

  # Direct logging - simple and straightforward
  emit_log(event_name, attributes)

  # Return nil to maintain backward compatibility
  nil
end

.logger ⇒ Object 



29
30
31
 
# File 'lib/dspy.rb', line 29

def self.logger
  @logger ||= create_logger
end

.with_lm(lm) ⇒ Object 



201
202
203
204
205
206
207
 
# File 'lib/dspy.rb', line 201

def self.with_lm(lm)
  previous_lm = Fiber[FIBER_LM_KEY]
  Fiber[FIBER_LM_KEY] = lm
  yield
ensure
  Fiber[FIBER_LM_KEY] = previous_lm
end