ruby_llm-ups 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78938b9d6f46ff771624b50d0f0932f70670aeb2c1fba8114cb706fb20cebabf
+  data.tar.gz: 6cb294cb6d6b6abdf3a794615b86f9322cd3131beb34a27098d0109d96e6b017
+SHA512:
+  metadata.gz: 79207f86600028793f3c2f881a25e5e1d4adf4dffdd5537c085fab512a99465d729f5e44768a933a8d5e7ae5b4b824a47b365197cb5bcd830dc28c6c7df9fcb7
+  data.tar.gz: 320e462bef0b2f46f04e77b590aa6955f2b6ab5e712dfc0876dc6d118b5ff44228de06f2100e1e094e414c0005d0061b2c2f96cfabae7b1c5b73b455ffd14138

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-16
+
+### Added
+
+- Automatic heartbeat reporting after each successful LLM response (model, provider, response time, tool count)
+- `Monitored` mixin for automatic per-agent component creation on ups.dev
+- `ComponentRegistry` for find-or-create component semantics
+- Manual status reporting via `report_status` (operational, degraded, partial/major outage, maintenance)
+- Incident lifecycle management: create, update, resolve
+- Async background reporter with debouncing and circuit breaker
+- Rails integration via Railtie with auto-configuration from credentials
+- Configurable error handling — monitoring failures never interrupt LLM workflows

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Valentino Stoll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,244 @@
+# RubyLLM::Ups
+
+Connect your RubyLLM-powered agents to [ups.dev](https://ups.dev) status pages.
+
+After each LLM response, the gem sends a lightweight heartbeat to ups.dev — model, provider, response time, tool count. **No message content is ever sent.** Status degradation and incidents are reported by you, when you decide they matter.
+
+## Installation
+
+```ruby
+gem "ruby_llm-ups"
+```
+
+## Quick Start
+
+### 1. Configure
+
+```ruby
+RubyLLM::Ups.configure do |c|
+  c.api_key = "ups_live_abc123_xyz789"
+  c.status_page_id = "my-page-slug"  # your status page slug or numeric ID
+end
+```
+
+In Rails, credentials are auto-loaded — no initializer needed if you set:
+
+```yaml
+# config/credentials.yml.enc
+ups:
+  api_key: ups_live_abc123_xyz789
+  status_page_id: my-page-slug
+```
+
+### 2. Include `Monitored` in your base agent
+
+```ruby
+class ApplicationAgent < RubyLLM::Agent
+  include RubyLLM::Ups::Monitored
+end
+```
+
+That's it. Every agent that inherits from `ApplicationAgent` gets its own component on ups.dev, auto-created by name. `ResearchAgent` becomes "Research Agent", `DataProcessor` becomes "Data Processor Agent".
+
+```ruby
+class ResearchAgent < ApplicationAgent
+  model "claude-sonnet-4-20250514"
+  tools SearchTool, SummarizeTool
+end
+
+agent = ResearchAgent.new    # → "Research Agent" component created on ups.dev
+agent.ask("Hello")           # → heartbeat: operational + metadata
+```
+
+Override the default name with `ups_component`:
+
+```ruby
+class MyAgent < ApplicationAgent
+  ups_component "Customer Support Bot"
+end
+```
+
+## What gets reported
+
+Every successful LLM response sends:
+
+```ruby
+{
+  model: "claude-sonnet-4-20250514",   # which model handled the request
+  provider: "anthropic",                # the LLM provider
+  last_response_time_ms: 1230,          # end-to-end response time
+  tool_count: 3                         # number of tools available
+}
+```
+
+Failed LLM calls report nothing — the monitor only fires on successful responses. You decide when a failure is worth reporting (see below).
+
+## Reporting failures
+
+### Status degradation
+
+Use `report_status` when you detect a problem — partial failures, elevated error rates, slow responses:
+
+```ruby
+RubyLLM::Ups.report_status(:degraded_performance,
+  component_id: component_id,
+  agent_metadata: {
+    failed_step: "summarization",
+    error: "Provider timeout"
+  }
+)
+```
+
+### Incidents
+
+Create incidents for failures your users should know about:
+
+```ruby
+RubyLLM::Ups.create_incident(
+  title: "Processing pipeline down",
+  impact: :major,
+  status: :investigating,
+  description: "Failed at enrichment stage: API rate limit exceeded"
+)
+```
+
+### Pipeline pattern
+
+A common pattern for multi-stage agent pipelines:
+
+```ruby
+class Pipeline
+  def call
+    stages.each { |stage| run_stage(stage) }
+    ups_report_operational
+  rescue => e
+    ups_create_incident(e)
+    raise
+  end
+
+  def run_stage(stage)
+    stage.call
+  rescue => e
+    if optional_stage?(stage)
+      ups_report_degraded(stage, e)  # partial failure — degraded, not down
+    else
+      raise                          # critical failure — will create incident
+    end
+  end
+
+  private
+
+  def pipeline_component_id
+    @pipeline_component_id ||= begin
+      component = RubyLLM::Ups.component_registry.find_or_create("My Pipeline")
+      component["id"]
+    end
+  end
+
+  def ups_report_operational
+    RubyLLM::Ups.report_status(:operational, component_id: pipeline_component_id)
+  rescue => e
+    Rails.logger.warn("[ups.dev] #{e.message}")
+  end
+
+  def ups_report_degraded(stage, error)
+    RubyLLM::Ups.report_status(:degraded_performance,
+      component_id: pipeline_component_id,
+      agent_metadata: { failed_stage: stage.name, error: error.message }
+    )
+  rescue => e
+    Rails.logger.warn("[ups.dev] #{e.message}")
+  end
+
+  def ups_create_incident(error)
+    RubyLLM::Ups.create_incident(
+      title: "Pipeline failed",
+      impact: :major,
+      status: :investigating,
+      description: error.message
+    )
+  rescue => e
+    Rails.logger.warn("[ups.dev] #{e.message}")
+  end
+end
+```
+
+Key points:
+- Use `component_registry.find_or_create` to get a named component for non-agent things
+- Always rescue ups.dev calls — monitoring failures should never break your app
+- `report_status(:operational)` after success resets a previously degraded component
+
+## Incident lifecycle
+
+```ruby
+# Open
+incident = RubyLLM::Ups.create_incident(
+  title: "Agent responding slowly",
+  impact: :minor,               # :none, :minor, :major, :critical
+  status: :investigating        # :investigating, :identified, :monitoring, :resolved
+)
+
+# Update
+RubyLLM::Ups.update_incident(incident["incident"]["id"],
+  status: :identified,
+  update_message: "Root cause: Anthropic API degradation"
+)
+
+# Resolve
+RubyLLM::Ups.resolve_incident(incident["incident"]["id"])
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` | required | Your ups.dev API key |
+| `status_page_id` | required | Status page slug or numeric ID |
+| `component_id` | — | Default component for `monitor` and `report_status` (optional with `Monitored`) |
+| `base_url` | `https://ups.dev` | API base URL |
+| `request_timeout` | `30` | HTTP timeout in seconds |
+| `on_error` | stderr | Error handler proc |
+| `async` | `true` | Send heartbeats in a background thread |
+| `flush_interval` | `5` | Seconds between async flushes |
+| `circuit_breaker_threshold` | `5` | Consecutive failures before opening circuit |
+| `circuit_breaker_timeout` | `60` | Seconds to keep circuit open before retrying |
+
+### Error handling
+
+Monitoring errors never interrupt your LLM workflows. Route them somewhere useful:
+
+```ruby
+RubyLLM::Ups.configure do |c|
+  c.on_error = ->(e) { Rails.logger.warn("[ups.dev] #{e.message}") }
+end
+```
+
+## Manual monitoring
+
+If you don't want `Monitored`, call `monitor()` directly:
+
+```ruby
+RubyLLM::Ups.configure do |c|
+  c.api_key = "..."
+  c.status_page_id = "..."
+  c.component_id = "my-agent-id"
+end
+
+chat = RubyLLM.chat(model: "claude-sonnet-4-20250514")
+RubyLLM::Ups.monitor(chat)
+chat.ask("Hello")  # → heartbeat sent
+```
+
+## Direct client access
+
+```ruby
+client = RubyLLM::Ups.client
+
+client.list_components
+client.create_component(name: "New Agent", component_type: "agent")
+client.update_component("comp-id", status: :operational, agent_metadata: { model: "gpt-4" })
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/ruby_llm/ups/async_reporter.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    class AsyncReporter
+      CLOSED = :closed
+      OPEN = :open
+      HALF_OPEN = :half_open
+
+      def initialize(client, config)
+        @client = client
+        @config = config
+        @buffer = {}
+        @mutex = Mutex.new
+        @signal = Queue.new
+        @thread = nil
+        @shutdown = false
+        @at_exit_registered = false
+
+        # Circuit breaker state
+        @cb_state = CLOSED
+        @consecutive_failures = 0
+        @opened_at = nil
+      end
+
+      def enqueue(component_id, status:, agent_metadata:)
+        @mutex.synchronize do
+          @buffer[component_id] = { status: status, agent_metadata: agent_metadata }
+        end
+        ensure_running
+        @signal.push(:enqueue) rescue nil # wake the worker
+      end
+
+      def shutdown(timeout: 2)
+        @mutex.synchronize { @shutdown = true }
+        @signal.push(:shutdown) rescue nil
+        @thread&.join(timeout)
+      end
+
+      def running?
+        @thread&.alive? == true
+      end
+
+      def flush_now
+        entries = drain_buffer
+        flush_entries(entries) unless entries.empty?
+      end
+
+      private
+
+      def ensure_running
+        return if @thread&.alive?
+
+        @mutex.synchronize do
+          return if @thread&.alive?
+          @shutdown = false
+
+          @thread = Thread.new { worker_loop }
+          @thread.abort_on_exception = false
+
+          unless @at_exit_registered
+            at_exit { shutdown }
+            @at_exit_registered = true
+          end
+        end
+      end
+
+      def worker_loop
+        loop do
+          # Wait for signal or flush interval timeout
+          wait_for_signal
+
+          break if @mutex.synchronize { @shutdown }
+
+          entries = drain_buffer
+          flush_entries(entries) unless entries.empty?
+        end
+
+        # Final drain on shutdown
+        entries = drain_buffer
+        flush_entries(entries) unless entries.empty?
+      end
+
+      def wait_for_signal
+        deadline = Time.now + @config.flush_interval
+        loop do
+          remaining = deadline - Time.now
+          break if remaining <= 0
+
+          begin
+            # Non-blocking pop with short sleep fallback
+            @signal.pop(true)
+            break
+          rescue ThreadError
+            sleep(0.1)
+          end
+        end
+      end
+
+      def drain_buffer
+        @mutex.synchronize do
+          entries = @buffer.dup
+          @buffer.clear
+          entries
+        end
+      end
+
+      def flush_entries(entries)
+        return if circuit_open?
+
+        entries.each do |component_id, payload|
+          begin
+            @client.update_component(component_id, status: payload[:status],
+                                                   agent_metadata: payload[:agent_metadata])
+            record_success
+          rescue => e
+            record_failure
+            break if circuit_open?
+            @config.on_error&.call(e)
+          end
+        end
+      end
+
+      def circuit_open?
+        case @cb_state
+        when CLOSED
+          false
+        when OPEN
+          if Time.now - @opened_at >= @config.circuit_breaker_timeout
+            @cb_state = HALF_OPEN
+            false
+          else
+            true
+          end
+        when HALF_OPEN
+          false
+        end
+      end
+
+      def record_success
+        @consecutive_failures = 0
+        @cb_state = CLOSED
+      end
+
+      def record_failure
+        @consecutive_failures += 1
+        if @consecutive_failures >= @config.circuit_breaker_threshold
+          @cb_state = OPEN
+          @opened_at = Time.now
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/ups/client.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module RubyLLM
+  module Ups
+    class Client
+      def initialize(config)
+        @config = config
+        @config.validate!
+      end
+
+      def update_component(component_id, status:, agent_metadata: {})
+        patch("components/#{component_id}", component: {
+          status: status,
+          agent_metadata: agent_metadata
+        })
+      end
+
+      def create_component(name:, component_type: "agent", **attrs)
+        post("components", component: { name: name, component_type: component_type, **attrs })
+      end
+
+      def list_components
+        get("components")
+      end
+
+      def create_incident(title:, impact:, status: :investigating, **attrs)
+        post("incidents", incident: {
+          title: title,
+          impact: impact,
+          status: status,
+          **attrs
+        })
+      end
+
+      def update_incident(id, **attrs)
+        patch("incidents/#{id}", incident: attrs)
+      end
+
+      def resolve_incident(id)
+        update_incident(id, status: :resolved)
+      end
+
+      private
+
+      def get(path)
+        handle_response(connection.get(api_path(path)))
+      end
+
+      def post(path, body)
+        handle_response(connection.post(api_path(path)) do |req|
+          req.body = JSON.generate(body)
+        end)
+      end
+
+      def patch(path, body)
+        handle_response(connection.patch(api_path(path)) do |req|
+          req.body = JSON.generate(body)
+        end)
+      end
+
+      def api_path(path)
+        "/api/v1/status_pages/#{@config.status_page_id}/#{path}"
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: @config.base_url) do |f|
+          f.headers["Authorization"] = "Bearer #{@config.api_key}"
+          f.headers["Content-Type"] = "application/json"
+          f.headers["Accept"] = "application/json"
+          f.headers["User-Agent"] = "ruby_llm-ups/#{VERSION}"
+          f.options.timeout = @config.request_timeout
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def handle_response(response)
+        body = parse_body(response.body)
+
+        case response.status
+        when 200..299
+          body
+        when 401
+          raise AuthenticationError.new("Invalid API token", status: response.status, body: body)
+        when 404
+          raise NotFoundError.new("Resource not found", status: response.status, body: body)
+        when 429
+          raise RateLimitError.new("Rate limit exceeded", status: response.status, body: body)
+        else
+          raise ApiError.new("API error", status: response.status, body: body)
+        end
+      end
+
+      def parse_body(body)
+        return {} if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        { "raw" => body }
+      end
+    end
+  end
+end

data/lib/ruby_llm/ups/component_registry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    class ComponentRegistry
+      def initialize(client)
+        @client = client
+        @cache = {}
+        @mutex = Mutex.new
+      end
+
+      def find_or_create(name)
+        @mutex.synchronize { return @cache[name] if @cache[name] }
+
+        component = find_by_name(name) || create_component(name)
+
+        @mutex.synchronize { @cache[name] = component }
+        component
+      end
+
+      def clear_cache
+        @mutex.synchronize { @cache.clear }
+      end
+
+      private
+
+      def find_by_name(name)
+        response = @client.list_components
+        components = response["components"] || response
+        components = [components] if components.is_a?(Hash)
+
+        components.find { |c| c["name"] == name }
+      end
+
+      def create_component(name)
+        response = @client.create_component(name: name, component_type: "agent")
+        response["component"] || response
+      end
+    end
+  end
+end

data/lib/ruby_llm/ups/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    class Configuration
+      attr_accessor :api_key, :base_url, :status_page_id, :component_id,
+                    :request_timeout, :on_error,
+                    :async, :flush_interval,
+                    :circuit_breaker_threshold, :circuit_breaker_timeout
+
+      def initialize
+        @base_url = "https://ups.dev"
+        @request_timeout = 30
+        @on_error = ->(e) { $stderr.puts("[ruby_llm-ups] #{e.message}") }
+        @async = true
+        @flush_interval = 5
+        @circuit_breaker_threshold = 5
+        @circuit_breaker_timeout = 60
+      end
+
+      def validate!
+        raise ConfigurationError, "api_key is required" if api_key.nil? || api_key.empty?
+        raise ConfigurationError, "status_page_id is required" if status_page_id.nil? || status_page_id.empty?
+      end
+    end
+  end
+end

data/lib/ruby_llm/ups/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+
+    class ApiError < Error
+      attr_reader :status, :body
+
+      def initialize(message = nil, status: nil, body: nil)
+        @status = status
+        @body = body
+        super(message || "API error (#{status})")
+      end
+    end
+
+    class AuthenticationError < ApiError; end
+    class NotFoundError < ApiError; end
+    class RateLimitError < ApiError; end
+  end
+end

data/lib/ruby_llm/ups/incident_methods.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    module IncidentMethods
+      def create_incident(title:, impact:, status: :investigating, **attrs)
+        meta = _ups_monitor.build_metadata
+        meta[:component_id] ||= _ups_monitor.component_id
+        _ups_monitor.client.create_incident(title: title, impact: impact, status: status,
+                                            agent_metadata: meta, **attrs)
+      end
+
+      def update_incident(id, **attrs)
+        caller_meta = attrs.delete(:agent_metadata) || {}
+        meta = _ups_monitor.build_metadata.merge(caller_meta)
+        _ups_monitor.client.update_incident(id, agent_metadata: meta, **attrs)
+      end
+
+      def resolve_incident(id)
+        update_incident(id, status: :resolved)
+      end
+    end
+  end
+end

data/lib/ruby_llm/ups/monitor.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    class Monitor
+      attr_reader :component_id, :client
+
+      def initialize(target, component_id:, client:, async_reporter: nil)
+        @chat = extract_chat(target)
+        @component_id = component_id
+        @client = client
+        @async_reporter = async_reporter
+        @request_start = nil
+        install_callbacks
+        install_incident_methods(target)
+      end
+
+      def mark_start
+        @request_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def report(_message)
+        if @async_reporter
+          @async_reporter.enqueue(@component_id, status: :operational, agent_metadata: build_metadata)
+        else
+          @client.update_component(@component_id, status: :operational, agent_metadata: build_metadata)
+        end
+      rescue => e
+        handle_error(e)
+      end
+
+      def build_metadata
+        metadata = {
+          model: @chat.model.id,
+          provider: @chat.model.provider.to_s,
+          tool_count: @chat.tools.size
+        }
+
+        if @request_start
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @request_start
+          metadata[:last_response_time_ms] = (elapsed * 1000).round
+        end
+
+        metadata
+      end
+
+      private
+
+      def extract_chat(target)
+        target.respond_to?(:chat) ? target.chat : target
+      end
+
+      def install_callbacks
+        monitor = self
+
+        @chat.on_new_message do
+          monitor.mark_start
+        end
+
+        @chat.on_end_message do |msg|
+          monitor.report(msg) if msg.role == :assistant
+        end
+      end
+
+      def install_incident_methods(target)
+        target.instance_variable_set(:@_ups_monitor, self)
+        target.define_singleton_method(:_ups_monitor) { @_ups_monitor } unless target.respond_to?(:_ups_monitor)
+        target.extend(IncidentMethods)
+      end
+
+      def handle_error(error)
+        Ups.config.on_error.call(error)
+      end
+    end
+  end
+end

data/lib/ruby_llm/ups/monitored.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    module Monitored
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.prepend(Initializer)
+      end
+
+      module ClassMethods
+        def ups_component(name = nil)
+          if name
+            @_ups_component_name = name
+          else
+            @_ups_component_name
+          end
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@_ups_component_name, @_ups_component_name)
+        end
+      end
+
+      module Initializer
+        def initialize(*, **kwargs, &block)
+          super
+          _ups_auto_monitor
+        end
+
+        private
+
+        def _ups_auto_monitor
+          return unless _ups_configured?
+
+          name = self.class.ups_component || _ups_derive_name
+          component = RubyLLM::Ups.component_registry.find_or_create(name)
+          component_id = component["id"]
+
+          RubyLLM::Ups.monitor(self, component_id: component_id)
+        rescue => e
+          RubyLLM::Ups.config.on_error&.call(e)
+        end
+
+        def _ups_configured?
+          config = RubyLLM::Ups.config
+          config.api_key && !config.api_key.to_s.empty? &&
+            config.status_page_id && !config.status_page_id.to_s.empty?
+        end
+
+        def _ups_derive_name
+          class_name = self.class.name&.split("::")&.last || self.class.to_s
+          # Insert space before capitals: "ResearchAgent" -> "Research Agent"
+          name = class_name.gsub(/([a-z])([A-Z])/, '\1 \2')
+          # Append "Agent" if not already present
+          name += " Agent" unless name =~ /Agent\s*$/i
+          name
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/ups/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    class Railtie < Rails::Railtie
+      initializer "ruby_llm_ups.configure" do
+        config = RubyLLM::Ups.config
+        creds = Rails.application.credentials.dig(:ups) || {}
+
+        config.api_key ||= creds[:api_key]
+        config.status_page_id ||= creds[:status_page_id]
+        config.component_id ||= creds[:component_id]
+      end
+    end
+  end
+end

data/lib/ruby_llm/ups/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Ups
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_llm/ups.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "ups/version"
+require_relative "ups/errors"
+require_relative "ups/configuration"
+require_relative "ups/client"
+require_relative "ups/async_reporter"
+require_relative "ups/incident_methods"
+require_relative "ups/monitor"
+require_relative "ups/component_registry"
+require_relative "ups/monitored"
+
+module RubyLLM
+  module Ups
+    class << self
+      def configure
+        yield config
+        @client = nil # reset client on reconfigure
+        @async_reporter = nil
+        @component_registry = nil
+      end
+
+      def config
+        @config ||= Configuration.new
+      end
+
+      def client
+        @client ||= Client.new(config)
+      end
+
+      def component_registry
+        @component_registry ||= ComponentRegistry.new(client)
+      end
+
+      def monitor(chat_or_agent, component_id: nil)
+        cid = resolve_component_id!(component_id)
+        Monitor.new(chat_or_agent, component_id: cid, client: client,
+                                   async_reporter: config.async ? async_reporter : nil)
+        chat_or_agent
+      end
+
+      def report_status(status, component_id: nil, agent_metadata: {})
+        cid = resolve_component_id!(component_id)
+        client.update_component(cid, status: status, agent_metadata: agent_metadata)
+      end
+
+      def create_incident(title:, impact:, status: :investigating, **attrs)
+        client.create_incident(title: title, impact: impact, status: status, **attrs)
+      end
+
+      def update_incident(id, **attrs)
+        client.update_incident(id, **attrs)
+      end
+
+      def resolve_incident(id)
+        client.resolve_incident(id)
+      end
+
+      def reset!
+        @async_reporter&.shutdown
+        @config = nil
+        @client = nil
+        @async_reporter = nil
+        @component_registry = nil
+      end
+
+      private
+
+      def async_reporter
+        @async_reporter ||= AsyncReporter.new(client, config)
+      end
+
+      def resolve_component_id!(component_id = nil)
+        cid = component_id || config.component_id
+        raise ConfigurationError, "component_id is required" if cid.nil? || cid.to_s.empty?
+
+        cid
+      end
+    end
+  end
+end
+
+require_relative "ups/railtie" if defined?(Rails::Railtie)

data/lib/ruby_llm-ups.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ruby_llm/ups"

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-ups
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Valentino Stoll
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Automatically report AI agent health, response times, and model info
+  to your ups.dev status page.
+email:
+- v@codenamev.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ruby_llm-ups.rb
+- lib/ruby_llm/ups.rb
+- lib/ruby_llm/ups/async_reporter.rb
+- lib/ruby_llm/ups/client.rb
+- lib/ruby_llm/ups/component_registry.rb
+- lib/ruby_llm/ups/configuration.rb
+- lib/ruby_llm/ups/errors.rb
+- lib/ruby_llm/ups/incident_methods.rb
+- lib/ruby_llm/ups/monitor.rb
+- lib/ruby_llm/ups/monitored.rb
+- lib/ruby_llm/ups/railtie.rb
+- lib/ruby_llm/ups/version.rb
+homepage: https://github.com/codenamev/ruby_llm-ups
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/codenamev/ruby_llm-ups
+  source_code_uri: https://github.com/codenamev/ruby_llm-ups
+  changelog_uri: https://github.com/codenamev/ruby_llm-ups/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: ups.dev integration for RubyLLM
+test_files: []