Skip to main content
The OpenAI Ruby SDK provides comprehensive RBI definitions for use with Sorbet, Ruby’s static type checker. The library has no runtime dependency on sorbet-runtime, so you can use Sorbet for development-time type checking without any performance overhead.

​
Type-Safe Parameters

You can use typed parameter classes for full type safety: 
openai.chat.completions.create(
  messages: [OpenAI::Chat::ChatCompletionUserMessageParam.new(content: "Say this is a test")],
  model: "gpt-5.2"
)

​
Hash Parameters (Not Type-Safe)

Hashes work but don’t provide type safety: 
# This works but Sorbet won't catch type errors:
openai.chat.completions.create(
  messages: [{role: "user", content: "Say this is a test"}],
  model: "gpt-5.2"
)

​
Using Params Classes

You can also construct and splat full parameter objects: 
params = OpenAI::Chat::CompletionCreateParams.new(
  messages: [OpenAI::Chat::ChatCompletionUserMessageParam.new(content: "Say this is a test")],
  model: "gpt-5.2"
)

openai.chat.completions.create(**params)
Using typed parameter classes helps Sorbet catch errors at development time, such as typos in field names or incorrect types.

​
Enums and Tagged Symbols

Since this library doesn’t depend on sorbet-runtime, it cannot provide T::Enum instances. Instead, the SDK uses tagged symbols — primitives at runtime with rich type information for Sorbet.

​
Accessing Enum Constants

# Returns the symbol :"in-memory"
puts(OpenAI::Chat::CompletionCreateParams::PromptCacheRetention::IN_MEMORY)

# Revealed type: `T.all(OpenAI::Chat::CompletionCreateParams::PromptCacheRetention, Symbol)`
T.reveal_type(OpenAI::Chat::CompletionCreateParams::PromptCacheRetention::IN_MEMORY)

​
Using Enums in Requests

Enum parameters accept both the constant and its literal value:
Using the enum constants (rather than literal symbols) provides better autocomplete and type checking in your editor.

​
RBI Files

The SDK ships with RBI files in the rbi/ directory of the gem. These are automatically discovered by Sorbet when you include the gem in your project.

​
Setting Up Sorbet

1

Install Sorbet

Add Sorbet to your Gemfile:
gem 'sorbet'
gem 'sorbet-runtime'  # Optional, only if you want runtime checks
2

Initialize Sorbet

Run Sorbet’s initialization command:
bundle exec srb init
3

Type Check Your Code

Run the type checker:
bundle exec srb tc

​
Type-Safe Response Handling

Response objects are also fully typed: 
completion = openai.chat.completions.create(
  messages: [{role: "user", content: "Hello"}],
  model: "gpt-5.2"
)

# Sorbet knows the shape of the response
message = completion.choices[0].message
content = message.content  # Type: String | nil

# Sorbet will catch this error:
# invalid_field = completion.invalid_field  # Method not found

​
Non-Breaking Type Changes

The OpenAI Ruby SDK considers improvements to *.rbi and *.rbs type definitions to be non-breaking changes according to SemVer. Type definitions may be refined in patch releases.

RBS Types

RBS type signature definitions

BaseModel

BaseModel conveniences and helpers

Structured Outputs

Type-safe structured outputs

Sorbet Documentation

Official Sorbet documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us