chore: documentation improvements

Author: stainless-app[bot]

README.md

@@ -31,16 +31,26 @@ openai = OpenAI::Client.new(
 )
 
 chat_completion = openai.chat.completions.create(
-  messages: [{
-    role: "user",
-    content: "Say this is a test"
-  }],
-  model: "gpt-4o"
+  messages: [{role: :user, content: "Say this is a test"}],
+  model: :"gpt-4.1"
 )
 
 puts(chat_completion)
 ```
 
+## Sorbet
+
+This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+
+When using sorbet, it is recommended to use model classes as below. This provides stronger type checking and tooling integration.
+
+```ruby
+openai.chat.completions.create(
+  messages: [OpenAI::Models::Chat::ChatCompletionUserMessageParam.new(role: :user, content: "Say this is a test")],
+  model: :"gpt-4.1"
+)
+```
+
 ### Pagination
 
 List methods in the OpenAI API are paginated.
@@ -68,11 +78,8 @@ We provide support for streaming responses using Server-Sent Events (SSE).
 
 ```ruby
 stream = openai.chat.completions.stream_raw(
-  messages: [{
-    role: "user",
-    content: "Say this is a test"
-  }],
-  model: "gpt-4o"
+  messages: [{role: :user, content: "Say this is a test"}],
+  model: :"gpt-4.1"
 )
 
 stream.each do |completion|
@@ -88,11 +95,11 @@ Request parameters that correspond to file uploads can be passed as `StringIO`,
 require "pathname"
 
 # using `Pathname`, the file will be lazily read, without reading everything in to memory
-file_object = openai.files.create(file: Pathname("input.jsonl"), purpose: "fine-tune")
+file_object = openai.files.create(file: Pathname("input.jsonl"), purpose: :"fine-tune")
 
 file = File.read("input.jsonl")
 # using `StringIO`, useful if you already have the data in memory
-file_object = openai.files.create(file: StringIO.new(file), purpose: "fine-tune")
+file_object = openai.files.create(file: StringIO.new(file), purpose: :"fine-tune")
 
 puts(file_object.id)
 ```
@@ -103,7 +110,7 @@ When the library is unable to connect to the API, or if the API returns a non-su
 
 ```ruby
 begin
-  job = openai.fine_tuning.jobs.create(model: "gpt-4o", training_file: "file-abc123")
+  job = openai.fine_tuning.jobs.create(model: :"babbage-002", training_file: "file-abc123")
 rescue OpenAI::Errors::APIError => e
   puts(e.status) # 400
 end
@@ -141,11 +148,8 @@ openai = OpenAI::Client.new(
 
 # Or, configure per-request:
 openai.chat.completions.create(
-  messages: [{
-    role: "user",
-    content: "How can I get the name of the current day in JavaScript?"
-  }],
-  model: "gpt-4o",
+  messages: [{role: :user, content: "How can I get the name of the current day in JavaScript?"}],
+  model: :"gpt-4.1",
   request_options: {max_retries: 5}
 )
 ```
@@ -166,78 +170,44 @@ openai = OpenAI::Client.new(
 
 # Or, configure per-request:
 openai.chat.completions.create(
-  messages: [{
-    role: "user",
-    content: "How can I list all files in a directory using Python?"
-  }],
-  model: "gpt-4o",
+  messages: [{role: :user, content: "How can I list all files in a directory using Python?"}],
+  model: :"gpt-4.1",
   request_options: {timeout: 5}
 )
 ```
 
-## LSP Support
+## Editor support
 
-### Solargraph
+Some editor language services like [Solargraph](https://github.com/castwide/solargraph?tab=readme-ov-file#gem-support) or [Sorbet](https://sorbet.org/docs/rbi#the-hidden-definitions-rbi) require a manually triggered indexing step before functionalities like auto-completion and go to definition can operate.
 
-This library includes [Solargraph](https://solargraph.org) support for both auto completion and go to definition.
+Please refer to their respective documentation for details. This library also includes a [short guide](https://github.com/openai/openai-ruby/tree/main/CONTRIBUTING.md#editor-support) on how to set up various editor services for internal development.
 
-```ruby
-gem "solargraph", group: :development
-```
+## Advanced Concepts
 
-After Solargraph is installed, **you must populate its index** either via the provided editor command, or by running the following in your terminal:
+### Model DSL
 
-```sh
-bundle exec solargraph gems
-```
+This library uses a Model DSL to represent request parameters and response shapes in `lib/openai/models`.
 
-Note: if you had installed the gem either using a `git:` or `github:` URL, or had vendored the gem using bundler, you will need to set up your [`.solargraph.yml`](https://solargraph.org/guides/configuration) to include the path to the gem's `lib` directory.
+The model classes service as anchor points for both toolchain readable documentation, and language service assisted navigation links. This information also allows the SDK's internals to perform translation between plain and rich data types; e.g., conversion between a `Time` instance and an ISO8601 `String`, and vice versa.
 
-```yaml
-include:
-  - 'vendor/bundle/ruby/*/gems/openai-*/lib/**/*.rb'
-```
-
-Otherwise Solargraph will not be able to provide type information or auto-completion for any non-indexed libraries.
-
-### Sorbet
-
-This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
-
-What this means is that while you can use Sorbet to type check your code statically, and benefit from the [Sorbet Language Server](https://sorbet.org/docs/lsp) in your editor, there is no runtime type checking and execution overhead from Sorbet itself.
-
-Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `OpenAI::BaseModel` class, you will need to use the `**` splat operator to pass the arguments:
-
-Please follow Sorbet's [setup guides](https://sorbet.org/docs/adopting) for best experience.
+In all places where a `BaseModel` type is specified, vanilla Ruby `Hash` can also be used. For example, the following are interchangeable as arguments:
 
 ```ruby
+# This has tooling readability, for auto-completion, static analysis, and goto definition with supported language services
 params = OpenAI::Models::Chat::CompletionCreateParams.new(
-    messages: [
-      OpenAI::Models::ChatCompletionUserMessageParam.new(
-        role: "user",
-        content: "Say this is a test"
-      )
-    ],
-    model: "gpt-4o"
-  )
+  messages: [OpenAI::Models::Chat::ChatCompletionUserMessageParam.new(role: :user, content: "Say this is a test")],
+  model: :"gpt-4.1"
+)
 
-openai.chat.completions.create(**params)
+# This also works
+params = {
+  messages: [{role: :user, content: "Say this is a test"}],
+  model: :"gpt-4.1"
+}
 ```
 
-Note: **This library emits an intentional warning under the [`tapioca` toolchain](https://github.com/Shopify/tapioca)**. This is normal, and does not impact functionality.
-
-### Ruby LSP
-
-The Ruby LSP has [best effort support](https://shopify.github.io/ruby-lsp/#guessed-types) for inferring type information from Ruby code, and as such it may not always be able to provide accurate type information.
-
-## Advanced
-
 ### Making custom/undocumented requests
 
-This library is typed for convenient access to the documented API.
-
-If you need to access undocumented endpoints, params, or response properties, the library can still be used.
-
 #### Undocumented request params
 
 If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a requests as seen in examples above.
@@ -248,15 +218,15 @@ To make requests to undocumented endpoints, you can make requests using `client.
 
 ```ruby
 response = client.request(
-    method: :post,
-    path: '/undocumented/endpoint',
-    query: {"dog": "woof"},
-    headers: {"useful-header": "interesting-value"},
-    body: {"he": "llo"},
-  )
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"he": "llo"},
+)
 ```
 
-### Concurrency & Connection Pooling
+### Concurrency & connection pooling
 
 The `OpenAI::Client` instances are thread-safe, and should be re-used across multiple threads. By default, each `Client` have their own HTTP connection pool, with a maximum number of connections equal to thread count.
 
@@ -266,6 +236,33 @@ Unless otherwise specified, other classes in the SDK do not have locks protectin
 
 Currently, `OpenAI::Client` instances are only fork-safe if there are no in-flight HTTP requests.
 
+### Sorbet
+
+#### Enums
+
+Sorbet's typed enums require sub-classing of the [`T::Enum` class](https://sorbet.org/docs/tenum) from the `sorbet-runtime` gem.
+
+Since this library does not depend on `sorbet-runtime`, it uses a [`T.all` intersection type](https://sorbet.org/docs/intersection-types) with a ruby primitive type to construct a "tagged alias" instead.
+
+```ruby
+module OpenAI::Models::ChatModel
+  # This alias aids language service driven navigation.
+  TaggedSymbol = T.type_alias { T.all(Symbol, OpenAI::Models::ChatModel) }
+end
+```
+
+#### Argument passing trick
+
+It is possible to pass a compatible model / parameter class to a method that expects keyword arguments by using the `**` splat operator.
+
+```ruby
+params = OpenAI::Models::Chat::CompletionCreateParams.new(
+  messages: [OpenAI::Models::Chat::ChatCompletionUserMessageParam.new(role: :user, content: "Say this is a test")],
+  model: :"gpt-4.1"
+)
+openai.chat.completions.create(**params)
+```
+
 ## Versioning
 
 This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
@@ -275,3 +272,7 @@ This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` typ
 ## Requirements
 
 Ruby 3.1.0 or higher.
+
+## Contributing
+
+See [the contributing documentation](https://github.com/openai/openai-ruby/tree/main/CONTRIBUTING.md).

Rakefile

@@ -21,7 +21,7 @@ end
 
 desc("Preview docs; use `PORT=<PORT>` to change the port")
 multitask(:"docs:preview") do
-  sh(*%w[yard server --bind [::] --reload --quiet --port], ENV.fetch("PORT", "8808"))
+  sh(*%w[yard server --reload --quiet --bind [::] --port], ENV.fetch("PORT", "8808"))
 end
 
 desc("Run test suites; use `TEST=path/to/test.rb` to run a specific test file")
@@ -111,7 +111,7 @@ end
 desc("Typecheck everything")
 multitask(typecheck: [:"typecheck:steep", :"typecheck:sorbet"])
 
-desc("Lint everything")
+desc("Lint and typecheck")
 multitask(lint: [:"lint:rubocop", :typecheck])
 
 desc("Build yard docs")

lib/openai.rb

@@ -19,15 +19,6 @@
 # We already ship the preferred sorbet manifests in the package itself.
 # `tapioca` currently does not offer us a way to opt out of unnecessary compilation.
 if Object.const_defined?(:Tapioca) && caller.chain([$PROGRAM_NAME]).chain(ARGV).grep(/tapioca/)
-  Warning.warn(
-    <<~WARN
-      \n
-      ⚠️ skipped loading of "openai" gem under `tapioca`.
-
-      This message is normal and expected if you are running a `tapioca` command, and does not impact `.rbi` generation.
-      \n
-    WARN
-  )
   return
 end