squishling 0.2.0 → 0.3.0

data/lib/squishling/llm_client.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Squishling
+  # RubyLLM requests for one squished method, with RubyLLM's errors mapped onto Squishling's taxonomy.
+  class LLMClient
+    # Where RubyLLM's own code lives, to tell its ArgumentErrors from the developer's (see #judge).
+    RUBY_LLM_LIB = File.dirname(RubyLLM.method(:judge).source_location.first)
+    private_constant :RUBY_LLM_LIB
+
+    # Runs each job on its own thread and returns, in order, each job's [value, exception]. Only provider
+    # requests run here: parsing, validation, and the developer's callbacks stay on the caller's thread. Fiber
+    # storage (RubyLLM's usage owner) is inherited by the threads, and RubyLLM's instrumentation context is
+    # carried over the way RubyLLM's own concurrent tool calls do it. Unlike those, the threads don't enter the
+    # Rails executor: the caller already holds it, and a second share can deadlock against a pending code reload.
+    # If the caller is interrupted while waiting (a timeout, Thread#raise), the requests still running are
+    # stopped rather than left running unobserved.
+    def self.concurrently(jobs)
+      return jobs.map { |job| capture(job) } if jobs.size < 2
+
+      context = instrumentation_context
+      threads = jobs.map do |job|
+        thread = Thread.new { with_instrumentation_context(context) { capture(job) } }
+        thread.report_on_exception = false
+        thread
+      end
+      threads.map(&:value)
+    ensure
+      threads&.each { |thread| thread.kill.join if thread.alive? }
+    end
+
+    def self.capture(job)
+      [job.call, nil]
+    rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised on the caller's thread
+      [nil, e]
+    end
+
+    def self.instrumentation_context
+      instrumentation = defined?(RubyLLM::Support::Instrumentation) && RubyLLM::Support::Instrumentation
+      return unless instrumentation.respond_to?(:current_workflow) && instrumentation.respond_to?(:capture_context)
+
+      [instrumentation.current_workflow, instrumentation.capture_context]
+    end
+
+    def self.with_instrumentation_context(context, &)
+      return yield unless context
+
+      instrumentation = RubyLLM::Support::Instrumentation
+      instrumentation.with_workflow(context.first) { instrumentation.with_context(context.last, &) }
+    end
+
+    private_class_method :capture, :instrumentation_context, :with_instrumentation_context
+
+    def initialize(label)
+      @label = label
+    end
+
+    # A fresh chat on one escalation step, with the system prompt, the strict output schema, and its params.
+    def chat(step, instructions:, schema:)
+      chat = build_chat(step)
+      chat.with_instructions(instructions)
+      chat.with_schema(schema)
+      apply_params(chat, step.params)
+      chat
+    end
+
+    # Transient HTTP failures are already retried by RubyLLM (RubyLLM.config.max_retries); anything
+    # that still fails is surfaced as an LLMError, which moves on to the next attempt of the
+    # escalation (or propagates from the last one). A 400 means the request we built is invalid (an
+    # unsupported param, a schema the provider rejects), so it's a setup mistake: escalating or a
+    # fallback would otherwise hide it on every call.
+    def ask(chat, message, step)
+      request(step) { chat.ask(message) }
+    end
+
+    # A System One judgment (RubyLLM.judge) on one step. The step's params are sent as provider options.
+    # RubyLLM raises ArgumentError for a judgment it can't build (e.g. a model on a provider that takes none, or
+    # a provider option its protocol reserves), and a bare RubyLLM::Error without an HTTP response for a provider
+    # that doesn't support judgments at all. An ArgumentError from anywhere else (an instrumentation subscriber
+    # runs inside the call) is the developer's own and propagates as-is.
+    def judge(input, questions:, step:)
+      request(step) do
+        RubyLLM.judge(input, questions:, provider_options: step.params, **model_options(step))
+      rescue RubyLLM::ModelNotFoundError => e
+        raise ConfigurationError, "#{@label}: #{e.message}"
+      rescue ArgumentError => e
+        raise unless raised_by_ruby_llm?(e)
+
+        raise ConfigurationError, "#{@label}: #{e.message}"
+      rescue RubyLLM::Error => e
+        raise unless e.instance_of?(RubyLLM::Error) && e.response.nil?
+
+        raise ConfigurationError, "#{@label}: #{e.message}"
+      end
+    end
+
+    private
+
+    def raised_by_ruby_llm?(error)
+      error.backtrace&.first&.start_with?("#{RUBY_LLM_LIB}/") || false
+    end
+
+    def build_chat(step)
+      RubyLLM.chat(**model_options(step))
+    rescue RubyLLM::ModelNotFoundError, RubyLLM::ConfigurationError => e
+      raise ConfigurationError, "#{@label}: #{e.message}"
+    end
+
+    # RubyLLM validates some settings locally (e.g. an impossible thinking budget for the model)
+    # and raises ArgumentError before any request is sent.
+    def apply_params(chat, params)
+      Params.apply(chat, params)
+    rescue ArgumentError => e
+      raise ConfigurationError, "#{@label}: invalid params #{params.inspect} (#{e.message})"
+    end
+
+    def request(step)
+      yield
+    rescue RubyLLM::ConfigurationError, RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
+      raise ConfigurationError, "#{@label}: #{e.class}: #{e.message}"
+    rescue RubyLLM::BadRequestError => e
+      raise ConfigurationError,
+        "#{@label}: the provider rejected the request (#{e.message})#{params_hint(step.params)}"
+    rescue RubyLLM::Error, Faraday::Error => e
+      raise LLMError, "#{@label}: #{e.class}: #{e.message}"
+    end
+
+    # Models missing from RubyLLM's registry (e.g. newly released ones) are only usable when a
+    # provider is named, so RubyLLM is told to assume they exist.
+    def model_options(step)
+      model = step.model
+      provider = step.provider
+      options = { model:, provider: }.compact
+      options[:assume_model_exists] = true if model && provider && !known_model?(model, provider)
+      options
+    end
+
+    def known_model?(model, provider)
+      RubyLLM.models.find(model, provider:)
+      true
+    rescue RubyLLM::ModelNotFoundError
+      false
+    end
+
+    def params_hint(params)
+      return "" if params.empty?
+
+      ". Check params #{params.inspect}; reasoning models often reject sampling params such as temperature and top_p"
+    end
+  end
+end

data/lib/squishling/model_path.rb

@@ -9,12 +9,19 @@ module Squishling
   #     { model: "claude-opus-5-5", params: { thinking: { effort: :high } } }
   #   ]
   # attempts: (default 1) retries a step; order: (all steps or none, unique, lowest first) makes the order
-  # explicit instead of positional.
+  # explicit instead of positional. forward_rejected: false starts a step from the original input alone, without
+  # the previous step's rejected output.
   module ModelPath
-    # One attempt: the model, its provider, and the fully resolved generation params.
-    Step = Data.define(:model, :provider, :params)
+    # One attempt: the model, its provider, the fully resolved generation params, and whether the previous
+    # step's rejected output is shown to it.
+    Step = Data.define(:model, :provider, :params, :forward_rejected) do
+      # The model for logs and messages (nil means RubyLLM's default model).
+      def display_name
+        model || "RubyLLM default model"
+      end
+    end
 
-    STEP_KEYS = %i[model provider params attempts order].freeze
+    STEP_KEYS = %i[model provider params attempts order forward_rejected].freeze
 
     module_function
 
@@ -54,7 +61,7 @@ module Squishling
     def steps(path, provider:, params:)
       path.flat_map do |step|
         attempt = Step.new(model: step[:model], provider: step[:provider] || provider,
-          params: Params.resolve(params, step[:params]))
+          params: Params.resolve(params, step[:params]), forward_rejected: step[:forward_rejected])
         [attempt] * step[:attempts]
       end
     end
@@ -76,7 +83,8 @@ module Squishling
 
     def normalize_step(step, label)
       case step
-      when String, Symbol then { model: model_name(step, label), provider: nil, params: nil, attempts: 1 }
+      when String, Symbol
+        { model: model_name(step, label), provider: nil, params: nil, attempts: 1, forward_rejected: true }
       when Hash then normalize_hash(step, label)
       else
         raise ConfigurationError, "#{label}: each step must be a model name or a Hash with model:, got #{step.inspect}"
@@ -100,8 +108,14 @@ module Squishling
         raise ConfigurationError, "#{label} (#{model}): order: must be an Integer, got #{step[:order].inspect}"
       end
 
+      forward_rejected = step.fetch(:forward_rejected, true)
+      unless [true, false].include?(forward_rejected)
+        raise ConfigurationError,
+          "#{label} (#{model}): forward_rejected: must be true or false, got #{forward_rejected.inspect}"
+      end
+
       params = step[:params] && Params.normalize(step[:params], "#{label} (#{model}) params")
-      normalized = { model:, provider: step[:provider], params:, attempts: }
+      normalized = { model:, provider: step[:provider], params:, attempts:, forward_rejected: }
       step.key?(:order) ? normalized.merge(order: step[:order]) : normalized
     end
 

data/lib/squishling/output_check.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Turns a model response into a typed result: parses it, validates it against the schema, and runs the
+  # method's squish_validate check.
+  class OutputCheck
+    MAX_ERRORS = 20
+    UNREPRESENTABLE = "response contained a value JSON can't represent (such as Infinity or invalid UTF-8)"
+
+    def initialize(definition, receiver, inputs)
+      @definition = definition
+      @receiver = receiver
+      @inputs = inputs
+    end
+
+    # Parses and validates a response: [typed result, []] when it passes, [nil or result, errors] otherwise.
+    # The judge's role skips squish_validate, which checks the operation's output, not a verdict.
+    def call(content, prompt)
+      data, errors = parse(content)
+      errors = prompt.schema.validate(data) if errors.empty?
+      return [nil, cap(errors)] if errors.any?
+
+      result = prompt.schema.build(data, squished: true)
+      [result, prompt.role == :judge ? [] : validator_errors(result)]
+    end
+
+    private
+
+    # RubyLLM parses structured output itself and leaves the raw string when that fails, so
+    # content is a Hash on success, or a String/nil when the model refused, was cut off, or
+    # ignored the schema.
+    def parse(content)
+      return [nil, [UNREPRESENTABLE]] if content.is_a?(String) && !content.valid_encoding?
+      return [nil, ["response was empty"]] if content.nil? || (content.is_a?(String) && content.strip.empty?)
+
+      data = content.is_a?(String) ? JSON.parse(strip_code_fence(content)) : content
+      representable?(data) ? [data, []] : [nil, [UNREPRESENTABLE]]
+    rescue JSON::ParserError => e
+      [nil, ["response was not valid JSON#{parse_position(e)}"]]
+    end
+
+    # JSON.parse turns an out-of-range number such as 1e400 into Infinity, and accepts invalid UTF-8 in a string.
+    # Both can satisfy the schema but can't be serialized again (and the deterministic path rejects them), so
+    # they are invalid output.
+    def representable?(data)
+      JSON.generate(data)
+      true
+    rescue JSON::GeneratorError
+      false
+    end
+
+    # A long output can fail the schema thousands of times over; every error goes into the retry message and
+    # the log, so only the first few are kept.
+    def cap(errors)
+      return errors if errors.size <= MAX_ERRORS
+
+      errors.first(MAX_ERRORS) + ["... and #{errors.size - MAX_ERRORS} more errors"]
+    end
+
+    # The parser's message quotes a snippet of the response, which must not reach error messages or logs
+    # (the raw output lives only in InvalidOutputError#raw), so only the position is kept.
+    def parse_position(error)
+      position = error.message.strip.match(/ at line (\d+) column (\d+)\z/)
+      position ? " (at line #{position[1]} column #{position[2]})" : ""
+    end
+
+    # Models without native structured output sometimes wrap JSON in a markdown code fence.
+    def strip_code_fence(text)
+      text[/\A\s*```(?:json)?\s*\n(.*?)\n\s*```\s*\z/m, 1] || text
+    end
+
+    # Runs the squish_validate check, if any. Exceptions it raises are the user's own and propagate as-is.
+    def validator_errors(result)
+      validator = @definition.validator
+      return [] unless validator
+
+      value = @receiver.instance_exec(result, **@inputs, &validator)
+      case value
+      when nil, true then []
+      when false then ["the output was rejected by squish_validate"]
+      when String, Array then Array(value).flatten.compact.map(&:to_s).reject { |message| message.strip.empty? }
+      else
+        return contract_errors(value) if value.respond_to?(:success?) && value.respond_to?(:errors)
+
+        raise ConfigurationError, "#{@definition.label}: squish_validate must return nil, true, false, a String, " \
+                                  "an Array of Strings, or a validation result, got #{value.class}"
+      end
+    end
+
+    # A dry-validation style result: errors.to_h is { key => ["message", ...] }, nested for nested keys.
+    def contract_errors(value)
+      return [] if value.success?
+
+      errors = value.errors
+      errors = errors.to_h if !errors.is_a?(Array) && errors.respond_to?(:to_h)
+      messages = errors.is_a?(Hash) ? flatten_messages(errors) : Array(errors).map(&:to_s)
+      messages.empty? ? ["the output was rejected by squish_validate"] : messages
+    end
+
+    def flatten_messages(errors, prefix = nil)
+      errors.flat_map do |key, value|
+        path = [prefix, key].compact.join(".")
+        next flatten_messages(value, path) if value.is_a?(Hash)
+
+        Array(value).map { |message| path.empty? ? message.to_s : "#{path} #{message}" }
+      end
+    end
+  end
+end

data/lib/squishling/params.rb

@@ -11,9 +11,25 @@ module Squishling
     RESERVED_KEYS = %i[
       model messages input inputs instructions contents system system_instruction systemInstruction cachedContent
       stream stream_options store include response_format text output_config outputConfig tools tool_choice
-      toolConfig schema
+      toolConfig tool_config schema
     ].freeze
 
+    # Some protocols carry the structured-output format (or tool selection) inside a container that is
+    # itself allowed, because it also holds ordinary settings (Gemini's topK, Mistral's top_p, ...). RubyLLM
+    # deep-merges provider options, so these nested keys would override the strict format just like the
+    # top-level ones. Re-check each protocol's render_payload (ruby_llm protocols/*/chat.rb) on every
+    # ruby_llm upgrade.
+    GENERATION_CONFIG_RESERVED_KEYS = %i[
+      responseMimeType response_mime_type responseSchema response_schema responseJsonSchema response_json_schema
+      response_format tools tool_choice toolConfig tool_config
+    ].freeze
+    COMPLETION_ARGS_RESERVED_KEYS = %i[response_format tools tool_choice].freeze
+    NESTED_RESERVED_KEYS = {
+      generationConfig: GENERATION_CONFIG_RESERVED_KEYS, # Gemini
+      generation_config: GENERATION_CONFIG_RESERVED_KEYS, # Gemini Interactions
+      completion_args: COMPLETION_ARGS_RESERVED_KEYS # Mistral Conversations
+    }.freeze
+
     module_function
 
     # Validates and symbolizes one layer. nil values are kept so a layer can unset an inherited key.
@@ -26,10 +42,30 @@ module Squishling
         raise ConfigurationError, "#{label}: #{reserved.join(', ')} can't be set through params " \
                                   "(controlled by Squishling/RubyLLM; use model:/provider:/output_schema)"
       end
+      reject_nested_reserved!(params, label)
       params[:thinking] = normalize_thinking(params[:thinking], label) unless params[:thinking].nil?
       params.freeze
     end
 
+    # Nested keys are compared as symbols so a string-keyed "responseMimeType" can't slip past the check.
+    # A non-Hash container would replace (not merge into) the one RubyLLM builds, wiping the strict format.
+    # Validated containers are copied and frozen so they can't be mutated after the check.
+    def reject_nested_reserved!(params, label)
+      nested = NESTED_RESERVED_KEYS.flat_map do |container, reserved|
+        value = params[container]
+        next [] if value.nil?
+        raise ConfigurationError, "#{label}: #{container} must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+        params[container] = value.dup.freeze
+        (value.keys.filter_map { |key| key.to_sym if key.respond_to?(:to_sym) } & reserved)
+          .map { |key| "#{container}.#{key}" }
+      end
+      return if nested.empty?
+
+      raise ConfigurationError, "#{label}: #{nested.join(', ')} can't be set through params " \
+                                "(controls the strict output format or tools; use output_schema)"
+    end
+
     # Later layers override earlier ones key by key; nil removes the key (back to the provider default).
     def resolve(*layers)
       layers.compact.reduce({}) { |merged, layer| merged.merge(layer) }.compact

data/lib/squishling/router.rb

@@ -13,7 +13,7 @@ module Squishling
     class << self
       def dispatch(receiver, name, args, kwargs, impl, wrapper:)
         if (frame = enclosing_frame(receiver, name, wrapper))
-          return frame.definition.coerce(impl.call)
+          return coerce_inner(frame, impl.call)
         end
 
         definition = receiver.class.squishling_definition(name)
@@ -57,6 +57,12 @@ module Squishling
 
       private
 
+      # An inner call (`super`, or the method called from squish_when or a fallback) hands its value to user code
+      # that may reshape it, so only a Hash is typed (for accessor access); the outermost return is validated in full.
+      def coerce_inner(frame, value)
+        value.is_a?(Hash) ? frame.definition.coerce(value) : value
+      end
+
       def route_to_llm(frame, definition, reason)
         log(definition, reason)
         previous = frame.phase
@@ -73,7 +79,7 @@ module Squishling
 
       # The call in progress that this one is part of, which runs its Ruby implementation without routing again:
       # a subclass override's `super` (entered through an ancestor's wrapper), or a call made while deciding or on
-      # the LLM path (squish_when, squish_fallback, an instructions proc). Only recursion from the Ruby
+      # the LLM path (squish_when, squish_fallback, a purpose proc). Only recursion from the Ruby
       # implementation itself is a new call, routed on its own.
       def enclosing_frame(receiver, name, wrapper)
         frame = frames.reverse_each.find do |candidate|

data/lib/squishling/source.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Squishling
-  # Ruby source for append_instructions items: a class or module body, or a single method, rendered as a
+  # Ruby source for append_to_purpose items: a class or module body, or a single method, rendered as a
   # fenced code block. Parsed with Prism (a default gem since Ruby 3.3), loaded the first time it's needed.
   module Source
     # owner => { method name, or nil for the module itself => rendered source }. Weak keys, so classes replaced
@@ -30,7 +30,7 @@ module Squishling
       def module_source(mod)
         constant = constant_location(mod)
         sources = constant ? class_bodies(mod, constant) : method_defs(mod)
-        raise ConfigurationError, "append_instructions: source for #{mod.inspect} isn't available" if sources.empty?
+        raise ConfigurationError, "append_to_purpose: source for #{mod.inspect} isn't available" if sources.empty?
 
         [display_name(mod), sources.join("\n\n")]
       end
@@ -58,7 +58,7 @@ module Squishling
       def method_source(method)
         label = method_label(method)
         source = def_source(method)
-        raise ConfigurationError, "append_instructions: source for #{label} isn't available" unless source
+        raise ConfigurationError, "append_to_purpose: source for #{label} isn't available" unless source
 
         [label, source]
       end
@@ -84,7 +84,7 @@ module Squishling
       # A squished method resolves to Squishling's wrapper; show the implementation beneath it.
       def unwrap(method)
         Wrapper.implementation(method) or
-          raise ConfigurationError, "append_instructions: #{method.name} has no implementation to show"
+          raise ConfigurationError, "append_to_purpose: #{method.name} has no implementation to show"
       end
 
       # Named after the def that's shown, so an alias is labeled by its original name.
@@ -162,7 +162,7 @@ module Squishling
         text = File.read(file, encoding: Encoding::UTF_8).scrub
         [Prism.parse(text).value, text.lines]
       rescue SystemCallError => e
-        raise ConfigurationError, "append_instructions: can't read #{file} (#{e.class})"
+        raise ConfigurationError, "append_to_purpose: can't read #{file} (#{e.class})"
       end
 
       # Give the node's first line its source line's indentation (it may start mid-line, as in

data/lib/squishling/squawk.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Squishling
+  # The opt-in observability hook: a callable run after every LLM attempt with the attempt's raw output, so
+  # it can be sent somewhere (an error tracker, a tracing tool). It's the one sanctioned way for model output
+  # to leave the process; nothing runs unless one is configured.
+  module Squawk
+    KEYWORD_TYPES = %i[key keyreq].freeze
+    POSITIONAL_TYPES = %i[req opt].freeze
+    KEYWORD_CAPTURE_TYPES = %i[key keyreq keyrest].freeze
+    KEYWORDS = %i[output metadata error].freeze
+
+    module_function
+
+    # The hook itself, or nil/false to inherit/silence. Anything else must respond to call and take keywords
+    # only, which is checked here so a mismatch fails at setup, not inside the first attempt.
+    def validate(hook, where)
+      return hook if hook.nil? || hook == false
+
+      unless hook.respond_to?(:call)
+        raise ConfigurationError, "#{where} squawk must respond to call (or be false), got #{hook.inspect}"
+      end
+      if positional_only?(parameters(hook))
+        raise ConfigurationError,
+          "#{where} squawk is called with keywords (output:, metadata:, error:), not positional arguments"
+      end
+      unknown = parameters(hook).filter_map { |type, name| name if type == :keyreq && !KEYWORDS.include?(name) }
+      raise ConfigurationError, "#{where} squawk requires unknown keyword(s) #{unknown.join(', ')}" if unknown.any?
+
+      hook
+    end
+
+    # Calls the hook with the keywords it declares, or all of them when it takes **, so new metadata fields
+    # never break an existing lambda. Exceptions it raises are the user's own and propagate as-is.
+    def call(hook, **payload)
+      parameters = parameters(hook)
+      payload = payload.slice(*parameters.filter_map { |type, name| name if KEYWORD_TYPES.include?(type) }) \
+        unless parameters.any? { |type, _| type == :keyrest }
+      hook.call(**payload)
+    end
+
+    # Positional parameters, or a bare splat, would receive the keywords as a Hash (or not at all).
+    def positional_only?(parameters)
+      types = parameters.map(&:first)
+      types.intersect?(POSITIONAL_TYPES) || (types.include?(:rest) && !types.intersect?(KEYWORD_CAPTURE_TYPES))
+    end
+
+    def parameters(hook)
+      (hook.is_a?(Proc) || hook.is_a?(Method) ? hook : hook.method(:call)).parameters
+    end
+  end
+end

data/lib/squishling/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Squishling
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/squishling.rb

@@ -9,16 +9,22 @@ require_relative "squishling/version"
 require_relative "squishling/errors"
 require_relative "squishling/configuration"
 require_relative "squishling/params"
+require_relative "squishling/squawk"
 require_relative "squishling/model_path"
+require_relative "squishling/harness"
 require_relative "squishling/result"
 require_relative "squishling/schema"
 require_relative "squishling/source"
 require_relative "squishling/appendices"
 require_relative "squishling/definition"
+require_relative "squishling/llm_client"
+require_relative "squishling/output_check"
 require_relative "squishling/invoker"
+require_relative "squishling/judge"
 require_relative "squishling/router"
 require_relative "squishling/wrapper"
 require_relative "squishling/class_methods"
+require_relative "squishling/collisions"
 
 # Include Squishling in a class to make it elastic: its squished methods either run their
 # Ruby implementation or send their inputs through an LLM and return schema-validated results.
@@ -39,7 +45,11 @@ module Squishling
     def included(base)
       raise ConfigurationError, "Squishling can only be included in a class" unless base.is_a?(Class)
 
+      # A redundant include in a subclass overrides nothing new: the superclass's own methods already won.
+      Collisions.check!(base) unless base.superclass&.include?(Squishling)
       base.extend(ClassMethods)
+      # `result` is a convenience alias for squishling_result; a class that already has a `result` keeps it.
+      base.include(ResultAlias) unless base.method_defined?(:result) || base.private_method_defined?(:result)
       base.send(:squishling_install_wrapper)
     end
   end
@@ -53,16 +63,23 @@ module Squishling
     frame.definition.build_result(attrs || kwargs, squished: false)
   end
 
-  alias_method :result, :squishling_result
+  # Included separately, and only when the class has no `result` of its own, so `result` never shadows an
+  # inherited one. A module (not an alias on the class) keeps it out of the class's own source.
+  module ResultAlias
+    def result(...)
+      squishling_result(...)
+    end
+  end
 
   # Hand the squished method currently executing to the LLM, e.g. from a `rescue` when the Ruby path can't
   # handle this input. Returns the typed result (squished? true, or false when the declared fallback supplied
-  # it); return it from the method. The overrides apply to this call only: append_instructions adds to (or,
+  # it); return it from the method. The overrides apply to this call only: append_to_purpose adds to (or,
   # with false, replaces) the declared sections, context is sent alongside the declared squish_context,
-  # model/escalation (one or the other)/provider/instructions replace the declared ones, and params merge key
-  # by key over them.
-  def squish!(append_instructions: nil, context: nil, instructions: nil, model: nil, escalation: nil, provider: nil,
-    params: nil)
-    Router.hand_off(self, { append_instructions:, context:, instructions:, model:, escalation:, provider:, params: })
+  # model/escalation (one or the other)/provider/purpose/harness replace the declared ones, and params merge
+  # key by key over them.
+  def squish!(append_to_purpose: nil, context: nil, purpose: nil, model: nil, escalation: nil, provider: nil,
+    params: nil, harness: nil)
+    Router.hand_off(self, { append_to_purpose:, context:, purpose:, model:, escalation:, provider:, params:,
+                            harness: })
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: squishling
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: schematist
   requirement: !ruby/object:Gem::Requirement
@@ -72,21 +72,30 @@ files:
 - SECURITY.md
 - docs/configuration.md
 - docs/failures.md
+- docs/harnesses.md
+- docs/measuring-tokens.md
+- docs/naming.md
 - docs/routing.md
 - docs/schemas.md
 - lib/squishling.rb
 - lib/squishling/appendices.rb
 - lib/squishling/class_methods.rb
+- lib/squishling/collisions.rb
 - lib/squishling/configuration.rb
 - lib/squishling/definition.rb
 - lib/squishling/errors.rb
+- lib/squishling/harness.rb
 - lib/squishling/invoker.rb
+- lib/squishling/judge.rb
+- lib/squishling/llm_client.rb
 - lib/squishling/model_path.rb
+- lib/squishling/output_check.rb
 - lib/squishling/params.rb
 - lib/squishling/result.rb
 - lib/squishling/router.rb
 - lib/squishling/schema.rb
 - lib/squishling/source.rb
+- lib/squishling/squawk.rb
 - lib/squishling/version.rb
 - lib/squishling/wrapper.rb
 homepage: https://github.com/Coolhand-Labs/squishling