class RubyLLM::Context

A Context is an isolated configuration scope. It offers the same entry points as the top-level RubyLLM module but reads from its own Configuration copy instead of the global one, which suits multi-tenant applications and per-request overrides.

Contexts are created with RubyLLM.context:

ctx = RubyLLM.context do |config|
  config.openai_api_key = ENV.fetch('TENANT_OPENAI_API_KEY')
  config.request_timeout = 180
end

ctx.chat.ask "Explain Ruby blocks."
ctx.paint("A paper boat in the rain").save("boat.png")
ctx.transcribe("meeting.wav").text

The global configuration is left untouched.

Batch submission uses each chat’s own configuration (a chat carries the config it was built with), so there is no context entry point for it. To look up an existing batch, where no chats carry the config, pass a context to Batch.find:

RubyLLM::Batch.find(id, provider: :anthropic, context: ctx)

Public Instance Methods

animate (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 80
def animate(*args, **kwargs, &)
  Video.animate(*args, **kwargs, context: self, &)
end

Generates a video using this context’s configuration, blocking until it is ready. Accepts the same arguments as RubyLLM.animate.

animate_later (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 86
def animate_later(*args, **kwargs, &)
  VideoJob.animate_later(*args, **kwargs, context: self, &)
end

Submits a video generation job using this context’s configuration. Accepts the same arguments as RubyLLM.animate_later.

cache (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 147
def cache(*args, **kwargs, &)
  CachedContent.create(*args, **kwargs, context: self, &)
end

Creates a provider-side prompt cache using this context’s configuration. Accepts the same arguments as RubyLLM.cache.

chat (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 38
def chat(*args, **kwargs, &)
  Chat.new(*args, **kwargs, context: self, &)
end

Creates a new Chat that uses this context’s configuration. Accepts the same arguments as RubyLLM.chat.

count_tokens (text, model: nil, provider: nil)

Source

# File lib/ruby_llm/context.rb, line 44
def count_tokens(text, model: nil, provider: nil)
  chat(model:, provider:).count_tokens(text)
end

Counts tokens using this context’s configuration. Accepts the same arguments as RubyLLM.count_tokens.

download (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 141
def download(*args, **kwargs, &)
  UploadedFile.download(*args, **kwargs, context: self, &)
end

Downloads a provider-hosted file using this context’s configuration. Accepts the same arguments as RubyLLM.download.

embed (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 62
def embed(*args, **kwargs, &)
  Embedding.embed(*args, **kwargs, context: self, &)
end

Generates embeddings using this context’s configuration. Accepts the same arguments as RubyLLM.embed.

embed_later (text, model: nil, provider: nil, dimensions: nil)

Source

# File lib/ruby_llm/context.rb, line 68
def embed_later(text, model: nil, provider: nil, dimensions: nil)
  EmbeddingRequest.new(text, model:, provider:, dimensions:, context: self)
end

Stages an embedding request using this context’s configuration. Accepts the same arguments as RubyLLM.embed_later.

moderate (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 92
def moderate(*args, **kwargs, &)
  Moderation.moderate(*args, **kwargs, context: self, &)
end

Runs content moderation using this context’s configuration. Accepts the same arguments as RubyLLM.moderate.

ocr (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 123
def ocr(*args, **kwargs, &)
  OCR.ocr(*args, **kwargs, context: self, &)
end

Extracts document text using this context’s configuration. Accepts the same arguments as RubyLLM.ocr.

paint (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 74
def paint(*args, **kwargs, &)
  Image.paint(*args, **kwargs, context: self, &)
end

Generates an image using this context’s configuration. Accepts the same arguments as RubyLLM.paint.

rerank (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 129
def rerank(*args, **kwargs, &)
  Rerank.rerank(*args, **kwargs, context: self, &)
end

Ranks documents using this context’s configuration. Accepts the same arguments as RubyLLM.rerank.

research (*args, **kwargs)

Source

# File lib/ruby_llm/context.rb, line 98
def research(*args, **kwargs)
  ResearchJob.research(*args, **kwargs, context: self)
end

Runs hosted research using this context’s configuration. Accepts the same arguments as RubyLLM.research.

research_later (*args, **kwargs)

Source

# File lib/ruby_llm/context.rb, line 104
def research_later(*args, **kwargs)
  ResearchJob.research_later(*args, **kwargs, context: self)
end

Submits hosted research using this context’s configuration. Accepts the same arguments as RubyLLM.research_later.

speak (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 111
def speak(*args, **kwargs, &)
  Speech.speak(*args, **kwargs, context: self, &)
end

Generates speech audio using this context’s configuration. Given a block, yields SpeechChunk objects and returns the complete Speech. Accepts the same arguments as RubyLLM.speak.

tokenize (*args, **kwargs)

Source

# File lib/ruby_llm/context.rb, line 50
def tokenize(*args, **kwargs)
  Tokenization.tokenize(*args, **kwargs, context: self)
end

Tokenizes plain text using this context’s configuration. Accepts the same arguments as RubyLLM.tokenize.

transcribe (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 117
def transcribe(*args, **kwargs, &)
  Transcription.transcribe(*args, **kwargs, context: self, &)
end

Transcribes audio using this context’s configuration. Accepts the same arguments as RubyLLM.transcribe.

upload (*args, **kwargs, &)

Source

# File lib/ruby_llm/context.rb, line 135
def upload(*args, **kwargs, &)
  UploadedFile.upload(*args, **kwargs, context: self, &)
end

Uploads a file to a provider using this context’s configuration. Accepts the same arguments as RubyLLM.upload.

workflow (name, id: nil, metadata: nil, &)

Source

# File lib/ruby_llm/context.rb, line 56
def workflow(name, id: nil, metadata: nil, &)
  Workflow.new(name, id:, metadata:, config: config).run(&)
end

Runs a named workflow using this context’s instrumenter. Accepts the same arguments as RubyLLM.workflow.