> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ejecutar con el SDK de Ruby

> Invoca un deployment de prompt desde Ruby con la gema fetch_hive

# Ejecutar con el SDK de Ruby

Usa la gema oficial `fetch_hive` cuando quieras invocar un deployment de prompt desde Ruby. El SDK envuelve el endpoint público [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) con ayudantes idiomáticos, maneja la autenticación y analiza las respuestas en streaming convirtiéndolas en hashes producidos.

## Instalación

Agrega a tu `Gemfile`:

```ruby theme={null}
gem "fetch_hive"
```

Luego ejecuta:

```bash theme={null}
bundle install
```

O instálala directamente:

```bash theme={null}
gem install fetch_hive
```

La gema usa `faraday` por debajo y admite Ruby 3.0+.

## Autenticación

Configura la variable de entorno `FETCH_HIVE_API_KEY` con tu clave de API del workspace (el cliente la lee automáticamente):

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```ruby theme={null}
require "fetch_hive"

client = FetchHive::Client.new
```

O pasa la clave explícitamente:

```ruby theme={null}
client = FetchHive::Client.new(api_key: "fhk_...")
```

Consulta [API Keys](../workspace/api-keys) para saber cómo crear y rotar claves.

## Ejemplo básico

Invoca un deployment de prompt y lee la respuesta final:

```ruby theme={null}
require "fetch_hive"

client = FetchHive::Client.new

result = client.invoke_prompt(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { text: "Fetch Hive helps teams ship AI products faster." }
)

puts result["response"]
```

`invoke_prompt` se bloquea hasta que el prompt se completa y devuelve el cuerpo JSON analizado como un hash. Consulta la [forma de respuesta sin streaming](../api-reference/prompts/invoke#response).

## Referencia del método

| Palabra clave | Tipo     | Requerido | Descripción                                                                                                                                      |
| ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deployment`  | `String` | Sí        | El nombre del deployment de prompt                                                                                                               |
| `variant`     | `String` | No        | El nombre de la variante del deployment                                                                                                          |
| `inputs`      | `Hash`   | No        | Pares clave-valor para las variables del prompt                                                                                                  |
| `user`        | `String` | No        | Identificador opaco de quien llama, expuesto en [User Tracking](../user-tracking/overview)                                                       |
| `metadata`    | `Hash`   | No        | Metadata plana definida por quien llama, para auditoría y filtrado de registros. Consulta [Metadata de invoke](../user-tracking/invoke-metadata) |

El SDK inyecta `streaming: false` para `invoke_prompt`. Para transmitir, usa `invoke_prompt_stream` (a continuación).

## Manejo de la respuesta

```ruby theme={null}
result = client.invoke_prompt(deployment: "my-prompt", variant: "default")

puts result["response"]      # final text
puts result["model"]         # model identifier
puts result["usage"]         # token usage breakdown
puts result["request_id"]    # use this to look up the run in Logs
```

## Streaming

Usa `invoke_prompt_stream` para recibir Server-Sent Events a medida que llegan. El método produce cada hash de evento analizado al bloque:

```ruby theme={null}
client.invoke_prompt_stream(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { text: "Fetch Hive helps teams ship AI products faster." }
) do |chunk|
  case chunk["type"]
  when "response"
    print chunk["response"]
    $stdout.flush
  when "usage"
    puts "\n\nUsage: #{chunk['usage']}"
  end
end
```

La transmisión produce los mismos tipos de evento documentados en [Invoke Prompt → Response](../api-reference/prompts/invoke#response): `reasoning`, `response`, un evento `usage` final o un evento `error` si el proveedor falla durante la transmisión.

Si omites el bloque, el método devuelve un `Enumerator` que puedes pasar:

```ruby theme={null}
enum = client.invoke_prompt_stream(deployment: "my-prompt", variant: "default")
enum.each { |chunk| handle(chunk) }
```

## Configuración

| Opción     | Predeterminado                 | Descripción                         |
| ---------- | ------------------------------ | ----------------------------------- |
| `api_key`  | `ENV["FETCH_HIVE_API_KEY"]`    | Token bearer del dashboard          |
| `base_url` | `https://api.fetchhive.com/v1` | Sobrescribe la URL base de la API   |
| `timeout`  | `120`                          | Timeout de la solicitud en segundos |

```ruby theme={null}
client = FetchHive::Client.new(
  api_key: "fhk_...",
  base_url: "https://api.fetchhive.com/v1",
  timeout: 60
)
```

## Errores

Las respuestas distintas a 2xx lanzan un `RuntimeError` con el código de estado y el cuerpo. Rescátalas si necesitas manejar fallos:

```ruby theme={null}
begin
  result = client.invoke_prompt(deployment: "my-prompt", variant: "default")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end
```

Consulta [Errors and Rate Limits](../api-reference/errors-and-rate-limits) para el significado de los códigos de estado.

## Enlaces

* [Gem on RubyGems](https://rubygems.org/gems/fetch_hive)
* [Source on GitHub](https://github.com/Fetch-Hive/ruby-sdk)

## Siguientes pasos

* [Ejecutar con API](./run-with-api) - El mismo flujo con cURL
* [Ejecutar con el SDK de Python](./run-with-python-sdk)
* [Ejecutar con el SDK de Node.js](./run-with-nodejs-sdk)
* [Ejecutar con el SDK de PHP](./run-with-php-sdk)
* [Invoke Prompt](../api-reference/prompts/invoke) - Referencia completa del endpoint