savvy_openrouter 0.2.0

checksums.yaml

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

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,50 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "vendor/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 35
+
+Metrics/ParameterLists:
+  Max: 8
+
+Metrics/ClassLength:
+  Max: 300
+
+Metrics/ModuleLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Max: 48
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*_spec.rb"
+    - "*.gemspec"
+
+Layout/LineLength:
+  Max: 130
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Style/YAMLFileRead:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-05-09
+
+### Added
+
+- **`Chat`:** configurable **`chat_retries`** / **`completion_retries`** for **`client.chat.completions`** — retries on empty assistant text, **`usage.completion_tokens == 0`**, and HTTP **429** / **502** / **500**/**501** / **503** with backoff (streaming unchanged).
+- **`Models`:** `SavvyOpenrouter::Resources::Models#list` forwards keyword arguments as **`GET /models`** query parameters (`category`, `output_modalities`, `supported_parameters`, etc.).
+- **`Models`:** `SavvyOpenrouter::Resources::Models#first_ranked_free_text_model(category:, output_modalities: "text")` returns the first model in the API response whose **`pricing.prompt`** and **`pricing.completion`** are both zero, preserving OpenRouter’s list order (used to mirror curated “top free” picks per category when combined with text modality filters).
+- **`Configuration`:** `api_call_log` in YAML or `api_call_log:` on the client — optional persistence of each HTTP exchange to a model class (`create!`) with user-defined column mappings for debugging (JSON, raw, and streaming paths).
+- **`Configuration`:** `responses_defaults` / `defaults_responses` in YAML or `responses_defaults:` on the client: merged only into **`POST /responses`**, so Responses-only fields (plugins, server tools, `max_output_tokens`, …) are not merged into chat, embeddings, rerank, audio, or Anthropic bodies.
+
+### Documentation
+
+- **README:** chat completion retries (`chat_retries`), API call logging (`api_call_log`), Models API, usage snippets, and integration test notes.
+
+## [0.1.0] - 2026-05-09
+
+### Added
+
+- `SavvyOpenrouter::Client` with resources for chat (incl. SSE streaming), Responses beta, Anthropic `/messages`, embeddings, rerank, models, credits, providers, generations, endpoints (ZDR), analytics (`/activity`), audio (speech + transcription), video generation (create, poll, download, stream, `poll_until`), OAuth PKCE helpers, API keys, organization members, guardrails, and workspaces.
+- YAML configuration discovery (`config/savvy_openrouter.yml`, `.savvy_openrouter.yml`) with merge defaults for chat and video requests.
+- Rails generator `savvy_openrouter:install` and CLI `savvy_openrouter install`.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Bryan Feller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,234 @@
+# Savvy OpenRouter
+
+Ruby client for [OpenRouter](https://openrouter.ai/) — unified access to chat models, embeddings, reranking, speech, transcription, **video generation**, OAuth, API keys, guardrails, workspaces, and related REST endpoints.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "savvy_openrouter"
+```
+
+Or install the gem directly:
+
+```bash
+gem install savvy_openrouter
+```
+
+## Configuration
+
+Precedence is **keyword arguments to `SavvyOpenrouter::Client`** (highest), then **YAML config**, then **environment variables** (lowest).
+
+### Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `OPENROUTER_API_KEY` | Bearer token (required for requests) |
+| `OPENROUTER_BASE_URL` | API base (default `https://openrouter.ai/api/v1`) |
+| `OPENROUTER_DEFAULT_MODEL` | Default `model` when omitted in request bodies |
+| `OPENROUTER_HTTP_REFERER` | `HTTP-Referer` header ([app attribution](https://openrouter.ai/docs/app-attribution.mdx)) |
+| `OPENROUTER_APP_TITLE` | `X-Title` header |
+
+### YAML config (optional)
+
+If `config/savvy_openrouter.yml` or `.savvy_openrouter.yml` exists in the working directory, it is loaded automatically. Example:
+
+```yaml
+api_key: "sk-or-v1-..."
+default_model: "openai/gpt-4o-mini"
+defaults:
+  temperature: 0.7
+  max_tokens: 4096
+video_defaults:
+  aspect_ratio: "16:9"
+  resolution: "720p"
+http_referer: "https://your-app.example.com"
+app_title: "Your App"
+
+# Responses API only (POST /responses) — plugins, tools, max_output_tokens, x_search_filter, etc.
+# Use this instead of putting `plugins` under global `defaults` (which would also merge into chat/embeddings).
+# See https://openrouter.ai/docs/api/reference/responses/web-search
+# responses_defaults:
+#   plugins:
+#     - id: web
+#       max_results: 5
+#   max_output_tokens: 4096
+```
+
+### API call logging (`api_call_log`)
+
+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.
+
+```yaml
+# Optional — persist each outbound HTTP exchange for debugging (Faraday JSON + raw + SSE streams)
+api_call_log:
+  model: OpenRouterApiCallLog
+  max_body_bytes: 65536
+  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
+```
+
+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.
+
+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).
+
+### Chat completion retries (`chat_retries`)
+
+For **`client.chat.completions`** only (not streaming), you can retry when OpenRouter returns a **successful HTTP 200** but the payload looks broken—common with **free tiers** (`usage.completion_tokens == 0`) or an **empty assistant `content`**—and on selected **HTTP errors** (`429`, `502`, `500`/`501`, `503`).
+
+Configure **`chat_retries`** in YAML or pass **`chat_retries:`** / **`completion_retries:`** to **`SavvyOpenrouter::Client`**. Retries are off unless **`max_attempts`** is **greater than 1**.
+
+```yaml
+chat_retries:
+  max_attempts: 4
+  base_delay_ms: 400
+  max_delay_ms: 8000
+  exponential_backoff: true   # default true; set false for fixed delay
+  jitter_ratio: 0.15          # 0–1, fraction of delay added randomly
+  on:                           # optional overrides (default true for each unless set false)
+    zero_completion_tokens: true
+    empty_assistant_content: true
+    rate_limit: true
+    bad_gateway: true
+    internal_server_error: true
+    service_unavailable: true
+```
+
+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.
+
+### Install templates
+
+**Rails**
+
+```bash
+rails generate savvy_openrouter:install
+```
+
+**Plain Ruby / scripts**
+
+```bash
+bundle exec savvy_openrouter install
+```
+
+Creates `config/savvy_openrouter.yml` from the bundled template.
+
+### Responses API: web search and plugins
+
+The [Responses API](https://openrouter.ai/docs/api/reference/responses/overview) accepts parameters such as [`plugins`](https://openrouter.ai/docs/api/reference/responses/web-search) (legacy web plugin), [`tools`](https://openrouter.ai/docs/guides/features/server-tools/web-search) (recommended `openrouter:web_search` server tool for Chat Completions and Responses), `max_output_tokens`, and `x_search_filter` (xAI).
+
+**Do not put those keys in the global `defaults` hash**, because `defaults` is merged into **chat completions, embeddings, rerank, audio,** etc. Instead use **`responses_defaults`** in YAML (or `responses_defaults:` when constructing `SavvyOpenrouter::Client`). Those keys are merged **only** into `client.responses.create(...)`.
+
+Example:
+
+```yaml
+responses_defaults:
+  plugins:
+    - id: web
+      max_results: 5
+  max_output_tokens: 9000
+```
+
+Per-request arguments override the same keys from `responses_defaults`.
+
+OpenRouter documents the legacy `plugins: [{ id: "web" }]` approach as deprecated in favor of the **`openrouter:web_search` server tool** via the `tools` array; you can still pass either shape through this gem as passthrough JSON.
+
+### Models API (`GET /models`)
+
+[`GET /api/v1/models`](https://openrouter.ai/docs/api/api-reference/models/get-models) supports optional **query parameters**, including `category` (for example `programming`, `roleplay`, `science`), `output_modalities` (for example `text`), and `supported_parameters`. Pass them as keywords to **`client.models.list`**:
+
+```ruby
+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:
+
+```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.
+
+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.
+
+## Usage
+
+```ruby
+require "savvy_openrouter"
+
+client = SavvyOpenrouter::Client.new(api_key: ENV.fetch("OPENROUTER_API_KEY"))
+
+# Chat completion (defaults from YAML/env merged into body)
+response = client.chat.completions(
+  messages: [{ role: "user", content: "Hello!" }]
+)
+puts response[:choices].first[:message][:content]
+
+# Streaming (SSE); each yielded string is a JSON `data:` payload from OpenRouter
+client.chat.completions_stream(messages: [{ role: "user", content: "Hi" }]) do |data_json|
+  chunk = JSON.parse(data_json)
+  print chunk.dig("choices", 0, "delta", "content")
+end
+
+# Embeddings
+client.embeddings.create(model: "openai/text-embedding-3-small", input: "Hello world")
+
+# Video: create (HTTP 202), poll, download binary
+job = client.videos.create(model: "google/veo-3.1", prompt: "A calm ocean at dawn")
+status = client.videos.poll_until(job[:id])
+video_bytes = client.videos.download(job[:id]) if status[:status].to_s == "completed"
+
+# Binary speech (TTS)
+audio_bytes = client.audio.speech(model: "elevenlabs/...", input: "Hello")
+
+# Responses API (beta)
+client.responses.create(model: "openai/gpt-4o", input: "Hello")
+
+# Discover top free model for a category (GET /models) — run rarely; persist the id, do not call per user message
+top_free = client.models.first_ranked_free_text_model(category: "programming")
+# e.g. save top_free[:id] to ENV or default_model, then:
+client.chat.completions(model: top_free[:id], messages: [{ role: "user", content: "Hello!" }])
+
+# Management APIs (typically require a management key)
+client.api_keys.list
+client.guardrails.list
+client.workspaces.list
+```
+
+See the [OpenRouter API reference](https://openrouter.ai/docs/api/reference/overview) for request/response shapes.
+
+## Errors
+
+API failures raise subclasses of `SavvyOpenrouter::ApiError` (for example `AuthenticationError`, `PaymentRequiredError`, `RateLimitError`, `BadGatewayError`). Every error exposes `#status_code` and `#response_body` when available.
+
+## Development
+
+```bash
+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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in this project's repositories is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/savvy_openrouter

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+
+gem_root = File.expand_path("..", __dir__)
+template = File.join(gem_root, "lib/generators/savvy_openrouter/install/templates/savvy_openrouter.yml")
+
+unless File.file?(template)
+  warn "Template missing: #{template}"
+  exit 1
+end
+
+case ARGV[0]
+when "install"
+  dest_dir = File.join(Dir.pwd, "config")
+  dest = File.join(dest_dir, "savvy_openrouter.yml")
+  FileUtils.mkdir_p(dest_dir)
+  if File.file?(dest)
+    warn "Already exists: #{dest}"
+    exit 1
+  end
+  FileUtils.cp(template, dest)
+  puts "Created #{dest}"
+when nil, "-h", "--help"
+  puts "Usage: savvy_openrouter install"
+  exit(ARGV[0] ? 0 : 1)
+else
+  warn "Unknown command: #{ARGV[0].inspect}"
+  warn "Usage: savvy_openrouter install"
+  exit 1
+end

data/lib/generators/savvy_openrouter/install/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module SavvyOpenrouter
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/savvy_openrouter.yml for OpenRouter defaults"
+
+      def copy_config
+        copy_file "savvy_openrouter.yml", "config/savvy_openrouter.yml"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# OpenRouter defaults — loaded automatically when present at config/savvy_openrouter.yml
+# or .savvy_openrouter.yml (see SavvyOpenrouter::Configuration).
+#
+# Precedence: keyword arguments to SavvyOpenrouter::Client > this file > ENV variables.
+
+# api_key: "sk-or-v1-..."
+# base_url: "https://openrouter.ai/api/v1"
+
+# Default model merged into chat/embeddings/rerank/audio bodies when `model` is omitted:
+# default_model: "openai/gpt-4o-mini"
+
+# Optional app attribution headers (https://openrouter.ai/docs/app-attribution.mdx):
+# http_referer: "https://your-app.example.com"
+# app_title: "Your App Name"
+
+# Keys merged into POST /chat/completions (and similar) bodies:
+# defaults:
+#   temperature: 0.7
+#   max_tokens: 4096
+
+# Keys merged into POST /videos bodies when creating video jobs:
+# video_defaults:
+#   aspect_ratio: "16:9"
+#   resolution: "720p"
+#   duration: 8
+
+# Keys merged only into POST /responses (Responses API beta) — not chat/embeddings:
+# responses_defaults:
+#   plugins:
+#     - id: web
+#       max_results: 5
+#   max_output_tokens: 9000
+#
+# Optional: persist HTTP exchanges for debugging (Rails: migration + model with create!)
+# api_call_log:
+#   model: OpenRouterApiCallLog
+#   max_body_bytes: 65536
+#   columns:
+#     method: http_method
+#     path: request_url
+#     status: response_status
+#     duration_ms: duration_ms
+#     request_body: request_body
+#     response_body: response_body
+#     error_class: error_class
+#     error_message: error_message
+#     streaming: streaming
+#
+# Optional: retry chat/completions (non-streaming) on empty output, zero completion tokens, or transient HTTP errors
+# chat_retries:
+#   max_attempts: 4
+#   base_delay_ms: 400
+#   max_delay_ms: 8000