muse_spark

A zero-dependency Ruby client for Meta's Model API,
with first-class support for the Responses API and the Muse Spark model family.

Should you use this gem?

The Model API is wire-compatible with both OpenAI and Anthropic at the same base
URL. If you only need chat completions, you don't need this gem — point an
existing OpenAI-compatible Ruby client at https://api.meta.ai/v1 and you're done.

Reach for muse_spark when you want the Responses API specifically:

• Cross-turn reasoning replay, so tool loops keep the model's chain of thought
• Server-managed conversation state via previous_response_id
• Search grounding (web_search) and background execution
• Typed error classes and automatic retries with backoff
• No runtime dependencies, so nothing conflicts with your app's gems

Requirements

• Ruby >= 3.1
• No runtime dependencies

Installation

# Gemfile
gem "muse_spark"

Or:

gem install muse_spark

Getting an API key

1. Go to the Model API dashboard.
2. Open the API keys section and click Create API key.
3. Give it a descriptive name and copy it immediately — the key is shown only once.

Keys look like LLM|<id>|<secret>.

Setting your key

export MODEL_API_KEY="LLM|123456789|your-secret-here"

The client reads MODEL_API_KEY automatically:

client = MuseSpark::Client.new

Or pass it explicitly:

client = MuseSpark::Client.new(api_key: ENV.fetch("MODEL_API_KEY"))

Never commit keys. Use a separate key per application so you can revoke one
without disrupting the others.

Quickstart

require "muse_spark"

client = MuseSpark::Client.new

response = client.responses.create(input: "What is the capital of France?")

puts response.output_text
#=> The capital of France is **Paris**.

puts response.usage.total_tokens

Streaming

final = client.responses.stream(input: "Explain how neural networks learn.") do |event|
  print event.delta if event.text_delta?
end
puts
puts final.usage.output_tokens

Stream for long generations: non-streaming requests are subject to a server-side
time limit and fail with MuseSpark::GatewayTimeoutError if they run too long.

Events expose #type, #delta, #sequence_number, and predicates such as
#text_delta? and `#co