savvy_openrouter 0.2.0 → 0.4.2

data/lib/savvy_openrouter/connection_api_call_recording.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  class Connection
+    # JSON Faraday exchanges + timing helpers for {api_call_log}.
+    module ApiCallRecording
+      private
+
+      def record_faraday_json(method:, rel_path:, params:, request_body:, response:, duration_ms:)
+        return if suppress_api_call_log?
+        return unless @api_call_logger.enabled?
+
+        attrs = merge_call_log_context(
+          faraday_json_attrs(method: method, rel_path: rel_path, params: params, request_body: request_body,
+                             response: response, duration_ms: duration_ms)
+        )
+
+        if defer_chat_completions_log?(method: method, rel_path: rel_path)
+          @pending_deferred_chat_log = attrs
+          return
+        end
+
+        if defer_responses_log?(method: method, rel_path: rel_path)
+          @pending_deferred_responses_log = attrs
+          return
+        end
+
+        @api_call_logger.record(attrs)
+      end
+
+      def faraday_json_attrs(method:, rel_path:, params:, request_body:, response:, duration_ms:)
+        lim = @api_call_logger.max_body_limit
+        body = response.body
+        usage = usage_hash_from_body(body)
+        status = response.status
+        success = status.is_a?(Integer) && (200..299).include?(status)
+        gid = ApiCallLogger.generation_id_from(response: response, parsed_body: body)
+        cost = usage ? ApiCallLogger.cost_from_usage(usage) : nil
+        lm = extract_logical_model_from_request(request_body)
+        error_message =
+          if success
+            nil
+          else
+            ApiCallLogger.error_message_from_response_body(body)
+          end
+
+        {
+          "method" => method,
+          "path" => full_url(rel_path, params),
+          "status" => status,
+          "http_status" => status,
+          "duration_ms" => duration_ms.round(3),
+          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
+          "response_body" => ApiCallLogger.format_body_for_log(body, max_bytes: lim),
+          "request_json" => request_body,
+          "response_json" => body,
+          "error_class" => nil,
+          "error_message" => error_message,
+          "streaming" => false,
+          "success" => success,
+          "generation_id" => gid,
+          "usage" => usage,
+          "cost" => cost,
+          "logical_model" => lm
+        }
+      end
+
+      def usage_hash_from_body(body)
+        return unless body.is_a?(Hash)
+
+        u = body[:usage] || body["usage"]
+        u.is_a?(Hash) ? u : nil
+      end
+
+      def extract_logical_model_from_request(request_body)
+        case request_body
+        when Hash
+          m = request_body[:model] || request_body["model"]
+          s = m.to_s.strip
+          s.empty? ? nil : s
+        end
+      end
+
+      def full_url(rel_path, params)
+        u = join_uri(rel_path)
+        if params && !params.empty?
+          flat = params.transform_keys(&:to_s)
+          u.query = URI.encode_www_form(flat)
+        end
+        u.to_s
+      end
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
+      end
+
+      def elapsed_ms(started)
+        monotonic_ms - started
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/connection_api_call_recording_transport.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  class Connection
+    # Raw, streaming, and transport-error rows for {api_call_log}.
+    module ApiCallRecordingTransport
+      private
+
+      def record_faraday_raw(method:, rel_path:, params:, request_body:, response:, duration_ms:)
+        return if suppress_api_call_log?
+        return unless @api_call_logger.enabled?
+
+        lim = @api_call_logger.max_body_limit
+        status = response.status
+        success = status.is_a?(Integer) && (200..299).include?(status)
+        body_for_resp =
+          if response.body.is_a?(String) && response.body.encoding == Encoding::ASCII_8BIT
+            "[binary #{response.body.bytesize} bytes]"
+          else
+            response.body
+          end
+        error_message = error_message_for_raw_response(success, body_for_resp)
+        attrs = merge_call_log_context(
+          {
+            "method" => method,
+            "path" => full_url(rel_path, params),
+            "status" => status,
+            "http_status" => status,
+            "duration_ms" => duration_ms.round(3),
+            "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
+            "response_body" => ApiCallLogger.format_body_for_log(body_for_resp, max_bytes: lim),
+            "request_json" => request_body,
+            "response_json" => (body_for_resp.is_a?(Hash) ? body_for_resp : nil),
+            "error_class" => nil,
+            "error_message" => error_message,
+            "streaming" => false,
+            "success" => success
+          }
+        )
+        @api_call_logger.record(attrs)
+      end
+
+      def record_stream(method:, rel_path:, params:, request_body:, status:, response_body:, duration_ms:)
+        return if suppress_api_call_log?
+        return unless @api_call_logger.enabled?
+
+        lim = @api_call_logger.max_body_limit
+        preview =
+          if status == 200
+            "[stream completed]"
+          else
+            response_body
+          end
+        ok = status.is_a?(Integer) && (200..299).include?(status)
+        error_message = error_message_for_raw_response(ok, preview)
+        attrs = merge_call_log_context(
+          {
+            "method" => method,
+            "path" => full_url(rel_path, params),
+            "status" => status,
+            "http_status" => status,
+            "duration_ms" => duration_ms.round(3),
+            "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
+            "response_body" => ApiCallLogger.format_body_for_log(preview, max_bytes: lim),
+            "error_class" => nil,
+            "error_message" => error_message,
+            "streaming" => true,
+            "success" => ok
+          }
+        )
+        @api_call_logger.record(attrs)
+      end
+
+      def record_transport_error(method:, rel_path:, params:, request_body:, duration_ms:, error:)
+        return if suppress_api_call_log?
+        return unless @api_call_logger.enabled?
+
+        lim = @api_call_logger.max_body_limit
+        msg = ApiCallLogger.format_body_for_log(error.message, max_bytes: lim)
+
+        attrs = merge_call_log_context(
+          {
+            "method" => method,
+            "path" => full_url(rel_path, params),
+            "status" => nil,
+            "http_status" => nil,
+            "duration_ms" => duration_ms.round(3),
+            "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
+            "response_body" => "",
+            "error_class" => error.class.name,
+            "error_message" => msg,
+            "streaming" => false,
+            "success" => false
+          }
+        )
+        @api_call_logger.record(attrs)
+      end
+
+      def error_message_for_raw_response(success, payload)
+        return if success
+
+        case payload
+        when Hash
+          ApiCallLogger.error_message_from_response_body(payload)
+        when String
+          ApiCallLogger.error_message_from_json_string(payload)
+        end
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/connection_instrumentation.rb

@@ -2,7 +2,7 @@
 
 module SavvyOpenrouter
   class Connection
-    # Timing + persistence hooks for optional request logging ({api_call_log} config).
+    # Timing + orchestration hooks for optional request logging ({api_call_log} config).
     module Instrumentation
       private
 
@@ -19,8 +19,14 @@ module SavvyOpenrouter
           else raise ArgumentError, "unsupported #{method_sym}"
           end
         duration_ms = elapsed_ms(started)
-        record_faraday_json(method: method_sym.to_s.upcase, rel_path: rel, params: params, request_body: body, response: response,
-                            duration_ms: duration_ms)
+        record_faraday_json(
+          method: method_sym.to_s.upcase,
+          rel_path: rel,
+          params: params,
+          request_body: body,
+          response: response,
+          duration_ms: duration_ms
+        )
         parse_json_response(response, success: success)
       rescue SavvyOpenrouter::ApiError
         raise
@@ -30,103 +36,32 @@ module SavvyOpenrouter
         raise
       end
 
-      def record_faraday_json(method:, rel_path:, params:, request_body:, response:, duration_ms:)
-        return unless @api_call_logger.enabled?
-
-        lim = @api_call_logger.max_body_limit
-        @api_call_logger.record(
-          "method" => method,
-          "path" => full_url(rel_path, params),
-          "status" => response.status,
-          "duration_ms" => duration_ms.round(3),
-          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
-          "response_body" => ApiCallLogger.format_body_for_log(response.body, max_bytes: lim),
-          "error_class" => nil,
-          "error_message" => nil,
-          "streaming" => false
-        )
-      end
-
-      def record_faraday_raw(method:, rel_path:, params:, request_body:, response:, duration_ms:)
-        return unless @api_call_logger.enabled?
-
-        lim = @api_call_logger.max_body_limit
-        body_for_resp =
-          if response.body.is_a?(String) && response.body.encoding == Encoding::ASCII_8BIT
-            "[binary #{response.body.bytesize} bytes]"
-          else
-            response.body
-          end
-        @api_call_logger.record(
-          "method" => method,
-          "path" => full_url(rel_path, params),
-          "status" => response.status,
-          "duration_ms" => duration_ms.round(3),
-          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
-          "response_body" => ApiCallLogger.format_body_for_log(body_for_resp, max_bytes: lim),
-          "error_class" => nil,
-          "error_message" => nil,
-          "streaming" => false
-        )
-      end
-
-      def record_stream(method:, rel_path:, params:, request_body:, status:, response_body:, duration_ms:)
-        return unless @api_call_logger.enabled?
+      def defer_chat_completions_log?(method:, rel_path:)
+        return false unless @api_call_logger.enabled?
+        return false unless @api_call_logger.chat_attempts_final?
+        return false unless method.to_s.upcase == "POST"
+        return false unless rel_path.to_s.include?("chat/completions")
 
-        lim = @api_call_logger.max_body_limit
-        preview =
-          if status == 200
-            "[stream completed]"
-          else
-            response_body
-          end
-        @api_call_logger.record(
-          "method" => method,
-          "path" => full_url(rel_path, params),
-          "status" => status,
-          "duration_ms" => duration_ms.round(3),
-          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
-          "response_body" => ApiCallLogger.format_body_for_log(preview, max_bytes: lim),
-          "error_class" => nil,
-          "error_message" => nil,
-          "streaming" => true
-        )
+        true
       end
 
-      def record_transport_error(method:, rel_path:, params:, request_body:, duration_ms:, error:)
-        return unless @api_call_logger.enabled?
-
-        lim = @api_call_logger.max_body_limit
-        msg = ApiCallLogger.format_body_for_log(error.message, max_bytes: lim)
-
-        @api_call_logger.record(
-          "method" => method,
-          "path" => full_url(rel_path, params),
-          "status" => nil,
-          "duration_ms" => duration_ms.round(3),
-          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
-          "response_body" => "",
-          "error_class" => error.class.name,
-          "error_message" => msg,
-          "streaming" => false
-        )
-      end
+      def defer_responses_log?(method:, rel_path:)
+        return false unless @api_call_logger.enabled?
+        return false unless @api_call_logger.responses_attempts_final?
+        return false unless method.to_s.upcase == "POST"
 
-      def full_url(rel_path, params)
-        u = join_uri(rel_path)
-        if params && !params.empty?
-          flat = params.transform_keys(&:to_s)
-          u.query = URI.encode_www_form(flat)
-        end
-        u.to_s
+        rel = rel_path.to_s
+        rel == "responses" || rel.end_with?("/responses")
       end
 
-      def monotonic_ms
-        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
+      def merge_call_log_context(base)
+        ctx = Configuration.stringify_keys_static(@call_context_stack.last || {})
+        Configuration.stringify_keys_static(base).merge(ctx)
       end
 
-      def elapsed_ms(started)
-        monotonic_ms - started
+      def suppress_api_call_log?
+        ctx = @call_context_stack.last || {}
+        ctx["suppress_api_call_log"] == true || ctx[:suppress_api_call_log] == true
       end
     end
   end

data/lib/savvy_openrouter/patterns/structured_output.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../structured_output_error"
+
+module SavvyOpenrouter
+  # Post-success validators for structured JSON (chat + Responses). Pure Ruby; use via +require "savvy_openrouter/patterns"+.
+  # rubocop:disable Metrics/ModuleLength -- single cohesive module for optional require path
+  module Patterns
+    module_function
+
+    def validate_after_success!(endpoint:, request:, response:)
+      return unless response.is_a?(Hash)
+
+      json = deep_stringify_keys(response)
+
+      case endpoint.to_s
+      when "chat_completions"
+        validate_chat!(request, json)
+      when "responses"
+        validate_responses!(request, json)
+      end
+    end
+
+    def validate_chat!(request_hash, json)
+      return unless chat_structured_requested?(request_hash)
+
+      choices = json["choices"]
+      unless choices.is_a?(Array) && !choices.empty?
+        raise StructuredOutputError.new("No choices in chat completion", reason: :no_choices, response_body: json)
+      end
+
+      choice = choices.first
+      msg = choice["message"]
+      unless msg.is_a?(Hash)
+        raise StructuredOutputError.new("Missing assistant message", reason: :no_choices, response_body: json)
+      end
+
+      return if tool_calls_present?(msg)
+
+      text = extract_chat_assistant_text(msg)
+      if text.strip.empty?
+        raise StructuredOutputError.new(
+          "Structured output was requested but assistant message content is empty",
+          reason: :empty_content,
+          response_body: json
+        )
+      end
+
+      assert_parseable_json!(text, json)
+    end
+
+    def validate_responses!(request_hash, json)
+      return unless responses_structured_requested?(request_hash)
+
+      text = extract_responses_output_text(json)
+      if text.strip.empty?
+        raise StructuredOutputError.new(
+          "Structured output was requested but Responses API returned no parseable text output",
+          reason: :empty_content,
+          response_body: json
+        )
+      end
+
+      assert_parseable_json!(text, json)
+    end
+
+    def chat_structured_requested?(body)
+      return false unless body.is_a?(Hash)
+
+      rf = body[:response_format] || body["response_format"]
+      return false unless rf.is_a?(Hash)
+
+      t = (rf[:type] || rf["type"]).to_s
+      %w[json_schema json_object].include?(t)
+    end
+
+    def responses_structured_requested?(body)
+      return false unless body.is_a?(Hash)
+
+      text = body[:text] || body["text"]
+      return false unless text.is_a?(Hash)
+
+      fmt = text[:format] || text["format"]
+      return false unless fmt.is_a?(Hash)
+
+      t = (fmt[:type] || fmt["type"]).to_s
+      %w[json_schema json_object].include?(t)
+    end
+
+    def extract_chat_assistant_text(msg)
+      msg = deep_stringify_keys(msg) if msg.is_a?(Hash)
+      c = msg["content"]
+      case c
+      when String
+        c
+      when Array
+        c.filter_map do |p|
+          next unless p.is_a?(Hash)
+
+          txt = p["text"]
+          p["type"].to_s == "text" && txt.is_a?(String) && !txt.strip.empty? ? txt : nil
+        end.join
+      else
+        ""
+      end
+    end
+
+    def extract_responses_output_text(payload)
+      payload = deep_stringify_keys(payload) if payload.is_a?(Hash)
+      return "" unless payload.is_a?(Hash)
+
+      ot = payload["output_text"]
+      return ot.to_s if ot.is_a?(String) && !ot.strip.empty?
+
+      outputs = payload["output"]
+      return "" unless outputs.is_a?(Array)
+
+      texts = []
+      outputs.each do |item|
+        next unless item.is_a?(Hash)
+
+        content = item["content"]
+        next unless content.is_a?(Array)
+
+        content.each do |part|
+          next unless part.is_a?(Hash)
+          next unless part["type"].to_s == "output_text"
+
+          texts << part["text"].to_s
+        end
+      end
+      texts.join
+    end
+
+    def assert_parseable_json!(text, response_json)
+      stripped = text.strip
+      begin
+        JSON.parse(stripped)
+      rescue JSON::ParserError => e
+        fenced = stripped[/```(?:json)?\s*([\s\S]*?)```/mi, 1]
+        if fenced && !fenced.strip.empty?
+          begin
+            return JSON.parse(fenced.strip)
+          rescue JSON::ParserError => e2
+            err = StructuredOutputError.new(
+              "Structured output was requested but message content is not valid JSON (#{e2.message})",
+              reason: :invalid_json,
+              response_body: response_json
+            )
+            raise err, cause: e2
+          end
+        end
+
+        err = StructuredOutputError.new(
+          "Structured output was requested but message content is not valid JSON (#{e.message})",
+          reason: :invalid_json,
+          response_body: response_json
+        )
+        raise err, cause: e
+      end
+    end
+
+    def deep_stringify_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), h|
+          h[k.to_s] = deep_stringify_keys(v)
+        end
+      when Array
+        obj.map { |v| deep_stringify_keys(v) }
+      else
+        obj
+      end
+    end
+
+    def tool_calls_present?(msg)
+      tc = msg["tool_calls"]
+      tc.is_a?(Array) && !tc.empty?
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/savvy_openrouter/patterns.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Opt-in helpers for structured JSON validation after successful HTTP responses.
+#
+#   require "savvy_openrouter/patterns"
+#   SavvyOpenrouter::Patterns.validate_after_success!(endpoint: "chat_completions", request: body, response: json)
+#
+# Raises {SavvyOpenrouter::StructuredOutputError} (+reason+, +response_body+).
+require_relative "patterns/structured_output"