squishling 0.4.0 → 0.5.0

data/lib/squishling/testing.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "squishling"
+
+require_relative "testing/errors"
+require_relative "testing/reply"
+require_relative "testing/script"
+require_relative "testing/request"
+require_relative "testing/observer"
+require_relative "testing/adapter"
+require_relative "testing/state"
+require_relative "testing/checks"
+require_relative "testing/stubs"
+require_relative "testing/direct"
+require_relative "testing/fixtures"
+require_relative "testing/helpers"
+require_relative "testing/minitest"
+require_relative "testing/rspec"
+
+module Squishling
+  # Test support, opt-in: `require "squishling/testing"` (it is not loaded with `require "squishling"`, and needs no
+  # test framework). A scripted adapter answers in place of a provider and records what was sent to it, plus stubs
+  # for the callers of squished methods, schema-driven fixtures, and assertions. See docs/testing.md and the
+  # Squishling::Testing::Minitest and ::RSpec mixins.
+  module Testing
+    class << self
+      # Makes the scripted Adapter the one every squished call goes through, and returns it. The block scripts it
+      # (see Script); #script adds to it later.
+      def install(adapter = Adapter.new)
+        yield adapter.script if block_given?
+        State.set(:observer, Observer.new(chained_observer(Squishling.config.observer)))
+        State.set(:adapter, adapter)
+        adapter
+      end
+
+      # Any request that reaches the provider seam raises ProviderCallError, naming the squished method. Call it in a
+      # suite-wide before hook: a test that forgot to script its calls then fails at the call, not far from it.
+      def forbid_provider_calls!
+        State.set(:adapter, ForbiddenAdapter.new)
+      end
+
+      # Runs the block with provider calls forbidden and returns the calls (the squished methods' labels) that tried
+      # to reach the provider, even if the block rescued the error. The adapter is put back afterwards.
+      def no_llm_call
+        config = Squishling.config
+        previous = config.adapter
+        guard = ForbiddenAdapter.new
+        config.adapter = guard
+        begin
+          yield
+        rescue ProviderCallError
+          nil
+        ensure
+          config.adapter = previous
+        end
+        guard.attempts
+      end
+
+      # See Stubs.result: Klass.call returns a real, schema-validated result of the method's type.
+      def stub_result(klass, attrs = nil, method: :call, squished: true, **more, &)
+        Stubs.result(klass, Schema.jsonify((attrs || {}).merge(more)), method:, squished:, &)
+      end
+
+      # See Stubs.error: Klass.call raises the real error class with realistic attributes.
+      def stub_error(klass, kind, **, &)
+        Stubs.error(klass, kind, **, &)
+      end
+
+      # The messages squish_validate and the schema reject this reply with. See Direct.
+      def validate(klass, reply, **inputs)
+        Direct.validate(klass, reply, **inputs)
+      end
+
+      def fallback_for(klass, error, **inputs)
+        Direct.fallback_for(klass, error, **inputs)
+      end
+
+      def preview(klass, **inputs)
+        Direct.preview(klass, **inputs)
+      end
+
+      def valid_reply_for(source, **overrides)
+        Fixtures.valid_reply_for(source, **overrides)
+      end
+
+      def invalid_reply_for(source, **)
+        Fixtures.invalid_reply_for(source, **)
+      end
+
+      # A recorder to assign as config.squawk (or give to with_squawk): every attempt's output, error and metadata.
+      def capture_squawk
+        SquawkCapture.new
+      end
+
+      # Runs the block with the capture as config.squawk, and puts the previous hook back. A squawk set on a class or
+      # a method still takes precedence over the configured one.
+      def with_squawk(capture = capture_squawk)
+        config = Squishling.config
+        previous = config.squawk
+        config.squawk = capture
+        yield capture
+        capture
+      ensure
+        config.squawk = previous
+      end
+
+      # Puts back what the helpers changed (the adapter and observer) and clears the stubs. The mixins do this
+      # after every test; call it yourself with a custom setup.
+      def reset!
+        Stubs.clear!
+        State.restore!
+      end
+
+      private
+
+      # An observer the app configured itself (an object, or :coolhand) is kept in the chain; the default Coolhand
+      # auto-detection, and our own observer from an earlier install, are not.
+      def chained_observer(observer)
+        return observer.previous if observer.is_a?(Observer)
+        return Squishling::Observer.resolve(observer) if observer.is_a?(Symbol)
+
+        observer if observer.respond_to?(:around)
+      end
+    end
+  end
+end

data/lib/squishling/verification.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Squishling
+  # What Squishling.verify found: the problems in the squished classes' setup, none when it is sound.
+  module Verification
+    # One thing wrong. label names where ("Triage#call", or "adapter" for a setup that isn't one class's).
+    Problem = Data.define(:label, :message) do
+      # The existing messages already start with the label; say it once.
+      def to_s
+        message.start_with?(label) ? message : "#{label}: #{message}"
+      end
+    end
+
+    class Report
+      attr_reader :problems
+
+      def initialize(problems)
+        @problems = problems.dup.freeze
+        freeze
+      end
+
+      def ok?
+        problems.empty?
+      end
+
+      def size
+        problems.size
+      end
+
+      # A lint-style listing, one problem per line.
+      def to_s
+        return "Squishling: no problems found" if ok?
+
+        lines = problems.map { |problem| "  #{problem}" }
+        "Squishling found #{size} #{size == 1 ? 'problem' : 'problems'}:\n#{lines.join("\n")}"
+      end
+    end
+  end
+end

data/lib/squishling/verifier.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Checks squished classes without making a request: what can only otherwise fail on a method's first call (its
+  # output schema and typed result, its callables' keywords) and the settings the layers resolve to. Collects every
+  # problem rather than stopping at the first. See Squishling.verify.
+  class Verifier
+    # Checks one squished method's Definition. Each check returns messages, or raises what the call would.
+    class MethodCheck
+      CHECKS = %i[schema declarations harness callables].freeze
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def problems
+        CHECKS.flat_map { |check| run(check) }
+      end
+
+      private
+
+      def run(check)
+        Array(send(check)).map { |message| problem(message) }
+      rescue ConfigurationError, ArgumentError => e
+        [problem(e.message)]
+      end
+
+      def problem(message)
+        Verification::Problem.new(label: @definition.label, message:)
+      end
+
+      # The output schema, its typed result (the Data class a call returns), and the JSON Schema itself.
+      def schema
+        schema = @definition.schema
+        messages = []
+        messages << "has no output_schema" unless schema
+        messages << "has no purpose" unless @definition.purpose_declared?
+        return messages unless schema
+
+        schema.result_class
+        messages + JSONSchemer.schema(schema.json_schema).validate_schema.map { |error| error["error"] }
+      end
+
+      # The escalation, generation params, and squawk this method resolves to across method, class, and config.
+      def declarations
+        steps = @definition.declared_path.first.reject { |step| step[:model].nil? }
+        ModelPath.from_escalation(steps, "#{@definition.label} escalation") if steps.any?
+        Params.normalize(@definition.params, "#{@definition.label} params")
+        Squawk.validate(@definition.squawk, @definition.label)
+        []
+      end
+
+      def harness
+        harness = @definition.harness
+        messages = []
+        unless Harness::Registry.fetch(harness.type).equal?(harness.klass)
+          messages << "harness #{harness.type.inspect} was unregistered or replaced after it was declared"
+        end
+        messages << "the judge needs an adapter that supports judgments" if unsupported_judgment?(harness)
+        messages
+      end
+
+      def unsupported_judgment?(harness)
+        judge = harness.options[:judge]
+        judge.is_a?(Hash) && judge[:type] == :judgment && !Squishling.config.resolved_adapter.judgments?
+      rescue ConfigurationError
+        false # no usable adapter: reported once, as the adapter's own problem
+      end
+
+      # Callables the method's inputs are passed to as keywords: include_when: of each step, and squish_when.
+      def callables
+        names, open = @definition.input_names
+        gates = @definition.declared_path.first.filter_map do |step|
+          [step[:include_when], "escalation step #{step[:model].inspect} include_when:"] if step[:include_when]
+        end
+        gates << [@definition.predicate, "squish_when"] if @definition.predicate
+        gates.flat_map { |callable, what| KeywordCheck.messages(callable, names, open).map { "#{what} #{_1}" } }
+      end
+    end
+
+    # Whether a Proc called as instance_exec(**inputs, &proc) accepts the inputs.
+    module KeywordCheck
+      module_function
+
+      # Messages for how the proc can't be called with the inputs. open: any keyword may be an input (the method
+      # takes **), so none can be known.
+      def messages(callable, inputs, open)
+        return ["must be a Proc, got #{callable.inspect}"] unless callable.is_a?(Proc)
+        return [] if open
+
+        parameters = callable.parameters
+        [missing_keywords(parameters, inputs), unaccepted_keywords(callable, parameters, inputs),
+         missing_positionals(callable, parameters, inputs)].compact
+      end
+
+      def missing_keywords(parameters, inputs)
+        missing = parameters.filter_map { |type, name| name if type == :keyreq } - inputs
+        return if missing.empty?
+
+        "requires #{keywords(missing)}, which #{missing.one? ? 'is not an input' : 'are not inputs'} of the method"
+      end
+
+      # A lambda with no positional parameters, or a proc that names keywords, raises on a keyword it doesn't take.
+      # Other procs and positional lambdas receive the keywords as a Hash, or ignore them.
+      def unaccepted_keywords(callable, parameters, inputs)
+        types = parameters.map(&:first)
+        return if types.include?(:keyrest) || !strict?(callable, types)
+
+        unaccepted = inputs - parameters.filter_map { |type, name| name if Squawk::KEYWORD_TYPES.include?(type) }
+        return if unaccepted.empty?
+
+        "doesn't accept #{keywords(unaccepted)}, which the method takes as input when a caller passes it (add **)"
+      end
+
+      # A lambda's required positional parameters get the keywords as one Hash, or nothing when there are none or
+      # the lambda names keywords itself.
+      def missing_positionals(callable, parameters, inputs)
+        return unless callable.lambda?
+
+        types = parameters.map(&:first)
+        required = types.count(:req)
+        given = types.intersect?(%i[key keyreq keyrest]) || inputs.empty? ? 0 : 1
+        return unless required > given
+
+        "takes #{required} positional argument(s), but is called with keywords only"
+      end
+
+      def strict?(callable, types)
+        keywords = types.intersect?(Squawk::KEYWORD_TYPES)
+        callable.lambda? ? keywords || !types.intersect?(%i[req opt rest]) : keywords
+      end
+
+      def keywords(names)
+        names.map { |name| "#{name}:" }.join(", ")
+      end
+    end
+
+    def initialize(classes)
+      classes.each { |klass| check_squished!(klass) }
+      @classes = classes
+    end
+
+    def call
+      Verification::Report.new(adapter_problems + @classes.flat_map { |klass| class_problems(klass) })
+    end
+
+    private
+
+    def check_squished!(klass)
+      return if klass.is_a?(Class) && klass.include?(Squishling)
+
+      raise ConfigurationError, "#{klass.inspect} doesn't include Squishling"
+    end
+
+    # The configured adapter, or RubyLLM's, must be usable.
+    def adapter_problems
+      Squishling.config.resolved_adapter
+      []
+    rescue ConfigurationError => e
+      [Verification::Problem.new(label: "adapter", message: e.message)]
+    end
+
+    def class_problems(klass)
+      klass.squished_methods.keys.flat_map do |name|
+        definition = klass.squishling_definition(name)
+        next [] if unused_default?(definition)
+
+        MethodCheck.new(definition).problems
+      end
+    end
+
+    # Every class has the default method (call) squished, whether or not it uses it.
+    def unused_default?(definition)
+      definition.name == ClassMethods::DEFAULT_METHOD && !definition.implemented? && definition.schema.nil?
+    rescue ConfigurationError, ArgumentError
+      false
+    end
+  end
+end

data/lib/squishling/version.rb

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

data/lib/squishling.rb

@@ -2,13 +2,18 @@
 
 require "json"
 require "json_schemer"
-require "ruby_llm"
 require "schematist"
 
 require_relative "squishling/version"
 require_relative "squishling/errors"
 require_relative "squishling/configuration"
 require_relative "squishling/params"
+require_relative "squishling/named_registry"
+require_relative "squishling/adapter/error_body"
+require_relative "squishling/adapter"
+require_relative "squishling/adapters/ruby_llm"
+require_relative "squishling/adapters/openai_options"
+require_relative "squishling/adapters/openai_compatible"
 require_relative "squishling/squawk"
 require_relative "squishling/observer"
 require_relative "squishling/observers/coolhand"
@@ -26,9 +31,11 @@ require_relative "squishling/schema"
 require_relative "squishling/source"
 require_relative "squishling/appendices"
 require_relative "squishling/definition"
+require_relative "squishling/budget"
 require_relative "squishling/llm_client"
 require_relative "squishling/output_check"
 require_relative "squishling/run/messages"
+require_relative "squishling/run/rejections"
 require_relative "squishling/run"
 require_relative "squishling/invoker"
 require_relative "squishling/judge"
@@ -36,6 +43,10 @@ require_relative "squishling/router"
 require_relative "squishling/wrapper"
 require_relative "squishling/class_methods"
 require_relative "squishling/collisions"
+require_relative "squishling/class_registry"
+require_relative "squishling/verification"
+require_relative "squishling/verifier"
+require_relative "squishling/railtie" if defined?(Rails::Railtie)
 
 # 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.
@@ -74,6 +85,47 @@ module Squishling
       Harness.types
     end
 
+    # Registers a custom adapter class (see Adapter::Base) under a name, usable as config.adapter = :name, or
+    # config.adapter = { type: :name, option: value } for an adapter whose initialize takes options. To use an adapter
+    # without registering it, assign an instance: config.adapter = MyAdapter.new. Raises ConfigurationError for a name
+    # that is invalid or already taken, including the built-in :ruby_llm and :openai_compatible.
+    def register_adapter(name, klass)
+      Adapter::Registry.register(name, klass)
+    end
+
+    # The names of the adapters that can be configured: the built-ins, then those registered.
+    def adapters
+      Adapter::Registry.names
+    end
+
+    # Forgets the registered adapters (the built-ins stay), e.g. between specs.
+    def reset_adapters!
+      Adapter::Registry.reset!
+    end
+
+    # Every class that includes Squishling, and each subclass of one, that is loaded and hasn't been replaced by a
+    # reload. Classes are held weakly, so listing them doesn't keep reloaded ones alive. In Rails, eager load first
+    # (Rails.application.eager_load!) to include classes not yet autoloaded.
+    def squished_classes
+      ClassRegistry.classes
+    end
+
+    # Checks squished classes without making a request: each method's output schema and typed result, its resolved
+    # escalation, params, squawk and harness, and the keywords its include_when: and squish_when procs take. Checks
+    # the given classes, or every squished_classes when none are given. Returns a Verification::Report listing every
+    # problem found (ok? when none).
+    def verify(*classes)
+      Verifier.new(classes.empty? ? squished_classes : classes.flatten).call
+    end
+
+    # Like verify, but raises a VerificationError (a ConfigurationError) naming every problem. For CI and boot checks.
+    def verify!(*classes)
+      report = verify(*classes)
+      raise VerificationError, report unless report.ok?
+
+      report
+    end
+
     def included(base)
       raise ConfigurationError, "Squishling can only be included in a class" unless base.is_a?(Class)
 
@@ -108,10 +160,11 @@ module Squishling
   # 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/purpose/harness replace the declared ones, and params merge
-  # key by key over them.
+  # key by key over them. max_total_output_tokens/max_total_input_tokens cap what the call may spend across all its
+  # requests (false lifts a declared cap).
   def squish!(append_to_purpose: nil, context: nil, purpose: nil, model: nil, escalation: nil, provider: nil,
-    params: nil, harness: nil)
+    params: nil, harness: nil, max_total_output_tokens: nil, max_total_input_tokens: nil)
     Router.hand_off(self, { append_to_purpose:, context:, purpose:, model:, escalation:, provider:, params:,
-                            harness: })
+                            harness:, max_total_output_tokens:, max_total_input_tokens: })
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: squishling
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -23,20 +23,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: ruby_llm
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: schematist
   requirement: !ruby/object:Gem::Requirement
@@ -53,12 +39,13 @@ dependencies:
         version: '1.1'
 description: 'Squishling makes Ruby classes elastic. Add a squishling to a class and
   it can send inputs straight to an LLM (OpenAI, Anthropic Claude, Google Gemini,
-  or any provider RubyLLM supports) and return strict-schema-validated, typed results:
-  the same type your Ruby code returns. Use it to gracefully maintain fickle integrations,
-  build interfaces for unknown data formats, and rescue production errors by handing
-  the failing call to the LLM with the source class as context. Write Ruby only for
-  the paths where token costs justify maintaining it. Per-input routing, validated
-  retries, and fallbacks for your LLM calls included.'
+  or any provider RubyLLM supports, or any OpenAI-compatible endpoint, or your own
+  adapter) and return strict-schema-validated, typed results: the same type your Ruby
+  code returns. Use it to gracefully maintain fickle integrations, build interfaces
+  for unknown data formats, and rescue production errors by handing the failing call
+  to the LLM with the source class as context. Write Ruby only for the paths where
+  token costs justify maintaining it. Per-input routing, validated retries, and fallbacks
+  for your LLM calls included.'
 email:
 - mc@coolhandlabs.com
 executables: []
@@ -70,6 +57,7 @@ files:
 - README.md
 - Rakefile
 - SECURITY.md
+- docs/adapters.md
 - docs/configuration.md
 - docs/coolhand.md
 - docs/failures.md
@@ -79,9 +67,18 @@ files:
 - docs/observers.md
 - docs/routing.md
 - docs/schemas.md
+- docs/testing.md
+- docs/verifying.md
 - lib/squishling.rb
+- lib/squishling/adapter.rb
+- lib/squishling/adapter/error_body.rb
+- lib/squishling/adapters/openai_compatible.rb
+- lib/squishling/adapters/openai_options.rb
+- lib/squishling/adapters/ruby_llm.rb
 - lib/squishling/appendices.rb
+- lib/squishling/budget.rb
 - lib/squishling/class_methods.rb
+- lib/squishling/class_registry.rb
 - lib/squishling/collisions.rb
 - lib/squishling/configuration.rb
 - lib/squishling/definition.rb
@@ -97,18 +94,40 @@ files:
 - lib/squishling/judge.rb
 - lib/squishling/llm_client.rb
 - lib/squishling/model_path.rb
+- lib/squishling/named_registry.rb
 - lib/squishling/observer.rb
 - lib/squishling/observers/coolhand.rb
 - lib/squishling/output_check.rb
 - lib/squishling/params.rb
+- lib/squishling/railtie.rb
 - lib/squishling/result.rb
 - lib/squishling/rotation.rb
 - lib/squishling/router.rb
+- lib/squishling/rspec.rb
 - lib/squishling/run.rb
 - lib/squishling/run/messages.rb
+- lib/squishling/run/rejections.rb
 - lib/squishling/schema.rb
 - lib/squishling/source.rb
 - lib/squishling/squawk.rb
+- lib/squishling/tasks/squishling.rake
+- lib/squishling/testing.rb
+- lib/squishling/testing/adapter.rb
+- lib/squishling/testing/checks.rb
+- lib/squishling/testing/direct.rb
+- lib/squishling/testing/errors.rb
+- lib/squishling/testing/fixtures.rb
+- lib/squishling/testing/helpers.rb
+- lib/squishling/testing/minitest.rb
+- lib/squishling/testing/observer.rb
+- lib/squishling/testing/reply.rb
+- lib/squishling/testing/request.rb
+- lib/squishling/testing/rspec.rb
+- lib/squishling/testing/script.rb
+- lib/squishling/testing/state.rb
+- lib/squishling/testing/stubs.rb
+- lib/squishling/verification.rb
+- lib/squishling/verifier.rb
 - lib/squishling/version.rb
 - lib/squishling/wrapper.rb
 homepage: https://github.com/Coolhand-Labs/squishling