intentkit 0.8.16.dev1__py3-none-any.whl → 0.8.17.dev2__py3-none-any.whl

intentkit/skills/dexscreener/search_token.py

@@ -1,182 +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.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},
-        )
+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,7 +4,7 @@ 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.skills.base import SkillConfig, SkillState
 from intentkit.skills.dune_analytics.base import DuneBaseTool
@@ -12,7 +12,7 @@ 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,7 +33,7 @@ async def get_skills(
     config: Config,
     is_private: bool,
     **kwargs,
-) -> List[DuneBaseTool]:
+) -> list[DuneBaseTool]:
     """Load Dune Analytics skills based on configuration.
 
     Args:
@@ -67,7 +67,7 @@ async def get_skills(
     return loaded_skills
 
 
-def get_dune_skill(name: str) -> Optional[DuneBaseTool]:
+def get_dune_skill(name: str) -> DuneBaseTool | None:
     """Retrieve a Dune Analytics skill instance by name.
 
     Args:

intentkit/skills/dune_analytics/base.py

@@ -3,8 +3,6 @@
 Provides shared functionality for interacting with the Dune Analytics API.
 """
 
-from typing import Type
-
 from langchain_core.tools.base import ToolException
 from pydantic import BaseModel, Field
 
@@ -19,7 +17,7 @@ class DuneBaseTool(IntentKitSkill):
 
     name: str = Field(description="Tool name")
     description: str = Field(description="Tool description")
-    args_schema: Type[BaseModel]
+    args_schema: type[BaseModel]
 
     def get_api_key(self) -> str:
         """Retrieve the Dune Analytics API key from context.

intentkit/skills/dune_analytics/fetch_kol_buys.py

@@ -3,7 +3,7 @@
 Uses query ID 4832844 to retrieve a list of KOL buy transactions.
 """
 
-from typing import Any, Dict, Type
+from typing import Any
 
 import httpx
 from pydantic import BaseModel, Field
@@ -28,7 +28,7 @@ class KOLBuysInput(BaseModel):
 class KOLBuyData(BaseModel):
     """Data model for KOL buy results."""
 
-    data: Dict[str, Any] = Field(description="KOL buy data from Dune API")
+    data: dict[str, Any] = Field(description="KOL buy data from Dune API")
     error: str = Field(default="", description="Error message if fetch failed")
 
 
@@ -47,14 +47,14 @@ class FetchKOLBuys(DuneBaseTool):
         "Fetches a list of KOL memecoin buy transactions on Solana from Dune Analytics API using query ID 4832844. "
         "Supports a configurable limit for the number of results. Handles rate limits with retries."
     )
-    args_schema: Type[BaseModel] = KOLBuysInput
+    args_schema: type[BaseModel] = KOLBuysInput
 
     @retry(
         stop=stop_after_attempt(3), wait=wait_exponential(multiplier=5, min=5, max=60)
     )
     async def fetch_data(
         self, query_id: int, api_key: str, limit: int = 10
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Fetch data for a specific Dune query.
 
         Args:

intentkit/skills/dune_analytics/fetch_nation_metrics.py

@@ -5,7 +5,7 @@ Supports predefined metrics (e.g., total_users, unique_ai_citizens) or direct qu
 
 import difflib
 import re
-from typing import Any, Dict, Type
+from typing import Any
 
 import httpx
 from pydantic import BaseModel, Field
@@ -62,14 +62,14 @@ class MetricData(BaseModel):
     """Data model for a single metric result."""
 
     metric: str = Field(description="Metric name or query ID")
-    data: Dict[str, Any] = Field(description="Metric data from Dune API")
+    data: dict[str, Any] = Field(description="Metric data from Dune API")
     error: str = Field(default="", description="Error message if fetch failed")
 
 
 class NationMetricsOutput(BaseModel):
     """Output schema for Crestal Nation metrics."""
 
-    metrics: Dict[str, MetricData] = Field(
+    metrics: dict[str, MetricData] = Field(
         description="Dictionary of metric names or query IDs to their data"
     )
     summary: str = Field(description="Summary of fetched metrics")
@@ -84,7 +84,7 @@ class FetchNationMetrics(DuneBaseTool):
         "Supports predefined metrics, direct query IDs, or all configured metrics if none specified. "
         "Handles rate limits with retries."
     )
-    args_schema: Type[BaseModel] = NationMetricsInput
+    args_schema: type[BaseModel] = NationMetricsInput
 
     def normalize_metric(self, metric: str) -> str:
         """Normalize a metric string for matching.
@@ -122,7 +122,7 @@ class FetchNationMetrics(DuneBaseTool):
     )
     async def fetch_data(
         self, query_id: int, api_key: str, limit: int = 1000
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Fetch data for a specific Dune query.
 
         Args:

intentkit/skills/elfa/base.py

@@ -1,5 +1,3 @@
-from typing import Type
-
 from langchain_core.tools.base import ToolException
 from pydantic import BaseModel, Field
 
@@ -14,7 +12,7 @@ class ElfaBaseTool(IntentKitSkill):
 
     name: str = Field(description="The name of the tool")
     description: str = Field(description="A description of what the tool does")
-    args_schema: Type[BaseModel]
+    args_schema: type[BaseModel]
 
     def get_api_key(self) -> str:
         context = self.get_context()