# openai/openai-ruby architecture

> Architecture diagram of the GitHub repository openai/openai-ruby, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/openai-ruby
- Repository: https://github.com/openai/openai-ruby

## Overview

##### Project type and purpose
- This is an open-source Ruby client library (a gem) providing a typed, high-level wrapper around the OpenAI REST API.
- It’s not a web app or microservice but a software development kit (SDK) that Ruby applications import to call OpenAI endpoints, handle retries, paging, streaming, and marshal request/response data into rich model objects.

##### File structure
- Top-level directories:
- bin/ – CLI scripts for release and environment checks.
- examples/ – Ruby scripts showing usage patterns (chat, streaming, file uploads).
- lib/openai/ – the heart of the SDK:
– client.rb – the OpenAI::Client entry point.
– internal/transport – HTTP layer (connection‐pool, net/http wrapper).
– internal/type – machinery for BaseModel, type conversion, pagination.
– helpers/structured_output – utilities for JSON schema ↔ model conversions.
– models/ – classes representing request parameters and response structures per API domain (chat, audio, files, fine-tuning, evaluations, vector stores, etc.).
– resources/ – DSL for each REST resource grouping (e.g., chat.completions, files, embeddings).
- rbi/, sig/, sorbet/ – static type definitions for Sorbet and RBS.
- test/ – comprehensive unit tests.
- scripts/, Rakefile – tooling for build, lint, tests, release.

##### Insights from the README
- Uses net/http with connection_pool for thread-safe, pooled HTTP.
- Exposes OpenAI::Client with configurable timeouts, retries, and streaming support via SSE.
- Offers auto-pagination as iterators.
- Emphasizes strong typing with BaseModel and Sorbet/RBS support.

##### Main components & interactions
a. Components:
1. Client Layer (OpenAI::Client)
2. Transport Layer (PooledNetRequester → BaseClient → net/http)
3. Type & Model Layer (BaseModel, TypeConverters, Page/Stream abstractions)
4. Helpers (StructuredOutput, FilePart handling)
5. Resource DSL (chat, audio, files, embeddings, fine-tuning, evals, etc.)
6. External System (OpenAI REST API endpoints)
7. User Code (examples or consuming application)
b. Relationships & data flow:
- User Code → invokes → Client Layer
- Client Layer → delegates to → Resource DSL → builds request params as Model objects
- Resource DSL → calls → Transport Layer
- Transport Layer → HTTP request → OpenAI REST API
- API returns HTTP response → Transport Layer → parses JSON → Type & Model Layer → returns BaseModel instances
- Streaming endpoints use SSE client in Transport Layer, emitting events to Type & Model Layer
c. Architectural patterns & principles:
- Layered architecture: separation of concerns (Client, Resources, Transport, Models)
- DSL for resource grouping (method chaining: openai.chat.completions.create)
- Decorator/wrapper pattern for HTTP transport (connection pooling, retries)
- Auto-pagination iterator pattern
- Strong typing via BaseModel and static type definitions for Sorbet/RBS
d. Key technologies & libraries:
- Ruby 3.2+
- net/http (standard library)
- connection_pool gem
- Server-Sent Events streaming
- Sorbet/RBS/RBI for static typing

##### Detail is key
- Sub-layer (e.g., within Transport: PooledRequester → BaseClient → net/http).
- Streaming vs. non-streaming flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Runtime Flow
    subgraph "User Code"
        UserApp["User Code (examples or app)"]:::runtime
    end
    UserApp -->|"invokes"| Client

    Client["OpenAI::Client"]:::runtime
    click Client "https://github.com/openai/openai-ruby/blob/main/lib/openai/client.rb"

    Client -->|"uses DSL"| ResDir

    subgraph "Resource DSL"
        ResDir["Resources (DSL)"]:::runtime
        click ResDir "https://github.com/openai/openai-ruby/tree/main/lib/openai/resources/"
        ChatComp["chat.completions"]:::runtime
        click ChatComp "https://github.com/openai/openai-ruby/blob/main/lib/openai/resources/chat/completions.rb"
        ComMsgs["messages"]:::runtime
        click ComMsgs "https://github.com/openai/openai-ruby/blob/main/lib/openai/resources/chat/completions/messages.rb"
        FilesRes["files"]:::runtime
        click FilesRes "https://github.com/openai/openai-ruby/blob/main/lib/openai/resources/files.rb"
        EmbeddingsRes["embeddings"]:::runtime
        click EmbeddingsRes "https://github.com/openai/openai-ruby/blob/main/lib/openai/resources/embeddings.rb"
        FineTuneRes["fine_tuning"]:::runtime
        click FineTuneRes "https://github.com/openai/openai-ruby/blob/main/lib/openai/resources/fine_tuning.rb"
        EvalRes["evaluations"]:::runtime
        click EvalRes "https://github.com/openai/openai-ruby/blob/main/lib/openai/resources/evaluations.rb"
        ResDir --> ChatComp
        ResDir --> FilesRes
        ResDir --> EmbeddingsRes
        ResDir --> FineTuneRes
        ResDir --> EvalRes
        ChatComp --> ComMsgs
    end

    ResDir -->|"builds request"| PR

    subgraph "Transport Layer"
        PR["PooledNetRequester"]:::runtime
        click PR "https://github.com/openai/openai-ruby/blob/main/lib/openai/internal/transport/pooled_net_requester.rb"
        BC["BaseClient"]:::runtime
        click BC "https://github.com/openai/openai-ruby/blob/main/lib/openai/internal/transport/base_client.rb"
        HTTP["net/http"]:::runtime
        PR --> BC --> HTTP
    end

    BC -->|"HTTP request"| ExternalAPI
    HTTP -->|"HTTP request"| ExternalAPI

    ExternalAPI["OpenAI REST API"]:::external

    ExternalAPI -->|"HTTP response"| BC

    subgraph "Type & Model Layer"
        BM["BaseModel"]:::data
        click BM "https://github.com/openai/openai-ruby/blob/main/lib/openai/internal/type/base_model.rb"
        TC["TypeConverters"]:::data
        click TC "https://github.com/openai/openai-ruby/blob/main/lib/openai/internal/type/converter.rb"
        BP["BasePage (auto-pagination)"]:::data
        click BP "https://github.com/openai/openai-ruby/blob/main/lib/openai/internal/type/base_page.rb"
        BS["BaseStream (SSE)"]:::data
        click BS "https://github.com/openai/openai-ruby/blob/main/lib/openai/internal/type/base_stream.rb"
        GM["Generated Models"]:::data
        click GM "https://github.com/openai/openai-ruby/tree/main/lib/openai/models/"
        BM --> GM
        TC --> GM
        BS --> GM
        BC --> BM
        BC --> BS
        GM --> UserApp
        BP --> BP
        GM --> BP
    end

    subgraph "Helpers"
        SO["StructuredOutput"]:::data
        click SO "https://github.com/openai/openai-ruby/blob/main/lib/openai/helpers/structured_output/base_model.rb"
        click SO "https://github.com/openai/openai-ruby/blob/main/lib/openai/helpers/structured_output/json_schema_converter.rb"
        FP["FilePart"]:::data
        click FP "https://github.com/openai/openai-ruby/blob/main/lib/openai/file_part.rb"
    end

    SO --> BM
    FP --> PR

    %% Auxiliary Tooling
    subgraph "Type Definitions"
        RBI["RBI Definitions"]:::tooling
        click RBI "https://github.com/openai/openai-ruby/blob/main/rbi/openai/client.rbi"
        click RBI "https://github.com/openai/openai-ruby/blob/main/rbi/openai/internal/transport/pooled_net_requester.rbi"
        click RBI "https://github.com/openai/openai-ruby/blob/main/rbi/openai/models/all_models.rbi"
        RBS["RBS Definitions"]:::tooling
        click RBS "https://github.com/openai/openai-ruby/blob/main/sig/openai/client.rbs"
        click RBS "https://github.com/openai/openai-ruby/blob/main/sig/openai/internal/type/converter.rbs"
        click RBS "https://github.com/openai/openai-ruby/blob/main/sig/openai/models/audio/speech_create_params.rbs"
    end

    subgraph "CLI & Tooling"
        CLI1["bin scripts"]:::tooling
        click CLI1 "https://github.com/openai/openai-ruby/tree/main/bin/check-release-environment"
        click CLI1 "https://github.com/openai/openai-ruby/tree/main/bin/publish-gem"
        Scripts["scripts/"]:::tooling
        click Scripts "https://github.com/openai/openai-ruby/tree/main/scripts/bootstrap"
        click Scripts "https://github.com/openai/openai-ruby/tree/main/scripts/test"
        click Scripts "https://github.com/openai/openai-ruby/tree/main/scripts/lint"
        RF["Rakefile"]:::tooling
        click RF "https://github.com/openai/openai-ruby/tree/main/Rakefile"
    end

    %% Styles
    classDef runtime fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef data fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32;
    classDef tooling fill:#eceff1,stroke:#455a64,color:#455a64;
    classDef external fill:#ffebee,stroke:#c62828,color:#c62828;
```
