dspy 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85ae2299dbddc20bfd710c68e9e8dfbeeb201b742e3fd18b768669ddc4443261
-  data.tar.gz: ba0ee2d5f637f499448e456fb58f0513aa58b5b258e754bf1b32839ea8c49b63
+  metadata.gz: abf60ee3b93bfb4b1a66af4bf59c2b6d4422bbe4f6b130f84fcafe03e9817cf3
+  data.tar.gz: 4e5678be47e6b76b974a7cc2dec2adf6a1f5609ac5ac6d07cdfdc3c67f804703
 SHA512:
-  metadata.gz: 310de5ce11b23d29bd168069eae4f5ce3ac154ba91974c96b9d70e5d02a0dcb45122dc4c83f80097a409ff448a0a30d45ebec3ff0883d80b2cdd8f1215d2dfff
-  data.tar.gz: 1ce5ff1bfe900bcedabab28efba1e8352fed81c6cbf458d5b7c54e8f7eea29fa6b7ee33a62dcc73b456ede6181a85bbf055541e4fb70037ac4de05e3be2b8ce9
+  metadata.gz: 91036445e7e1c45c56275722a1c96beb8b716adb2d4036fe6df051a4d554eb47c39dbbc2e6c0994135df3d0000dfca25572b21975d1ac02fa2ff49ce09c183c4
+  data.tar.gz: 302be904ad43e6a64405521d6bf9f02c2539debd252933cf9d9bcebb0fa7c81abb7fa0b26b5abdb1a3502a55abed8f8c3dabb76278ff27813f196e9ae7938cd3

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/lm/adapter_factory.rb

@@ -16,6 +16,13 @@ module DSPy
 
       PROVIDERS_WITH_EXTRA_OPTIONS = %w[openai anthropic ollama gemini openrouter ruby_llm].freeze
 
+      # `reasoning:` is currently implemented only for the Anthropic adapter
+      # (see adr/019-anthropic-reasoning-temperature-config.md). Checked here,
+      # once, so every provider fails the same way instead of each adapter
+      # either raising a raw ArgumentError (no `reasoning:` keyword declared)
+      # or silently ignoring it (RubyLLMAdapter's `**options`).
+      REASONING_SUPPORTED_PROVIDERS = %w[anthropic].freeze
+
       class AdapterData < Data.define(:class_name, :gem_name)
         def self.from_prefix(provider_prefix)
           if ADAPTER_MAP.key?(provider_prefix)
@@ -37,7 +44,9 @@ module DSPy
         def create(model_id, api_key:, **options)
           provider, model = parse_model_id(model_id)
           adapter_class = get_adapter_class(provider)
-          
+          ensure_reasoning_supported!(provider, options)
+          options = normalize_reasoning_option(provider, options)
+
           # Pass provider-specific options
           adapter_options = { model: model, api_key: api_key }
           # Some providers accept additional options
@@ -48,6 +57,27 @@ module DSPy
 
         private
 
+        def ensure_reasoning_supported!(provider, options)
+          return unless options.key?(:reasoning) && !options[:reasoning].nil?
+          return if REASONING_SUPPORTED_PROVIDERS.include?(provider)
+
+          raise DSPy::LM::ConfigurationError,
+            "reasoning: is currently supported only by the Anthropic adapter " \
+            "(got provider: #{provider.inspect}). See adr/019-anthropic-reasoning-temperature-config.md."
+        end
+
+        # `reasoning: nil` on an unsupported provider should behave exactly like
+        # not passing `reasoning:` at all — ensure_reasoning_supported! already
+        # let it through (only a *truthy* reasoning: raises above), but the key
+        # would otherwise still get forwarded into `**options`, and adapters
+        # that don't declare a `reasoning:` keyword (OpenAI, Gemini, Ollama,
+        # OpenRouter) would raise a raw ArgumentError over a value nobody set.
+        def normalize_reasoning_option(provider, options)
+          return options if REASONING_SUPPORTED_PROVIDERS.include?(provider)
+
+          options.reject { |key, _| key == :reasoning }
+        end
+
         # Parse model_id to determine provider and model
         def parse_model_id(model_id)
           unless model_id.include?('/')
@@ -78,11 +108,11 @@ module DSPy
 
         def ensure_adapter_loaded!(provider)
           adapter_data = adapter_data(provider)
-          require adapter_data.require_path
           msg = <<~ERROR
             Adapter not found: #{adapter_data.class_name}.
             Install the #{adapter_data.gem_name} gem and try again.
           ERROR
+          require adapter_data.require_path
         rescue LoadError
           raise MissingAdapterError, msg
         end

data/lib/dspy/lm/json_strategy.rb

@@ -38,7 +38,7 @@ module DSPy
           # OpenAI/Ollama: try to extract JSON from various formats
           extract_json_from_content(response.content)
         elsif adapter_class_name.include?('AnthropicAdapter')
-          # Anthropic: Beta API returns JSON in content, same as OpenAI/Gemini
+          # Anthropic: structured output returns JSON in content, same as OpenAI/Gemini
           extract_json_from_content(response.content)
         elsif adapter_class_name.include?('GeminiAdapter')
           # Gemini: try to extract JSON from various formats
@@ -97,14 +97,17 @@ module DSPy
 
         return unless structured_outputs_enabled
 
-        # Use Anthropic Beta API structured outputs
+        # Structured outputs live under the stable (non-beta) `output_config.format`
+        # shape. `output_format`/`betas` are deprecated by Anthropic in favor of
+        # this (see adr/019-anthropic-reasoning-temperature-config.md); the adapter
+        # merges this with any `reasoning:`-derived effort into a single
+        # `output_config:` hash before calling the Anthropic client.
         schema = DSPy::Anthropic::LM::SchemaConverter.to_beta_format(signature_class)
 
-        request_params[:output_format] = ::Anthropic::Models::Beta::BetaJSONOutputFormat.new(
+        request_params[:output_format] = ::Anthropic::Models::JSONOutputFormat.new(
           type: :json_schema,
           schema: schema
         )
-        request_params[:betas] = ["structured-outputs-2025-11-13"]
       end
 
       # Gemini preparation

data/lib/dspy/lm/reasoning.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  # Shared, provider-agnostic reasoning/thinking configuration.
+  #
+  # Passed to +DSPy::LM.new(..., reasoning: ...)+. Each adapter is responsible
+  # for mapping the resulting struct onto its own provider's request shape and
+  # raising +DSPy::LM::ConfigurationError+ for combinations it can't support
+  # (see the Anthropic adapter's +ModelCapabilities+ registry).
+  #
+  # Exactly one reasoning mode is set per instance (effort tier, manual token
+  # budget, adaptive thinking, or explicitly disabled) — this is a
+  # discriminated union, not a combinable set of options.
+  class Reasoning < T::Struct
+    extend T::Sig
+
+    # Named effort tiers, as documented by Anthropic's `output_config.effort`
+    # (https://platform.claude.com/docs/en/build-with-claude/effort).
+    class Effort < T::Enum
+      enums do
+        Low = new('low')
+        Medium = new('medium')
+        High = new('high')
+        XHigh = new('xhigh')
+        Max = new('max')
+      end
+    end
+
+    const :effort, T.nilable(Effort), default: nil
+    const :budget_tokens, T.nilable(Integer), default: nil
+    const :adaptive, T::Boolean, default: false
+    const :disabled, T::Boolean, default: false
+
+    sig { params(args: T.untyped).void }
+    def initialize(**args)
+      super
+
+      active = {
+        effort: !effort.nil?,
+        budget_tokens: !budget_tokens.nil?,
+        adaptive: adaptive,
+        disabled: disabled
+      }.select { |_, set| set }.keys
+
+      if active.size > 1
+        raise DSPy::LM::ConfigurationError,
+          "DSPy::Reasoning represents exactly one reasoning mode at a time " \
+          "(effort, budget_tokens, adaptive, or disabled), but #{active.size} were set: #{active.join(', ')}."
+      end
+    end
+
+    class << self
+      extend T::Sig
+
+      sig { returns(Reasoning) }
+      def low
+        new(effort: Effort::Low)
+      end
+
+      sig { returns(Reasoning) }
+      def medium
+        new(effort: Effort::Medium)
+      end
+
+      sig { returns(Reasoning) }
+      def high
+        new(effort: Effort::High)
+      end
+
+      sig { returns(Reasoning) }
+      def xhigh
+        new(effort: Effort::XHigh)
+      end
+
+      sig { returns(Reasoning) }
+      def max
+        new(effort: Effort::Max)
+      end
+
+      sig { params(tokens: Integer).returns(Reasoning) }
+      def budget(tokens)
+        new(budget_tokens: tokens)
+      end
+
+      sig { returns(Reasoning) }
+      def adaptive
+        new(adaptive: true)
+      end
+
+      sig { returns(Reasoning) }
+      def disabled
+        new(disabled: true)
+      end
+    end
+  end
+end

data/lib/dspy/lm.rb

@@ -6,6 +6,7 @@ require 'securerandom'
 
 # Load adapter infrastructure
 require_relative 'lm/errors'
+require_relative 'lm/reasoning'
 require_relative 'lm/response'
 require_relative 'lm/adapter'
 require_relative 'lm/adapter_factory'

data/lib/dspy/mixins/type_coercion.rb

@@ -299,9 +299,11 @@ module DSPy
       # Coerces an array value, converting each element as needed
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_array_value(value, prop_type)
-        return value unless value.is_a?(Array)
         return value unless prop_type.is_a?(T::Types::TypedArray)
 
+        value = try_parse_string_to_array(value)
+        return value unless value.is_a?(Array)
+
         element_type = prop_type.type
         value.map { |element| coerce_value_to_type(element, element_type) }
       end
@@ -347,6 +349,18 @@ module DSPy
         value
       end
 
+      # Attempts to parse a JSON string into an Array.
+      # Returns the parsed Array on success, or the original value otherwise.
+      sig { params(value: T.untyped).returns(T.untyped) }
+      def try_parse_string_to_array(value)
+        return value unless value.is_a?(String)
+
+        parsed = JSON.parse(value)
+        parsed.is_a?(Array) ? parsed : value
+      rescue JSON::ParserError
+        value
+      end
+
       # Attempts to parse a JSON string into a Hash.
       # Returns the parsed Hash on success, or the original value otherwise.
       sig { params(value: T.untyped).returns(T.untyped) }

data/lib/dspy/predict.rb

@@ -246,6 +246,11 @@ module DSPy
     sig { params(input_values: T::Hash[Symbol, T.untyped], output_attributes: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
     def create_prediction_result(input_values, output_attributes)
       begin
+        @signature_class.validate_required_fields!(
+          output_attributes,
+          @signature_class.output_field_descriptors
+        )
+
         combined_struct = create_combined_struct_class
         all_attributes = input_values.merge(output_attributes)
         

data/lib/dspy/re_act.rb

@@ -110,6 +110,8 @@ module DSPy
     end
 
     FINISH_ACTION = "finish"
+    THOUGHT_LOOP_INSTRUCTION = "Generate a thought about what to do next to process the given inputs."
+    OBSERVATION_LOOP_INSTRUCTION = "Process the observation from a tool and decide what to do next."
     sig { returns(T.class_of(DSPy::Signature)) }
     attr_reader :original_signature_class
 
@@ -147,6 +149,15 @@ module DSPy
       # Create enhanced output struct with ReAct fields
       @enhanced_output_struct = create_enhanced_output_struct(signature_class)
       enhanced_output_struct = @enhanced_output_struct
+      input_descriptors = signature_class.input_field_descriptors
+      output_descriptors = input_descriptors.merge(signature_class.output_field_descriptors).merge(
+        history: DSPy::Signature::FieldDescriptor.new(
+          T::Array[T::Hash[Symbol, T.untyped]],
+          "ReAct execution history"
+        ),
+        iterations: DSPy::Signature::FieldDescriptor.new(Integer, "Number of iterations executed"),
+        tools_used: DSPy::Signature::FieldDescriptor.new(T::Array[String], "List of tools used during execution")
+      )
 
       # Create enhanced signature class
       enhanced_signature = Class.new(DSPy::Signature) do
@@ -155,9 +166,11 @@ module DSPy
 
         # Use the same input struct
         @input_struct_class = signature_class.input_struct_class
+        @input_field_descriptors = input_descriptors
 
         # Use the enhanced output struct with ReAct fields
         @output_struct_class = enhanced_output_struct
+        @output_field_descriptors = output_descriptors
 
         # Store original signature name
         @original_signature_name = signature_class.name
@@ -198,7 +211,9 @@ module DSPy
     def with_instruction(instruction)
       clone = self.class.new(@original_signature_class, tools: @tools.values, max_iterations: @max_iterations)
       thought_generator = clone.instance_variable_get(:@thought_generator)
+      observation_processor = clone.instance_variable_get(:@observation_processor)
       clone.instance_variable_set(:@thought_generator, thought_generator.with_instruction(instruction))
+      clone.instance_variable_set(:@observation_processor, observation_processor.with_instruction(instruction))
       clone
     end
 
@@ -224,6 +239,14 @@ module DSPy
 
     private
 
+    sig { params(signature_class: T.class_of(DSPy::Signature), loop_instruction: String).returns(String) }
+    def loop_description(signature_class, loop_instruction)
+      [
+        signature_class.description,
+        loop_instruction
+      ].compact.reject(&:empty?).join("\n\n")
+    end
+
     # Serialize value for LLM display
     sig { params(value: T.untyped).returns(T.untyped) }
     def serialize_for_llm(value)
@@ -302,6 +325,13 @@ module DSPy
       action_enum_class = @action_enum_class
       input_context_type = signature_class.input_struct_class || String
 
+      # Carry the user signature's instructions into the loop prompt, then append the
+      # loop mechanics — mirroring Python DSPy's ReAct, which prepends
+      # signature.instructions to the react predictor's instructions. Without this the
+      # user's task description never reaches the LM: it is only set on the enhanced
+      # signature used for typing, which issues no LM calls.
+      thought_description = loop_description(signature_class, THOUGHT_LOOP_INSTRUCTION)
+
       # Get the output field type for the final_answer field
       output_field_name = signature_class.output_struct_class.props.keys.first
       output_field_type = signature_class.output_struct_class.props[output_field_name][:type_object]
@@ -309,7 +339,7 @@ module DSPy
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
-        description "Generate a thought about what to do next to process the given inputs."
+        description thought_description
 
         # Define input fields
         input do
@@ -327,7 +357,7 @@ module DSPy
             description: "Reasoning about what to do next, considering the history and observations."
           const :action, action_enum_class,
             description: "The action to take. MUST be one of the tool names listed in `available_tools` input, or the literal string \"finish\" to provide the final answer."
-          const :tool_input, ToolInput,
+          const :tool_input, ToolInput, default: nil,
             description: "Input for the chosen tool action. Required when action is a tool name. MUST be a JSON object matching the tool's parameter schema. Set to null when action is \"finish\"."
           const :final_answer, T.nilable(output_field_type),
             description: "The final answer to return. Required when action is \"finish\". Must match the expected output type. Set to null when action is a tool name."
@@ -339,10 +369,12 @@ module DSPy
     sig { params(signature_class: T.class_of(DSPy::Signature), data_format: Symbol).returns(T.class_of(DSPy::Signature)) }
     def create_observation_signature(signature_class, data_format)
       input_context_type = signature_class.input_struct_class || String
+      observation_description = loop_description(signature_class, OBSERVATION_LOOP_INSTRUCTION)
+
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
-        description "Process the observation from a tool and decide what to do next."
+        description observation_description
 
         # Define input fields
         input do
@@ -520,6 +552,11 @@ module DSPy
 
       output_data[output_field_name] = deserialized_value
 
+      @signature_class.validate_required_fields!(
+        output_data,
+        @signature_class.output_field_descriptors
+      )
+
       @enhanced_output_struct.new(**output_data)
     end
 

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

data/lib/dspy/scores/data_type.rb

@@ -15,7 +15,7 @@ module DSPy
         Categorical = new('CATEGORICAL')
       end
 
-      sig { params(value: String).returns(DataType) }
+      sig { override.params(value: String).returns(DataType) }
       def self.deserialize(value)
         case value
         when 'NUMERIC' then Numeric

data/lib/dspy/signature.rb

@@ -55,7 +55,7 @@ module DSPy
       sig { returns(T.class_of(T::Struct)) }
       def build_struct_class
         descriptors = @field_descriptors
-        Class.new(T::Struct) do
+        struct_class = Class.new(T::Struct) do
           extend T::Sig
           descriptors.each do |name, descriptor|
             opts = {}
@@ -64,6 +64,22 @@ module DSPy
             const name, descriptor.type, **opts
           end
         end
+
+        struct_class.instance_variable_set(:@dspy_field_descriptors, descriptors)
+
+        # Use a virtual source path so source-comment introspection does not mistake
+        # this generated method for the anonymous struct's class definition.
+        struct_class.singleton_class.class_eval(<<~RUBY, "(dspy-signature-struct)", 1)
+          def new(*args, **kwargs)
+            properties = DSPy::Signature.constructor_properties(args, kwargs)
+            descriptors = instance_variable_get(:@dspy_field_descriptors)
+            DSPy::Signature.validate_required_fields!(properties, descriptors)
+
+            args.empty? ? super(**kwargs) : super(args.first)
+          end
+        RUBY
+
+        struct_class
       end
     end
 
@@ -85,6 +101,26 @@ module DSPy
       sig { returns(T::Hash[Symbol, FieldDescriptor]) }
       attr_reader :output_field_descriptors
 
+      sig { params(args: T.untyped, kwargs: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
+      def constructor_properties(args, kwargs)
+        return kwargs if args.empty?
+        return args.first if args.length == 1 && args.first.is_a?(Hash) && kwargs.empty?
+
+        raise ArgumentError, "Expected properties as keywords or one positional hash, not both"
+      end
+
+      sig { params(properties: T::Hash[T.untyped, T.untyped], descriptors: T::Hash[Symbol, FieldDescriptor]).void }
+      def validate_required_fields!(properties, descriptors)
+        required_fields = descriptors.reject { |_name, descriptor| descriptor.has_default }.keys
+        missing_fields = required_fields.reject do |name|
+          properties.key?(name) || properties.key?(name.to_s)
+        end
+        return if missing_fields.empty?
+
+        names = missing_fields.map(&:inspect).join(', ')
+        raise ArgumentError, "Missing required properties: #{names}"
+      end
+
       sig { params(desc: T.nilable(String)).returns(T.nilable(String)) }
       def description(desc = nil)
         if desc.nil?

data/lib/dspy/tools/toolset.rb

@@ -2,6 +2,7 @@
 
 require 'sorbet-runtime'
 require 'json'
+require_relative 'base'
 require_relative '../type_system/sorbet_json_schema'
 require_relative '../mixins/type_coercion'
 
@@ -193,4 +194,4 @@ module DSPy
       end
     end
   end
-end
+end

data/lib/dspy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DSPy
-  VERSION = "1.0.0"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -177,6 +177,7 @@ files:
 - lib/dspy/lm/json_strategy.rb
 - lib/dspy/lm/message.rb
 - lib/dspy/lm/message_builder.rb
+- lib/dspy/lm/reasoning.rb
 - lib/dspy/lm/response.rb
 - lib/dspy/lm/usage.rb
 - lib/dspy/lm/vision_models.rb