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

intentkit/skills/dexscreener/search_token.py

@@ -1,184 +1,182 @@
-import logging
-from typing import Any, Optional, Type
-
-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,
-    MAX_SEARCH_RESULTS,
-    SEARCH_DISCLAIMER,
-    QueryType,
-    SortBy,
-    VolumeTimeframe,
-    create_error_response,
-    create_no_results_response,
-    determine_query_type,
-    filter_address_pairs,
-    filter_ticker_pairs,
-    format_success_response,
-    handle_validation_error,
-    sort_pairs_by_criteria,
-    truncate_large_fields,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class SearchTokenInput(BaseModel):
-    """Input schema for the DexScreener search_token tool."""
-
-    query: str = Field(
-        description="The search query string (e.g., token symbol 'WIF', pair address, token address '0x...', token name 'Dogwifhat', or ticker '$WIF'). Prefixing with '$' filters results to match the base token symbol exactly (case-insensitive)."
-    )
-    sort_by: Optional[SortBy] = Field(
-        default=SortBy.LIQUIDITY,
-        description="Sort preference for the results. Options: 'liquidity' (default) or 'volume'",
-    )
-    volume_timeframe: Optional[VolumeTimeframe] = Field(
-        default=VolumeTimeframe.TWENTY_FOUR_HOUR,
-        description="Define which timeframe should we use if the 'sort_by' is 'volume'. Available options: '5_minutes', '1_hour', '6_hour', '24_hour'",
-    )
-
-
-class SearchToken(DexScreenerBaseTool):
-    """
-    Tool to search for token pairs on DexScreener based on a query string.
-    """
-
-    name: str = "dexscreener_search_token"
-    description: str = (
-        f"Searches DexScreener for token pairs matching the provided query string "
-        f"(e.g., token symbol like 'WIF', pair address, token name like 'Dogwifhat', or ticker like '$WIF'). "
-        f"If the query starts with '$', it filters results to only include pairs where the base token symbol exactly matches the ticker (case-insensitive). "
-        f"Returns a list of matching pairs with details like price, volume, liquidity, etc., "
-        f"sorted by the specified criteria (via 'sort_by': 'liquidity', 'volume'; defaults to 'liquidity'), "
-        f"limited to the top {MAX_SEARCH_RESULTS}. "
-        f"Use this tool to find token information based on user queries."
-    )
-    args_schema: Type[BaseModel] = SearchTokenInput
-
-    async def _arun(
-        self,
-        query: str,
-        sort_by: Optional[SortBy] = SortBy.LIQUIDITY,
-        volume_timeframe: Optional[VolumeTimeframe] = VolumeTimeframe.TWENTY_FOUR_HOUR,
-        **kwargs: Any,
-    ) -> str:
-        """Implementation to search token, with filtering based on query type."""
-
-        # dexscreener 300 request per minute (across all user) based on dexscreener docs
-        # https://docs.dexscreener.com/api/reference#get-latest-dex-search
-        await self.user_rate_limit_by_category(
-            # using hardcoded user_id to make sure it limit across all users
-            user_id=f"{self.category}{self.name}",
-            limit=300,
-            minutes=1,
-        )
-
-        sort_by = sort_by or SortBy.LIQUIDITY
-        volume_timeframe = volume_timeframe or VolumeTimeframe.TWENTY_FOUR_HOUR
-
-        # Determine query type
-        query_type = determine_query_type(query)
-
-        # Process query based on type
-        if query_type == QueryType.TICKER:
-            search_query = query[1:]  # Remove the '$' prefix
-            target_ticker = search_query.upper()
-        else:
-            search_query = query
-            target_ticker = None
-
-        logger.info(
-            f"Executing DexScreener search_token tool with query: '{query}' "
-            f"(interpreted as {query_type.value} search for '{search_query}'), "
-            f"sort_by: {sort_by}"
-        )
-
-        try:
-            data, error_details = await self._get(
-                path=API_ENDPOINTS["search"], params={"q": search_query}
-            )
-
-            if error_details:
-                return await self._handle_error_response(error_details)
-            if not data:
-                logger.error(f"No data or error details returned for query '{query}'")
-                return create_error_response(
-                    error_type="empty_success",
-                    message="API call returned empty success response.",
-                    additional_data={"query": query},
-                )
-
-            try:
-                result = SearchTokenResponseModel.model_validate(data)
-            except ValidationError as e:
-                return handle_validation_error(e, query, len(str(data)))
-
-            if not result.pairs:
-                return create_no_results_response(
-                    query, reason="returned null or empty for pairs"
-                )
-
-            pairs_list = [p for p in result.pairs if p is not None]
-
-            # Apply filtering based on query type
-            if query_type == QueryType.TICKER and target_ticker:
-                pairs_list = filter_ticker_pairs(pairs_list, target_ticker)
-                if not pairs_list:
-                    return create_no_results_response(
-                        query, reason=f"no match for ticker '${target_ticker}'"
-                    )
-            elif query_type == QueryType.ADDRESS:
-                pairs_list = filter_address_pairs(pairs_list, search_query)
-                if not pairs_list:
-                    return create_no_results_response(
-                        query, reason=f"no match for address '{search_query}'"
-                    )
-
-            # Sort pairs by specified criteria
-            pairs_list = sort_pairs_by_criteria(pairs_list, sort_by, volume_timeframe)
-
-            # If sorting failed, pairs_list will be returned unchanged by the utility function
-
-            final_count = min(len(pairs_list), MAX_SEARCH_RESULTS)
-            logger.info(f"Returning {final_count} pairs for query '{query}'")
-            return format_success_response(
-                {
-                    **SEARCH_DISCLAIMER,
-                    "pairs": [p.model_dump() for p in pairs_list[:MAX_SEARCH_RESULTS]],
-                }
-            )
-        except Exception as e:
-            return await self._handle_unexpected_runtime_error(e, query)
-
-    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 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: str) -> str:
-        """Formats unexpected runtime exception details into a JSON string."""
-        logger.exception(
-            f"An unexpected runtime error occurred in search_token tool _arun method for query '{query}': {e}"
-        )
-        return create_error_response(
-            error_type="runtime_error",
-            message="An unexpected internal error occurred processing the search request",
-            details=str(e),
-            additional_data={"query": query},
-        )
+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,
+    MAX_SEARCH_RESULTS,
+    SEARCH_DISCLAIMER,
+    QueryType,
+    SortBy,
+    VolumeTimeframe,
+    create_error_response,
+    create_no_results_response,
+    determine_query_type,
+    filter_address_pairs,
+    filter_ticker_pairs,
+    format_success_response,
+    handle_validation_error,
+    sort_pairs_by_criteria,
+    truncate_large_fields,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SearchTokenInput(BaseModel):
+    """Input schema for the DexScreener search_token tool."""
+
+    query: str = Field(
+        description="The search query string (e.g., token symbol 'WIF', pair address, token address '0x...', token name 'Dogwifhat', or ticker '$WIF'). Prefixing with '$' filters results to match the base token symbol exactly (case-insensitive)."
+    )
+    sort_by: SortBy | None = Field(
+        default=SortBy.LIQUIDITY,
+        description="Sort preference for the results. Options: 'liquidity' (default) or 'volume'",
+    )
+    volume_timeframe: VolumeTimeframe | None = Field(
+        default=VolumeTimeframe.TWENTY_FOUR_HOUR,
+        description="Define which timeframe should we use if the 'sort_by' is 'volume'. Available options: '5_minutes', '1_hour', '6_hour', '24_hour'",
+    )
+
+
+class SearchToken(DexScreenerBaseTool):
+    """
+    Tool to search for token pairs on DexScreener based on a query string.
+    """
+
+    name: str = "dexscreener_search_token"
+    description: str = (
+        f"Searches DexScreener for token pairs matching the provided query string "
+        f"(e.g., token symbol like 'WIF', pair address, token name like 'Dogwifhat', or ticker like '$WIF'). "
+        f"If the query starts with '$', it filters results to only include pairs where the base token symbol exactly matches the ticker (case-insensitive). "
+        f"Returns a list of matching pairs with details like price, volume, liquidity, etc., "
+        f"sorted by the specified criteria (via 'sort_by': 'liquidity', 'volume'; defaults to 'liquidity'), "
+        f"limited to the top {MAX_SEARCH_RESULTS}. "
+        f"Use this tool to find token information based on user queries."
+    )
+    args_schema: type[BaseModel] = SearchTokenInput
+
+    async def _arun(
+        self,
+        query: str,
+        sort_by: SortBy | None = SortBy.LIQUIDITY,
+        volume_timeframe: VolumeTimeframe | None = VolumeTimeframe.TWENTY_FOUR_HOUR,
+        **kwargs: Any,
+    ) -> str:
+        """Implementation to search token, with filtering based on query type."""
+
+        # dexscreener 300 request per minute (across all user) based on dexscreener docs
+        # https://docs.dexscreener.com/api/reference#get-latest-dex-search
+        await self.global_rate_limit_by_skill(
+            limit=300,
+            seconds=60,
+        )
+
+        sort_by = sort_by or SortBy.LIQUIDITY
+        volume_timeframe = volume_timeframe or VolumeTimeframe.TWENTY_FOUR_HOUR
+
+        # Determine query type
+        query_type = determine_query_type(query)
+
+        # Process query based on type
+        if query_type == QueryType.TICKER:
+            search_query = query[1:]  # Remove the '$' prefix
+            target_ticker = search_query.upper()
+        else:
+            search_query = query
+            target_ticker = None
+
+        logger.info(
+            f"Executing DexScreener search_token tool with query: '{query}' "
+            f"(interpreted as {query_type.value} search for '{search_query}'), "
+            f"sort_by: {sort_by}"
+        )
+
+        try:
+            data, error_details = await self._get(
+                path=API_ENDPOINTS["search"], params={"q": search_query}
+            )
+
+            if error_details:
+                return await self._handle_error_response(error_details)
+            if not data:
+                logger.error(f"No data or error details returned for query '{query}'")
+                return create_error_response(
+                    error_type="empty_success",
+                    message="API call returned empty success response.",
+                    additional_data={"query": query},
+                )
+
+            try:
+                result = SearchTokenResponseModel.model_validate(data)
+            except ValidationError as e:
+                return handle_validation_error(e, query, len(str(data)))
+
+            if not result.pairs:
+                return create_no_results_response(
+                    query, reason="returned null or empty for pairs"
+                )
+
+            pairs_list = [p for p in result.pairs if p is not None]
+
+            # Apply filtering based on query type
+            if query_type == QueryType.TICKER and target_ticker:
+                pairs_list = filter_ticker_pairs(pairs_list, target_ticker)
+                if not pairs_list:
+                    return create_no_results_response(
+                        query, reason=f"no match for ticker '${target_ticker}'"
+                    )
+            elif query_type == QueryType.ADDRESS:
+                pairs_list = filter_address_pairs(pairs_list, search_query)
+                if not pairs_list:
+                    return create_no_results_response(
+                        query, reason=f"no match for address '{search_query}'"
+                    )
+
+            # Sort pairs by specified criteria
+            pairs_list = sort_pairs_by_criteria(pairs_list, sort_by, volume_timeframe)
+
+            # If sorting failed, pairs_list will be returned unchanged by the utility function
+
+            final_count = min(len(pairs_list), MAX_SEARCH_RESULTS)
+            logger.info(f"Returning {final_count} pairs for query '{query}'")
+            return format_success_response(
+                {
+                    **SEARCH_DISCLAIMER,
+                    "pairs": [p.model_dump() for p in pairs_list[:MAX_SEARCH_RESULTS]],
+                }
+            )
+        except Exception as e:
+            return await self._handle_unexpected_runtime_error(e, query)
+
+    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 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: str) -> str:
+        """Formats unexpected runtime exception details into a JSON string."""
+        logger.exception(
+            f"An unexpected runtime error occurred in search_token tool _arun method for query '{query}': {e}"
+        )
+        return create_error_response(
+            error_type="runtime_error",
+            message="An unexpected internal error occurred processing the search request",
+            details=str(e),
+            additional_data={"query": query},
+        )

intentkit/skills/dexscreener/utils.py

@@ -4,8 +4,9 @@ Utility functions and constants for DexScreener skills.
 
 import json
 import logging
+from collections.abc import Callable
 from enum import Enum
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any
 
 from pydantic import ValidationError
 
@@ -175,11 +176,11 @@ def get_sort_function(
 
 
 def sort_pairs_by_criteria(
-    pairs: List[PairModel],
+    pairs: list[PairModel],
     sort_by: SortBy = SortBy.LIQUIDITY,
     volume_timeframe: VolumeTimeframe = VolumeTimeframe.TWENTY_FOUR_HOUR,
     reverse: bool = True,
-) -> List[PairModel]:
+) -> list[PairModel]:
     """
     Sort pairs by the specified criteria.
 
@@ -200,7 +201,7 @@ def sort_pairs_by_criteria(
         return pairs  # Return original list if sorting fails
 
 
-def filter_ticker_pairs(pairs: List[PairModel], target_ticker: str) -> List[PairModel]:
+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.
 
@@ -222,8 +223,8 @@ def filter_ticker_pairs(pairs: List[PairModel], target_ticker: str) -> List[Pair
 
 
 def filter_address_pairs(
-    pairs: List[PairModel], target_address: str
-) -> List[PairModel]:
+    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.
@@ -256,8 +257,8 @@ def filter_address_pairs(
 def create_error_response(
     error_type: str,
     message: str,
-    details: Optional[str] = None,
-    additional_data: Optional[Dict[str, Any]] = None,
+    details: str | None = None,
+    additional_data: dict[str, Any] | None = None,
 ) -> str:
     """
     Create a standardized error response in JSON format.
@@ -288,7 +289,7 @@ def create_error_response(
 def create_no_results_response(
     query_info: str,
     reason: str = "no results found",
-    additional_data: Optional[Dict[str, Any]] = None,
+    additional_data: dict[str, Any] | None = None,
 ) -> str:
     """
     Create a standardized "no results found" response.
@@ -314,7 +315,7 @@ def create_no_results_response(
 
 
 def handle_validation_error(
-    error: ValidationError, query_info: str, data_length: Optional[int] = None
+    error: ValidationError, query_info: str, data_length: int | None = None
 ) -> str:
     """
     Handle validation errors in a standardized way.
@@ -342,8 +343,8 @@ def handle_validation_error(
 
 
 def truncate_large_fields(
-    data: Dict[str, Any], max_length: int = 500
-) -> Dict[str, Any]:
+    data: dict[str, Any], max_length: int = 500
+) -> dict[str, Any]:
     """
     Truncate large string fields in error response data to avoid overwhelming the LLM.
 
@@ -363,7 +364,7 @@ def truncate_large_fields(
     return truncated
 
 
-def group_pairs_by_token(pairs: List[PairModel]) -> Dict[str, List[PairModel]]:
+def group_pairs_by_token(pairs: list[PairModel]) -> dict[str, list[PairModel]]:
     """
     Group pairs by token address for better organization in multi-token responses.
 
@@ -406,7 +407,7 @@ def validate_chain_id(chain_id: str) -> bool:
     return chain_id.lower() in SUPPORTED_CHAINS
 
 
-def format_success_response(data: Dict[str, Any]) -> str:
+def format_success_response(data: dict[str, Any]) -> str:
     """
     Format a successful response as JSON string.
 

intentkit/skills/dune_analytics/__init__.py

@@ -4,16 +4,15 @@ Loads and initializes skills for fetching data from Dune Analytics API.
 """
 
 import logging
-from typing import Dict, List, Optional, TypedDict
+from typing import TypedDict
 
-from intentkit.abstracts.skill import SkillStoreABC
 from intentkit.skills.base import SkillConfig, SkillState
 from intentkit.skills.dune_analytics.base import DuneBaseTool
 
 logger = logging.getLogger(__name__)
 
 # Cache for skill instances
-_skill_cache: Dict[str, DuneBaseTool] = {}
+_skill_cache: dict[str, DuneBaseTool] = {}
 
 
 class SkillStates(TypedDict):
@@ -33,9 +32,8 @@ class Config(SkillConfig):
 async def get_skills(
     config: Config,
     is_private: bool,
-    store: SkillStoreABC,
     **kwargs,
-) -> List[DuneBaseTool]:
+) -> list[DuneBaseTool]:
     """Load Dune Analytics skills based on configuration.
 
     Args:
@@ -59,7 +57,7 @@ async def get_skills(
 
     loaded_skills = []
     for name in available_skills:
-        skill = get_dune_skill(name, store)
+        skill = get_dune_skill(name)
         if skill:
             logger.info("Successfully loaded skill: %s", name)
             loaded_skills.append(skill)
@@ -69,7 +67,7 @@ async def get_skills(
     return loaded_skills
 
 
-def get_dune_skill(name: str, store: SkillStoreABC) -> Optional[DuneBaseTool]:
+def get_dune_skill(name: str) -> DuneBaseTool | None:
     """Retrieve a Dune Analytics skill instance by name.
 
     Args:
@@ -87,11 +85,11 @@ def get_dune_skill(name: str, store: SkillStoreABC) -> Optional[DuneBaseTool]:
         if name == "fetch_nation_metrics":
             from .fetch_nation_metrics import FetchNationMetrics
 
-            _skill_cache[name] = FetchNationMetrics(skill_store=store)
+            _skill_cache[name] = FetchNationMetrics()
         elif name == "fetch_kol_buys":
             from .fetch_kol_buys import FetchKOLBuys
 
-            _skill_cache[name] = FetchKOLBuys(skill_store=store)
+            _skill_cache[name] = FetchKOLBuys()
         else:
             logger.warning("Unknown Dune Analytics skill: %s", name)
             return None

intentkit/skills/dune_analytics/base.py

@@ -1,52 +1,48 @@
-"""Base module for Dune Analytics skills.
-
-Provides shared functionality for interacting with the Dune Analytics API.
-"""
-
-from typing import Type
-
-from langchain.tools.base import ToolException
-from pydantic import BaseModel, Field
-
-from intentkit.abstracts.skill import SkillStoreABC
-from intentkit.skills.base import IntentKitSkill
-
-
-class DuneBaseTool(IntentKitSkill):
-    """Base class for Dune Analytics skills.
-
-    Offers common functionality like API key retrieval and Dune API interaction.
-    """
-
-    name: str = Field(description="Tool name")
-    description: str = Field(description="Tool description")
-    args_schema: Type[BaseModel]
-    skill_store: SkillStoreABC = Field(description="Skill store for data persistence")
-
-    def get_api_key(self) -> str:
-        """Retrieve the Dune Analytics API key from context.
-
-        Returns:
-            API key string.
-
-        Raises:
-            ToolException: If the API key is not found.
-        """
-        context = self.get_context()
-        skill_config = context.agent.skill_config(self.category)
-        api_key_provider = skill_config.get("api_key_provider")
-        if api_key_provider == "agent_owner":
-            api_key = skill_config.get("api_key")
-            if api_key:
-                return api_key
-            else:
-                raise ToolException("No api_key found in agent_owner configuration")
-        else:
-            raise ToolException(
-                f"Invalid API key provider: {api_key_provider}. Only 'agent_owner' is supported for Dune Analytics."
-            )
-
-    @property
-    def category(self) -> str:
-        """Category of the skill."""
-        return "dune_analytics"
+"""Base module for Dune Analytics skills.
+
+Provides shared functionality for interacting with the Dune Analytics API.
+"""
+
+from langchain_core.tools.base import ToolException
+from pydantic import BaseModel, Field
+
+from intentkit.skills.base import IntentKitSkill
+
+
+class DuneBaseTool(IntentKitSkill):
+    """Base class for Dune Analytics skills.
+
+    Offers common functionality like API key retrieval and Dune API interaction.
+    """
+
+    name: str = Field(description="Tool name")
+    description: str = Field(description="Tool description")
+    args_schema: type[BaseModel]
+
+    def get_api_key(self) -> str:
+        """Retrieve the Dune Analytics API key from context.
+
+        Returns:
+            API key string.
+
+        Raises:
+            ToolException: If the API key is not found.
+        """
+        context = self.get_context()
+        skill_config = context.agent.skill_config(self.category)
+        api_key_provider = skill_config.get("api_key_provider")
+        if api_key_provider == "agent_owner":
+            api_key = skill_config.get("api_key")
+            if api_key:
+                return api_key
+            else:
+                raise ToolException("No api_key found in agent_owner configuration")
+        else:
+            raise ToolException(
+                f"Invalid API key provider: {api_key_provider}. Only 'agent_owner' is supported for Dune Analytics."
+            )
+
+    @property
+    def category(self) -> str:
+        """Category of the skill."""
+        return "dune_analytics"