agentbill-sdk 5.0.1 → 9.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e9b487391274ecb94dbc031a40f6e30a167e6fa0e30bb257464f68e497871f2
-  data.tar.gz: cc6bc10bfdddf68981cd5454f80b4cffc6ea10a244f49f7e1f6582dd154e9b6c
+  metadata.gz: 0ee9e7fe3afb95e290b137974dadcb40147cc4b3855985688bf5ece9c037930b
+  data.tar.gz: 52fdd0c0634edc3bd36425244a0fc923e2b820bfced8fe8a14ace7538e55225d
 SHA512:
-  metadata.gz: a4409ffa8bac425a994a09c45d513877d5167e7ca9706c86229de4a6a50f8bf1da729ec1ccab5448c1dda808ed43cb04b2c314840f894801bd203cd8ca608aff
-  data.tar.gz: 285d37fb82ae7b3173474c72c47647e2585d8cf983730b16a24adf068a7baae3004078e10c79c493f66960d19921fd531d4aac1b7b6f35688ec7b9e1b541c987
+  metadata.gz: c567fa89b467b00d36f1df21ac752ea772d6c333af73df20f4ea986739acc2490e57d52568d1604a8b4067588f1796d7e94ae2e7cf3ee3ecfca71c6cdfe4c5c2
+  data.tar.gz: 3a18a47c140ed7eb1d6a46f5ee8ddc04ab91ce822bae23f7f8dcecbadf444b9b80f95f83f5006e56ddaa6cd468ddd7bad3b3940ffc030fc92116e8341b14a99b

data/.github/workflows/ci.yml

@@ -1,10 +1,11 @@
 name: CI
 
 on:
-  push:
-    branches: [ main, develop ]
   pull_request:
     branches: [ main, develop ]
+    paths:
+      - 'sdks/ruby/**'
+      - '.github/workflows/ci.yml'
 
 jobs:
   test:
@@ -13,8 +14,8 @@ jobs:
     
     strategy:
       matrix:
-        ruby-version: ['3.0', '3.1', '3.2', '3.3']
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        ruby-version: ['3.3']
+        os: [ubuntu-latest]
     
     steps:
       - uses: actions/checkout@v4

data/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.19.3] - 2026-02-24
+
+### Fixed
+- **OTLP Normalizer**: `company.id` → `agentbill.company_id` resource attribute — fixes collector rejection
+
+## [7.19.2] - 2026-02-24
+
+### Fixed
+- **M365 Seeder v1.1.0** — 3 critical fixes under Shared OTLP Normalizer topic:
+  1. **Identity Resolution (0% → 100%)**: Auto-provisions customers before seeding
+  2. **Valid Trace/Span IDs**: Uses `generateDedupFromSource()` — eliminates normalizer repair warnings
+  3. **Batched Collector Calls**: 50 spans/batch with 500ms delay — fixes 504 timeouts
+
+## [7.19.1] - 2026-02-24
+
+### Added
+- **Version Alignment**: Aligned with Python SDK v7.19.1 — M365 Copilot test data seeder for pipeline validation without enterprise account
+
+## [7.19.0] - 2026-02-24
+
+### Changed
+- **Version Alignment**: Aligned with Python SDK v7.19.0 shared OTLP normalizer and connector migration
+
+## [7.6.3] - 2025-12-17
+
+### Changed
+- **Version Alignment**: Aligned with Python SDK v7.6.3 wrap_openai() semantic cache fix
+- Ruby SDK already had cache hit check and cache population in `wrap_openai()`
+
+## [6.8.8] - 2025-12-09
+
+### Fixed
+- **Version Bump**: Aligned with Python SDK v6.8.8 wrapper trace context auto-generation fix
+
+## [6.8.5] - 2025-12-09
+
+### Fixed
+- **Tracer Version Alignment**: Updated `service.version` and `scope.version` in OTLP payload to 6.8.5
+
+## [6.8.4] - 2025-12-08
+
+### Fixed
+- **CRITICAL**: Fixed `agent_id` and `customer_id` not being sent as OTEL resource attributes
+- The otel-collector extracts these from resource attributes, not top-level payload
+- Added `agent_id` config option to SDK initialization
+
+## [6.8.3] - 2025-12-08
+
+### Fixed
+- **Version Bump**: Aligned with Python SDK v6.8.3 trace context fix for decorator pattern
+- No functional changes in Ruby SDK (fix was Python-specific)
+
 ## [5.0.1] - 2025-11-06
 
 ### Added
@@ -31,7 +83,7 @@ agentbill.track_signal(
 - **CRITICAL**: Fixed authentication header to use `X-API-Key` instead of `Authorization: Bearer` format
 - Updated `track_signal()` method in agentbill.rb to use correct authentication
 - Updated `flush()` method in tracer.rb to use correct authentication
-- Signals now properly authenticate with record-signals and otel-collector edge functions
+- Signals now properly authenticate with the unified OTEL pipeline (otel-collector)
 
 ## [2.0.1] - 2025-10-25
 

data/examples/ollama_basic.rb

@@ -0,0 +1,81 @@
+# AgentBill v6.0.0 - Ollama Integration Example
+# Tracks local Ollama chat and generation (metrics only, $0 cost)
+
+require 'agentbill'
+require 'net/http'
+require 'json'
+
+# Mock Ollama client (replace with actual Ollama SDK)
+class OllamaClient
+  def chat(params)
+    uri = URI('http://localhost:11434/api/chat')
+    
+    http = Net::HTTP.new(uri.host, uri.port)
+    
+    request = Net::HTTP::Post.new(uri.path)
+    request['Content-Type'] = 'application/json'
+    request.body = params.to_json
+    
+    response = http.request(request)
+    JSON.parse(response.body, symbolize_names: true)
+  end
+
+  def generate(params)
+    uri = URI('http://localhost:11434/api/generate')
+    
+    http = Net::HTTP.new(uri.host, uri.port)
+    
+    request = Net::HTTP::Post.new(uri.path)
+    request['Content-Type'] = 'application/json'
+    request.body = params.to_json
+    
+    response = http.request(request)
+    JSON.parse(response.body, symbolize_names: true)
+  end
+end
+
+# Initialize AgentBill
+agentbill = AgentBill::Client.init({
+  api_key: ENV['AGENTBILL_API_KEY'],
+  customer_id: 'customer-123',
+  debug: true
+})
+
+# Create Ollama client
+ollama = OllamaClient.new
+
+# Wrap with AgentBill
+ollama_wrapper = AgentBill::OllamaWrapper.new(ollama, agentbill.config, agentbill.tracer)
+tracked_ollama = ollama_wrapper.wrap
+
+puts "🦙 Using Ollama (local, free)...\n\n"
+
+# Example 1: Chat
+puts "💬 Chat example:"
+chat_response = tracked_ollama.chat({
+  model: 'llama2',
+  messages: [
+    {
+      role: 'user',
+      content: 'Why is the sky blue? Give a brief answer.'
+    }
+  ]
+})
+
+puts "✅ Response: #{chat_response[:message][:content]}"
+puts "📊 Tokens: prompt=#{chat_response[:prompt_eval_count]}, completion=#{chat_response[:eval_count]}"
+puts "💰 Cost: $0.00 (local model)\n\n"
+
+# Example 2: Generate
+puts "📝 Generate example:"
+generate_response = tracked_ollama.generate({
+  model: 'llama2',
+  prompt: 'Write a haiku about coding:'
+})
+
+puts "✅ Response: #{generate_response[:response]}"
+puts "📊 Tokens: prompt=#{generate_response[:prompt_eval_count]}, completion=#{generate_response[:eval_count]}"
+puts "💰 Cost: $0.00 (local model)\n\n"
+
+puts "ℹ️  Ollama runs locally, so there's no API cost."
+puts "   AgentBill tracks metrics for monitoring and analysis.\n"

data/examples/perplexity_basic.rb

@@ -0,0 +1,66 @@
+# AgentBill v6.0.0 - Perplexity AI Integration Example
+# Tracks Perplexity AI chat completions with online search
+
+require 'agentbill'
+require 'net/http'
+require 'json'
+
+# Mock Perplexity client (replace with actual Perplexity SDK)
+class PerplexityClient
+  def initialize(api_key)
+    @api_key = api_key
+  end
+
+  def chat_create(params)
+    uri = URI('https://api.perplexity.ai/chat/completions')
+    
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true
+    
+    request = Net::HTTP::Post.new(uri.path)
+    request['Authorization'] = "Bearer #{@api_key}"
+    request['Content-Type'] = 'application/json'
+    request.body = params.to_json
+    
+    response = http.request(request)
+    JSON.parse(response.body, symbolize_names: true)
+  end
+end
+
+# Initialize AgentBill
+agentbill = AgentBill::Client.init({
+  api_key: ENV['AGENTBILL_API_KEY'],
+  customer_id: 'customer-123',
+  debug: true
+})
+
+# Create Perplexity client
+perplexity = PerplexityClient.new(ENV['PERPLEXITY_API_KEY'])
+
+# Wrap with AgentBill
+perplexity_wrapper = AgentBill::PerplexityWrapper.new(perplexity, agentbill.config, agentbill.tracer)
+tracked_perplexity = perplexity_wrapper.wrap
+
+puts "🔍 Querying Perplexity AI with online search...\n\n"
+
+# Make a request - automatically tracked
+response = tracked_perplexity.chat_create({
+  model: 'llama-3.1-sonar-small-128k-online',
+  messages: [
+    {
+      role: 'system',
+      content: 'Be precise and concise.'
+    },
+    {
+      role: 'user',
+      content: 'What are the latest developments in AI for 2025?'
+    }
+  ],
+  temperature: 0.2,
+  top_p: 0.9,
+  max_tokens: 1000
+})
+
+puts "✅ Response: #{response[:choices][0][:message][:content]}"
+puts "\n📊 Usage: #{response[:usage]}"
+puts "💰 Cost automatically tracked in AgentBill dashboard\n"

data/lib/agentbill/agents.rb

@@ -0,0 +1,226 @@
+# AgentBill Agents Resource - CRUD operations with signal type management
+# 
+# Example:
+#   ab = AgentBill::Client.init(api_key: 'agb_...')
+#   
+#   # Create agent
+#   agent = ab.agents.create(name: 'Support Bot', description: 'Customer support')
+#   puts "API Key (save this!): #{agent['api_key']}"
+#   
+#   # Assign signal types
+#   ab.agents.assign_signal_types(
+#     agent_id: agent['id'],
+#     signal_type_names: ['ai_call', 'completion']
+#   )
+#   
+#   # List agents
+#   result = ab.agents.list(status: 'active')
+#   
+#   # Get signal types for agent
+#   signal_types = ab.agents.get_signal_types(agent['id'])
+
+require 'net/http'
+require 'json'
+
+module AgentBill
+  class AgentsResource
+    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 agents with optional status filter and pagination
+    #
+    # @param status [String, nil] Filter by status ('active', 'inactive', 'archived')
+    # @param limit [Integer] Number of agents to return (default: 50)
+    # @param offset [Integer] Offset for pagination (default: 0)
+    # @param search [String, nil] Search term to filter by name or description
+    # @return [Hash] Hash with 'data' (list of agents) and 'pagination' info
+    def list(status: nil, limit: 50, offset: 0, search: nil)
+      uri = URI("#{@base_url}/functions/v1/api-agents")
+      params = { limit: limit.to_s, offset: offset.to_s }
+      params[:status] = status if status
+      params[:search] = search if search
+      uri.query = URI.encode_www_form(params)
+
+      response = make_request(:get, uri)
+      handle_response(response, 'list agents')
+    end
+
+    # Create a new agent
+    # IMPORTANT: The response includes a one-time visible API key.
+    # Save this key securely - it cannot be retrieved again.
+    #
+    # @param name [String] Agent name (required)
+    # @param description [String, nil] Agent description
+    # @param agent_type [String, nil] Type of agent (e.g., 'support', 'sales', 'assistant')
+    # @param model [String, nil] Default model for this agent
+    # @param external_id [String, nil] Your external ID for this agent
+    # @param metadata [Hash, nil] Additional metadata
+    # @param signal_type_names [Array<String>, nil] Signal types to auto-assign (e.g., ['ai_call', 'completion'])
+    # @return [Hash] Created agent object with api_key (one-time visible)
+    def create(name:, description: nil, agent_type: nil, model: nil, external_id: nil, metadata: nil, signal_type_names: nil)
+      uri = URI("#{@base_url}/functions/v1/api-agents")
+      
+      payload = { name: name }
+      payload[:description] = description if description
+      payload[:agent_type] = agent_type if agent_type
+      payload[:model] = model if model
+      payload[:external_id] = external_id if external_id
+      payload[:metadata] = metadata if metadata
+      payload[:signal_type_names] = signal_type_names if signal_type_names
+
+      response = make_request(:post, uri, payload)
+      handle_response(response, 'create agent')
+    end
+
+    # Get an agent by ID or external_id
+    #
+    # @param agent_id [String] Agent UUID or external_id
+    # @param by_external_id [Boolean] If true, treat agent_id as external_id
+    # @return [Hash] Agent object
+    def get(agent_id, by_external_id: false)
+      uri = URI("#{@base_url}/functions/v1/api-agents")
+      params = by_external_id ? { external_id: agent_id } : { id: agent_id }
+      uri.query = URI.encode_www_form(params)
+
+      response = make_request(:get, uri)
+      result = handle_response(response, 'get agent')
+      
+      if result['data'].is_a?(Array)
+        raise "Agent not found" if result['data'].empty?
+        return result['data'][0]
+      end
+      result
+    end
+
+    # Update an agent
+    #
+    # @param agent_id [String] Agent UUID
+    # @param name [String, nil] New name
+    # @param description [String, nil] New description
+    # @param agent_type [String, nil] New agent type
+    # @param model [String, nil] New default model
+    # @param status [String, nil] New status ('active', 'inactive', 'archived')
+    # @param metadata [Hash, nil] New metadata (replaces existing)
+    # @return [Hash] Updated agent object
+    def update(agent_id, name: nil, description: nil, agent_type: nil, model: nil, status: nil, metadata: nil)
+      uri = URI("#{@base_url}/functions/v1/api-agents")
+      
+      payload = { id: agent_id }
+      payload[:name] = name if name
+      payload[:description] = description if description
+      payload[:agent_type] = agent_type if agent_type
+      payload[:model] = model if model
+      payload[:status] = status if status
+      payload[:metadata] = metadata if metadata
+
+      response = make_request(:patch, uri, payload)
+      handle_response(response, 'update agent')
+    end
+
+    # Delete an agent
+    #
+    # @param agent_id [String] Agent UUID to delete
+    def delete(agent_id)
+      uri = URI("#{@base_url}/functions/v1/api-agents")
+      payload = { id: agent_id }
+
+      response = make_request(:delete, uri, payload)
+      handle_response(response, 'delete agent')
+    end
+
+    # Assign signal types to an agent (explicit assignment)
+    # This method explicitly configures which signal types the agent can emit.
+    #
+    # @param agent_id [String, nil] Agent UUID (provide this OR external_agent_id)
+    # @param external_agent_id [String, nil] External agent ID (provide this OR agent_id)
+    # @param signal_type_ids [Array<String>, nil] List of signal type UUIDs to assign
+    # @param signal_type_names [Array<String>, nil] List of signal type names (e.g., ['ai_call', 'completion'])
+    # @return [Hash] Hash with agent_id, signal_type_ids, and assigned_count
+    def assign_signal_types(agent_id: nil, external_agent_id: nil, signal_type_ids: nil, signal_type_names: nil)
+      raise ArgumentError, "Either agent_id or external_agent_id is required" unless agent_id || external_agent_id
+      raise ArgumentError, "Either signal_type_ids or signal_type_names is required" unless signal_type_ids || signal_type_names
+
+      uri = URI("#{@base_url}/functions/v1/api-agent-signal-types")
+      
+      payload = {}
+      payload[:agent_id] = agent_id if agent_id
+      payload[:external_agent_id] = external_agent_id if external_agent_id
+      payload[:signal_type_ids] = signal_type_ids if signal_type_ids
+      payload[:signal_type_names] = signal_type_names if signal_type_names
+
+      response = make_request(:post, uri, payload)
+      handle_response(response, 'assign signal types')
+    end
+
+    # Get signal types assigned to an agent
+    #
+    # @param agent_id [String] Agent UUID or external_id
+    # @param by_external_id [Boolean] If true, treat agent_id as external_id
+    # @return [Hash] Hash with agent_id and list of signal_types
+    def get_signal_types(agent_id, by_external_id: false)
+      uri = URI("#{@base_url}/functions/v1/api-agent-signal-types")
+      params = by_external_id ? { external_agent_id: agent_id } : { agent_id: agent_id }
+      uri.query = URI.encode_www_form(params)
+
+      response = make_request(:get, uri)
+      handle_response(response, 'get signal types')
+    end
+
+    # Remove signal types from an agent
+    #
+    # @param agent_id [String] Agent UUID
+    # @param signal_type_ids [Array<String>, nil] Specific signal type IDs to remove. If nil, removes all.
+    def remove_signal_types(agent_id, signal_type_ids: nil)
+      uri = URI("#{@base_url}/functions/v1/api-agent-signal-types")
+      
+      payload = { agent_id: agent_id }
+      payload[:signal_type_ids] = signal_type_ids if signal_type_ids
+
+      response = make_request(:delete, uri, payload)
+      handle_response(response, 'remove signal types')
+    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/attributes.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Canonical attribute constants for OTEL span attributes.
+#
+# Single source of truth for all attribute keys used across the SDK.
+# Prevents string drift between signals.rb, tracer.rb, and wrapper code.
+#
+# v9.5.5: Added multi-modality attributes (R3 alignment with Python/TS/Go).
+
+module AgentBill
+  module Attributes
+    # Core signal attributes
+    ATTR_EVENT_NAME       = 'agentbill.event_name'
+    ATTR_IS_BUSINESS_EVENT = 'agentbill.is_business_event'
+    ATTR_IDEMPOTENCY_KEY  = 'agentbill.idempotency_key'
+    ATTR_DATA_SOURCE      = 'agentbill.data_source'
+
+    # Identity
+    ATTR_CUSTOMER_ID = 'agentbill.customer_id'
+    ATTR_AGENT_ID    = 'agentbill.agent_id'
+
+    # Business data
+    ATTR_REVENUE    = 'agentbill.revenue'
+    ATTR_CURRENCY   = 'agentbill.currency'
+    ATTR_EVENT_TYPE = 'agentbill.event_type'
+    ATTR_EVENT_VALUE = 'agentbill.event_value'
+
+    # Linking
+    ATTR_SESSION_ID       = 'agentbill.session_id'
+    ATTR_ORDER_ID         = 'agentbill.order_id'
+    ATTR_ORDER_EXTERNAL_ID = 'agentbill.order_external_id'
+    ATTR_PARENT_SPAN_ID   = 'agentbill.parent_span_id'
+    ATTR_METADATA         = 'agentbill.metadata'
+
+    # AI telemetry (OpenTelemetry Semantic Conventions)
+    ATTR_MODEL            = 'gen_ai.request.model'
+    ATTR_PROVIDER         = 'gen_ai.system'
+    ATTR_PROMPT_TOKENS    = 'gen_ai.usage.prompt_tokens'
+    ATTR_COMPLETION_TOKENS = 'gen_ai.usage.completion_tokens'
+    ATTR_TOTAL_TOKENS     = 'gen_ai.usage.total_tokens'
+    ATTR_LATENCY_MS       = 'agentbill.latency_ms'
+    ATTR_PROMPT_HASH      = 'agentbill.prompt_hash'
+
+    # Modality / operation name (OTEL Semantic Convention: gen_ai.operation.name)
+    # Official values: chat, embeddings, text_completion, create_image, audio_speech, audio_transcription
+    ATTR_OPERATION_NAME = 'gen_ai.operation.name'
+
+    # Image generation — request params (pricing tier) vs usage (quantity billed)
+    ATTR_IMAGE_SIZE    = 'gen_ai.request.image_size'         # e.g. "1024x1024" — determines price tier
+    ATTR_IMAGE_QUALITY = 'gen_ai.request.image_quality'      # e.g. "hd", "standard" — determines price tier
+    ATTR_IMAGE_COUNT   = 'gen_ai.usage.image_count'          # actual images generated — quantity billed
+
+    # Audio — request params vs usage
+    ATTR_AUDIO_INPUT_FORMAT     = 'gen_ai.request.audio_input_format'
+    ATTR_AUDIO_OUTPUT_FORMAT    = 'gen_ai.request.audio_output_format'
+    ATTR_AUDIO_DURATION_SECONDS = 'gen_ai.usage.audio_duration_seconds'
+
+    # TTS — request params vs usage
+    ATTR_TTS_VOICE      = 'gen_ai.request.tts_voice'
+    ATTR_TTS_CHARACTERS = 'gen_ai.usage.characters'
+
+    # Embedding — request params vs usage
+    ATTR_EMBEDDING_DIMENSIONS  = 'gen_ai.request.embedding_dimensions'
+    ATTR_EMBEDDING_INPUT_COUNT = 'gen_ai.usage.embedding_input_count'
+
+    # Cache attributes
+    ATTR_CACHE_HIT   = 'agentbill.cache_hit'
+    ATTR_FROM_CACHE  = 'agentbill.from_cache'
+    ATTR_TOKENS_SAVED = 'agentbill.tokens_saved'
+    ATTR_COST_SAVED  = 'agentbill.cost_saved'
+
+    # Cost tracing (Phase 1: enable_cost_tracing flag)
+    ATTR_COST_TRACING_ENABLED = 'agentbill.cost_tracing.enabled'
+
+    # Manual cost (Phase 3 – two-variant model)
+    ATTR_COST_PROVIDED = 'agentbill.cost.provided'  # bool: server skips model_pricing
+    ATTR_COST_PROVIDER = 'agentbill.cost.provider'  # str: maps from CostData.vendor
+    ATTR_COST_AMOUNT   = 'agentbill.cost.amount'    # float: pre-calculated cost
+    ATTR_COST_CURRENCY = 'agentbill.cost.currency'  # str: currency code
+
+    # Business grouping (whitelist)
+    GROUPING_KEYS = %w[session_id workflow_id batch_id correlation_id].freeze
+
+    # Bulk
+    ATTR_BULK_INDEX   = 'agentbill.bulk_index'
+    ATTR_BULK_REQUEST = 'agentbill.bulk_request'
+
+    # Resource / SDK constants
+    RESOURCE_SERVICE_NAME = 'agentbill-ruby-sdk'
+    SDK_VERSION           = '9.5.5'
+    SCOPE_NAME            = 'agentbill.signals'
+    SCOPE_NAME_BULK       = 'agentbill.signals.bulk'
+    SIGNAL_SPAN_NAME      = 'agentbill.trace.signal'
+  end
+end