patient_llm 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7873a0b7daf57787415d4484495a17f130cbf3a14137613799651aa0007f2d63
-  data.tar.gz: 728755787c1a52c805ebd70eaf163fae702d55b9525325b101b9dae571ad1652
+  metadata.gz: c5a3fc235def2976b4a57107239ab72e51a50a2b3abdfed579c0c0d4ea6f681d
+  data.tar.gz: 77b63683fc706598ab29e2fa710d9d6650c568712301e1ff4d87bd8a50668228
 SHA512:
-  metadata.gz: c101043564f214413f1a50b3536d56eff6f611e227013cc26507fd7b8465f1554bb6922de98f736f0712bda809afa2654bf1c366740c8b5ca3e673074e5738d7
-  data.tar.gz: 80d9a476d5fbe99a96946558a1d847c7faad08250584f9d0b5b452d6faeb906066d64b9c5e822139aed84f22d41c0059e035d59cefc9dc75979b8c4bffb7fd20
+  metadata.gz: e43ffc0679e0ab348e8462884042ba538d734101acfb5b7ecb5e4058167dc3fdd7aa50ad953a091695faae5ad1ce4c25ff1b13614c2ac553587b3568115e8f9a
+  data.tar.gz: 034554bf031c5696ddb2bf877463f9cbcf5e57e32cdc39563975de22f0ea6cde189be72cfe053ea1338144b320254196ed51589ded11ba753161e4af544de3e4

data/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.3.0
+
+### Changed
+
+- Renamed the `completion_path` argument to `path` on both `PatientLLM.ask` and provider configuration. The `completion_path` name is still accepted as a deprecated alias and now emits a deprecation warning.
+- The path is now joined with the base URL using `URI.join` to ensure proper handling of relative paths in the `path` argument. If the path starts with a slash, it will be treated as an absolute path and will replace the base URL's path. If it does not start with a slash, it will be treated as a relative path and will be appended to the base URL's path.
+
+## 0.2.0
+
+### Added
+
+- Requires authentication headers to be set up as secrets using `PatientHttp.secret`. This is enforced and an error will be raised if plain text values are included for any of the following headers in the provider configuration: `authorization`, `x-api-key`, `x-goog-api-key`, `api-key`.
+
+### Changed
+
+- Requires patient_http version 1.1 or higher.
+
 ## 0.1.0
 
 ### Added

data/README.md

@@ -27,25 +27,30 @@ Without a handler, `PatientLLM.ask` raises `RuntimeError: No request handler reg
 
 ### Configuration
 
-Register your LLM providers with their API base URLs and authentication headers:
+Register your LLM providers with their API base URLs and authentication headers. Authentication headers must be registered using the PatientHttp secrets manager. This ensures that these values are never included in the serialized payloads in the job queue, and are only attached to the request at dispatch time.
 
 ```ruby
 PatientLLM.configure do |config|
   config.provider :openai,
     url: "https://api.openai.com",
-    headers: {"Authorization" => "Bearer #{ENV["OPENAI_API_KEY"]}"}
+    headers: {"authorization" => PatientHttp.secret("openai.bearer_token")}
 
   config.provider :anthropic,
     url: "https://api.anthropic.com",
-    headers: {"x-api-key" => ENV["ANTHROPIC_API_KEY"]},
+    headers: {"x-api-key" => PatientHttp.secret("anthropic.api_key")},
     serializer: :messages
 end
+
+# Register the API keys as secrets with the PatientHttp secrets manager. This example
+# is for the Sidekiq integration, but the pattern is the same for SolidQueue.
+PatientHttp::Sidekiq.configure do |config|
+  config.register_secret("openai.bearer_token") { "Bearer #{ENV.fetch("OPENAI_API_KEY")}" }
+  config.register_secret("anthropic.api_key") { ENV.fetch("ANTHROPIC_API_KEY") }
+end
 ```
 
 > [!NOTE]
-> Authentication headers configured on the provider are re-attached to every request at dispatch time and are persisted in the asynchronous job payload.
->
-> You should set up encryption for you job payloads to prevent leaking credentials. See the documentation for [patient_http-sidekiq](https://github.com/bdurand/patient_http-sidekiq#sensitive-data-handling) or [patient_http-solid_queue](https://github.com/bdurand/patient_http-solid_queue#sensitive-data-handling) for details.
+> You can also set up encryption for your job payloads to ensure the entire serialized payload is always encrypted in the job queue. See the documentation for [patient_http-sidekiq](https://github.com/bdurand/patient_http-sidekiq#sensitive-data-handling) or [patient_http-solid_queue](https://github.com/bdurand/patient_http-solid_queue#sensitive-data-handling) for details.
 
 ### Creating a Callback Class
 
@@ -180,9 +185,9 @@ session.max_output_tokens = 1000
 PatientLLM.ask(session,
   provider: :openai,
   callback: LLMCallback,
-  url: "http://localhost:1234",           # Override the provider's base URL
+  url: "http://localhost:1234",            # Override the provider's base URL
   serializer: :messages,                   # Override the API format
-  completion_path: "/chat/completions",    # Override the endpoint path
+  path: "/chat/completions",               # Override the endpoint path
   headers: {"X-Custom" => "value"},        # Additional HTTP headers
   params: {max_completion_tokens: 1000}    # Additional request parameters
 )
@@ -190,24 +195,24 @@ PatientLLM.ask(session,
 
 ### URL composition
 
-The full request URL is built by concatenating the base URL (from the provider registry or the `url:` option) with the `completion_path`. When you don't set `completion_path`, it defaults to the path for the active serializer (`/v1/chat/completions` for `:chat_completion`, `/v1/responses` for `:open_responses`, `/v1/messages` for `:messages`, `/converse` for `:converse`, `/v1beta/models/{model}:generateContent` for `:gemini`). A `{model}` placeholder in the path is replaced with the session's model at dispatch time, which is how the Gemini default targets Google's `/v1beta/models/{model}:generateContent` endpoint. Trailing slashes on the base and leading slashes on the path are normalized, so:
+The full request URL is built by concatenating the base URL (from the provider registry or the `url:` option) with the `path`. When you don't set `path`, it defaults to the path for the active serializer (`/v1/chat/completions` for `:chat_completion`, `/v1/responses` for `:open_responses`, `/v1/messages` for `:messages`, `/converse` for `:converse`, `/v1beta/models/{model}:generateContent` for `:gemini`). A `{model}` placeholder in the path is replaced with the session's model at dispatch time, which is how the Gemini default targets Google's `/v1beta/models/{model}:generateContent` endpoint. Trailing slashes on the base and leading slashes on the path are normalized, so:
 
 ```
-url = "https://api.openai.com"            completion_path = "/v1/chat/completions"
+url = "https://api.openai.com"            path = "/v1/chat/completions"
 -> https://api.openai.com/v1/chat/completions
 
-url = "http://localhost:1234"             completion_path = "/v1/chat/completions"
+url = "http://localhost:1234"             path = "/v1/chat/completions"
 -> http://localhost:1234/v1/chat/completions
 ```
 
-If your base URL already includes a `/v1` prefix, override the completion path to avoid duplication:
+If your base URL already includes a `/v1` prefix, override the path to avoid duplication:
 
 ```ruby
 PatientLLM.ask(session,
   provider: :openai,
   callback: LLMCallback,
   url: "https://my-gateway.internal/openai/v1",
-  completion_path: "/chat/completions"
+  path: "chat/completions"
 )
 ```
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.3.0

data/lib/patient_llm/callback.rb

@@ -213,7 +213,7 @@ module PatientLLM
       # Restore per-request overrides
       ask_kwargs[:url] = request_options["url"] if request_options["url"]
       ask_kwargs[:serializer] = request_options["serializer"].to_sym if request_options["serializer"]
-      ask_kwargs[:completion_path] = request_options["completion_path"] if request_options["completion_path"]
+      ask_kwargs[:path] = request_options["path"] if request_options["path"]
       ask_kwargs[:headers] = request_options["headers"] if request_options["headers"]
       ask_kwargs[:params] = request_options["params"] if request_options["params"]
 

data/lib/patient_llm/configuration.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module PatientLLM
+  # Headers that must be setup to use the secrets manager. If any of these headers
+  # are included in the provider configuration, an error will be raised unless their
+  # values are set up as secrets using `PatientHttp.secret`.
+  AUTHENTICATION_HEADERS = ["authorization", "x-api-key", "x-goog-api-key", "api-key"].freeze
+
   # Configuration for provider registry.
   #
   # @example
@@ -21,20 +26,28 @@ module PatientLLM
     # @param url [String] Base URL for the provider API
     # @param headers [Hash] Default headers for requests
     # @param serializer [Symbol] API format (:chat_completion, :open_responses, :messages, :converse, :gemini)
-    # @param completion_path [String, nil] Override the default endpoint path
+    # @param path [String, nil] Override the default endpoint path
+    # @param completion_path [String, nil] Deprecated alias for +path+
     # @param params [Hash] Additional parameters to merge into every request payload
     # @return [void]
-    def provider(name, url:, headers: {}, serializer: :chat_completion, completion_path: nil, params: {})
+    def provider(name, url:, headers: {}, serializer: :chat_completion, path: nil, completion_path: nil, params: {})
+      if completion_path
+        warn "PatientLLM::Configuration#provider: the `completion_path:` argument is deprecated; use `path:` instead", uplevel: 1
+        path ||= completion_path
+      end
+
       sym = serializer.to_sym
       unless PatientLLM::VALID_SERIALIZERS.include?(sym)
         raise ArgumentError, "Unknown serializer: #{sym.inspect}. Valid options: #{PatientLLM::VALID_SERIALIZERS.map(&:inspect).join(", ")}"
       end
 
+      ensure_auth_headers_use_secrets!(headers)
+
       @providers[name.to_s] = {
         url: url,
         headers: headers,
         serializer: sym,
-        completion_path: completion_path,
+        path: path,
         params: params
       }
     end
@@ -46,5 +59,18 @@ module PatientLLM
     def lookup(name)
       @providers[name&.to_s]
     end
+
+    private
+
+    def ensure_auth_headers_use_secrets!(headers)
+      headers.each do |header_name, header_value|
+        normalized_header_name = header_name.to_s.downcase
+        next unless AUTHENTICATION_HEADERS.include?(normalized_header_name)
+
+        if header_value && !header_value.is_a?(PatientHttp::SecretReference)
+          raise ArgumentError, "Authentication header #{header_name} must be set up as a secret using `PatientHttp.secret`"
+        end
+      end
+    end
   end
 end

data/lib/patient_llm.rb

@@ -2,6 +2,7 @@
 
 require "patient_http"
 require "prompt_builder"
+require "uri"
 
 module PatientLLM
   VERSION = File.read(File.join(__dir__, "../VERSION")).strip
@@ -16,11 +17,11 @@ module PatientLLM
   # dispatch time, matching Google's `/v1beta/models/{model}:generateContent`
   # endpoint.
   SERIALIZER_PATHS = {
-    chat_completion: "/v1/chat/completions",
-    open_responses: "/v1/responses",
-    messages: "/v1/messages",
-    converse: "/converse",
-    gemini: "/v1beta/models/{model}:generateContent"
+    chat_completion: "v1/chat/completions",
+    open_responses: "v1/responses",
+    messages: "v1/messages",
+    converse: "converse",
+    gemini: "v1beta/models/{model}:generateContent"
   }.freeze
 
   # Required version header for the Anthropic Messages API.
@@ -62,11 +63,17 @@ module PatientLLM
     # @param callback_args [Hash] Custom arguments passed through to the callback
     # @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 completion_path [String, nil] Override the endpoint path for this request
+    # @param path [String, nil] Override the endpoint path for this request
+    # @param completion_path [String, nil] Deprecated alias for +path+
     # @param headers [Hash, nil] Additional headers merged on top of provider headers
     # @param params [Hash, nil] Additional params merged into the request payload
     # @return [Object] Handler-specific identifier for the enqueued request
-    def ask(session, provider:, callback:, callback_args: {}, url: nil, serializer: nil, completion_path: nil, headers: nil, params: nil, tool_iteration: 0, original_request_id: nil) # :nodoc: tool_iteration and original_request_id are internal
+    def ask(session, provider:, callback:, callback_args: {}, url: nil, serializer: nil, path: nil, completion_path: nil, headers: nil, params: nil, tool_iteration: 0, original_request_id: nil) # :nodoc: tool_iteration and original_request_id are internal
+      if completion_path
+        warn "PatientLLM.ask: the `completion_path:` argument is deprecated; use `path:` instead", uplevel: 1
+        path ||= completion_path
+      end
+
       provider_config = self.provider(provider) || {}
       provider_name = provider.to_s
 
@@ -79,9 +86,9 @@ module PatientLLM
 
       resolved_serializer = (serializer || provider_config[:serializer] || :chat_completion).to_sym
       validate_serializer!(resolved_serializer)
-      resolved_completion_path = completion_path || provider_config[:completion_path] || SERIALIZER_PATHS[resolved_serializer] || "/v1/chat/completions"
-      if resolved_completion_path.include?("{model}")
-        resolved_completion_path = resolved_completion_path.gsub("{model}", session.model.to_s)
+      resolved_path = path || provider_config[:path] || SERIALIZER_PATHS[resolved_serializer] || "/v1/chat/completions"
+      if resolved_path.include?("{model}")
+        resolved_path = resolved_path.gsub("{model}", session.model.to_s)
       end
       resolved_headers = (provider_config[:headers] || {}).merge(headers || {})
       if resolved_serializer == :messages && !resolved_headers.key?("anthropic-version")
@@ -92,12 +99,12 @@ module PatientLLM
       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_completion_path)
+      request_url = join_url(resolved_url, resolved_path)
 
       request_options = {}
       request_options["url"] = url if url
       request_options["serializer"] = serializer.to_s if serializer
-      request_options["completion_path"] = completion_path if completion_path
+      request_options["path"] = path if path
       request_options["headers"] = headers if headers && !headers.empty?
       request_options["params"] = params if params && !params.empty?
 
@@ -128,7 +135,9 @@ module PatientLLM
     end
 
     def join_url(base, path)
-      "#{base.sub(%r{/\z}, "")}/#{path.to_s.sub(%r{\A/}, "")}"
+      base_uri = URI.parse(base)
+      base_uri.path = "#{base_uri.path}/" unless base_uri.path&.end_with?("/")
+      URI.join(base_uri, path).to_s
     end
 
     def deep_merge(hash1, hash2)

data/patient_llm.gemspec

@@ -37,7 +37,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 3.0"
 
-  spec.add_dependency "patient_http"
+  spec.add_dependency "patient_http", "~> 1.1"
   spec.add_dependency "prompt_builder"
 
   spec.add_development_dependency "bundler"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patient_llm
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Brian Durand
@@ -13,16 +13,16 @@ dependencies:
   name: patient_http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: prompt_builder
   requirement: !ruby/object:Gem::Requirement