Ruby SDK

Installation

Install

gem install notilens

# Or in Gemfile:
gem "notilens"

Setup

Initialize

require "notilens"

nl = NotiLens.init("my-app", token: "YOUR_TOKEN", secret: "YOUR_SECRET")

# Or use environment variables: NOTILENS_TOKEN / NOTILENS_SECRET
nl = NotiLens.init("my-app")

Task Lifecycle

Task Events

Real-world uses: wrap an AI research agent (start → progress → complete/fail), a nightly invoice import (loop per batch → complete), or a user-triggered export (start → output_generated → complete).

run = nl.task("email")
run.queue
run.start

run.progress("Fetching records...")
run.loop("Processing batch 2")
run.retry
run.pause("Rate limited")
run.resume("Resuming")
run.wait("Awaiting tool")
run.error("Non-fatal error")

run.complete("All done")
run.fail("Unrecoverable")
run.timeout("Exceeded 30s")
run.cancel("User cancelled")
run.terminate("OOM")

Metrics

Metrics

Real-world uses: track LLM token spend across a multi-step run. Monitor records in a nightly ETL — NotiLens alerts if count drops vs baseline. Watch API error rate across runs.

run.metric("tokens", 350)
run.metric("tokens", 210)    # now 560
run.metric("cost", 0.0012)
run.metric("model", "gpt-4")

run.reset_metrics("tokens")
run.reset_metrics

Full Example

Complete Working Example

require "notilens"

nl  = NotiLens.init("summarizer", token: "TOKEN", secret: "SECRET")
run = nl.task("report")
run.start

begin
  run.progress("Fetching PDF")
  result = llm.complete(prompt)
  run.metric("tokens", result.usage.total_tokens)
  run.metric("cost", result.usage.cost)
  run.output_generated("Summary ready")
  run.complete("Done")
rescue => e
  run.fail(e.message)
end

force_send

force_send Parameter

Controls whether a notification bypasses ML-based filtering (true) or routes through it (false).

Override

run.progress("Fetching...", force_send: true)
run.fail("Error", force_send: false)
nl.notify("order.placed", "Done", force_send: false)