fetch_hive

Official Ruby SDK for Fetch Hive — invoke AI prompts, workflows, and agents from your application.

Installation

Add to your Gemfile:

gem "fetch_hive", "~> 0.2.6"

Then run:

bundle install

Or install directly:

gem install fetch_hive

Quick start

require "fetch_hive"

client = FetchHive::Client.new(api_key: ENV["FETCH_HIVE_API_KEY"])

Get your API key from the Fetch Hive dashboard.

Invoke a prompt

result = client.invoke_prompt(
  deployment: "my-prompt",
  inputs: { name: "Alice", topic: "machine learning" },
  metadata: {}
)
puts result["response"]

Invoke a prompt (streaming)

client.invoke_prompt_stream(deployment: "my-prompt", inputs: { name: "Alice" }) do |chunk|
  case chunk["type"]
  when "response" then print chunk["response"]
  when "usage"    then puts "\nUsage: #{chunk['usage']}"
  end
end

Invoke a workflow

run = client.invoke_workflow(
  deployment: "my-workflow",
  inputs: { customer_id: "42" },
  metadata: {}
)
puts run["status"], run["output"]

Invoke a workflow (async)

run = client.invoke_workflow(
  deployment: "my-workflow",
  inputs: { customer_id: "42" },
  async_mode: true,
  callback_url: "https://example.com/webhook"
)
puts "Queued: #{run['run_id']}"

Invoke an agent

reply = client.invoke_agent(
  agent: "my-agent",
  message: "What is the weather in London?",
  metadata: {}
)
puts reply["response"]

Metadata

Pass optional metadata on prompt, workflow, or agent invokes to attach flat audit fields for log display and filtering. Metadata values must be strings, numbers, booleans, or nil.

Invoke an agent (streaming)

client.invoke_agent_stream(
  agent: "my-agent",
  message: "What is the weather in London?",
  thread_id: "session-abc123"  # optional — persist conversation history
) do |chunk|
  case chunk["type"]
  when "response" then print chunk["response"]
  when "tool"     then puts "\nCalling tool: #{chunk['tool']}"
  when "usage"    then puts "\nUsage: #{chunk['usage']}"
  end
end

Multimodal (image) inputs

result = client.invoke_agent(
  agent: "vision-agent",
  message: "Describe this image",
  image_urls: ["https://example.com/photo.jpg"]
)
puts result["response"]

Authentication

Pass the API key to the constructor or set the environment variable:

export FETCH_HIVE_API_KEY=fhk_...

client = FetchHive::Client.new  # picks up FETCH_HIVE_API_KEY automatically

Configuration

Option	Default	Description
`api_key`	`ENV["FETCH_HIVE_API_KEY"]`	Bearer token from the Fetch Hive dashboard
`base_url`	`https://api.fetchhive.com/v1`	Override the API base URL
`timeout`	`120`	Request timeout in seconds

Version

0.2.6

License

MIT — see LICENSE.