rubyllm-observ 0.6.4 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a648839b815f45ded484d1b4e97c83a583fff99b3922d4920694c30500e566d4
-  data.tar.gz: 6bda76d81a50e4171fbc400c4195e76a6db1c270fe57aab6d2d9182e872f5613
+  metadata.gz: 94f902979484dc837e40bf42dbfc66381eaf4326b3f03831b31aa36478a55c81
+  data.tar.gz: bfbdeaf7ecf11149bcb6d22832267d8959d827b4680aac05c25d762d48310293
 SHA512:
-  metadata.gz: 8adeb19ae2ea22fc7aef0190b89d87ca60921a34ef21ab7dc385c8882a0590316a2cc29f1d5cefeb7ab0c5cf27cfa766766a1507f4496aef2c14196e967b57e5
-  data.tar.gz: ed4287385ce15431b945d223300213d26a678290fb48a156108a968a76e52476a22dcac1777fbe287842e6fb855bd5c6563de946d0d98e0b2f0eaac410aa66cb
+  metadata.gz: e6d87df6d6e07ed28f8b5df8ed07d25077705764c5535176e9a142e58a59a6f023b313add55a8e25e37f0aebe3400d7d1631b326554431f9087c37806e8d93b0
+  data.tar.gz: 86c2026e946ee56ff3089294a53952eee7c93c4a238ca9553596bd51e8fe098e36fd3c50db586e6d2d50b69515a07f71b11ddcc8374cb0a18ae118e967766404

data/app/services/observ/concerns/observable_service.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Observ
+  module Concerns
+    # Concern for adding observability to service objects
+    #
+    # This module provides automatic observability session management for services
+    # that perform LLM operations. It handles session creation, lifecycle management,
+    # and chat instrumentation.
+    #
+    # Usage:
+    #   class MyService
+    #     include Observ::Concerns::ObservableService
+    #
+    #     def initialize(observability_session: nil)
+    #       initialize_observability(
+    #         observability_session,
+    #         service_name: "my_service",
+    #         metadata: { custom: "data" }
+    #       )
+    #     end
+    #
+    #     def perform(input)
+    #       with_observability do |session|
+    #         # Your service logic here
+    #         # Session automatically finalized on success/error
+    #       end
+    #     end
+    #   end
+    module ObservableService
+      extend ActiveSupport::Concern
+
+      included do
+        attr_reader :observability
+      end
+
+      # Initialize observability for the service
+      #
+      # @param session_or_false [Observ::Session, false, nil] Session to use, false to disable, nil to auto-create
+      # @param service_name [String] Name of the service (used in session metadata)
+      # @param metadata [Hash] Additional metadata to include in the session
+      def initialize_observability(session_or_false = nil, service_name:, metadata: {})
+        if session_or_false == false
+          # Explicitly disable observability
+          @observability = nil
+          @owns_session = false
+        elsif session_or_false
+          # Use provided session
+          @observability = session_or_false
+          @owns_session = false
+        else
+          # Auto-create session for standalone use
+          @observability = create_service_session(service_name, metadata)
+          @owns_session = @observability.present?
+        end
+      end
+
+      # Execute a block with automatic session lifecycle management
+      #
+      # The session will be finalized automatically after the block completes,
+      # whether it succeeds or raises an error. Only sessions owned by this
+      # service instance (i.e., auto-created sessions) will be finalized.
+      #
+      # @yield [session] The observability session (may be nil if disabled)
+      # @return The result of the block
+      #
+      # @example
+      #   with_observability do |session|
+      #     # Your service logic here
+      #     process_data(session)
+      #   end
+      def with_observability(&block)
+        result = block.call(@observability)
+        finalize_service_session if @owns_session
+        result
+      rescue StandardError
+        finalize_service_session if @owns_session
+        raise
+      end
+
+      # Instrument a RubyLLM chat instance for observability
+      #
+      # This wraps the chat's ask method to automatically create traces
+      # and track LLM calls within the observability session.
+      #
+      # @param chat [RubyLLM::Chat] The chat instance to instrument
+      # @param context [Hash] Additional context to include in traces
+      # @return [Observ::ChatInstrumenter, nil] The instrumenter or nil if observability is disabled
+      #
+      # @example
+      #   chat = RubyLLM.chat(model: "gpt-4")
+      #   instrument_chat(chat, context: { operation: "summarize" })
+      #   response = chat.ask("Summarize this text")
+      def instrument_chat(chat, context: {})
+        return unless @observability
+
+        @observability.instrument_chat(chat, context: context)
+      end
+
+      private
+
+      # Create a new observability session for this service
+      #
+      # @param service_name [String] Name of the service
+      # @param metadata [Hash] Additional metadata for the session
+      # @return [Observ::Session, nil] The created session or nil if observability is disabled/failed
+      def create_service_session(service_name, metadata = {})
+        return nil unless Rails.configuration.observability.enabled
+
+        Observ::Session.create!(
+          user_id: "#{service_name}_service",
+          metadata: metadata.merge(
+            agent_type: service_name,
+            standalone: true,
+            created_at: Time.current.iso8601
+          )
+        )
+      rescue StandardError => e
+        Rails.logger.error(
+          "[#{self.class.name}] Failed to create observability session: #{e.message}"
+        )
+        nil
+      end
+
+      # Finalize the observability session if we own it
+      #
+      # This marks the session as complete and triggers aggregation of metrics.
+      # Only called for sessions created by this service instance.
+      def finalize_service_session
+        return unless @observability
+
+        @observability.finalize
+        Rails.logger.debug(
+          "[#{self.class.name}] Session finalized: #{@observability.session_id}"
+        )
+      rescue StandardError => e
+        Rails.logger.error(
+          "[#{self.class.name}] Failed to finalize session: #{e.message}"
+        )
+      end
+    end
+  end
+end

data/lib/observ/version.rb

@@ -1,3 +1,3 @@
 module Observ
-  VERSION = "0.6.4"
+  VERSION = "0.6.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubyllm-observ
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.6.5
 platform: ruby
 authors:
 - Franck D'agostini
@@ -309,6 +309,7 @@ files:
 - app/services/observ/agent_provider.rb
 - app/services/observ/agent_selection_service.rb
 - app/services/observ/chat_instrumenter.rb
+- app/services/observ/concerns/observable_service.rb
 - app/services/observ/dataset_runner_service.rb
 - app/services/observ/evaluator_runner_service.rb
 - app/services/observ/evaluators/base_evaluator.rb