savvy_openrouter 0.2.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5429c1ab8b5a4a777f1e95511f1ff54a6b4c409026637a1732f090bf919fc1fc
-  data.tar.gz: 40731fb4249d671e8ad33aaeab2de19708972cf75abc2a5d3d91e702d9e7dde4
+  metadata.gz: 8137e975dade1520d62e20932114c3001f00f068ef088a58e1ffb461c1ba7473
+  data.tar.gz: 6aedce626d20af2e52b5b109c595a7b36a87c1861275d6bcce5d64cf52dfbd7c
 SHA512:
-  metadata.gz: 73104149df96fcbbc61b33719d924865335c98f355ac37f5701b0083005e8dca9f7fc38d7740722d70524a207a485474cfe7a7e03383cde1bf2818dbe91a8eb6
-  data.tar.gz: 1d3f8011538f69c2e5e47aae61b7adbb28d262ab3e13c369214d7c6f442d347da1ce8ae36e05bdc36067624b732dc6b8d63d22c38df4e8d43de5d7334ae2854b
+  metadata.gz: ca74a1076e38ef38c008d8562744cc88625ca409c93e3ce3474c8413c04cb10fc830a7fc69811578e6d2dee4f1b659b2339319cd151abf2062f446d4df02b0c0
+  data.tar.gz: 30a6e7c41a40710944ad41a2ea9d3886961d4f6ef9e2f6ef7f902c339cb1b7d4e63705a63e2f74163ee06f173cb7ba66f5c2e48c09d20829838f24894e752d9d

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 ## [Unreleased]
 
+## [0.4.2] - 2026-07-14
+
+### Changed
+
+- **`Models#first_ranked_free_text_model`:** passes **`max_price: 0`** to **`GET /models`** (OpenRouter’s free-price filter) while still requiring zero prompt and completion pricing. Temporary free models with an **`expiration_date`** remain eligible when they rank first. Integration expectations updated for current top free ids; smoke chat model switched off the removed `inclusionai/ring-2.6-1t:free` id.
+
+## [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**
@@ -151,14 +214,14 @@ OpenRouter documents the legacy `plugins: [{ id: "web" }]` approach as deprecate
 client.models.list(category: "programming", output_modalities: "text")
 ```
 
-OpenRouter returns models in **curated rank order** within each filtered result set—that order is not “highest `context_length` wins.” To approximate the **top free text model** for a category, call **`first_ranked_free_text_model`**, which keeps API order and returns the **first** model whose **`pricing.prompt`** and **`pricing.completion`** both parse to zero:
+OpenRouter returns models in **curated rank order** within each filtered result set—that order is not “highest `context_length` wins.” To approximate the **top free text model** for a category, call **`first_ranked_free_text_model`**, which calls **`GET /models`** with **`max_price=0`** (and text modality), keeps API order, and returns the **first** model whose **`pricing.prompt`** and **`pricing.completion`** both parse to zero. Temporary free models (those with an **`expiration_date` / “going away” badge) are **included** on purpose when they rank first:
 
 ```ruby
 client.models.first_ranked_free_text_model(category: "programming")
 client.models.first_ranked_free_text_model(category: "roleplay")
 ```
 
-**Use a stored model id for normal traffic.** Resolving the free model calls **`GET /models`** (one request). Each chat turn is **`POST /chat/completions`** (another). If you call `first_ranked_free_text_model` (or `list` and pick) on **every** user message, you pay **two** API calls per turn—list plus chat. Instead, resolve **once** (at deploy, in a Rake task, or on a long TTL), **remember** the returned **`id`** (environment variable, database, cache, or `default_model` in `savvy_openrouter.yml`), and pass that string to **`client.chat.completions(model: ...)`** for ongoing requests. Refresh the stored id when you want to pick up a new “top free” model after OpenRouter changes their list.
+**Use a stored model id for normal traffic.** Resolving the free model calls **`GET /models`** (one request). Each chat turn is **`POST /chat/completions`** (another). If you call `first_ranked_free_text_model` (or `list` and pick) on **every** user message, you pay **two** API calls per turn—list plus chat. Instead, resolve **once** (at deploy, in a Rake task, or on a long TTL), **remember** the returned **`id`** (environment variable, database, cache, or `default_model` in `savvy_openrouter.yml`), and pass that string to **`client.chat.completions(model: ...)`** for ongoing requests. Refresh the stored id when you want to pick up a new “top free” model after OpenRouter changes their list—especially if the chosen model lists an expiration date.
 
 That heuristic stays aligned with OpenRouter’s listing **as long as their ranking and pricing rows stay as they are**; it is not a separate benchmark score from the JSON (there is no `rating` field on each model). For chat-specific knobs such as **`tools`**, **`tool_choice`**, and **`response_format`** (including JSON schema), pass them on **`client.chat.completions`**; global YAML **`defaults`** also merge into embeddings and other resources, so prefer per-call args for tool and schema defaults unless you only use chat endpoints.
 
@@ -219,7 +282,7 @@ bin/setup
 bundle exec rake   # RSpec + RuboCop
 ```
 
-Integration tests live in `spec/integration/` and are tagged `:integration`. When `OPENROUTER_API_KEY` is set, they call the live API (WebMock allows net connect only for those examples). Smoke chat examples use the free model `inclusionai/ring-2.6-1t:free`; **`spec/integration/free_model_rank_spec.rb`** asserts curated “first free” model ids for `programming` and `roleplay` against the live models list (these examples can fail if OpenRouter changes ordering or pricing).
+Integration tests live in `spec/integration/` and are tagged `:integration`. When `OPENROUTER_API_KEY` is set, they call the live API (WebMock allows net connect only for those examples). Smoke chat examples use the free model `nvidia/nemotron-3-super-120b-a12b:free`; **`spec/integration/free_model_rank_spec.rb`** asserts curated “first free” model ids for `programming` and `roleplay` against the live models list (these examples can fail if OpenRouter changes ordering or pricing).
 
 ## Contributing
 

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)