Class: Melaya::PipelinesAPI

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

Overview

Pipelines API — overview dashboard, pipeline run listing, traces, and cron-based scheduling.

Maps to:

/api/v1/private/overview/*         — dashboard + run listing
/api/v1/private/runs/:id/traces/*  — distributed traces
/api/v1/private/pipeline-schedule  — cron scheduling
/api/v1/version                    — server version (public)

Examples:

runs = melaya.pipelines.list(project: "my-project", limit: 20)
melaya.pipelines.upsert_schedule("my-project", "nightly-report",
  cron: "0 2 * * *")

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ PipelinesAPI

Returns a new instance of PipelinesAPI.



18
19
20
 
# File 'lib/melaya/pipelines.rb', line 18

def initialize(http)
  @http = http
end

Instance Method Details

#build_with_ai(brief) ⇒ Hash

POST /api/v1/private/ai/build-pipeline/sync Generate a pipeline config from a natural-language brief using AI.

Parameters:

  • brief (Hash) —

    free-form brief payload sent to the AI builder

Returns:

  • (Hash) —

    generated pipeline config



316
317
318
 
# File 'lib/melaya/pipelines.rb', line 316

def build_with_ai(brief)
  @http.post("/api/v1/private/ai/build-pipeline/sync", brief)
end

#cancel_run(name, run_id) ⇒ Hash

DELETE /api/v1/private/pipelines/:name/runs/:run_id Cancel an in-progress pipeline run.

Parameters:

  • name (String) —

    pipeline name

  • run_id (String) —

    run identifier

Returns:

  • (Hash) —

    empty hash on success



253
254
255
 
# File 'lib/melaya/pipelines.rb', line 253

def cancel_run(name, run_id)
  @http.delete("/api/v1/private/pipelines/#{enc(name)}/runs/#{enc(run_id)}")
end

#chart_data(params = {}) ⇒ Object

GET /api/v1/private/overview/chart Get chart data for overview dashboard (cost/usage over time).



38
39
40
 
# File 'lib/melaya/pipelines.rb', line 38

def chart_data(params = {})
  @http.get("/api/v1/private/overview/chart", params)
end

#cost_breakdown(params = {}) ⇒ Object

GET /api/v1/private/overview/cost-breakdown Get cost breakdown by model/provider.



44
45
46
 
# File 'lib/melaya/pipelines.rb', line 44

def cost_breakdown(params = {})
  @http.get("/api/v1/private/overview/cost-breakdown", params)
end

#count ⇒ Object

GET /api/v1/private/overview/pipeline-count Count of pipeline runs grouped by status.



50
51
52
 
# File 'lib/melaya/pipelines.rb', line 50

def count
  @http.get("/api/v1/private/overview/pipeline-count")
end

#create(name:, project:, description: nil, **config) ⇒ Hash

POST /api/v1/private/pipelines Create a new pipeline config.

Parameters:

  • name (String) —

    pipeline name

  • project (String) —

    owning project

  • description (String, nil) (defaults to: nil)
  • config (Hash) —

    additional config keys merged into the request body

Returns:

  • (Hash) —

    created pipeline config



173
174
175
176
177
178
179
180
 
# File 'lib/melaya/pipelines.rb', line 173

def create(name:, project:, description: nil, **config)
  body = compact(
    "name"        => name,
    "project"     => project,
    "description" => description
  ).merge(stringify_keys(config))
  @http.post("/api/v1/private/pipelines", body)
end

#delete_pipeline(name, project: nil) ⇒ Hash

DELETE /api/v1/private/pipelines/:name Delete a pipeline config.

Parameters:

  • name (String) —

    pipeline name

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

    owning project

Returns:

  • (Hash) —

    empty hash on success



208
209
210
211
 
# File 'lib/melaya/pipelines.rb', line 208

def delete_pipeline(name, project: nil)
  params = compact("project" => project)
  @http.delete("/api/v1/private/pipelines/#{enc(name)}", params)
end

#delete_traces(run_id) ⇒ Hash

DELETE /api/v1/private/runs/:runId/traces Delete all traces (and their spans) for a run by runId. No request body required — the runId in the path identifies the target.

Parameters:

  • run_id (String)

Returns:

  • (Hash) —

    { "deletedSpans" => Integer, "requestedTraces" => Integer (optional) }



114
115
116
 
# File 'lib/melaya/pipelines.rb', line 114

def delete_traces(run_id)
  @http.delete("/api/v1/private/runs/#{enc(run_id)}/traces")
end

#get(name, project: nil) ⇒ Hash

GET /api/v1/private/pipelines/:name Fetch a single pipeline config by name.

Parameters:

  • name (String) —

    pipeline name

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

    owning project (disambiguates when multiple projects share a name)

Returns:

  • (Hash) —

    pipeline config



187
188
189
190
 
# File 'lib/melaya/pipelines.rb', line 187

def get(name, project: nil)
  params = compact("project" => project)
  @http.get("/api/v1/private/pipelines/#{enc(name)}", params)
end

#get_schedule(project, pipeline_name) ⇒ Object

GET /api/v1/private/pipeline-schedule/:project/:pipelineName Get schedule status for a pipeline.

Parameters:

  • project (String)
  • pipeline_name (String) 


130
131
132
 
# File 'lib/melaya/pipelines.rb', line 130

def get_schedule(project, pipeline_name)
  @http.get("/api/v1/private/pipeline-schedule/#{enc(project)}/#{enc(pipeline_name)}")
end

#instantiate_template(template_id, name:, project:, overrides: nil) ⇒ Hash

POST /api/v1/private/templates/:template_id/instantiate Instantiate a platform template into a new pipeline config.

Parameters:

  • template_id (String) —

    the template to instantiate

  • name (String) —

    name for the resulting pipeline

  • project (String) —

    target project

  • overrides (Hash, nil) (defaults to: nil) —

    optional config overrides applied on top of the template defaults

Returns:

  • (Hash) —

    { "pipeline" => config }



307
308
309
310
 
# File 'lib/melaya/pipelines.rb', line 307

def instantiate_template(template_id, name:, project:, overrides: nil)
  body = compact("name" => name, "project" => project, "overrides" => overrides)
  @http.post("/api/v1/private/templates/#{enc(template_id)}/instantiate", body)
end

#list(project: nil, pipeline_name: nil, status: nil, limit: nil, offset: nil) ⇒ Object

GET /api/v1/private/overview/pipelines Paginated list of pipeline runs.

Parameters:

  • project (String, nil) (defaults to: nil)
  • pipeline_name (String, nil) (defaults to: nil)
  • status (String, nil) (defaults to: nil)
  • limit (Integer, nil) (defaults to: nil)
  • offset (Integer, nil) (defaults to: nil) 


61
62
63
64
65
66
 
# File 'lib/melaya/pipelines.rb', line 61

def list(project: nil, pipeline_name: nil, status: nil, limit: nil, offset: nil)
  @http.get("/api/v1/private/overview/pipelines",
    compact("project" => project, "pipelineName" => pipeline_name,
            "status"  => status,  "limit"        => limit,
            "offset"  => offset))
end

#list_pipelines ⇒ Object

GET /api/v1/private/pipelines List all pipeline configs accessible to the caller. Returns { "pipelines" => [...] }.



162
163
164
 
# File 'lib/melaya/pipelines.rb', line 162

def list_pipelines
  @http.get("/api/v1/private/pipelines")
end

#list_schedules ⇒ Object

GET /api/v1/private/pipeline-schedule List all pipeline schedules accessible to the caller.



122
123
124
 
# File 'lib/melaya/pipelines.rb', line 122

def list_schedules
  @http.get("/api/v1/private/pipeline-schedule")
end

#model_prices ⇒ Object

GET /api/v1/private/overview/model-prices Get pricing data for available AI models.



32
33
34
 
# File 'lib/melaya/pipelines.rb', line 32

def model_prices
  @http.get("/api/v1/private/overview/model-prices")
end

#output(name, path, download: false) ⇒ Object

GET /api/v1/private/pipelines/:name/outputs/:path Fetch a specific output artifact. Each segment of path is individually URL-encoded so slashes in segment values are preserved as separators.

Parameters:

  • name (String) —

    pipeline name

  • path (String) —

    artifact path, e.g. "reports/2024-01/summary.json"

  • download (Boolean) (defaults to: false) —

    if true, adds ?download=1 to trigger a download response

Returns:

  • artifact content or download redirect



272
273
274
275
276
 
# File 'lib/melaya/pipelines.rb', line 272

def output(name, path, download: false)
  encoded_path = path.to_s.split("/").map { |seg| enc(seg) }.join("/")
  params = download ? { "download" => 1 } : {}
  @http.get("/api/v1/private/pipelines/#{enc(name)}/outputs/#{encoded_path}", params)
end

#outputs(name) ⇒ Object

GET /api/v1/private/pipelines/:name/outputs List all output artifacts produced by a pipeline.

Parameters:

  • name (String) —

    pipeline name

Returns:

  • artifacts listing



261
262
263
 
# File 'lib/melaya/pipelines.rb', line 261

def outputs(name)
  @http.get("/api/v1/private/pipelines/#{enc(name)}/outputs")
end

#overview ⇒ Object

GET /api/v1/private/overview Dashboard overview: usage stats, active strategies, recent runs.



26
27
28
 
# File 'lib/melaya/pipelines.rb', line 26

def overview
  @http.get("/api/v1/private/overview")
end

#pause_schedule(project, pipeline_name) ⇒ Object

POST /api/v1/private/pipeline-schedule/:project/:pipelineName/pause Pause a pipeline schedule.



147
148
149
 
# File 'lib/melaya/pipelines.rb', line 147

def pause_schedule(project, pipeline_name)
  @http.post("/api/v1/private/pipeline-schedule/#{enc(project)}/#{enc(pipeline_name)}/pause")
end

#preview_code(config) ⇒ Object

POST /api/v1/private/pipelines/preview-code Generate a code preview for a pipeline config without saving it.

Parameters:

  • config (Hash) —

    pipeline config to preview

Returns:

  • preview payload



282
283
284
 
# File 'lib/melaya/pipelines.rb', line 282

def preview_code(config)
  @http.post("/api/v1/private/pipelines/preview-code", config)
end

#recent ⇒ Object

GET /api/v1/private/overview/pipelines/recent Most recent pipeline runs for a dashboard widget.



70
71
72
 
# File 'lib/melaya/pipelines.rb', line 70

def recent
  @http.get("/api/v1/private/overview/pipelines/recent")
end

#resume_schedule(project, pipeline_name) ⇒ Object

POST /api/v1/private/pipeline-schedule/:project/:pipelineName/resume Resume a paused pipeline schedule.



153
154
155
 
# File 'lib/melaya/pipelines.rb', line 153

def resume_schedule(project, pipeline_name)
  @http.post("/api/v1/private/pipeline-schedule/#{enc(project)}/#{enc(pipeline_name)}/resume")
end

#run(name, project: nil, execution_target: nil, studio_url: nil, env_overrides: nil) ⇒ Hash

POST /api/v1/private/pipelines/:name/run Enqueue a pipeline run.

Parameters:

  • name (String) —

    pipeline name

  • project (String, nil) (defaults to: nil)
  • execution_target (String, nil) (defaults to: nil) —

    runner target identifier

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

    override studio URL

  • env_overrides (Hash, nil) (defaults to: nil) —

    environment variable overrides

Returns:

  • (Hash) —

    { "run_id" => String, "queued" => Boolean }



221
222
223
224
225
226
227
228
229
 
# File 'lib/melaya/pipelines.rb', line 221

def run(name, project: nil, execution_target: nil, studio_url: nil, env_overrides: nil)
  body = compact(
    "project"         => project,
    "executionTarget" => execution_target,
    "studio_url"      => studio_url,
    "env_overrides"   => env_overrides
  )
  @http.post("/api/v1/private/pipelines/#{enc(name)}/run", body.empty? ? nil : body)
end

#run_ids(name) ⇒ Hash

GET /api/v1/private/pipelines/:name/runs List all run IDs for a pipeline.

Parameters:

  • name (String) —

    pipeline name

Returns:

  • (Hash) —

    { "run_ids" => Array }



235
236
237
 
# File 'lib/melaya/pipelines.rb', line 235

def run_ids(name)
  @http.get("/api/v1/private/pipelines/#{enc(name)}/runs")
end

#run_status(name, run_id) ⇒ Hash

GET /api/v1/private/pipelines/:name/runs/:run_id Get the status of a specific pipeline run.

Parameters:

  • name (String) —

    pipeline name

  • run_id (String) —

    run identifier

Returns:

  • (Hash) —

    { "runId", "status", "createdAt", "executionTarget", "cost" }



244
245
246
 
# File 'lib/melaya/pipelines.rb', line 244

def run_status(name, run_id)
  @http.get("/api/v1/private/pipelines/#{enc(name)}/runs/#{enc(run_id)}")
end

#server_version ⇒ Object

GET /api/v1/version (public) Get current server version string.



324
325
326
 
# File 'lib/melaya/pipelines.rb', line 324

def server_version
  @http.get("/api/v1/version")
end

#subagents ⇒ Hash

GET /api/v1/private/pipelines/subagents Fetch the registry of sub-agent definitions available to pipelines.

Returns:

  • (Hash) —

    sub-agent registry



296
297
298
 
# File 'lib/melaya/pipelines.rb', line 296

def subagents
  @http.get("/api/v1/private/pipelines/subagents")
end

#tools ⇒ Hash

GET /api/v1/private/pipelines/tools Fetch the registry of tools available to pipeline steps.

Returns:

  • (Hash) —

    tool registry



289
290
291
 
# File 'lib/melaya/pipelines.rb', line 289

def tools
  @http.get("/api/v1/private/pipelines/tools")
end

#trace(run_id, trace_id) ⇒ Object

GET /api/v1/private/runs/:runId/traces/:traceId Get a single trace by ID.



98
99
100
 
# File 'lib/melaya/pipelines.rb', line 98

def trace(run_id, trace_id)
  @http.get("/api/v1/private/runs/#{enc(run_id)}/traces/#{enc(trace_id)}")
end

#trace_stats(run_id, trace_id) ⇒ Object

GET /api/v1/private/runs/:runId/traces/:traceId/stats Get statistics for a specific trace.



104
105
106
 
# File 'lib/melaya/pipelines.rb', line 104

def trace_stats(run_id, trace_id)
  @http.get("/api/v1/private/runs/#{enc(run_id)}/traces/#{enc(trace_id)}/stats")
end

#traces(run_id, params = {}) ⇒ Hash

GET /api/v1/private/runs/:runId/traces List traces for a run (paginated).

Returns a paginated envelope, NOT a flat array:

{
"data" => {
  "list"     => Array<Hash>,   # trace summaries
  "total"    => Integer,        # total matching traces
  "page"     => Integer,
  "pageSize" => Integer
}
}

Parameters:

  • run_id (String)
  • params (Hash) (defaults to: {}) —

    optional pagination / filter params (page:, pageSize:, ...)

Returns:

  • (Hash) —

    paginated envelope as described above



92
93
94
 
# File 'lib/melaya/pipelines.rb', line 92

def traces(run_id, params = {})
  @http.get("/api/v1/private/runs/#{enc(run_id)}/traces", params)
end

#update(name, config:, project: nil) ⇒ Hash

PUT /api/v1/private/pipelines/:name Replace a pipeline's config.

Parameters:

  • name (String) —

    pipeline name

  • config (Hash) —

    full pipeline config payload

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

    owning project

Returns:

  • (Hash) —

    updated pipeline config



198
199
200
201
 
# File 'lib/melaya/pipelines.rb', line 198

def update(name, config:, project: nil)
  body = compact("config" => config, "project" => project)
  @http.put("/api/v1/private/pipelines/#{enc(name)}", body)
end

#upsert_schedule(project, pipeline_name, cron:, config: nil) ⇒ Object

PUT /api/v1/private/pipeline-schedule/:project/:pipelineName Create or update a pipeline schedule (cron expression + optional config).

Parameters:

  • project (String)
  • pipeline_name (String)
  • cron (String) —

    cron expression e.g. "0 2 * * *"

  • config (Hash, nil) (defaults to: nil) —

    optional pipeline config overrides



140
141
142
143
 
# File 'lib/melaya/pipelines.rb', line 140

def upsert_schedule(project, pipeline_name, cron:, config: nil)
  body = compact("cron" => cron, "config" => config)
  @http.put("/api/v1/private/pipeline-schedule/#{enc(project)}/#{enc(pipeline_name)}", body)
end