paygent-sdk 1.0.0__py3-none-any.whl

paygent_sdk/client.py

@@ -0,0 +1,464 @@
+"""
+Main client implementation for the Paygent SDK.
+"""
+
+import json
+import logging
+import time
+from typing import Optional
+from urllib.parse import urljoin
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+try:
+    import tiktoken
+except ImportError:
+    tiktoken = None
+
+from .models import UsageData, UsageDataWithStrings, APIRequest, ModelPricing, MODEL_PRICING
+
+
+class Client:
+    """Paygent SDK client for tracking usage and costs for AI models."""
+
+    def __init__(self, api_key: str, base_url: str = "http://13.201.118.45:8080"):
+        """
+        Initialize the Paygent SDK client.
+
+        Args:
+            api_key: Your Paygent API key
+            base_url: Base URL for the Paygent API (default: http://13.201.118.45:8080)
+        """
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        
+        # Setup logging
+        self.logger = logging.getLogger(f"paygent_sdk.{id(self)}")
+        self.logger.setLevel(logging.INFO)
+        
+        # Add console handler if no handlers exist
+        if not self.logger.handlers:
+            handler = logging.StreamHandler()
+            formatter = logging.Formatter(
+                '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+            )
+            handler.setFormatter(formatter)
+            self.logger.addHandler(handler)
+        
+        # Setup HTTP client with retry strategy
+        self.session = requests.Session()
+        
+        # Configure retry strategy
+        retry_strategy = Retry(
+            total=3,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+        )
+        
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+        
+        # Set default timeout
+        self.session.timeout = 30
+
+    @classmethod
+    def new_client(cls, api_key: str) -> 'Client':
+        """
+        Create a new Paygent SDK client with the default API URL.
+
+        Args:
+            api_key: Your Paygent API key
+            
+        Returns:
+            Client instance
+        """
+        return cls(api_key)
+
+    @classmethod
+    def new_client_with_url(cls, api_key: str, base_url: str) -> 'Client':
+        """
+        Create a new Paygent SDK client with a custom base URL.
+
+        Args:
+            api_key: Your Paygent API key
+            base_url: Custom base URL for the Paygent API
+            
+        Returns:
+            Client instance
+        """
+        return cls(api_key, base_url)
+
+    def _calculate_cost(self, model: str, usage_data: UsageData) -> float:
+        """
+        Calculate the cost based on model and usage data.
+        
+        Args:
+            model: The AI model name
+            usage_data: Usage data containing token counts
+            
+        Returns:
+            Calculated cost in USD
+        """
+        pricing = MODEL_PRICING.get(model)
+        if not pricing:
+            self.logger.warning(f"Unknown model '{model}', using default pricing")
+            # Use default pricing for unknown models (per 1000 tokens)
+            pricing = ModelPricing(
+                prompt_tokens_cost=0.0001,  # $0.10 per 1000 tokens
+                completion_tokens_cost=0.0001  # $0.10 per 1000 tokens
+            )
+
+        # Calculate cost per 1000 tokens
+        prompt_cost = (usage_data.prompt_tokens / 1000.0) * pricing.prompt_tokens_cost
+        completion_cost = (usage_data.completion_tokens / 1000.0) * pricing.completion_tokens_cost
+        total_cost = prompt_cost + completion_cost
+
+        self.logger.debug(
+            f"Cost calculation for model '{model}': "
+            f"prompt_tokens={usage_data.prompt_tokens} ({prompt_cost:.6f}), "
+            f"completion_tokens={usage_data.completion_tokens} ({completion_cost:.6f}), "
+            f"total={total_cost:.6f}"
+        )
+
+        return total_cost
+
+    def send_usage(
+        self, 
+        agent_id: str, 
+        customer_id: str, 
+        indicator: str, 
+        usage_data: UsageData
+    ) -> None:
+        """
+        Send usage data to the Paygent API.
+        
+        Args:
+            agent_id: Unique identifier for the agent
+            customer_id: Unique identifier for the customer
+            indicator: Indicator for the usage event
+            usage_data: Usage data containing model and token information
+            
+        Raises:
+            requests.RequestException: If the HTTP request fails
+            ValueError: If the usage data is invalid
+        """
+        self.logger.info(
+            f"Starting sendUsage for agentID={agent_id}, customerID={customer_id}, "
+            f"indicator={indicator}, model={usage_data.model}"
+        )
+
+        # Calculate cost
+        try:
+            cost = self._calculate_cost(usage_data.model, usage_data)
+        except Exception as e:
+            self.logger.error(f"Failed to calculate cost: {e}")
+            raise ValueError(f"Failed to calculate cost: {e}") from e
+
+        self.logger.info(f"Calculated cost: {cost:.6f} for model {usage_data.model}")
+
+        # Prepare API request
+        api_request = APIRequest(
+            agent_id=agent_id,
+            customer_id=customer_id,
+            indicator=indicator,
+            amount=cost
+        )
+
+        # Prepare request data
+        request_data = {
+            "agentId": api_request.agent_id,
+            "customerId": api_request.customer_id,
+            "indicator": api_request.indicator,
+            "amount": api_request.amount,
+            "inputToken": usage_data.prompt_tokens,
+            "outputToken": usage_data.completion_tokens,
+            "model": usage_data.model,
+            "serviceProvider": usage_data.service_provider
+        }
+
+        self.logger.debug(f"API request body: {json.dumps(request_data)}")
+
+        # Create HTTP request
+        url = urljoin(self.base_url, "/api/v1/usage")
+        
+        headers = {
+            "Content-Type": "application/json",
+            "paygent-api-key": self.api_key
+        }
+
+        self.logger.debug(f"Making HTTP POST request to: {url}")
+
+        try:
+            # Make HTTP request
+            response = self.session.post(
+                url,
+                json=request_data,
+                headers=headers,
+                timeout=30
+            )
+            
+            self.logger.debug(
+                f"API response status: {response.status_code}, "
+                f"body: {response.text}"
+            )
+
+            # Check response status
+            if 200 <= response.status_code < 300:
+                self.logger.info(
+                    f"Successfully sent usage data for agentID={agent_id}, "
+                    f"customerID={customer_id}, cost={cost:.6f}"
+                )
+                return
+
+            # Handle error response
+            self.logger.error(
+                f"API request failed with status {response.status_code}: {response.text}"
+            )
+            response.raise_for_status()
+
+        except requests.RequestException as e:
+            self.logger.error(f"HTTP request failed: {e}")
+            raise
+
+    def set_log_level(self, level: int) -> None:
+        """
+        Set the logging level for the client.
+        
+        Args:
+            level: Logging level (e.g., logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR)
+        """
+        self.logger.setLevel(level)
+
+    def get_logger(self) -> logging.Logger:
+        """
+        Get the logger instance for custom logging.
+        
+        Returns:
+            Logger instance
+        """
+        return self.logger
+
+    def _get_token_count(self, model: str, text: str) -> int:
+        """
+        Get token count for a given model and text.
+        Supports OpenAI, Anthropic, Google, Meta, AWS, Mistral, Cohere, DeepSeek
+        
+        Args:
+            model: The AI model name
+            text: Text to count tokens for
+            
+        Returns:
+            Number of tokens
+        """
+        if not text:
+            return 0
+
+        if not tiktoken:
+            self.logger.warning("tiktoken not available, using fallback token counting")
+            return self._fallback_token_count(text)
+
+        model_lower = model.lower()
+
+        try:
+            # OpenAI GPT models
+            if model_lower.startswith("gpt-"):
+                encoding = tiktoken.encoding_for_model(model)
+                return len(encoding.encode(text))
+            
+            # Anthropic Claude models
+            elif model_lower.startswith("claude-"):
+                encoding = tiktoken.get_encoding("cl100k_base")
+                return len(encoding.encode(text))
+            
+            # Google DeepMind Gemini models
+            elif model_lower.startswith("gemini-"):
+                encoding = tiktoken.get_encoding("cl100k_base")
+                return len(encoding.encode(text))
+            
+            # Meta Llama models
+            elif model_lower.startswith("llama-"):
+                encoding = tiktoken.get_encoding("cl100k_base")
+                return len(encoding.encode(text))
+            
+            # AWS Titan models
+            elif model_lower.startswith("titan-"):
+                encoding = tiktoken.get_encoding("cl100k_base")
+                return len(encoding.encode(text))
+            
+            # Mistral models
+            elif model_lower.startswith("mistral-"):
+                encoding = tiktoken.get_encoding("cl100k_base")
+                return len(encoding.encode(text))
+            
+            # Cohere models
+            elif model_lower.startswith("command"):
+                encoding = tiktoken.get_encoding("cl100k_base")
+                return len(encoding.encode(text))
+            
+            # DeepSeek models
+            elif model_lower.startswith("deepseek-"):
+                encoding = tiktoken.get_encoding("cl100k_base")
+                return len(encoding.encode(text))
+            
+            # Default fallback
+            else:
+                self.logger.warning(f"Unknown model '{model}', using cl100k_base encoding")
+                encoding = tiktoken.get_encoding("cl100k_base")
+                return len(encoding.encode(text))
+
+        except Exception as e:
+            self.logger.warning(f"Failed to get token count for model {model}: {e}, using fallback")
+            return self._fallback_token_count(text)
+
+    def _fallback_token_count(self, text: str) -> int:
+        """
+        Fallback token counting method using word-based estimation.
+        
+        Args:
+            text: Text to count tokens for
+            
+        Returns:
+            Estimated number of tokens
+        """
+        # Simple word-based estimation: 1.3 tokens per word
+        word_count = len(text.split())
+        return int(word_count * 1.3)
+
+    def _calculate_cost_from_strings(self, model: str, usage_data: UsageDataWithStrings) -> float:
+        """
+        Calculate the cost based on model and usage data with strings.
+        
+        Args:
+            model: The AI model name
+            usage_data: Usage data containing prompt and output strings
+            
+        Returns:
+            Calculated cost in USD
+        """
+        # Count tokens
+        prompt_tokens = self._get_token_count(model, usage_data.prompt_string)
+        completion_tokens = self._get_token_count(model, usage_data.output_string)
+        total_tokens = prompt_tokens + completion_tokens
+
+        self.logger.debug(
+            f"Token counting for model '{model}': "
+            f"prompt_tokens={prompt_tokens}, completion_tokens={completion_tokens}, "
+            f"total_tokens={total_tokens}"
+        )
+
+        # Create UsageData for cost calculation
+        usage_data_obj = UsageData(
+            service_provider=usage_data.service_provider,
+            model=model,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=total_tokens
+        )
+
+        return self._calculate_cost(model, usage_data_obj)
+
+    def send_usage_with_token_string(
+        self, 
+        agent_id: str, 
+        customer_id: str, 
+        indicator: str, 
+        usage_data: UsageDataWithStrings
+    ) -> None:
+        """
+        Send usage data to the Paygent API using prompt and output strings.
+        The function automatically counts tokens using proper tokenizers for each model provider and calculates costs.
+        
+        Args:
+            agent_id: Unique identifier for the agent
+            customer_id: Unique identifier for the customer
+            indicator: Indicator for the usage event
+            usage_data: Usage data containing prompt and output strings
+            
+        Raises:
+            requests.RequestException: If the HTTP request fails
+            ValueError: If the usage data is invalid
+        """
+        self.logger.info(
+            f"Starting sendUsageWithTokenString for agentID={agent_id}, customerID={customer_id}, "
+            f"indicator={indicator}, serviceProvider={usage_data.service_provider}, model={usage_data.model}"
+        )
+
+        # Calculate cost from strings
+        try:
+            cost = self._calculate_cost_from_strings(usage_data.model, usage_data)
+        except Exception as e:
+            self.logger.error(f"Failed to calculate cost from strings: {e}")
+            raise ValueError(f"Failed to calculate cost from strings: {e}") from e
+
+        self.logger.info(f"Calculated cost: {cost:.6f} for model {usage_data.model} from strings")
+
+        # Calculate token counts for API request
+        prompt_tokens = self._get_token_count(usage_data.model, usage_data.prompt_string)
+        completion_tokens = self._get_token_count(usage_data.model, usage_data.output_string)
+
+        # Prepare API request
+        api_request = APIRequest(
+            agent_id=agent_id,
+            customer_id=customer_id,
+            indicator=indicator,
+            amount=cost
+        )
+
+        # Prepare request data
+        request_data = {
+            "agentId": api_request.agent_id,
+            "customerId": api_request.customer_id,
+            "indicator": api_request.indicator,
+            "amount": api_request.amount,
+            "inputToken": prompt_tokens,
+            "outputToken": completion_tokens,
+            "model": usage_data.model,
+            "serviceProvider": usage_data.service_provider
+        }
+
+        self.logger.debug(f"API request body: {json.dumps(request_data)}")
+
+        # Create HTTP request
+        url = urljoin(self.base_url, "/api/v1/usage")
+        
+        headers = {
+            "Content-Type": "application/json",
+            "paygent-api-key": self.api_key
+        }
+
+        self.logger.debug(f"Making HTTP POST request to: {url}")
+
+        try:
+            # Make HTTP request
+            response = self.session.post(
+                url,
+                json=request_data,
+                headers=headers,
+                timeout=30
+            )
+            
+            self.logger.debug(
+                f"API response status: {response.status_code}, "
+                f"body: {response.text}"
+            )
+
+            # Check response status
+            if 200 <= response.status_code < 300:
+                self.logger.info(
+                    f"Successfully sent usage data from strings for agentID={agent_id}, "
+                    f"customerID={customer_id}, cost={cost:.6f}"
+                )
+                return
+
+            # Handle error response
+            self.logger.error(
+                f"API request failed with status {response.status_code}: {response.text}"
+            )
+            response.raise_for_status()
+
+        except requests.RequestException as e:
+            self.logger.error(f"HTTP request failed: {e}")
+            raise

paygent_sdk/constants.py

@@ -0,0 +1,217 @@
+"""
+Model constants for the Paygent SDK.
+
+This module provides predefined constants for AI models and service providers
+to make it easier for users to reference models without hardcoding strings.
+
+For the Go SDK equivalent, see: https://github.com/paygent/paygent-sdk-go
+"""
+
+# Service Provider Constants
+class ServiceProvider:
+    """Service provider constants for external access."""
+    OPENAI = "OpenAI"
+    ANTHROPIC = "Anthropic"
+    GOOGLE_DEEPMIND = "Google DeepMind"
+    META = "Meta"
+    AWS = "AWS"
+    MISTRAL_AI = "Mistral AI"
+    COHERE = "Cohere"
+    DEEPSEEK = "DeepSeek"
+    CUSTOM = "Custom"
+
+
+# OpenAI Models
+class OpenAIModels:
+    """OpenAI model constants."""
+    # GPT-5 Series
+    GPT_5 = "gpt-5"
+    GPT_5_MINI = "gpt-5-mini"
+    GPT_5_NANO = "gpt-5-nano"
+    GPT_5_CHAT_LATEST = "gpt-5-chat-latest"
+    GPT_5_CODEX = "gpt-5-codex"
+    GPT_5_PRO = "gpt-5-pro"
+    GPT_5_SEARCH_API = "gpt-5-search-api"
+    
+    # GPT-4.1 Series
+    GPT_4_1 = "gpt-4.1"
+    GPT_4_1_MINI = "gpt-4.1-mini"
+    GPT_4_1_NANO = "gpt-4.1-nano"
+    
+    # GPT-4o Series
+    GPT_4O = "gpt-4o"
+    GPT_4O_2024_05_13 = "gpt-4o-2024-05-13"
+    GPT_4O_MINI = "gpt-4o-mini"
+    
+    # Realtime Models
+    GPT_REALTIME = "gpt-realtime"
+    GPT_REALTIME_MINI = "gpt-realtime-mini"
+    GPT_4O_REALTIME_PREVIEW = "gpt-4o-realtime-preview"
+    GPT_4O_MINI_REALTIME_PREVIEW = "gpt-4o-mini-realtime-preview"
+    
+    # Audio Models
+    GPT_AUDIO = "gpt-audio"
+    GPT_AUDIO_MINI = "gpt-audio-mini"
+    GPT_4O_AUDIO_PREVIEW = "gpt-4o-audio-preview"
+    GPT_4O_MINI_AUDIO_PREVIEW = "gpt-4o-mini-audio-preview"
+    
+    # O-Series Models
+    O1 = "o1"
+    O1_PRO = "o1-pro"
+    O3_PRO = "o3-pro"
+    O3 = "o3"
+    O3_DEEP_RESEARCH = "o3-deep-research"
+    O4_MINI = "o4-mini"
+    O4_MINI_DEEP_RESEARCH = "o4-mini-deep-research"
+    O3_MINI = "o3-mini"
+    O1_MINI = "o1-mini"
+    
+    # Other Models
+    CODEX_MINI_LATEST = "codex-mini-latest"
+    GPT_4O_MINI_SEARCH_PREVIEW = "gpt-4o-mini-search-preview"
+    GPT_4O_SEARCH_PREVIEW = "gpt-4o-search-preview"
+    COMPUTER_USE_PREVIEW = "computer-use-preview"
+    CHATGPT_4O_LATEST = "chatgpt-4o-latest"
+    
+    # GPT-4 Turbo
+    GPT_4_TURBO_2024_04_09 = "gpt-4-turbo-2024-04-09"
+    GPT_4_0125_PREVIEW = "gpt-4-0125-preview"
+    GPT_4_1106_PREVIEW = "gpt-4-1106-preview"
+    GPT_4_1106_VISION_PREVIEW = "gpt-4-1106-vision-preview"
+    GPT_4_0613 = "gpt-4-0613"
+    GPT_4_0314 = "gpt-4-0314"
+    GPT_4_32K = "gpt-4-32k"
+    
+    # GPT-3.5 Series
+    GPT_3_5_TURBO = "gpt-3.5-turbo"
+    GPT_3_5_TURBO_0125 = "gpt-3.5-turbo-0125"
+    GPT_3_5_TURBO_1106 = "gpt-3.5-turbo-1106"
+    GPT_3_5_TURBO_0613 = "gpt-3.5-turbo-0613"
+    GPT_3_5_0301 = "gpt-3.5-0301"
+    GPT_3_5_TURBO_INSTRUCT = "gpt-3.5-turbo-instruct"
+    GPT_3_5_TURBO_16K_0613 = "gpt-3.5-turbo-16k-0613"
+    
+    # Legacy Models
+    DAVINCI_002 = "davinci-002"
+    BABBAGE_002 = "babbage-002"
+
+
+# Anthropic Models
+class AnthropicModels:
+    """Anthropic model constants."""
+    SONNET_4_5 = "Sonnet 4.5"
+    HAIKU_4_5 = "Haiku 4.5"
+    OPUS_4_1 = "Opus 4.1"
+    SONNET_4 = "Sonnet 4"
+    OPUS_4 = "Opus 4"
+    SONNET_3_7 = "Sonnet 3.7"
+    HAIKU_3_5 = "Haiku 3.5"
+    OPUS_3 = "Opus 3"
+    HAIKU_3 = "Haiku 3"
+
+
+# Google DeepMind Models
+class GoogleDeepMindModels:
+    """Google DeepMind model constants."""
+    GEMINI_2_5_PRO = "Gemini 2.5 Pro"
+    GEMINI_2_5_FLASH = "Gemini 2.5 Flash"
+    GEMINI_2_5_FLASH_PREVIEW = "Gemini 2.5 Flash Preview"
+    GEMINI_2_5_FLASH_LITE = "Gemini 2.5 Flash-Lite"
+    GEMINI_2_5_FLASH_LITE_PREVIEW = "Gemini 2.5 Flash-Lite Preview"
+    GEMINI_2_5_FLASH_NATIVE_AUDIO = "Gemini 2.5 Flash Native Audio"
+    GEMINI_2_5_FLASH_IMAGE = "Gemini 2.5 Flash Image"
+    GEMINI_2_5_FLASH_PREVIEW_TTS = "Gemini 2.5 Flash Preview TTS"
+    GEMINI_2_5_PRO_PREVIEW_TTS = "Gemini 2.5 Pro Preview TTS"
+    GEMINI_2_5_COMPUTER_USE_PREVIEW = "Gemini 2.5 Computer Use Preview"
+
+
+# Meta Models
+class MetaModels:
+    """Meta model constants."""
+    # Llama 4 Series
+    LLAMA_4_MAVERICK = "Llama 4 Maverick"
+    LLAMA_4_SCOUT = "Llama 4 Scout"
+    
+    # Llama 3.3 Series
+    LLAMA_3_3_70B_INSTRUCT_TURBO = "Llama 3.3 70B Instruct-Turbo"
+    
+    # Llama 3.2 Series
+    LLAMA_3_2_3B_INSTRUCT_TURBO = "Llama 3.2 3B Instruct Turbo"
+    
+    # Llama 3.1 Series
+    LLAMA_3_1_405B_INSTRUCT_TURBO = "Llama 3.1 405B Instruct Turbo"
+    LLAMA_3_1_70B_INSTRUCT_TURBO = "Llama 3.1 70B Instruct Turbo"
+    LLAMA_3_1_8B_INSTRUCT_TURBO = "Llama 3.1 8B Instruct Turbo"
+    
+    # Llama 3 Series
+    LLAMA_3_70B_INSTRUCT_TURBO = "Llama 3 70B Instruct Turbo"
+    LLAMA_3_70B_INSTRUCT_REFERENCE = "Llama 3 70B Instruct Reference"
+    LLAMA_3_8B_INSTRUCT_LITE = "Llama 3 8B Instruct Lite"
+    
+    # Llama 2
+    LLAMA_2 = "LLaMA-2"
+    
+    # Llama Guard Series
+    LLAMA_GUARD_4_12B = "Llama Guard 4 12B"
+    LLAMA_GUARD_3_11B_VISION_TURBO = "Llama Guard 3 11B Vision Turbo"
+    LLAMA_GUARD_3_8B = "Llama Guard 3 8B"
+    LLAMA_GUARD_2_8B = "Llama Guard 2 8B"
+    
+    # Salesforce
+    SALESFORCE_LLAMA_RANK_V1_8B = "Salesforce Llama Rank V1 (8B)"
+
+
+# AWS Models
+class AWSModels:
+    """AWS model constants."""
+    AMAZON_NOVA_MICRO = "Amazon Nova Micro"
+    AMAZON_NOVA_LITE = "Amazon Nova Lite"
+    AMAZON_NOVA_PRO = "Amazon Nova Pro"
+
+
+# Mistral AI Models
+class MistralAIModels:
+    """Mistral AI model constants."""
+    MISTRAL_7B_INSTRUCT = "Mistral 7B Instruct"
+    MISTRAL_LARGE = "Mistral Large"
+    MISTRAL_SMALL = "Mistral Small"
+    MISTRAL_MEDIUM = "Mistral Medium"
+
+
+# Cohere Models
+class CohereModels:
+    """Cohere model constants."""
+    COMMAND_R7B = "Command R7B"
+    COMMAND_R = "Command R"
+    COMMAND_R_PLUS = "Command R+"
+    COMMAND_A = "Command A"
+    AYA_EXPANSE_8B_32B = "Aya Expanse (8B/32B)"
+
+
+# DeepSeek Models
+class DeepSeekModels:
+    """DeepSeek model constants."""
+    DEEPSEEK_CHAT = "DeepSeek Chat"
+    DEEPSEEK_REASONER = "DeepSeek Reasoner"
+    DEEPSEEK_R1_GLOBAL = "DeepSeek R1 Global"
+    DEEPSEEK_R1_DATAZONE = "DeepSeek R1 DataZone"
+    DEEPSEEK_V3_2_EXP = "DeepSeek V3.2-Exp"
+
+
+
+
+
+
+def is_model_supported(model: str) -> bool:
+    """
+    Check if a model is supported by the SDK.
+    
+    Args:
+        model: The model name
+        
+    Returns:
+        True if the model is supported, False otherwise
+    """
+    # Import here to avoid circular dependency
+    from .models import MODEL_PRICING
+    return model in MODEL_PRICING