intentkit 0.6.21.dev2__py3-none-any.whl → 0.6.22.dev1__py3-none-any.whl

intentkit/skills/dexscreener/utils.py

@@ -0,0 +1,419 @@
+"""
+Utility functions and constants for DexScreener skills.
+"""
+
+import json
+import logging
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional
+
+from pydantic import ValidationError
+
+from intentkit.skills.dexscreener.model.search_token_response import PairModel
+
+logger = logging.getLogger(__name__)
+
+# API Base URL
+DEXSCREENER_BASE_URL = "https://api.dexscreener.com"
+
+# API Endpoints
+API_ENDPOINTS = {
+    "search": "/latest/dex/search",
+    "pairs": "/latest/dex/pairs",
+    "token_pairs": "/token-pairs/v1",
+    "tokens": "/tokens/v1",
+    "token_profiles": "/token-profiles/latest/v1",
+    "token_boosts_latest": "/token-boosts/latest/v1",
+    "token_boosts_top": "/token-boosts/top/v1",
+    "orders": "/orders/v1",
+}
+
+# Rate Limits (requests per minute)
+RATE_LIMITS = {
+    "search": 300,
+    "pairs": 300,
+    "token_pairs": 300,
+    "tokens": 300,
+    "token_profiles": 60,
+    "token_boosts": 60,
+    "orders": 60,
+}
+
+# Limits
+MAX_SEARCH_RESULTS = 25
+MAX_TOKENS_BATCH = 30
+
+# Common disclaimer for search results
+SEARCH_DISCLAIMER = {
+    "disclaimer": (
+        "Search results may include unofficial, duplicate, or potentially malicious tokens. "
+        "If multiple unrelated tokens share a similar name or ticker, ask the user for the exact token address. "
+        "If the correct token is not found, re-run the tool using the provided address. "
+        "Also advise the user to verify the token's legitimacy via its official social links included in the result."
+    )
+}
+
+
+# Query Types
+class QueryType(str, Enum):
+    TEXT = "TEXT"
+    TICKER = "TICKER"
+    ADDRESS = "ADDRESS"
+
+
+# Sort Options
+class SortBy(str, Enum):
+    LIQUIDITY = "liquidity"
+    VOLUME = "volume"
+
+
+# Volume Timeframes
+class VolumeTimeframe(str, Enum):
+    FIVE_MINUTES = "5_minutes"
+    ONE_HOUR = "1_hour"
+    SIX_HOUR = "6_hour"
+    TWENTY_FOUR_HOUR = "24_hour"
+
+
+# Supported Chain IDs
+SUPPORTED_CHAINS = [
+    "ethereum",
+    "bsc",
+    "polygon",
+    "avalanche",
+    "fantom",
+    "cronos",
+    "arbitrum",
+    "optimism",
+    "base",
+    "solana",
+    "sui",
+    "tron",
+    "ton",
+]
+
+
+def determine_query_type(query: str) -> QueryType:
+    """
+    Determine whether the query is a TEXT, TICKER, or ADDRESS.
+
+    Args:
+        query: The search query string
+
+    Returns:
+        QueryType enum value
+    """
+    if query.startswith("0x"):
+        return QueryType.ADDRESS
+    if query.startswith("$"):
+        return QueryType.TICKER
+    return QueryType.TEXT
+
+
+def get_liquidity_value(pair: PairModel) -> float:
+    """
+    Extract liquidity USD value from a pair, defaulting to 0.0 if not available.
+
+    Args:
+        pair: PairModel instance
+
+    Returns:
+        Liquidity value in USD as float
+    """
+    return (
+        pair.liquidity.usd if pair.liquidity and pair.liquidity.usd is not None else 0.0
+    )
+
+
+def get_volume_value(
+    pair: PairModel, timeframe: VolumeTimeframe = VolumeTimeframe.TWENTY_FOUR_HOUR
+) -> float:
+    """
+    Extract volume value from a pair for the specified timeframe.
+
+    Args:
+        pair: PairModel instance
+        timeframe: VolumeTimeframe enum value
+
+    Returns:
+        Volume value as float
+    """
+    if not pair.volume:
+        return 0.0
+
+    volume_map = {
+        VolumeTimeframe.FIVE_MINUTES: pair.volume.m5,
+        VolumeTimeframe.ONE_HOUR: pair.volume.h1,
+        VolumeTimeframe.SIX_HOUR: pair.volume.h6,
+        VolumeTimeframe.TWENTY_FOUR_HOUR: pair.volume.h24,
+    }
+
+    return volume_map.get(timeframe, 0.0) or 0.0
+
+
+def get_sort_function(
+    sort_by: SortBy,
+    volume_timeframe: VolumeTimeframe = VolumeTimeframe.TWENTY_FOUR_HOUR,
+) -> Callable[[PairModel], float]:
+    """
+    Get the appropriate sorting function based on sort criteria.
+
+    Args:
+        sort_by: SortBy enum value
+        volume_timeframe: VolumeTimeframe enum value (used when sorting by volume)
+
+    Returns:
+        Callable function that takes a PairModel and returns a float for sorting
+    """
+    if sort_by == SortBy.LIQUIDITY:
+        return get_liquidity_value
+    elif sort_by == SortBy.VOLUME:
+        return lambda pair: get_volume_value(pair, volume_timeframe)
+    else:
+        logger.warning(f"Invalid sort_by value '{sort_by}', defaulting to liquidity.")
+        return get_liquidity_value
+
+
+def sort_pairs_by_criteria(
+    pairs: List[PairModel],
+    sort_by: SortBy = SortBy.LIQUIDITY,
+    volume_timeframe: VolumeTimeframe = VolumeTimeframe.TWENTY_FOUR_HOUR,
+    reverse: bool = True,
+) -> List[PairModel]:
+    """
+    Sort pairs by the specified criteria.
+
+    Args:
+        pairs: List of PairModel instances to sort
+        sort_by: Sorting criteria (liquidity or volume)
+        volume_timeframe: Timeframe for volume sorting
+        reverse: Sort in descending order if True
+
+    Returns:
+        Sorted list of PairModel instances
+    """
+    try:
+        sort_func = get_sort_function(sort_by, volume_timeframe)
+        return sorted(pairs, key=sort_func, reverse=reverse)
+    except Exception as e:
+        logger.error(f"Failed to sort pairs: {e}", exc_info=True)
+        return pairs  # Return original list if sorting fails
+
+
+def filter_ticker_pairs(pairs: List[PairModel], target_ticker: str) -> List[PairModel]:
+    """
+    Filter pairs to only include those where base token symbol matches target ticker.
+
+    Args:
+        pairs: List of PairModel instances
+        target_ticker: Target ticker symbol (case-insensitive)
+
+    Returns:
+        Filtered list of PairModel instances
+    """
+    target_ticker_upper = target_ticker.upper()
+    return [
+        p
+        for p in pairs
+        if p.baseToken
+        and p.baseToken.symbol
+        and p.baseToken.symbol.upper() == target_ticker_upper
+    ]
+
+
+def filter_address_pairs(
+    pairs: List[PairModel], target_address: str
+) -> List[PairModel]:
+    """
+    Filter pairs to only include those matching the target address.
+    Checks pairAddress, baseToken.address, and quoteToken.address.
+
+    Args:
+        pairs: List of PairModel instances
+        target_address: Target address (case-insensitive)
+
+    Returns:
+        Filtered list of PairModel instances
+    """
+    target_address_lower = target_address.lower()
+    return [
+        p
+        for p in pairs
+        if (p.pairAddress and p.pairAddress.lower() == target_address_lower)
+        or (
+            p.baseToken
+            and p.baseToken.address
+            and p.baseToken.address.lower() == target_address_lower
+        )
+        or (
+            p.quoteToken
+            and p.quoteToken.address
+            and p.quoteToken.address.lower() == target_address_lower
+        )
+    ]
+
+
+def create_error_response(
+    error_type: str,
+    message: str,
+    details: Optional[str] = None,
+    additional_data: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Create a standardized error response in JSON format.
+
+    Args:
+        error_type: Type/category of error
+        message: Human-readable error message
+        details: Optional additional details about the error
+        additional_data: Optional dictionary of additional data to include
+
+    Returns:
+        JSON string containing error information
+    """
+    response = {
+        "error": message,
+        "error_type": error_type,
+    }
+
+    if details:
+        response["details"] = details
+
+    if additional_data:
+        response.update(additional_data)
+
+    return json.dumps(response, indent=2)
+
+
+def create_no_results_response(
+    query_info: str,
+    reason: str = "no results found",
+    additional_data: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Create a standardized "no results found" response.
+
+    Args:
+        query_info: Information about the query that was performed
+        reason: Reason why no results were found
+        additional_data: Optional additional data to include
+
+    Returns:
+        JSON string containing no results information
+    """
+    response = {
+        "message": f"No results found for the query. Reason: {reason}.",
+        "query_info": query_info,
+        "pairs": [],
+    }
+
+    if additional_data:
+        response.update(additional_data)
+
+    return json.dumps(response, indent=2)
+
+
+def handle_validation_error(
+    error: ValidationError, query_info: str, data_length: Optional[int] = None
+) -> str:
+    """
+    Handle validation errors in a standardized way.
+
+    Args:
+        error: The ValidationError that occurred
+        query_info: Information about the query being processed
+        data_length: Optional length of the data that failed validation
+
+    Returns:
+        JSON error response string
+    """
+    log_message = f"Failed to validate DexScreener response structure for {query_info}. Error: {error}"
+    if data_length:
+        log_message += f". Raw data length: {data_length}"
+
+    logger.error(log_message, exc_info=True)
+
+    return create_error_response(
+        error_type="validation_error",
+        message="Failed to parse successful DexScreener API response",
+        details=str(error.errors()),
+        additional_data={"query_info": query_info},
+    )
+
+
+def truncate_large_fields(
+    data: Dict[str, Any], max_length: int = 500
+) -> Dict[str, Any]:
+    """
+    Truncate large string fields in error response data to avoid overwhelming the LLM.
+
+    Args:
+        data: Dictionary potentially containing large string fields
+        max_length: Maximum length for string fields before truncation
+
+    Returns:
+        Dictionary with truncated fields
+    """
+    truncated = data.copy()
+
+    for key in ["details", "response_body"]:
+        if isinstance(truncated.get(key), str) and len(truncated[key]) > max_length:
+            truncated[key] = truncated[key][:max_length] + "... (truncated)"
+
+    return truncated
+
+
+def group_pairs_by_token(pairs: List[PairModel]) -> Dict[str, List[PairModel]]:
+    """
+    Group pairs by token address for better organization in multi-token responses.
+
+    Args:
+        pairs: List of PairModel instances
+
+    Returns:
+        Dictionary mapping lowercase token addresses to lists of pairs
+    """
+    tokens_data = {}
+
+    for pair in pairs:
+        # Group by base token address
+        if pair.baseToken and pair.baseToken.address:
+            base_addr = pair.baseToken.address.lower()
+            if base_addr not in tokens_data:
+                tokens_data[base_addr] = []
+            tokens_data[base_addr].append(pair)
+
+        # Group by quote token address
+        if pair.quoteToken and pair.quoteToken.address:
+            quote_addr = pair.quoteToken.address.lower()
+            if quote_addr not in tokens_data:
+                tokens_data[quote_addr] = []
+            tokens_data[quote_addr].append(pair)
+
+    return tokens_data
+
+
+def validate_chain_id(chain_id: str) -> bool:
+    """
+    Validate if the chain ID is supported.
+
+    Args:
+        chain_id: Chain ID to validate
+
+    Returns:
+        True if chain ID is supported, False otherwise
+    """
+    return chain_id.lower() in SUPPORTED_CHAINS
+
+
+def format_success_response(data: Dict[str, Any]) -> str:
+    """
+    Format a successful response as JSON string.
+
+    Args:
+        data: Response data dictionary
+
+    Returns:
+        JSON formatted string
+    """
+    return json.dumps(data, indent=2)

intentkit/skills/xmtp/base.py

@@ -1,4 +1,4 @@
-from typing import Literal
+from typing import Dict, Literal
 
 from intentkit.skills.base import IntentKitSkill
 
@@ -9,7 +9,66 @@ class XmtpBaseTool(IntentKitSkill):
     # Set response format to content_and_artifact for returning tuple
     response_format: Literal["content", "content_and_artifact"] = "content_and_artifact"
 
+    # ChainId mapping for XMTP wallet_sendCalls (mainnet only)
+    CHAIN_ID_HEX_BY_NETWORK: Dict[str, str] = {
+        "ethereum-mainnet": "0x1",  # 1
+        "base-mainnet": "0x2105",  # 8453
+        "arbitrum-mainnet": "0xA4B1",  # 42161
+        "optimism-mainnet": "0xA",  # 10
+    }
+
+    # CDP network mapping for swap quote API (mainnet only)
+    NETWORK_FOR_CDP_MAPPING: Dict[str, str] = {
+        "ethereum-mainnet": "ethereum",
+        "base-mainnet": "base",
+        "arbitrum-mainnet": "arbitrum",
+        "optimism-mainnet": "optimism",
+    }
+
     @property
     def category(self) -> str:
         """Return the skill category."""
         return "xmtp"
+
+    def validate_network_and_get_chain_id(
+        self, network_id: str, skill_name: str
+    ) -> str:
+        """Validate network and return chain ID hex.
+
+        Args:
+            network_id: The network ID to validate
+            skill_name: The name of the skill for error messages
+
+        Returns:
+            The hex chain ID for the network
+
+        Raises:
+            ValueError: If the network is not supported
+        """
+        if network_id not in self.CHAIN_ID_HEX_BY_NETWORK:
+            supported_networks = ", ".join(self.CHAIN_ID_HEX_BY_NETWORK.keys())
+            raise ValueError(
+                f"XMTP {skill_name} supports the following networks: {supported_networks}. "
+                f"Current agent network: {network_id}"
+            )
+        return self.CHAIN_ID_HEX_BY_NETWORK[network_id]
+
+    def get_cdp_network(self, network_id: str) -> str:
+        """Get CDP network name for the given network ID.
+
+        Args:
+            network_id: The network ID
+
+        Returns:
+            The CDP network name
+
+        Raises:
+            ValueError: If the network is not supported for CDP
+        """
+        if network_id not in self.NETWORK_FOR_CDP_MAPPING:
+            supported_networks = ", ".join(self.NETWORK_FOR_CDP_MAPPING.keys())
+            raise ValueError(
+                f"CDP swap does not support network: {network_id}. "
+                f"Supported networks: {supported_networks}"
+            )
+        return self.NETWORK_FOR_CDP_MAPPING[network_id]

intentkit/skills/xmtp/price.py

@@ -21,7 +21,7 @@ class XmtpGetSwapPrice(XmtpBaseTool):
     """Skill for fetching indicative swap price using CDP SDK."""
 
     name: str = "xmtp_get_swap_price"
-    description: str = "Get an indicative swap price/quote for token pair and amount on Base networks using CDP."
+    description: str = "Get an indicative swap price/quote for token pair and amount on Ethereum, Base, Arbitrum, and Optimism mainnet networks using CDP."
     response_format: Literal["content", "content_and_artifact"] = "content"
     args_schema: Type[BaseModel] = SwapPriceInput
 
@@ -35,15 +35,19 @@ class XmtpGetSwapPrice(XmtpBaseTool):
         context = self.get_context()
         agent = context.agent
 
-        if agent.network_id not in ("base-mainnet", "base-sepolia"):
+        # Only support mainnet networks for price and swap
+        supported_networks = [
+            "ethereum-mainnet",
+            "base-mainnet",
+            "arbitrum-mainnet",
+            "optimism-mainnet",
+        ]
+        if agent.network_id not in supported_networks:
             raise ValueError(
-                f"Swap price only supported on base-mainnet or base-sepolia. Current: {agent.network_id}"
+                f"Swap price only supported on {', '.join(supported_networks)}. Current: {agent.network_id}"
             )
 
-        network_for_cdp = {
-            "base-mainnet": "base",
-            "base-sepolia": "base-sepolia",
-        }[agent.network_id]
+        network_for_cdp = self.get_cdp_network(agent.network_id)
 
         cdp_client = get_origin_cdp_client(self.skill_store)
         # Note: Don't use async with context manager as get_origin_cdp_client returns a managed global client

intentkit/skills/xmtp/swap.py

@@ -33,14 +33,14 @@ class XmtpSwap(XmtpBaseTool):
 
     Generates a wallet_sendCalls transaction request to perform a token swap.
     May include an ERC20 approval call followed by the router swap call.
-    Supports Base mainnet and Base Sepolia testnet.
+    Supports Ethereum, Polygon, Base, Arbitrum, and Optimism networks (both mainnet and testnet).
     """
 
     name: str = "xmtp_swap"
     description: str = (
-        "Create an XMTP transaction request for swapping tokens on Base using CDP swap quote. "
+        "Create an XMTP transaction request for swapping tokens using CDP swap quote. "
         "Returns a wallet_sendCalls payload that can include an optional approval call and the swap call. "
-        "Only supports base-mainnet and base-sepolia."
+        "Supports Ethereum, Base, Arbitrum, and Optimism mainnet networks."
     )
     args_schema: Type[BaseModel] = SwapInput
 
@@ -87,26 +87,25 @@ class XmtpSwap(XmtpBaseTool):
         context = self.get_context()
         agent = context.agent
 
-        # ChainId mapping for XMTP wallet_sendCalls
-        chain_id_hex_by_network = {
-            "base-mainnet": "0x2105",  # 8453
-            "base-sepolia": "0x14A34",  # 84532
-        }
-
-        if agent.network_id not in chain_id_hex_by_network:
+        # Only support mainnet networks for swap
+        supported_networks = [
+            "ethereum-mainnet",
+            "base-mainnet",
+            "arbitrum-mainnet",
+            "optimism-mainnet",
+        ]
+        if agent.network_id not in supported_networks:
             raise ValueError(
-                f"XMTP swap only supports base-mainnet or base-sepolia. Current agent network: {agent.network_id}"
+                f"Swap only supported on {', '.join(supported_networks)}. Current: {agent.network_id}"
             )
 
-        chain_id_hex = chain_id_hex_by_network[agent.network_id]
+        # Validate network and get chain ID
+        chain_id_hex = self.validate_network_and_get_chain_id(agent.network_id, "swap")
 
-        # CDP network mapping for swap quote API
+        # Get CDP network name
         # Reference: CDP SDK examples for swap quote and price
         # https://github.com/coinbase/cdp-sdk/blob/main/examples/python/evm/swaps/create_swap_quote.py
-        network_for_cdp = {
-            "base-mainnet": "base",
-            "base-sepolia": "base-sepolia",
-        }[agent.network_id]
+        network_for_cdp = self.get_cdp_network(agent.network_id)
 
         # Get CDP client from global origin helper (server-side credentials)
         cdp_client = get_origin_cdp_client(self.skill_store)

intentkit/skills/xmtp/transfer.py

@@ -13,9 +13,9 @@ class TransferInput(BaseModel):
     from_address: str = Field(description="The sender address for the transfer")
     to_address: str = Field(description="The recipient address for the transfer")
     amount: str = Field(
-        description="The amount to transfer (as string to handle large numbers)"
+        description="The amount to transfer in human-readable format (e.g., '1.5' for 1.5 ETH, '100' for 100 USDC). Do NOT multiply by token decimals."
     )
-    currency: str = Field(description="Currency symbol (e.g., 'ETH', 'USDC', 'DAI')")
+    currency: str = Field(description="Currency symbol (e.g., 'ETH', 'USDC', 'NATION')")
     token_contract_address: Optional[str] = Field(
         default=None,
         description="Token contract address for ERC20 transfers. Leave empty for ETH transfers.",
@@ -26,14 +26,10 @@ class XmtpTransfer(XmtpBaseTool):
     """Skill for creating XMTP transfer transactions."""
 
     name: str = "xmtp_transfer"
-    description: str = """Create an XMTP transaction request for transferring ETH or ERC20 tokens on Base mainnet.
-    
+    description: str = """Create an XMTP transaction request for transferring ETH or ERC20 tokens.
     This skill generates a wallet_sendCalls transaction request according to XMTP protocol 
-    that can be sent to users for signing. The transaction can transfer:
-    - ETH (when token_contract_address is not provided)
-    - ERC20 tokens (when token_contract_address is provided)
-    
-    Only supports Base mainnet network.
+    that can be sent to users for signing. 
+    Supports Ethereum, Polygon, Base, Arbitrum, and Optimism networks (both mainnet and testnet).
     """
     args_schema: Type[BaseModel] = TransferInput
 
@@ -61,19 +57,10 @@ class XmtpTransfer(XmtpBaseTool):
         context = self.get_context()
         agent = context.agent
 
-        # ChainId mapping for XMTP wallet_sendCalls
-        chain_id_hex_by_network = {
-            "base-mainnet": "0x2105",  # 8453
-            "base-sepolia": "0x14A34",  # 84532
-        }
-
-        if agent.network_id not in chain_id_hex_by_network:
-            raise ValueError(
-                f"XMTP transfer only supports base-mainnet or base-sepolia network. "
-                f"Current agent network: {agent.network_id}"
-            )
-
-        chain_id_hex = chain_id_hex_by_network[agent.network_id]
+        # Validate network and get chain ID
+        chain_id_hex = self.validate_network_and_get_chain_id(
+            agent.network_id, "transfer"
+        )
 
         # Validate token contract and get decimals
         if token_contract_address:

{intentkit-0.6.21.dev2.dist-info → intentkit-0.6.22.dev1.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: intentkit
-Version: 0.6.21.dev2
+Version: 0.6.22.dev1
 Summary: Intent-based AI Agent Platform - Core Package
-Project-URL: Homepage, https://github.com/crestal-network/intentkit
-Project-URL: Repository, https://github.com/crestal-network/intentkit
-Project-URL: Documentation, https://github.com/crestal-network/intentkit/tree/main/docs
-Project-URL: Bug Tracker, https://github.com/crestal-network/intentkit/issues
+Project-URL: Homepage, https://github.com/crestalnetwork/intentkit
+Project-URL: Repository, https://github.com/crestalnetwork/intentkit
+Project-URL: Documentation, https://github.com/crestalnetwork/intentkit/tree/main/docs
+Project-URL: Bug Tracker, https://github.com/crestalnetwork/intentkit/issues
 Author-email: hyacinthus <hyacinthus@gmail.com>
 License: MIT License