squishling 0.1.0

data/lib/squishling/definition.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Squishling
+  # A squished method's settings, with per-method overrides falling back to class-level defaults.
+  # `for_call` layers one call's `squish!` overrides on top.
+  class Definition
+    # Matches the keys a squish! context: Hash may use.
+    NAME_KEY = ->(key) { key.is_a?(String) || key.is_a?(Symbol) }
+
+    attr_reader :klass, :name, :call_context
+
+    def initialize(klass:, name:, instructions: nil, append_instructions: nil, output_schema: nil, model: nil,
+      provider: nil, params: nil, predicate: nil, fallback: nil, call_context: {})
+      @klass = klass
+      @name = name
+      @instructions = instructions
+      @append_instructions = append_instructions
+      @output_schema = output_schema
+      @model = model
+      @provider = provider
+      @params = params
+      @predicate = predicate
+      @fallback = fallback
+      @call_context = call_context
+    end
+
+    # This definition with one call's overrides on top. The output schema and predicate can't be overridden:
+    # the call must still return the method's result type.
+    def for_call(instructions: nil, append_instructions: nil, context: nil, model: nil, provider: nil, params: nil)
+      raise ConfigurationError, "#{label}: squish! provider: needs a model:" if provider && !model
+      unless context.nil? || (context.is_a?(Hash) && context.each_key.all?(NAME_KEY))
+        raise ConfigurationError, "#{label}: squish! context: must be a Hash with String or Symbol keys"
+      end
+
+      appended = Appendices.normalize(append_instructions, "#{label} squish!") unless append_instructions.nil?
+      call_params = params && Params.normalize(params, "#{label} squish! params")
+      self.class.new(
+        klass:, name:, output_schema: @output_schema, predicate: @predicate, fallback: @fallback,
+        instructions: instructions || @instructions,
+        append_instructions: [*@append_instructions, *appended],
+        model: model || @model, provider: model ? provider : @provider,
+        # merge, not Params.resolve: a nil at the method level must still unset the class's key.
+        params: call_params ? (@params || {}).merge(call_params) : @params,
+        call_context: @call_context.merge((context || {}).transform_keys(&:to_sym))
+      )
+    end
+
+    def label
+      "#{klass}##{name}"
+    end
+
+    # The system prompt: the instructions, then each append_instructions section.
+    def instructions(receiver)
+      value = @instructions || klass.instructions
+      value = receiver.instance_exec(&value) if value.is_a?(Proc)
+      return value if value.nil? || value.empty?
+
+      [value, *Appendices.render(append_instructions, receiver, label)].join("\n\n")
+    end
+
+    def append_instructions
+      Appendices.resolve(klass.squishling_append_instructions + (@append_instructions || []))
+    end
+
+    def schema
+      raw = @output_schema || klass.output_schema
+      raw && Schema.for(raw)
+    end
+
+    def model
+      model_and_provider.first
+    end
+
+    def provider
+      model_and_provider.last
+    end
+
+    # A provider travels with the model declared at the same level (method, class, or config),
+    # so a per-method Anthropic model never inherits a class-level OpenAI provider.
+    def model_and_provider
+      config = Squishling.config
+      [[@model, @provider], [klass.squishling_model, klass.squishling_provider],
+       [config.default_model, config.default_provider]].find(&:first) || [nil, nil]
+    end
+
+    # Generation params: config defaults, overridden key by key by the class, then by the method.
+    def params
+      Params.resolve(Squishling.config.default_params, klass.squishling_params, @params)
+    end
+
+    def context_names
+      klass.squishling_context_names
+    end
+
+    def squish?(receiver, inputs)
+      predicate = @predicate || klass.squishling_predicate
+      return false unless predicate
+
+      receiver.instance_exec(**inputs, &predicate) ? true : false
+    end
+
+    # Runs the elastic path. When the LLM fails (InvalidOutputError or LLMError) and a fallback is
+    # declared, the fallback's return value is used instead, coerced like a deterministic return.
+    def invoke_llm(receiver, inputs)
+      Invoker.new(self, receiver, inputs).call
+    rescue InvalidOutputError, LLMError => e
+      handler = @fallback || klass.squishling_fallback
+      raise unless handler
+
+      Squishling.config.logger&.warn("[Squishling] #{label} LLM failed, using fallback: #{e.message}")
+      coerce(receiver.instance_exec(e, **inputs, &handler))
+    end
+
+    # Deterministic return values: hashes are validated and turned into the typed result;
+    # anything else (including an already-built result) passes through.
+    def coerce(value)
+      value.is_a?(Hash) && schema ? build_result(value, squished: false) : value
+    end
+
+    def build_result(attrs, squished:)
+      raise ConfigurationError, "#{label} has no output_schema" unless schema
+      return attrs if attrs.is_a?(Result::Instance)
+
+      data = Schema.jsonify(attrs)
+      errors = schema.validate(data)
+      raise InvalidOutputError.new(errors:, raw: attrs, source: "Deterministic") if errors.any?
+
+      schema.build(data, squished:)
+    end
+
+    # Map positional and keyword arguments onto the original method's parameter names.
+    def bind_arguments(args, kwargs)
+      positional = args.dup
+      bound = {}
+
+      parameters.each do |type, param|
+        case type
+        when :req, :opt
+          bound[param] = positional.shift unless positional.empty? || param.nil?
+        when :rest
+          bound[param.nil? || param == :* ? :args : param] = positional.shift(positional.size)
+        end
+      end
+      positional.each_with_index { |value, index| bound[:"arg#{index}"] = value }
+
+      bound.merge(kwargs)
+    end
+
+    private
+
+    # The implementation's parameters, beneath the prepended wrappers.
+    def parameters
+      Wrapper.implementation(klass.instance_method(name))&.parameters || []
+    end
+  end
+end

data/lib/squishling/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Error < StandardError; end
+
+  # A programming or setup mistake (missing instructions/schema, non-strict schema, unknown model,
+  # missing API key). Never retried and never passed to squish_fallback.
+  class ConfigurationError < Error; end
+
+  # Output that didn't match the schema: from the LLM after all retries, or from the deterministic path.
+  class InvalidOutputError < Error
+    attr_reader :errors, :raw, :attempts
+
+    def initialize(errors:, raw: nil, source: "LLM", attempts: nil)
+      @errors = errors
+      @raw = raw
+      @attempts = attempts
+      tries = attempts ? " after #{attempts} attempt#{'s' unless attempts == 1}" : ""
+      super("#{source} output did not match the output schema#{tries}: #{errors.join('; ')}")
+    end
+  end
+
+  # The LLM call itself failed (rate limit, server error, timeout, connection) after RubyLLM's own
+  # HTTP retries. The original exception is available as #cause.
+  class LLMError < Error; end
+end

data/lib/squishling/invoker.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Squishling
+  # The elastic path: sends a squished method's inputs through RubyLLM with structured output.
+  class Invoker
+    INPUT_NOTE = <<~NOTE
+      The input is a JSON object. "arguments" holds the values passed to this operation; "context", when
+      present, holds additional state about the caller. Respond only with JSON matching the required schema.
+    NOTE
+
+    def initialize(definition, receiver, inputs)
+      @definition = definition
+      @receiver = receiver
+      @inputs = inputs
+    end
+
+    def call
+      instructions = @definition.instructions(@receiver)
+      schema = @definition.schema
+      raise ConfigurationError, "#{@definition.label} has no instructions" if instructions.nil? || instructions.empty?
+      raise ConfigurationError, "#{@definition.label} has no output_schema" unless schema
+
+      chat = build_chat
+      chat.with_instructions("#{instructions}\n\n#{INPUT_NOTE}")
+      chat.with_schema(schema.llm_schema)
+      apply_params(chat)
+
+      response = ask(chat, JSON.generate(payload))
+      attempts = 0
+      loop do
+        attempts += 1
+        data, errors = parse(response.content)
+        errors = schema.validate(data) if errors.empty?
+        return schema.build(data, squished: true) if errors.empty?
+
+        if attempts > Squishling.config.max_retries
+          raise InvalidOutputError.new(errors:, raw: response.content, attempts:)
+        end
+
+        response = ask(chat, retry_message(errors))
+      end
+    end
+
+    private
+
+    def build_chat
+      RubyLLM.chat(**chat_options)
+    rescue RubyLLM::ModelNotFoundError, RubyLLM::ConfigurationError => e
+      raise ConfigurationError, "#{@definition.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.apply(chat, @definition.params)
+    rescue ArgumentError => e
+      raise ConfigurationError, "#{@definition.label}: invalid params #{@definition.params.inspect} (#{e.message})"
+    end
+
+    # Transient HTTP failures are already retried by RubyLLM (config.max_retries); anything that
+    # still fails is surfaced as an LLMError rather than retried again here. A 400 means the request
+    # we built is invalid (an unsupported param, a schema the provider rejects), so it's a setup
+    # mistake: a fallback would otherwise hide it on every call.
+    def ask(chat, message)
+      chat.ask(message)
+    rescue RubyLLM::ConfigurationError, RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
+      raise ConfigurationError, "#{@definition.label}: #{e.class}: #{e.message}"
+    rescue RubyLLM::BadRequestError => e
+      raise ConfigurationError, "#{@definition.label}: the provider rejected the request (#{e.message})#{params_hint}"
+    rescue RubyLLM::Error, Faraday::Error => e
+      raise LLMError, "#{@definition.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 chat_options
+      model = @definition.model
+      provider = @definition.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 = @definition.params
+      return "" if params.empty?
+
+      ". Check params #{params.inspect}; reasoning models often reject sampling params such as temperature and top_p"
+    end
+
+    # Only the arguments, the declared squish_context names, and a squish! call's context leave the process.
+    def payload
+      body = { arguments: Schema.jsonify(describe(@inputs)) }
+      context = @definition.context_names.to_h { |name| [name, context_value(name)] }.merge(@definition.call_context)
+      body[:context] = Schema.jsonify(describe(context)) if context.any?
+      body
+    end
+
+    # Exceptions are sent as their class and message. Plain JSON would send only the message, and with
+    # json/add/exception loaded it would also send the backtrace, which exposes file paths.
+    def describe(value)
+      case value
+      when Exception then { class: exception_class_name(value.class), message: value.message }
+      when Hash then value.transform_values { |item| describe(item) }
+      when Array then value.map { |item| describe(item) }
+      else value
+      end
+    end
+
+    # An anonymous error class (Class.new(StandardError)) is named after its closest named ancestor.
+    def exception_class_name(klass)
+      klass = klass.superclass until klass.name
+      klass.name
+    end
+
+    def context_value(name)
+      return @receiver.send(name) if @receiver.respond_to?(name, true)
+
+      @receiver.instance_variable_get(:"@#{name}")
+    end
+
+    # 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, ["response was empty"]] if content.nil? || (content.is_a?(String) && content.strip.empty?)
+      return [content, []] unless content.is_a?(String)
+
+      [JSON.parse(strip_code_fence(content)), []]
+    rescue JSON::ParserError => e
+      [nil, ["response was not valid JSON (#{e.message.lines.first&.strip})"]]
+    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
+
+    def retry_message(errors)
+      "Your previous response did not match the required schema:\n- #{errors.join("\n- ")}\n" \
+        "Respond again with corrected JSON only."
+    end
+  end
+end

data/lib/squishling/params.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Generation params (temperature, thinking, max_output_tokens, top_p, ...) layered config -> class -> method.
+  module Params
+    THINKING_KEYS = %i[effort budget display].freeze
+
+    # Request keys Squishling or RubyLLM own. Provider options are merged into the request last,
+    # 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
+    ].freeze
+
+    module_function
+
+    # Validates and symbolizes one layer. nil values are kept so a layer can unset an inherited key.
+    def normalize(params, label)
+      raise ConfigurationError, "#{label} must be a Hash, got #{params.class}" unless params.is_a?(Hash)
+
+      params = params.transform_keys(&:to_sym)
+      reserved = params.keys & RESERVED_KEYS
+      if reserved.any?
+        raise ConfigurationError, "#{label}: #{reserved.join(', ')} can't be set through params " \
+                                  "(controlled by Squishling/RubyLLM; use model:/provider:/output_schema)"
+      end
+      params[:thinking] = normalize_thinking(params[:thinking], label) unless params[:thinking].nil?
+      params.freeze
+    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
+    end
+
+    # Portable settings use RubyLLM's dedicated setters, which translate them for each provider;
+    # everything else is merged into the provider request as-is.
+    def apply(chat, params)
+      rest = params.except(:temperature, :thinking, :max_output_tokens)
+      chat.with_temperature(params[:temperature]) if params.key?(:temperature)
+      chat.with_max_output_tokens(params[:max_output_tokens]) if params.key?(:max_output_tokens)
+      apply_thinking(chat, params[:thinking]) if params.key?(:thinking)
+      chat.with_provider_options(rest) if rest.any?
+      chat
+    end
+
+    # true: the model's default thinking; false: off; a Hash: { effort:, budget:, display: }.
+    def apply_thinking(chat, thinking)
+      thinking.is_a?(Hash) ? chat.with_thinking(**thinking) : chat.with_thinking(thinking)
+    end
+
+    def normalize_thinking(thinking, label)
+      return thinking if [true, false].include?(thinking)
+
+      thinking = thinking.transform_keys(&:to_sym) if thinking.is_a?(Hash)
+      unless thinking.is_a?(Hash) && thinking.any? && (thinking.keys - THINKING_KEYS).empty? && !thinking.value?(nil)
+        raise ConfigurationError,
+          "#{label}: thinking must be true, false, or a Hash with :effort, :budget and/or :display, " \
+          "got #{thinking.inspect}"
+      end
+
+      thinking
+    end
+  end
+end

data/lib/squishling/result.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Builds Data classes from a JSON Schema so both the LLM and deterministic paths return
+  # the same typed object.
+  module Result
+    # Mixed into every generated result class.
+    module Instance
+      def initialize(squishling_squished: false, **attrs)
+        @squished = squishling_squished
+        super(**attrs)
+      end
+
+      # True when this result came from the LLM rather than Ruby code.
+      def squished?
+        @squished
+      end
+
+      def [](key)
+        members.include?(key.to_sym) ? public_send(key.to_sym) : nil
+      end
+
+      def to_h
+        super.transform_values { |value| Result.deep_to_h(value) }
+      end
+    end
+
+    module ClassMethods
+      def from_h(hash, squished: false)
+        hash = hash.transform_keys(&:to_sym)
+        attrs = members.to_h { |member| [member, squishling_fields[member].call(hash[member], squished)] }
+        new(squishling_squished: squished, **attrs)
+      end
+
+      private
+
+      def squishling_fields
+        @squishling_fields ||= @squishling_builder.fields_for(@squishling_schema)
+      end
+    end
+
+    class << self
+      def build(json_schema)
+        Builder.new(json_schema).class_for(json_schema)
+      end
+
+      def deep_to_h(value)
+        case value
+        when Instance then value.to_h
+        when Array then value.map { |item| deep_to_h(item) }
+        else value
+        end
+      end
+    end
+
+    # Resolves $refs and builds (memoized, so recursive schemas work) one Data class per object schema.
+    class Builder
+      IDENTITY = ->(value, _squished) { value.is_a?(Hash) ? value.transform_keys(&:to_sym) : value }
+
+      def initialize(root)
+        @root = root
+        @classes = {}.compare_by_identity
+      end
+
+      # Returns a Data class, or nil when the schema isn't an object with properties.
+      def class_for(schema)
+        schema = resolve(schema)
+        return nil unless schema.is_a?(Hash) && schema["properties"].is_a?(Hash)
+
+        @classes[schema] ||= begin
+          klass = Data.define(*schema["properties"].keys.map(&:to_sym))
+          klass.include(Instance)
+          klass.extend(ClassMethods)
+          klass.instance_variable_set(:@squishling_builder, self)
+          klass.instance_variable_set(:@squishling_schema, schema)
+          klass
+        end
+      end
+
+      def fields_for(schema)
+        schema["properties"].to_h { |key, property| [key.to_sym, converter_for(property)] }
+      end
+
+      private
+
+      def converter_for(property)
+        property = resolve(property)
+        return IDENTITY unless property.is_a?(Hash)
+
+        # `optional` (anyOf [schema, null]) is typed as its schema; nil passes through every converter.
+        if (branch = nullable_branch(property))
+          converter_for(branch)
+        elsif (klass = class_for(property))
+          ->(value, squished) { value.is_a?(Hash) ? klass.from_h(value, squished:) : value }
+        elsif property["items"]
+          item = converter_for(property["items"])
+          ->(value, squished) { value.is_a?(Array) ? value.map { |v| item.call(v, squished) } : value }
+        else
+          IDENTITY
+        end
+      end
+
+      # The single non-null branch of an anyOf/oneOf. Unions with several non-null branches are
+      # ambiguous, so their values are left untyped.
+      def nullable_branch(property)
+        union = property["anyOf"] || property["oneOf"]
+        return unless union.is_a?(Array)
+
+        branches = union.reject { |branch| resolve(branch).is_a?(Hash) && resolve(branch)["type"] == "null" }
+        branches.first if branches.size == 1
+      end
+
+      def resolve(schema)
+        return schema unless schema.is_a?(Hash) && schema["$ref"].is_a?(String)
+        return schema unless schema["$ref"].start_with?("#/")
+
+        path = schema["$ref"].delete_prefix("#/").split("/")
+        @root.dig(*path) || schema
+      end
+    end
+  end
+end

data/lib/squishling/router.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+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!
+    # already sent it to the LLM.
+    Frame = Struct.new(:receiver, :definition, :wrapper, :inputs, :phase, :escalated)
+
+    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)
+        end
+
+        definition = receiver.class.squishling_definition(name)
+        frame = Frame.new(receiver, definition, wrapper, definition.bind_arguments(args, kwargs), :routing, false)
+        frames.push(frame)
+        begin
+          return route_to_llm(frame, definition, "predicate") if definition.squish?(receiver, frame.inputs)
+
+          begin
+            frame.phase = :ruby
+            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
+
+            return route_to_llm(frame, definition, "not implemented")
+          end
+
+          definition.coerce(value)
+        ensure
+          frames.pop
+        end
+      end
+
+      def current_frame(receiver)
+        frames.reverse_each.find { |frame| frame.receiver.equal?(receiver) }
+      end
+
+      # squish!: hand the call in progress on this receiver to the LLM, with this call's overrides.
+      def escalate(receiver, overrides)
+        frame = current_frame(receiver)
+        raise Error, "#{receiver.class}#squish! called outside a squished method" unless frame
+        unless frame.phase == :ruby
+          raise Error, "#{frame.definition.label}: squish! can only be called from the method's Ruby implementation, " \
+                       "not from squish_when or while already on the LLM path (e.g. from squish_fallback)"
+        end
+
+        frame.escalated = true
+        route_to_llm(frame, frame.definition.for_call(**overrides), "squish!")
+      end
+
+      private
+
+      def route_to_llm(frame, definition, reason)
+        log(definition, reason)
+        previous = frame.phase
+        frame.phase = :llm
+        definition.invoke_llm(frame.receiver, frame.inputs)
+      ensure
+        frame.phase = previous
+      end
+
+      # Thread#[] is fiber-local, so concurrent fibers don't share frames.
+      def frames
+        Thread.current[FRAMES_KEY] ||= []
+      end
+
+      # 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
+      # implementation itself is a new call, routed on its own.
+      def enclosing_frame(receiver, name, wrapper)
+        frame = frames.reverse_each.find do |candidate|
+          candidate.receiver.equal?(receiver) && candidate.definition.name == name
+        end
+        frame unless frame.nil? || (frame.wrapper.equal?(wrapper) && frame.phase == :ruby)
+      end
+
+      def log(definition, reason)
+        Squishling.config.logger&.debug("[Squishling] #{definition.label} -> LLM (#{reason})")
+      end
+    end
+  end
+end

data/lib/squishling/schema.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Normalizes the supported output-schema forms into a JSON Schema, validates data against it,
+  # and builds typed results.
+  class Schema
+    CACHE = {}.compare_by_identity
+    CACHE_LOCK = Mutex.new
+
+    class << self
+      def for(raw)
+        CACHE_LOCK.synchronize { CACHE[raw] ||= new(raw) }
+      end
+
+      # Deep-convert to plain JSON types (string keys), as the LLM would return them.
+      def jsonify(value)
+        JSON.parse(JSON.generate(value))
+      end
+    end
+
+    # The payload handed to RubyLLM's `with_schema`: always strict.
+    attr_reader :llm_schema
+    # The bare JSON Schema used for validation and result typing.
+    attr_reader :json_schema
+
+    def initialize(raw)
+      hash = self.class.jsonify(to_hash(raw))
+      wrapped = wrapped?(hash)
+      body = wrapped ? hash["schema"] : hash
+
+      # Same precedence RubyLLM uses: a top-level strict flag wins over one inside the schema.
+      strict = hash.key?("strict") ? hash["strict"] : body["strict"]
+      raise ConfigurationError, "Squishling only supports strict output schemas (got strict: false)" if strict == false
+
+      @json_schema = body.except("strict")
+      @llm_schema = {
+        "name" => hash["name"] || body["title"],
+        "description" => hash["description"] || body["description"],
+        "schema" => @json_schema,
+        "strict" => true
+      }.compact
+      @validator = JSONSchemer.schema(@json_schema)
+    end
+
+    def validate(data)
+      @validator.validate(data).map { |error| error["error"] }
+    end
+
+    def build(data, squished:)
+      result_class ? result_class.from_h(data, squished:) : data
+    end
+
+    def result_class
+      return @result_class if defined?(@result_class)
+
+      @result_class = Result.build(@json_schema)
+    end
+
+    private
+
+    def to_hash(raw)
+      case raw
+      when Hash then raw
+      when Class
+        raise ConfigurationError, "#{raw} is not a Schematist::Schema" unless raw <= Schematist::Schema
+
+        raw.new.to_json_schema
+      else
+        return raw.to_json_schema if raw.respond_to?(:to_json_schema)
+
+        raise ConfigurationError, "Unsupported output_schema: #{raw.inspect}"
+      end
+    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")
+    end
+  end
+end