savvy_openrouter 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5429c1ab8b5a4a777f1e95511f1ff54a6b4c409026637a1732f090bf919fc1fc
-  data.tar.gz: 40731fb4249d671e8ad33aaeab2de19708972cf75abc2a5d3d91e702d9e7dde4
+  metadata.gz: 0b72086a1800026ac12dae2c055b06051b61dec6ea35704d9ebe3a96aac9dee5
+  data.tar.gz: f2d1a708927e1b8fbaf57c10c648a4928cf19714bbae20ee0b4865b918c852b2
 SHA512:
-  metadata.gz: 73104149df96fcbbc61b33719d924865335c98f355ac37f5701b0083005e8dca9f7fc38d7740722d70524a207a485474cfe7a7e03383cde1bf2818dbe91a8eb6
-  data.tar.gz: 1d3f8011538f69c2e5e47aae61b7adbb28d262ab3e13c369214d7c6f442d347da1ce8ae36e05bdc36067624b732dc6b8d63d22c38df4e8d43de5d7334ae2854b
+  metadata.gz: e6cae64c814dd9a1a8162638f28740c05f617085081c32982fce542a1eff413a2010d00977d7a4433886ac2a3d022bc8edeab48693132e53be5ae95b071b03fe
+  data.tar.gz: b50221b09dfce3abbf179bd76d6d8ac951e1382d3bf899cd43008f7cd1f6f2e0d8aa9cc6c08b8deba11e721bb929db33ddabc4cb76c151a1c88c6f87ca9629a0

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 ## [Unreleased]
 
+## [0.4.1] - 2026-05-15
+
+### Added
+
+- **`file_parser_pdf_engine`** in YAML / `Configuration` (or **`OPENROUTER_FILE_PARSER_PDF_ENGINE`**): choose OpenRouter **`file-parser`** PDF engine (`native`, `cloudflare-ai`, `mistral-ocr`, …). **`RequestPlugins.prepare_chat_body!(body, pdf_engine: …)`** applies it when injecting or completing the **`file-parser`** plugin.
+- **`api_call_log`:** failed JSON HTTP responses populate **`error_message`** from the API **`error.message`** when the column is mapped (`response_json` still holds the full body).
+
+### Documentation
+
+- README: PDF engine configuration.
+
+## [0.4.0] - 2026-05-15
+
+### Added
+
+- **`require "savvy_openrouter/patterns"`:** Pure-Ruby structured JSON validation after HTTP 200 for chat (`json_object` / `json_schema`) and Responses (`text.format`). Raises **`SavvyOpenrouter::StructuredOutputError`** (`reason`, `response_body`).
+- **`require "savvy_openrouter/request_plugins"`:** **`prepare_chat_body!`** / **`prepare_responses_body!`** inject OpenRouter **response-healing** and **file-parser** (Cloudflare PDF) for chat when applicable.
+- **`responses_retries`** in YAML or on **`Client`:** same shape as **`chat_retries`** for **`POST /responses`** — zero **`usage.output_tokens`**, selected **`status`** values, and optional HTTP error retries; **`Resources::Responses#create`** runs the retry loop with backoff.
+- **`api_call_log.responses_attempts`:** **`final`** defers Responses logging to the last HTTP attempt (like **`chat_attempts`**); **`all`** logs every attempt (default). **`Connection#flush_deferred_responses_log!`** flushes after the loop.
+
+### Documentation
+
+- README: patterns, request plugins, `responses_retries`, `responses_attempts`.
+
+## [0.3.0] - 2026-05-15
+
+### Changed
+
+- **`api_call_log`:** Column map keys are a **whitelist**: every `source => db_column` entry is copied from the logged attrs when `source` is present, so apps can map **passthrough** context (for example `bill_forward_event_id`) without gem changes.
+- **`api_call_log` / connection:** Additional canonical attrs populated on JSON requests when mapped: **`http_status`**, **`success`**, **`generation_id`** (from `x-generation-id` or JSON `id`), **`usage`**, **`cost`** (derived from usage when possible), **`logical_model`**, **`endpoint` / resource context**, structured **`request_json`** / **`response_json`** (JSON columns should receive serialized objects; coercion formats these for storage).
+- **`chat_attempts`:** `final` defers chat completion logging until the **last** HTTP attempt of a retry loop (one row per logical call); `all` logs **each** attempt (default). Set under `api_call_log` in YAML or client options.
+- **`Connection#with_call_context`:** Merges a shallow hash into the active logging context for nested calls (e.g. billing ids); **`suppress_api_call_log: true`** skips persistence for that scope.
+- **`Connection#record_manual_api_call` / `Client#record_api_call`:** Persist a row after HTTP success for **logical** failures (invalid structured JSON, validation), merged with the current call context.
+
+### Documentation
+
+- README and install template: expanded `api_call_log` examples and new options.
+
 ## [0.2.0] - 2026-05-09
 
 ### Added

data/README.md

@@ -60,26 +60,52 @@ app_title: "Your App"
 
 Optional persistence of **every outbound OpenRouter HTTP request** made through this gem (JSON clients, raw/binary downloads, and streaming chat). Configure **`api_call_log`** in YAML or pass **`api_call_log:`** when building **`SavvyOpenrouter::Client`**.
 
-It depends on **Active Record** (or any Ruby class you configure) exposing **`create!(attributes)`** — the usual Rails pattern. Define a migration for whatever columns you map (strings / integers / booleans / text); avoid indexing huge raw payloads on Postgres without care.
+It depends on **Active Record** (or any Ruby class you configure) exposing **`create!(attributes)`** — the usual Rails pattern. Define a migration for whatever columns you map (strings / integers / booleans / text / jsonb); avoid indexing huge raw payloads on Postgres without care.
+
+Each entry under **`columns`** is **`<source_key>: <your_column>`**. If the logged payload includes **`source_key`**, it is copied into the row (after coercion). Reserved keys (**`model`**, **`columns`**, **`max_body_bytes`**, **`chat_attempts`**, **`responses_attempts`**) are never read from logged attrs. Any other **`source_key`** you whitelist can carry **app-specific** context (for example `bill_forward_event_id`), provided your code merges it via **`connection.with_call_context`**.
 
 ```yaml
-# Optional — persist each outbound HTTP exchange for debugging (Faraday JSON + raw + SSE streams)
 api_call_log:
   model: OpenRouterApiCallLog
   max_body_bytes: 65536
+  # With chat_retries, log only the final HTTP attempt (one row per logical completion).
+  # Use "all" (or omit) to persist every retry attempt.
+  chat_attempts: final
   columns:
-    method: http_method          # GET, POST, …
-    path: request_url            # full URL including query string when present
-    status: response_status      # integer HTTP status (nil on transport failure before response)
-    duration_ms: duration_ms     # float milliseconds
-    request_body: request_body   # JSON-ish text; secrets redacted; truncated to max_body_bytes
-    response_body: response_body # same treatment
-    error_class: error_class     # nil when Faraday returned a response
-    error_message: error_message # transport errors or truncated exception message
-    streaming: streaming         # true for chat SSE streams
+    method: http_method
+    path: request_url
+    status: response_status           # same as http_status when Faraday returned a response
+    http_status: http_status
+    success: success                  # boolean: 2xx HTTP
+    duration_ms: duration_ms
+    request_body: request_body
+    response_body: response_body
+    request_json: request_json        # structured body; coercion JSON-serializes for json/text columns
+    response_json: response_json
+    usage: usage                      # usage hash from JSON responses when present
+    cost: cost                        # BigDecimal parsed from usage when present
+    generation_id: generation_id    # from x-generation-id header or response id
+    logical_model: logical_model    # model string from request body when present
+    endpoint: endpoint              # resource endpoint label when set via call context
+    error_class: error_class
+    error_message: error_message
+    streaming: streaming
+    bill_forward_event_id: bill_forward_event_id   # example passthrough key
 ```
 
-Canonical keys on the **left** (`method`, `path`, …) are fixed by the gem; **right-hand** names are your database columns. Omit mappings you do not need. Set **`api_call_log: false`** (or omit `model` / `columns`) to disable.
+**Call context:** wrap outbound calls to attach keys merged into every log row for that scope:
+
+```ruby
+client.connection.with_call_context(bill_forward_event_id: event.id) do
+  client.chat.completions(...)
+end
+```
+
+Set **`suppress_api_call_log: true`** in the context hash to skip persistence for that block (for example when the app performs its own higher-level logging / retries).
+
+**Logical failures after HTTP 200** (invalid structured JSON, validation): use **`client.record_api_call(attrs)`** (delegates to **`connection.record_manual_api_call`**). Attributes are merged with the current **`with_call_context`** stack.
+
+Canonical source keys the gem may set include: **`method`**, **`path`**, **`status`**, **`http_status`**, **`duration_ms`**, **`request_body`**, **`response_body`**, **`request_json`**, **`response_json`**, **`usage`**, **`cost`**, **`generation_id`**, **`logical_model`**, **`endpoint`**, **`success`**, **`error_class`**, **`error_message`** (for failed JSON HTTP responses, from the API **`error.message`** when present), **`streaming`**, plus any keys you pass through **`with_call_context`**. Omit mappings you do not need. Set **`api_call_log: false`** (or omit **`model`** / **`columns`**) to disable.
 
 Logging failures never raise into your app code. Large bodies are truncated; **`Authorization`** / **`sk-or-v1-*`** patterns in serialized bodies are redacted (still treat logs as sensitive).
 
@@ -107,6 +133,43 @@ chat_retries:
 
 After the last attempt, the gem returns the **final response body** (for 200s) or **re-raises** the last API error. **`completions_stream`** does not use this policy—handle streaming retries in your own code if needed.
 
+### Responses API retries (`responses_retries`)
+
+For **`client.responses.create`** only, configure **`responses_retries`** in YAML or pass **`responses_retries:`** to **`SavvyOpenrouter::Client`**. Same timing options as **`chat_retries`** (`max_attempts`, `base_delay_ms`, …). When **`on.zero_output_tokens`** is true (default), the gem retries on **successful HTTP 200** responses where **`usage.output_tokens`** is zero and **`status`** indicates an incomplete or empty generation (see `ResponsesRetryPolicy`).
+
+With **`api_call_log`**, set **`responses_attempts: final`** to persist **one** row for the last HTTP attempt of a retry loop; **`all`** logs each attempt (default).
+
+### Structured output validation (`savvy_openrouter/patterns`)
+
+Optional pure-Ruby checks that assistant / Responses text is non-empty **parseable JSON** when the request asked for **`json_object`** or **`json_schema`**:
+
+```ruby
+require "savvy_openrouter/patterns"
+
+SavvyOpenrouter::Patterns.validate_after_success!(
+  endpoint: "chat_completions",
+  request: request_body_hash,
+  response: parsed_response_hash
+)
+# raises SavvyOpenrouter::StructuredOutputError (reason: :empty_content, :invalid_json, :no_choices)
+```
+
+Helpers: **`chat_structured_requested?`**, **`responses_structured_requested?`**, **`extract_chat_assistant_text`**, **`extract_responses_output_text`**, **`assert_parseable_json!`**.
+
+### Request plugins (`savvy_openrouter/request_plugins`)
+
+Optional injection of OpenRouter plugins before **`chat.completions`** / **`responses.create`**:
+
+```ruby
+require "savvy_openrouter/request_plugins"
+
+SavvyOpenrouter::RequestPlugins.prepare_chat_body!(body) # PDF engine from config / default cloudflare-ai
+SavvyOpenrouter::RequestPlugins.prepare_chat_body!(body, pdf_engine: "native") # e.g. Gemini native PDF
+SavvyOpenrouter::RequestPlugins.prepare_responses_body!(body) # response-healing for structured Responses
+```
+
+YAML (or `OPENROUTER_FILE_PARSER_PDF_ENGINE`): **`file_parser_pdf_engine`** — `native`, `cloudflare-ai`, `mistral-ocr`, etc. Apps using **`OpenRouterService`** pass this through from the loaded **`SavvyOpenrouter::Client`** config automatically.
+
 ### Install templates
 
 **Rails**

data/lib/generators/savvy_openrouter/install/templates/savvy_openrouter.yml

@@ -1,6 +1,12 @@
 # OpenRouter defaults — loaded automatically when present at config/savvy_openrouter.yml
 # or .savvy_openrouter.yml (see SavvyOpenrouter::Configuration).
 #
+# PDF file-parser engine when messages include PDFs (openrouter file-parser plugin):
+# file_parser_pdf_engine: native          # model-native when supported (e.g. Gemini)
+# file_parser_pdf_engine: cloudflare-ai  # free conversion to markdown (gem default if unset)
+# file_parser_pdf_engine: mistral-ocr    # paid; scans / complex PDFs
+# Or: ENV OPENROUTER_FILE_PARSER_PDF_ENGINE
+#
 # Precedence: keyword arguments to SavvyOpenrouter::Client > this file > ENV variables.
 
 # api_key: "sk-or-v1-..."
@@ -35,17 +41,42 @@
 # api_call_log:
 #   model: OpenRouterApiCallLog
 #   max_body_bytes: 65536
+#   # With chat_retries: "final" logs only the last attempt; "all" logs each HTTP try.
+#   chat_attempts: final
+#   # With responses_retries loops: "final" logs only the last POST /responses attempt.
+#   responses_attempts: final
 #   columns:
 #     method: http_method
 #     path: request_url
 #     status: response_status
+#     http_status: http_status
+#     success: success
 #     duration_ms: duration_ms
 #     request_body: request_body
 #     response_body: response_body
+#     request_json: request_json
+#     response_json: response_json
+#     usage: usage
+#     cost: cost
+#     generation_id: generation_id
+#     logical_model: logical_model
+#     endpoint: endpoint
 #     error_class: error_class
 #     error_message: error_message
 #     streaming: streaming
 #
+# Optional: retry POST /responses on zero output_tokens or transient HTTP errors
+# responses_retries:
+#   max_attempts: 3
+#   base_delay_ms: 400
+#   max_delay_ms: 8000
+#   on:
+#     zero_output_tokens: true
+#     rate_limit: true
+#     bad_gateway: true
+#     internal_server_error: true
+#     service_unavailable: true
+#
 # Optional: retry chat/completions (non-streaming) on empty output, zero completion tokens, or transient HTTP errors
 # chat_retries:
 #   max_attempts: 4

data/lib/savvy_openrouter/api_call_logger.rb

@@ -1,15 +1,30 @@
 # frozen_string_literal: true
 
 require "json"
+require "bigdecimal"
 
 module SavvyOpenrouter
   # Persists OpenRouter HTTP exchanges when configured via +api_call_log+ (YAML or Client kwargs).
   # Failures while saving never raise into application code.
+  #
+  # Column map (+columns+ hash): every +source_key => db_column+ entry is a whitelist. If +attrs+
+  # includes +source_key+, its value is copied to the row (after optional coercion). This allows
+  # app-specific passthrough keys (e.g. +bill_forward_event_id+) without extending the gem enum.
+  #
+  # Documented source keys populated by Connection/resources: +method+, +path+, +status+, +http_status+,
+  # +duration_ms+, +request_body+, +response_body+, +error_class+, +error_message+, +streaming+,
+  # +endpoint+, +logical_model+, +generation_id+, +success+, +cost+, +usage+, +request_json+,
+  # +response_json+.
   class ApiCallLogger
     DEFAULT_MAX_BODY_BYTES = 65_536
 
+    # Reserved keys in api_call_log YAML — never treated as column sources.
+    RESERVED_CONFIG_KEYS = %w[model columns max_body_bytes chat_attempts responses_attempts].freeze
+
+    # Keys the gem may set automatically (subset); full set is any key allowed in +columns+.
     CANONICAL_KEYS = %w[
-      method path status duration_ms request_body response_body error_class error_message streaming
+      method path status http_status duration_ms request_body response_body error_class error_message streaming
+      endpoint logical_model generation_id success cost usage request_json response_json
     ].freeze
 
     class << self
@@ -25,6 +40,60 @@ module SavvyOpenrouter
         truncate_bytes(str, max_bytes)
       end
 
+      def generation_id_from(response:, parsed_body:)
+        h = response.respond_to?(:headers) ? response.headers : nil
+        if h
+          raw = h["x-generation-id"] || h["X-Generation-Id"] || h["X-GENERATION-ID"]
+          gid = blank_to_nil(raw&.to_s)
+          return gid if gid
+        end
+        return unless parsed_body.is_a?(Hash)
+
+        blank_to_nil((parsed_body[:id] || parsed_body["id"]).to_s)
+      end
+
+      def blank_to_nil(raw)
+        t = raw.to_s.strip
+        t.empty? ? nil : t
+      end
+
+      # Best-effort OpenRouter-style error.message for JSON error bodies (symbol or string keys).
+      def error_message_from_response_body(body)
+        return unless body.is_a?(Hash)
+
+        err = body[:error] || body["error"]
+        case err
+        when Hash
+          blank_to_nil((err[:message] || err["message"]).to_s)
+        when String
+          blank_to_nil(err)
+        end
+      end
+
+      def error_message_from_json_string(str)
+        return unless str.is_a?(String)
+
+        stripped = str.strip
+        return unless stripped.start_with?("{", "[")
+
+        parsed = JSON.parse(stripped, symbolize_names: true)
+        error_message_from_response_body(parsed) if parsed.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def cost_from_usage(usage)
+        return unless usage.is_a?(Hash)
+
+        u = usage.transform_keys(&:to_s)
+        v = u["cost"] || u["total_cost"]
+        return if v.nil?
+
+        BigDecimal(v.to_s)
+      rescue ArgumentError
+        nil
+      end
+
       private
 
       def redact_secrets(str)
@@ -56,7 +125,15 @@ module SavvyOpenrouter
       n.is_a?(Integer) && n.positive? ? n : DEFAULT_MAX_BODY_BYTES
     end
 
-    # +attrs+ uses canonical string keys (see CANONICAL_KEYS). Column mapping is applied before create.
+    def chat_attempts_final?
+      @config["chat_attempts"].to_s == "final"
+    end
+
+    def responses_attempts_final?
+      @config["responses_attempts"].to_s == "final"
+    end
+
+    # +attrs+ string-keyed hashes; column mapping selects and renames fields for +create!+.
     def record(attrs)
       return unless enabled?
 
@@ -74,14 +151,50 @@ module SavvyOpenrouter
     def build_row(attrs)
       cols = @config["columns"] || {}
       attrs = Configuration.stringify_keys_static(attrs)
-      cols.each_with_object({}) do |(canonical, column_name), acc|
-        next unless CANONICAL_KEYS.include?(canonical.to_s)
-        next unless attrs.key?(canonical.to_s)
+      lim = max_body_limit
+
+      cols.each_with_object({}) do |(source_key, column_name), acc|
+        sk = source_key.to_s
+        next if RESERVED_CONFIG_KEYS.include?(sk)
+        next unless attrs.key?(sk)
+
+        acc[column_name.to_s] = coerce_value(sk, attrs[sk], lim)
+      end
+    end
 
-        acc[column_name.to_s] = attrs[canonical.to_s]
+    def coerce_value(source_key, val, lim)
+      case source_key
+      when "request_json", "response_json", "usage"
+        val.nil? ? nil : self.class.format_body_for_log(val, max_bytes: lim)
+      when "error_message"
+        val.nil? ? nil : self.class.format_body_for_log(val.to_s, max_bytes: lim)
+      when "success"
+        coerce_success(val)
+      when "cost"
+        coerce_cost(val)
+      when "http_status", "status"
+        val.is_a?(Integer) ? val : Integer(val, exception: false) || val
+      else
+        val
       end
     end
 
+    def coerce_success(val)
+      return nil if val.nil?
+      return val if [true, false].include?(val)
+
+      val ? true : false
+    end
+
+    def coerce_cost(val)
+      return nil if val.nil?
+      return val if val.is_a?(BigDecimal)
+
+      BigDecimal(val.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
     def constantize_model(name)
       raise NameError, "blank model" if name.empty?
       raise NameError, "invalid model name #{name.inspect}" if name.include?("..") || /[^A-Za-z0-9_:]/.match?(name)

data/lib/savvy_openrouter/client.rb

@@ -25,6 +25,16 @@ module SavvyOpenrouter
   class Client
     attr_reader :config, :connection
 
+    # Optional DB-backed request logging; see README (+api_call_log+).
+    def api_call_logger
+      connection.api_call_logger
+    end
+
+    # Merge active +with_call_context+ stack attrs and persist one row (e.g. structured-output failure after HTTP 200).
+    def record_api_call(attrs)
+      connection.record_manual_api_call(attrs)
+    end
+
     def initialize(config_path: nil, **options)
       @config = Configuration.new(config_path: config_path, **options)
       @connection = Connection.new(@config)

data/lib/savvy_openrouter/configuration.rb

@@ -5,7 +5,8 @@ require "yaml"
 module SavvyOpenrouter
   class Configuration
     attr_accessor :api_key, :base_url, :default_model, :http_referer, :app_title
-    attr_reader :defaults, :video_defaults, :responses_defaults, :api_call_log, :chat_retries
+    attr_reader :defaults, :video_defaults, :responses_defaults, :api_call_log, :chat_retries, :responses_retries,
+                :file_parser_pdf_engine
 
     alias llm_model default_model
     alias llm_model= default_model=
@@ -30,6 +31,8 @@ module SavvyOpenrouter
       @responses_defaults = {}
       @api_call_log = {}
       @chat_retries = {}
+      @responses_retries = {}
+      @file_parser_pdf_engine = nil
       load_from_env!
       yaml_path = config_path || self.class.discover_config_file
       merge_hash!(self.class.load_file(yaml_path)) if yaml_path
@@ -44,6 +47,7 @@ module SavvyOpenrouter
       nil
     end
 
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- single YAML merge entry point
     def merge_hash!(hash)
       return unless hash.is_a?(Hash)
 
@@ -61,7 +65,10 @@ module SavvyOpenrouter
       assign_api_call_log(hash["api_call_log"]) if hash.key?("api_call_log")
       assign_chat_retries(hash["chat_retries"]) if hash.key?("chat_retries")
       assign_chat_retries(hash["completion_retries"]) if hash.key?("completion_retries")
+      assign_responses_retries(hash["responses_retries"]) if hash.key?("responses_retries")
+      assign_file_parser_pdf_engine(hash["file_parser_pdf_engine"]) if hash.key?("file_parser_pdf_engine")
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     def merge_chat_body(body)
       body = stringify_keys(body)
@@ -94,6 +101,8 @@ module SavvyOpenrouter
       @default_model = ENV.fetch("OPENROUTER_DEFAULT_MODEL", nil)
       @http_referer = ENV.fetch("OPENROUTER_HTTP_REFERER", nil)
       @app_title = ENV.fetch("OPENROUTER_APP_TITLE", nil)
+      env_pdf = ENV.fetch("OPENROUTER_FILE_PARSER_PDF_ENGINE", nil)
+      @file_parser_pdf_engine = env_pdf.strip if env_pdf && !env_pdf.strip.empty?
     end
 
     def apply_options!(options)
@@ -117,6 +126,8 @@ module SavvyOpenrouter
       elsif opts.key?(:completion_retries)
         assign_chat_retries(opts.delete(:completion_retries))
       end
+      assign_responses_retries(opts.delete(:responses_retries)) if opts.key?(:responses_retries)
+      assign_file_parser_pdf_engine(opts.delete(:file_parser_pdf_engine)) if opts.key?(:file_parser_pdf_engine)
 
       return if opts.empty?
 
@@ -152,5 +163,28 @@ module SavvyOpenrouter
         raise ArgumentError, "chat_retries must be a Hash or false"
       end
     end
+
+    def assign_responses_retries(value)
+      case value
+      when false, nil
+        @responses_retries = {}
+      when Hash
+        h = self.class.stringify_keys_static(value)
+        h["on"] = self.class.stringify_keys_static(h["on"]) if h["on"].is_a?(Hash)
+        @responses_retries = h
+      else
+        raise ArgumentError, "responses_retries must be a Hash or false"
+      end
+    end
+
+    def assign_file_parser_pdf_engine(value)
+      @file_parser_pdf_engine =
+        if value.nil?
+          nil
+        else
+          s = value.to_s.strip
+          s.empty? ? nil : s
+        end
+    end
   end
 end

data/lib/savvy_openrouter/connection.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "connection_instrumentation"
+require_relative "connection_api_call_recording"
+require_relative "connection_api_call_recording_transport"
 
 require "faraday"
 require "json"
@@ -10,14 +12,19 @@ require "uri"
 module SavvyOpenrouter
   class Connection
     include Instrumentation
+    include ApiCallRecording
+    include ApiCallRecordingTransport
 
     DEFAULT_SUCCESS = [200, 201, 202, 204].freeze
 
-    attr_reader :config
+    attr_reader :config, :api_call_logger
 
     def initialize(config)
       @config = config
       @api_call_logger = ApiCallLogger.new(config.api_call_log)
+      @call_context_stack = []
+      @pending_deferred_chat_log = nil
+      @pending_deferred_responses_log = nil
       base = normalize_base(config.base_url)
       headers = build_headers
       @conn = Faraday.new(url: base, headers: headers) do |faraday|
@@ -154,6 +161,38 @@ module SavvyOpenrouter
       raise
     end
 
+    def with_call_context(context = {})
+      parent = @call_context_stack.last || {}
+      merged = parent.merge(stringify_body(context.is_a?(Hash) ? context : {}))
+      @call_context_stack.push(merged)
+      yield
+    ensure
+      @call_context_stack.pop
+    end
+
+    # Record a logical failure after HTTP success (e.g. invalid structured JSON). Merges +context+ with +attrs+.
+    def record_manual_api_call(attrs)
+      ctx = stringify_body(@call_context_stack.last || {})
+      merged = ctx.merge(Configuration.stringify_keys_static(attrs))
+      @api_call_logger.record(merged)
+    end
+
+    def flush_deferred_chat_log!
+      attrs = @pending_deferred_chat_log
+      @pending_deferred_chat_log = nil
+      return if attrs.nil?
+
+      @api_call_logger.record(attrs)
+    end
+
+    def flush_deferred_responses_log!
+      attrs = @pending_deferred_responses_log
+      @pending_deferred_responses_log = nil
+      return if attrs.nil?
+
+      @api_call_logger.record(attrs)
+    end
+
     def stream_post(path, body, &)
       ensure_api_key!
       uri = join_uri(path)

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