agentbill-sdk 5.0.1 → 9.4.0

data/lib/agentbill/customers.rb

@@ -0,0 +1,164 @@
+# AgentBill Customers Resource - CRUD operations
+# 
+# Example:
+#   ab = AgentBill::Client.init(api_key: 'agb_...')
+#   
+#   # List customers
+#   result = ab.customers.list(limit: 10)
+#   
+#   # Create customer
+#   customer = ab.customers.create(name: 'Acme', email: 'a@b.com')
+#   
+#   # Get customer by ID
+#   customer = ab.customers.get('cust-123')
+#   
+#   # Update customer
+#   customer = ab.customers.update('cust-123', name: 'Acme Inc')
+#   
+#   # Delete customer
+#   ab.customers.delete('cust-123')
+
+require 'net/http'
+require 'json'
+
+module AgentBill
+  class CustomersResource
+    def initialize(config)
+      @config = config
+      @base_url = config[:base_url] || 'https://api.agentbill.io'
+      @api_key = config[:api_key]
+      @debug = config[:debug] || false
+    end
+
+    # List customers with pagination and search
+    #
+    # @param limit [Integer] Number of customers to return (default: 50)
+    # @param offset [Integer] Offset for pagination (default: 0)
+    # @param search [String, nil] Search term to filter by name or email
+    # @return [Hash] Hash with 'data' (list of customers) and 'pagination' info
+    def list(limit: 50, offset: 0, search: nil)
+      uri = URI("#{@base_url}/functions/v1/api-customers")
+      params = { limit: limit.to_s, offset: offset.to_s }
+      params[:search] = search if search
+      uri.query = URI.encode_www_form(params)
+
+      response = make_request(:get, uri)
+      handle_response(response, 'list customers')
+    end
+
+    # Create a new customer
+    #
+    # @param name [String] Customer name (required)
+    # @param email [String] Customer email (required)
+    # @param phone [String, nil] Phone number
+    # @param website [String, nil] Website URL
+    # @param external_id [String, nil] Your external ID for this customer
+    # @param metadata [Hash, nil] Additional metadata
+    # @return [Hash] Created customer object
+    def create(name:, email:, phone: nil, website: nil, external_id: nil, metadata: nil)
+      uri = URI("#{@base_url}/functions/v1/api-customers")
+      
+      payload = { name: name, email: email }
+      payload[:phone] = phone if phone
+      payload[:website] = website if website
+      payload[:external_id] = external_id if external_id
+      payload[:metadata] = metadata if metadata
+
+      response = make_request(:post, uri, payload)
+      handle_response(response, 'create customer')
+    end
+
+    # Get a customer by ID or external_id
+    #
+    # @param customer_id [String] Customer UUID or external_id
+    # @param by_external_id [Boolean] If true, treat customer_id as external_id
+    # @return [Hash] Customer object
+    def get(customer_id, by_external_id: false)
+      uri = URI("#{@base_url}/functions/v1/api-customers")
+      params = by_external_id ? { external_id: customer_id } : { id: customer_id }
+      uri.query = URI.encode_www_form(params)
+
+      response = make_request(:get, uri)
+      result = handle_response(response, 'get customer')
+      
+      if result['data'].is_a?(Array)
+        raise "Customer not found" if result['data'].empty?
+        return result['data'][0]
+      end
+      result
+    end
+
+    # Update a customer
+    #
+    # @param customer_id [String] Customer UUID
+    # @param name [String, nil] New name
+    # @param email [String, nil] New email
+    # @param phone [String, nil] New phone
+    # @param website [String, nil] New website
+    # @param metadata [Hash, nil] New metadata (replaces existing)
+    # @return [Hash] Updated customer object
+    def update(customer_id, name: nil, email: nil, phone: nil, website: nil, metadata: nil)
+      uri = URI("#{@base_url}/functions/v1/api-customers")
+      
+      payload = { id: customer_id }
+      payload[:name] = name if name
+      payload[:email] = email if email
+      payload[:phone] = phone if phone
+      payload[:website] = website if website
+      payload[:metadata] = metadata if metadata
+
+      response = make_request(:patch, uri, payload)
+      handle_response(response, 'update customer')
+    end
+
+    # Delete a customer
+    #
+    # @param customer_id [String] Customer UUID to delete
+    def delete(customer_id)
+      uri = URI("#{@base_url}/functions/v1/api-customers")
+      payload = { id: customer_id }
+
+      response = make_request(:delete, uri, payload)
+      handle_response(response, 'delete customer')
+    end
+
+    private
+
+    def make_request(method, uri, payload = nil)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = 30
+
+      case method
+      when :get
+        request = Net::HTTP::Get.new(uri)
+      when :post
+        request = Net::HTTP::Post.new(uri.path)
+        request.body = payload.to_json if payload
+      when :patch
+        request = Net::HTTP::Patch.new(uri.path)
+        request.body = payload.to_json if payload
+      when :delete
+        request = Net::HTTP::Delete.new(uri.path)
+        request.body = payload.to_json if payload
+      end
+
+      request['Content-Type'] = 'application/json'
+      request['X-API-Key'] = @api_key
+
+      http.request(request)
+    end
+
+    def handle_response(response, operation)
+      body = response.body ? JSON.parse(response.body) : {}
+      
+      unless %w[200 201 204].include?(response.code)
+        error_msg = body['error'] || "Failed to #{operation}"
+        raise error_msg
+      end
+
+      puts "[AgentBill] #{operation} successful" if @debug
+      body
+    end
+  end
+end

data/lib/agentbill/distributed.rb

@@ -0,0 +1,109 @@
+# AgentBill Distributed Tracing for Ruby
+#
+# Functions for cross-service trace propagation and correlation.
+# This is the SINGLE SOURCE OF TRUTH for trace context in the Ruby SDK.
+
+module AgentBill
+  module Distributed
+    # Thread-local storage for trace context
+    @trace_context = {}
+    @tracing_token = nil
+
+    class << self
+      # Get the current trace context (trace_id, span_id)
+      # This is the SINGLE SOURCE OF TRUTH used by the tracer.
+      def get_trace_context
+        Thread.current[:agentbill_trace_context]
+      end
+
+      # Set the trace context manually.
+      # Called by the tracer after starting a span.
+      def set_trace_context(trace_id, span_id)
+        Thread.current[:agentbill_trace_context] = {
+          trace_id: trace_id,
+          span_id: span_id
+        }
+      end
+
+      # Clear the current trace context
+      def clear_trace_context
+        Thread.current[:agentbill_trace_context] = nil
+        Thread.current[:agentbill_tracing_token] = nil
+      end
+
+      # Get the current tracing token
+      def get_tracing_token
+        Thread.current[:agentbill_tracing_token]
+      end
+
+      # Generate a new tracing token for distributed trace propagation
+      def generate_tracing_token
+        ctx = get_trace_context
+        random_suffix = SecureRandom.hex(4)
+
+        if ctx
+          token = "agentbill-v1-#{ctx[:trace_id]}-#{ctx[:span_id]}-#{random_suffix}"
+        else
+          trace_id = SecureRandom.hex(16)
+          span_id = SecureRandom.hex(8)
+          set_trace_context(trace_id, span_id)
+          token = "agentbill-v1-#{trace_id}-#{span_id}-#{random_suffix}"
+        end
+
+        Thread.current[:agentbill_tracing_token] = token
+        token
+      end
+
+      # Set the tracing token received from an upstream service
+      def set_tracing_token(token)
+        return false unless token&.start_with?('agentbill-v1-')
+
+        parts = token.split('-')
+        return false if parts.length < 5
+
+        trace_id = parts[2]
+        span_id = parts[3]
+
+        set_trace_context(trace_id, span_id)
+        Thread.current[:agentbill_tracing_token] = token
+        true
+      rescue
+        false
+      end
+
+      # Get HTTP headers for trace propagation
+      def propagate_trace_headers
+        headers = {}
+
+        token = get_tracing_token
+        headers['X-AgentBill-Trace'] = token if token
+
+        ctx = get_trace_context
+        if ctx
+          headers['traceparent'] = "00-#{ctx[:trace_id]}-#{ctx[:span_id]}-01"
+        end
+
+        headers
+      end
+
+      # Extract trace context from incoming HTTP headers
+      def extract_trace_from_headers(headers)
+        # Try AgentBill token first
+        token = headers['X-AgentBill-Trace'] || headers['x-agentbill-trace']
+        return true if token && set_tracing_token(token)
+
+        # Try W3C traceparent
+        traceparent = headers['traceparent'] || headers['Traceparent']
+        if traceparent
+          parts = traceparent.split('-')
+          if parts.length >= 3
+            set_trace_context(parts[1], parts[2])
+            return true
+          end
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/agentbill/exceptions.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# AgentBill Exceptions
+#
+# Custom exception classes for Cost Guard protection and error handling.
+
+module AgentBill
+  # Base class for all AgentBill errors
+  class AgentBillError < StandardError
+    attr_reader :details
+
+    def initialize(message, details = {})
+      @details = details
+      super(message)
+    end
+  end
+
+  # Raised when a request would exceed the configured budget limits.
+  #
+  # This is thrown by the context manager or wrapper when ai-cost-guard-router
+  # returns allowed=false due to budget constraints.
+  #
+  # @example
+  #   begin
+  #     AgentBill.tracing(customer_id: 'cust-123', daily_budget: 10.00) do |ctx|
+  #       response = openai.chat.completions.create(...)
+  #     end
+  #   rescue AgentBill::BudgetExceededError => e
+  #     puts "Budget exceeded: #{e.reason}"
+  #     # Handle gracefully - queue for later, show user message, etc.
+  #   end
+  class BudgetExceededError < AgentBillError
+    attr_reader :reason, :code
+
+    def initialize(reason, details = {})
+      @reason = reason
+      @code = 'BUDGET_EXCEEDED'
+      super("Budget exceeded: #{reason}", details)
+    end
+  end
+
+  # Raised when a request would exceed rate limits.
+  class RateLimitExceededError < AgentBillError
+    attr_reader :reason, :code
+
+    def initialize(reason, details = {})
+      @reason = reason
+      @code = 'RATE_LIMIT_EXCEEDED'
+      super("Rate limit exceeded: #{reason}", details)
+    end
+  end
+
+  # Raised when a request violates a Cost Guard policy.
+  class PolicyViolationError < AgentBillError
+    attr_reader :reason, :code
+
+    def initialize(reason, details = {})
+      @reason = reason
+      @code = 'POLICY_VIOLATION'
+      super("Policy violation: #{reason}", details)
+    end
+  end
+
+  # Raised when input validation fails.
+  class ValidationError < AgentBillError
+    attr_reader :field, :code
+
+    def initialize(message, field = nil)
+      @field = field
+      @code = 'VALIDATION_ERROR'
+      super("Validation error: #{message}")
+    end
+  end
+
+  # Raised when tracing operations fail.
+  class TracingError < AgentBillError
+    attr_reader :code
+
+    def initialize(message, details = {})
+      @code = 'TRACING_ERROR'
+      super("Tracing error: #{message}", details)
+    end
+  end
+end

data/lib/agentbill/ollama_wrapper.rb

@@ -0,0 +1,133 @@
+# Ollama Wrapper for AgentBill Ruby SDK (Local, $0 cost)
+# v7.17.3: Fixed to use OTEL spans instead of deleted track-ai-usage endpoint
+
+
+module AgentBill
+  class OllamaWrapper
+    def initialize(client, config, tracer)
+      @client = client
+      @config = config
+      @tracer = tracer
+    end
+
+    def wrap
+      wrap_chat
+      wrap_generate
+      @client
+    end
+
+    private
+
+    def wrap_chat
+      original_chat = @client.method(:chat)
+      config = @config
+      tracer = @tracer
+
+      @client.define_singleton_method(:chat) do |params|
+        model = params[:model] || 'llama2'
+
+        start_time = Time.now
+        span = tracer.start_span('ollama.chat', {
+          # ✅ OTEL GenAI compliant attributes
+          'gen_ai.system' => 'ollama',
+          'gen_ai.request.model' => model,
+          'gen_ai.operation.name' => 'chat',
+          # ⚠️ Backward compatibility
+          'model' => model,
+          'provider' => 'ollama'
+        })
+
+        begin
+          response = original_chat.call(params)
+          latency = ((Time.now - start_time) * 1000).round
+
+          input_tokens = response[:prompt_eval_count] || 0
+          output_tokens = response[:eval_count] || 0
+
+          # v7.17.3: Track via OTEL span attributes (no track_usage call)
+          span.set_attributes({
+            # ✅ OTEL GenAI compliant attributes
+            'gen_ai.usage.input_tokens' => input_tokens,
+            'gen_ai.usage.output_tokens' => output_tokens,
+            'gen_ai.usage.total_tokens' => input_tokens + output_tokens,
+            'agentbill.event_name' => 'ollama_local',
+            'agentbill.latency_ms' => latency,
+            # ⚠️ Backward compatibility
+            'response.prompt_eval_count' => input_tokens,
+            'response.eval_count' => output_tokens,
+            'latency_ms' => latency,
+            'cost' => 0
+          })
+          span.set_status(0)
+
+          puts "[AgentBill] ✓ Ollama chat tracked (local, $0.00)" if config[:debug]
+          response
+        rescue => e
+          span.set_status(1, e.message)
+          raise
+        ensure
+          span.finish
+          # v7.17.3: Auto-flush span to OTEL collector
+          tracer.flush_sync rescue nil
+        end
+      end
+    end
+
+    def wrap_generate
+      original_generate = @client.method(:generate)
+      config = @config
+      tracer = @tracer
+
+      @client.define_singleton_method(:generate) do |params|
+        model = params[:model] || 'llama2'
+
+        start_time = Time.now
+        span = tracer.start_span('ollama.generate', {
+          # ✅ OTEL GenAI compliant attributes
+          'gen_ai.system' => 'ollama',
+          'gen_ai.request.model' => model,
+          'gen_ai.operation.name' => 'text_completion',
+          # ⚠️ Backward compatibility
+          'model' => model,
+          'provider' => 'ollama'
+        })
+
+        begin
+          response = original_generate.call(params)
+          latency = ((Time.now - start_time) * 1000).round
+
+          input_tokens = response[:prompt_eval_count] || 0
+          output_tokens = response[:eval_count] || 0
+
+          # v7.17.3: Track via OTEL span attributes (no track_usage call)
+          span.set_attributes({
+            # ✅ OTEL GenAI compliant attributes
+            'gen_ai.usage.input_tokens' => input_tokens,
+            'gen_ai.usage.output_tokens' => output_tokens,
+            'gen_ai.usage.total_tokens' => input_tokens + output_tokens,
+            'agentbill.event_name' => 'ollama_generate',
+            'agentbill.latency_ms' => latency,
+            # ⚠️ Backward compatibility
+            'response.prompt_eval_count' => input_tokens,
+            'response.eval_count' => output_tokens,
+            'latency_ms' => latency,
+            'cost' => 0
+          })
+          span.set_status(0)
+
+          puts "[AgentBill] ✓ Ollama generate tracked (local, $0.00)" if config[:debug]
+          response
+        rescue => e
+          span.set_status(1, e.message)
+          raise
+        ensure
+          span.finish
+          # v7.17.3: Auto-flush span to OTEL collector
+          tracer.flush_sync rescue nil
+        end
+      end
+    end
+
+    # v7.17.3: track_usage method DELETED - all tracking now goes through OTEL spans
+  end
+end