SDK quickstart: Ruby

The official openai Ruby gem points cleanly at our endpoint. Compatible with Rails, Sidekiq, or plain Ruby scripts.

Install

# Gemfile
gem "openai", "~> 8"
# or for an older established client:
# gem "ruby-openai", "~> 8"

Hello world

require "openai"

client = OpenAI::Client.new(
  base_url: "https://api.greenjoules.cloud/v1",
  access_token: ENV["JC_API_KEY"],
)

response = client.chat.completions.create(
  model: "auto",
  messages: [{ role: "user", content: "hi" }],
)

puts response.choices[0].message.content

Streaming

client.chat.completions.stream(
  model: "auto",
  messages: [{ role: "user", content: "tell me a story" }],
) do |chunk|
  print chunk.choices[0].delta.content.to_s
end

Embeddings

r = client.embeddings.create(
  model: "text-embedding-3-small",
  input: ["a", "b"],
)
r.data.each { |d| puts "dim=#{d.embedding.length}" }

Joule headers in Rails

The official gem returns the raw HTTP response on each call. Capture and log it:

response = client.chat.completions.create_with_raw_response(...)
parsed   = response.parse
Rails.logger.info "joules: #{response.http_response['x-energy-joules']}"
render json: parsed.choices[0].message

Sidekiq pattern

class EnergyMeteredJob
  include Sidekiq::Worker
  def perform(prompt)
    r = OPENAI.chat.completions.create_with_raw_response(
      model: "auto",
      messages: [{role: "user", content: prompt}],
    )
    EnergyLedger.record(
      joules: r.http_response["x-energy-joules"].to_f,
      tier:   r.http_response["x-tier"],
      job_id: jid,
    )
  end
end

Errors

begin
  client.chat.completions.create(...)
rescue OpenAI::Errors::APIStatusError => e
  case e.status
  when 402 then BalanceMailer.low_balance.deliver_later
  when 429 then EnergyBudgetAlert.notify(workload: "rag-ask")
  else raise
  end
end

Next

For object store via the aws-sdk-s3 gem, see Migrate from AWS S3. The gem works against our endpoint with no special configuration beyond endpoint:.