squishling 0.1.0 → 0.3.0

data/lib/squishling/model_path.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Squishling
+  # The models a squished call tries, in order. Declared either as one model (model: "claude-haiku-4-5", a
+  # single attempt) or as an escalation: an Array of steps, each a model name or a Hash:
+  #   escalation: [
+  #     { model: "claude-haiku-4-5", attempts: 2 },
+  #     "claude-sonnet-5-5",
+  #     { 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. 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, 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 forward_rejected].freeze
+
+    module_function
+
+    # A single model: model:/default_model. Returns a one-step path, or nil when not declared.
+    def from_model(model, label)
+      return nil if model.nil?
+
+      if model.is_a?(Array) || model.is_a?(Hash)
+        raise ConfigurationError, "#{label} takes one model; use escalation: [...] to try several in order"
+      end
+
+      [normalize_step(model, label)].freeze
+    end
+
+    # An escalation: escalation:/default_escalation. Returns the steps in order, or nil when not declared.
+    def from_escalation(escalation, label)
+      return nil if escalation.nil?
+      unless escalation.is_a?(Array)
+        raise ConfigurationError, "#{label} must be an Array of steps, got #{escalation.class}"
+      end
+      raise ConfigurationError, "#{label} can't be empty" if escalation.empty?
+
+      ordered(escalation.map { |step| normalize_step(step, label) }, label).freeze
+    end
+
+    # model: and escalation: both describe what to try, so a level may declare only one of them.
+    def declare(model, escalation, label)
+      if !model.nil? && !escalation.nil?
+        raise ConfigurationError, "#{label}: declare model: or escalation:, not both (put the model in the escalation)"
+      end
+
+      from_model(model, "#{label} model") || from_escalation(escalation, "#{label} escalation")
+    end
+
+    # One Step per attempt. The level's provider applies to steps that don't name their own, and each
+    # step's params are merged over the level-resolved params.
+    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]), forward_rejected: step[:forward_rejected])
+        [attempt] * step[:attempts]
+      end
+    end
+
+    def ordered(steps, label)
+      numbered = steps.count { |step| step.key?(:order) }
+      return steps.map { |step| step.except(:order) } if numbered.zero?
+
+      if numbered < steps.size
+        raise ConfigurationError, "#{label}: give every step an order: or none (#{numbered} of #{steps.size} have one)"
+      end
+
+      orders = steps.map { |step| step[:order] }
+      duplicates = orders.tally.select { |_, count| count > 1 }.keys
+      raise ConfigurationError, "#{label}: duplicate order: #{duplicates.join(', ')}" if duplicates.any?
+
+      steps.sort_by { |step| step[:order] }.map { |step| step.except(:order) }
+    end
+
+    def normalize_step(step, label)
+      case step
+      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}"
+      end
+    end
+
+    def normalize_hash(step, label)
+      step = step.transform_keys(&:to_sym)
+      unknown = step.keys - STEP_KEYS
+      raise ConfigurationError, "#{label}: unknown step option(s) #{unknown.join(', ')}" if unknown.any?
+      unless step[:model].is_a?(String) || step[:model].is_a?(Symbol)
+        raise ConfigurationError, "#{label}: a step needs a model: name, got #{step.inspect}"
+      end
+
+      model = model_name(step[:model], label)
+      attempts = step.fetch(:attempts, 1)
+      unless attempts.is_a?(Integer) && attempts.positive?
+        raise ConfigurationError, "#{label} (#{model}): attempts: must be a positive Integer, got #{attempts.inspect}"
+      end
+      if step.key?(:order) && !step[:order].is_a?(Integer)
+        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:, forward_rejected: }
+      step.key?(:order) ? normalized.merge(order: step[:order]) : normalized
+    end
+
+    def model_name(model, label)
+      name = model.to_s
+      raise ConfigurationError, "#{label}: model names can't be blank" if name.strip.empty?
+
+      name
+    end
+  end
+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

@@ -9,10 +9,27 @@ module Squishling
     # overriding RubyLLM's defaults, so these would silently replace the model, the conversation,
     # or the strict output format.
     RESERVED_KEYS = %i[
-      model messages input instructions contents system system_instruction stream stream_options store include
-      response_format text output_config tools tool_choice schema
+      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 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.
@@ -25,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

@@ -4,16 +4,16 @@ module Squishling
   # Decides, per call, whether a squished method runs its Ruby implementation or the LLM.
   module Router
     # One squished call in progress. `phase` is :routing (deciding, e.g. running squish_when), :ruby (running
-    # the implementation), or :llm (on the LLM path, including any fallback); `escalated` records that squish!
+    # the implementation), or :llm (on the LLM path, including any fallback); `handed_off` records that squish!
     # already sent it to the LLM.
-    Frame = Struct.new(:receiver, :definition, :wrapper, :inputs, :phase, :escalated)
+    Frame = Struct.new(:receiver, :definition, :wrapper, :inputs, :phase, :handed_off)
 
     FRAMES_KEY = :__squishling_frames__
 
     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)
@@ -27,7 +27,7 @@ module Squishling
             value = impl.call
           rescue NotImplementedError
             # After squish!, the error came from the LLM path (a fallback, a proc), not a missing implementation.
-            raise if frame.escalated
+            raise if frame.handed_off
 
             return route_to_llm(frame, definition, "not implemented")
           end
@@ -43,7 +43,7 @@ module Squishling
       end
 
       # squish!: hand the call in progress on this receiver to the LLM, with this call's overrides.
-      def escalate(receiver, overrides)
+      def hand_off(receiver, overrides)
         frame = current_frame(receiver)
         raise Error, "#{receiver.class}#squish! called outside a squished method" unless frame
         unless frame.phase == :ruby
@@ -51,12 +51,18 @@ module Squishling
                        "not from squish_when or while already on the LLM path (e.g. from squish_fallback)"
         end
 
-        frame.escalated = true
+        frame.handed_off = true
         route_to_llm(frame, frame.definition.for_call(**overrides), "squish!")
       end
 
       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/schema.rb

@@ -7,6 +7,14 @@ module Squishling
     CACHE = {}.compare_by_identity
     CACHE_LOCK = Mutex.new
 
+    # Conditional keywords (Schematist's `given` and `dependent`) that providers' strict modes don't support.
+    # They're validated locally and kept out of the schema sent to the LLM.
+    LOCAL_ONLY_KEYWORDS = %w[if then else dependentRequired dependentSchemas].freeze
+    # Keywords whose value is a map of names to schemas: the names are data, never keywords to strip.
+    SCHEMA_MAPS = %w[properties patternProperties $defs definitions].freeze
+    # Keywords whose value is literal data, copied untouched.
+    DATA_KEYWORDS = %w[enum const default examples].freeze
+
     class << self
       def for(raw)
         CACHE_LOCK.synchronize { CACHE[raw] ||= new(raw) }
@@ -18,9 +26,9 @@ module Squishling
       end
     end
 
-    # The payload handed to RubyLLM's `with_schema`: always strict.
+    # The payload handed to RubyLLM's `with_schema`: always strict, without LOCAL_ONLY_KEYWORDS.
     attr_reader :llm_schema
-    # The bare JSON Schema used for validation and result typing.
+    # The full JSON Schema used for validation and result typing.
     attr_reader :json_schema
 
     def initialize(raw)
@@ -36,7 +44,7 @@ module Squishling
       @llm_schema = {
         "name" => hash["name"] || body["title"],
         "description" => hash["description"] || body["description"],
-        "schema" => @json_schema,
+        "schema" => provider_schema(@json_schema),
         "strict" => true
       }.compact
       @validator = JSONSchemer.schema(@json_schema)
@@ -72,6 +80,40 @@ module Squishling
       end
     end
 
+    # A copy of the schema without the conditional keywords. An allOf made only of conditionals (how
+    # Schematist emits several `given` blocks) goes too.
+    def provider_schema(node)
+      case node
+      when Array then node.map { |item| provider_schema(item) }
+      when Hash
+        copy = node.each_with_object({}) do |(key, value), stripped|
+          next if LOCAL_ONLY_KEYWORDS.include?(key)
+
+          stripped[key] =
+            if DATA_KEYWORDS.include?(key)
+              value
+            elsif SCHEMA_MAPS.include?(key) && value.is_a?(Hash)
+              value.transform_values { |schema| provider_schema(schema) }
+            else
+              provider_schema(value)
+            end
+        end
+        without_conditional_all_of(copy, node)
+      else node
+      end
+    end
+
+    def without_conditional_all_of(copy, original)
+      return copy unless original["allOf"].is_a?(Array)
+
+      kept = copy["allOf"].zip(original["allOf"]).reject { |_, branch| conditional_only?(branch) }.map(&:first)
+      kept.empty? ? copy.except("allOf") : copy.merge("allOf" => kept)
+    end
+
+    def conditional_only?(branch)
+      branch.is_a?(Hash) && branch.any? && (branch.keys - LOCAL_ONLY_KEYWORDS - %w[description $comment]).empty?
+    end
+
     # Some schema objects emit a { name:, description:, schema: {...} } wrapper instead of a bare schema.
     def wrapped?(hash)
       hash["schema"].is_a?(Hash) && !hash.key?("type") && !hash.key?("properties")

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.1.0"
+  VERSION = "0.3.0"
 end

data/lib/squishling.rb

@@ -9,15 +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.
@@ -38,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
@@ -52,14 +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/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, provider: nil, params: nil)
-    Router.escalate(self, { append_instructions:, context:, instructions:, model:, 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.1.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,20 +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