dspy-gemini 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d8c3a914bf14371393cd8666e8fe6dde619beba003ad16513e3ecb077239b06
-  data.tar.gz: fdd2ee0fd8710a95653626ccf32a529fe491efefcb5bbe3f7c4422586a056733
+  metadata.gz: f74542eb4beab2b4b2c3c3931b496c4a0ef8d7e6925fb63dd7bf1b71d770a9c0
+  data.tar.gz: 6d8cdd3ffcadbbea59ebc03c0b199fa79e07aac79a07ba9dc29aba1aa39169fa
 SHA512:
-  metadata.gz: efedc61fd10498ee0efff8f03d1b55c8f9e2407fe7afaad7b99e2489fb184ebbec468a3ffc85054ece684bcaaa8cd8e112ce4a4a64a9ec32e39ad823d8d1256d
-  data.tar.gz: 05203eb5b8bc7b61ec438fb65d0c289c59a2cb7a97dc5e8bd64e195f64f183879392d701da50d94af66fc62b81383b8520125a7181850001e4c3cb19b3fed4c0
+  metadata.gz: f30d06f707b26c85d0497feb334664f553f7f02f5c5fccfd5ecfd9a4ef32d668f6cb1f567a22a772e8f48a5a7cc7ccc462a96abc8ec354161e722717758574d8
+  data.tar.gz: aa30c0732139dc720652735bc5f850a5ba1f39cd2e32082dc0d592a7a61a344143f72160737583cb3e15300a958a87084b7f5612b1029e60dc5559b8cb72b53a

data/README.md

@@ -6,95 +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.
+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')
@@ -104,7 +25,7 @@ class Classify < DSPy::Signature
   end
 
   input do
-    const :sentence, String, description: 'The sentence to analyze'
+    const :sentence, String
   end
 
   output do
@@ -114,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/gemini/README.md

@@ -1,37 +1,52 @@
-# DSPy Gemini adapter gem
+# DSPy Gemini Adapter
 
-`dspy-gemini` provides the Gemini adapter for DSPy.rb so we can rely on Google's API without bloating the core gem. Install it whenever you plan to call `gemini/*` model ids from DSPy.
+`dspy-gemini` lets `DSPy::LM` call model IDs with the `gemini/` prefix. The package is a supported provider adapter; model and SDK capabilities still vary.
 
-## When you need it
-- You call `DSPy::LM.new` with a provider of `gemini`.
-- You want structured outputs, multimodal prompts, or streaming responses backed by Gemini's Generative Language API.
+See the [package and capability matrix](https://oss.vicente.services/dspy.rb/getting-started/packages/) for canonical status and model/SDK boundaries.
 
-Projects that only target OpenAI, Anthropic, or other providers can skip this gem.
+## Prerequisites
 
-## Installation
-Add it beside `dspy` and install dependencies:
+- Ruby 3.3 or newer and Bundler
+- a Gemini API key
+- a Gemini model ID available to your account
 
-```ruby
-# Gemfile
-gem 'dspy'
-gem 'dspy-gemini'
-```
+## Install and Run
 
-```sh
-bundle install
+Add both gems to your `Gemfile`:
+
+```ruby
+gem "dspy"
+gem "dspy-gemini"
 ```
 
-The adapter enforces `gemini-ai ~> 4.3` at runtime (and raises if the dependency is missing or out of range).
+Save this as `gemini_smoke.rb`:
 
-## Configuration
-- Set `ENV['GEMINI_API_KEY']`, or pass `api_key:` directly.
+```ruby
+require "dspy"
 
-## Basic usage
+lm = DSPy::LM.new(
+  ENV.fetch("GEMINI_MODEL"),
+  api_key: ENV.fetch("GEMINI_API_KEY")
+)
 
-```ruby
-require 'dspy'
-# No need to explicitly require 'dspy/gemini'
+response = lm.raw_chat([{ role: "user", content: "Reply with: adapter ready" }])
+puts response.content
+```
 
-lm = DSPy::LM.new('gemini/gemini-1.5-flash', api_key: ENV.fetch('GEMINI_API_KEY'))
+Then install and run it:
 
+```bash
+bundle install
+export GEMINI_API_KEY="your-key"
+export GEMINI_MODEL="gemini/your-model-id"
+bundle exec ruby gemini_smoke.rb
 ```
+
+The command prints the model response. Requiring `dspy` loads the installed adapter for a `gemini/` model; explicit `require "dspy/gemini"` is also supported.
+
+## Failure Conditions
+
+- A missing key raises from `ENV.fetch` before the request.
+- A missing or incompatible `gemini-ai` dependency prevents the adapter from loading.
+- An unavailable model, safety rejection, or invalid request raises an adapter/provider error.
+- Schema, image, safety, and streaming behavior depend on the selected Gemini model and SDK/API version. Verify the exact request; installing the gem does not guarantee every capability.

data/lib/dspy/gemini/lm/adapters/gemini_adapter.rb

@@ -5,9 +5,6 @@ require 'json'
 require 'dspy/lm/vision_models'
 require 'dspy/lm/adapter'
 
-require 'dspy/gemini/guardrails'
-DSPy::Gemini::Guardrails.ensure_gemini_installed!
-
 module DSPy
   module Gemini
     module LM
@@ -52,7 +49,9 @@ module DSPy
             # Validate vision support if images are present
             if contains_images?(normalized_messages)
               DSPy::LM::VisionModels.validate_vision_support!('gemini', model)
-              # Convert messages to Gemini format with proper image handling
+            end
+
+            if contains_media?(normalized_messages)
               normalized_messages = format_multimodal_messages(normalized_messages, 'gemini')
             end
 

data/lib/dspy/gemini/lm/schema_converter.rb

@@ -45,8 +45,8 @@ module DSPy
           # Get the output JSON schema from the signature class
           output_schema = signature_class.output_json_schema
 
-          # Convert to Gemini format (OpenAPI 3.0 Schema subset - not related to OpenAI)
-          convert_dspy_schema_to_gemini(output_schema)
+          # response_json_schema accepts JSON Schema, including nullable type arrays.
+          convert_property_to_gemini(output_schema)
         end
 
         sig { params(model: String).returns(T::Boolean) }
@@ -73,87 +73,34 @@ module DSPy
 
         private
 
-        sig { params(dspy_schema: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
-        def self.convert_dspy_schema_to_gemini(dspy_schema)
-          # For Gemini's responseJsonSchema, we need pure JSON Schema format
-          # Remove OpenAPI-specific fields like "$schema"
-          result = {
-            type: "object",
-            properties: {},
-            required: []
-          }
-
-          # Convert properties
-          properties = dspy_schema[:properties] || {}
-          properties.each do |prop_name, prop_schema|
-            result[:properties][prop_name] = convert_property_to_gemini(prop_schema)
-          end
-
-          # Set required fields
-          result[:required] = (dspy_schema[:required] || []).map(&:to_s)
-
-          result
-        end
-
         sig { params(property_schema: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
         def self.convert_property_to_gemini(property_schema)
-          # Handle oneOf/anyOf schemas (union types) - Gemini supports these in responseJsonSchema
-          if property_schema[:oneOf]
-            return {
-              oneOf: property_schema[:oneOf].map { |schema| convert_property_to_gemini(schema) },
-              description: property_schema[:description]
-            }.compact
-          end
+          # Preserve types and constraints instead of rebuilding nodes from scalar
+          # type names: Sorbet represents nilable fields as type: [type, "null"].
+          result = property_schema.reject { |key, _| key == :"$schema" || key == :const }
 
-          if property_schema[:anyOf]
-            return {
-              anyOf: property_schema[:anyOf].map { |schema| convert_property_to_gemini(schema) },
-              description: property_schema[:description]
-            }.compact
-          end
+          # Keep the existing const-to-enum conversion, including false/null values.
+          result[:enum] = [property_schema[:const]] if property_schema.key?(:const)
 
-          case property_schema[:type]
-          when "string"
-            result = { type: "string" }
-            # Gemini responseJsonSchema doesn't support const, so convert to single-value enum
-            # See: https://ai.google.dev/api/generate-content#FIELDS.response_json_schema
-            if property_schema[:const]
-              result[:enum] = [property_schema[:const]]
-            elsif property_schema[:enum]
-              result[:enum] = property_schema[:enum]
+          [:properties, :"$defs", :definitions].each do |key|
+            if property_schema[key].is_a?(Hash)
+              result[key] = property_schema[key].transform_values { |schema| convert_property_to_gemini(schema) }
             end
-            result
-          when "integer"
-            { type: "integer" }
-          when "number"
-            { type: "number" }
-          when "boolean"
-            { type: "boolean" }
-          when "array"
-            {
-              type: "array",
-              items: convert_property_to_gemini(property_schema[:items] || { type: "string" })
-            }
-          when "object"
-            result = { type: "object" }
-
-            if property_schema[:properties]
-              result[:properties] = {}
-              property_schema[:properties].each do |nested_prop, nested_schema|
-                result[:properties][nested_prop] = convert_property_to_gemini(nested_schema)
-              end
+          end
 
-              # Set required fields for nested objects
-              if property_schema[:required]
-                result[:required] = property_schema[:required].map(&:to_s)
-              end
+          [:items, :additionalProperties].each do |key|
+            if property_schema[key].is_a?(Hash)
+              result[key] = convert_property_to_gemini(property_schema[key])
             end
+          end
 
-            result
-          else
-            # Default to string for unknown types
-            { type: "string" }
+          [:oneOf, :anyOf, :allOf, :prefixItems].each do |key|
+            if property_schema[key].is_a?(Array)
+              result[key] = property_schema[key].map { |schema| convert_property_to_gemini(schema) }
+            end
           end
+
+          result
         end
 
         sig { params(schema: T::Hash[Symbol, T.untyped], current_depth: Integer).returns(Integer) }

data/lib/dspy/gemini/version.rb

@@ -2,6 +2,6 @@
 
 module DSPy
   module Gemini
-    VERSION = '1.0.3'
+    VERSION = '1.0.5'
   end
 end

data/lib/dspy/gemini.rb

@@ -2,8 +2,5 @@
 
 require 'dspy/gemini/version'
 
-require 'dspy/gemini/guardrails'
-DSPy::Gemini::Guardrails.ensure_gemini_installed!
-
 require 'dspy/gemini/lm/adapters/gemini_adapter'
 require 'dspy/gemini/lm/schema_converter'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy-gemini
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -15,28 +15,40 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.30'
+        version: 0.30.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.30'
+        version: 0.30.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: gemini-ai
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 4.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 4.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 description: Provides the GeminiAdapter so Gemini-compatible providers can be added
   to DSPy.rb projects independently of the core gem.
 email:
@@ -49,7 +61,6 @@ files:
 - README.md
 - lib/dspy/gemini.rb
 - lib/dspy/gemini/README.md
-- lib/dspy/gemini/guardrails.rb
 - lib/dspy/gemini/lm/adapters/gemini_adapter.rb
 - lib/dspy/gemini/lm/schema_converter.rb
 - lib/dspy/gemini/version.rb

data/lib/dspy/gemini/guardrails.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-require 'dspy/lm/errors'
-
-module DSPy
-  module Gemini
-    class Guardrails
-      SUPPORTED_GEMINI_VERSIONS = "~> 4.3".freeze
-
-      def self.ensure_gemini_installed!
-        require 'gemini-ai'
-
-        spec = Gem.loaded_specs["gemini-ai"]
-        unless spec && Gem::Requirement.new(SUPPORTED_GEMINI_VERSIONS).satisfied_by?(spec.version)
-          msg = <<~MSG
-            DSPY requires `gemini-ai` gem #{SUPPORTED_GEMINI_VERSIONS}.
-            Please Install or upgrade it with `bundle add gemini-ai --version "#{SUPPORTED_GEMINI_VERSIONS}"`.
-          MSG
-          raise DSPy::LM::UnsupportedVersionError, msg
-        end
-      end
-    end
-  end
-end
-