agentbill-sdk 2.0.1 → 7.17.0

data/lib/agentbill/signals.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'net/http'
+require 'json'
+require 'uri'
+require 'time'
+
+require_relative 'distributed'
+
+module AgentBill
+  # Signal module for tracking business events and linking revenue to AI traces.
+  module Signals
+    BASE_URL = 'https://api.agentbill.io'
+    VERSION = '7.16.1'
+
+    @config = {}
+
+    class << self
+      attr_accessor :config
+
+      def set_config(options)
+        @config = options
+      end
+
+      def get_config
+        @config
+      end
+    end
+  end
+
+  class << self
+    # Emit a business signal/event and link it to AI traces.
+    #
+    # @param event_name [String] Name of the business event
+    # @param options [Hash] Signal options
+    # @option options [Float] :revenue Revenue amount
+    # @option options [Hash] :metadata Additional metadata
+    # @option options [String] :customer_id Customer ID
+    # @option options [String] :session_id Session ID
+    # @option options [String] :trace_id Trace ID to link to
+    # @option options [String] :span_id Span ID to link to
+    # @option options [String] :parent_span_id Parent span ID
+    # @option options [String] :currency Currency (default: USD)
+    # @option options [String] :event_type Event type
+    # @option options [Float] :event_value Event value
+    # @option options [String] :order_id Order ID to link to (v7.8.0)
+    # @option options [String] :order_external_id External order ID (v7.8.0)
+    #
+    # @return [Hash] Result with success status
+    #
+    # @example
+    #   AgentBill.signal('purchase', revenue: 99.99, metadata: { product_id: 'prod-123' })
+    def signal(event_name, **options)
+      config = Signals.get_config
+
+      api_key = config[:api_key]
+      raise ArgumentError, 'AgentBill not initialized. Call AgentBill.init() first or use AgentBill.tracing context.' unless api_key
+
+      effective_customer_id = options[:customer_id] || config[:customer_id]
+
+      # Auto-detect trace context if not provided
+      ctx = Distributed.get_trace_context
+      trace_id = options[:trace_id]
+      parent_span_id = options[:parent_span_id]
+
+      if ctx
+        trace_id ||= ctx[:trace_id]
+        parent_span_id ||= ctx[:span_id] unless parent_span_id
+      end
+
+      generated_span_id = options[:span_id] || SecureRandom.hex(8)
+      generated_trace_id = trace_id || SecureRandom.hex(16)
+      now_ns = (Time.now.to_f * 1_000_000_000).to_i
+
+      # Build OTEL-compliant span attributes
+      attributes = [
+        { key: 'agentbill.event_name', value: { stringValue: event_name } },
+        { key: 'agentbill.is_business_event', value: { boolValue: true } }
+      ]
+
+      attributes << { key: 'agentbill.customer_id', value: { stringValue: effective_customer_id } } if effective_customer_id
+      attributes << { key: 'agentbill.agent_id', value: { stringValue: config[:agent_id] } } if config[:agent_id]
+
+      if options[:revenue]
+        attributes << { key: 'agentbill.revenue', value: { doubleValue: options[:revenue] } }
+        attributes << { key: 'agentbill.currency', value: { stringValue: options[:currency] || 'USD' } }
+      end
+
+      attributes << { key: 'agentbill.event_value', value: { doubleValue: options[:event_value] } } if options[:event_value]
+      attributes << { key: 'agentbill.event_type', value: { stringValue: options[:event_type] } } if options[:event_type]
+      attributes << { key: 'agentbill.session_id', value: { stringValue: options[:session_id] } } if options[:session_id]
+      attributes << { key: 'agentbill.parent_span_id', value: { stringValue: parent_span_id } } if parent_span_id
+      # v7.8.0: Order linking
+      attributes << { key: 'agentbill.order_id', value: { stringValue: options[:order_id] } } if options[:order_id]
+      attributes << { key: 'agentbill.order_external_id', value: { stringValue: options[:order_external_id] } } if options[:order_external_id]
+      attributes << { key: 'agentbill.metadata', value: { stringValue: JSON.generate(options[:metadata]) } } if options[:metadata]
+
+      # Build OTEL payload
+      payload = {
+        resourceSpans: [{
+          resource: {
+            attributes: [
+              { key: 'service.name', value: { stringValue: 'agentbill-ruby-sdk' } },
+              { key: 'agentbill.customer_id', value: { stringValue: effective_customer_id || '' } },
+              { key: 'agentbill.agent_id', value: { stringValue: config[:agent_id] || '' } }
+            ]
+          },
+          scopeSpans: [{
+            scope: { name: 'agentbill.signals', version: Signals::VERSION },
+            spans: [{
+              traceId: generated_trace_id,
+              spanId: generated_span_id,
+              parentSpanId: parent_span_id || '',
+              name: 'agentbill.trace.signal',
+              kind: 1,
+              startTimeUnixNano: now_ns.to_s,
+              endTimeUnixNano: now_ns.to_s,
+              attributes: attributes,
+              status: { code: 1 }
+            }]
+          }]
+        }]
+      }
+
+      base_url = config[:base_url] || Signals::BASE_URL
+      debug = config[:debug] || false
+
+      begin
+        url = URI("#{base_url}/functions/v1/otel-collector")
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = true
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(url)
+        request['x-api-key'] = api_key
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(payload)
+
+        response = http.request(request)
+
+        response_data = {}
+        body_success = true
+        begin
+          response_data = JSON.parse(response.body)
+          body_success = response_data['success'] != false
+        rescue StandardError
+          # If can't parse JSON, fall back to HTTP status check
+        end
+
+        is_success = response.code.to_i == 200 && body_success
+
+        if debug
+          if is_success
+            puts "[AgentBill] ✓ Signal '#{event_name}' tracked via OTEL"
+            puts "[AgentBill]   Revenue: $#{'%.2f' % options[:revenue]} #{options[:currency] || 'USD'}" if options[:revenue]
+            puts "[AgentBill]   Trace ID: #{generated_trace_id}"
+          else
+            puts "[AgentBill] ⚠️ Signal tracking failed: #{response_data['error'] || response.message}"
+            response_data['errors']&.each { |err| puts "[AgentBill]   - #{err}" }
+          end
+        end
+
+        {
+          success: is_success,
+          status_code: response.code.to_i,
+          trace_id: generated_trace_id,
+          span_id: generated_span_id,
+          error: is_success ? nil : response_data['error'],
+          errors: is_success ? nil : response_data['errors']
+        }
+      rescue StandardError => e
+        puts "[AgentBill] ⚠️ Signal tracking error: #{e.message}" if debug
+        {
+          success: false,
+          error: e.message,
+          trace_id: generated_trace_id
+        }
+      end
+    end
+
+    # Track a conversion event for revenue attribution.
+    #
+    # @param event_type [String] Type of conversion
+    # @param event_value [Float] Value of the conversion
+    # @param options [Hash] Additional options
+    #
+    # @return [Hash] Result with status
+    def track_conversion(event_type, event_value, **options)
+      signal(
+        "conversion_#{event_type}",
+        revenue: event_value,
+        event_type: event_type,
+        event_value: event_value,
+        **options
+      )
+    end
+  end
+end

data/lib/agentbill/tracer.rb

@@ -1,15 +1,17 @@
 require 'net/http'
 require 'json'
 require 'securerandom'
+require_relative 'distributed'
 
 module AgentBill
   class Span
-    attr_accessor :name, :trace_id, :span_id, :attributes, :start_time, :end_time, :status
+    attr_accessor :name, :trace_id, :span_id, :parent_span_id, :attributes, :start_time, :end_time, :status
 
-    def initialize(name, trace_id, span_id, attributes)
+    def initialize(name, trace_id, span_id, parent_span_id, attributes)
       @name = name
       @trace_id = trace_id
       @span_id = span_id
+      @parent_span_id = parent_span_id
       @attributes = attributes
       @start_time = (Time.now.to_f * 1_000_000_000).to_i
       @end_time = nil
@@ -30,9 +32,21 @@ module AgentBill
   end
 
   class Tracer
+    # OpenTelemetry tracer for AgentBill
+    #
+    # IMPORTANT: This tracer integrates with Distributed module for trace context.
+    # - If a trace context exists (via Distributed.get_trace_context), it reuses the trace_id
+    # - Always generates a new span_id for each span
+    # - Updates the global trace context so get_trace_context returns correct values
+    #
+    # This ensures that:
+    # 1. get_trace_context always returns the trace_id that matches what's sent to the portal
+    # 2. Distributed tracing works correctly across services
+    # 3. Parent-child span relationships are properly maintained
+
     def initialize(config)
       @config = config
-      @base_url = config[:base_url] || 'https://uenhjwdtnxtchlmqarjo.supabase.co'
+      @base_url = config[:base_url] || 'https://api.agentbill.io'
       @api_key = config[:api_key]
       @customer_id = config[:customer_id]
       @debug = config[:debug] || false
@@ -40,14 +54,37 @@ module AgentBill
     end
 
     def start_span(name, attributes)
-      trace_id = SecureRandom.hex(16)
+      # Check for existing trace context from Distributed module
+      ctx = Distributed.get_trace_context
+      parent_span_id = nil
+
+      if ctx
+        # Reuse existing trace_id for correlation
+        trace_id = ctx[:trace_id]
+        parent_span_id = ctx[:span_id]
+        puts "[AgentBill Tracer] Using existing trace context: trace_id=#{trace_id[0..7]}..." if @debug
+      else
+        # Generate new trace_id for new trace
+        trace_id = SecureRandom.hex(16)
+        puts "[AgentBill Tracer] Creating new trace: trace_id=#{trace_id[0..7]}..." if @debug
+      end
+
+      # Always generate new span_id for this span
       span_id = SecureRandom.hex(8)
 
+      # Update global trace context so get_trace_context returns correct values
+      Distributed.set_trace_context(trace_id, span_id)
+
       attributes['service.name'] = 'agentbill-ruby-sdk'
       attributes['customer.id'] = @customer_id if @customer_id
 
-      span = Span.new(name, trace_id, span_id, attributes)
+      span = Span.new(name, trace_id, span_id, parent_span_id, attributes)
       @spans << span
+
+      if @debug
+        puts "[AgentBill Tracer] Started span: #{name}, trace_id=#{trace_id[0..7]}..., span_id=#{span_id[0..7]}..."
+      end
+
       span
     end
 
@@ -61,7 +98,7 @@ module AgentBill
       http.use_ssl = true
 
       request = Net::HTTP::Post.new(uri.path)
-      request['Authorization'] = "Bearer #{@api_key}"
+      request['X-API-Key'] = @api_key
       request['Content-Type'] = 'application/json'
       request.body = payload.to_json
 
@@ -77,16 +114,31 @@ module AgentBill
     private
 
     def build_otlp_payload
+      # Build resource attributes - agent_id and customer_id must be sent here
+      # for the otel-collector to extract them correctly
+      resource_attrs = [
+        { key: 'service.name', value: { stringValue: 'agentbill-ruby-sdk' } },
+        { key: 'service.version', value: { stringValue: '6.8.8' } }
+      ]
+      
+      # Add customer_id as resource attribute if configured
+      if @customer_id
+        resource_attrs << { key: 'customer.id', value: { stringValue: @customer_id } }
+      end
+      
+      # Add agent_id as resource attribute if configured
+      agent_id = @config[:agent_id]
+      if agent_id
+        resource_attrs << { key: 'agent.id', value: { stringValue: agent_id } }
+      end
+      
       {
         resourceSpans: [{
           resource: {
-            attributes: [
-              { key: 'service.name', value: { stringValue: 'agentbill-ruby-sdk' } },
-              { key: 'service.version', value: { stringValue: '1.0.0' } }
-            ]
+            attributes: resource_attrs
           },
           scopeSpans: [{
-            scope: { name: 'agentbill', version: '1.0.0' },
+            scope: { name: 'agentbill', version: '6.8.8' },
             spans: @spans.map { |span| span_to_otlp(span) }
           }]
         }]
@@ -94,7 +146,7 @@ module AgentBill
     end
 
     def span_to_otlp(span)
-      {
+      otlp_span = {
         traceId: span.trace_id,
         spanId: span.span_id,
         name: span.name,
@@ -104,6 +156,11 @@ module AgentBill
         attributes: span.attributes.map { |k, v| { key: k, value: value_to_otlp(v) } },
         status: span.status
       }
+
+      # Add parent span ID if this is a child span
+      otlp_span[:parentSpanId] = span.parent_span_id if span.parent_span_id
+
+      otlp_span
     end
 
     def value_to_otlp(value)

data/lib/agentbill/tracing.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'net/http'
+require 'json'
+require 'uri'
+
+require_relative 'exceptions'
+require_relative 'distributed'
+require_relative 'signals'
+
+module AgentBill
+  # Context manager for tracking AI operations with Cost Guard protection.
+  #
+  # Implements the flow from the sequence diagram:
+  # 1. Pre-validate with ai-cost-guard-router
+  # 2. If blocked, raise BudgetExceededError
+  # 3. If allowed, execute AI calls
+  # 4. After completion, send spans to otel-collector
+  class TracingContext
+    attr_reader :trace_id, :span_id, :parent_span_id, :request_id, :start_time, :validation_result
+
+    BASE_URL = 'https://api.agentbill.io'
+    VERSION = '7.16.1'
+
+    def initialize(options = {})
+      @api_key = options[:api_key] || ENV['AGENTBILL_API_KEY']
+      @customer_id = options[:customer_id]
+      @daily_budget = options[:daily_budget]
+      @monthly_budget = options[:monthly_budget]
+      @agent_id = options[:agent_id]
+      @base_url = options[:base_url] || BASE_URL
+      @debug = options[:debug] || false
+      @model = options[:model] || 'gpt-4'
+      @estimated_tokens = options[:estimated_tokens] || 1000
+
+      @trace_id = nil
+      @span_id = nil
+      @parent_span_id = nil
+      @request_id = nil
+      @start_time = nil
+      @validation_result = nil
+      @spans = []
+    end
+
+    def enter
+      generate_ids
+      @start_time = Time.now
+
+      # Set global config for signal() function
+      Signals.set_config(
+        api_key: @api_key,
+        customer_id: @customer_id,
+        agent_id: @agent_id,
+        base_url: @base_url,
+        debug: @debug
+      )
+
+      # CRITICAL: Pre-validate with Cost Guard
+      @validation_result = validate_budget
+
+      # CRITICAL: Raise exception if not allowed
+      unless @validation_result['allowed']
+        reason = @validation_result['reason'] || 'Request blocked by Cost Guard'
+        reason_lower = reason.downcase
+
+        if reason_lower.include?('budget')
+          raise BudgetExceededError.new(reason, @validation_result)
+        elsif reason_lower.include?('rate')
+          raise RateLimitExceededError.new(reason, @validation_result)
+        else
+          raise PolicyViolationError.new(reason, @validation_result)
+        end
+      end
+
+      self
+    end
+
+    def exit(error = nil)
+      end_time = Time.now
+
+      # Add root span for the entire context
+      add_span(
+        'agentbill_tracing',
+        {
+          'customer_id' => @customer_id,
+          'agent_id' => @agent_id,
+          'request_id' => @request_id,
+          'error' => error&.message
+        },
+        (@start_time.to_f * 1_000_000_000).to_i,
+        (end_time.to_f * 1_000_000_000).to_i,
+        error ? 1 : 0
+      )
+
+      # Export spans to otel-collector
+      export_spans
+
+      # Clear trace context
+      Distributed.clear_trace_context
+    end
+
+    def add_span(name, attributes, start_time_ns, end_time_ns, status = 0)
+      span = {
+        'trace_id' => @trace_id,
+        'span_id' => SecureRandom.hex(8),
+        'parent_span_id' => @span_id,
+        'name' => name,
+        'attributes' => attributes,
+        'start_time_unix_nano' => start_time_ns,
+        'end_time_unix_nano' => end_time_ns,
+        'status' => { 'code' => status }
+      }
+      @spans << span
+    end
+
+    def cache_response(model, messages, response_content, input_tokens = 0, output_tokens = 0)
+      prompt_hash = hash_prompt(messages)
+      url = URI("#{@base_url}/functions/v1/cache-ai-response")
+
+      payload = {
+        api_key: @api_key,
+        prompt_hash: prompt_hash,
+        response_content: response_content,
+        model: model,
+        prompt_content: messages.is_a?(String) ? messages : JSON.generate(messages),
+        tokens_used: input_tokens + output_tokens,
+        cacheable: true,
+        ttl_hours: 24,
+        customer_id: @customer_id,
+        request_id: @request_id
+      }
+
+      begin
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = true
+        http.read_timeout = 5
+
+        request = Net::HTTP::Post.new(url)
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(payload)
+
+        response = http.request(request)
+        log("✓ Cached response: #{response.code}") if @debug
+      rescue StandardError => e
+        log("⚠️ Cache error (non-blocking): #{e.message}") if @debug
+      end
+    end
+
+    private
+
+    def log(message)
+      puts "[AgentBill] #{message}" if @debug
+    end
+
+    def generate_ids
+      existing = Distributed.get_trace_context
+
+      if existing && existing[:trace_id]
+        @trace_id = existing[:trace_id]
+        @parent_span_id = existing[:span_id]
+      else
+        @trace_id = SecureRandom.hex(16)
+        @parent_span_id = nil
+      end
+
+      @span_id = SecureRandom.hex(8)
+      Distributed.set_trace_context(@trace_id, @span_id)
+    end
+
+    def validate_budget
+      url = URI("#{@base_url}/functions/v1/ai-cost-guard-router")
+
+      payload = {
+        api_key: @api_key,
+        customer_id: @customer_id,
+        model: @model,
+        messages: [],
+        estimated_tokens: @estimated_tokens
+      }
+
+      payload[:daily_budget_override] = @daily_budget if @daily_budget
+      payload[:monthly_budget_override] = @monthly_budget if @monthly_budget
+      payload[:agent_id] = @agent_id if @agent_id
+
+      begin
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = true
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(url)
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(payload)
+
+        response = http.request(request)
+
+        if response.code.to_i >= 500
+          log('⚠️ Router server error (failing open)') if @debug
+          return { 'allowed' => true, 'reason' => 'Router server error (failed open)' }
+        end
+
+        if response.code.to_i >= 400
+          log("❌ Router rejected: #{response.body}") if @debug
+          return { 'allowed' => false, 'reason' => response.body }
+        end
+
+        result = JSON.parse(response.body)
+        @request_id = result['request_id']
+
+        if @debug
+          if result['allowed']
+            log('✓ Budget validation passed')
+          else
+            log("❌ Budget validation failed: #{result['reason']}")
+          end
+        end
+
+        result
+      rescue StandardError => e
+        log("⚠️ Router network error: #{e.message} (failing open)") if @debug
+        { 'allowed' => true, 'reason' => 'Router network error (failed open)' }
+      end
+    end
+
+    def export_spans
+      return if @spans.empty?
+
+      url = URI("#{@base_url}/functions/v1/otel-collector")
+
+      resource_attributes = [
+        { key: 'service.name', value: { stringValue: 'agentbill-ruby-sdk' } },
+        { key: 'service.version', value: { stringValue: VERSION } }
+      ]
+
+      resource_attributes << { key: 'customer.id', value: { stringValue: @customer_id } } if @customer_id
+      resource_attributes << { key: 'agent.id', value: { stringValue: @agent_id } } if @agent_id
+
+      otlp_spans = @spans.map do |span|
+        otlp_span = {
+          traceId: span['trace_id'],
+          spanId: span['span_id'],
+          name: span['name'],
+          kind: 1,
+          startTimeUnixNano: span['start_time_unix_nano'].to_s,
+          endTimeUnixNano: span['end_time_unix_nano'].to_s,
+          attributes: (span['attributes'] || {}).map do |k, v|
+            value = case v
+                    when String then { stringValue: v }
+                    when Integer then { intValue: v }
+                    when Float then { doubleValue: v }
+                    else { stringValue: v.to_s }
+                    end
+            { key: k, value: value }
+          end,
+          status: span['status']
+        }
+        otlp_span[:parentSpanId] = span['parent_span_id'] if span['parent_span_id']
+        otlp_span
+      end
+
+      payload = {
+        resourceSpans: [{
+          resource: { attributes: resource_attributes },
+          scopeSpans: [{
+            scope: { name: 'agentbill', version: VERSION },
+            spans: otlp_spans
+          }]
+        }]
+      }
+
+      begin
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = true
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(url)
+        request['Content-Type'] = 'application/json'
+        request['X-API-Key'] = @api_key
+        request.body = JSON.generate(payload)
+
+        response = http.request(request)
+
+        if @debug
+          if response.code.to_i == 200
+            log("✓ Exported #{@spans.length} spans to otel-collector")
+          else
+            log("⚠️ Span export failed: #{response.code}")
+          end
+        end
+      rescue StandardError => e
+        log("⚠️ Span export error: #{e.message}") if @debug
+      end
+    end
+
+    def hash_prompt(messages)
+      content = messages.is_a?(String) ? messages : JSON.generate(messages)
+      Digest::SHA256.hexdigest(content)
+    end
+  end
+
+  class << self
+    # Context manager for tracking AI operations with Cost Guard protection.
+    #
+    # @example
+    #   AgentBill.tracing(customer_id: 'cust-123', api_key: 'ab_xxx') do |ctx|
+    #     response = openai.chat.completions.create(...)
+    #     AgentBill.signal('chat_completed', revenue: 0.50)
+    #   end
+    #
+    # @raise [BudgetExceededError] If daily/monthly budget would be exceeded
+    # @raise [RateLimitExceededError] If rate limits would be exceeded
+    # @raise [PolicyViolationError] If other policy constraints are violated
+    def tracing(customer_id:, api_key: nil, daily_budget: nil, monthly_budget: nil,
+                agent_id: nil, base_url: nil, debug: false, model: nil, estimated_tokens: 1000)
+      effective_api_key = api_key || ENV['AGENTBILL_API_KEY']
+      raise ArgumentError, 'api_key is required. Provide it as argument or set AGENTBILL_API_KEY env var.' unless effective_api_key
+
+      ctx = TracingContext.new(
+        api_key: effective_api_key,
+        customer_id: customer_id,
+        daily_budget: daily_budget,
+        monthly_budget: monthly_budget,
+        agent_id: agent_id,
+        base_url: base_url,
+        debug: debug,
+        model: model,
+        estimated_tokens: estimated_tokens
+      )
+
+      begin
+        ctx.enter
+        yield ctx
+      rescue BudgetExceededError, RateLimitExceededError, PolicyViolationError
+        raise
+      rescue StandardError => e
+        ctx.exit(e)
+        raise
+      else
+        ctx.exit
+      end
+    end
+  end
+end

data/lib/agentbill/version.rb

@@ -1,3 +1,3 @@
 module AgentBill
-  VERSION = "2.0.1"
+  VERSION = "7.17.0"
 end