dspy-ruby_llm 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5131c4c5545dc867c284d046a0f43cf8bb109f9f0417f4154cf9cfad4f73b55b
-  data.tar.gz: c10d6e0614e3bd3ae92d88ef93197e86370d25e9b49d7a4fb946928b3039f5cd
+  metadata.gz: 954de47d2c188958e0f761dc8d4aa62d6c33feacc049f38eb9d3ddd31ba48f18
+  data.tar.gz: 2ccfa1e9a88a273627f717d9b5af87a64e04b478e6e2407e32e2b6a5c71ea50c
 SHA512:
-  metadata.gz: 781466444aae497b51952ec0e2914dc551ef8f6008449bc95676e4fc84a3aec2bebf27f1b5673901c9d8f19c3f86f0f692477ddd98a2ef1bf3faaa55788a0576
-  data.tar.gz: 10b9cdb52396c6f089cdd32c40f41363f463f1e1acc19fcaa741cbf2668e79b8af81f898170afcadfdb0e05aa2dff0b601fa22e67cd2397a448ee9e0ed2e6ec6
+  metadata.gz: 5816b736e227cf2661923d57485b4e1c75d447234523daa07890a1455464590846957505e43be7f3baefecbfc89ac3a910b83b5b984ac0fae5a4b98784e6ee10
+  data.tar.gz: 1b1787a237e8184298635afe70f5b9ba2e99151e3826a715d8805c246996967c0ed4e9cef2a341347d7c5e29b4579ad3e54aa5413452d6fe280bc373c468856a

data/README.md

@@ -6,96 +6,16 @@
 [![Documentation](https://img.shields.io/badge/docs-oss.vicente.services%2Fdspy.rb-blue)](https://oss.vicente.services/dspy.rb/)
 [![Discord](https://img.shields.io/discord/1161519468141355160?label=discord&logo=discord&logoColor=white)](https://discord.gg/zWBhrMqn)
 
-**Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
+**Build typed agents and model-backed programs in Ruby.**
 
-DSPy.rb is the Ruby port of Stanford's [DSPy](https://dspy.ai). Instead of wrestling with brittle prompt strings, you define typed signatures and let the framework handle the rest. Prompts become functions. LLM calls become predictable.
-The `1.x` line is the stable release track for production Ruby LLM applications.
+DSPy.rb brings [DSPy](https://dspy.ai)'s signature, module, agent, and optimizer model to Ruby, with Sorbet types and Ruby-native integrations. A signature declares a task as typed inputs and outputs. A module chooses how to execute it. Ruby composes modules into programs, while `ReAct` adds a bounded loop when the model should choose the next action. DSPy.rb builds the provider request and validates the returned shape.
 
-```ruby
-require 'dspy'
-
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
-end
-
-class Summarize < DSPy::Signature
-  description "Summarize the given text in one sentence."
-
-  input do
-    const :text, String
-  end
-
-  output do
-    const :summary, String
-  end
-end
-
-summarizer = DSPy::Predict.new(Summarize)
-result = summarizer.call(text: "DSPy.rb brings structured LLM programming to Ruby...")
-puts result.summary
-```
-
-That's it. No prompt templates. No JSON parsing. No prayer-based error handling.
-
-## Installation
-
-```ruby
-# Gemfile
-gem 'dspy'
-gem 'dspy-openai'     # For OpenAI, OpenRouter, or Ollama
-# gem 'dspy-anthropic' # For Claude
-# gem 'dspy-gemini'    # For Gemini
-# gem 'dspy-ruby_llm'  # For 12+ providers via RubyLLM
-```
-
-```bash
-bundle install
-```
-
-## Quick Start
-
-### Configure Your LLM
-
-```ruby
-# OpenAI
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-                      api_key: ENV['OPENAI_API_KEY'],
-                      structured_outputs: true)
-end
-
-# Anthropic Claude
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514',
-                      api_key: ENV['ANTHROPIC_API_KEY'])
-end
-
-# Google Gemini
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
-                      api_key: ENV['GEMINI_API_KEY'])
-end
-
-# Ollama (local, free)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('ollama/llama3.2')
-end
-
-# OpenRouter (200+ models)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
-                      api_key: ENV['OPENROUTER_API_KEY'])
-end
-```
-
-### Define a Signature
+The `1.x` series is the current stable release line.
 
-Signatures are typed contracts for LLM operations. Define inputs, outputs, and let DSPy handle the prompt:
+In a configured application, the task contract and call look like this:
 
 ```ruby
 class Classify < DSPy::Signature
-  description "Classify sentiment of a given sentence."
-
   class Sentiment < T::Enum
     enums do
       Positive = new('positive')
@@ -105,7 +25,7 @@ class Classify < DSPy::Signature
   end
 
   input do
-    const :sentence, String, description: 'The sentence to analyze'
+    const :sentence, String
   end
 
   output do
@@ -115,107 +35,39 @@ class Classify < DSPy::Signature
 end
 
 classifier = DSPy::Predict.new(Classify)
-result = classifier.call(sentence: "This book was super fun to read!")
-
-result.sentiment    # => #<Sentiment::Positive>
-result.confidence   # => 0.92
+result = classifier.call(sentence: "This book was fun to read!")
 ```
 
-### Chain of Thought
-
-For complex reasoning, use `ChainOfThought` to get step-by-step explanations:
-
-```ruby
-solver = DSPy::ChainOfThought.new(MathProblem)
-result = solver.call(problem: "If a train travels 120km in 2 hours, what's its speed?")
-
-result.reasoning  # => "Speed = Distance / Time = 120km / 2h = 60km/h"
-result.answer     # => "60 km/h"
-```
+Define a typed task contract instead of maintaining an output template. Receive validated Ruby values instead of parsing provider JSON. Handle configuration, transport, and validation errors explicitly.
 
-### ReAct Agents
-
-Build agents that use tools to accomplish tasks:
-
-```ruby
-class SearchTool < DSPy::Tools::Base
-  tool_name "search"
-  tool_description "Search for information"
-
-  sig { params(query: String).returns(String) }
-  def call(query:)
-    # Your search implementation
-    "Result 1, Result 2"
-  end
-end
-
-agent = DSPy::ReAct.new(ResearchTask, tools: [SearchTool.new], max_iterations: 5)
-result = agent.call(question: "What's the latest on Ruby 3.4?")
-```
+## Start Here
 
-## What's Included
+The [Quick Start](https://oss.vicente.services/dspy.rb/getting-started/quick-start/) is the complete supported path: install the core and provider gems, configure a key, save a program, and run it.
 
-**Core Modules**: Predict, ChainOfThought, ReAct agents, and composable pipelines.
+Use [Installation](https://oss.vicente.services/dspy.rb/getting-started/installation/) to choose a provider. The [package and capability matrix](https://oss.vicente.services/dspy.rb/getting-started/packages/) records exact gem names, require behavior, support labels, and model or SDK boundaries.
 
-**Type Safety**: Sorbet-based runtime validation. Enums, unions, nested structs—all work.
+## Mental Model
 
-**Multimodal**: Image analysis with `DSPy::Image` for vision-capable models.
+- A `DSPy::Signature` defines the task contract.
+- `DSPy::Predict` and other modules choose an execution strategy.
+- Ordinary Ruby owns fixed sequencing, branching, persistence, permissions, and failure policy.
+- Results cross a runtime validation boundary; validation establishes shape, not factual correctness.
 
-**Observability**: Zero-config Langfuse integration via OpenTelemetry. Non-blocking, production-ready.
-
-**Optimization**: MIPROv2 (Bayesian optimization) and GEPA (genetic evolution) for prompt tuning.
-
-**Provider Support**: OpenAI, Anthropic, Gemini, Ollama, and OpenRouter via official SDKs.
-
-## Documentation
-
-**[Full Documentation](https://oss.vicente.services/dspy.rb/)** — Getting started, core concepts, advanced patterns.
-
-**[llms.txt](https://oss.vicente.services/dspy.rb/llms.txt)** — LLM-friendly reference for AI assistants.
-
-### Claude Skill
-
-A [Claude Skill](https://github.com/vicentereig/dspy-rb-skill) is available to help you build DSPy.rb applications:
-
-```bash
-# Claude Code — install from the vicentereig/engineering marketplace
-claude install-skill vicentereig/engineering --skill dspy-rb
-```
-
-For Claude.ai Pro/Max, download the [skill ZIP](https://github.com/vicentereig/dspy-rb-skill/archive/refs/heads/main.zip) and upload via Settings > Skills.
-
-## Examples
-
-The [examples/](examples/) directory has runnable code for common patterns:
-
-- Sentiment classification
-- ReAct agents with tools
-- Image analysis
-- Prompt optimization
-
-```bash
-bundle exec ruby examples/basic_search_agent.rb
-```
+### ReAct Agents
 
-## Optional Gems
+Use `ReAct` when the model needs to choose among typed Ruby tools inside an iteration bound. The application still owns tool authorization, side effects, budgets, and errors. See [Predictors](https://oss.vicente.services/dspy.rb/core-concepts/predictors/) and [Toolsets](https://oss.vicente.services/dspy.rb/core-concepts/toolsets/).
 
-DSPy.rb ships sibling gems for features with heavier dependencies. Add them as needed:
+## Explore
 
-| Gem | What it does |
-| --- | --- |
-| `dspy-datasets` | Dataset helpers, Parquet/Polars tooling |
-| `dspy-evals` | Evaluation harness with metrics and callbacks |
-| `dspy-miprov2` | Bayesian optimization for prompt tuning |
-| `dspy-gepa` | Genetic-Pareto prompt evolution |
-| `dspy-o11y-langfuse` | Auto-configure Langfuse tracing |
-| `dspy-code_act` | Think-Code-Observe agents |
-| `dspy-deep_search` | Production DeepSearch with Exa |
+- [Documentation](https://oss.vicente.services/dspy.rb/) — task-oriented guides and reference
+- [Examples](examples/) — repository demos indexed by capability and prerequisites
+- [llms.txt](https://oss.vicente.services/dspy.rb/llms.txt) — generated reference for AI assistants
 
-See [the full list](https://oss.vicente.services/dspy.rb/getting-started/installation/) in the docs.
+Provider adapters, optimizers, observability exporters, datasets, and code-executing agents are separate packages when they add dependencies. Check the package matrix before selecting one; package availability does not guarantee uniform provider or model behavior.
 
 ## Contributing
 
-Feedback is invaluable. If you encounter issues, [open an issue](https://github.com/vicentereig/dspy.rb/issues). For suggestions, [start a discussion](https://github.com/vicentereig/dspy.rb/discussions).
+For bugs, [open an issue](https://github.com/vicentereig/dspy.rb/issues). For suggestions, [start a discussion](https://github.com/vicentereig/dspy.rb/discussions).
 
 Want to contribute code? Reach out: hey at vicente.services
 

data/lib/dspy/ruby_llm/README.md

@@ -1,174 +1,53 @@
-# DSPy RubyLLM Adapter
+# DSPy RubyLLM Adapter (Preview)
 
-Unified access to 12+ LLM providers through a single adapter using [RubyLLM](https://rubyllm.com).
+`dspy-ruby_llm` delegates model lookup, provider selection, request transport, and capability discovery to [RubyLLM](https://rubyllm.com). The package is preview: provider coverage is not a uniform capability promise.
 
-## Installation
+See the [package and capability matrix](https://oss.vicente.services/dspy.rb/getting-started/packages/) for canonical status and the files shared with the core gem.
 
-Add to your Gemfile:
+## Prerequisites
 
-```ruby
-gem 'dspy-ruby_llm'
-```
-
-## Usage
+- Ruby, Bundler, and `gem "dspy-ruby_llm"`
+- RubyLLM credentials and configuration for the selected provider
+- a model ID recognized by RubyLLM, or an explicit `provider:` override
 
-### Using Existing RubyLLM Configuration (Recommended)
-
-If you already have RubyLLM configured, DSPy will use your existing setup automatically:
+## Install and Run
 
 ```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")
+gem "dspy-ruby_llm"
 ```
 
-### Model ID Format
-
-Use `ruby_llm/{model_id}` format where `model_id` is the RubyLLM model identifier:
+Save this as `ruby_llm_smoke.rb`:
 
 ```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")
+require "dspy"
+require "dspy/ruby_llm"
 
-# 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'
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
 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')
+lm = DSPy::LM.new("ruby_llm/gpt-4o")
+response = lm.raw_chat([{ role: "user", content: "Reply with: adapter ready" }])
+puts response.content
 ```
 
-### 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)
-)
+```bash
+bundle install
+export OPENAI_API_KEY="your-key"
+bundle exec ruby ruby_llm_smoke.rb
 ```
 
-For providers with non-standard auth (Bedrock, VertexAI), configure RubyLLM globally - see examples above.
+The command prints the provider response. DSPy reuses RubyLLM's global configuration only when the `DSPy::LM` call does not supply `api_key`, `base_url`, `timeout`, or `max_retries` overrides. Supplying any of those options creates a scoped adapter configuration.
 
-### With DSPy Signatures
+For a model absent from RubyLLM's registry, specify the provider explicitly:
 
 ```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
+lm = DSPy::LM.new("ruby_llm/my-model", provider: "ollama")
 ```
 
-### 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:
+## Capability and Failure Boundaries
 
-| RubyLLM Error | DSPy Error |
-|---------------|------------|
-| `UnauthorizedError` | `MissingAPIKeyError` |
-| `RateLimitError` | `AdapterError` (with retry hint) |
-| `ModelNotFoundError` | `AdapterError` |
-| `BadRequestError` | `AdapterError` |
-| `ConfigurationError` | `ConfigurationError` |
+- A missing RubyLLM credential or unknown model/provider fails before or during the request.
+- Registry data and capability detection vary with the installed RubyLLM version.
+- Authentication, attachments, schemas, streaming, retries, and request options vary by underlying provider and model; document input is currently restricted to Anthropic.
+- Error mapping preserves a DSPy boundary, but provider-specific details still come from RubyLLM and its SDKs. Test the exact model and request your application will use.

data/lib/dspy/ruby_llm/version.rb

@@ -2,6 +2,6 @@
 
 module DSPy
   module RubyLLM
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy-ruby_llm
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -86,5 +86,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: RubyLLM adapter for DSPy.rb - unified access to 12+ LLM providers.
+summary: RubyLLM provider adapter for DSPy.rb.
 test_files: []