If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/alexrudall/ruby-openai shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1w ago
• 8 active contributors
• MIT licensed
• Tests present
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live alexrudall/ruby-openai repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alexrudall/ruby-openai.

What it runs against: a local clone of alexrudall/ruby-openai — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in alexrudall/ruby-openai | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of alexrudall/ruby-openai. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/alexrudall/ruby-openai.git
#   cd ruby-openai
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of alexrudall/ruby-openai and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "alexrudall/ruby-openai(\\.git)?\\b" \\
  && ok "origin remote is alexrudall/ruby-openai" \\
  || miss "origin remote is not alexrudall/ruby-openai (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 38 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~8d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/alexrudall/ruby-openai"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ruby-openai is a Ruby gem providing a complete wrapper around the OpenAI API, enabling Ruby developers to integrate GPT models, the Responses API, Realtime WebRTC conversations, vision capabilities, and assistants into their applications. It abstracts away HTTP complexity and provides idiomatic Ruby interfaces for streaming, tool calling, batch processing, and vector store management. Modular architecture with lib/openai/client.rb as the main entry point delegating to specialized modules (lib/openai/chat.rb, lib/openai/assistants.rb, lib/openai/realtime.rb, lib/openai/vector_stores.rb, etc). HTTP handling abstracted in lib/openai/http.rb with Faraday middleware support. Streaming implemented via lib/openai/stream.rb. Responses API separated into lib/openai/responses.rb for newer async patterns.

Ruby developers (Rails, Sinatra, or standalone) building AI-powered applications who need production-ready OpenAI integrations without writing raw HTTP clients. Also useful for AI/ML engineers prototyping with Ruby and teams migrating from Python OpenAI SDK to Ruby.

Production-ready with active maintenance. The project has a clear versioning strategy (see lib/openai/version.rb), CircleCI CI/CD pipeline, comprehensive test coverage, proper documentation (MIGRATION.md, CONTRIBUTING.md), and recent updates supporting cutting-edge OpenAI features like Realtime WebRTC and GPT-5. Actively developed with sponsor backing.

Low-to-medium risk: single maintainer (alexrudall) is a potential bottleneck, but the gem has strong community backing (Discord, sponsors listed in README). Tight coupling to OpenAI API means breaking changes in OpenAI's API require rapid updates. Dependency footprint appears small (primary dependency is Faraday for HTTP), reducing supply-chain risk.

Active development on Realtime WebRTC support (lib/openai/realtime.rb), Responses API (lib/openai/responses.rb), and vector store management (lib/openai/vector_store_*.rb files). Recent additions include batch processing (lib/openai/batches.rb) and run_steps support. Maintainer actively merges PRs and updates for new OpenAI capabilities.

git clone https://github.com/alexrudall/ruby-openai.git && cd ruby-openai && bundle install && bundle exec rspec to run tests. For development: use bin/setup to initialize, bin/console for interactive testing.

Daily commands: This is a library gem, not a runnable application. Use in your own project by adding gem 'ruby-openai' to Gemfile, then: client = OpenAI::Client.new(api_key: ENV['OPENAI_API_KEY']). For development, run tests with: bundle exec rspec. Linting with: bundle exec rubocop.

• lib/openai/client.rb: Main entry point; instantiates and delegates to all feature modules (Chat, Assistants, Realtime, etc.)
• lib/openai/http.rb: Core HTTP abstraction using Faraday; handles authentication, headers, timeouts, and all API requests
• lib/openai/stream.rb: Implements Server-Sent Events (SSE) streaming for real-time chat and response APIs
• lib/openai/realtime.rb: WebRTC and websocket support for OpenAI Realtime API (newest feature)
• lib/openai/assistants.rb: Assistants API implementation with thread/message/run management
• lib/openai/responses.rb: Newer async Responses API for long-running inference tasks
• ruby-openai.gemspec: Gem metadata and dependency declarations
• .circleci/config.yml: CI/CD pipeline; defines test matrix and deployment logic

New API endpoints: add methods to lib/openai/client.rb delegating to a new file lib/openai/[feature].rb following the pattern of lib/openai/assistants.rb. New HTTP features: modify lib/openai/http.rb. Streaming improvements: lib/openai/stream.rb. Tests go in spec/ mirroring the lib/ structure. Use CircleCI config (.circleci/config.yml) to verify changes.

OPENAI_API_KEY environment variable must be set or passed explicitly to OpenAI::Client.new (no default fallback). Streaming responses require handling Enumerator/blocks carefully in Ruby; see lib/openai/stream.rb for SSE parsing edge cases. Realtime API (WebRTC) requires additional setup beyond HTTP (websocket/event handling); check lib/openai/realtime.rb. Azure, Deepseek, Ollama, and Groq require different base_uri and header configurations (documented in README but easy to miss). Ruby version constraints may exist in gemspec; verify ruby-openai.gemspec for minimum version.

• Server-Sent Events (SSE) — Streaming chat and response APIs in this gem use SSE to send real-time token updates; understanding event parsing in lib/openai/stream.rb requires knowledge of SSE protocol
• Faraday Middleware Chain — lib/openai/http.rb uses Faraday middleware for logging, authentication, and error handling; customizing requests requires understanding middleware composition
• WebRTC and WebSocket APIs — Realtime API (lib/openai/realtime.rb) uses WebSocket for bi-directional communication; differs fundamentally from the HTTP request/response pattern used elsewhere
• Enumerator Pattern (Ruby Streams) — Streaming responses in this gem return Enumerator objects; understanding lazy evaluation and block iteration is essential for consuming streams without loading all data into memory
• Token Counting (BPE Tokenization) — Gem provides token counting utilities for cost estimation; understanding OpenAI's Byte-Pair Encoding (BPE) tokenization helps optimize prompt design
• Function Calling / Tool Use — lib/openai/chat.rb supports function calling where LLM returns structured tool invocations; core pattern for building agent systems and grounded AI applications
• Vector Embeddings and Semantic Search — Vector store modules (lib/openai/vector_store*.rb) manage embeddings for RAG; understanding vector similarity is prerequisite for building knowledge base integrations

• openai/openai-python — Official Python OpenAI SDK; ruby-openai mirrors its API design and supports the same endpoints
• alexrudall/anthropic — Sibling Ruby gem by same maintainer wrapping Anthropic Claude API with identical patterns and conventions
• rails/rails — Primary ecosystem for Ruby; ruby-openai integrates naturally into Rails apps via Gemfile and ActiveJob
• lostisland/faraday — Core dependency for HTTP abstraction; understanding Faraday middleware is crucial for customizing requests
• alexrudall/midjourney — Sibling Ruby gem for Midjourney API following same architectural patterns as ruby-openai

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for lib/openai/realtime.rb WebRTC implementation

The realtime.rb file handles WebRTC connections for the new Realtime API feature, but there are no corresponding test fixtures or specs visible in the cassettes directory (no realtime_*.yml files). This is a critical feature advertised in the README but lacks test coverage. New contributors can add VCR cassettes and spec tests to ensure WebRTC stream handling, connection lifecycle, and error cases are properly tested.

• [ ] Create spec/openai/realtime_spec.rb with test cases for WebRTC connection initialization
• [ ] Add VCR cassette fixtures in spec/fixtures/cassettes/ for realtime_connect.yml, realtime_send_message.yml, realtime_disconnect.yml
• [ ] Test error handling for malformed WebRTC frames and connection failures
• [ ] Add integration tests for streaming audio input/output through the Realtime API

Add missing test coverage for lib/openai/vector_store_files.rb and lib/openai/vector_store_file_batches.rb

Vector store functionality is implemented in the codebase but the spec/fixtures/cassettes/ directory has no vector_store_files_.yml or vector_store_file_batches_.yml test fixtures. These are important for RAG (Retrieval-Augmented Generation) workflows. Adding comprehensive tests will ensure file uploads, batch operations, and vector store management work correctly.

• [ ] Create spec/openai/vector_stores_spec.rb with tests for file operations (upload, delete, list)
• [ ] Create VCR cassettes: vector_store_files_upload.yml, vector_store_files_delete.yml, vector_store_file_batches_create.yml, vector_store_file_batches_cancel.yml
• [ ] Add tests for batch status polling and error handling for invalid file formats
• [ ] Test pagination for large vector store file listings

Implement missing request/response specs for lib/openai/stream.rb streaming behavior

The Stream class in lib/openai/stream.rb handles response streaming (used across Chat, Completions, and Realtime APIs), but there are no specific stream_*.yml cassettes or detailed streaming specs. This is critical for ensuring chunked responses, stream termination, and partial JSON parsing work correctly across all streaming endpoints.

• [ ] Create spec/openai/stream_spec.rb with tests for chunk parsing and event emission
• [ ] Add VCR cassettes: stream_chat_completion.yml, stream_completion.yml, stream_error_handling.yml
• [ ] Test incomplete/malformed JSON in stream chunks (edge case handling)
• [ ] Add benchmarks for streaming performance with large response payloads

• Add missing spec files for lib/openai/realtime.rb (WebRTC module) and lib/openai/responses.rb (Responses API) — follow the pattern in spec/ for existing modules like assistants_spec.rb
• Document error handling patterns: create examples/error_handling.rb showing rescue blocks for OpenAI::Error exceptions across different API calls (currently documented loosely in README)
• Add streaming examples for vector store file batch operations (lib/openai/vector_store_file_batches.rb) — parallel with existing examples/ for Chat streaming

The ruby-openai library has a solid security posture with proper vulnerability disclosure processes and CI/CD integration. Main security concerns relate to the sensitive nature of API key handling and file operations inherent to the library's purpose. The library properly uses GitHub's private vulnerability reporting and has security documentation. Key recommendations focus on ensuring consuming applications properly handle credentials, validating file inputs securely, and maintaining dependency security. The incomplete visibility into actual implementation code and dependency versions prevents a higher security score. Regular security audits and dependency scanning through Dependabot should mitigate most risks.

• Medium · API Key Exposure Risk in Environment Variables — lib/openai/client.rb, lib/openai/http.rb, lib/openai/http_headers.rb. The codebase is an OpenAI API client library that handles authentication tokens and API keys. While no hardcoded secrets were found in the provided file structure, the nature of this library means it will process sensitive API credentials at runtime. If these credentials are not properly managed by consuming applications, there is risk of exposure in logs, error messages, or memory dumps. Fix: Ensure documentation clearly instructs users to: 1) Store API keys only in environment variables or secure vaults, 2) Never commit credentials to version control, 3) Implement request/response sanitization to prevent credential leakage in logs, 4) Use security headers and HTTPS for all API communications.
• Medium · WebRTC Realtime Implementation Security — lib/openai/realtime.rb. The library supports Realtime WebRTC conversations (mentioned in README). WebRTC implementations can have security implications including: unencrypted peer connections, STUN/TURN server selection, and data leak risks. The implementation details are not fully visible, but this is a sensitive feature. Fix: Ensure the WebRTC implementation: 1) Uses DTLS-SRTP for encryption, 2) Validates certificate pinning, 3) Properly handles connection termination, 4) Does not expose internal IP addresses through ICE candidates, 5) Has security audit documentation.
• Medium · File Upload/Stream Handling Security — lib/openai/audio.rb, lib/openai/files.rb, lib/openai/stream.rb, lib/openai/vector_store_files.rb. The library includes file operations (audio.rb, files.rb, vector_store_files.rb) which involve file uploads and streaming. Without seeing the implementation, there are potential risks around: file size validation, file type validation, path traversal, and temporary file cleanup. Fix: Implement strict file handling: 1) Validate file sizes before upload, 2) Whitelist allowed file types, 3) Sanitize file paths to prevent directory traversal, 4) Securely delete temporary files, 5) Use secure temporary directories, 6) Validate file content, not just extensions.
• Medium · Missing Dependency Vulnerability Information — Gemfile, Gemfile.lock. The Gemfile and Gemfile.lock content was not provided for analysis. This prevents verification of whether any direct or transitive dependencies have known security vulnerabilities. Fix: 1) Regularly run 'bundle audit' to check for vulnerable dependencies, 2) Keep all dependencies updated, 3) Use Dependabot (which appears to be configured) to track security updates, 4) Review and document rationale for dependency pinning or version constraints.
• Low · Missing SECURITY.md Completeness — SECURITY.md. The SECURITY.md file appears to be truncated in the provided snippet. The response process section is incomplete, which could leave users uncertain about vulnerability handling timelines. Fix: Complete the SECURITY.md document with: 1) Full response and patching timeline, 2) Security contact information, 3) Vulnerability disclosure timeline, 4) Information about security updates, 5) Links to security advisories.
• Low · Docker Security Best Practices — .devcontainer/Dockerfile, .devcontainer/docker-compose.yml. Development container is configured (.devcontainer/Dockerfile). While development containers are less critical, they should still follow security best practices. Fix: Review the Dockerfile for: 1) Use of specific base image versions (not 'latest'), 2) Non-root user execution, 3) Minimal layer count, 4) No hardcoded secrets, 5) Security scanning in CI/CD pipeline.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.