language-operator 0.0.1 → 0.1.31

data/lib/language_operator/agent/safety/budget_tracker.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative '../../logger'
+require_relative '../../loggable'
+
+module LanguageOperator
+  module Agent
+    module Safety
+      # Budget Tracker for enforcing cost and token limits
+      #
+      # Tracks cumulative costs and token usage per agent instance
+      # and enforces configured budgets.
+      #
+      # @example
+      #   tracker = BudgetTracker.new(daily_budget: 10.0, hourly_budget: 1.0)
+      #   tracker.check_budget!(estimated_cost: 0.05, estimated_tokens: 500)
+      class BudgetTracker
+        include LanguageOperator::Loggable
+
+        attr_reader :daily_budget, :hourly_budget, :token_budget
+
+        class BudgetExceededError < StandardError; end
+
+        def initialize(daily_budget: nil, hourly_budget: nil, token_budget: nil)
+          @daily_budget = daily_budget&.to_f
+          @hourly_budget = hourly_budget&.to_f
+          @token_budget = token_budget&.to_i
+
+          @daily_spending = 0.0
+          @hourly_spending = 0.0
+          @daily_tokens = 0
+          @hourly_tokens = 0
+
+          @day_start = Time.now
+          @hour_start = Time.now
+
+          logger.info('Budget tracker initialized',
+                      daily_budget: @daily_budget&.round(2),
+                      hourly_budget: @hourly_budget&.round(2),
+                      token_budget: @token_budget)
+        end
+
+        # Check if a request would exceed budget limits
+        #
+        # @param estimated_cost [Float] Estimated cost for the request
+        # @param estimated_tokens [Integer] Estimated token count
+        # @raise [BudgetExceededError] If budget would be exceeded
+        def check_budget!(estimated_cost: 0.0, estimated_tokens: 0)
+          reset_if_needed
+
+          # Check daily budget
+          if @daily_budget && (@daily_spending + estimated_cost) > @daily_budget
+            remaining = [@daily_budget - @daily_spending, 0].max
+            logger.error('Daily budget exceeded',
+                         current: @daily_spending.round(4),
+                         limit: @daily_budget,
+                         remaining: remaining.round(4),
+                         requested: estimated_cost.round(4))
+            raise BudgetExceededError,
+                  "Daily budget exceeded: $#{@daily_spending.round(4)}/$#{@daily_budget} " \
+                  "(requested: $#{estimated_cost.round(4)})"
+          end
+
+          # Check hourly budget
+          if @hourly_budget && (@hourly_spending + estimated_cost) > @hourly_budget
+            remaining = [@hourly_budget - @hourly_spending, 0].max
+            logger.error('Hourly budget exceeded',
+                         current: @hourly_spending.round(4),
+                         limit: @hourly_budget,
+                         remaining: remaining.round(4),
+                         requested: estimated_cost.round(4))
+            raise BudgetExceededError,
+                  "Hourly budget exceeded: $#{@hourly_spending.round(4)}/$#{@hourly_budget} " \
+                  "(requested: $#{estimated_cost.round(4)})"
+          end
+
+          # Check token budget
+          if @token_budget && (@daily_tokens + estimated_tokens) > @token_budget
+            remaining = [@token_budget - @daily_tokens, 0].max
+            logger.error('Token budget exceeded',
+                         current: @daily_tokens,
+                         limit: @token_budget,
+                         remaining: remaining,
+                         requested: estimated_tokens)
+            raise BudgetExceededError,
+                  "Token budget exceeded: #{@daily_tokens}/#{@token_budget} " \
+                  "(requested: #{estimated_tokens})"
+          end
+
+          logger.debug('Budget check passed',
+                       estimated_cost: estimated_cost.round(4),
+                       estimated_tokens: estimated_tokens)
+        end
+
+        # Record actual spending after a request
+        #
+        # @param cost [Float] Actual cost of the request
+        # @param tokens [Integer] Actual token count
+        def record_spending(cost:, tokens:)
+          reset_if_needed
+
+          @daily_spending += cost
+          @hourly_spending += cost
+          @daily_tokens += tokens
+          @hourly_tokens += tokens
+
+          logger.debug('Spending recorded',
+                       cost: cost.round(4),
+                       tokens: tokens,
+                       daily_total: @daily_spending.round(4),
+                       hourly_total: @hourly_spending.round(4),
+                       daily_tokens: @daily_tokens)
+        end
+
+        # Get current budget status
+        #
+        # @return [Hash] Budget status information
+        def status
+          reset_if_needed
+
+          {
+            daily: {
+              spending: @daily_spending.round(4),
+              budget: @daily_budget&.round(2),
+              remaining: @daily_budget ? (@daily_budget - @daily_spending).round(4) : nil,
+              percentage: @daily_budget ? ((@daily_spending / @daily_budget) * 100).round(1) : nil
+            },
+            hourly: {
+              spending: @hourly_spending.round(4),
+              budget: @hourly_budget&.round(2),
+              remaining: @hourly_budget ? (@hourly_budget - @hourly_spending).round(4) : nil,
+              percentage: @hourly_budget ? ((@hourly_spending / @hourly_budget) * 100).round(1) : nil
+            },
+            tokens: {
+              used: @daily_tokens,
+              budget: @token_budget,
+              remaining: @token_budget ? (@token_budget - @daily_tokens) : nil,
+              percentage: @token_budget ? ((@daily_tokens.to_f / @token_budget) * 100).round(1) : nil
+            }
+          }
+        end
+
+        private
+
+        def logger_component
+          'Safety::BudgetTracker'
+        end
+
+        # Reset counters if time periods have elapsed
+        def reset_if_needed
+          now = Time.now
+
+          # Reset daily counters
+          if (now - @day_start) >= 86_400 # 24 hours
+            logger.info('Resetting daily budget counters',
+                        previous_spending: @daily_spending.round(4),
+                        previous_tokens: @daily_tokens)
+            @daily_spending = 0.0
+            @daily_tokens = 0
+            @day_start = now
+          end
+
+          # Reset hourly counters
+          return unless (now - @hour_start) >= 3600 # 1 hour
+
+          logger.debug('Resetting hourly budget counters',
+                       previous_spending: @hourly_spending.round(4))
+          @hourly_spending = 0.0
+          @hourly_tokens = 0
+          @hour_start = now
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/agent/safety/content_filter.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../../logger'
+require_relative '../../loggable'
+
+module LanguageOperator
+  module Agent
+    module Safety
+      # Content Filter for pre-prompt and post-response filtering
+      #
+      # Supports pattern matching for blocked keywords and topics.
+      # Can be extended to integrate with moderation APIs.
+      #
+      # @example
+      #   filter = ContentFilter.new(blocked_patterns: ['password', 'secret'])
+      #   filter.check_content!("Here is my password: 12345", direction: :input)
+      class ContentFilter
+        include LanguageOperator::Loggable
+
+        class ContentBlockedError < StandardError; end
+
+        def initialize(blocked_patterns: [], blocked_topics: [], case_sensitive: false)
+          @blocked_patterns = blocked_patterns || []
+          @blocked_topics = blocked_topics || []
+          @case_sensitive = case_sensitive
+
+          logger.info('Content filter initialized',
+                      patterns: @blocked_patterns.length,
+                      topics: @blocked_topics.length,
+                      case_sensitive: @case_sensitive)
+        end
+
+        # Check content for blocked patterns
+        #
+        # @param content [String] Content to check
+        # @param direction [Symbol] :input or :output
+        # @raise [ContentBlockedError] If content contains blocked patterns
+        def check_content!(content, direction: :input)
+          return if @blocked_patterns.empty? && @blocked_topics.empty?
+
+          content_to_check = @case_sensitive ? content : content.downcase
+
+          # Check blocked patterns
+          @blocked_patterns.each do |pattern|
+            pattern_to_match = @case_sensitive ? pattern : pattern.downcase
+            next unless content_to_check.include?(pattern_to_match)
+
+            logger.warn('Blocked pattern detected',
+                        direction: direction,
+                        pattern: pattern,
+                        content_preview: content[0..100])
+            raise ContentBlockedError,
+                  "Content blocked: contains forbidden pattern '#{pattern}' in #{direction}"
+          end
+
+          # Check blocked topics (using regex patterns)
+          @blocked_topics.each do |topic|
+            pattern = @case_sensitive ? Regexp.new(topic) : Regexp.new(topic, Regexp::IGNORECASE)
+            next unless content_to_check.match?(pattern)
+
+            logger.warn('Blocked topic detected',
+                        direction: direction,
+                        topic: topic,
+                        content_preview: content[0..100])
+            raise ContentBlockedError,
+                  "Content blocked: matches forbidden topic '#{topic}' in #{direction}"
+          end
+
+          logger.debug('Content check passed',
+                       direction: direction,
+                       content_length: content.length)
+        end
+
+        # Check if content would be blocked (without raising)
+        #
+        # @param content [String] Content to check
+        # @return [Boolean] True if content would be blocked
+        def blocked?(content)
+          check_content!(content)
+          false
+        rescue ContentBlockedError
+          true
+        end
+
+        private
+
+        def logger_component
+          'Safety::ContentFilter'
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/agent/safety/manager.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require_relative 'budget_tracker'
+require_relative 'rate_limiter'
+require_relative 'content_filter'
+require_relative 'audit_logger'
+require_relative '../../logger'
+require_relative '../../loggable'
+
+module LanguageOperator
+  module Agent
+    module Safety
+      # Safety Manager
+      #
+      # Coordinates all safety components (budget tracking, rate limiting,
+      # content filtering, audit logging) and provides a unified interface.
+      #
+      # @example
+      #   safety = Manager.new(
+      #     daily_budget: 10.0,
+      #     requests_per_minute: 10,
+      #     blocked_patterns: ['password']
+      #   )
+      #   safety.check_request!(message: "Hello", estimated_cost: 0.01)
+      class Manager
+        include LanguageOperator::Loggable
+
+        attr_reader :budget_tracker, :rate_limiter, :content_filter, :audit_logger
+
+        def initialize(config = {})
+          @config = config
+          @enabled = config.fetch(:enabled, true)
+
+          # Initialize components based on configuration
+          @budget_tracker = if budget_config_present?
+                              BudgetTracker.new(
+                                daily_budget: config[:daily_budget],
+                                hourly_budget: config[:hourly_budget],
+                                token_budget: config[:token_budget]
+                              )
+                            end
+
+          @rate_limiter = if rate_limit_config_present?
+                            RateLimiter.new(
+                              requests_per_minute: config[:requests_per_minute],
+                              requests_per_hour: config[:requests_per_hour],
+                              requests_per_day: config[:requests_per_day]
+                            )
+                          end
+
+          @content_filter = if content_filter_config_present?
+                              ContentFilter.new(
+                                blocked_patterns: config[:blocked_patterns] || [],
+                                blocked_topics: config[:blocked_topics] || [],
+                                case_sensitive: config[:case_sensitive] || false
+                              )
+                            end
+
+          @audit_logger = (AuditLogger.new if config.fetch(:audit_logging, true))
+
+          logger.info('Safety manager initialized',
+                      enabled: @enabled,
+                      budget_tracking: !@budget_tracker.nil?,
+                      rate_limiting: !@rate_limiter.nil?,
+                      content_filtering: !@content_filter.nil?,
+                      audit_logging: !@audit_logger.nil?)
+        end
+
+        # Check if safety checks are enabled
+        #
+        # @return [Boolean]
+        def enabled?
+          @enabled
+        end
+
+        # Perform all pre-request safety checks
+        #
+        # @param message [String] The message being sent
+        # @param estimated_cost [Float] Estimated cost of the request
+        # @param estimated_tokens [Integer] Estimated token count
+        # @raise [BudgetTracker::BudgetExceededError] If budget exceeded
+        # @raise [RateLimiter::RateLimitExceededError] If rate limit exceeded
+        # @raise [ContentFilter::ContentBlockedError] If content blocked
+        def check_request!(message:, estimated_cost: 0.0, estimated_tokens: 0)
+          return unless @enabled
+
+          begin
+            # Check content filter (input)
+            if @content_filter
+              @content_filter.check_content!(message, direction: :input)
+              logger.debug('Input content check passed')
+            end
+
+            # Check budget
+            if @budget_tracker
+              @budget_tracker.check_budget!(
+                estimated_cost: estimated_cost,
+                estimated_tokens: estimated_tokens
+              )
+              logger.debug('Budget check passed')
+            end
+
+            # Check rate limit
+            if @rate_limiter
+              @rate_limiter.check_rate_limit!
+              logger.debug('Rate limit check passed')
+            end
+
+            logger.debug('All safety checks passed')
+          rescue BudgetTracker::BudgetExceededError,
+                 RateLimiter::RateLimitExceededError,
+                 ContentFilter::ContentBlockedError => e
+            # Log to audit
+            @audit_logger&.log_blocked_request(
+              reason: e.class.name,
+              details: {
+                message: e.message,
+                message_preview: message[0..100],
+                estimated_cost: estimated_cost,
+                estimated_tokens: estimated_tokens
+              }
+            )
+            raise
+          end
+        end
+
+        # Check response content
+        #
+        # @param response [String] The LLM response
+        # @raise [ContentFilter::ContentBlockedError] If content blocked
+        def check_response!(response)
+          return unless @enabled
+          return unless @content_filter
+
+          begin
+            @content_filter.check_content!(response, direction: :output)
+            logger.debug('Output content check passed')
+          rescue ContentFilter::ContentBlockedError => e
+            @audit_logger&.log_content_filter_event(
+              event: 'output_blocked',
+              details: {
+                message: e.message,
+                response_preview: response[0..100]
+              }
+            )
+            raise
+          end
+        end
+
+        # Record successful request
+        #
+        # @param cost [Float] Actual cost
+        # @param tokens [Integer] Actual token count
+        def record_request(cost:, tokens:)
+          return unless @enabled
+
+          @budget_tracker&.record_spending(cost: cost, tokens: tokens)
+          @rate_limiter&.record_request
+
+          @audit_logger&.log_budget_event(
+            event: 'request_completed',
+            details: {
+              cost: cost.round(4),
+              tokens: tokens,
+              budget_status: @budget_tracker&.status
+            }
+          )
+        end
+
+        # Get current safety status
+        #
+        # @return [Hash] Safety status information
+        def status
+          {
+            enabled: @enabled,
+            budget: @budget_tracker&.status,
+            rate_limits: @rate_limiter&.status,
+            content_filter: {
+              enabled: !@content_filter.nil?,
+              patterns: @config[:blocked_patterns]&.length || 0,
+              topics: @config[:blocked_topics]&.length || 0
+            }
+          }
+        end
+
+        private
+
+        def logger_component
+          'Safety::Manager'
+        end
+
+        def budget_config_present?
+          @config[:daily_budget] || @config[:hourly_budget] || @config[:token_budget]
+        end
+
+        def rate_limit_config_present?
+          @config[:requests_per_minute] || @config[:requests_per_hour] || @config[:requests_per_day]
+        end
+
+        def content_filter_config_present?
+          @config[:blocked_patterns]&.any? ||
+            @config[:blocked_topics]&.any?
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/agent/safety/rate_limiter.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative '../../logger'
+require_relative '../../loggable'
+
+module LanguageOperator
+  module Agent
+    module Safety
+      # Rate Limiter for enforcing request limits
+      #
+      # Enforces per-agent rate limiting to prevent runaway requests.
+      #
+      # @example
+      #   limiter = RateLimiter.new(requests_per_minute: 10, requests_per_hour: 100)
+      #   limiter.check_rate_limit!
+      class RateLimiter
+        include LanguageOperator::Loggable
+
+        class RateLimitExceededError < StandardError; end
+
+        def initialize(requests_per_minute: nil, requests_per_hour: nil, requests_per_day: nil)
+          @requests_per_minute = requests_per_minute&.to_i
+          @requests_per_hour = requests_per_hour&.to_i
+          @requests_per_day = requests_per_day&.to_i
+
+          @minute_requests = []
+          @hour_requests = []
+          @day_requests = []
+
+          logger.info('Rate limiter initialized',
+                      per_minute: @requests_per_minute,
+                      per_hour: @requests_per_hour,
+                      per_day: @requests_per_day)
+        end
+
+        # Check if a request would exceed rate limits
+        #
+        # @raise [RateLimitExceededError] If rate limit would be exceeded
+        def check_rate_limit!
+          now = Time.now
+
+          # Clean up old requests
+          cleanup_old_requests(now)
+
+          # Check per-minute limit
+          if @requests_per_minute && @minute_requests.length >= @requests_per_minute
+            oldest = @minute_requests.first
+            wait_time = 60 - (now - oldest)
+            logger.error('Per-minute rate limit exceeded',
+                         current: @minute_requests.length,
+                         limit: @requests_per_minute,
+                         wait_time: wait_time.round(1))
+            raise RateLimitExceededError,
+                  "Per-minute rate limit exceeded: #{@minute_requests.length}/#{@requests_per_minute} " \
+                  "(retry in #{wait_time.round(1)}s)"
+          end
+
+          # Check per-hour limit
+          if @requests_per_hour && @hour_requests.length >= @requests_per_hour
+            oldest = @hour_requests.first
+            wait_time = 3600 - (now - oldest)
+            logger.error('Per-hour rate limit exceeded',
+                         current: @hour_requests.length,
+                         limit: @requests_per_hour,
+                         wait_time: (wait_time / 60).round(1))
+            raise RateLimitExceededError,
+                  "Per-hour rate limit exceeded: #{@hour_requests.length}/#{@requests_per_hour} " \
+                  "(retry in #{(wait_time / 60).round(1)}m)"
+          end
+
+          # Check per-day limit
+          if @requests_per_day && @day_requests.length >= @requests_per_day
+            oldest = @day_requests.first
+            wait_time = 86_400 - (now - oldest)
+            logger.error('Per-day rate limit exceeded',
+                         current: @day_requests.length,
+                         limit: @requests_per_day,
+                         wait_time: (wait_time / 3600).round(1))
+            raise RateLimitExceededError,
+                  "Per-day rate limit exceeded: #{@day_requests.length}/#{@requests_per_day} " \
+                  "(retry in #{(wait_time / 3600).round(1)}h)"
+          end
+
+          logger.debug('Rate limit check passed',
+                       minute_requests: @minute_requests.length,
+                       hour_requests: @hour_requests.length,
+                       day_requests: @day_requests.length)
+        end
+
+        # Record a request
+        def record_request
+          now = Time.now
+          cleanup_old_requests(now)
+
+          @minute_requests << now
+          @hour_requests << now
+          @day_requests << now
+
+          logger.debug('Request recorded',
+                       minute_count: @minute_requests.length,
+                       hour_count: @hour_requests.length,
+                       day_count: @day_requests.length)
+        end
+
+        # Get current rate limit status
+        #
+        # @return [Hash] Rate limit status information
+        def status
+          now = Time.now
+          cleanup_old_requests(now)
+
+          {
+            per_minute: {
+              requests: @minute_requests.length,
+              limit: @requests_per_minute,
+              remaining: @requests_per_minute ? (@requests_per_minute - @minute_requests.length) : nil
+            },
+            per_hour: {
+              requests: @hour_requests.length,
+              limit: @requests_per_hour,
+              remaining: @requests_per_hour ? (@requests_per_hour - @hour_requests.length) : nil
+            },
+            per_day: {
+              requests: @day_requests.length,
+              limit: @requests_per_day,
+              remaining: @requests_per_day ? (@requests_per_day - @day_requests.length) : nil
+            }
+          }
+        end
+
+        private
+
+        def logger_component
+          'Safety::RateLimiter'
+        end
+
+        def cleanup_old_requests(now)
+          # Remove requests older than 1 minute
+          @minute_requests.reject! { |t| (now - t) > 60 }
+
+          # Remove requests older than 1 hour
+          @hour_requests.reject! { |t| (now - t) > 3600 }
+
+          # Remove requests older than 1 day
+          @day_requests.reject! { |t| (now - t) > 86_400 }
+        end
+      end
+    end
+  end
+end