squishling 0.1.0

data/docs/routing.md

@@ -0,0 +1,210 @@
+# Routing: Ruby or LLM
+
+Every squished method call is routed to one of two paths: the method's own Ruby implementation (the
+*deterministic* path) or an LLM call (the *elastic* path). Both return the same validated, typed result.
+
+## Which methods are squished
+
+- **`call`** is squished by default, and `InvoiceParser.call(...)` is shorthand for `new.call(...)`.
+- **Any other method** is squished once you declare it with `squish :name, ...` (see [Entry points](#entry-points)).
+- **Methods you don't declare are never wrapped.** They're plain Ruby, though a squished method can call them,
+  and they can call `squish!` on its behalf.
+
+## When a call goes to the LLM
+
+A squished call runs its Ruby implementation unless one of these sends it to the LLM:
+
+| Trigger | Declared where | Decided |
+|---|---|---|
+| `squish_when` (or `when:`) predicate is truthy | class, or per method | before Ruby runs |
+| The method has no implementation: it isn't defined, or it raises `NotImplementedError` | the method body | when Ruby gives up |
+| `squish!` | inside the method, e.g. in a `rescue` | after Ruby has partly run, see [Escalating from Ruby](#escalating-from-ruby-with-squish) |
+
+With no predicate and a working implementation, every call runs Ruby.
+
+The predicate receives the method's inputs as keywords and is evaluated against the instance, so it can read
+instance state too. Accept `**` to ignore inputs you don't need.
+
+```ruby
+class InvoiceParser
+  include Squishling
+  # ...
+  squish_when { |client_name:, **| !HARDENED_CLIENTS.include?(client_name) }
+end
+
+def summarize(text) = raise NotImplementedError   # elastic until someone writes it
+```
+
+When the Ruby implementation runs, a `Hash` it returns is validated against the schema and turned into the
+same typed result the LLM path produces. `result(...)` (alias `squishling_result`) does the same explicitly.
+Invalid deterministic output raises `Squishling::InvalidOutputError` too, so a hardened path can't silently
+drift from the contract.
+
+A `NotImplementedError` raised anywhere inside the method, including from code it calls, also routes to the
+LLM.
+
+Each call is routed on its own, including a squished method that calls itself on smaller inputs. A subclass
+override that calls `super` is one call: it's routed once, at the subclass. A call to the method from its own
+`squish_when` or `squish_fallback` (or an instructions proc) isn't routed again: it runs the Ruby
+implementation, so a fallback can hand the input back to Ruby with `call(**inputs)`.
+
+## Hardening a path
+
+This is the workflow from [Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai):
+
+1. Ship the class with instructions and a schema but no implementation. Every call goes to the LLM.
+2. Watch which inputs carry the volume. `squished?` on each result tells you which path served it.
+3. Write Ruby for the high-volume cases and narrow `squish_when` so only the rest go to the LLM.
+
+Callers never change, because both paths return the same result class.
+
+## Entry points
+
+Squish methods other than `call` with `squish`, optionally overriding the class-level settings per method:
+
+```ruby
+class TicketTriager
+  include Squishling
+
+  squish_context :customer_tier, :product   # instance state sent alongside the arguments
+
+  squish :triage, instructions: "Assign a priority and team.", model: "claude-haiku-4-5" do
+    string :priority, enum: %w[low med high]
+    string :team
+  end
+
+  def initialize(customer_tier:, product:, db:)
+    @customer_tier, @product, @db = customer_tier, product, db
+  end
+
+  def triage(ticket_text) = raise NotImplementedError
+end
+```
+
+`squish` accepts:
+
+- `instructions:` (replaces the class's)
+- `append_instructions:` (added to the class's, see [Appending to the instructions](#appending-to-the-instructions))
+- `output_schema:` (or a schema block)
+- `model:`, `provider:`, and `params:` (generation params; see [Configuration](configuration.md))
+- `when:`, a predicate proc
+- `fallback:` (see [Failure handling](failures.md))
+
+`squish` can come before or after the method's `def`.
+
+## Escalating from Ruby with `squish!`
+
+Call `squish!` inside a squished method to hand *this call* to the LLM: for example, when the Ruby parser
+fails on an input it wasn't written for. It sends the call's arguments, as any LLM call would, and returns the
+typed result (`squished?` is `true`, or `false` if the declared `squish_fallback` supplied it). Return that result
+from the method.
+
+```ruby
+class InvoiceParser
+  include Squishling
+
+  instructions "Extract invoice fields from the client's raw data."
+  append_instructions "Here is the Ruby that parses well-formed invoices, for context on the logic and goals:",
+                      self
+  output_schema do
+    string :invoice_number
+    number :total
+  end
+
+  def call(client_name:, data:)
+    parsed = AcmeParser.parse(data)
+    result(invoice_number: parsed.id, total: parsed.sum)
+  rescue AcmeParser::ParseError => e
+    squish!(append_instructions: "The Ruby parser above failed on this input; the error is in the context.",
+            context: { parse_error: e })
+  end
+end
+```
+
+`squish!` takes these overrides, all optional and all for this call only:
+
+| Option | Effect |
+|---|---|
+| `context:` | A Hash sent under `"context"` with any `squish_context` values (a same-named key wins). Exceptions are sent as `{ "class", "message" }`, never their backtrace. |
+| `append_instructions:` | Added to the declared sections; `false` (alone or first in an Array) drops them for this call |
+| `instructions:` | Replaces the instructions |
+| `model:`, `provider:`, `params:` | E.g. escalate to a stronger model when Ruby fails. A `provider:` needs a `model:`; `params:` merge key by key over the declared ones. |
+
+- **The output schema can't be overridden.** The call still returns the method's result type.
+- **Failures** go through the normal LLM path: a declared `squish_fallback` is used, otherwise
+  `InvalidOutputError` or `LLMError` is raised. When you call `squish!` from a `rescue`, Ruby sets the
+  rescued error as the `cause` of whatever is raised, so you can rescue the LLM failure and raise your own:
+
+  ```ruby
+  rescue AcmeParser::ParseError => e
+    begin
+      squish!(context: { parse_error: e })
+    rescue Squishling::InvalidOutputError, Squishling::LLMError
+      raise InvoiceUnreadable, "neither Ruby nor the LLM could parse invoice #{client_name}"
+    end
+  ```
+
+- It works anywhere beneath a squished method on the same object: in the method itself, in a helper it calls,
+  or in a parent implementation reached through `super`. Calling it anywhere else, or from a `squish_fallback`
+  (which would loop), raises `Squishling::Error`.
+
+## Appending to the instructions
+
+`append_instructions` adds sections to the system prompt after the instructions. It takes items, an Array of
+them, or a block (treated as a Proc item). Each item is one of:
+
+| Item | Sent as |
+|---|---|
+| a String | itself |
+| a class or module (`self` inside a class body is that class) | its Ruby source, including bodies that reopen it in other files (see the limits below) |
+| a method (`instance_method(:call)`, `AcmeParser.method(:parse)`) | that method's source |
+| a Proc | evaluated against the instance on each call; it can return any of the above, an Array of them, or `nil`/`false` to add nothing (`-> { strict? && "Be strict." }`) |
+
+```ruby
+class InvoiceParser
+  include Squishling
+
+  append_instructions "The Ruby that parses well-formed invoices:", self, AcmeParser
+  append_instructions -> { "This client's invoices are in #{currency}." }
+
+  squish :summarize, append_instructions: false do   # no appendices for this method
+    string :summary
+  end
+end
+```
+
+The same option goes in the class-wide call: `squishling append_instructions: ["...", self]`.
+
+Sections are added down the chain: class, then subclass, then `squish :name, append_instructions:`, then
+`squish!(append_instructions:)`. `false` drops everything declared above it, so `[false, "Only this."]`
+replaces it.
+
+Source is read with Ruby's own parser (Prism) the first time it's needed and cached. Some limits:
+
+- A class's source is every `class`/`module` body that defines one of its methods, plus the one where its
+  constant is first assigned (including `Parser = Class.new do ... end`). A body that reopens the class
+  without defining a method isn't included.
+- A class without a constant (built with `Class.new` and never assigned, nested in an anonymous module, or given
+  a temporary name) is sent method by method: each of its own `def`s, without the code around them.
+- A class built from a `Struct.new`/`Data.define` block (`Point = Struct.new(:x) do ... end`) isn't found; reopen
+  it with `class Point` or append its methods individually.
+- Only `def`s count. Methods made with `define_method` or `attr_*` aren't shown, and a method item made that way
+  raises `ConfigurationError`, as does code with no source file, such as code generated by `eval`.
+
+**Appended source is sent to your provider.** Don't append classes that hold secrets in constants.
+
+## What the LLM sees
+
+- **System prompt:** your instructions (a String, or a Proc evaluated against the instance), then any
+  `append_instructions` sections, then a short note describing the input format.
+- **User message:** JSON with the method's arguments, mapped to their parameter names. Any
+  `squish_context` values, and a `squish!` call's `context:`, go under `"context"`:
+
+```json
+{ "arguments": { "ticket_text": "API is down!" },
+  "context":   { "customer_tier": "enterprise", "product": "API" } }
+```
+
+`squish_context` names are read from a method of that name if there is one, otherwise from the instance
+variable. Only context you name is sent. Instance variables are never dumped wholesale, so API clients,
+database connections, and secrets stay out of the prompt.

data/docs/schemas.md

@@ -0,0 +1,87 @@
+# Output schemas and typed results
+
+## Declaring a schema
+
+`output_schema` (and `squish`) accept any of:
+
+- a [Schematist](https://github.com/crmne/schematist) DSL block (the schema DSL RubyLLM 2.0 uses)
+- a `Schematist::Schema` subclass (`RubyLLM::Schema` too, if your app uses the `ruby_llm-schema` shim)
+- a raw JSON Schema `Hash`
+
+```ruby
+output_schema do
+  string :invoice_number
+  number :total
+  array :line_items do
+    object do
+      string :description
+      number :amount
+    end
+  end
+end
+
+output_schema InvoiceSchema   # class InvoiceSchema < Schematist::Schema
+
+output_schema(
+  type: "object",
+  properties: { sentiment: { type: "string", enum: %w[positive negative neutral] } },
+  required: ["sentiment"],
+  additionalProperties: false
+)
+```
+
+## Strict schemas only
+
+Squishling only supports **strict** output schemas: it always asks RubyLLM for strict structured output, and a
+schema declaring `strict: false` raises `Squishling::ConfigurationError`. RubyLLM 2.0 on its own would send a
+schema with optional properties non-strict; Squishling always sets the flag explicitly, so it stays strict.
+
+With raw hashes, follow your provider's strict-mode rules (e.g. list every property in `required` and set
+`additionalProperties: false`). The DSL generates compliant schemas for you, as long as you don't mark fields
+`required: false`. Use `optional` instead (below). A schema the provider rejects in strict mode raises
+`ConfigurationError`.
+
+Not every provider enforces strict mode server-side (Anthropic, for example, doesn't receive the flag), so
+Squishling validates every result itself. See [Failure handling](failures.md).
+
+## Typed results
+
+Object schemas produce `Data` result classes, and nested objects become nested `Data`. Both paths of a
+squished method return the same class.
+
+```ruby
+r = InvoiceParser.call(client_name: "globex", data: csv)
+r.total                          # => 1250.0
+r[:total]                        # => 1250.0
+r.line_items.first.description   # nested Data
+r.to_h                           # deep Hash with symbol keys
+r.squished?                      # => true when it came from the LLM
+```
+
+On the deterministic path, return a `Hash` or build the result with `result(...)`. Either way it's validated
+against the schema.
+
+## Optional vs. empty
+
+Strict mode requires **every key to be present**, so a field can't be left out. To say "not provided", make the
+field nullable with the DSL's `optional`. The key stays required, but its value may be `null`:
+
+```ruby
+output_schema do
+  array :symptoms, of: :string      # always a list; [] means "none"
+  optional :allergies do            # [] means "none", nil means "not mentioned"
+    array of: :string
+  end
+  optional :vitals do               # a typed Data object, or nil
+    object do
+      integer :heart_rate
+    end
+  end
+end
+```
+
+`optional` produces `anyOf: [<schema>, {type: "null"}]`, which is strict-compatible. Squishling types the non-null
+branch as usual: `vitals` is a `Data` object or `nil`, and a list of objects is a list of `Data` objects. In a raw
+JSON Schema, `type: ["array", "null"]` works too. A union with more than one non-null branch is ambiguous, so its
+values come back as plain hashes. If you need the model to tell "none" apart from "not mentioned", say so in your
+instructions.

data/lib/squishling/appendices.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Squishling
+  # append_instructions: extra system-prompt sections placed after the instructions, layered
+  # class -> subclass -> method -> call. Each level adds to the levels above it; `false` drops them.
+  module Appendices
+    ITEM_TYPES = [String, Module, Method, UnboundMethod, Proc].freeze
+
+    module_function
+
+    # Validates one level's items. A single item or an Array; `false` (alone or as an element) is kept as a
+    # marker that clears everything declared before it.
+    def normalize(items, label)
+      items = [items] unless items.is_a?(Array)
+      items.each { |item| check!(item, label) unless item == false }
+      items.dup.freeze
+    end
+
+    # The items in effect once every level is concatenated in order.
+    def resolve(items)
+      items.reduce([]) { |kept, item| item == false ? [] : kept << item }
+    end
+
+    # Strings verbatim, classes/modules/methods as their source, procs evaluated against the receiver
+    # (returning any of those, an Array of them, or nil/false to add nothing, so `-> { strict? && "..." }` works).
+    def render(items, receiver, label)
+      items.flat_map do |item|
+        next [render_item(item)] unless item.is_a?(Proc)
+
+        values = receiver.instance_exec(&item)
+        (values.is_a?(Array) ? values : [values]).select(&:itself).map do |value|
+          check!(value, "#{label} append_instructions proc", procs: false)
+          render_item(value)
+        end
+      end
+    end
+
+    def render_item(item)
+      item.is_a?(String) ? item : Source.render(item)
+    end
+
+    def check!(item, label, procs: true)
+      allowed = procs ? ITEM_TYPES : ITEM_TYPES - [Proc]
+      return if allowed.any? { |type| item.is_a?(type) }
+
+      raise ConfigurationError, "#{label}: append_instructions items must be Strings, classes or modules, " \
+                                "#{procs ? 'methods, or procs' : 'or methods'} (got #{describe(item)})"
+    end
+
+    # Simple values as written; anything else by class only, since a proc returning the wrong object (a user,
+    # a config) shouldn't copy its attributes into an error message.
+    def describe(item)
+      case item
+      when Symbol, Numeric, true, nil then item.inspect
+      else "an instance of #{item.class}"
+      end
+    end
+  end
+end

data/lib/squishling/class_methods.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Class-level DSL available to every squishling class.
+  module ClassMethods
+    DEFAULT_METHOD = :call
+
+    # Set class-wide options in one call:
+    #   squishling model: "claude-sonnet-5-5", instructions: "...", output_schema: MySchema
+    # Pass provider: alongside model: for models missing from RubyLLM's registry, e.g.
+    #   squishling model: "gpt-6-luna", provider: :openai
+    # params: are generation params merged over the configured defaults (see Configuration#default_params):
+    #   squishling params: { temperature: 0.1, top_p: 0.9 }
+    # append_instructions: adds sections after the instructions (see #append_instructions):
+    #   squishling append_instructions: ["The Ruby that handles well-formed input:", self]
+    def squishling(model: nil, provider: nil, params: nil, instructions: nil, append_instructions: nil,
+      output_schema: nil)
+      @squishling_model = model if model
+      @squishling_provider = provider if provider
+      @squishling_params = Params.normalize(params, "#{self} params") if params
+      self.instructions(instructions) if instructions
+      self.append_instructions(append_instructions) unless append_instructions.nil?
+      self.output_schema(output_schema) if output_schema
+      self
+    end
+
+    def squishling_model
+      squishling_lookup(:@squishling_model)
+    end
+
+    def squishling_provider
+      squishling_lookup(:@squishling_provider)
+    end
+
+    # Generation params merged down the inheritance chain, so a subclass overrides individual keys.
+    def squishling_params
+      squishling_inherited(:squishling_params, {}).merge(@squishling_params || {})
+    end
+
+    # The system prompt. A String, or a Proc evaluated against the instance.
+    def instructions(text = nil, &block)
+      return squishling_lookup(:@squishling_instructions) if text.nil? && block.nil?
+
+      @squishling_instructions = block || text
+    end
+
+    # Sections appended to the system prompt after the instructions, added to by subclasses, `squish`, and
+    # `squish!`. Items: Strings; a class or module (`self` for this class) or a method (`instance_method(:call)`),
+    # sent as its Ruby source; or a Proc evaluated against the instance. `false` drops inherited items.
+    #   append_instructions "Here is the Ruby that parses well-formed invoices:", self
+    #   append_instructions { "This client's invoices are in #{currency}." }
+    def append_instructions(*items, &block)
+      items = items.first if items.size == 1 && items.first.is_a?(Array)
+      items += [block] if block
+      (@squishling_append_instructions ||= []).concat(Appendices.normalize(items, "#{self} append_instructions"))
+      self
+    end
+
+    # Every level's items in declaration order, `false` markers included (see Appendices.resolve).
+    def squishling_append_instructions
+      squishling_inherited(:squishling_append_instructions, []) + (@squishling_append_instructions || [])
+    end
+
+    # The output format: a Schematist::Schema subclass (RubyLLM::Schema with the ruby_llm-schema shim),
+    # a raw JSON Schema Hash, or a Schematist DSL block.
+    def output_schema(schema = nil, &block)
+      return squishling_lookup(:@squishling_output_schema) if schema.nil? && block.nil?
+
+      @squishling_output_schema = block ? Schematist::Schema.create(&block) : schema
+    end
+
+    # Routing predicate, called with the method's inputs as keywords and evaluated against the
+    # instance. Truthy sends the call to the LLM; falsy runs the Ruby implementation.
+    def squish_when(&block)
+      @squishling_predicate = block
+    end
+
+    def squishling_predicate
+      squishling_lookup(:@squishling_predicate)
+    end
+
+    # Called with the error and the method's inputs (as keywords) when the LLM path fails with an
+    # InvalidOutputError or LLMError, evaluated against the instance. Its return value is used as
+    # the result (hashes are validated and typed); re-raise to propagate.
+    #   squish_fallback { |error, **inputs| { priority: "medium", team: "support" } }
+    def squish_fallback(&block)
+      @squishling_fallback = block
+    end
+
+    def squishling_fallback
+      squishling_lookup(:@squishling_fallback)
+    end
+
+    # Instance state (attributes or instance variables) to send to the LLM alongside the arguments.
+    def squish_context(*names)
+      (@squishling_context_names ||= []).concat(names.map(&:to_sym))
+    end
+
+    def squishling_context_names
+      (squishling_inherited(:squishling_context_names, []) + (@squishling_context_names || [])).uniq
+    end
+
+    # Make methods elastic. Each may override the class-level settings:
+    #   squish :triage, instructions: "...", model: "...", provider: :openai, when: ->(**) { true },
+    #                   fallback: ->(error, **) { { priority: "medium" } }, append_instructions: [...] do
+    #     string :priority
+    #   end
+    def squish(*names, instructions: nil, append_instructions: nil, output_schema: nil, model: nil, provider: nil,
+      params: nil, when: nil, fallback: nil, &schema_block)
+      schema = schema_block ? Schematist::Schema.create(&schema_block) : output_schema
+      params &&= Params.normalize(params, "#{self} squish params")
+      unless append_instructions.nil?
+        append_instructions = Appendices.normalize(append_instructions, "#{self} squish append_instructions")
+      end
+      options = { instructions:, append_instructions:, output_schema: schema, model:, provider:, params:,
+                  predicate: binding.local_variable_get(:when), fallback: }.compact
+
+      names.map(&:to_sym).each do |name|
+        (@squishling_methods ||= {})[name] = options
+        @squishling_wrapper.wrap(name)
+      end
+    end
+
+    def squished_methods
+      squishling_inherited(:squished_methods, { DEFAULT_METHOD => {} }).merge(@squishling_methods || {})
+    end
+
+    def squishling_definition(name)
+      options = squished_methods.fetch(name.to_sym) { raise Error, "#{self}##{name} is not squished" }
+      Definition.new(klass: self, name: name.to_sym, **options)
+    end
+
+    # Service-object shortcut: InvoiceParser.call(...) == InvoiceParser.new.call(...)
+    def call(...)
+      new.call(...)
+    end
+
+    def inherited(subclass)
+      super
+      subclass.send(:squishling_install_wrapper)
+    end
+
+    private
+
+    # Each class gets its own prepended wrapper so overrides in subclasses are routed too.
+    def squishling_install_wrapper
+      @squishling_wrapper = Wrapper.new
+      prepend(@squishling_wrapper)
+
+      squished_methods.each_key { |name| @squishling_wrapper.wrap(name) }
+    end
+
+    # The superclass's merged setting, or the default at the top of the chain.
+    def squishling_inherited(reader, default)
+      superclass.respond_to?(reader) ? superclass.public_send(reader) : default
+    end
+
+    def squishling_lookup(ivar)
+      klass = self
+      while klass.is_a?(ClassMethods)
+        return klass.instance_variable_get(ivar) if klass.instance_variable_defined?(ivar)
+
+        klass = klass.superclass
+      end
+      nil
+    end
+  end
+end

data/lib/squishling/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Configuration
+    # Model used by every squishling class that doesn't declare its own.
+    # When nil, RubyLLM's own default model is used.
+    attr_accessor :default_model
+
+    # Provider for default_model (e.g. :openai). Only needed for models missing from
+    # RubyLLM's registry.
+    attr_accessor :default_provider
+
+    # Generation params applied to every call, overridable per class and per method.
+    # :temperature and :thinking ({ effort:, budget: }) map to RubyLLM's with_temperature and
+    # with_thinking; any other key (top_p, max_tokens, seed, ...) is passed to the provider as-is.
+    attr_reader :default_params
+
+    # How many times to re-ask the LLM when its output fails schema validation.
+    attr_accessor :max_retries
+
+    # Optional Logger for routing decisions.
+    attr_accessor :logger
+
+    def initialize
+      @default_model = nil
+      @default_provider = nil
+      @default_params = {}
+      @max_retries = 1
+      @logger = nil
+    end
+
+    def default_params=(params)
+      @default_params = Params.normalize(params, "default_params")
+    end
+  end
+end