axn-ruby_llm 0.2.0 → 0.3.0

data/lib/axn/ruby_llm/tool_adapter.rb

@@ -3,17 +3,22 @@
 module Axn
   module RubyLLM
     # Namespaced per-class config (axn's `Axn::Configurable`, PRO-2880): any Axn — with no
-    # adapter-specific mixin required — can declare `configure(:ruby_llm) { |c| c.halt_after = true }`
+    # adapter-specific mixin required — can declare `configure(:ruby_llm) { |c| c.present_as = :message }`
     # to set these per-class, alongside e.g. `configure(:mcp) { ... }` for a different adapter on the
     # same class, without the two colliding. `wrap` resolves them via `resolve_override_for`, which
     # falls back to this module's own global `config` (`Axn::RubyLLM.configure { |c| ... }`) and then
     # to each setting's default — the same class-override-then-global-then-default chain a flat
     # `overridable: true` accessor would give a single-adapter consumer.
     config_namespace :ruby_llm
-    setting :halt_after, default: false, overridable: true
-    setting :provider_params, default: {}, overridable: true
+    setting :provider_options, default: {}, overridable: true
     setting :present_as, default: :structured, one_of: %i[structured message], overridable: true
-    setting :reject_opaque_exposed_values, default: false, one_of: [true, false], overridable: true
+    # `Axn::Tools::AdapterSerialization` (extended onto Axn::RubyLLM in ruby_llm.rb, which is required
+    # before this file reopens the module) owns this setting's declaration so the three adapters can't
+    # drift on it. `default:` is a required kwarg with no core-picked value on purpose: an LLM-facing
+    # adapter is better off shipping an ugly-but-honest rendering than failing the whole tool call, so
+    # ruby_llm (like axn-mcp) declares `false`, where axn-openapi's published output contract declares
+    # `true`. Must follow `config_namespace` above -- it's an `overridable:` setting.
+    declare_reject_opaque_exposed_values! default: false
 
     # Wraps any Axn as a ::RubyLLM::Tool: schema, name, and description are read straight off the
     # Axn's own declared contract (`input_schema` / `resolved_axn_name` / `description`, from axn's
@@ -29,15 +34,14 @@ module Axn
       ADAPTER_FAILURE_MESSAGE = "The tool could not produce a valid response"
 
       class << self
-        def wrap(axn_class, halt_after: nil, provider_params: nil, present_as: nil, render_as: NOT_SET, ambient_context: NOT_SET)
+        def wrap(axn_class, provider_options: nil, present_as: nil, render_as: NOT_SET, provider_params: NOT_SET, ambient_context: NOT_SET)
           validate_present_as_kwargs!(present_as, render_as)
+          validate_provider_options_kwargs!(provider_params)
 
           tool_class = build_tool_class(
             axn_class,
-            halt_after: halt_after.nil? ? Axn::RubyLLM.resolve_override_for(axn_class, :halt_after) : halt_after,
-            provider_params: provider_params.nil? ? Axn::RubyLLM.resolve_override_for(axn_class, :provider_params) : provider_params,
+            provider_options: provider_options.nil? ? Axn::RubyLLM.resolve_override_for(axn_class, :provider_options) : provider_options,
             present_as: present_as.nil? ? Axn::RubyLLM.resolve_override_for(axn_class, :present_as) : present_as,
-            reject_opaque: Axn::RubyLLM.resolve_override_for(axn_class, :reject_opaque_exposed_values),
             ambient_context:,
           )
 
@@ -64,7 +68,50 @@ module Axn
           raise ArgumentError, "present_as must be one of :structured, :message; got #{present_as.inspect}#{hint}"
         end
 
-        def build_tool_class(axn_class, halt_after:, provider_params:, present_as:, reject_opaque:, ambient_context:)
+        # `provider_params:` was renamed to `provider_options:` (PRO-3467) to match RubyLLM 2.0's own
+        # `Tool.provider_options`, which replaced `with_params` for tool-level provider metadata.
+        # Same hard-error treatment as `render_as:` above: pre-1.0, never silently shimmed.
+        def validate_provider_options_kwargs!(provider_params)
+          return if provider_params.equal?(NOT_SET)
+
+          raise ArgumentError,
+                "`provider_params:` was renamed to `provider_options:` " \
+                "(e.g. `Axn::RubyLLM.wrap(..., provider_options: { ... })`)."
+        end
+
+        # `guard_tool_response`'s `on_error`: the transport-native error response, plus the operator's
+        # only pointer to WHY (the tool-facing text stays generic -- see ADAPTER_FAILURE_MESSAGE).
+        # Mirrors axn-openapi's dispatcher hint / axn-mcp's Invocation guard: the config pointer lives
+        # HERE rather than in core's exception message, since core raises the same error for adapters
+        # with no such setting. Named as BOTH config levels, never just the gem-wide setter -- the
+        # value is resolved per-tool, so a `configure(:ruby_llm)` override beats `config`, and core
+        # exposes no way to ask which level supplied a resolved value. Non-committal ("if this is")
+        # because reject_opaque_exposed_values being on doesn't mean THIS failure is an opaque
+        # rejection -- it could equally be a colliding key, a non-finite Float, or a gem bug.
+        #
+        # The whole hint is built and logged INSIDE a best_effort: `axn_class` is caller code, and
+        # interpolating it (a hostile/buggy #to_s) must not raise out of `on_error` -- `guard_tool_response`
+        # reports and re-raises an on_error failure rather than substituting a response, so a raise
+        # here would cost the tool its error response entirely. Deliberately a SEPARATE best_effort
+        # from the guard's own on_exception report: a broken configured logger must not suppress that
+        # report, and a broken reporter must not suppress this diagnostic line -- each is the guard's
+        # only surviving signal when the OTHER one is what's broken.
+        def serialization_failure_response(axn_class, error)
+          Axn::Extensions.best_effort("logging a tool serialization failure hint") do
+            hint = if Axn::RubyLLM.resolve_override_for(axn_class, :reject_opaque_exposed_values)
+                     " (if this is an opaque-value rejection: reject_opaque_exposed_values resolved true for " \
+                       "#{axn_class} — unset it on the action via `configure(:ruby_llm)`, or gem-wide via " \
+                       "`Axn::RubyLLM.config.reject_opaque_exposed_values = false`, whichever is set)"
+                   else
+                     ""
+                   end
+            Axn.config.logger.error { "[axn-ruby_llm] failed to serialize successful result: #{error.class}: #{error.message}#{hint}" }
+          end
+
+          { error: ADAPTER_FAILURE_MESSAGE }
+        end
+
+        def build_tool_class(axn_class, provider_options:, present_as:, ambient_context:)
           # Core's canonical, provider-safe tool_name (PRO-2921): strips configured leading prefixes,
           # snake_cases with single underscores, restricts to [a-z0-9_], and is never blank (anonymous
           # -> "tool"). Pass the `:ruby_llm` adapter key so a per-adapter `tool ruby_llm: { name: }`
@@ -74,15 +121,25 @@ module Axn
           # different name, so provider tool calls / forced choices on the declared name wouldn't
           # match. Absent an override it's identical to the zero-arg name (Axn::MCP.wrap passes `:mcp`
           # the same way -- the author-once point).
+          #
+          # Passed through unmodified (PRO-3467): RubyLLM 2.0's Gemini protocol reads a tool's schema
+          # via `parametersJsonSchema` -- the wire form verbatim, with no whitelist converter in the
+          # way -- so the array-valued-`type` / additionalProperties / min-maxProperties workarounds
+          # 1.x needed here are gone along with the fixed-property Gemini schema converter they patched
+          # around.
           tool_name = axn_class.tool_name(:ruby_llm)
-          input_schema = normalize_nullable_types(axn_class.input_schema)
+          input_schema = axn_class.input_schema
+          # Built HERE, not inside `define_method(:execute)`: `self` in the executed block is the
+          # ::RubyLLM::Tool instance, which has no access to this module's private helpers. Closing
+          # over the lambda from build_tool_class's scope binds it to ToolAdapter instead.
+          on_serialization_failure = ->(e) { serialization_failure_response(axn_class, e) }
 
           Class.new(::RubyLLM::Tool) do
             description(axn_class.description) if axn_class.description
-            params(input_schema)
-            with_params(**provider_params) if provider_params.any?
+            parameters(input_schema)
+            provider_options(provider_options) if provider_options.any?
 
-            define_method(:name) { tool_name }
+            define_singleton_method(:tool_name) { tool_name }
 
             define_method(:execute) do |**args|
               # Run the Axn through axn core's tool Invoker (PRO-2943): input types are coerced from the
@@ -90,8 +147,10 @@ module Axn
               # (the injection guard) while the wrap's own trusted context is injected in its place.
               # Contract violations settle user-facing, so `input_invalid?` lets us hand the model a
               # clean, correctable "Invalid tool arguments" error instead of leaking a dev-facing bug
-              # (which also keeps a bad tool call from paging on_exception).
-              invoker = ::Axn::Tools::Invoker.new(user_facing_input_errors: true, reject_undeclared_inputs: true)
+              # (which also keeps a bad tool call from paging on_exception). `adapter: :ruby_llm`
+              # (PRO-3332) stamps the invoked_via dimension around the call, so a Datadog dashboard can
+              # separate tool-driven traffic from ordinary direct `.call`s with no per-call work here.
+              invoker = ::Axn::Tools::Invoker.new(adapter: :ruby_llm, user_facing_input_errors: true, reject_undeclared_inputs: true)
               result = if ambient_context.equal?(NOT_SET)
                          invoker.call(axn_class, args)
                        else
@@ -110,71 +169,37 @@ module Axn
               # step that runs AFTER it (exposed-value serialization + JSON encoding) can raise
               # outside core's executor: a value core can't render (two Hash keys colliding on one
               # JSON property, a non-finite Float, non-UTF-8 bytes, an opaque value under
-              # reject_opaque), a structure past the JSON encoder's max_nesting, or a gem bug.
-              # RubyLLM has no rescue around a tool's #execute, so any of these would escape and
-              # break the whole chat. Scope the guard to JUST that mapping step (NOT the Invoker call,
-              # which already handles + reports its own exceptions -- double-guarding would
-              # double-report on_exception): report through axn's global on_exception for
-              # observability, then -- honoring core's best_effort_raises_in_dev so a real bug
-              # surfaces loudly rather than being masked -- re-raise in dev, otherwise return a tool
-              # error so #execute ALWAYS yields a value. Shaped to drop into the planned shared
-              # Axn::Tools::Serialization.guard (PRO-2996 §2b) with no behavior change.
-              begin
-                # RubyLLM::Chat#handle_tool_calls only treats a Content/Content::Raw return as-is; any
-                # other object (including a plain Hash) gets `#to_s`'d before being sent to the
-                # provider -- which for a Hash produces Ruby's inspect syntax (`{"k"=>"v"}`), not
-                # JSON. Serialize structured payloads ourselves so the wire form is always valid JSON.
-                payload = if present_as == :message
-                            result.message
-                          else
-                            Axn::Extensions::Serialization.render(result, reject_opaque:).to_json
-                          end
-                halt_after ? halt(payload) : payload
-              rescue StandardError => e
-                # Report through on_exception for observability -- but the reporter is app-configured
-                # and CAN raise (a buggy hook, or one assuming `action` is a settled instance). Core
-                # normally invokes on_exception INSIDE its own best_effort; we call it directly, so a
-                # raising reporter would escape and defeat this guard's never-raises intent (aborting
-                # chat.ask in production). Wrap it in best_effort ourselves -- it swallows + warn-logs
-                # (and reraises in dev per best_effort_raises_in_dev), same as core.
-                Axn::Extensions.best_effort("reporting a tool serialization failure via on_exception") do
-                  Axn.config.on_exception(e, action: axn_class, context: { source: "Axn::RubyLLM" })
+              # reject_opaque_exposed_values), a structure past the JSON encoder's max_nesting, or a
+              # gem bug. RubyLLM has no rescue around a tool's #execute, so any of these would escape
+              # and break the whole chat. `guard_tool_response` (PRO-2996, from
+              # Axn::Tools::AdapterSerialization) is core's shared version of exactly that guard --
+              # report through the global on_exception inside a best_effort, re-raise when
+              # raises_in_dev? so a real bug surfaces loudly, else hand `on_error` the exception so
+              # this adapter builds its own transport-native error response. It is scoped to JUST the
+              # mapping step (NOT the Invoker call, which already handles + reports its own
+              # exceptions -- double-guarding would double-report on_exception), and the block's
+              # return value is #execute's.
+              Axn::RubyLLM.guard_tool_response(axn_class, on_error: on_serialization_failure) do
+                # RubyLLM::Tool.split_result (called from Chat#add_tool_result_message) sends a String
+                # through as-is but `#to_json`'s a returned Hash/Array only via its OWN #to_json
+                # dispatch, not necessarily matching how axn would serialize it (Symbol keys/values,
+                # BigDecimal, Time, opaque-value rejection). Serialize structured payloads ourselves so
+                # the wire form always reflects axn's own serialization contract, not Ruby's default.
+                #
+                # `serialize_exposed` (not `Serialization.render` directly) resolves
+                # reject_opaque_exposed_values PER CALL off the result's own action class, so a
+                # per-tool `configure(:ruby_llm)` override is honored and a config change reaches
+                # already-wrapped tools. `present_as` stays a wrap-time kwarg: it's adapter-owned, not
+                # part of the shared mixin, and `wrap` accepts it as an explicit override.
+                if present_as == :message
+                  result.message
+                else
+                  Axn::RubyLLM.serialize_exposed(result).to_json
                 end
-                raise if Axn::Extensions.raises_in_dev?
-
-                { error: ADAPTER_FAILURE_MESSAGE }
               end
             end
           end
         end
-
-        # axn reflects a nullable/optional field as a JSON Schema array-valued `type`
-        # (e.g. `["integer", "null"]`). That's valid JSON Schema and OpenAI/Anthropic consume it
-        # fine, but RubyLLM's Gemini converter only recognizes anyOf-form nullability: it does
-        # `param_type_for_gemini(type)` with `type.to_s.downcase`, so an array `type` matches no
-        # case and falls through to STRING -- silently dropping both the declared type and the
-        # nullability. Rewrite every array-valued `type` into the equivalent `anyOf: [{type: ...}]`,
-        # which Gemini's `normalize_any_of_schema` collapses back to the real type + nullable, and
-        # which the other providers accept unchanged. Purely a wire-shape change: the admitted value
-        # set is identical, and the adapter's own validator (json_types_for) already reads anyOf.
-        #
-        # Builds new Hashes/Arrays throughout rather than mutating -- axn may hand back a memoized
-        # input_schema, and mutating it would corrupt every other reader.
-        def normalize_nullable_types(node)
-          case node
-          when Hash
-            rebuilt = node.to_h { |key, value| [key, normalize_nullable_types(value)] }
-            if rebuilt[:type].is_a?(Array)
-              types = rebuilt.delete(:type)
-              rebuilt[:anyOf] = types.map { |type| { type: } }
-            end
-            rebuilt
-          when Array
-            node.map { |value| normalize_nullable_types(value) }
-          else
-            node
-          end
-        end
       end
     end
 

data/lib/axn/ruby_llm/version.rb

@@ -2,6 +2,6 @@
 
 module Axn
   module RubyLLM
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/axn/ruby_llm.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "delegate"
 require "ruby_llm"
 require "axn"
 
@@ -12,17 +11,20 @@ module Axn
     include Axn::Mountable
     extend Axn::Configurable
     extend Axn::Tools::AdapterRoots
+    extend Axn::Tools::AdapterSerialization
 
     setting :default_model, default: "gpt-4o-mini"
     setting :enabled, default: true
     setting :error_headline, default: "LLM request failed"
 
-    # `Axn::Tools::AdapterRoots` (extended above) declares `tool_roots` with `default: []`; re-declare
-    # it (core's `setting` is last-wins) to ship the shared agent-tools dir as the default, so any Axn
+    # `Axn::Tools::AdapterRoots` (extended above) declares `tool_roots` with core's conservative
+    # `default: []`; `tool_roots_default` re-declares it to ship the shared agent-tools dir, so any Axn
     # living under `app/agent_tools` is exposed as a `:ruby_llm` tool out of the box. It's the same dir
-    # axn-mcp defaults to, so one Axn there is authored once and surfaces on both. The re-declaration
-    # keeps AdapterRoots' broad-path validation (no widening a root to `app/`/`actions`/`.`/`..`).
-    setting :tool_roots, default: ["agent_tools"], validate: ->(value) { Axn::Tools::AdapterRoots.validate!(value) }
+    # axn-mcp defaults to, so one Axn there is authored once and surfaces on both. Going through
+    # `tool_roots_default` rather than a hand-written `setting` keeps AdapterRoots' broad-path
+    # validation (no widening a root to `app/`/`actions`/`.`/`..`) without hand-copying its lambda, and
+    # validates the default EAGERLY at gem load instead of at the registry's first read.
+    tool_roots_default %w[agent_tools]
 
     # Register this module as the `:ruby_llm` adapter AND its config source (PRO-2948): the registry
     # reads `Axn::RubyLLM.config.tool_roots` off the source to grant directory-based membership.
@@ -30,16 +32,6 @@ module Axn
 
     mount_axn :ask, Ask
 
-    # Backward-compatible view of `config` returned by the deprecated `configuration` alias. The
-    # pre-DSL `Configuration#enabled?` invoked a callable gate (`enabled = -> { ... }`); the
-    # DSL-generated `config.enabled?` returns an assigned Proc as-is (always truthy). Delegate
-    # everything to `config`, but restore the callable-resolving `enabled?` (via the module-level
-    # `enabled?`) so a compatibility caller's production gate still resolves correctly during the
-    # deprecation window instead of silently reading as enabled. Removed with the alias in 0.3.0.
-    class DeprecatedConfigProxy < SimpleDelegator
-      def enabled? = Axn::RubyLLM.enabled?
-    end
-
     class << self
       # `enabled` accepts a Boolean OR a callable — the documented production-gating idiom is
       # `c.enabled = -> { Rails.env.production? }`. axn's Configurable used to invoke an assigned
@@ -51,30 +43,6 @@ module Axn
         value = config.enabled
         value.respond_to?(:call) ? !!value.call : !!value
       end
-
-      # DEPRECATED backward-compatible aliases for the pre-DSL API. The
-      # Axn::Configurable DSL standardizes on `.config` / `reset_config!`.
-      # These keep older callers working but emit a deprecation warning and
-      # are scheduled for removal in the next minor version (see DEPRECATIONS.md).
-      def configuration
-        _warn_deprecated_alias("Axn::RubyLLM.configuration", "Axn::RubyLLM.config")
-        DeprecatedConfigProxy.new(config)
-      end
-
-      def reset_configuration!
-        _warn_deprecated_alias("Axn::RubyLLM.reset_configuration!", "Axn::RubyLLM.reset_config!")
-        reset_config!
-      end
-
-      private
-
-      def _warn_deprecated_alias(old, new)
-        warn(
-          "[axn-ruby_llm] DEPRECATION: #{old} is deprecated and will be removed in the next minor version; use #{new} instead.",
-          category: :deprecated,
-          uplevel: 2,
-        )
-      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axn-ruby_llm
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kali Donovan
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.5
+        version: 0.1.0.pre.alpha.6.1
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.5
+        version: 0.1.0.pre.alpha.6.1
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -35,22 +35,36 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.10.0
 description: Call LLMs from Axn actions using RubyLLM, with structured error handling,
-  optional JSON mode, and cost/token tracking.
+  schema-based structured output, and cost/token tracking.
 email:
 - kali@teamshares.com
 executables: []