muse_spark Ruby gem

# muse_spark

A zero-dependency Ruby client for [Meta's Model API](https://dev.meta.ai/docs/),
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

```ruby
# Gemfile
gem "muse_spark"
```

Or:

```bash
gem install muse_spark
```

## Getting an API key

1. Go to the [Model API dashboard](https://dev.meta.ai/).
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

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

The client reads `MODEL_API_KEY` automatically:

```ruby
client = MuseSpark::Client.new
```

Or pass it explicitly:

```ruby
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

```ruby
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

```ruby
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