Class: DSPy::DeepResearch::Module

Inherits:
Module
  • Object
show all
Extended by:
T::Sig
Defined in:
lib/dspy/deep_research/module.rb

Defined Under Namespace

Classes: Result, SectionResult

Constant Summary collapse

SectionSpec = 
DSPy::DeepResearch::Signatures::BuildOutline::SectionSpec
ResearchMode = 
DSPy::DeepResearch::Signatures::BuildOutline::Mode
MODEL_ENV_KEYS = 
{
  planner: 'DSPY_DEEP_RESEARCH_PLANNER_MODEL',
  qa: 'DSPY_DEEP_RESEARCH_QA_MODEL',
  synthesizer: 'DSPY_DEEP_RESEARCH_SYNTH_MODEL',
  reporter: 'DSPY_DEEP_RESEARCH_REPORTER_MODEL'
}.freeze
MODEL_PRIORITY = 
{
  planner: [
    'gemini/gemini-2.5-pro',
    'openai/o4-mini',
    'anthropic/claude-4.1-opus'
  ],
  qa: [
    'gemini/gemini-2.5-pro',
    'openai/o4-mini',
    'anthropic/claude-4.1-opus'
  ],
  synthesizer: [
    'anthropic/claude-sonnet-4-5',
    'openai/gpt-4.1'
  ],
  reporter: [
    'anthropic/claude-sonnet-4-5',
    'openai/gpt-4.1'
  ]
}.freeze
MODE_CONFIG = 
T.let(
  {
    ResearchMode::Light => T.let(1, Integer),
    ResearchMode::Medium => T.let(3, Integer),
    ResearchMode::Hard => T.let(5, Integer),
    ResearchMode::Ultra => T.let(6, Integer)
  }.freeze,
  T::Hash[ResearchMode, Integer]
)
DEFAULT_MODE = 
ResearchMode::Medium

Instance Method Summary collapse

Constructor Details

#initialize(planner: DSPy::Predict.new(DSPy::DeepResearch::Signatures::BuildOutline), deep_search_factory: nil, synthesizer: DSPy::Predict.new(DSPy::DeepResearch::Signatures::SynthesizeSection), qa_reviewer: DSPy::Predict.new(DSPy::DeepResearch::Signatures::QAReview), reporter: DSPy::Predict.new(DSPy::DeepResearch::Signatures::AssembleReport), section_queue_factory: nil, max_section_attempts: 3) ⇒ Module

Returns a new instance of Module.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/dspy/deep_research/module.rb', line 88

def initialize(
  planner: DSPy::Predict.new(DSPy::DeepResearch::Signatures::BuildOutline),
  deep_search_factory: nil,
  synthesizer: DSPy::Predict.new(DSPy::DeepResearch::Signatures::SynthesizeSection),
  qa_reviewer: DSPy::Predict.new(DSPy::DeepResearch::Signatures::QAReview),
  reporter: DSPy::Predict.new(DSPy::DeepResearch::Signatures::AssembleReport),
  section_queue_factory: nil,
  max_section_attempts: 3
)
  super()

  @planner = planner
  @deep_search_factory = deep_search_factory || default_deep_search_factory
  @synthesizer = synthesizer
  @qa_reviewer = qa_reviewer
  @reporter = reporter
  @section_queue_factory = section_queue_factory || -> { DSPy::DeepResearch::SectionQueue.new }
  @max_section_attempts = max_section_attempts
  @deep_search_instruction = nil
  @deep_search_examples = []

  reset_state!
  configure_default_predictor_models
end

Instance Method Details

#forward_untyped(**input_values) ⇒ Object

Raises:



153
154
155
156
157
158
159
160
161
162
163
164
165
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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/dspy/deep_research/module.rb', line 153

def forward_untyped(**input_values)
  brief = input_values[:brief]
  unless brief.is_a?(String)
    raise ArgumentError, "DeepResearch expects keyword argument :brief"
  end

  mode = normalize_mode(input_values[:mode])

  reset_state!
  @current_mode = mode
  @current_mode_target_sections = mode_target_sections(mode)

  outline = @planner.call(brief: brief, mode: mode)
  sections = apply_mode_to_sections(outline.sections, @current_mode_target_sections)
  enqueue_sections(sections)

  while (section_spec = @section_queue.dequeue)
    attempts = @section_queue.attempts_for(section_spec)
    if attempts > @max_section_attempts
      raise DSPy::DeepResearch::QueueStarvationError,
            "Section #{section_spec.identifier} exceeded max attempts (#{attempts}/#{@max_section_attempts})"
    end

    emit_section_started(section_spec, attempts)

    deep_search_module = build_deep_search(section_spec)
    deep_result = deep_search_module.call(question: section_spec.prompt)
    @token_budget_exhausted ||= deep_result.budget_exhausted

    evidence = merge_section_evidence(section_spec, deep_result)

    synthesized = @synthesizer.call(
      brief: brief,
      section: section_spec,
      answer: deep_result.answer,
      notes: evidence[:notes],
      citations: evidence[:citations]
    )

    citations = Array(synthesized.citations || evidence[:citations]).compact.uniq
    warnings = section_warnings(evidence, deep_result)
    base_status = deep_result.budget_exhausted ? SectionResult::Status::Partial : SectionResult::Status::Complete

    qa_decision = @qa_reviewer.call(
      brief: brief,
      section: section_spec,
      draft: synthesized.draft,
      notes: evidence[:notes],
      citations: evidence[:citations],
      attempt: attempts
    )

    case qa_decision.status
    when DSPy::DeepResearch::Signatures::QAReview::Status::Approved
      section_result = build_section_result(section_spec, synthesized, citations, attempts, base_status, warnings)
      accept_section(section_result)
    when DSPy::DeepResearch::Signatures::QAReview::Status::NeedsMoreEvidence
      follow_up_prompt = qa_decision.follow_up_prompt

      if deep_result.budget_exhausted
        warnings << insufficient_evidence_warning(section_spec)
        section_result = build_section_result(
          section_spec,
          synthesized,
          citations,
          attempts,
          SectionResult::Status::InsufficientEvidence,
          warnings
        )
        accept_section(section_result)
        emit_section_insufficient(section_spec, attempts, warnings.last)
        next
      end

      if attempts >= @max_section_attempts
        raise DSPy::DeepResearch::EvidenceDeficitError,
              "QA requested more evidence for #{section_spec.title} beyond max attempts"
      end

      unless follow_up_prompt
        raise DSPy::DeepResearch::EvidenceDeficitError,
              "QA requested more evidence for #{section_spec.title} but no follow-up prompt provided"
      end

      emit_section_retry(section_spec, attempts, follow_up_prompt)

      follow_up = @section_queue.enqueue_follow_up(section_spec, prompt: follow_up_prompt)
      DSPy.event(
        "deep_research.section.requeued",
        identifier: section_spec.identifier,
        follow_up_identifier: follow_up.identifier,
        prompt: follow_up_prompt,
        attempt: follow_up.attempt
      )
    else
      raise DSPy::DeepResearch::SynthesisCoherenceError,
            "Unexpected QA status: #{qa_decision.status}"
    end
  end

  raise DSPy::DeepResearch::SynthesisCoherenceError, "No sections were approved" if @accepted_sections.empty?

  assembled = @reporter.call(
    brief: brief,
    sections: @accepted_sections.map do |section|
      DSPy::DeepResearch::Signatures::AssembleReport::SectionDraft.new(
        identifier: section.identifier,
        title: section.title,
        draft: section.draft,
        citations: section.citations
      )
    end
  )

  result = Result.new(
    report: assembled.report,
    sections: @accepted_sections.dup,
    citations: merged_citations(Array(assembled.citations)),
    warnings: @warnings.dup,
    budget_exhausted: @token_budget_exhausted
  )
  ensure_report_ready(assembled, brief)
  result
end

#named_predictors ⇒ Object 



114
115
116
117
118
119
120
121
 
# File 'lib/dspy/deep_research/module.rb', line 114

def named_predictors
  [
    ["planner", @planner],
    ["synthesizer", @synthesizer],
    ["qa_reviewer", @qa_reviewer],
    ["reporter", @reporter]
  ]
end

#predictors ⇒ Object 



124
125
126
 
# File 'lib/dspy/deep_research/module.rb', line 124

def predictors
  named_predictors.map { |(_, predictor)| predictor }
end

#with_examples(examples) ⇒ Object 



141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/dspy/deep_research/module.rb', line 141

def with_examples(examples)
  examples_copy = examples.map { |example| example }
  clone_with(
    planner: apply_examples(@planner, examples_copy),
    synthesizer: apply_examples(@synthesizer, examples_copy),
    qa_reviewer: apply_examples(@qa_reviewer, examples_copy),
    reporter: apply_examples(@reporter, examples_copy),
    deep_search_instruction: @deep_search_instruction,
    deep_search_examples: examples_copy
  )
end

#with_instruction(instruction) ⇒ Object 



129
130
131
132
133
134
135
136
137
138
 
# File 'lib/dspy/deep_research/module.rb', line 129

def with_instruction(instruction)
  clone_with(
    planner: apply_instruction(@planner, instruction),
    synthesizer: apply_instruction(@synthesizer, instruction),
    qa_reviewer: apply_instruction(@qa_reviewer, instruction),
    reporter: apply_instruction(@reporter, instruction),
    deep_search_instruction: instruction,
    deep_search_examples: @deep_search_examples.dup
  )
end