patient_llm 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1b92ba6cfe7609461cc940064399ce5a9c17f79ad18b5beaea3ae33ef9bfb11
-  data.tar.gz: c3420d27801ab7571685e6d3fde742ed7203ecb01a068a89749c07c6511fc11b
+  metadata.gz: a477a6fc932f1ad07d9dae5c06bc71e3ebac003a10b155400076172a7f0a67fc
+  data.tar.gz: 6d11574edcede56eb37658e36f94fe2f45aa693fc058508c8058eeab3df6429b
 SHA512:
-  metadata.gz: eab9baa8560c32b4af7cdda7c1f72b13701f86c7295e3c2b5ae990b073707f69687e207b9908672e8dc78a6d0134fe829f20b3d40cb9d3b3c2bc5197b53c071a
-  data.tar.gz: 826f52f65cf57779edcbb1ee5dcdb8be254cff69d509eaa30b25e799a955db4f5c5413160b535c2169906a62f0e6d7bfda55589f7a7273a2003a431de49cdc25
+  metadata.gz: eb0cde4a1466a1a885f78b0a57c3ec50124650672cee430d13818d0daa3b3ddb0baf1fe3b326165ddf43d814e6c458eceb8ff4d9b24c21d33902b861bcd1f3f3
+  data.tar.gz: 881b6d03088e1d3880597fb3fecb87b5e53885846d39f61548394ef2cd68ced822f3dd7e6514061d522942ed7fe084f0e8c86ec8752d9233cb206218fe783a28

data/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.6.0
+
+### Added
+
+- Added `PatientLLM.preview_request` and `PatientLLM::Agent.preview_request` to build the request that `ask` would send without sending it. Both return a `PatientLLM::RequestPreview` with the resolved `url`, `headers`, and JSON `payload`, produced by the same resolution logic dispatch uses. Nothing is enqueued or executed, header values that reference registered secrets are replaced with placeholders, and request preprocessors (which run at send time) are not applied. `Agent.preview_request` accepts the same options as `ask`, ignoring `context:` and `callback:` since they do not affect the request.
+
 ## 0.5.1
 
 ### Added

data/README.md

@@ -364,6 +364,16 @@ response = ResearchAgent.ask!("What is the capital of France?")
 response.text   # => "Paris."
 ```
 
+### Previewing requests
+
+`preview_request` builds the request that `ask` would send — through the same resolution logic — without sending anything. It returns a `PatientLLM::RequestPreview` with the resolved `url`, `headers`, and JSON `payload`. Header values that reference registered secrets are replaced with placeholders, and request preprocessors (which run at send time) are not applied:
+
+```ruby
+preview = ResearchAgent.preview_request("What is the capital of France?")
+preview.url       # => "https://api.openai.com/v1/chat/completions"
+preview.payload   # => {"model" => "gpt-4o", "messages" => [...], ...}
+```
+
 ## The low-level API
 
 Agents compile down to this API; use it directly when you need full control.
@@ -451,6 +461,13 @@ PatientLLM.ask(session,
 
 `headers` and `params` are merged on top of the provider's configured values, while the other options replace the provider defaults. All overrides are preserved across automatic tool-loop iterations.
 
+`PatientLLM.preview_request` accepts the same arguments (minus `callback:`) and returns the request that `ask` would send — a `PatientLLM::RequestPreview` with the resolved `url`, `headers` (secret values redacted), and JSON `payload` — without enqueuing or executing anything:
+
+```ruby
+preview = PatientLLM.preview_request(session, provider: :openai)
+preview.payload   # => {"model" => "gpt-4o", "messages" => [...]}
+```
+
 ### Tool calling with the registry
 
 Tools can also be registered on the global `PromptBuilder.tool_registry` with their handler, then attached to sessions by name — no schema duplication:

data/VERSION

@@ -1 +1 @@
-0.5.1
+0.6.0

data/lib/patient_llm/agent.rb

@@ -353,6 +353,37 @@ module PatientLLM
         capture[:response] || raise("No response was captured; the request did not complete")
       end
 
+      # Build the request that {ask} would send without sending it. The
+      # session is built from the agent's declarations exactly as {ask} builds
+      # it (including any per-request session options and the user message,
+      # which is appended to a passed session), and the request is resolved
+      # through the same logic as a dispatched request. Nothing is enqueued or
+      # executed. See {PatientLLM.preview_request} for details on what the
+      # preview does and does not reflect.
+      #
+      # @param message [String, Array, Hash, nil] the user message to add
+      # @param session [PromptBuilder::Session, nil] an existing session to use
+      #   instead of building a new one
+      # @param context [Hash, nil] accepted for parity with {ask} and ignored;
+      #   the context does not affect the request
+      # @param callback [Class, String, nil] accepted for parity with {ask} and
+      #   ignored; the callback does not affect the request
+      # @param options [Hash] the same per-request overrides accepted by {ask}
+      # @return [PatientLLM::RequestPreview] the url, headers, and JSON payload
+      def preview_request(message = nil, session: nil, context: nil, callback: nil, **options)
+        session_options = options.slice(*PromptBuilder::Session::INITIALIZE_OPTIONS)
+        raise ArgumentError.new("session options cannot be passed when a session is provided") if session && session_options.any?
+
+        session ||= build_session(**session_options)
+        session.user(message) if message
+
+        PatientLLM.preview_request(
+          session,
+          provider: provider_name!,
+          **options.except(*PromptBuilder::Session::INITIALIZE_OPTIONS)
+        )
+      end
+
       # Build a new session from the agent's declarations. Options passed by
       # the caller take precedence over the agent's declarations for the same
       # fields (pass an explicit nil to unset a declared value for one request).

data/lib/patient_llm/request_preview.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PatientLLM
+  # The request that {PatientLLM.ask} would send, as returned by
+  # {PatientLLM.preview_request} and {Agent.preview_request}. Header values
+  # that reference registered secrets are replaced with placeholder strings.
+  #
+  # @!attribute [r] url
+  #   @return [String] The fully resolved request URL
+  # @!attribute [r] headers
+  #   @return [Hash] The request headers, with secret values redacted
+  # @!attribute [r] payload
+  #   @return [Hash] The JSON request payload
+  RequestPreview = Data.define(:url, :headers, :payload)
+end

data/lib/patient_llm.rb

@@ -16,6 +16,7 @@ module PatientLLM
   autoload :HaltError, File.expand_path("patient_llm/halt_error", __dir__)
   autoload :MaxToolIterationsError, File.expand_path("patient_llm/max_tool_iterations_error", __dir__)
   autoload :Presets, File.expand_path("patient_llm/presets", __dir__)
+  autoload :RequestPreview, File.expand_path("patient_llm/request_preview", __dir__)
   autoload :Schema, File.expand_path("patient_llm/schema", __dir__)
   autoload :StructuredOutputError, File.expand_path("patient_llm/structured_output_error", __dir__)
 
@@ -157,24 +158,65 @@ module PatientLLM
     #   {Callback::MAX_TOOL_ITERATIONS}.
     # @return [Object] Handler-specific identifier for the enqueued request
     def ask(session, provider:, callback:, callback_args: {}, url: nil, serializer: nil, path: nil, headers: nil, params: nil, preprocessors: nil, timeout: nil, max_tool_iterations: nil)
-      request_options = {}
-      request_options["url"] = url if url
-      request_options["serializer"] = serializer.to_s if serializer
-      request_options["path"] = path if path
-      request_options["headers"] = headers if headers && !headers.empty?
-      request_options["params"] = params if params && !params.empty?
-      request_options["preprocessors"] = preprocessors if preprocessors
-      request_options["timeout"] = timeout if timeout
-      request_options["max_tool_iterations"] = max_tool_iterations if max_tool_iterations
-
-      # The request options travel through the job queue in the callback args,
-      # which only permit JSON-native values; convert Symbols (e.g. serializer
-      # names, preprocessor names, header/param values) to Strings up front.
-      request_options = PromptBuilder.jsonify(request_options)
+      request_options = build_request_options(
+        url: url,
+        serializer: serializer,
+        path: path,
+        headers: headers,
+        params: params,
+        preprocessors: preprocessors,
+        timeout: timeout,
+        max_tool_iterations: max_tool_iterations
+      )
 
       dispatch(session, provider: provider, callback: callback, callback_args: callback_args, request_options: request_options)
     end
 
+    # Build the request that {.ask} would send without sending it. The same
+    # resolution logic as {.ask} is applied: per-request overrides are merged
+    # over the provider configuration, the session is serialized with the
+    # resolved serializer, and provider params are merged into the payload.
+    #
+    # Nothing is enqueued or executed and no callback is required. Request
+    # preprocessors (e.g. AWS SigV4 signing) run at send time in the request
+    # processor, so their changes are not reflected in the preview. Header
+    # values that reference registered secrets are replaced with placeholders
+    # and never resolved.
+    #
+    # @param session [PromptBuilder::Session] The prompt session containing conversation state
+    # @param provider [Symbol, String] Registered provider name
+    # @param url [String, nil] Override the provider's base URL for this request
+    # @param serializer [Symbol, nil] Override the provider's serializer for this request
+    # @param path [String, nil] Override the endpoint path for this request
+    # @param headers [Hash, nil] Additional headers merged on top of provider headers
+    # @param params [Hash, nil] Additional params merged into the request payload
+    # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] Accepted for
+    #   parity with {.ask}; preprocessors are not applied to the preview.
+    # @param timeout [Numeric, nil] Accepted for parity with {.ask}; does not affect the preview.
+    # @param max_tool_iterations [Integer, nil] Accepted for parity with {.ask}; does not
+    #   affect the preview.
+    # @return [RequestPreview] The url, headers, and JSON payload the request would send
+    def preview_request(session, provider:, url: nil, serializer: nil, path: nil, headers: nil, params: nil, preprocessors: nil, timeout: nil, max_tool_iterations: nil)
+      request_options = build_request_options(
+        url: url,
+        serializer: serializer,
+        path: path,
+        headers: headers,
+        params: params,
+        preprocessors: preprocessors,
+        timeout: timeout,
+        max_tool_iterations: max_tool_iterations
+      )
+
+      resolved = resolve_request(session, self.provider(provider) || {}, request_options)
+
+      RequestPreview.new(
+        url: resolved.url,
+        headers: redact_secret_headers(resolved.headers),
+        payload: resolved.payload
+      )
+    end
+
     # Internal dispatch used by {.ask} and by {Callback} to re-issue requests
     # during the automatic tool loop. Not part of the public API.
     #
@@ -187,45 +229,16 @@ module PatientLLM
         PatientLLM::Callback.validate_callback_class!(PatientHttp::ClassHelper.resolve_class_name(callback.to_s))
       end
 
-      resolved_url = request_options["url"] || provider_config[:url]
-      raise ArgumentError, "No API base URL configured. Set url: or register a provider with a url." unless resolved_url
-
-      resolved_serializer = (request_options["serializer"] || provider_config[:serializer] || :chat_completion).to_sym
-      validate_serializer!(resolved_serializer)
-
-      resolved_path = request_options["path"] || provider_config[:path] || SERIALIZER_PATHS[resolved_serializer]
-      if resolved_path.include?("{model}")
-        raise ArgumentError, "The endpoint path #{resolved_path.inspect} includes a {model} placeholder but session.model is not set" if session.model.nil?
-
-        # Encode the model as a single path segment; Bedrock model ids can be
-        # ARNs containing ":" and "/" that would otherwise splice extra path
-        # segments into the URL and break SigV4 signing.
-        resolved_path = resolved_path.gsub("{model}", URI.encode_uri_component(session.model.to_s))
-      end
-
-      resolved_headers = (provider_config[:headers] || {}).merge(request_options["headers"] || {})
-      if resolved_serializer == :messages && !resolved_headers.key?("anthropic-version")
-        resolved_headers = {"anthropic-version" => ANTHROPIC_VERSION}.merge(resolved_headers)
-      end
-
-      resolved_params = (provider_config[:params] || {}).merge(request_options["params"] || {})
-      resolved_preprocessors = request_options["preprocessors"] || provider_config[:preprocessors]
-      resolved_timeout = request_options["timeout"] || provider_config[:timeout]
-      resolved_max_tool_iterations = (request_options["max_tool_iterations"] || provider_config[:max_tool_iterations] || Callback::MAX_TOOL_ITERATIONS).to_i
-
-      payload = session.request_payload(resolved_serializer)
-      payload = deep_merge(payload, deep_stringify_keys(resolved_params)) unless resolved_params.empty?
-
-      request_url = join_url(resolved_url, resolved_path)
+      resolved = resolve_request(session, provider_config, request_options)
 
       dispatch_callback_args = {
         session: session_payload(session),
         provider: provider_name,
-        serializer: resolved_serializer.to_s,
+        serializer: resolved.serializer.to_s,
         callback: callback.to_s,
         custom: PromptBuilder.jsonify(callback_args || {}),
         request_options: request_options,
-        max_tool_iterations: resolved_max_tool_iterations,
+        max_tool_iterations: resolved.max_tool_iterations,
         tool_iteration: tool_iteration,
         original_request_id: original_request_id
       }
@@ -233,11 +246,11 @@ module PatientLLM
       if inline?
         request = PatientHttp::Request.new(
           :post,
-          request_url,
-          json: payload,
-          headers: resolved_headers,
-          preprocessors: resolved_preprocessors,
-          timeout: resolved_timeout
+          resolved.url,
+          json: resolved.payload,
+          headers: resolved.headers,
+          preprocessors: resolved.preprocessors,
+          timeout: resolved.timeout
         )
         PatientHttp.execute_inline(
           request: request,
@@ -247,11 +260,11 @@ module PatientLLM
         )
       else
         PatientHttp.post(
-          request_url,
-          json: payload,
-          headers: resolved_headers,
-          preprocessors: resolved_preprocessors,
-          timeout: resolved_timeout,
+          resolved.url,
+          json: resolved.payload,
+          headers: resolved.headers,
+          preprocessors: resolved.preprocessors,
+          timeout: resolved.timeout,
           raise_error_responses: true,
           callback: PatientLLM::Callback,
           callback_args: dispatch_callback_args
@@ -261,6 +274,79 @@ module PatientLLM
 
     private
 
+    # Fully resolved request produced by merging per-request options over the
+    # provider configuration.
+    ResolvedRequest = Data.define(:url, :serializer, :headers, :payload, :preprocessors, :timeout, :max_tool_iterations)
+    private_constant :ResolvedRequest
+
+    # Normalize per-request overrides into a request options hash. The request
+    # options travel through the job queue in the callback args, which only
+    # permit JSON-native values; convert Symbols (e.g. serializer names,
+    # preprocessor names, header/param values) to Strings up front.
+    def build_request_options(url:, serializer:, path:, headers:, params:, preprocessors:, timeout:, max_tool_iterations:)
+      request_options = {}
+      request_options["url"] = url if url
+      request_options["serializer"] = serializer.to_s if serializer
+      request_options["path"] = path if path
+      request_options["headers"] = headers if headers && !headers.empty?
+      request_options["params"] = params if params && !params.empty?
+      request_options["preprocessors"] = preprocessors if preprocessors
+      request_options["timeout"] = timeout if timeout
+      request_options["max_tool_iterations"] = max_tool_iterations if max_tool_iterations
+
+      PromptBuilder.jsonify(request_options)
+    end
+
+    # Resolve the request URL, headers, payload, and execution settings from
+    # the request options merged over the provider configuration. This is the
+    # single source of truth for what a request looks like; both {.dispatch}
+    # and {.preview_request} build requests through it.
+    def resolve_request(session, provider_config, request_options)
+      resolved_url = request_options["url"] || provider_config[:url]
+      raise ArgumentError, "No API base URL configured. Set url: or register a provider with a url." unless resolved_url
+
+      resolved_serializer = (request_options["serializer"] || provider_config[:serializer] || :chat_completion).to_sym
+      validate_serializer!(resolved_serializer)
+
+      resolved_path = request_options["path"] || provider_config[:path] || SERIALIZER_PATHS[resolved_serializer]
+      if resolved_path.include?("{model}")
+        raise ArgumentError, "The endpoint path #{resolved_path.inspect} includes a {model} placeholder but session.model is not set" if session.model.nil?
+
+        # Encode the model as a single path segment; Bedrock model ids can be
+        # ARNs containing ":" and "/" that would otherwise splice extra path
+        # segments into the URL and break SigV4 signing.
+        resolved_path = resolved_path.gsub("{model}", URI.encode_uri_component(session.model.to_s))
+      end
+
+      resolved_headers = (provider_config[:headers] || {}).merge(request_options["headers"] || {})
+      if resolved_serializer == :messages && !resolved_headers.key?("anthropic-version")
+        resolved_headers = {"anthropic-version" => ANTHROPIC_VERSION}.merge(resolved_headers)
+      end
+
+      resolved_params = (provider_config[:params] || {}).merge(request_options["params"] || {})
+
+      payload = session.request_payload(resolved_serializer)
+      payload = deep_merge(payload, deep_stringify_keys(resolved_params)) unless resolved_params.empty?
+
+      ResolvedRequest.new(
+        url: join_url(resolved_url, resolved_path),
+        serializer: resolved_serializer,
+        headers: resolved_headers,
+        payload: payload,
+        preprocessors: request_options["preprocessors"] || provider_config[:preprocessors],
+        timeout: request_options["timeout"] || provider_config[:timeout],
+        max_tool_iterations: (request_options["max_tool_iterations"] || provider_config[:max_tool_iterations] || Callback::MAX_TOOL_ITERATIONS).to_i
+      )
+    end
+
+    # Replace secret reference header values with placeholders so a preview
+    # never resolves or exposes secret values.
+    def redact_secret_headers(headers)
+      headers.transform_values do |value|
+        value.is_a?(PatientHttp::SecretReference) ? "<secret:#{value.name}>" : value
+      end
+    end
+
     # Serialize the session for the callback args, offloading it to a payload
     # store when session offloading is configured and the serialized session
     # exceeds the threshold. Offloaded payloads are not deleted after use so

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patient_llm
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Brian Durand
@@ -57,6 +57,7 @@ files:
 - lib/patient_llm/halt_error.rb
 - lib/patient_llm/max_tool_iterations_error.rb
 - lib/patient_llm/presets.rb
+- lib/patient_llm/request_preview.rb
 - lib/patient_llm/schema.rb
 - lib/patient_llm/structured_output_error.rb
 - patient_llm.gemspec