squishling 0.1.0

data/lib/squishling/source.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Ruby source for append_instructions 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
+    # by code reloading (e.g. Rails in development) can be collected.
+    CACHE = ObjectSpace::WeakKeyMap.new
+    CACHE_LOCK = Mutex.new
+    CLASS_NODES = %i[class_node module_node].freeze
+
+    class << self
+      def render(item)
+        # Methods are keyed by owner and name: `method(:call)` builds a new object on every call.
+        owner, name = item.is_a?(Module) ? [item, nil] : [item.owner, item.name]
+        CACHE_LOCK.synchronize do
+          rendered = (CACHE[owner] ||= {})
+          rendered.fetch(name) { rendered[name] = fence(*extract(item)) }
+        end
+      end
+
+      private
+
+      def extract(item)
+        require "prism"
+        item.is_a?(Module) ? module_source(item) : method_source(unwrap(item))
+      end
+
+      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?
+
+        [display_name(mod), sources.join("\n\n")]
+      end
+
+      # Every `class X`/`module X` body for the constant that holds one of its methods, so a class reopened across
+      # files is covered, or the Class.new/Module.new block the constant is assigned from (`X = Class.new do`).
+      def class_bodies(mod, constant)
+        anchors = [constant, *own_methods(mod).map { |method| location(method) }].compact
+        anchors.group_by(&:first).flat_map do |file, pairs|
+          tree, text = parse(file)
+          nodes = pairs.map(&:last).uniq.filter_map do |line|
+            innermost(tree, line) { |node, enclosing| defines?(node, enclosing, mod, [file, line] == constant) }
+          end
+          nodes.uniq.sort_by { |node| node.location.start_line }.map { |node| slice(node, text) }
+        end
+      end
+
+      # Without a constant there's no class body to find reliably (its methods may come from a factory or a
+      # class_eval inside unrelated code), so each of its own `def`s is sent instead, and nothing around them.
+      def method_defs(mod)
+        parsed = {}
+        own_methods(mod).sort_by { |method| location(method) || [] }.filter_map { |method| def_source(method, parsed) }
+      end
+
+      def method_source(method)
+        label = method_label(method)
+        source = def_source(method)
+        raise ConfigurationError, "append_instructions: source for #{label} isn't available" unless source
+
+        [label, source]
+      end
+
+      # The method's own `def`, matched by name and line, or nil (define_method, attr_*, eval'd code).
+      def def_source(method, parsed = {})
+        file, line = location(method)
+        return unless file
+
+        tree, text = (parsed[file] ||= parse(file))
+        node = innermost(tree, line) do |candidate|
+          candidate.type == :def_node && candidate.name == method.original_name && candidate.location.start_line == line
+        end
+        node && slice(node, text)
+      end
+
+      # [file, line] for code in a readable file. Some Ruby builds add columns to source_location.
+      def location(method)
+        file, line = method.source_location
+        [file, line] if file && File.file?(file)
+      end
+
+      # 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"
+      end
+
+      # Named after the def that's shown, so an alias is labeled by its original name.
+      def method_label(method)
+        owner = method.owner
+        return "#{display_name(owner.attached_object)}.#{method.original_name}" if owner.singleton_class?
+
+        "#{display_name(owner)}##{method.original_name}"
+      end
+
+      # The module's own instance and singleton methods, as UnboundMethods.
+      def own_methods(mod)
+        names = mod.instance_methods(false) + mod.private_instance_methods(false)
+        singleton = mod.singleton_class
+        singleton_names = mod.singleton_methods(false) + singleton.private_instance_methods(false)
+        names.filter_map { |name| own_method(mod, name) } +
+          singleton_names.filter_map { |name| own_method(singleton, name) }
+      end
+
+      # instance_method resolves to a prepended module (Squishling's wrapper, or any other) first. Going through
+      # instance_method also bypasses a class's own `self.method` (e.g. an HTTP request model).
+      def own_method(mod, name)
+        method = mod.instance_method(name)
+        method = method.super_method until method.nil? || method.owner == mod
+        method
+      end
+
+      # A `class X`/`module X` node whose full lexical name is the module's (so a monkeypatch from inside an
+      # unrelated `Vendor::Client` never sends that class for `Billing::Client`), or the Class.new/Module.new block
+      # at the constant's assignment, never an unrelated block that happens to define one of its methods.
+      def defines?(node, enclosing, mod, at_constant)
+        if CLASS_NODES.include?(node.type)
+          lexical_name([*enclosing, node]) == module_name(mod)
+        else
+          at_constant && node.type == :call_node && node.name == :new && node.block &&
+            %w[Class Module].include?(node.receiver&.slice)
+        end
+      end
+
+      # Where the module's constant is assigned, or nil when it has none in a readable file: anonymous, nested in
+      # an anonymous namespace ("#<Module:0x...>::Parser"), given a temporary name (set_temporary_name), or eval'd.
+      def constant_location(mod)
+        name = module_name(mod)
+        file, line = name && Object.const_source_location(name)
+        [file, line] if file && File.file?(file)
+      rescue NameError
+        nil
+      end
+
+      # The deepest node containing the line that satisfies the block, which also gets the enclosing nodes.
+      def innermost(node, line, enclosing = [], &)
+        location = node.location
+        return nil unless line.between?(location.start_line, location.end_line)
+
+        node.compact_child_nodes.each do |child|
+          found = innermost(child, line, [*enclosing, node], &)
+          return found if found
+        end
+        yield(node, enclosing) ? node : nil
+      end
+
+      # The constant a class/module node defines, from it and the class/module nodes around it
+      # (`module Billing; class Client` and `class Billing::Client` are both "Billing::Client").
+      def lexical_name(nodes)
+        nodes.select { |node| CLASS_NODES.include?(node.type) }.reduce("") do |name, node|
+          path = node.constant_path.slice
+          next path.delete_prefix("::") if path.start_with?("::") || name.empty?
+
+          "#{name}::#{path}"
+        end
+      end
+
+      # Ruby reads source as UTF-8 whatever the locale (e.g. LANG=C in a container).
+      def parse(file)
+        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})"
+      end
+
+      # Give the node's first line its source line's indentation (it may start mid-line, as in
+      # `parser = Class.new do`), then strip the indentation shared by every line.
+      def slice(node, text)
+        lines = "#{text[node.location.start_line - 1][/\A */]}#{node.slice}".lines
+        indent = lines.reject { |line| line.strip.empty? }.map { |line| line[/\A */].size }.min || 0
+        lines.map { |line| line.strip.empty? ? "\n" : line[indent..] }.join.chomp
+      end
+
+      def display_name(mod)
+        return "(#{mod.class} instance)" unless mod.is_a?(Module)
+
+        module_name(mod) || "(anonymous #{mod.is_a?(Class) ? 'class' : 'module'})"
+      end
+
+      # The constant name Ruby assigned, ignoring any `def self.name` override on the class.
+      def module_name(mod)
+        Module.instance_method(:name).bind_call(mod)
+      end
+
+      # A fence longer than any backtick run in the source, so the code can't close it early.
+      def fence(label, code)
+        ticks = "`" * [3, (code.scan(/`+/).map(&:size).max || 0) + 1].max
+        "#{ticks}ruby\n# Source: #{label}\n#{code}\n#{ticks}"
+      end
+    end
+  end
+end

data/lib/squishling/version.rb

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

data/lib/squishling/wrapper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Module prepended to a squishling class. It intercepts squished methods regardless of
+  # whether they're defined before or after the `squish` declaration (or at all).
+  class Wrapper < Module
+    # The method beneath any Squishling wrappers (instance_method resolves to the prepended wrapper first),
+    # or nil when the method has no implementation.
+    def self.implementation(method)
+      method = method.super_method while method&.owner.is_a?(Wrapper)
+      method
+    end
+
+    def wrap(name)
+      return if method_defined?(name, false)
+
+      wrapper = self
+      define_method(name) do |*args, **kwargs, &block|
+        impl =
+          if defined?(super)
+            -> { super(*args, **kwargs, &block) }
+          else
+            -> { raise NotImplementedError, "#{self.class}##{name} has no implementation" }
+          end
+
+        Router.dispatch(self, name, args, kwargs, impl, wrapper:)
+      end
+    end
+
+    def inspect
+      "#<Squishling::Wrapper>"
+    end
+  end
+end

data/lib/squishling.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+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/result"
+require_relative "squishling/schema"
+require_relative "squishling/source"
+require_relative "squishling/appendices"
+require_relative "squishling/definition"
+require_relative "squishling/invoker"
+require_relative "squishling/router"
+require_relative "squishling/wrapper"
+require_relative "squishling/class_methods"
+
+# 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.
+module Squishling
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    def included(base)
+      raise ConfigurationError, "Squishling can only be included in a class" unless base.is_a?(Class)
+
+      base.extend(ClassMethods)
+      base.send(:squishling_install_wrapper)
+    end
+  end
+
+  # Build the typed result for the squished method currently executing, validating it against
+  # the output schema. Use this from the deterministic path so both paths return the same type.
+  def squishling_result(attrs = nil, **kwargs)
+    frame = Router.current_frame(self)
+    raise Error, "#{self.class}#squishling_result called outside a squished method" unless frame
+
+    frame.definition.build_result(attrs || kwargs, squished: false)
+  end
+
+  alias_method :result, :squishling_result
+
+  # 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,
+  # 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: })
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: squishling
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Carroll
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: schematist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        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.'
+email:
+- mc@coolhandlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- SECURITY.md
+- docs/configuration.md
+- docs/failures.md
+- docs/routing.md
+- docs/schemas.md
+- lib/squishling.rb
+- lib/squishling/appendices.rb
+- lib/squishling/class_methods.rb
+- lib/squishling/configuration.rb
+- lib/squishling/definition.rb
+- lib/squishling/errors.rb
+- lib/squishling/invoker.rb
+- lib/squishling/params.rb
+- lib/squishling/result.rb
+- lib/squishling/router.rb
+- lib/squishling/schema.rb
+- lib/squishling/source.rb
+- lib/squishling/version.rb
+- lib/squishling/wrapper.rb
+homepage: https://github.com/Coolhand-Labs/squishling
+licenses:
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Coolhand-Labs/squishling
+  source_code_uri: https://github.com/Coolhand-Labs/squishling
+  changelog_uri: https://github.com/Coolhand-Labs/squishling/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/Coolhand-Labs/squishling/tree/main/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Elastic Ruby classes with LLM batteries included: zero-code integrations,
+  graceful error rescue, and code only where it''s worth maintaining.'
+test_files: []