dspy-deep_search 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e560a465f74100b46c31a029666764a5c3ba5bc7916813dff0502ac9486c673
+  data.tar.gz: a6c488d9c459347ec6b6f34d809b70ca8c59188f835b96c62d1e9fa067e03972
+SHA512:
+  metadata.gz: 4a9329395aefefe5db74191efbf9cee68a4a25266617403b8f9629898b8093ef3251eea470ac1bab55d9787db407c2981abbb7410eff90b4b8b8c05d3fa937ef
+  data.tar.gz: 24c77161c79f28bc8bdf99e4555f3a075466df16f2b533288dfd6634d4a37e08281057e27bd2084fafe5965b09e49e204e10eb2d19689fbbd1965641753642c0

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,313 @@
+# 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
+```
+
+### 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
+```
+
+### Sibling Gems
+
+DSPy.rb ships multiple gems from this monorepo so you can opt into features with heavier dependency trees (e.g., datasets pull in Polars/Arrow, MIPROv2 requires `numo-*` BLAS bindings) only when you need them. Add these alongside `dspy`:
+
+| Gem | Description | Status |
+| --- | --- | --- |
+| `dspy-schema` | Exposes `DSPy::TypeSystem::SorbetJsonSchema` for downstream reuse. (Still required by the core `dspy` gem; extraction lets other projects depend on it directly.) | **Stable** (v1.0.0) |
+| `dspy-code_act` | Think-Code-Observe agents that synthesize and execute Ruby safely. (Add the gem or set `DSPY_WITH_CODE_ACT=1` before requiring `dspy/code_act`.) | **Stable** (v1.0.0) |
+| `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. (Toggle via `DSPY_WITH_DATASETS`.) | **Stable** (v1.0.0) |
+| `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. (Toggle via `DSPY_WITH_EVALS`.) | **Stable** (v1.0.0) |
+| `dspy-miprov2` | Bayesian optimization + Gaussian Process backend for the MIPROv2 teleprompter. (Install or export `DSPY_WITH_MIPROV2=1` before requiring the teleprompter.) | **Stable** (v1.0.0) |
+| `dspy-gepa` | `DSPy::Teleprompt::GEPA`, reflection loops, experiment tracking, telemetry adapters. (Install or set `DSPY_WITH_GEPA=1`.) | **Stable** (v1.0.0) |
+| `gepa` | GEPA optimizer core (Pareto engine, telemetry, reflective proposer). | **Stable** (v1.0.0) |
+| `dspy-o11y` | Core observability APIs: `DSPy::Observability`, async span processor, observation types. (Install or set `DSPY_WITH_O11Y=1`.) | **Stable** (v1.0.0) |
+| `dspy-o11y-langfuse` | Auto-configures DSPy observability to stream spans to Langfuse via OTLP. (Install or set `DSPY_WITH_O11Y_LANGFUSE=1`.) | **Stable** (v1.0.0) |
+| `dspy-deep_search` | Production DeepSearch loop with Exa-backed search/read, token budgeting, and instrumentation (Issue #163). | **Beta** (v1.0.0) |
+| `dspy-deep_research` | Planner/QA orchestration atop DeepSearch plus the memory supervisor used by the CLI example. | **Beta** (v1.0.0) |
+
+Set the matching `DSPY_WITH_*` environment variables (see `Gemfile`) to include or exclude each sibling gem when running Bundler locally (for example `DSPY_WITH_GEPA=1` or `DSPY_WITH_O11Y_LANGFUSE=1`). Refer to `adr/013-dependency-tree.md` for the full dependency map and roadmap.
+### Your First Reliable Predictor
+
+```ruby
+
+# Configure DSPy globablly to use your fave LLM - you can override this on an instance levle. 
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
+                      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/deep_search/README.md

@@ -0,0 +1,5 @@
+# DSPy::DeepSearch
+
+Foundational building blocks for DeepSearch-style DSPy agents. Tracks the search→read→reason loop, token budgets, and adapters for search providers.
+
+See ADR 015 for the implementation roadmap.

data/lib/dspy/deep_search/clients/exa_client.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module DSPy
+  module DeepSearch
+    module Clients
+      class ExaClient
+        extend T::Sig
+
+        class Error < StandardError; end
+        class ConfigurationError < Error; end
+        class ApiError < Error; end
+
+        class Result < T::Struct
+          const :url, String
+          const :title, T.nilable(String)
+          const :summary, T.nilable(String)
+          const :highlights, T::Array[String]
+          const :score, T.nilable(Float)
+        end
+
+        class Content < T::Struct
+          const :url, String
+          const :text, T.nilable(String)
+          const :summary, T.nilable(String)
+          const :highlights, T::Array[String]
+        end
+
+        sig { params(client: T.nilable(::Exa::Client)).void }
+        def initialize(client: nil)
+          @client = T.let(client || build_client, ::Exa::Client)
+        end
+
+        sig do
+          params(
+            query: String,
+            num_results: Integer,
+            autoprompt: T::Boolean
+          ).returns(T::Array[Result])
+        end
+        def search(query:, num_results: 5, autoprompt: true)
+          response = with_api_errors do
+            client.search.search(
+              query: query,
+              num_results: num_results,
+              use_autoprompt: autoprompt,
+              summary: true
+            )
+          end
+
+          response.results.filter_map do |result|
+            next if result.url.nil?
+
+            Result.new(
+              url: result.url,
+              title: result.title,
+              summary: result.summary,
+              highlights: normalize_highlights(result.highlights),
+              score: result.score
+            )
+          end
+        end
+
+        sig do
+          params(
+            urls: T::Array[String],
+            options: T::Hash[Symbol, T.untyped]
+          ).returns(T::Array[Content])
+        end
+        def contents(urls:, **options)
+          raise ArgumentError, "urls must not be empty" if urls.empty?
+
+          defaults = {
+            text: true,
+            summary: true,
+            highlights: true,
+            filter_empty_results: true
+          }
+
+          payload = Exa::Types::ContentsRequest.new(**defaults.merge(options).merge(urls: urls)).to_payload
+
+          raw_response = with_api_errors do
+            client.request(
+              method: :post,
+              path: "contents",
+              body: payload,
+              response_model: nil
+            )
+          end
+
+          symbolized = symbolize_keys(raw_response)
+
+          check_content_statuses!(symbolized)
+
+          Array(symbolized[:results]).each_with_index.filter_map do |result, index|
+            result = symbolize_keys(result)
+            url = result[:url] || urls[index]
+            next if url.nil?
+
+            Content.new(
+              url: url,
+              text: result[:text],
+              summary: result[:summary],
+              highlights: normalize_highlights(result[:highlights])
+            )
+          end
+        end
+
+        private
+
+        sig { returns(::Exa::Client) }
+        def build_client
+          ::Exa::Client.new
+        rescue ::Exa::Errors::ConfigurationError => e
+          raise ConfigurationError, e.message
+        end
+
+        sig { params(response: T::Hash[Symbol, T.untyped]).void }
+        def check_content_statuses!(response)
+          statuses = response[:statuses]
+          return if statuses.nil?
+
+          failure = Array(statuses).map { |status| symbolize_keys(status) }.find { |status| status[:status] != "success" }
+          return if failure.nil?
+
+          error_details = failure[:error] ? failure[:error].inspect : nil
+          message = [
+            "Exa contents request failed for #{failure[:id]}",
+            failure[:status],
+            error_details
+          ].compact.join(" - ")
+
+          raise ApiError, message
+        end
+
+        sig { params(hash: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+        def symbolize_keys(hash)
+          case hash
+          when Hash
+            hash.each_with_object({}) do |(key, value), acc|
+              acc[(key.is_a?(String) ? key.to_sym : key)] = value
+            end
+          else
+            {}
+          end
+        end
+
+        sig { params(highlights: T.nilable(T::Array[T.nilable(String)])).returns(T::Array[String]) }
+        def normalize_highlights(highlights)
+          Array(highlights).compact.map(&:to_s)
+        end
+
+        sig { params(block: T.proc.returns(T.untyped)).returns(T.untyped) }
+        def with_api_errors(&block)
+          block.call
+        rescue ::Exa::Errors::ConfigurationError => e
+          raise ConfigurationError, e.message
+        rescue ::Exa::Errors::APIError => e
+          raise ApiError, e.message
+        rescue ::Exa::Error => e
+          raise ApiError, e.message
+        end
+
+        sig { returns(::Exa::Client) }
+        attr_reader :client
+      end
+    end
+  end
+end

data/lib/dspy/deep_search/gap_queue.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "set"
+
+module DSPy
+  module DeepSearch
+    class GapQueue
+      extend T::Sig
+
+      class Empty < StandardError; end
+
+      sig { void }
+      def initialize
+        @queue = T.let([], T::Array[T.untyped])
+        @seen = T.let(Set.new, T::Set[T.untyped])
+      end
+
+      sig { params(item: T.untyped).void }
+      def enqueue(item)
+        return if @seen.include?(item)
+
+        @queue << item
+        @seen << item
+      end
+
+      sig { returns(T.untyped) }
+      def dequeue
+        raise Empty, "No items remaining in gap queue" if @queue.empty?
+
+        item = @queue.shift
+        @seen.delete(item)
+        item
+      end
+
+      sig { returns(Integer) }
+      def size
+        @queue.length
+      end
+
+      sig { returns(T::Boolean) }
+      def empty?
+        @queue.empty?
+      end
+    end
+  end
+end

data/lib/dspy/deep_search/module.rb

@@ -0,0 +1,463 @@
+# frozen_string_literal: true
+
+module DSPy
+  module DeepSearch
+    class Module < DSPy::Module
+      extend T::Sig
+
+      class Result < T::Struct
+        const :answer, String
+        const :notes, T::Array[String]
+        const :citations, T::Array[String]
+        const :budget_exhausted, T::Boolean, default: false
+        const :warning, T.nilable(String), default: nil
+      end
+
+      class TokenBudgetExceeded < DSPy::Error; end
+
+      DEFAULT_SEARCH_RESULTS = 5
+
+      MODEL_ENV_KEYS = {
+        seed: 'DSPY_DEEP_SEARCH_SEED_MODEL',
+        reader: 'DSPY_DEEP_SEARCH_READER_MODEL',
+        reason: 'DSPY_DEEP_SEARCH_REASON_MODEL'
+      }.freeze
+
+      MODEL_PRIORITY = {
+        seed: [
+          'gemini/gemini-2.5-flash-lite',
+          'anthropic/claude-haiku-4-5'
+        ],
+        reader: [
+          'anthropic/claude-sonnet-4-5',
+          'openai/gpt-4.1'
+        ],
+        reason: [
+          'gemini/gemini-2.5-pro',
+          'openai/o4-mini',
+          'anthropic/claude-4.1-opus'
+        ]
+      }.freeze
+
+      subscribe 'lm.tokens', :meter_tokens
+
+      sig do
+        params(
+          token_budget: DSPy::DeepSearch::TokenBudget,
+          seed_predictor: T.untyped,
+          search_predictor: T.nilable(T.untyped),
+          reader_predictor: T.untyped,
+          reason_predictor: T.untyped,
+          search_client: DSPy::DeepSearch::Clients::ExaClient
+        ).void
+      end
+      def initialize(
+        token_budget: DSPy::DeepSearch::TokenBudget.new(limit: 20_000),
+        seed_predictor: DSPy::Predict.new(DSPy::DeepSearch::Signatures::SeedQuery),
+        search_predictor: nil,
+        reader_predictor: DSPy::Predict.new(DSPy::DeepSearch::Signatures::ReadSource),
+        reason_predictor: DSPy::Predict.new(DSPy::DeepSearch::Signatures::ReasonStep),
+        search_client: DSPy::DeepSearch::Clients::ExaClient.new
+      )
+        super()
+
+        @token_budget = token_budget
+        @token_budget_limit = token_budget.limit
+        @seed_predictor = seed_predictor
+        @search_predictor = search_predictor
+        @reader_predictor = reader_predictor
+        @reason_predictor = reason_predictor
+        @search_client = search_client
+        @gap_queue = DSPy::DeepSearch::GapQueue.new
+
+        configure_default_predictor_models
+      end
+
+      def forward_untyped(**input_values)
+        question = input_values[:question]
+        unless question.is_a?(String)
+          raise ArgumentError, "DeepSearch expects keyword argument :question"
+        end
+
+        reset_state!
+        process_question(question)
+      rescue DSPy::DeepSearch::TokenBudget::Exceeded => e
+        build_budget_exhausted_result(question, e)
+      end
+
+      sig { override.returns(T::Array[[String, DSPy::Module]]) }
+      def named_predictors
+        pairs = []
+        pairs << ["seed_predictor", @seed_predictor] if @seed_predictor
+        pairs << ["search_predictor", T.must(@search_predictor)] if @search_predictor
+        pairs << ["reader_predictor", @reader_predictor] if @reader_predictor
+        pairs << ["reason_predictor", @reason_predictor] if @reason_predictor
+        pairs
+      end
+
+      sig { override.returns(T::Array[DSPy::Module]) }
+      def predictors
+        named_predictors.map { |(_, predictor)| predictor }
+      end
+
+      sig { params(instruction: String).returns(Module) }
+      def with_instruction(instruction)
+        clone_with(
+          seed_predictor: apply_instruction(@seed_predictor, instruction),
+          search_predictor: apply_instruction(@search_predictor, instruction),
+          reader_predictor: apply_instruction(@reader_predictor, instruction),
+          reason_predictor: apply_instruction(@reason_predictor, instruction),
+          token_budget_limit: @token_budget_limit
+        )
+      end
+
+      sig { params(examples: T::Array[DSPy::FewShotExample]).returns(Module) }
+      def with_examples(examples)
+        examples_copy = examples.map { |example| example }
+        clone_with(
+          seed_predictor: apply_examples(@seed_predictor, examples_copy),
+          search_predictor: apply_examples(@search_predictor, examples_copy),
+          reader_predictor: apply_examples(@reader_predictor, examples_copy),
+          reason_predictor: apply_examples(@reason_predictor, examples_copy),
+          token_budget_limit: @token_budget_limit
+        )
+      end
+      sig { params(limit: Integer).returns(Module) }
+      def with_token_budget(limit)
+        clone_with(
+          seed_predictor: @seed_predictor,
+          search_predictor: @search_predictor,
+          reader_predictor: @reader_predictor,
+          reason_predictor: @reason_predictor,
+          token_budget_limit: limit
+        )
+      end
+
+      private
+
+      sig { params(question: String).returns(Result) }
+      def process_question(question)
+        query = @seed_predictor.call(question: question).query
+        loop do
+          emit_loop_started(question, query)
+
+          urls = fetch_search_urls(query)
+          break if urls.empty?
+
+          urls.each { |url| enqueue_url(url) }
+          collect_notes
+
+          decision = @reason_predictor.call(question: question, insights: @notes)
+          emit_reason_decision(question, decision)
+
+          case decision.decision
+          when DSPy::DeepSearch::Signatures::ReasonStep::Decision::Answer
+            answer_text = decision.draft_answer || synthesize_answer
+            return Result.new(answer: answer_text, notes: @notes.dup, citations: @citations.dup)
+          when DSPy::DeepSearch::Signatures::ReasonStep::Decision::ContinueSearch
+            query = decision.refined_query || query
+            next
+          when DSPy::DeepSearch::Signatures::ReasonStep::Decision::ReadMore
+            collect_notes if pending_urls?
+            next
+          end
+        end
+
+        Result.new(answer: synthesize_answer, notes: @notes.dup, citations: @citations.dup)
+      end
+
+      sig { params(url: String).void }
+      def enqueue_url(url)
+        @gap_queue.enqueue(url)
+      end
+
+      sig { returns(T::Boolean) }
+      def pending_urls?
+        !@gap_queue.empty?
+      end
+
+      sig { void }
+      def collect_notes
+        until @gap_queue.empty?
+          url = @gap_queue.dequeue
+          fetch_and_extract(url)
+        end
+      end
+
+      sig { params(url: String).void }
+      def fetch_and_extract(url)
+        DSPy.event(
+          "deep_search.fetch.started",
+          url: url
+        )
+
+        notes_before = @notes.length
+        citations_before = @citations.length
+
+        contents = @search_client.contents(urls: [url])
+        record_notes(url, contents)
+        reader_notes = @reader_predictor.call(url: url).notes
+        @notes.concat(Array(reader_notes))
+
+        DSPy.event(
+          "deep_search.fetch.completed",
+          url: url,
+          notes_added: @notes.length - notes_before,
+          citations_added: @citations.length - citations_before,
+          token_budget_remaining: token_budget_remaining
+        )
+      rescue DSPy::DeepSearch::Clients::ExaClient::ApiError => e
+        DSPy.event(
+          "deep_search.fetch.failed",
+          url: url,
+          error: e.message
+        )
+        DSPy.logger&.warn("DeepSearch fetch failed", url: url, error: e.message)
+      end
+
+      sig { params(url: String, contents: T::Array[DSPy::DeepSearch::Clients::ExaClient::Content]).void }
+      def record_notes(url, contents)
+        contents.each do |content|
+          if content.summary
+            @notes << content.summary
+          end
+          content.highlights.each do |highlight|
+            @notes << highlight
+          end
+          @citations << url unless @citations.include?(url)
+        end
+      end
+
+      sig { returns(String) }
+      def synthesize_answer
+        return "" if @notes.empty?
+
+        @notes.first(5).join("\n")
+      end
+
+      sig { void }
+      def reset_state!
+        @notes = []
+        @citations = []
+        @gap_queue = DSPy::DeepSearch::GapQueue.new
+      end
+
+      sig { params(query: String).returns(T::Array[String]) }
+      def fetch_search_urls(query)
+        if @search_predictor
+          Array(@search_predictor.call(query: query).urls).compact
+        else
+          results = Array(
+            @search_client.search(
+              query: query,
+              num_results: DEFAULT_SEARCH_RESULTS,
+              autoprompt: true
+            )
+          )
+          results.map do |result|
+            if result.respond_to?(:url)
+              result.url
+            elsif result.is_a?(Hash)
+              result[:url] || result['url']
+            else
+              nil
+            end
+          end.compact.uniq
+        end
+      end
+
+      sig { params(_event_name: String, attrs: T::Hash[Symbol, T.untyped]).void }
+      def meter_tokens(_event_name, attrs)
+        @token_budget.track!(
+          prompt_tokens: attrs[:input_tokens].to_i,
+          completion_tokens: attrs[:output_tokens].to_i
+        )
+      end
+
+      sig do
+        params(
+          seed_predictor: T.untyped,
+          search_predictor: T.nilable(T.untyped),
+          reader_predictor: T.untyped,
+          reason_predictor: T.untyped,
+          token_budget_limit: Integer
+        ).returns(Module)
+      end
+      def clone_with(seed_predictor:, search_predictor:, reader_predictor:, reason_predictor:, token_budget_limit: @token_budget_limit)
+        self.class.new(
+          token_budget: DSPy::DeepSearch::TokenBudget.new(limit: token_budget_limit),
+          seed_predictor: seed_predictor,
+          search_predictor: search_predictor,
+          reader_predictor: reader_predictor,
+          reason_predictor: reason_predictor,
+          search_client: @search_client
+        )
+      end
+
+      sig { params(predictor: T.nilable(T.untyped), instruction: String).returns(T.nilable(T.untyped)) }
+      def apply_instruction(predictor, instruction)
+        return nil if predictor.nil?
+        return predictor.with_instruction(instruction) if predictor.respond_to?(:with_instruction)
+        predictor
+      end
+
+      sig { params(predictor: T.nilable(T.untyped), examples: T::Array[DSPy::FewShotExample]).returns(T.nilable(T.untyped)) }
+      def apply_examples(predictor, examples)
+        return nil if predictor.nil?
+        return predictor.with_examples(examples) if predictor.respond_to?(:with_examples)
+        predictor
+      end
+
+      sig { params(question: String, query: String).void }
+      def emit_loop_started(question, query)
+        DSPy.event(
+          "deep_search.loop.started",
+          question: question,
+          query: query,
+          token_budget_remaining: token_budget_remaining
+        )
+      end
+
+      sig { params(question: String, decision: T.untyped).void }
+      def emit_reason_decision(question, decision)
+        decision_enum = decision.respond_to?(:decision) ? decision.decision : nil
+        serialized_decision =
+          if decision_enum.respond_to?(:serialize)
+            decision_enum.serialize
+          elsif decision_enum.respond_to?(:to_s)
+            decision_enum.to_s
+          else
+            nil
+          end
+
+        DSPy.event(
+          "deep_search.reason.decision",
+          question: question,
+          decision: serialized_decision,
+          notes_count: @notes.length,
+          citations_count: @citations.length,
+          refined_query: decision.respond_to?(:refined_query) ? decision.refined_query : nil,
+          draft_answer: decision.respond_to?(:draft_answer) ? decision.draft_answer : nil,
+          token_budget_remaining: token_budget_remaining
+        )
+      end
+
+      sig { returns(Integer) }
+      def token_budget_remaining
+        remaining = @token_budget_limit - @token_budget.total_tokens
+        remaining.negative? ? 0 : remaining
+      end
+
+      def configure_default_predictor_models
+        @lm_cache = {}
+        assign_model(@seed_predictor, :seed)
+        assign_model(@reader_predictor, :reader)
+        assign_model(@reason_predictor, :reason)
+      end
+
+      def env_model(role)
+        key = MODEL_ENV_KEYS[role]
+        value = key ? ENV[key] : nil
+        return nil if value.nil?
+
+        trimmed = value.strip
+        trimmed.empty? ? nil : trimmed
+      end
+
+      def assign_model(predictor, role)
+        return unless predictor
+        return if predictor.respond_to?(:config) && predictor.config.lm
+
+        candidates = []
+        env_override = env_model(role)
+        candidates << env_override if env_override
+        candidates.concat(Array(MODEL_PRIORITY[role]))
+
+        candidates.each do |model_id|
+          next unless model_id
+          lm = build_lm(model_id)
+          next unless lm
+
+          begin
+            predictor.configure { |config| config.lm = lm }
+            return
+          rescue StandardError => e
+            DSPy.logger&.warn(
+              "DeepSearch predictor LM assignment error",
+              role: role,
+              model: model_id,
+              error: e.message
+            )
+          end
+        end
+
+        DSPy.logger&.warn(
+          "DeepSearch predictor LM assignment skipped (no viable model)",
+          role: role
+        )
+      end
+
+      def build_lm(model_id)
+        @lm_cache ||= {}
+        return @lm_cache[model_id] if @lm_cache.key?(model_id)
+
+        provider = model_id.split('/', 2).first
+        api_key = api_key_for(provider)
+        unless api_key && !api_key.strip.empty?
+          DSPy.logger&.warn(
+            "DeepSearch skipped LM assignment due to missing API key",
+            model: model_id,
+            provider: provider
+          )
+          return nil
+        end
+
+        @lm_cache[model_id] = DSPy::LM.new(model_id, api_key: api_key)
+      rescue StandardError => e
+        DSPy.logger&.warn(
+          "DeepSearch failed to initialize LM",
+          model: model_id,
+          error: e.message
+        )
+        nil
+      end
+
+      def api_key_for(provider)
+        case provider
+        when 'openai'
+          ENV['OPENAI_API_KEY']
+        when 'anthropic'
+          ENV['ANTHROPIC_API_KEY']
+        when 'gemini'
+          ENV['GEMINI_API_KEY']
+        when 'google'
+          ENV['GEMINI_API_KEY'] || ENV['GOOGLE_API_KEY']
+        else
+          nil
+        end
+      end
+
+      sig { params(question: String, error: DSPy::DeepSearch::TokenBudget::Exceeded).returns(Result) }
+      def build_budget_exhausted_result(question, error)
+        warning = error.message
+        DSPy.event(
+          "deep_search.budget.exhausted",
+          question: question,
+          notes_count: @notes.length,
+          citations_count: @citations.length,
+          token_budget_limit: @token_budget_limit,
+          total_tokens: @token_budget.total_tokens,
+          warning: warning
+        )
+
+        Result.new(
+          answer: synthesize_answer,
+          notes: @notes.dup,
+          citations: @citations.dup,
+          budget_exhausted: true,
+          warning: warning
+        )
+      end
+    end
+  end
+end

data/lib/dspy/deep_search/signatures.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module DSPy
+  module DeepSearch
+    module Signatures
+      extend T::Sig
+
+      class SeedQuery < DSPy::Signature
+        description "Seed the first search query for DeepSearch"
+
+        input do
+          const :question, String, description: "User research question"
+        end
+
+        output do
+          const :query, String, description: "Initial search query"
+        end
+      end
+
+      class SearchSources < DSPy::Signature
+        description "Call the search provider and return candidate URLs"
+
+        input do
+          const :query, String, description: "Search engine query"
+        end
+
+        output do
+          const :urls, T::Array[String], description: "Ranked URLs to read next"
+        end
+      end
+
+      class ReadSource < DSPy::Signature
+        description "Summarize a single source into bullet notes"
+
+        input do
+          const :url, String, description: "URL selected by the search step"
+        end
+
+        output do
+          const :notes, T::Array[String], description: "Key takeaways from the page"
+        end
+      end
+
+      class ReasonStep < DSPy::Signature
+        description "Decide whether to keep searching, read more, or answer"
+
+        class Decision < T::Enum
+          enums do
+            ContinueSearch = new("continue_search")
+            ReadMore       = new("read_more")
+            Answer         = new("answer")
+          end
+        end
+
+        input do
+          const :question, String, description: "Original user question"
+          const :insights, T::Array[String], description: "Accumulated notes" 
+        end
+
+        output do
+          const :decision, Decision, description: "Next action for the loop"
+          const :refined_query, T.nilable(String), description: "Follow-up search query"
+          const :draft_answer, T.nilable(String), description: "Candidate answer" 
+        end
+      end
+    end
+  end
+end

data/lib/dspy/deep_search/token_budget.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DSPy
+  module DeepSearch
+    class TokenBudget
+      extend T::Sig
+
+      class Exceeded < StandardError; end
+
+      sig { returns(Integer) }
+      attr_reader :limit
+
+      sig { returns(Integer) }
+      attr_reader :total_tokens
+
+      sig { params(limit: Integer).void }
+      def initialize(limit:)
+        @limit = limit
+        @total_tokens = T.let(0, Integer)
+      end
+
+      sig do
+        params(
+          prompt_tokens: Integer,
+          completion_tokens: Integer
+        ).void
+      end
+      def track!(prompt_tokens:, completion_tokens:)
+        prompt = T.must(prompt_tokens)
+        completion = T.must(completion_tokens)
+
+        increment = prompt + completion
+        new_total = @total_tokens + increment
+
+        if new_total >= limit
+          raise Exceeded, "Token budget exceeded: #{new_total}/#{limit}"
+        end
+
+        @total_tokens = new_total
+      end
+    end
+  end
+end

data/lib/dspy/deep_search/version.rb

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

data/lib/dspy/deep_search.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require "exa"
+
+require_relative "deep_search/version"
+require_relative "deep_search/token_budget"
+require_relative "deep_search/gap_queue"
+require_relative "deep_search/clients/exa_client"
+require_relative "deep_search/signatures"
+require_relative "deep_search/module"
+
+module DSPy
+  module DeepSearch
+    extend T::Sig
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: dspy-deep_search
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Vicente Reig Rincón de Arellano
+bindir: bin
+cert_chain: []
+date: 1980-01-02 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'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.30.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.30.1
+- !ruby/object:Gem::Dependency
+  name: exa-ai-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - ">="
+      - !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'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: DeepSearch loop utilities and modules for DSPy agents.
+email:
+- oss@vicente.services
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dspy/deep_search.rb
+- lib/dspy/deep_search/README.md
+- lib/dspy/deep_search/clients/exa_client.rb
+- lib/dspy/deep_search/gap_queue.rb
+- lib/dspy/deep_search/module.rb
+- lib/dspy/deep_search/signatures.rb
+- lib/dspy/deep_search/token_budget.rb
+- lib/dspy/deep_search/version.rb
+homepage: https://vicentereig.github.io/dspy.rb/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://vicentereig.github.io/dspy.rb/
+  source_code_uri: https://github.com/vicentereig/dspy.rb
+  changelog_uri: https://github.com/vicentereig/dspy.rb/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: DeepSearch primitives for DSPy
+test_files: []