intentkit 0.6.13.dev2__py3-none-any.whl → 0.8.17__py3-none-any.whl

intentkit/skills/dexscreener/base.py

@@ -1,133 +1,125 @@
-import json
-import logging
-from typing import Any, Dict, Optional, Tuple
-
-import httpx
-from pydantic import Field
-
-from intentkit.abstracts.skill import SkillStoreABC
-from intentkit.skills.base import IntentKitSkill
-
-logger = logging.getLogger(__name__)
-
-DEXSCREENER_BASE_URL = "https://api.dexscreener.com"
-
-# Removed DexScreenerApiError as it won't be raised by _get anymore
-
-# ApiResult still represents (success_data, error_data)
-ApiResult = Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]
-
-
-class DexScreenerBaseTool(IntentKitSkill):
-    """
-    Generic base class for tools interacting with the Dex Screener API.
-    Handles shared logic like API calls and error reporting via return values.
-    """
-
-    skill_store: SkillStoreABC = Field(
-        description="The skill store for persisting data and configs."
-    )
-    base_url: str = DEXSCREENER_BASE_URL
-
-    @property
-    def category(self) -> str:
-        return "dexscreener"
-
-    async def _get(
-        self,
-        path: str,
-        params: Optional[Dict[str, Any]] = None,
-    ) -> ApiResult:
-        """
-        Makes an asynchronous GET request to the DexScreener API.
-
-        Args:
-            path: The API endpoint path (e.g., "/dex/search").
-            params: Optional dictionary of query parameters.
-
-        Returns:
-            A tuple (data, error_details):
-            - (dict, None): On HTTP 2xx success with valid JSON response.
-            - (None, dict): On any error (API error, connection error,
-                            JSON parsing error, unexpected error). The dict
-                            contains details including an 'error_type'.
-        """
-        if not path.startswith("/"):
-            path = "/" + path
-
-        url = f"{self.base_url}{path}"
-        headers = {"Accept": "application/json"}
-        method = "GET"
-
-        logger.debug(f"Calling DexScreener API: {method} {url} with params: {params}")
-        response = None  # Define response outside try block for access in except
-
-        try:
-            async with httpx.AsyncClient() as client:
-                response = await client.request(
-                    method, url, params=params, headers=headers
-                )
-
-                # Attempt to parse JSON response text
-                try:
-                    response_data = response.json()
-                except json.JSONDecodeError as json_err:
-                    logger.error(
-                        f"Failed to parse JSON response from {url}. Status: {response.status_code}. Response text: {response.text}",
-                        exc_info=True,
-                    )
-                    error_details = {
-                        "error": "Failed to parse DexScreener API response",
-                        "error_type": "parsing_error",
-                        "status_code": response.status_code,
-                        "details": response.text,  # Raw text causing the error
-                        "original_exception": str(json_err),
-                        "url": url,
-                    }
-                    return None, error_details  # Return parsing error
-
-                # Check HTTP status *after* attempting JSON parse
-                if response.is_success:  # 2xx
-                    logger.debug(
-                        f"DexScreener API success response status: {response.status_code}"
-                    )
-                    return response_data, None  # Success
-                else:  # 4xx/5xx
-                    logger.warning(
-                        f"DexScreener API returned error status: {response.status_code} - {response.text}"
-                    )
-                    error_details = {
-                        "error": "DexScreener API request failed",
-                        "error_type": "api_error",
-                        "status_code": response.status_code,
-                        "response_body": response_data,  # Parsed error body if available
-                        "url": url,
-                    }
-                    return None, error_details  # Return API error
-
-        except httpx.RequestError as req_err:
-            logger.error(
-                f"Request error connecting to DexScreener API: {req_err}", exc_info=True
-            )
-            error_details = {
-                "error": "Failed to connect to DexScreener API",
-                "error_type": "connection_error",
-                "details": str(req_err),
-                "url": url,
-            }
-            return None, error_details  # Return connection error
-
-        except Exception as e:
-            # Catch any other unexpected errors during the process
-            logger.exception(
-                f"An unexpected error occurred during DexScreener API GET call: {e}"
-            )
-            status_code = response.status_code if response else None
-            error_details = {
-                "error": "An unexpected error occurred during API call",
-                "error_type": "unexpected_error",
-                "status_code": status_code,  # Include if available
-                "details": str(e),
-                "url": url,
-            }
-            return None, error_details  # Return unexpected error
+import json
+import logging
+from typing import Any
+
+import httpx
+
+from intentkit.skills.base import IntentKitSkill
+from intentkit.skills.dexscreener.utils import DEXSCREENER_BASE_URL
+
+logger = logging.getLogger(__name__)
+
+# ApiResult still represents (success_data, error_data)
+ApiResult = tuple[dict[str, Any] | None, dict[str, Any] | None]
+
+
+class DexScreenerBaseTool(IntentKitSkill):
+    """
+    Generic base class for tools interacting with the Dex Screener API.
+    Handles shared logic like API calls and error reporting via return values.
+    """
+
+    base_url: str = DEXSCREENER_BASE_URL
+
+    @property
+    def category(self) -> str:
+        return "dexscreener"
+
+    async def _get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> ApiResult:
+        """
+        Makes an asynchronous GET request to the DexScreener API.
+
+        Args:
+            path: The API endpoint path (e.g., "/dex/search").
+            params: Optional dictionary of query parameters.
+
+        Returns:
+            A tuple (data, error_details):
+            - (dict, None): On HTTP 2xx success with valid JSON response.
+            - (None, dict): On any error (API error, connection error,
+                            JSON parsing error, unexpected error). The dict
+                            contains details including an 'error_type'.
+        """
+        if not path.startswith("/"):
+            path = "/" + path
+
+        url = f"{self.base_url}{path}"
+        headers = {"Accept": "application/json"}
+        method = "GET"
+
+        logger.debug(f"Calling DexScreener API: {method} {url} with params: {params}")
+        response = None  # Define response outside try block for access in except
+
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.request(
+                    method, url, params=params, headers=headers
+                )
+
+                # Attempt to parse JSON response text
+                try:
+                    response_data = response.json()
+                except json.JSONDecodeError as json_err:
+                    logger.error(
+                        f"Failed to parse JSON response from {url}. Status: {response.status_code}. Response text: {response.text}",
+                        exc_info=True,
+                    )
+                    error_details = {
+                        "error": "Failed to parse DexScreener API response",
+                        "error_type": "parsing_error",
+                        "status_code": response.status_code,
+                        "details": response.text,  # Raw text causing the error
+                        "original_exception": str(json_err),
+                        "url": url,
+                    }
+                    return None, error_details  # Return parsing error
+
+                # Check HTTP status *after* attempting JSON parse
+                if response.is_success:  # 2xx
+                    logger.debug(
+                        f"DexScreener API success response status: {response.status_code}"
+                    )
+                    return response_data, None  # Success
+                else:  # 4xx/5xx
+                    logger.warning(
+                        f"DexScreener API returned error status: {response.status_code} - {response.text}"
+                    )
+                    error_details = {
+                        "error": "DexScreener API request failed",
+                        "error_type": "api_error",
+                        "status_code": response.status_code,
+                        "response_body": response_data,  # Parsed error body if available
+                        "url": url,
+                    }
+                    return None, error_details  # Return API error
+
+        except httpx.RequestError as req_err:
+            logger.error(
+                f"Request error connecting to DexScreener API: {req_err}", exc_info=True
+            )
+            error_details = {
+                "error": "Failed to connect to DexScreener API",
+                "error_type": "connection_error",
+                "details": str(req_err),
+                "url": url,
+            }
+            return None, error_details  # Return connection error
+
+        except Exception as e:
+            # Catch any other unexpected errors during the process
+            logger.exception(
+                f"An unexpected error occurred during DexScreener API GET call: {e}"
+            )
+            status_code = response.status_code if response else None
+            error_details = {
+                "error": "An unexpected error occurred during API call",
+                "error_type": "unexpected_error",
+                "status_code": status_code,  # Include if available
+                "details": str(e),
+                "url": url,
+            }
+            return None, error_details  # Return unexpected error

intentkit/skills/dexscreener/get_pair_info.py

@@ -0,0 +1,158 @@
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from intentkit.skills.dexscreener.base import DexScreenerBaseTool
+from intentkit.skills.dexscreener.model.search_token_response import PairModel
+from intentkit.skills.dexscreener.utils import (
+    API_ENDPOINTS,
+    RATE_LIMITS,
+    create_error_response,
+    format_success_response,
+    truncate_large_fields,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class GetPairInfoInput(BaseModel):
+    """Input schema for the DexScreener get_pair_info tool."""
+
+    chain_id: str = Field(
+        description="The blockchain chain ID (e.g., 'ethereum', 'solana', 'bsc', 'polygon', 'arbitrum', 'base', 'avalanche')"
+    )
+    pair_address: str = Field(
+        description="The trading pair contract address (e.g., '0x1234...abcd' for Ethereum-based chains)"
+    )
+
+
+class GetPairInfo(DexScreenerBaseTool):
+    """
+    Tool to get detailed information about a specific trading pair on DexScreener.
+    """
+
+    name: str = "dexscreener_get_pair_info"
+    description: str = (
+        "Retrieves detailed information about a specific trading pair using chain ID and pair address. "
+        "Returns comprehensive data including current price, volume, liquidity, price changes, "
+        "market cap, FDV, transaction counts, and social links. "
+        "Use this tool when you have a specific pair address and need detailed trading metrics."
+    )
+    args_schema: type[BaseModel] = GetPairInfoInput
+
+    async def _arun(
+        self,
+        chain_id: str,
+        pair_address: str,
+        **kwargs: Any,
+    ) -> str:
+        """Implementation to get specific pair information."""
+
+        # Apply rate limiting
+        await self.global_rate_limit_by_skill(
+            limit=RATE_LIMITS["pairs"],
+            seconds=60,
+        )
+
+        logger.info(
+            f"Executing DexScreener get_pair_info tool with chain_id: '{chain_id}', "
+            f"pair_address: '{pair_address}'"
+        )
+
+        try:
+            # Construct API path
+            api_path = f"{API_ENDPOINTS['pairs']}/{chain_id}/{pair_address}"
+
+            data, error_details = await self._get(path=api_path)
+
+            if error_details:
+                return await self._handle_error_response(error_details)
+
+            if not data:
+                logger.error(f"No data returned for pair {pair_address} on {chain_id}")
+                return create_error_response(
+                    error_type="empty_success",
+                    message="API call returned empty success response.",
+                    additional_data={
+                        "chain_id": chain_id,
+                        "pair_address": pair_address,
+                    },
+                )
+
+            # The API returns a single pair object, not wrapped in a pairs array
+            if not isinstance(data, dict):
+                return create_error_response(
+                    error_type="format_error",
+                    message="Unexpected response format - expected object",
+                    additional_data={
+                        "chain_id": chain_id,
+                        "pair_address": pair_address,
+                    },
+                )
+
+            try:
+                # Validate the response using our existing PairModel
+                pair_data = PairModel.model_validate(data)
+                logger.info(
+                    f"Successfully retrieved pair info for {pair_address} on {chain_id}"
+                )
+
+                return format_success_response(
+                    {
+                        "pair": pair_data.model_dump(),
+                        "chain_id": chain_id,
+                        "pair_address": pair_address,
+                    }
+                )
+
+            except Exception as validation_error:
+                logger.error(
+                    f"Failed to validate pair response for {pair_address} on {chain_id}: {validation_error}",
+                    exc_info=True,
+                )
+                # Return raw data if validation fails
+                return format_success_response(
+                    {
+                        "pair": data,
+                        "chain_id": chain_id,
+                        "pair_address": pair_address,
+                        "validation_warning": "Response structure may have changed",
+                    }
+                )
+
+        except Exception as e:
+            return await self._handle_unexpected_runtime_error(
+                e, f"{chain_id}/{pair_address}"
+            )
+
+    async def _handle_error_response(self, error_details: dict) -> str:
+        """Formats error details (from _get) into a JSON string."""
+        if error_details.get("error_type") in [
+            "connection_error",
+            "parsing_error",
+            "unexpected_error",
+        ]:
+            logger.error(
+                f"DexScreener get_pair_info tool encountered an error: {error_details}"
+            )
+        else:  # api_error
+            logger.warning(f"DexScreener API returned an error: {error_details}")
+
+        # Truncate potentially large fields before returning to user/LLM
+        truncated_details = truncate_large_fields(error_details)
+        return format_success_response(truncated_details)
+
+    async def _handle_unexpected_runtime_error(
+        self, e: Exception, query_info: str
+    ) -> str:
+        """Formats unexpected runtime exception details into a JSON string."""
+        logger.exception(
+            f"An unexpected runtime error occurred in get_pair_info tool _arun method for {query_info}: {e}"
+        )
+        return create_error_response(
+            error_type="runtime_error",
+            message="An unexpected internal error occurred processing the pair info request",
+            details=str(e),
+            additional_data={"query_info": query_info},
+        )

intentkit/skills/dexscreener/get_token_pairs.py

@@ -0,0 +1,165 @@
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationError
+
+from intentkit.skills.dexscreener.base import DexScreenerBaseTool
+from intentkit.skills.dexscreener.model.search_token_response import (
+    SearchTokenResponseModel,
+)
+from intentkit.skills.dexscreener.utils import (
+    API_ENDPOINTS,
+    RATE_LIMITS,
+    create_error_response,
+    create_no_results_response,
+    format_success_response,
+    get_liquidity_value,
+    handle_validation_error,
+    truncate_large_fields,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class GetTokenPairsInput(BaseModel):
+    """Input schema for the DexScreener get_token_pairs tool."""
+
+    chain_id: str = Field(
+        description="The blockchain chain ID (e.g., 'ethereum', 'solana', 'bsc', 'polygon', 'arbitrum', 'base', 'avalanche')"
+    )
+    token_address: str = Field(
+        description="The token contract address (e.g., '0x1234...abcd' for Ethereum-based chains)"
+    )
+
+
+class GetTokenPairs(DexScreenerBaseTool):
+    """
+    Tool to get all trading pairs for a specific token on DexScreener.
+    """
+
+    name: str = "dexscreener_get_token_pairs"
+    description: str = (
+        "Finds all trading pairs for a specific token using chain ID and token address. "
+        "Returns a list of all pools/pairs where this token is traded, including pair addresses, "
+        "DEX information, liquidity, volume, and pricing data for each pair. "
+        "Use this tool to analyze all available trading venues and liquidity sources for a specific token."
+    )
+    args_schema: type[BaseModel] = GetTokenPairsInput
+
+    async def _arun(
+        self,
+        chain_id: str,
+        token_address: str,
+        **kwargs: Any,
+    ) -> str:
+        """Implementation to get all pairs for a specific token."""
+
+        # Apply rate limiting
+        await self.global_rate_limit_by_skill(
+            limit=RATE_LIMITS["token_pairs"],
+            seconds=60,
+        )
+
+        logger.info(
+            f"Executing DexScreener get_token_pairs tool with chain_id: '{chain_id}', "
+            f"token_address: '{token_address}'"
+        )
+
+        try:
+            # Construct API path
+            api_path = f"{API_ENDPOINTS['token_pairs']}/{chain_id}/{token_address}"
+
+            data, error_details = await self._get(path=api_path)
+
+            if error_details:
+                return await self._handle_error_response(error_details)
+
+            if not data:
+                logger.error(
+                    f"No data returned for token {token_address} on {chain_id}"
+                )
+                return create_error_response(
+                    error_type="empty_success",
+                    message="API call returned empty success response.",
+                    additional_data={
+                        "chain_id": chain_id,
+                        "token_address": token_address,
+                    },
+                )
+
+            try:
+                # Validate response using SearchTokenResponseModel since API returns similar structure
+                result = SearchTokenResponseModel.model_validate(data)
+            except ValidationError as e:
+                return handle_validation_error(
+                    e, f"{chain_id}/{token_address}", len(str(data))
+                )
+
+            if not result.pairs:
+                return create_no_results_response(
+                    f"{chain_id}/{token_address}",
+                    reason="no trading pairs found for this token",
+                )
+
+            pairs_list = [p for p in result.pairs if p is not None]
+
+            if not pairs_list:
+                return create_no_results_response(
+                    f"{chain_id}/{token_address}",
+                    reason="all pairs were null or invalid",
+                )
+
+            # Sort pairs by liquidity (highest first) for better UX
+            try:
+                pairs_list.sort(key=get_liquidity_value, reverse=True)
+            except Exception as sort_err:
+                logger.warning(f"Failed to sort pairs by liquidity: {sort_err}")
+
+            logger.info(
+                f"Found {len(pairs_list)} pairs for token {token_address} on {chain_id}"
+            )
+
+            return format_success_response(
+                {
+                    "pairs": [p.model_dump() for p in pairs_list],
+                    "chain_id": chain_id,
+                    "token_address": token_address,
+                    "total_pairs": len(pairs_list),
+                }
+            )
+
+        except Exception as e:
+            return await self._handle_unexpected_runtime_error(
+                e, f"{chain_id}/{token_address}"
+            )
+
+    async def _handle_error_response(self, error_details: dict) -> str:
+        """Formats error details (from _get) into a JSON string."""
+        if error_details.get("error_type") in [
+            "connection_error",
+            "parsing_error",
+            "unexpected_error",
+        ]:
+            logger.error(
+                f"DexScreener get_token_pairs tool encountered an error: {error_details}"
+            )
+        else:  # api_error
+            logger.warning(f"DexScreener API returned an error: {error_details}")
+
+        # Truncate potentially large fields before returning to user/LLM
+        truncated_details = truncate_large_fields(error_details)
+        return format_success_response(truncated_details)
+
+    async def _handle_unexpected_runtime_error(
+        self, e: Exception, query_info: str
+    ) -> str:
+        """Formats unexpected runtime exception details into a JSON string."""
+        logger.exception(
+            f"An unexpected runtime error occurred in get_token_pairs tool _arun method for {query_info}: {e}"
+        )
+        return create_error_response(
+            error_type="runtime_error",
+            message="An unexpected internal error occurred processing the token pairs request",
+            details=str(e),
+            additional_data={"query_info": query_info},
+        )