Class: FetchHive::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/fetch_hive/client.rb

Overview

Idiomatic facade over the OpenAPI-generated code.

Usage:

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

# Non-streaming prompt
result = client.invoke_prompt(deployment: "my-prompt", inputs: { name: "Alice" })
puts result["response"]

# Streaming agent
client.invoke_agent_stream(agent: "my-agent", message: "Hello") 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

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.fetchhive.com/v1"

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: 120) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String, nil) (defaults to: nil) —

    Bearer token. Falls back to FETCH_HIVE_API_KEY env var.

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    Override the API base URL.

  • timeout (Integer) (defaults to: 120) —

    Request timeout in seconds (default: 120).

Raises:

  • (ArgumentError) 


33
34
35
36
37
38
39
40
 
# File 'lib/fetch_hive/client.rb', line 33

def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: 120)
  resolved = api_key || ENV["FETCH_HIVE_API_KEY"]
  raise ArgumentError, "api_key is required. Pass it explicitly or set FETCH_HIVE_API_KEY." if resolved.nil? || resolved.empty?

  @api_key  = resolved
  @base_url = base_url.to_s.sub(%r{/+\z}, "")
  @timeout  = timeout
end

Instance Method Details

#clear_agent_chat_messages(workspace_id:, agent_id:, chat_id:) ⇒ Object 



216
217
218
 
# File 'lib/fetch_hive/client.rb', line 216

def clear_agent_chat_messages(workspace_id:, agent_id:, chat_id:)
  request("PATCH", "/public/workspaces/#{workspace_id}/agents/#{agent_id}/chats/#{chat_id}/clear_messages", {})
end

#create_agent(workspace_id:, agent:) ⇒ Object 



188
189
190
 
# File 'lib/fetch_hive/client.rb', line 188

def create_agent(workspace_id:, agent:)
  post("/public/workspaces/#{workspace_id}/agents", { agent: agent })
end

#create_agent_chat(workspace_id:, agent_id:, chat:) ⇒ Object 



204
205
206
 
# File 'lib/fetch_hive/client.rb', line 204

def create_agent_chat(workspace_id:, agent_id:, chat:)
  post("/public/workspaces/#{workspace_id}/agents/#{agent_id}/chats", { chat: chat })
end

#create_knowledge_base(workspace_id:, knowledge_base:) ⇒ Object 



140
141
142
 
# File 'lib/fetch_hive/client.rb', line 140

def create_knowledge_base(workspace_id:, knowledge_base:)
  post("/public/workspaces/#{workspace_id}/knowledge_bases", { knowledge_base: knowledge_base })
end

#create_knowledge_base_item(workspace_id:, knowledge_base_id:, knowledge_base_item:) ⇒ Object 



164
165
166
 
# File 'lib/fetch_hive/client.rb', line 164

def create_knowledge_base_item(workspace_id:, knowledge_base_id:, knowledge_base_item:)
  post("/public/workspaces/#{workspace_id}/knowledge_bases/#{knowledge_base_id}/items", { knowledge_base_item: knowledge_base_item })
end

#delete_agent(workspace_id:, id:) ⇒ Object 



196
197
198
 
# File 'lib/fetch_hive/client.rb', line 196

def delete_agent(workspace_id:, id:)
  request("DELETE", "/public/workspaces/#{workspace_id}/agents/#{id}")
end

#delete_agent_chat(workspace_id:, agent_id:, chat_id:) ⇒ Object 



212
213
214
 
# File 'lib/fetch_hive/client.rb', line 212

def delete_agent_chat(workspace_id:, agent_id:, chat_id:)
  request("DELETE", "/public/workspaces/#{workspace_id}/agents/#{agent_id}/chats/#{chat_id}")
end

#delete_knowledge_base(workspace_id:, id:) ⇒ Object 



148
149
150
 
# File 'lib/fetch_hive/client.rb', line 148

def delete_knowledge_base(workspace_id:, id:)
  request("DELETE", "/public/workspaces/#{workspace_id}/knowledge_bases/#{id}")
end

#delete_knowledge_base_item(workspace_id:, knowledge_base_id:, id:) ⇒ Object 



172
173
174
 
# File 'lib/fetch_hive/client.rb', line 172

def delete_knowledge_base_item(workspace_id:, knowledge_base_id:, id:)
  request("DELETE", "/public/workspaces/#{workspace_id}/knowledge_bases/#{knowledge_base_id}/items/#{id}")
end

#get_agent(workspace_id:, id:) ⇒ Object 



184
185
186
 
# File 'lib/fetch_hive/client.rb', line 184

def get_agent(workspace_id:, id:)
  request("GET", "/public/workspaces/#{workspace_id}/agents/#{id}")
end

#get_agent_chat(workspace_id:, agent_id:, chat_id:) ⇒ Object 



200
201
202
 
# File 'lib/fetch_hive/client.rb', line 200

def get_agent_chat(workspace_id:, agent_id:, chat_id:)
  request("GET", "/public/workspaces/#{workspace_id}/agents/#{agent_id}/chats/#{chat_id}")
end

#get_knowledge_base(workspace_id:, id:) ⇒ Object 



136
137
138
 
# File 'lib/fetch_hive/client.rb', line 136

def get_knowledge_base(workspace_id:, id:)
  request("GET", "/public/workspaces/#{workspace_id}/knowledge_bases/#{id}")
end

#get_knowledge_base_item(workspace_id:, knowledge_base_id:, id:) ⇒ Object 



160
161
162
 
# File 'lib/fetch_hive/client.rb', line 160

def get_knowledge_base_item(workspace_id:, knowledge_base_id:, id:)
  request("GET", "/public/workspaces/#{workspace_id}/knowledge_bases/#{knowledge_base_id}/items/#{id}")
end

#get_request(id:) ⇒ Object

── Public resources ────────────────────────────────────────────────────────



128
129
130
 
# File 'lib/fetch_hive/client.rb', line 128

def get_request(id:)
  request("GET", "/public/requests/#{id}")
end

#invoke_agent(agent:, message:, thread_id: nil, user: nil, metadata: nil, messages: nil, image_urls: nil, attachments: nil, known_artifact_refs: nil, artifact_refs: nil) ⇒ Object

Send a message to an agent and return the full response hash.



84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/fetch_hive/client.rb', line 84

def invoke_agent(agent:, message:, thread_id: nil, user: nil, metadata: nil, messages: nil, image_urls: nil, attachments: nil, known_artifact_refs: nil, artifact_refs: nil)
  body = { agent: agent, message: message, streaming: false }
  body[:thread_id]  = thread_id  if thread_id
  body[:user]       = user       if user
  body[:metadata] = metadata if metadata
  body[:messages]   = messages   if messages
  body[:attachments] = attachments || image_urls if attachments || image_urls
  body[:known_artifact_refs] = known_artifact_refs if known_artifact_refs
  body[:artifact_refs] = artifact_refs if artifact_refs
  post("/agent/invoke", body)
end

#invoke_agent_stream(agent:, message:, thread_id: nil, user: nil, metadata: nil, messages: nil, image_urls: nil, attachments: nil, known_artifact_refs: nil, artifact_refs: nil, &block) ⇒ Object

Send a message to an agent and stream SSE events. Yields each parsed event hash. Returns an Enumerator when no block given.



98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/fetch_hive/client.rb', line 98

def invoke_agent_stream(agent:, message:, thread_id: nil, user: nil, metadata: nil, messages: nil, image_urls: nil, attachments: nil, known_artifact_refs: nil, artifact_refs: nil, &block)
  body = { agent: agent, message: message, streaming: true }
  body[:thread_id]  = thread_id  if thread_id
  body[:user]       = user       if user
  body[:metadata] = metadata if metadata
  body[:messages]   = messages   if messages
  body[:attachments] = attachments || image_urls if attachments || image_urls
  body[:known_artifact_refs] = known_artifact_refs if known_artifact_refs
  body[:artifact_refs] = artifact_refs if artifact_refs
  post_stream("/agent/invoke", body, &block)
end

#invoke_hive_agent(hive_agent:, objective:, callback_url:, sources: nil, metadata: nil) ⇒ Object

Start a Hive Agent run asynchronously. Requires a callback URL.

Raises:

  • (ArgumentError) 


113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/fetch_hive/client.rb', line 113

def invoke_hive_agent(hive_agent:, objective:, callback_url:, sources: nil, metadata: nil)
  raise ArgumentError, "callback_url is required for Hive Agent invocation" if callback_url.nil? || callback_url.to_s.strip.empty?

  body = {
    hive_agent: hive_agent,
    objective: objective,
    async: { enabled: true, callback_url: callback_url }
  }
  body[:sources] = sources if sources
  body[:metadata] = metadata if metadata
  post("/hive-agent/invoke", body)
end

#invoke_prompt(deployment:, variant: nil, inputs: nil, user: nil, metadata: nil) ⇒ Object

Invoke a prompt deployment and return the full response hash.



45
46
47
48
49
50
51
52
 
# File 'lib/fetch_hive/client.rb', line 45

def invoke_prompt(deployment:, variant: nil, inputs: nil, user: nil, metadata: nil)
  body = { deployment: deployment, streaming: false }
  body[:variant] = variant if variant
  body[:inputs]  = inputs  if inputs
  body[:user]    = user    if user
  body[:metadata] = metadata if metadata
  post("/prompt/invoke", body)
end

#invoke_prompt_stream(deployment:, variant: nil, inputs: nil, user: nil, metadata: nil, &block) ⇒ Object

Invoke a prompt deployment and stream SSE events. Yields each parsed event hash. Returns an Enumerator when no block given.



56
57
58
59
60
61
62
63
 
# File 'lib/fetch_hive/client.rb', line 56

def invoke_prompt_stream(deployment:, variant: nil, inputs: nil, user: nil, metadata: nil, &block)
  body = { deployment: deployment, streaming: true }
  body[:variant] = variant if variant
  body[:inputs]  = inputs  if inputs
  body[:user]    = user    if user
  body[:metadata] = metadata if metadata
  post_stream("/prompt/invoke", body, &block)
end

#invoke_workflow(deployment:, variant: nil, inputs: nil, async_mode: false, callback_url: nil, user: nil, metadata: nil) ⇒ Object

Invoke a workflow deployment (sync or async).



68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/fetch_hive/client.rb', line 68

def invoke_workflow(deployment:, variant: nil, inputs: nil, async_mode: false, callback_url: nil, user: nil, metadata: nil)
  body = { deployment: deployment }
  body[:variant] = variant if variant
  body[:inputs]  = inputs  if inputs
  body[:user]    = user    if user
  body[:metadata] = metadata if metadata
  if async_mode
    body[:async] = { enabled: true }
    body[:async][:callback_url] = callback_url if callback_url
  end
  post("/workflow/invoke", body)
end

#list_agent_chat_messages(workspace_id:, agent_id:, chat_id:) ⇒ Object 



220
221
222
 
# File 'lib/fetch_hive/client.rb', line 220

def list_agent_chat_messages(workspace_id:, agent_id:, chat_id:)
  request("GET", "/public/workspaces/#{workspace_id}/agents/#{agent_id}/chats/#{chat_id}/messages")
end

#list_agents(workspace_id:) ⇒ Object 



180
181
182
 
# File 'lib/fetch_hive/client.rb', line 180

def list_agents(workspace_id:)
  request("GET", "/public/workspaces/#{workspace_id}/agents")
end

#list_knowledge_base_items(workspace_id:, knowledge_base_id:) ⇒ Object 



156
157
158
 
# File 'lib/fetch_hive/client.rb', line 156

def list_knowledge_base_items(workspace_id:, knowledge_base_id:)
  request("GET", "/public/workspaces/#{workspace_id}/knowledge_bases/#{knowledge_base_id}/items")
end

#list_knowledge_bases(workspace_id:) ⇒ Object 



132
133
134
 
# File 'lib/fetch_hive/client.rb', line 132

def list_knowledge_bases(workspace_id:)
  request("GET", "/public/workspaces/#{workspace_id}/knowledge_bases")
end

#regenerate_knowledge_base_item(workspace_id:, knowledge_base_id:, id:) ⇒ Object 



176
177
178
 
# File 'lib/fetch_hive/client.rb', line 176

def regenerate_knowledge_base_item(workspace_id:, knowledge_base_id:, id:)
  post("/public/workspaces/#{workspace_id}/knowledge_bases/#{knowledge_base_id}/items/#{id}/regenerate", {})
end

#search_knowledge_base(workspace_id:, id:, **params) ⇒ Object 



152
153
154
 
# File 'lib/fetch_hive/client.rb', line 152

def search_knowledge_base(workspace_id:, id:, **params)
  post("/public/workspaces/#{workspace_id}/knowledge_bases/#{id}/search", params)
end

#update_agent(workspace_id:, id:, agent:) ⇒ Object 



192
193
194
 
# File 'lib/fetch_hive/client.rb', line 192

def update_agent(workspace_id:, id:, agent:)
  request("PATCH", "/public/workspaces/#{workspace_id}/agents/#{id}", { agent: agent })
end

#update_agent_chat(workspace_id:, agent_id:, chat_id:, chat:) ⇒ Object 



208
209
210
 
# File 'lib/fetch_hive/client.rb', line 208

def update_agent_chat(workspace_id:, agent_id:, chat_id:, chat:)
  request("PATCH", "/public/workspaces/#{workspace_id}/agents/#{agent_id}/chats/#{chat_id}", { chat: chat })
end

#update_knowledge_base(workspace_id:, id:, knowledge_base:) ⇒ Object 



144
145
146
 
# File 'lib/fetch_hive/client.rb', line 144

def update_knowledge_base(workspace_id:, id:, knowledge_base:)
  request("PATCH", "/public/workspaces/#{workspace_id}/knowledge_bases/#{id}", { knowledge_base: knowledge_base })
end

#update_knowledge_base_item(workspace_id:, knowledge_base_id:, id:, knowledge_base_item:) ⇒ Object 



168
169
170
 
# File 'lib/fetch_hive/client.rb', line 168

def update_knowledge_base_item(workspace_id:, knowledge_base_id:, id:, knowledge_base_item:)
  request("PATCH", "/public/workspaces/#{workspace_id}/knowledge_bases/#{knowledge_base_id}/items/#{id}", { knowledge_base_item: knowledge_base_item })
end