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

intentkit/skills/dexscreener/utils.py

@@ -0,0 +1,420 @@
+"""
+Utility functions and constants for DexScreener skills.
+"""
+
+import json
+import logging
+from collections.abc import Callable
+from enum import Enum
+from typing import Any
+
+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: str | None = None,
+    additional_data: dict[str, Any] | None = 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: dict[str, Any] | None = 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: int | None = 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/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"

intentkit/skills/dune_analytics/fetch_kol_buys.py

@@ -3,13 +3,12 @@
 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
 from tenacity import retry, stop_after_attempt, wait_exponential
 
-from intentkit.abstracts.skill import SkillStoreABC
 from intentkit.skills.dune_analytics.base import DuneBaseTool
 
 BASE_URL = "https://api.dune.com/api/v1/query"
@@ -29,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")
 
 
@@ -48,15 +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
-    skill_store: SkillStoreABC = Field(description="Skill store for data persistence")
+    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:
@@ -70,7 +68,7 @@ class FetchKOLBuys(DuneBaseTool):
         Raises:
             ToolException: If the API request fails.
         """
-        from langchain.tools.base import ToolException
+        from langchain_core.tools.base import ToolException
 
         url = f"{BASE_URL}/{query_id}/results?limit={limit}"
         headers = {"X-Dune-API-Key": api_key}

intentkit/skills/dune_analytics/fetch_nation_metrics.py

@@ -5,13 +5,12 @@ 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
 from tenacity import retry, stop_after_attempt, wait_exponential
 
-from intentkit.abstracts.skill import SkillStoreABC
 from intentkit.skills.dune_analytics.base import DuneBaseTool
 
 SUPPORTED_QUERIES = {
@@ -63,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")
@@ -85,8 +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
-    skill_store: SkillStoreABC = Field(description="Skill store for data persistence")
+    args_schema: type[BaseModel] = NationMetricsInput
 
     def normalize_metric(self, metric: str) -> str:
         """Normalize a metric string for matching.
@@ -124,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:
@@ -138,7 +136,7 @@ class FetchNationMetrics(DuneBaseTool):
         Raises:
             ToolException: If the API request fails.
         """
-        from langchain.tools.base import ToolException
+        from langchain_core.tools.base import ToolException
 
         url = f"{BASE_URL}/{query_id}/results?limit={limit}"
         headers = {"X-Dune-API-Key": api_key}