@every-env/compound-plugin 0.3.0 → 0.5.1

package/plugins/compound-engineering/skills/dspy-ruby/references/providers.md

@@ -1,338 +1,418 @@
 # DSPy.rb LLM Providers
 
-## Supported Providers
+## Adapter Architecture
 
-DSPy.rb provides unified support across multiple LLM providers through adapter gems that automatically load when installed.
+DSPy.rb ships provider SDKs as separate adapter gems. Install only the adapters the project needs. Each adapter gem depends on the official SDK for its provider and auto-loads when present -- no explicit `require` necessary.
 
-### Provider Overview
+```ruby
+# Gemfile
+gem 'dspy'              # core framework (no provider SDKs)
+gem 'dspy-openai'       # OpenAI, OpenRouter, Ollama
+gem 'dspy-anthropic'    # Claude
+gem 'dspy-gemini'       # Gemini
+gem 'dspy-ruby_llm'     # RubyLLM unified adapter (12+ providers)
+```
+
+---
+
+## Per-Provider Adapters
 
-- **OpenAI**: GPT-4, GPT-4o, GPT-4o-mini, GPT-3.5-turbo
-- **Anthropic**: Claude 3 family (Sonnet, Opus, Haiku), Claude 3.5 Sonnet
-- **Google Gemini**: Gemini 1.5 Pro, Gemini 1.5 Flash, other versions
-- **Ollama**: Local model support via OpenAI compatibility layer
-- **OpenRouter**: Unified multi-provider API for 200+ models
+### dspy-openai
 
-## Configuration
+Covers any endpoint that speaks the OpenAI chat-completions protocol: OpenAI itself, OpenRouter, and Ollama.
 
-### Basic Setup
+**SDK dependency:** `openai ~> 0.17`
 
 ```ruby
-require 'dspy'
+# OpenAI
+lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
 
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('provider/model-name', api_key: ENV['API_KEY'])
-end
+# OpenRouter -- access 200+ models behind a single key
+lm = DSPy::LM.new('openrouter/x-ai/grok-4-fast:free',
+  api_key: ENV['OPENROUTER_API_KEY']
+)
+
+# Ollama -- local models, no API key required
+lm = DSPy::LM.new('ollama/llama3.2')
+
+# Remote Ollama instance
+lm = DSPy::LM.new('ollama/llama3.2',
+  base_url: 'https://my-ollama.example.com/v1',
+  api_key: 'optional-auth-token'
+)
 ```
 
-### OpenAI Configuration
+All three sub-adapters share the same request handling, structured-output support, and error reporting. Swap providers without changing higher-level DSPy code.
 
-**Required gem**: `dspy-openai`
+For OpenRouter models that lack native structured-output support, disable it explicitly:
 
 ```ruby
-DSPy.configure do |c|
-  # GPT-4o Mini (recommended for development)
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
+lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
+  api_key: ENV['OPENROUTER_API_KEY'],
+  structured_outputs: false
+)
+```
 
-  # GPT-4o (more capable)
-  c.lm = DSPy::LM.new('openai/gpt-4o', api_key: ENV['OPENAI_API_KEY'])
+### dspy-anthropic
 
-  # GPT-4 Turbo
-  c.lm = DSPy::LM.new('openai/gpt-4-turbo', api_key: ENV['OPENAI_API_KEY'])
-end
+Provides the Claude adapter. Install it for any `anthropic/*` model id.
+
+**SDK dependency:** `anthropic ~> 1.12`
+
+```ruby
+lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514',
+  api_key: ENV['ANTHROPIC_API_KEY']
+)
+```
+
+Structured outputs default to tool-based JSON extraction (`structured_outputs: true`). Set `structured_outputs: false` to use enhanced-prompting extraction instead.
+
+```ruby
+# Tool-based extraction (default, most reliable)
+lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514',
+  api_key: ENV['ANTHROPIC_API_KEY'],
+  structured_outputs: true
+)
+
+# Enhanced prompting extraction
+lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514',
+  api_key: ENV['ANTHROPIC_API_KEY'],
+  structured_outputs: false
+)
 ```
 
-**Environment variable**: `OPENAI_API_KEY`
+### dspy-gemini
 
-### Anthropic Configuration
+Provides the Gemini adapter. Install it for any `gemini/*` model id.
 
-**Required gem**: `dspy-anthropic`
+**SDK dependency:** `gemini-ai ~> 4.3`
 
 ```ruby
-DSPy.configure do |c|
-  # Claude 3.5 Sonnet (latest, most capable)
-  c.lm = DSPy::LM.new('anthropic/claude-3-5-sonnet-20241022',
-    api_key: ENV['ANTHROPIC_API_KEY'])
+lm = DSPy::LM.new('gemini/gemini-2.5-flash',
+  api_key: ENV['GEMINI_API_KEY']
+)
+```
 
-  # Claude 3 Opus (most capable in Claude 3 family)
-  c.lm = DSPy::LM.new('anthropic/claude-3-opus-20240229',
-    api_key: ENV['ANTHROPIC_API_KEY'])
+**Environment variable:** `GEMINI_API_KEY` (also accepts `GOOGLE_API_KEY`).
 
-  # Claude 3 Sonnet (balanced)
-  c.lm = DSPy::LM.new('anthropic/claude-3-sonnet-20240229',
-    api_key: ENV['ANTHROPIC_API_KEY'])
+---
 
-  # Claude 3 Haiku (fast, cost-effective)
-  c.lm = DSPy::LM.new('anthropic/claude-3-haiku-20240307',
-    api_key: ENV['ANTHROPIC_API_KEY'])
-end
+## RubyLLM Unified Adapter
+
+The `dspy-ruby_llm` gem provides a single adapter that routes to 12+ providers through [RubyLLM](https://rubyllm.com). Use it when a project talks to multiple providers or needs access to Bedrock, VertexAI, DeepSeek, or Mistral without dedicated adapter gems.
+
+**SDK dependency:** `ruby_llm ~> 1.3`
+
+### Model ID Format
+
+Prefix every model id with `ruby_llm/`:
+
+```ruby
+lm = DSPy::LM.new('ruby_llm/gpt-4o-mini')
+lm = DSPy::LM.new('ruby_llm/claude-sonnet-4-20250514')
+lm = DSPy::LM.new('ruby_llm/gemini-2.5-flash')
 ```
 
-**Environment variable**: `ANTHROPIC_API_KEY`
+The adapter detects the provider from RubyLLM's model registry automatically. For models not in the registry, pass `provider:` explicitly:
+
+```ruby
+lm = DSPy::LM.new('ruby_llm/llama3.2', provider: 'ollama')
+lm = DSPy::LM.new('ruby_llm/anthropic/claude-3-opus',
+  api_key: ENV['OPENROUTER_API_KEY'],
+  provider: 'openrouter'
+)
+```
 
-### Google Gemini Configuration
+### Using Existing RubyLLM Configuration
 
-**Required gem**: `dspy-gemini`
+When RubyLLM is already configured globally, omit the `api_key:` argument. DSPy reuses the global config automatically:
 
 ```ruby
-DSPy.configure do |c|
-  # Gemini 1.5 Pro (most capable)
-  c.lm = DSPy::LM.new('gemini/gemini-1.5-pro',
-    api_key: ENV['GOOGLE_API_KEY'])
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+end
 
-  # Gemini 1.5 Flash (faster, cost-effective)
-  c.lm = DSPy::LM.new('gemini/gemini-1.5-flash',
-    api_key: ENV['GOOGLE_API_KEY'])
+# No api_key needed -- picks up the global config
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('ruby_llm/gpt-4o-mini')
 end
 ```
 
-**Environment variable**: `GOOGLE_API_KEY` or `GEMINI_API_KEY`
+When an `api_key:` (or any of `base_url:`, `timeout:`, `max_retries:`) is passed, DSPy creates a **scoped context** instead of reusing the global config.
 
-### Ollama Configuration
+### Cloud-Hosted Providers (Bedrock, VertexAI)
 
-**Required gem**: None (uses OpenAI compatibility layer)
+Configure RubyLLM globally first, then reference the model:
 
 ```ruby
-DSPy.configure do |c|
-  # Local Ollama instance
-  c.lm = DSPy::LM.new('ollama/llama3.1',
-    base_url: 'http://localhost:11434')
+# AWS Bedrock
+RubyLLM.configure do |c|
+  c.bedrock_api_key = ENV['AWS_ACCESS_KEY_ID']
+  c.bedrock_secret_key = ENV['AWS_SECRET_ACCESS_KEY']
+  c.bedrock_region = 'us-east-1'
+end
+lm = DSPy::LM.new('ruby_llm/anthropic.claude-3-5-sonnet', provider: 'bedrock')
 
-  # Other Ollama models
-  c.lm = DSPy::LM.new('ollama/mistral')
-  c.lm = DSPy::LM.new('ollama/codellama')
+# Google VertexAI
+RubyLLM.configure do |c|
+  c.vertexai_project_id = 'your-project-id'
+  c.vertexai_location = 'us-central1'
 end
+lm = DSPy::LM.new('ruby_llm/gemini-pro', provider: 'vertexai')
 ```
 
-**Note**: Ensure Ollama is running locally: `ollama serve`
+### Supported Providers Table
+
+| Provider    | Example Model ID                           | Notes                           |
+|-------------|--------------------------------------------|---------------------------------|
+| OpenAI      | `ruby_llm/gpt-4o-mini`                    | Auto-detected from registry     |
+| Anthropic   | `ruby_llm/claude-sonnet-4-20250514`       | Auto-detected from registry     |
+| Gemini      | `ruby_llm/gemini-2.5-flash`               | Auto-detected from registry     |
+| DeepSeek    | `ruby_llm/deepseek-chat`                  | Auto-detected from registry     |
+| Mistral     | `ruby_llm/mistral-large`                  | Auto-detected from registry     |
+| Ollama      | `ruby_llm/llama3.2`                       | Use `provider: 'ollama'`        |
+| AWS Bedrock | `ruby_llm/anthropic.claude-3-5-sonnet`    | Configure RubyLLM globally      |
+| VertexAI    | `ruby_llm/gemini-pro`                     | Configure RubyLLM globally      |
+| OpenRouter  | `ruby_llm/anthropic/claude-3-opus`        | Use `provider: 'openrouter'`    |
+| Perplexity  | `ruby_llm/llama-3.1-sonar-large`          | Use `provider: 'perplexity'`    |
+| GPUStack    | `ruby_llm/model-name`                     | Use `provider: 'gpustack'`      |
+
+---
 
-### OpenRouter Configuration
+## Rails Initializer Pattern
 
-**Required gem**: `dspy-openai` (uses OpenAI adapter)
+Configure DSPy inside an `after_initialize` block so Rails credentials and environment are fully loaded:
 
 ```ruby
-DSPy.configure do |c|
-  # Access 200+ models through OpenRouter
-  c.lm = DSPy::LM.new('openrouter/anthropic/claude-3.5-sonnet',
-    api_key: ENV['OPENROUTER_API_KEY'],
-    base_url: 'https://openrouter.ai/api/v1')
-
-  # Other examples
-  c.lm = DSPy::LM.new('openrouter/google/gemini-pro')
-  c.lm = DSPy::LM.new('openrouter/meta-llama/llama-3.1-70b-instruct')
+# config/initializers/dspy.rb
+Rails.application.config.after_initialize do
+  return if Rails.env.test? # skip in test -- use VCR cassettes instead
+
+  DSPy.configure do |config|
+    config.lm = DSPy::LM.new(
+      'openai/gpt-4o-mini',
+      api_key: Rails.application.credentials.openai_api_key,
+      structured_outputs: true
+    )
+
+    config.logger = if Rails.env.production?
+      Dry.Logger(:dspy, formatter: :json) do |logger|
+        logger.add_backend(stream: Rails.root.join("log/dspy.log"))
+      end
+    else
+      Dry.Logger(:dspy) do |logger|
+        logger.add_backend(level: :debug, stream: $stdout)
+      end
+    end
+  end
 end
 ```
 
-**Environment variable**: `OPENROUTER_API_KEY`
+Key points:
 
-## Provider Compatibility Matrix
+- Wrap in `after_initialize` so `Rails.application.credentials` is available.
+- Return early in the test environment. Rely on VCR cassettes for deterministic LLM responses.
+- Set `structured_outputs: true` (the default) for provider-native JSON extraction.
+- Use `Dry.Logger` with `:json` formatter in production for structured log parsing.
 
-### Feature Support
+---
 
-| Feature | OpenAI | Anthropic | Gemini | Ollama |
-|---------|--------|-----------|--------|--------|
-| Structured Output | ✅ | ✅ | ✅ | ✅ |
-| Vision (Images) | ✅ | ✅ | ✅ | ⚠️ Limited |
-| Image URLs | ✅ | ❌ | ❌ | ❌ |
-| Tool Calling | ✅ | ✅ | ✅ | Varies |
-| Streaming | ❌ | ❌ | ❌ | ❌ |
-| Function Calling | ✅ | ✅ | ✅ | Varies |
+## Fiber-Local LM Context
 
-**Legend**: ✅ Full support | ⚠️ Partial support | ❌ Not supported
+`DSPy.with_lm` sets a temporary language-model override scoped to the current Fiber. Every predictor call inside the block uses the override; outside the block the previous LM takes effect again.
 
-### Vision Capabilities
+```ruby
+fast = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
+powerful = DSPy::LM.new('anthropic/claude-sonnet-4-20250514', api_key: ENV['ANTHROPIC_API_KEY'])
 
-**Image URLs**: Only OpenAI supports direct URL references. For other providers, load images as base64 or from files.
+classifier = Classifier.new
 
-```ruby
-# OpenAI - supports URLs
-DSPy::Image.from_url("https://example.com/image.jpg")
+# Uses the global LM
+result = classifier.call(text: "Hello")
 
-# Anthropic, Gemini - use file or base64
-DSPy::Image.from_file("path/to/image.jpg")
-DSPy::Image.from_base64(base64_data, mime_type: "image/jpeg")
+# Temporarily switch to the fast model
+DSPy.with_lm(fast) do
+  result = classifier.call(text: "Hello")   # uses gpt-4o-mini
+end
+
+# Temporarily switch to the powerful model
+DSPy.with_lm(powerful) do
+  result = classifier.call(text: "Hello")   # uses claude-sonnet-4
+end
 ```
 
-**Ollama**: Limited multimodal functionality. Check specific model capabilities.
+### LM Resolution Hierarchy
 
-## Advanced Configuration
+DSPy resolves the active language model in this order:
 
-### Custom Parameters
+1. **Instance-level LM** -- set directly on a module instance via `configure`
+2. **Fiber-local LM** -- set via `DSPy.with_lm`
+3. **Global LM** -- set via `DSPy.configure`
 
-Pass provider-specific parameters during configuration:
+Instance-level configuration always wins, even inside a `DSPy.with_lm` block:
 
 ```ruby
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o',
-    api_key: ENV['OPENAI_API_KEY'],
-    temperature: 0.7,
-    max_tokens: 2000,
-    top_p: 0.9
-  )
+classifier = Classifier.new
+classifier.configure { |c| c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514', api_key: ENV['ANTHROPIC_API_KEY']) }
+
+fast = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
+
+DSPy.with_lm(fast) do
+  classifier.call(text: "Test")  # still uses claude-sonnet-4 (instance-level wins)
 end
 ```
 
-### Multiple Providers
+### configure_predictor for Fine-Grained Agent Control
 
-Use different models for different tasks:
+Complex agents (`ReAct`, `CodeAct`, `DeepResearch`, `DeepSearch`) contain internal predictors. Use `configure` for a blanket override and `configure_predictor` to target a specific sub-predictor:
 
 ```ruby
-# Fast model for simple tasks
-fast_lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
+agent = DSPy::ReAct.new(MySignature, tools: tools)
 
-# Powerful model for complex tasks
-powerful_lm = DSPy::LM.new('anthropic/claude-3-5-sonnet-20241022',
-  api_key: ENV['ANTHROPIC_API_KEY'])
+# Set a default LM for the agent and all its children
+agent.configure { |c| c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY']) }
 
-# Use different models in different modules
-class SimpleClassifier < DSPy::Module
-  def initialize
-    super
-    DSPy.configure { |c| c.lm = fast_lm }
-    @predictor = DSPy::Predict.new(SimpleSignature)
-  end
+# Override just the reasoning predictor with a more capable model
+agent.configure_predictor('thought_generator') do |c|
+  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514', api_key: ENV['ANTHROPIC_API_KEY'])
 end
 
-class ComplexAnalyzer < DSPy::Module
-  def initialize
-    super
-    DSPy.configure { |c| c.lm = powerful_lm }
-    @predictor = DSPy::ChainOfThought.new(ComplexSignature)
-  end
-end
+result = agent.call(question: "Summarize the report")
 ```
 
-### Per-Request Configuration
-
-Override configuration for specific predictions:
+Both methods support chaining:
 
 ```ruby
-predictor = DSPy::Predict.new(MySignature)
+agent
+  .configure { |c| c.lm = cheap_model }
+  .configure_predictor('thought_generator') { |c| c.lm = expensive_model }
+```
 
-# Use default configuration
-result1 = predictor.forward(input: "data")
+#### Available Predictors by Agent Type
 
-# Override temperature for this request
-result2 = predictor.forward(
-  input: "data",
-  config: { temperature: 0.2 }  # More deterministic
-)
-```
+| Agent                | Internal Predictors                                              |
+|----------------------|------------------------------------------------------------------|
+| `DSPy::ReAct`        | `thought_generator`, `observation_processor`                    |
+| `DSPy::CodeAct`      | `code_generator`, `observation_processor`                       |
+| `DSPy::DeepResearch`  | `planner`, `synthesizer`, `qa_reviewer`, `reporter`            |
+| `DSPy::DeepSearch`    | `seed_predictor`, `search_predictor`, `reader_predictor`, `reason_predictor` |
+
+#### Propagation Rules
 
-## Cost Optimization
+- Configuration propagates recursively to children and grandchildren.
+- Children with an already-configured LM are **not** overwritten by a later parent `configure` call.
+- Configure the parent first, then override specific children.
 
-### Model Selection Strategy
+---
 
-1. **Development**: Use cheaper, faster models (gpt-4o-mini, claude-3-haiku, gemini-1.5-flash)
-2. **Production Simple Tasks**: Continue with cheaper models if quality is sufficient
-3. **Production Complex Tasks**: Upgrade to more capable models (gpt-4o, claude-3.5-sonnet, gemini-1.5-pro)
-4. **Local Development**: Use Ollama for privacy and zero API costs
+## Feature-Flagged Model Selection
 
-### Example Cost-Conscious Setup
+Use a `FeatureFlags` module backed by ENV vars to centralize model selection. Each tool or agent reads its model from the flags, falling back to a global default.
 
 ```ruby
-# Development environment
-if Rails.env.development?
-  DSPy.configure do |c|
-    c.lm = DSPy::LM.new('ollama/llama3.1')  # Free, local
+module FeatureFlags
+  module_function
+
+  def default_model
+    ENV.fetch('DSPY_DEFAULT_MODEL', 'openai/gpt-4o-mini')
+  end
+
+  def default_api_key
+    ENV.fetch('DSPY_DEFAULT_API_KEY') { ENV.fetch('OPENAI_API_KEY', nil) }
   end
-elsif Rails.env.test?
-  DSPy.configure do |c|
-    c.lm = DSPy::LM.new('openai/gpt-4o-mini',  # Cheap for testing
-      api_key: ENV['OPENAI_API_KEY'])
+
+  def model_for(tool_name)
+    env_key = "DSPY_MODEL_#{tool_name.upcase}"
+    ENV.fetch(env_key, default_model)
   end
-else  # production
-  DSPy.configure do |c|
-    c.lm = DSPy::LM.new('anthropic/claude-3-5-sonnet-20241022',
-      api_key: ENV['ANTHROPIC_API_KEY'])
+
+  def api_key_for(tool_name)
+    env_key = "DSPY_API_KEY_#{tool_name.upcase}"
+    ENV.fetch(env_key, default_api_key)
   end
 end
 ```
 
-## Provider-Specific Best Practices
-
-### OpenAI
+### Per-Tool Model Override
 
-- Use `gpt-4o-mini` for development and simple tasks
-- Use `gpt-4o` for production complex tasks
-- Best vision support including URL loading
-- Excellent function calling capabilities
+Override an individual tool's model without touching application code:
 
-### Anthropic
+```bash
+# .env
+DSPY_DEFAULT_MODEL=openai/gpt-4o-mini
+DSPY_DEFAULT_API_KEY=sk-...
 
-- Claude 3.5 Sonnet is currently the most capable model
-- Excellent for complex reasoning and analysis
-- Strong safety features and helpful outputs
-- Requires base64 for images (no URL support)
+# Override the classifier to use Claude
+DSPY_MODEL_CLASSIFIER=anthropic/claude-sonnet-4-20250514
+DSPY_API_KEY_CLASSIFIER=sk-ant-...
 
-### Google Gemini
+# Override the summarizer to use Gemini
+DSPY_MODEL_SUMMARIZER=gemini/gemini-2.5-flash
+DSPY_API_KEY_SUMMARIZER=...
+```
 
-- Gemini 1.5 Pro for complex tasks, Flash for speed
-- Strong multimodal capabilities
-- Good balance of cost and performance
-- Requires base64 for images
+Wire each agent to its flag at initialization:
 
-### Ollama
+```ruby
+class ClassifierAgent < DSPy::Module
+  def initialize
+    super
+    model = FeatureFlags.model_for('classifier')
+    api_key = FeatureFlags.api_key_for('classifier')
 
-- Best for privacy-sensitive applications
-- Zero API costs
-- Requires local hardware resources
-- Limited multimodal support depending on model
-- Good for development and testing
+    @predictor = DSPy::Predict.new(ClassifySignature)
+    configure { |c| c.lm = DSPy::LM.new(model, api_key: api_key) }
+  end
 
-## Troubleshooting
+  def forward(text:)
+    @predictor.call(text: text)
+  end
+end
+```
 
-### API Key Issues
+This pattern keeps model routing declarative and avoids scattering `DSPy::LM.new` calls across the codebase.
 
-```ruby
-# Verify API key is set
-if ENV['OPENAI_API_KEY'].nil?
-  raise "OPENAI_API_KEY environment variable not set"
-end
+---
 
-# Test connection
-begin
-  DSPy.configure { |c| c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-    api_key: ENV['OPENAI_API_KEY']) }
-  predictor = DSPy::Predict.new(TestSignature)
-  predictor.forward(test: "data")
-  puts "✅ Connection successful"
-rescue => e
-  puts "❌ Connection failed: #{e.message}"
-end
-```
+## Compatibility Matrix
 
-### Rate Limiting
+Feature support across direct adapter gems. All features listed assume `structured_outputs: true` (the default).
 
-Handle rate limits gracefully:
+| Feature              | OpenAI | Anthropic | Gemini | Ollama   | OpenRouter | RubyLLM     |
+|----------------------|--------|-----------|--------|----------|------------|-------------|
+| Structured Output    | Native JSON mode | Tool-based extraction | Native JSON schema | OpenAI-compatible JSON | Varies by model | Via `with_schema` |
+| Vision (Images)      | File + URL | File + Base64 | File + Base64 | Limited  | Varies     | Delegates to underlying provider |
+| Image URLs           | Yes    | No        | No     | No       | Varies     | Depends on provider |
+| Tool Calling         | Yes    | Yes       | Yes    | Varies   | Varies     | Yes         |
+| Streaming            | Yes    | Yes       | Yes    | Yes      | Yes        | Yes         |
 
-```ruby
-def call_with_retry(predictor, input, max_retries: 3)
-  retries = 0
-  begin
-    predictor.forward(input)
-  rescue RateLimitError => e
-    retries += 1
-    if retries < max_retries
-      sleep(2 ** retries)  # Exponential backoff
-      retry
-    else
-      raise
-    end
-  end
-end
-```
+**Notes:**
 
-### Model Not Found
+- **Structured Output** is enabled by default on every adapter. Set `structured_outputs: false` to fall back to enhanced-prompting extraction.
+- **Vision / Image URLs:** Only OpenAI supports passing a URL directly. For Anthropic and Gemini, load images from file or Base64:
+  ```ruby
+  DSPy::Image.from_url("https://example.com/img.jpg")    # OpenAI only
+  DSPy::Image.from_file("path/to/image.jpg")             # all providers
+  DSPy::Image.from_base64(data, mime_type: "image/jpeg")  # all providers
+  ```
+- **RubyLLM** delegates to the underlying provider, so feature support matches the provider column in the table.
 
-Ensure the correct gem is installed:
+### Choosing an Adapter Strategy
 
-```bash
-# For OpenAI
-gem install dspy-openai
+| Scenario                                  | Recommended Adapter            |
+|-------------------------------------------|--------------------------------|
+| Single provider (OpenAI, Claude, or Gemini) | Dedicated gem (`dspy-openai`, `dspy-anthropic`, `dspy-gemini`) |
+| Multi-provider with per-agent model routing | `dspy-ruby_llm`               |
+| AWS Bedrock or Google VertexAI             | `dspy-ruby_llm`               |
+| Local development with Ollama              | `dspy-openai` (Ollama sub-adapter) or `dspy-ruby_llm` |
+| OpenRouter for cost optimization           | `dspy-openai` (OpenRouter sub-adapter) |
 
-# For Anthropic
-gem install dspy-anthropic
+### Current Recommended Models
 
-# For Gemini
-gem install dspy-gemini
-```
+| Provider  | Model ID                              | Use Case              |
+|-----------|---------------------------------------|-----------------------|
+| OpenAI    | `openai/gpt-4o-mini`                 | Fast, cost-effective  |
+| Anthropic | `anthropic/claude-sonnet-4-20250514` | Balanced reasoning    |
+| Gemini    | `gemini/gemini-2.5-flash`            | Fast, cost-effective  |
+| Ollama    | `ollama/llama3.2`                    | Local, zero API cost  |