squishling 0.3.0 → 0.5.0

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.3.0"
+  VERSION = "0.5.0"
 end

data/lib/squishling.rb

@@ -2,29 +2,51 @@
 
 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"
 require_relative "squishling/model_path"
+require_relative "squishling/rotation"
+require_relative "squishling/harness/option_types"
+require_relative "squishling/harness/registry"
+require_relative "squishling/harness/base"
+require_relative "squishling/harness/escalation"
+require_relative "squishling/harness/squishsum"
+require_relative "squishling/harness/judged_squishsum"
 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/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"
 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.
@@ -42,6 +64,68 @@ module Squishling
       @config = Configuration.new
     end
 
+    # Forgets the registered harnesses (the built-ins stay), e.g. between specs. Kept apart from reset_config!
+    # because harnesses are registered once at boot, and a suite that resets its config between examples
+    # shouldn't lose them.
+    def reset_harnesses!
+      Harness::Registry.reset!
+    end
+
+    # Registers a custom harness under a name, usable anywhere a built-in type is (harness: :name, or
+    # harness: { type: :name, option: value }, on a class, a method, a squish! call, or config.default_harness).
+    # Pass a Harness::Base subclass, or a block that becomes the body of one (see Harness::Base). Registered
+    # globally, so do it before the classes that use it load (an initializer). Raises ConfigurationError for a
+    # name that is invalid or already taken, including the built-in :escalation, :squishsum, :judged_squishsum.
+    def register_harness(name, klass = nil, &)
+      Harness::Registry.register(name, klass, &)
+    end
+
+    # The names of the harnesses that can be declared: the built-ins, then those registered.
+    def harnesses
+      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)
 
@@ -76,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.3.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,32 +57,77 @@ files:
 - README.md
 - Rakefile
 - SECURITY.md
+- docs/adapters.md
 - docs/configuration.md
+- docs/coolhand.md
 - docs/failures.md
 - docs/harnesses.md
 - docs/measuring-tokens.md
 - docs/naming.md
+- 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
 - lib/squishling/errors.rb
 - lib/squishling/harness.rb
+- lib/squishling/harness/base.rb
+- lib/squishling/harness/escalation.rb
+- lib/squishling/harness/judged_squishsum.rb
+- lib/squishling/harness/option_types.rb
+- lib/squishling/harness/registry.rb
+- lib/squishling/harness/squishsum.rb
 - lib/squishling/invoker.rb
 - 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