dspy-ruby_llm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8442dc722fa4ef77810d65ede3d52c66910af543550138add7656c4e703ada7b
+  data.tar.gz: 0ab6ee908cc82c0b674e52f2b5eeee6038266fc41171ba270aa1b13dd641e7f7
+SHA512:
+  metadata.gz: 68d12fbfe7c4732c07b7287f55a771ad8f55a4d7fc7eb66bd9f6a5f4a267b65811c9d2771604f083835d352b0c0907d9b01a1bf211cc454d8af87ad644bcabe5
+  data.tar.gz: 9c754e16b521f75373ca648a60010caa467b78c87ba1ea72c8bb63a5d6a9260261c4c42b004e42603d816f123db409090dd903de985e30444a8c18449eeef3d6

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,297 @@
+# 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/)
+[![Discord](https://img.shields.io/discord/1161519468141355160?label=discord&logo=discord&logoColor=white)](https://discord.gg/zWBhrMqn)
+
+> [!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
+>
+
+**Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
+
+DSPy.rb is the Ruby-first surgical port of Stanford's [DSPy paradigm](https://github.com/stanfordnlp/dspy). It delivers structured LLM programming, prompt engineering, and context engineering in the language we love. Instead of wrestling with brittle prompt strings, you define typed signatures in idiomatic Ruby and compose workflows and agents that actually behave.
+
+**Prompts are 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/): define modular signatures and let the framework deal with the messy bits.
+
+While we implement the same signatures, predictors, and optimization algorithms as the original library, DSPy.rb leans hard into Ruby conventions with Sorbet-based typing, ReAct loops, and production-ready integrations like non-blocking OpenTelemetry instrumentation.
+
+**What you get?** Ruby LLM applications that 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
+require 'dspy'
+
+# Configure DSPy globally to use your fave LLM (you can override per predictor).
+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 prediction loop.
+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
+```
+
+Save this as `examples/first_predictor.rb` and run it with:
+
+```bash
+bundle exec ruby examples/first_predictor.rb
+```
+
+### 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-openai` | Packages the OpenAI/OpenRouter/Ollama adapters plus the official SDK guardrails. Install whenever you call `openai/*`, `openrouter/*`, or `ollama/*`. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/openai/README.md) | **Stable** (v1.0.0) |
+| `dspy-anthropic` | Claude adapters, streaming, and structured-output helpers behind the official `anthropic` SDK. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/anthropic/README.md) | **Stable** (v1.0.0) |
+| `dspy-gemini` | Gemini adapters with multimodal + tool-call support via `gemini-ai`. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/gemini/README.md) | **Stable** (v1.0.0) |
+| `dspy-ruby_llm` | Unified access to 12+ LLM providers (OpenAI, Anthropic, Gemini, Bedrock, Ollama, DeepSeek, etc.) via [RubyLLM](https://rubyllm.com). [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/ruby_llm/README.md) | **Stable** (v0.1.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). | **Stable** (v1.0.0) |
+| `dspy-deep_research` | Planner/QA orchestration atop DeepSearch plus the memory supervisor used by the CLI example. | **Stable** (v1.0.0) |
+| `sorbet-toon` | Token-Oriented Object Notation (TOON) codec, prompt formatter, and Sorbet mixins for BAML/TOON Enhanced Prompting. [Sorbet::Toon README](https://github.com/vicentereig/dspy.rb/blob/main/lib/sorbet/toon/README.md) | **Alpha** (v0.1.0) |
+
+**Provider adapters:** Add `dspy-openai`, `dspy-anthropic`, and/or `dspy-gemini` next to `dspy` in your Gemfile depending on which `DSPy::LM` providers you call. Each gem already depends on the official SDK (`openai`, `anthropic`, `gemini-ai`), and DSPy auto-loads the adapters when the gem is present—no extra `require` needed.
+
+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.
+### 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:** Official clients, multimodal coverage, and observability baked in.
+<details>
+<summary>Expand for everything included</summary>
+
+- 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
+</details>
+
+**Core Building Blocks:** Predictors, agents, and pipelines wired through type-safe signatures.
+<details>
+<summary>Expand for everything included</summary>
+
+- **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
+</details>
+
+**Optimization & Evaluation:** Treat prompt optimization like a real ML workflow.
+<details>
+<summary>Expand for everything included</summary>
+
+- **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
+</details>
+
+**Production Features:** Hardened behaviors for teams shipping actual products.
+<details>
+<summary>Expand for everything included</summary>
+
+- **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
+</details>
+
+## Recent Achievements
+
+DSPy.rb has gone from experimental to production-ready in three fast releases.
+<details>
+<summary>Expand for the full changelog highlights</summary>
+
+### 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
+</details>
+
+**Current Focus Areas:** Closing the loop on production patterns and community adoption ahead of v1.0.
+<details>
+<summary>Expand for the roadmap</summary>
+
+### 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
+</details>
+
+**v1.0 Philosophy:** v1.0 lands after battle-testing, not checkbox bingo. The API is already stable; the milestone marks production confidence.
+
+
+## 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/ruby_llm/README.md

@@ -0,0 +1,174 @@
+# DSPy RubyLLM Adapter
+
+Unified access to 12+ LLM providers through a single adapter using [RubyLLM](https://rubyllm.com).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'dspy-ruby_llm'
+```
+
+## Usage
+
+### Using Existing RubyLLM Configuration (Recommended)
+
+If you already have RubyLLM configured, DSPy will use your existing setup automatically:
+
+```ruby
+# Your existing RubyLLM configuration
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+end
+
+# DSPy uses your existing config - no api_key needed!
+lm = DSPy::LM.new("ruby_llm/gpt-4o")
+lm = DSPy::LM.new("ruby_llm/claude-sonnet-4")
+```
+
+### Model ID Format
+
+Use `ruby_llm/{model_id}` format where `model_id` is the RubyLLM model identifier:
+
+```ruby
+# With explicit API key (creates scoped context)
+lm = DSPy::LM.new("ruby_llm/gpt-4o", api_key: ENV['OPENAI_API_KEY'])
+
+# Or use global RubyLLM config (no api_key needed)
+lm = DSPy::LM.new("ruby_llm/gpt-4o")
+lm = DSPy::LM.new("ruby_llm/claude-sonnet-4")
+lm = DSPy::LM.new("ruby_llm/gemini-1.5-pro")
+
+# For models not in RubyLLM registry, specify provider explicitly
+lm = DSPy::LM.new("ruby_llm/llama3.2", provider: 'ollama')
+```
+
+The adapter detects the provider from RubyLLM's model registry. For models not in the registry, use the `provider:` option.
+
+### Provider Override
+
+For custom deployments or models not in the registry, explicitly specify the provider:
+
+```ruby
+# OpenRouter
+lm = DSPy::LM.new("ruby_llm/anthropic/claude-3-opus",
+  api_key: ENV['OPENROUTER_API_KEY'],
+  provider: 'openrouter'
+)
+
+# Custom model with explicit provider
+lm = DSPy::LM.new("ruby_llm/my-custom-model",
+  api_key: ENV['OPENAI_API_KEY'],
+  provider: 'openai',
+  base_url: 'https://custom-endpoint.com/v1'
+)
+
+# AWS Bedrock - configure RubyLLM globally first
+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')
+
+# VertexAI - configure RubyLLM globally first
+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')
+```
+
+### Supported Providers
+
+| Provider | Example Model ID | Notes |
+|----------|------------------|-------|
+| OpenAI | `ruby_llm/gpt-4o` | In RubyLLM registry |
+| Anthropic | `ruby_llm/claude-sonnet-4` | In RubyLLM registry |
+| Google Gemini | `ruby_llm/gemini-1.5-pro` | In RubyLLM registry |
+| DeepSeek | `ruby_llm/deepseek-chat` | In RubyLLM registry |
+| Mistral | `ruby_llm/mistral-large` | In RubyLLM registry |
+| Ollama | `ruby_llm/llama3.2` | Use `provider: 'ollama'`, no API key needed |
+| 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'` |
+
+### Configuration Options
+
+```ruby
+lm = DSPy::LM.new("ruby_llm/gpt-4o",
+  api_key: ENV['OPENAI_API_KEY'],       # API key (or use global RubyLLM config)
+  base_url: 'https://custom.com/v1',    # Custom endpoint
+  timeout: 120,                          # Request timeout in seconds
+  max_retries: 3,                        # Retry count
+  structured_outputs: true               # Enable JSON schema (default: true)
+)
+```
+
+For providers with non-standard auth (Bedrock, VertexAI), configure RubyLLM globally - see examples above.
+
+### With DSPy Signatures
+
+```ruby
+class Summarize < DSPy::Signature
+  description "Summarize the given text"
+
+  input do
+    const :text, String
+  end
+
+  output do
+    const :summary, String
+  end
+end
+
+DSPy.configure do |config|
+  config.lm = DSPy::LM.new("ruby_llm/claude-sonnet-4")
+end
+
+summarizer = DSPy::Predict.new(Summarize)
+result = summarizer.call(text: "Long article text here...")
+puts result.summary
+```
+
+### Streaming
+
+```ruby
+lm = DSPy::LM.new("ruby_llm/gpt-4o", api_key: ENV['OPENAI_API_KEY'])
+
+response = lm.chat(messages: [{ role: 'user', content: 'Tell me a story' }]) do |chunk|
+  print chunk  # Print each chunk as it arrives
+end
+```
+
+## Dependencies
+
+This gem depends on:
+- `dspy` (>= 0.32)
+- `ruby_llm` (~> 1.3)
+
+RubyLLM itself has minimal dependencies (Faraday, Zeitwerk, Marcel).
+
+## Why Use This Adapter?
+
+1. **Unified interface** - One API for all providers
+2. **Lightweight** - RubyLLM has only 3 dependencies
+3. **Provider coverage** - Access Bedrock, VertexAI, DeepSeek without separate adapters
+4. **Built-in retries** - Automatic retry with exponential backoff
+5. **Model registry** - 500+ models with capability detection and auto provider resolution
+
+## Error Handling
+
+The adapter maps RubyLLM errors to DSPy error types:
+
+| RubyLLM Error | DSPy Error |
+|---------------|------------|
+| `UnauthorizedError` | `MissingAPIKeyError` |
+| `RateLimitError` | `AdapterError` (with retry hint) |
+| `ModelNotFoundError` | `AdapterError` |
+| `BadRequestError` | `AdapterError` |
+| `ConfigurationError` | `ConfigurationError` |

data/lib/dspy/ruby_llm/guardrails.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'dspy/lm/errors'
+
+module DSPy
+  module RubyLLM
+    class Guardrails
+      SUPPORTED_RUBY_LLM_VERSIONS = "~> 1.3".freeze
+
+      def self.ensure_ruby_llm_installed!
+        require 'ruby_llm'
+
+        spec = Gem.loaded_specs["ruby_llm"]
+        unless spec && Gem::Requirement.new(SUPPORTED_RUBY_LLM_VERSIONS).satisfied_by?(spec.version)
+          msg = <<~MSG
+            DSPy requires the `ruby_llm` gem #{SUPPORTED_RUBY_LLM_VERSIONS}.
+            Please install or upgrade it with `bundle add ruby_llm --version "#{SUPPORTED_RUBY_LLM_VERSIONS}"`.
+          MSG
+          raise DSPy::LM::UnsupportedVersionError, msg
+        end
+      end
+    end
+  end
+end

data/lib/dspy/ruby_llm/lm/adapters/ruby_llm_adapter.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'ruby_llm'
+require 'dspy/lm/adapter'
+require 'dspy/lm/vision_models'
+
+require 'dspy/ruby_llm/guardrails'
+DSPy::RubyLLM::Guardrails.ensure_ruby_llm_installed!
+
+module DSPy
+  module RubyLLM
+    module LM
+      module Adapters
+        class RubyLLMAdapter < DSPy::LM::Adapter
+          attr_reader :provider
+
+          # Options that require a scoped context instead of global RubyLLM config
+          SCOPED_OPTIONS = %i[base_url timeout max_retries].freeze
+
+          def initialize(model:, api_key: nil, **options)
+            @api_key = api_key
+            @options = options
+            @structured_outputs_enabled = options.fetch(:structured_outputs, true)
+            @provider_override = options[:provider] # Optional provider override
+
+            # Detect provider eagerly (matches OpenAI/Anthropic/Gemini adapters)
+            @provider = detect_provider(model)
+
+            # Determine if we should use global RubyLLM config or create scoped context
+            @use_global_config = should_use_global_config?(api_key, options)
+
+            super(model: model, api_key: api_key)
+
+            # Only validate API key if not using global config
+            unless @use_global_config
+              validate_api_key_for_provider!(api_key)
+            end
+
+            # Validate base_url if provided
+            validate_base_url!(@options[:base_url])
+          end
+
+          # Returns the context - either scoped or global
+          def context
+            @context ||= @use_global_config ? nil : create_context(@api_key)
+          end
+
+          def chat(messages:, signature: nil, &block)
+            normalized_messages = normalize_messages(messages)
+
+            # Validate vision support if images are present
+            if contains_images?(normalized_messages)
+              validate_vision_support!
+              normalized_messages = format_multimodal_messages(normalized_messages)
+            end
+
+            chat_instance = create_chat_instance
+
+            if block_given?
+              stream_response(chat_instance, normalized_messages, signature, &block)
+            else
+              standard_response(chat_instance, normalized_messages, signature)
+            end
+          rescue ::RubyLLM::UnauthorizedError => e
+            raise DSPy::LM::MissingAPIKeyError.new(provider)
+          rescue ::RubyLLM::RateLimitError => e
+            raise DSPy::LM::AdapterError, "Rate limit exceeded for #{provider}: #{e.message}"
+          rescue ::RubyLLM::ModelNotFoundError => e
+            raise DSPy::LM::AdapterError, "Model not found: #{e.message}. Check available models with RubyLLM.models.all"
+          rescue ::RubyLLM::BadRequestError => e
+            raise DSPy::LM::AdapterError, "Invalid request to #{provider}: #{e.message}"
+          rescue ::RubyLLM::ConfigurationError => e
+            raise DSPy::LM::ConfigurationError, "RubyLLM configuration error: #{e.message}"
+          rescue ::RubyLLM::Error => e
+            raise DSPy::LM::AdapterError, "RubyLLM error (#{provider}): #{e.message}"
+          end
+
+          private
+
+          # Detect provider from RubyLLM's model registry or use explicit override
+          def detect_provider(model_id)
+            return @provider_override.to_s if @provider_override
+
+            model_info = ::RubyLLM.models.find(model_id)
+            model_info.provider.to_s
+          rescue ::RubyLLM::ModelNotFoundError
+            raise DSPy::LM::ConfigurationError,
+              "Model '#{model_id}' not found in RubyLLM registry. " \
+              "Use provider: option to specify explicitly, or run RubyLLM.models.refresh!"
+          end
+
+          # Check if we should use RubyLLM's global configuration
+          # Uses global config when no api_key and no provider-specific options provided
+          def should_use_global_config?(api_key, options)
+            api_key.nil? && (options.keys & SCOPED_OPTIONS).empty?
+          end
+
+          # Validate API key for providers that require it
+          def validate_api_key_for_provider!(api_key)
+            # Ollama and some local providers don't require API keys
+            return if provider_allows_no_api_key?
+
+            validate_api_key!(api_key, provider)
+          end
+
+          def provider_allows_no_api_key?
+            %w[ollama gpustack].include?(provider)
+          end
+
+          def validate_base_url!(url)
+            return if url.nil?
+
+            uri = URI.parse(url)
+            unless %w[http https].include?(uri.scheme)
+              raise DSPy::LM::ConfigurationError, "base_url must use http or https scheme"
+            end
+          rescue URI::InvalidURIError
+            raise DSPy::LM::ConfigurationError, "Invalid base_url format: #{url}"
+          end
+
+          def create_context(api_key)
+            ::RubyLLM.context do |config|
+              configure_provider(config, api_key)
+              configure_connection(config)
+            end
+          end
+
+          # Configure RubyLLM using convention: {provider}_api_key and {provider}_api_base
+          # For providers with non-standard auth (bedrock, vertexai), configure RubyLLM globally
+          def configure_provider(config, api_key)
+            key_method = "#{provider}_api_key="
+            config.send(key_method, api_key) if api_key && config.respond_to?(key_method)
+
+            base_method = "#{provider}_api_base="
+            config.send(base_method, @options[:base_url]) if @options[:base_url] && config.respond_to?(base_method)
+          end
+
+          def configure_connection(config)
+            config.request_timeout = @options[:timeout] if @options[:timeout]
+            config.max_retries = @options[:max_retries] if @options[:max_retries]
+          end
+
+          def create_chat_instance
+            chat_options = { model: model }
+
+            # If provider is explicitly overridden, pass it to RubyLLM
+            if @provider_override
+              chat_options[:provider] = @provider_override.to_sym
+              chat_options[:assume_model_exists] = true
+            end
+
+            # Use global RubyLLM config or scoped context
+            if @use_global_config
+              ::RubyLLM.chat(**chat_options)
+            else
+              context.chat(**chat_options)
+            end
+          end
+
+          def standard_response(chat_instance, messages, signature)
+            chat_instance = prepare_chat_instance(chat_instance, messages, signature)
+            content, attachments = prepare_message_content(messages)
+            return build_empty_response unless content
+
+            response = send_message(chat_instance, content, attachments)
+            map_response(response)
+          end
+
+          def stream_response(chat_instance, messages, signature, &block)
+            chat_instance = prepare_chat_instance(chat_instance, messages, signature)
+            content, attachments = prepare_message_content(messages)
+            return build_empty_response unless content
+
+            response = send_message(chat_instance, content, attachments, &block)
+            map_response(response)
+          end
+
+          # Common setup: apply system instructions, build conversation history, and optional schema
+          def prepare_chat_instance(chat_instance, messages, signature)
+            # First, handle system messages via with_instructions for proper system prompt handling
+            system_message = messages.find { |m| m[:role] == 'system' }
+            chat_instance = chat_instance.with_instructions(system_message[:content]) if system_message
+
+            # Build conversation history by adding all non-system messages except the last user message
+            # The last user message will be passed to ask() to get the response
+            messages_to_add = messages.reject { |m| m[:role] == 'system' }
+
+            # Find the index of the last user message
+            last_user_index = messages_to_add.rindex { |m| m[:role] == 'user' }
+
+            if last_user_index && last_user_index > 0
+              # Add all messages before the last user message to build history
+              messages_to_add[0...last_user_index].each do |msg|
+                content, attachments = extract_content_and_attachments(msg)
+                next unless content
+
+                # Add message with appropriate role
+                if attachments.any?
+                  chat_instance.add_message(role: msg[:role].to_sym, content: content, attachments: attachments)
+                else
+                  chat_instance.add_message(role: msg[:role].to_sym, content: content)
+                end
+              end
+            end
+
+            if signature && @structured_outputs_enabled
+              schema = build_json_schema(signature)
+              chat_instance = chat_instance.with_schema(schema) if schema
+            end
+
+            chat_instance
+          end
+
+          # Extract content from last user message
+          # RubyLLM's Chat API builds conversation history via add_message() for previous turns,
+          # and the last user message is passed to ask() to get the response.
+          def prepare_message_content(messages)
+            last_user_message = messages.reverse.find { |m| m[:role] == 'user' }
+            return [nil, []] unless last_user_message
+
+            extract_content_and_attachments(last_user_message)
+          end
+
+          # Send message with optional streaming block
+          def send_message(chat_instance, content, attachments, &block)
+            kwargs = attachments.any? ? { with: attachments } : {}
+
+            if block_given?
+              chat_instance.ask(content, **kwargs) do |chunk|
+                block.call(chunk.content) if chunk.content
+              end
+            else
+              chat_instance.ask(content, **kwargs)
+            end
+          end
+
+          def extract_content_and_attachments(message)
+            content = message[:content]
+            attachments = []
+
+            if content.is_a?(Array)
+              text_parts = []
+              content.each do |item|
+                case item[:type]
+                when 'text'
+                  text_parts << item[:text]
+                when 'image'
+                  # Extract image URL or path
+                  image = item[:image]
+                  if image.respond_to?(:url)
+                    attachments << image.url
+                  elsif image.respond_to?(:path)
+                    attachments << image.path
+                  elsif item[:image_url]
+                    attachments << item[:image_url][:url]
+                  end
+                end
+              end
+              content = text_parts.join("\n")
+            end
+
+            [content.to_s, attachments]
+          end
+
+          def map_response(ruby_llm_response)
+            DSPy::LM::Response.new(
+              content: ruby_llm_response.content.to_s,
+              usage: build_usage(ruby_llm_response),
+              metadata: build_metadata(ruby_llm_response)
+            )
+          end
+
+          def build_usage(response)
+            input_tokens = response.input_tokens || 0
+            output_tokens = response.output_tokens || 0
+
+            DSPy::LM::Usage.new(
+              input_tokens: input_tokens,
+              output_tokens: output_tokens,
+              total_tokens: input_tokens + output_tokens
+            )
+          end
+
+          def build_metadata(response)
+            DSPy::LM::ResponseMetadataFactory.create('ruby_llm', {
+              model: response.model_id || model,
+              underlying_provider: provider
+            })
+          end
+
+          def build_empty_response
+            DSPy::LM::Response.new(
+              content: '',
+              usage: DSPy::LM::Usage.new(input_tokens: 0, output_tokens: 0, total_tokens: 0),
+              metadata: DSPy::LM::ResponseMetadataFactory.create('ruby_llm', {
+                model: model,
+                underlying_provider: provider
+              })
+            )
+          end
+
+          def build_json_schema(signature)
+            return nil unless signature.respond_to?(:json_schema)
+
+            schema = signature.json_schema
+            normalize_schema(schema)
+          end
+
+          def normalize_schema(schema)
+            return schema unless schema.is_a?(Hash)
+
+            @normalized_schema_cache ||= {}
+            cache_key = schema.hash
+
+            @normalized_schema_cache[cache_key] ||= begin
+              duped = deep_dup(schema)
+              add_additional_properties_false(duped)
+              duped.freeze
+            end
+          end
+
+          def add_additional_properties_false(schema)
+            return unless schema.is_a?(Hash)
+
+            if schema[:type] == 'object' || schema['type'] == 'object'
+              schema[:additionalProperties] = false
+              schema['additionalProperties'] = false
+            end
+
+            # Recursively process nested schemas
+            schema.each_value { |v| add_additional_properties_false(v) if v.is_a?(Hash) }
+
+            # Handle arrays with items
+            if schema[:items]
+              add_additional_properties_false(schema[:items])
+            elsif schema['items']
+              add_additional_properties_false(schema['items'])
+            end
+          end
+
+          def deep_dup(obj)
+            case obj
+            when Hash
+              obj.transform_values { |v| deep_dup(v) }
+            when Array
+              obj.map { |v| deep_dup(v) }
+            else
+              obj
+            end
+          end
+
+          def validate_vision_support!
+            # RubyLLM handles vision validation internally, but we can add
+            # additional DSPy-specific validation here if needed
+            DSPy::LM::VisionModels.validate_vision_support!(provider, model)
+          rescue DSPy::LM::IncompatibleImageFeatureError
+            # If DSPy doesn't know about the model, let RubyLLM handle it
+            # RubyLLM has its own model registry with capability detection
+          end
+
+          def format_multimodal_messages(messages)
+            messages.map do |msg|
+              if msg[:content].is_a?(Array)
+                formatted_content = msg[:content].map do |item|
+                  case item[:type]
+                  when 'text'
+                    { type: 'text', text: item[:text] }
+                  when 'image'
+                    # Validate and format image for provider
+                    image = item[:image]
+                    if image.respond_to?(:validate_for_provider!)
+                      image.validate_for_provider!(provider)
+                    end
+                    item
+                  else
+                    item
+                  end
+                end
+
+                { role: msg[:role], content: formatted_content }
+              else
+                msg
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dspy/ruby_llm/version.rb

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

data/lib/dspy/ruby_llm.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'dspy/ruby_llm/version'
+
+require 'dspy/ruby_llm/guardrails'
+DSPy::RubyLLM::Guardrails.ensure_ruby_llm_installed!
+
+require 'dspy/ruby_llm/lm/adapters/ruby_llm_adapter'

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: dspy-ruby_llm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vicente Reig Rincón de Arellano
+- Kieran Klaassen
+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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.30'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  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'
+description: Provides a unified adapter using RubyLLM to access OpenAI, Anthropic,
+  Gemini, Bedrock, Ollama, and more through a single interface in DSPy.rb projects.
+email:
+- hey@vicente.services
+- kieranklaassen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dspy/ruby_llm.rb
+- lib/dspy/ruby_llm/README.md
+- lib/dspy/ruby_llm/guardrails.rb
+- lib/dspy/ruby_llm/lm/adapters/ruby_llm_adapter.rb
+- lib/dspy/ruby_llm/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.9
+specification_version: 4
+summary: RubyLLM adapter for DSPy.rb - unified access to 12+ LLM providers.
+test_files: []