Class: Melaya::HitlAPI

Inherits:
Object
  • Object
show all
Defined in:
lib/melaya/hitl.rb

Overview

HITL (Human-in-the-Loop) API — list, approve, and reject pending tool-call approval requests generated by running agent pipelines.

Maps to /api/v1/private/hitl/*.

Examples:

pending = melaya.hitl.pending
pending.each do |req|
  melaya.hitl.approve(req["requestId"], comment: "Looks good")
end

# Bulk operations
melaya.hitl.bulk_decide(
  request_ids: ["r1", "r2"],
  decision: "approved",
  comment: "Batch OK"
)

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ HitlAPI

Returns a new instance of HitlAPI.



22
23
24
 
# File 'lib/melaya/hitl.rb', line 22

def initialize(http)
  @http = http
end

Instance Method Details

#approve(request_id, comment: nil) ⇒ Object

POST /api/v1/private/hitl/approvals/:requestId/approve Approve a pending HITL tool-call approval.

Parameters:

  • request_id (String)
  • comment (String, nil) (defaults to: nil) 


45
46
47
48
49
 
# File 'lib/melaya/hitl.rb', line 45

def approve(request_id, comment: nil)
  body = compact("comment" => comment)
  @http.post("/api/v1/private/hitl/approvals/#{enc(request_id)}/approve",
    body.empty? ? nil : body)
end

#bulk_decide(request_ids:, decision:, comment: nil) ⇒ Object

POST /api/v1/private/hitl/approvals/bulk Bulk approve or reject multiple pending tool calls in one call.

Parameters:

  • request_ids (Array<String>)
  • decision (String) —

    "approved" or "rejected"

  • comment (String, nil) (defaults to: nil) 


66
67
68
69
70
71
72
73
 
# File 'lib/melaya/hitl.rb', line 66

def bulk_decide(request_ids:, decision:, comment: nil)
  body = compact(
    "requestIds" => request_ids,
    "decision"   => decision,
    "comment"    => comment
  )
  @http.post("/api/v1/private/hitl/approvals/bulk", body)
end

#history(limit: nil, offset: nil) ⇒ Object

GET /api/v1/private/hitl/approvals/history List historical (decided) HITL approval records.

Parameters:

  • limit (Integer, nil) (defaults to: nil)
  • offset (Integer, nil) (defaults to: nil) 


36
37
38
39
 
# File 'lib/melaya/hitl.rb', line 36

def history(limit: nil, offset: nil)
  @http.get("/api/v1/private/hitl/approvals/history",
    compact("limit" => limit, "offset" => offset))
end

#pending ⇒ Object

GET /api/v1/private/hitl/approvals/pending List all pending HITL tool-call approvals for the authenticated user.



28
29
30
 
# File 'lib/melaya/hitl.rb', line 28

def pending
  @http.get("/api/v1/private/hitl/approvals/pending")
end

#reject(request_id, comment: nil) ⇒ Object

POST /api/v1/private/hitl/approvals/:requestId/reject Reject a pending HITL tool-call approval.

Parameters:

  • request_id (String)
  • comment (String, nil) (defaults to: nil) 


55
56
57
58
59
 
# File 'lib/melaya/hitl.rb', line 55

def reject(request_id, comment: nil)
  body = compact("comment" => comment)
  @http.post("/api/v1/private/hitl/approvals/#{enc(request_id)}/reject",
    body.empty? ? nil : body)
end

#run_messages(run_id, limit: nil, cursor: nil) ⇒ Object

GET /api/v1/private/hitl/runs/:runId/messages Get paginated messages for a pipeline run.

Parameters:

  • limit (Integer, nil) (defaults to: nil)
  • cursor (String, nil) (defaults to: nil) 


93
94
95
96
 
# File 'lib/melaya/hitl.rb', line 93

def run_messages(run_id, limit: nil, cursor: nil)
  @http.get("/api/v1/private/hitl/runs/#{enc(run_id)}/messages",
    compact("limit" => limit, "cursor" => cursor))
end

#run_tool_calls(run_id) ⇒ Object

GET /api/v1/private/hitl/runs/:runId/tool-calls Get all tool calls for a pipeline run.



100
101
102
 
# File 'lib/melaya/hitl.rb', line 100

def run_tool_calls(run_id)
  @http.get("/api/v1/private/hitl/runs/#{enc(run_id)}/tool-calls")
end

#run_tool_stats(run_id) ⇒ Object

GET /api/v1/private/hitl/runs/:runId/tool-stats Get tool-call statistics for a specific pipeline run.



79
80
81
 
# File 'lib/melaya/hitl.rb', line 79

def run_tool_stats(run_id)
  @http.get("/api/v1/private/hitl/runs/#{enc(run_id)}/tool-stats")
end

#run_tool_stats_by_agent(run_id) ⇒ Object

GET /api/v1/private/hitl/runs/:runId/tool-stats/by-agent Get tool-call stats broken down by agent for a run.



85
86
87
 
# File 'lib/melaya/hitl.rb', line 85

def run_tool_stats_by_agent(run_id)
  @http.get("/api/v1/private/hitl/runs/#{enc(run_id)}/tool-stats/by-agent")
end