openai 0.78.0 → 0.79.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf3def8aaf6807cfdd1d5df8ed41e2eaf6513c703e9f8baa77db8c145637147a
-  data.tar.gz: 49a15beeb6bda9ba47e71cff822aa4eb0778c400b3a891ae15b2b7ade46f28ad
+  metadata.gz: c91ec0ec5334f72006f30c1c9287f4175038c146c2ae5361447e99159dd4940e
+  data.tar.gz: 9f34b2932f7aa72d19b1e313f1fc37941fd85aa00232a395362a738619e6d8c2
 SHA512:
-  metadata.gz: 7335e2cf29373c855d5f5866bb41ad0317ee0ba1df4ade67a9bfbddce0cd0befa3fb3910baa852bb2e95c8298b86a7c84de9a8cfe2c6324709ebf1ab47b4c17b
-  data.tar.gz: e596b1723939ef042457f1a9b7275cbb6f4d26fb6fe9f3a31bdbdc47d398f963da59b82217a4f626463a25596c6e0702193b95f4c3b2160c94a5340e7ef5971a
+  metadata.gz: e90ca693f7e19f02b668b5e35facaead8a83da5dd7cd9b14a527e613572241f3e5086b5e8d7f29bff089e1a6ce02ac5657c4181feb02c4374f8368b68d7325d6
+  data.tar.gz: 2ac6392091a4b4a46b07272a29e16fac51a7dca2f36d6bdf2be356d34e3424d2e49c0a922d72a9edf4badafaf6b2b04682d37e4e66f4e5dc197958a4f7191c58

data/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## [0.79.0](https://github.com/openai/openai-ruby/compare/v0.78.0...v0.79.0) (2026-08-14)
+
+
+### Features
+
+* add HTTP response observability ([#365](https://github.com/openai/openai-ruby/issues/365)) ([48d36b7](https://github.com/openai/openai-ruby/commit/48d36b70883a446a8062dca50fbc2d419fbe1fb9))
+* add Tapioca typing for structured outputs ([#364](https://github.com/openai/openai-ruby/issues/364)) ([738e2b4](https://github.com/openai/openai-ruby/commit/738e2b4de4f991e594f9d319c4d17f0955cd8edd))
+* **api:** Add new model identifiers and remove audit log source ([e0a4bc5](https://github.com/openai/openai-ruby/commit/e0a4bc56d5280c45a12e44adc49b6c34e182b33f))
+* **api:** add WebSocket stream IDs ([#387](https://github.com/openai/openai-ruby/issues/387)) ([5880287](https://github.com/openai/openai-ruby/commit/588028770b493f2ad55b1b9acfe6ad3164c1cddc))
+* **api:** add workload identity access token issued event ([#372](https://github.com/openai/openai-ruby/issues/372)) ([9199779](https://github.com/openai/openai-ruby/commit/919977919667da8b0764a7134d646e9cac24e709))
+* **api:** deprecate Sora video APIs ([#386](https://github.com/openai/openai-ruby/issues/386)) ([0664456](https://github.com/openai/openai-ruby/commit/0664456735e3eccc8dd15041a45528f59df3787d))
+* **client:** add default headers ([#369](https://github.com/openai/openai-ruby/issues/369)) ([d516874](https://github.com/openai/openai-ruby/commit/d516874ebca3ac142ecbc9d829367ab97ae685f2))
+* expose request IDs ([#352](https://github.com/openai/openai-ruby/issues/352)) ([c15fb7b](https://github.com/openai/openai-ruby/commit/c15fb7b5d3f15de8ffc1404dba870752175415af))
+* support Azure OpenAI v1 ([#355](https://github.com/openai/openai-ruby/issues/355)) ([c1d223e](https://github.com/openai/openai-ruby/commit/c1d223e2253450cee2631f875b968baa7cbcdc2e))
+
+
+### Bug Fixes
+
+* **api:** Add new model identifiers and remove audit log source ([#360](https://github.com/openai/openai-ruby/issues/360)) ([e0a4bc5](https://github.com/openai/openai-ruby/commit/e0a4bc56d5280c45a12e44adc49b6c34e182b33f))
+* **api:** allow nil timeout in client signatures ([#363](https://github.com/openai/openai-ruby/issues/363)) ([e52ca61](https://github.com/openai/openai-ruby/commit/e52ca61a116f7a49e98f903c28337232608264d7))
+* **api:** document file upload metadata defaults ([#361](https://github.com/openai/openai-ruby/issues/361)) ([b4bc1ea](https://github.com/openai/openai-ruby/commit/b4bc1eaf8dd8edcc10700b3d29669816176839a3))
+* coerce nested BaseModel fields ([#295](https://github.com/openai/openai-ruby/issues/295)) ([e5152a9](https://github.com/openai/openai-ruby/commit/e5152a92962251ce76ceb3d89ec0b6b37fa4efdb))
+* enable streaming when retrieving responses ([#413](https://github.com/openai/openai-ruby/issues/413)) ([fd85182](https://github.com/openai/openai-ruby/commit/fd8518235b16089b03733040f22e51f3fb043ed4))
+* encode multipart array and nested fields ([#348](https://github.com/openai/openai-ruby/issues/348)) ([1c71a1e](https://github.com/openai/openai-ruby/commit/1c71a1eccdee36a1e8dc8ab974ad1437396bd6e6))
+* honor workload identity environment defaults ([#398](https://github.com/openai/openai-ruby/issues/398)) ([f4afea1](https://github.com/openai/openai-ruby/commit/f4afea1057ebfa5447fbbef0d89f62943473efdc))
+* keep required path parameters out of resource query strings ([#402](https://github.com/openai/openai-ruby/issues/402)) ([6768a7c](https://github.com/openai/openai-ruby/commit/6768a7c29664fc9edce4f4da261920da8bb1959d))
+* loading after ActiveSupport 6 subclass extensions ([#346](https://github.com/openai/openai-ruby/issues/346)) ([20fbb09](https://github.com/openai/openai-ruby/commit/20fbb0942991888e618e5b5a86531e58fff65626))
+* make SDK debug body logging fail closed ([#411](https://github.com/openai/openai-ruby/issues/411)) ([c4f7284](https://github.com/openai/openai-ruby/commit/c4f72846e6f2bddc280f0723f880130ad27d2b71))
+* package every README-linked guide and example ([#382](https://github.com/openai/openai-ruby/issues/382)) ([ddecd0f](https://github.com/openai/openai-ruby/commit/ddecd0f75fc2a9e33e5fb6caf3f7531f7868fb90))
+* preserve binary multipart stream reads ([#354](https://github.com/openai/openai-ruby/issues/354)) ([b3a1ba7](https://github.com/openai/openai-ruby/commit/b3a1ba7f3dc561ac28d2768e619e46da75177c3c))
+* preserve existing BaseModel instances during coercion ([#400](https://github.com/openai/openai-ruby/issues/400)) ([fbd8560](https://github.com/openai/openai-ruby/commit/fbd8560ff986774acb4c3af849eba048232a8da3))
+* preserve prefixed idempotency headers on redirects ([#404](https://github.com/openai/openai-ruby/issues/404)) ([c380e13](https://github.com/openai/openai-ruby/commit/c380e13d1f866d591add5b32cc7e414de0ac85f2))
+* preserve stream identity with HTTP logging ([#384](https://github.com/openai/openai-ruby/issues/384)) ([640a1fe](https://github.com/openai/openai-ruby/commit/640a1fed33e57194cf4241001d171b75bc3b7638))
+* prevent symbol-keyed headers from bypassing security filters ([#383](https://github.com/openai/openai-ruby/issues/383)) ([b8165af](https://github.com/openai/openai-ruby/commit/b8165afa3065ee01e1440bc7e5339a9c5a7d7123))
+* redact sensitive query and form logging ([#389](https://github.com/openai/openai-ruby/issues/389)) ([7aa54e4](https://github.com/openai/openai-ruby/commit/7aa54e43aba381c33639a8f697348d0620ced5d0))
+* reject invalid webhook signing secrets ([#403](https://github.com/openai/openai-ruby/issues/403)) ([ad12458](https://github.com/openai/openai-ruby/commit/ad1245832fd18c7830becc2375c9fa7deadca88f))
+* remove unsound structured-output Tapioca compiler ([#405](https://github.com/openai/openai-ruby/issues/405)) ([826769a](https://github.com/openai/openai-ruby/commit/826769a5169eb659042fbfcb9259ad61f04d20a5))
+* restore RuboCop coverage for RBI files ([#388](https://github.com/openai/openai-ruby/issues/388)) ([d2d4b5d](https://github.com/openai/openai-ruby/commit/d2d4b5d1308e21703724b2f2561da2d328be5c46))
+* return values from interruptible enumerator ([#350](https://github.com/openai/openai-ruby/issues/350)) ([327dad7](https://github.com/openai/openai-ruby/commit/327dad76d434b8ea56401efb1312e9b499cc8e71))
+* strip credential headers on cross-origin redirects ([#391](https://github.com/openai/openai-ruby/issues/391)) ([f50f08c](https://github.com/openai/openai-ruby/commit/f50f08c15f373e956c0013d519c6d69c2484e562))
+* tighten JSON, JSONL, and SSE content type matching ([#277](https://github.com/openai/openai-ruby/issues/277)) ([66359a0](https://github.com/openai/openai-ruby/commit/66359a09076711315bed0c8aceea8db89bc4bd42))
+* use API field names in structured output schemas ([#390](https://github.com/openai/openai-ruby/issues/390)) ([d1e3cf3](https://github.com/openai/openai-ruby/commit/d1e3cf3cd2793d18e98394cd5e66da766c686557))
+* validate and bound retry delays ([#392](https://github.com/openai/openai-ruby/issues/392)) ([fff94e7](https://github.com/openai/openai-ruby/commit/fff94e789a9d750913306fe3c52973bd3e730916))
+* **webhooks:** support Rack and case-insensitive HTTP headers ([#401](https://github.com/openai/openai-ruby/issues/401)) ([37de980](https://github.com/openai/openai-ruby/commit/37de98099af70d8e97f50f8dc02ce5166c081d38))
+
+
+### Reverts
+
+* nested BaseModel coercion ([#295](https://github.com/openai/openai-ruby/issues/295)) ([#375](https://github.com/openai/openai-ruby/issues/375)) ([65fa76e](https://github.com/openai/openai-ruby/commit/65fa76e57881804908bc4d1753ee7d60cff1f875))
+
+
+### Chores
+
+* Cover Ruby files at the SDK root ([#362](https://github.com/openai/openai-ruby/issues/362)) ([d11f25b](https://github.com/openai/openai-ruby/commit/d11f25b28044e618849cd430c63946a306ede32c))
+* enforce boolean symbol lint ([#395](https://github.com/openai/openai-ruby/issues/395)) ([fafdf2e](https://github.com/openai/openai-ruby/commit/fafdf2e86e2736b79212189dee07aa83ba912945))
+* enforce deprecated constant lint ([#379](https://github.com/openai/openai-ruby/issues/379)) ([0def912](https://github.com/openai/openai-ruby/commit/0def9124cadee946879f2f66a5018ee986972509))
+* enforce duplicate match pattern lint ([#380](https://github.com/openai/openai-ruby/issues/380)) ([7a8f2fb](https://github.com/openai/openai-ruby/commit/7a8f2fb4ac9d1176bb5e8eac88cccc9766e3fd6c))
+* enforce empty else lint ([#396](https://github.com/openai/openai-ruby/issues/396)) ([1e073c1](https://github.com/openai/openai-ruby/commit/1e073c14a657e93ea0394fba29f9a059b3bf9b09))
+* enforce line length lint ([#406](https://github.com/openai/openai-ruby/issues/406)) ([4592061](https://github.com/openai/openai-ruby/commit/459206126267209930640d25eae0fada7177bff0))
+* enforce line length on base models ([#416](https://github.com/openai/openai-ruby/issues/416)) ([aef1e33](https://github.com/openai/openai-ruby/commit/aef1e333cae9c72379b3230a35d0274917999f82))
+* enforce line length on requires ([#415](https://github.com/openai/openai-ruby/issues/415)) ([c24e045](https://github.com/openai/openai-ruby/commit/c24e045bc1a194a0935a36ed48a17841f5309718))
+* enforce missing RuboCop enable directives ([#368](https://github.com/openai/openai-ruby/issues/368)) ([50046bf](https://github.com/openai/openai-ruby/commit/50046bf02497984d46377b9e9f1f6cc1370ee776))
+* enforce missing super lint ([#393](https://github.com/openai/openai-ruby/issues/393)) ([2a42bd0](https://github.com/openai/openai-ruby/commit/2a42bd0531f0c16e2d61d55b2dee80e541111812))
+* enforce nonempty pattern branches ([#409](https://github.com/openai/openai-ruby/issues/409)) ([9d22d5c](https://github.com/openai/openai-ruby/commit/9d22d5c63a9f68f1839de6f6b20f92d767eec80b))
+* enforce redundant directive lint ([#366](https://github.com/openai/openai-ruby/issues/366)) ([8448a4c](https://github.com/openai/openai-ruby/commit/8448a4cb1551fb47a28205556e0bce320eb82c99))
+* enforce redundant exception lint ([#397](https://github.com/openai/openai-ruby/issues/397)) ([cbda8bc](https://github.com/openai/openai-ruby/commit/cbda8bc0e6e3b2b8d0b96dfe3021d4557b713400))
+* enforce symbol conversion lint ([#381](https://github.com/openai/openai-ruby/issues/381)) ([0531498](https://github.com/openai/openai-ruby/commit/0531498c5498804408381dcef3ddec1228196ecd))
+* enforce useless assignment lint ([#394](https://github.com/openai/openai-ruby/issues/394)) ([9688836](https://github.com/openai/openai-ruby/commit/96888367ae757d119c90f2d9a81f4000d21745c2))
+* guard RuboCop suppression directives ([#408](https://github.com/openai/openai-ruby/issues/408)) ([5b6e0dc](https://github.com/openai/openai-ruby/commit/5b6e0dcc325f0f5a6a0fc6df8d9aea4999c90cf5))
+* lint Ruby files repository-wide ([#377](https://github.com/openai/openai-ruby/issues/377)) ([8ca8426](https://github.com/openai/openai-ruby/commit/8ca842693f441f19b18fda7190de4d68b2f7f9d9))
+* remove Stainless attribution and infrastructure ([#371](https://github.com/openai/openai-ruby/issues/371)) ([33d2c86](https://github.com/openai/openai-ruby/commit/33d2c864e1f3c2a683f1b826838b2bfd2e380a26))
+* require MFA for gem releases ([#378](https://github.com/openai/openai-ruby/issues/378)) ([71798ec](https://github.com/openai/openai-ruby/commit/71798ecb840a3feb8574efae3dd94af577717d64))
+
+
+### Documentation
+
+* **api:** describe response stream event unions ([#412](https://github.com/openai/openai-ruby/issues/412)) ([87d18ef](https://github.com/openai/openai-ruby/commit/87d18efc19445d0080344f6ebd5bc95dc8aed5cb))
+* clarify file upload metadata ([#358](https://github.com/openai/openai-ruby/issues/358)) ([698ac65](https://github.com/openai/openai-ruby/commit/698ac65d948f07edf30255c621abaac6437f0bcf)), closes [#243](https://github.com/openai/openai-ruby/issues/243)
+* document fiber scheduler concurrency ([#357](https://github.com/openai/openai-ruby/issues/357)) ([25a7bbc](https://github.com/openai/openai-ruby/commit/25a7bbcdc93c3331dc199e4cfe1da6037ef43bb2))
+
 ## [0.78.0](https://github.com/openai/openai-ruby/compare/v0.77.1...v0.78.0) (2026-08-07)
 
 

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openai", "~> 0.78.0"
+gem "openai", "~> 0.79.0"
 ```
 
 <!-- x-release-please-end -->
@@ -82,6 +82,8 @@ end
 
 Request parameters that correspond to file uploads can be passed as raw contents, a [`Pathname`](https://rubyapi.org/3.3/o/pathname) instance, [`StringIO`](https://rubyapi.org/3.3/o/stringio), or more.
 
+Raw `String` and `StringIO` values, and `IO` objects without a path, do not carry format-identifying metadata. The SDK sends them using the fallback filename `upload`; raw `String` values default to `text/plain`, while `StringIO` and pathless `IO` values default to `application/octet-stream`. For format-sensitive endpoints, such as audio transcriptions, wrap each value in `OpenAI::FilePart` and provide an extension-bearing filename and content type.
+
 ```ruby
 require "pathname"
 
@@ -93,12 +95,25 @@ file_object = openai.files.create(file: File.read("input.jsonl"), purpose: "fine
 
 puts(file_object.id)
 
-# Or, to control the filename and/or content type:
-image = OpenAI::FilePart.new(Pathname('dog.jpg'), content_type: 'image/jpeg')
+# For format-sensitive uploads, provide the filename and content type:
+audio_data = StringIO.new(File.binread("audio.wav"))
+audio = OpenAI::FilePart.new(
+  audio_data,
+  filename: "audio.wav",
+  content_type: "audio/wav"
+)
+transcription = openai.audio.transcriptions.create(
+  model: "gpt-4o-transcribe",
+  file: audio
+)
+puts(transcription.text)
+
+# FilePart also accepts a Pathname:
+image = OpenAI::FilePart.new(Pathname("dog.jpg"), content_type: "image/jpeg")
 edited = openai.images.edit(
   prompt: "make this image look like a painting",
   model: "gpt-image-1",
-  size: '1024x1024',
+  size: "1024x1024",
   image: image
 )
 
@@ -205,6 +220,49 @@ rotation, build and atomically swap in new `OpenAI::NetHTTPClient` and
 in-flight work finishes. See the complete [custom HTTP client mTLS
 example](examples/mtls_custom_http_client.rb).
 
+## Microsoft Azure OpenAI
+
+Use the standard client with the Azure provider to call model deployments through
+the Azure OpenAI v1 API. The provider accepts an Azure resource endpoint and
+adds `/openai/v1` when needed:
+
+```ruby
+require "openai"
+
+client = OpenAI::Client.new(
+  provider: OpenAI::Providers.azure(
+    endpoint: ENV.fetch("AZURE_OPENAI_ENDPOINT"),
+    api_key: ENV.fetch("AZURE_OPENAI_API_KEY")
+  )
+)
+
+response = client.responses.create(
+  model: ENV.fetch("AZURE_OPENAI_DEPLOYMENT"),
+  input: "Say hello!"
+)
+
+puts(response.output_text)
+```
+
+Omit `endpoint` and `api_key` to use `AZURE_OPENAI_ENDPOINT` and
+`AZURE_OPENAI_API_KEY`. For Microsoft Entra authentication, pass a callable
+that returns a current bearer token. The provider invokes it before every
+request attempt, including retries:
+
+```ruby
+client = OpenAI::Client.new(
+  provider: OpenAI::Providers.azure(
+    endpoint: ENV.fetch("AZURE_OPENAI_ENDPOINT"),
+    token_provider: -> { fetch_azure_openai_token }
+  )
+)
+```
+
+This integration targets the Azure OpenAI v1 API. It does not add dated
+`api-version` query parameters or rewrite requests to legacy
+`/deployments/{deployment}` paths. See [azure.md](azure.md) for configuration,
+authentication precedence, and endpoint security details.
+
 ## Amazon Bedrock
 
 Use the standard client with the Bedrock provider to call OpenAI models through Amazon Bedrock's OpenAI-compatible API. Add `aws-sdk-core` to your application for AWS credential discovery and SigV4 signing:
@@ -365,8 +423,11 @@ Note that the `body` parameter must be the raw JSON string sent from the server
 require 'sinatra'
 require 'openai'
 
-# Set up the client with webhook secret from environment variable
-client = OpenAI::Client.new(webhook_secret: ENV['OPENAI_WEBHOOK_SECRET'])
+# Set up the client with API credentials and the webhook secret
+client = OpenAI::Client.new(
+  api_key: ENV.fetch('OPENAI_API_KEY'),
+  webhook_secret: ENV.fetch('OPENAI_WEBHOOK_SECRET')
+)
 
 post '/webhook' do
   request_body = request.body.read
@@ -404,8 +465,11 @@ require 'sinatra'
 require 'json'
 require 'openai'
 
-# Set up the client with webhook secret from environment variable
-client = OpenAI::Client.new(webhook_secret: ENV['OPENAI_WEBHOOK_SECRET'])
+# Set up the client with API credentials and the webhook secret
+client = OpenAI::Client.new(
+  api_key: ENV.fetch('OPENAI_API_KEY'),
+  webhook_secret: ENV.fetch('OPENAI_WEBHOOK_SECRET')
+)
 
 post '/webhook' do
   request_body = request.body.read
@@ -565,6 +629,108 @@ Error codes are as follows:
 | Timeout          | `APITimeoutError`          |
 | Network error    | `APIConnectionError`       |
 
+### Request logging
+
+Request logging is disabled by default. Enable it with a standard Ruby logger
+when creating the client:
+
+```ruby
+client = OpenAI::Client.new(
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  logger: Rails.logger,
+  log_level: :info
+)
+```
+
+The logger can be any object that responds to `debug`, `info`, `warn`, and
+`error`; the SDK does not depend on Rails. Supplying a logger enables `:info`
+logging by default. When logging is enabled without a custom logger, the SDK
+uses a standard-library `Logger` that writes to stderr. Use `log_level: :off`
+when you only need retry notifications.
+
+You can instead set `OPENAI_LOG=info` or `OPENAI_LOG=debug`. An explicit
+`log_level:` takes precedence over the environment variable.
+
+For example, to use the stderr logger for one process:
+
+```sh
+OPENAI_LOG=info bundle exec ruby app.rb
+```
+
+A completion message includes the logical request and retry context:
+
+```text
+[openai] request complete log_id=log_a1b2c3d4e5f6 method=POST path=/v1/responses status=200 request_id=req_123 attempts=1 duration_ms=42.7
+```
+
+| Level | Behavior |
+| --- | --- |
+| `:off` | No SDK request logs (default) |
+| `:error` | Terminal request failures after retries are exhausted |
+| `:warn` | Error events plus retry reason and delay |
+| `:info` | Safe request completion summaries |
+| `:debug` | Per-attempt headers and bounded structural body diagnostics |
+
+Info, warning, and error logs include operational fields such as the HTTP
+method, sanitized path, status, request ID, duration, and attempt count. They
+never include headers or bodies. Debug logs redact credential-bearing headers
+and query parameters, including authorization, API-key, cookie, token,
+credential, and signature values.
+
+Debug body diagnostics never include customer-controlled object keys, string
+values, prompts, model responses, tool arguments, form fields, or signed URLs.
+JSON bodies report only their byte size, top-level type, and object-field or
+array-item count; form bodies report only their byte size and field count. The
+built-in logger omits uploaded file contents, multipart bodies, binary bodies,
+server-sent event contents, unsupported text bodies, oversized bodies, and
+incomplete bodies. Response bodies are observed only as the application consumes
+them and are never read eagerly for logging.
+
+SDK log messages are intended for human diagnostics. Their text format is not
+a stable structured-event API and may change between releases. Exceptions from
+a supplied logger are isolated and never replace an API result or API error.
+
+### Response metadata and request IDs
+
+OpenAI recommends logging request IDs in production so requests can be traced
+during troubleshooting. Top-level models and pages returned by the client expose
+immutable HTTP response metadata through `last_response`:
+
+```ruby
+response = openai.responses.create(model: "gpt-5.2", input: "Say 'this is a test'.")
+puts(response.last_response.status)                 # 200
+puts(response.last_response.headers["x-request-id"]) # req_123
+puts(response.last_response.request_id)             # req_123
+puts(response._request_id)                           # req_123
+```
+
+Header names and values are normalized to strings, header names are lowercase,
+and the metadata and header map are frozen. Streams expose the metadata for the
+HTTP response that opened the stream. Higher-level streaming helpers expose the
+same metadata as their underlying stream; models assembled from stream events
+do not.
+
+`last_response` and `_request_id` are only populated on top-level typed models
+and pages returned by the client. They are `nil` on constructed or nested models
+and are not included in `to_h`, JSON, or YAML output. Endpoints returning raw
+primitives, binary data, or `nil` do not expose this metadata. Unlike other
+properties that begin with an underscore, `_request_id` is public.
+
+For failed HTTP requests, catch `OpenAI::Errors::APIStatusError` and use
+`request_id`:
+
+```ruby
+begin
+  openai.responses.create(model: "gpt-5.2", input: "Say 'this is a test'.")
+rescue OpenAI::Errors::APIStatusError => e
+  puts(e.request_id) # req_123
+  raise
+end
+```
+
+See the [official OpenAI request debugging documentation](https://developers.openai.com/api/reference/overview#debugging-requests)
+for more information.
+
 ### Retries
 
 Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
@@ -587,6 +753,27 @@ openai.chat.completions.create(
 )
 ```
 
+To observe retries as they happen, supply an `on_retry` callback when creating
+the client. The callback runs immediately before the retry delay and receives
+an immutable `OpenAI::RetryEvent`:
+
+```ruby
+openai = OpenAI::Client.new(
+  log_level: :off,
+  on_retry: lambda do |event|
+    Rails.logger.warn(
+      "OpenAI retry #{event.attempt}/#{event.max_attempts} " \
+      "status=#{event.status.inspect} request_id=#{event.request_id.inspect}"
+    )
+  end
+)
+```
+
+For response-triggered retries, `event.response` contains the same immutable
+status, headers, and request ID shape as `last_response`. For connection errors,
+`event.error` is populated instead. Exceptions raised by the callback are
+isolated and do not replace the API result or error.
+
 ### Timeouts
 
 By default, requests will time out after 600 seconds. You can use the timeout option to configure or disable this:
@@ -611,6 +798,20 @@ Note that requests that time out are retried by default.
 
 ## Advanced concepts
 
+### Default request headers
+
+Use `default_headers` to send the same custom headers with every request made by a client:
+
+```ruby
+finance = OpenAI::Client.new(
+  default_headers: {"x-cost-center" => "finance"}
+)
+```
+
+Explicit `default_headers` override values from `OPENAI_CUSTOM_HEADERS`. For a single request,
+`request_options[:extra_headers]` can override a client default or remove it by assigning `nil`.
+Authentication and endpoint-specific headers also take precedence over client defaults.
+
 ### BaseModel
 
 All parameter and response objects inherit from `OpenAI::Internal::Type::BaseModel`, which provides several conveniences, including:
@@ -668,6 +869,38 @@ response = client.request(
 
 `OpenAI::Client` instances using the default `OpenAI::NetHTTPClient` are threadsafe, but are only fork-safe when there are no in-flight HTTP requests. Injected HTTP clients are responsible for documenting and enforcing their own concurrency guarantees.
 
+#### Asynchronous requests with a fiber scheduler
+
+The default HTTP client also cooperates with Ruby's fiber scheduler interface
+(`Fiber.scheduler`). When a request runs inside a non-blocking fiber managed by
+an active scheduler, network operations, streaming reads, retry delays, and
+waits for a pooled connection yield to other fibers instead of blocking the
+thread. Resource methods keep their normal return types; schedule each complete
+request or stream operation as a task using the scheduler implementation your
+application already uses.
+
+For example, with the [`async`](https://github.com/socketry/async) gem:
+
+```ruby
+require "async"
+
+prompts = ["Summarize the incident report.", "Draft the follow-up actions."]
+
+responses = Async do |task|
+  prompts.map do |prompt|
+    task.async do
+      openai.responses.create(model: "gpt-5.2", input: prompt)
+    end
+  end.map(&:wait)
+end.wait
+```
+
+Outside a non-blocking fiber managed by an active scheduler, calls block the
+current thread as usual. The SDK does not install a scheduler or depend on a
+particular scheduler gem.
+
+#### Connection pooling
+
 By default, each `OpenAI::Client` creates its own HTTP connection pool with a size of at least 99 connections. As such, we recommend instantiating the client once per application in most settings. An injected HTTP client may instead share its pool across multiple SDK clients; the caller owns that HTTP client's lifecycle.
 
 When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.

data/SECURITY.md

@@ -2,28 +2,12 @@
 
 ## Reporting Security Issues
 
-This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
-
-To report a security issue, please contact the Stainless team at security@stainless.com.
+Please report potential security vulnerabilities through OpenAI's
+[coordinated vulnerability disclosure process](https://openai.com/policies/coordinated-vulnerability-disclosure-policy).
+For questions about that process, contact disclosure@openai.com.
 
 ## Responsible Disclosure
 
-We appreciate the efforts of security researchers and individuals who help us maintain the security of
-SDKs we generate. If you believe you have found a security vulnerability, please adhere to responsible
-disclosure practices by allowing us a reasonable amount of time to investigate and address the issue
-before making any information public.
-
-## Reporting Non-SDK Related Security Issues
-
-If you encounter security issues that are not directly related to SDKs but pertain to the services
-or products provided by OpenAI, please follow the respective company's security reporting guidelines.
-
-### OpenAI Terms and Policies
-
-Our Security Policy can be found at [Security Policy URL](https://openai.com/policies/coordinated-vulnerability-disclosure-policy).
-
-Please contact disclosure@openai.com for any questions or concerns regarding the security of our services.
-
----
-
-Thank you for helping us keep the SDKs and systems they interact with secure.
+Please allow OpenAI a reasonable amount of time to investigate and address the
+issue before making information public. Thank you for helping us keep this SDK
+and the systems it interacts with secure.

data/azure.md

@@ -0,0 +1,110 @@
+# Microsoft Azure OpenAI
+
+Configure the standard `OpenAI::Client` with the Azure provider to use the
+[Azure OpenAI v1 API](https://learn.microsoft.com/azure/foundry/openai/api-version-lifecycle):
+
+```ruby
+require "openai"
+
+client = OpenAI::Client.new(
+  provider: OpenAI::Providers.azure(
+    endpoint: ENV.fetch("AZURE_OPENAI_ENDPOINT"),
+    api_key: ENV.fetch("AZURE_OPENAI_API_KEY")
+  )
+)
+
+response = client.responses.create(
+  model: ENV.fetch("AZURE_OPENAI_DEPLOYMENT"),
+  input: "Say hello!"
+)
+
+puts(response.output_text)
+```
+
+The `model` parameter is the Azure model deployment name. The provider exposes
+the normal Ruby SDK resources, request and response models, retries, pagination,
+streaming helpers, and custom HTTP transport. Azure controls which resources and
+features are available for a deployment; unsupported calls surface as normal API
+errors.
+
+## Endpoint configuration
+
+Pass the Azure resource endpoint or set `AZURE_OPENAI_ENDPOINT`:
+
+```ruby
+provider = OpenAI::Providers.azure(
+  endpoint: "https://my-resource.openai.azure.com",
+  api_key: ENV.fetch("AZURE_OPENAI_API_KEY")
+)
+```
+
+The provider appends `/openai/v1` when it is absent. These values therefore
+configure the same base URL:
+
+```text
+https://my-resource.openai.azure.com
+https://my-resource.openai.azure.com/openai
+https://my-resource.openai.azure.com/openai/v1/
+```
+
+The endpoint must be an absolute HTTP or HTTPS URL without user information, a
+query string, or a fragment. Use HTTPS outside local testing. A path prefix is
+preserved for gateways and private routing, for example
+`https://gateway.example.com/azure` becomes
+`https://gateway.example.com/azure/openai/v1`.
+
+## Authentication
+
+Configure exactly one authentication mode explicitly. If neither is explicit,
+the provider uses `AZURE_OPENAI_API_KEY`.
+
+### Azure API key
+
+Pass `api_key` or set `AZURE_OPENAI_API_KEY`. The provider sends it in Azure's
+`api-key` header:
+
+```ruby
+provider = OpenAI::Providers.azure(
+  endpoint: ENV.fetch("AZURE_OPENAI_ENDPOINT"),
+  api_key: ENV.fetch("AZURE_OPENAI_API_KEY")
+)
+```
+
+Passing `api_key: nil` explicitly skips the environment fallback.
+
+### Microsoft Entra bearer token
+
+Pass a callable that returns a current access token for Azure OpenAI. Credential
+acquisition stays with the application, so the SDK does not require an Azure
+identity package:
+
+```ruby
+provider = OpenAI::Providers.azure(
+  endpoint: ENV.fetch("AZURE_OPENAI_ENDPOINT"),
+  token_provider: -> {
+    credential.get_token("https://cognitiveservices.azure.com/.default").token
+  }
+)
+```
+
+An explicit `token_provider` takes precedence over an ambient
+`AZURE_OPENAI_API_KEY`. It is invoked immediately before every request attempt,
+including API retries, so applications can refresh short-lived tokens without
+rebuilding the client.
+
+## Security
+
+The provider validates the request origin before attaching an API key or bearer
+token. It refuses to authenticate redirects or custom requests whose origin
+differs from the configured Azure endpoint. Custom `Authorization` and `api-key`
+headers cannot be combined with provider-owned authentication.
+
+Keep credentials out of source control and logs. Prefer short-lived Microsoft
+Entra tokens to long-lived API keys for production workloads.
+
+## Dated Azure APIs
+
+This provider targets the GA Azure OpenAI v1 API. It does not support dated API
+versions such as `2025-04-01-preview`, inject `api-version` query parameters, or
+rewrite generated resource paths to `/deployments/{deployment}`. Use the v1 API
+for new integrations.