ruby_llm-instructor 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efe5592fe81d6feb6e5a328c56ae00bca1bb3f8007826da4440d1bc042f12c7e
-  data.tar.gz: 0d5b70673f1da2ef41686603c1c50bb237cb6d7dd338d921f5ed894c38dcb2a0
+  metadata.gz: ad714a8bf1c0fdec80e73420156ddc0d93fa9e48a82b81078918a2ab19e34651
+  data.tar.gz: 539d055dbb5dba7937fdd040b740329edcf1f794259963438ef777538a79c7db
 SHA512:
-  metadata.gz: 8b0fb08a2c1c5f93639cfa79256029c3433b6ec4459d28082a69373464d08b6d4cc743b9617e7a4fb5eb1856f68f5cdad4efe3bd7d174753b42ca7d7e5aab7b7
-  data.tar.gz: 0a536fbab7e9f6420e8d9899ec30d78232c4f55af2dd6ed5ce62b154dc7b22607196291c88e39c60ddeed6eefecb46e568e5375e5dcdf0682a39ff0ca3e976b6
+  metadata.gz: 36ef7c3fcbf4bedc8eb415e57d0858691e2a8710f558642d04a4fa5c367ef1c6ca41bf85b15dfd82ebf2d45e088ab45069bc8cdf0b5b3182f64b9d1b936de24f
+  data.tar.gz: d3bd594ecdecadc5c603f5eb70d8ca79e15a08de79a29765664a7fa36eb57000afb17dcd55a0b0c9a530ad2c7c6861165df28a58e558e825d96863cc179e67f5

data/README.md

@@ -189,9 +189,15 @@ person.frozen? # => true
 
 ### Struct
 
+Both `keyword_init: true` and positional structs are supported:
+
 ```ruby
+# keyword_init (recommended)
 Address = Struct.new(:street, :city, :zip, keyword_init: true)
 
+# positional — also works
+Point = Struct.new(:x, :y)
+
 address = instructor.chat(
   model: "gpt-4o",
   response_model: Address,
@@ -246,6 +252,7 @@ instructor.chat(
 By default `ruby_llm-instructor` uses `mode: :schema` — structured output via the
 provider's native JSON schema constraint. Pass `mode: :tools` to use function
 calling instead, which works with older models that pre-date structured output.
+Passing any other value raises `ArgumentError` immediately.
 
 ```ruby
 # Default — structured output (recommended for modern models)
@@ -258,9 +265,8 @@ instructor.chat(model: "gpt-3.5-turbo", response_model: MyModel, prompt: "...",
 ## Auto-retry on validation failure
 
 When the LLM returns data that fails `valid?`, `ruby_llm-instructor` feeds the
-error messages back to the model and asks for a corrected response — up to
-`max_retries` times (default: 3). If all retries are exhausted, a `RuntimeError`
-is raised.
+error messages back to the model — along with the original task — and asks for a
+corrected response. This repeats up to `max_retries` times (default: 3).
 
 ```ruby
 instructor.chat(
@@ -271,6 +277,18 @@ instructor.chat(
 )
 ```
 
+If all retries are exhausted a `RubyLLM::Instructor::ValidationError` is raised
+(a `StandardError` subclass), carrying the final validation message:
+
+```ruby
+begin
+  instructor.chat(model: "gpt-4o", response_model: LeadCapture, prompt: "...")
+rescue RubyLLM::Instructor::ValidationError => e
+  # e.message => "ruby_llm-instructor failed validation after 3 attempts. Errors: ..."
+  Rails.logger.warn("LLM extraction failed: #{e.message}")
+end
+```
+
 ## One model, any provider
 
 The `model:` string is passed straight through to `ruby_llm`:
@@ -286,13 +304,15 @@ instructor.chat(model: "claude-3-5-sonnet", ...)
 instructor.chat(model: "llama3", ...)
 ```
 
-## What's in v0.1
+## What's in v0.2
 
 - All `ruby_llm`-supported providers (OpenAI, Anthropic, Gemini, Ollama, …)
-- Response models: PORO, ActiveModel, native dry-validation contract, duck-typed dry-v bridge, `Data.define`, `Struct`, custom `to_json_schema`
+- Response models: PORO, ActiveModel, native dry-validation contract, duck-typed dry-v bridge, `Data.define`, `Struct` (keyword and positional), custom `to_json_schema`
 - Type inference from `ActiveModel::Attributes` (integer, number, boolean)
 - Required vs. optional fields from presence validators
-- Automatic retry-on-validation-failure with corrective prompt
+- Automatic retry-on-validation-failure with corrective prompt (original task preserved on each retry)
+- `RubyLLM::Instructor::ValidationError` raised on exhaustion — rescueable by type
+- `mode:` validation — `ArgumentError` on unknown values
 - Streaming via `stream:` proc
 - Function-calling fallback via `mode: :tools`
 

data/lib/ruby_llm/instructor/adapters/ruby_llm_schema.rb

@@ -54,11 +54,7 @@ module RubyLLM
         end
 
         def dry_contract?
-          defined?(Dry::Validation::Contract) &&
-            @klass.is_a?(Class) &&
-            @klass < Dry::Validation::Contract
-        rescue TypeError
-          false
+          Utils.dry_contract?(@klass)
         end
 
         def build_dry_contract_schema

data/lib/ruby_llm/instructor/client.rb

@@ -3,7 +3,13 @@
 module RubyLLM
   module Instructor
     class Client
+      VALID_MODES = %i[schema tools].freeze
+
       def chat(model:, response_model:, prompt:, max_retries: 3, stream: nil, mode: :schema)
+        unless VALID_MODES.include?(mode)
+          raise ArgumentError, "Unknown mode #{mode.inspect}. Valid modes are: #{VALID_MODES.join(', ')}"
+        end
+
         compiled_schema = Adapters::RubyLlmSchemaAdapter.new(response_model).build_schema
         current_prompt = prompt
         retries = 0
@@ -28,10 +34,12 @@ module RubyLLM
         rescue ValidationError => e
           if retries < max_retries
             retries += 1
-            current_prompt = "Your structural response failed local validation rules: #{e.message}. Please fix the data matching the schema parameters perfectly."
+            current_prompt = "Original task: #{prompt}\n\n" \
+                             "Your previous response failed validation: #{e.message}. " \
+                             "Please fix the data to match the schema exactly."
             retry
           else
-            raise "ruby_llm-instructor failed validation after #{max_retries} attempts. Errors: #{e.message}"
+            raise ValidationError, "ruby_llm-instructor failed validation after #{max_retries} attempts. Errors: #{e.message}"
           end
         end
       end
@@ -58,11 +66,7 @@ module RubyLLM
       end
 
       def dry_contract?(klass)
-        defined?(Dry::Validation::Contract) &&
-          klass.is_a?(Class) &&
-          klass < Dry::Validation::Contract
-      rescue TypeError
-        false
+        Utils.dry_contract?(klass)
       end
 
       def validate_payload(response_model, parsed_data)
@@ -91,7 +95,13 @@ module RubyLLM
         end
 
         if response_model.respond_to?(:members)
-          response_model.new(**parsed_data.transform_keys(&:to_sym))
+          kwargs = parsed_data.transform_keys(&:to_sym)
+          begin
+            response_model.new(**kwargs)
+          rescue ArgumentError
+            # Positional Struct (no keyword_init:true) — fall back to positional args
+            response_model.new(*response_model.members.map { |m| kwargs[m] })
+          end
         else
           instance = response_model.new
           parsed_data.each do |key, value|

data/lib/ruby_llm/instructor/utils.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Instructor
+    module Utils
+      # Returns true when +klass+ is a Dry::Validation::Contract subclass.
+      # Safely returns false when dry-validation is not loaded or klass is not a
+      # class (e.g. an instance, a module, or a Data object).
+      def dry_contract?(klass)
+        !!(defined?(Dry::Validation::Contract) &&
+           klass.is_a?(Class) &&
+           klass < Dry::Validation::Contract)
+      rescue TypeError
+        false
+      end
+      module_function :dry_contract?
+    end
+  end
+end
+

data/lib/ruby_llm/instructor/version.rb

@@ -1,5 +1,5 @@
 module RubyLLM
   module Instructor
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/ruby_llm/instructor.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 require "ruby_llm"
 require "ruby_llm/schema"
 require "active_model"
 require_relative "instructor/version"
+require_relative "instructor/utils"
 require_relative "instructor/adapters/ruby_llm_schema"
 require_relative "instructor/client"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-instructor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sal Scotto Di Luzio
@@ -30,6 +30,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -37,6 +40,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -132,10 +138,15 @@ files:
 - lib/ruby_llm/instructor.rb
 - lib/ruby_llm/instructor/adapters/ruby_llm_schema.rb
 - lib/ruby_llm/instructor/client.rb
+- lib/ruby_llm/instructor/utils.rb
 - lib/ruby_llm/instructor/version.rb
+homepage: https://github.com/washu/ruby_llm-instructor
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/washu/ruby_llm-instructor
+  changelog_uri: https://github.com/washu/ruby_llm-instructor/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/washu/ruby_llm-instructor/issues
 rdoc_options: []
 require_paths:
 - lib