intentkit 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

intentkit/skills/defillama/base.py

@@ -0,0 +1,135 @@
+"""Base class for all DeFi Llama tools."""
+
+from datetime import datetime, timedelta, timezone
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import IntentKitSkill, SkillContext
+from intentkit.skills.defillama.config.chains import (
+    get_chain_from_alias,
+)
+
+DEFILLAMA_BASE_URL = "https://api.llama.fi"
+
+
+class DefiLlamaBaseTool(IntentKitSkill):
+    """Base class for DeFi Llama tools.
+
+    This class provides common functionality for all DeFi Llama API tools:
+    - Rate limiting
+    - State management
+    - Chain validation
+    - Error handling
+    """
+
+    name: str = Field(description="The name of the tool")
+    description: str = Field(description="A description of what the tool does")
+    args_schema: Type[BaseModel]
+    skill_store: SkillStoreABC = Field(
+        description="The skill store for persisting data"
+    )
+    base_url: str = Field(
+        default=DEFILLAMA_BASE_URL, description="Base URL for DeFi Llama API"
+    )
+
+    @property
+    def category(self) -> str:
+        return "defillama"
+
+    async def check_rate_limit(
+        self, context: SkillContext, max_requests: int = 30, interval: int = 5
+    ) -> tuple[bool, str | None]:
+        """Check if the rate limit has been exceeded.
+
+        Args:
+            context: Skill context
+            max_requests: Maximum requests allowed in the interval (default: 30)
+            interval: Time interval in minutes (default: 5)
+
+        Returns:
+            Rate limit status and error message if limited
+        """
+        rate_limit = await self.skill_store.get_agent_skill_data(
+            context.agent.id, self.name, "rate_limit"
+        )
+        current_time = datetime.now(tz=timezone.utc)
+
+        if (
+            rate_limit
+            and rate_limit.get("reset_time")
+            and rate_limit.get("count") is not None
+            and datetime.fromisoformat(rate_limit["reset_time"]) > current_time
+        ):
+            if rate_limit["count"] >= max_requests:
+                return True, "Rate limit exceeded"
+
+            rate_limit["count"] += 1
+            await self.skill_store.save_agent_skill_data(
+                context.agent.id, self.name, "rate_limit", rate_limit
+            )
+            return False, None
+
+        new_rate_limit = {
+            "count": 1,
+            "reset_time": (current_time + timedelta(minutes=interval)).isoformat(),
+        }
+        await self.skill_store.save_agent_skill_data(
+            context.agent.id, self.name, "rate_limit", new_rate_limit
+        )
+        return False, None
+
+    async def validate_chain(self, chain: str | None) -> tuple[bool, str | None]:
+        """Validate and normalize chain parameter.
+
+        Args:
+            chain: Chain name to validate
+
+        Returns:
+            Tuple of (is_valid, normalized_chain_name)
+        """
+        if chain is None:
+            return True, None
+
+        normalized_chain = get_chain_from_alias(chain)
+        if normalized_chain is None:
+            return False, None
+
+        return True, normalized_chain
+
+    def get_endpoint_url(self, endpoint: str) -> str:
+        """Construct full endpoint URL.
+
+        Args:
+            endpoint: API endpoint path
+
+        Returns:
+            Complete URL for the endpoint
+        """
+        return f"{self.base_url}/{endpoint.lstrip('/')}"
+
+    def format_error_response(self, status_code: int, message: str) -> dict:
+        """Format error responses consistently.
+
+        Args:
+            status_code: HTTP status code
+            message: Error message
+
+        Returns:
+            Formatted error response dictionary
+        """
+        return {
+            "error": True,
+            "status_code": status_code,
+            "message": message,
+            "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+        }
+
+    def get_current_timestamp(self) -> int:
+        """Get current timestamp in UTC.
+
+        Returns:
+            Current Unix timestamp
+        """
+        return int(datetime.now(tz=timezone.utc).timestamp())

intentkit/skills/defillama/coins/fetch_batch_historical_prices.py

@@ -0,0 +1,116 @@
+"""Tool for fetching batch historical token prices via DeFi Llama API."""
+
+from typing import Dict, List, Optional, Type
+
+from langchain.schema.runnable import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.defillama.api import fetch_batch_historical_prices
+from intentkit.skills.defillama.base import DefiLlamaBaseTool
+
+FETCH_BATCH_HISTORICAL_PRICES_PROMPT = """
+This tool fetches historical token prices from DeFi Llama for multiple tokens at multiple timestamps.
+Provide a dictionary mapping token identifiers to lists of timestamps in the format:
+- Ethereum tokens: {"ethereum:0x...": [timestamp1, timestamp2]}
+- Other chains: {"chainname:0x...": [timestamp1, timestamp2]}
+- CoinGecko IDs: {"coingecko:bitcoin": [timestamp1, timestamp2]}
+Returns historical price data including:
+- Prices in USD at each timestamp
+- Token symbols
+- Confidence scores for price data
+Uses a 4-hour search window around each specified timestamp.
+"""
+
+
+class HistoricalPricePoint(BaseModel):
+    """Model representing a single historical price point."""
+
+    timestamp: int = Field(..., description="Unix timestamp of the price data")
+    price: float = Field(..., description="Token price in USD at the timestamp")
+    confidence: float = Field(..., description="Confidence score for the price data")
+
+
+class TokenPriceHistory(BaseModel):
+    """Model representing historical price data for a single token."""
+
+    symbol: str = Field(..., description="Token symbol")
+    prices: List[HistoricalPricePoint] = Field(
+        ..., description="List of historical price points"
+    )
+
+
+class FetchBatchHistoricalPricesInput(BaseModel):
+    """Input schema for fetching batch historical token prices."""
+
+    coins_timestamps: Dict[str, List[int]] = Field(
+        ..., description="Dictionary mapping token identifiers to lists of timestamps"
+    )
+
+
+class FetchBatchHistoricalPricesResponse(BaseModel):
+    """Response schema for batch historical token prices."""
+
+    coins: Dict[str, TokenPriceHistory] = Field(
+        default_factory=dict,
+        description="Historical token prices keyed by token identifier",
+    )
+    error: Optional[str] = Field(None, description="Error message if any")
+
+
+class DefiLlamaFetchBatchHistoricalPrices(DefiLlamaBaseTool):
+    """Tool for fetching batch historical token prices from DeFi Llama.
+
+    This tool retrieves historical prices for multiple tokens at multiple
+    timestamps, using a 4-hour search window around each requested time.
+
+    Example:
+        prices_tool = DefiLlamaFetchBatchHistoricalPrices(
+            skill_store=store,
+            agent_id="agent_123",
+            agent_store=agent_store
+        )
+        result = await prices_tool._arun(
+            coins_timestamps={
+                "ethereum:0x...": [1640995200, 1641081600],  # Jan 1-2, 2022
+                "coingecko:bitcoin": [1640995200, 1641081600]
+            }
+        )
+    """
+
+    name: str = "defillama_fetch_batch_historical_prices"
+    description: str = FETCH_BATCH_HISTORICAL_PRICES_PROMPT
+    args_schema: Type[BaseModel] = FetchBatchHistoricalPricesInput
+
+    async def _arun(
+        self, config: RunnableConfig, coins_timestamps: Dict[str, List[int]]
+    ) -> FetchBatchHistoricalPricesResponse:
+        """Fetch historical prices for the given tokens at specified timestamps.
+
+        Args:
+            config: Runnable configuration
+            coins_timestamps: Dictionary mapping token identifiers to lists of timestamps
+
+        Returns:
+            FetchBatchHistoricalPricesResponse containing historical token prices or error
+        """
+        try:
+            # Check rate limiting
+            context = self.context_from_config(config)
+            is_rate_limited, error_msg = await self.check_rate_limit(context)
+            if is_rate_limited:
+                return FetchBatchHistoricalPricesResponse(error=error_msg)
+
+            # Fetch batch historical prices from API
+            result = await fetch_batch_historical_prices(
+                coins_timestamps=coins_timestamps
+            )
+
+            # Check for API errors
+            if isinstance(result, dict) and "error" in result:
+                return FetchBatchHistoricalPricesResponse(error=result["error"])
+
+            # Return the response matching the API structure
+            return FetchBatchHistoricalPricesResponse(coins=result["coins"])
+
+        except Exception as e:
+            return FetchBatchHistoricalPricesResponse(error=str(e))

intentkit/skills/defillama/coins/fetch_block.py

@@ -0,0 +1,98 @@
+"""Tool for fetching current block data via DeFi Llama API."""
+
+from typing import Optional, Type
+
+from langchain.schema.runnable import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.defillama.api import fetch_block
+from intentkit.skills.defillama.base import DefiLlamaBaseTool
+
+FETCH_BLOCK_PROMPT = """
+This tool fetches current block data from DeFi Llama for a specific chain.
+Provide:
+- Chain name (e.g. "ethereum", "bsc", "solana")
+Returns:
+- Block height
+- Block timestamp
+"""
+
+
+class BlockData(BaseModel):
+    """Model representing block data."""
+
+    height: int = Field(..., description="Block height number")
+    timestamp: int = Field(..., description="Unix timestamp of the block")
+
+
+class FetchBlockInput(BaseModel):
+    """Input schema for fetching block data."""
+
+    chain: str = Field(..., description="Chain name to fetch block data for")
+
+
+class FetchBlockResponse(BaseModel):
+    """Response schema for block data."""
+
+    chain: str = Field(..., description="Normalized chain name")
+    height: Optional[int] = Field(None, description="Block height number")
+    timestamp: Optional[int] = Field(None, description="Unix timestamp of the block")
+    error: Optional[str] = Field(None, description="Error message if any")
+
+
+class DefiLlamaFetchBlock(DefiLlamaBaseTool):
+    """Tool for fetching current block data from DeFi Llama.
+
+    This tool retrieves current block data for a specific chain.
+
+    Example:
+        block_tool = DefiLlamaFetchBlock(
+            skill_store=store,
+            agent_id="agent_123",
+            agent_store=agent_store
+        )
+        result = await block_tool._arun(chain="ethereum")
+    """
+
+    name: str = "defillama_fetch_block"
+    description: str = FETCH_BLOCK_PROMPT
+    args_schema: Type[BaseModel] = FetchBlockInput
+
+    async def _arun(self, config: RunnableConfig, chain: str) -> FetchBlockResponse:
+        """Fetch current block data for the given chain.
+
+        Args:
+            config: Runnable configuration
+            chain: Chain name to fetch block data for
+
+        Returns:
+            FetchBlockResponse containing block data or error
+        """
+        try:
+            # Validate chain parameter
+            is_valid, normalized_chain = await self.validate_chain(chain)
+            if not is_valid or normalized_chain is None:
+                return FetchBlockResponse(chain=chain, error=f"Invalid chain: {chain}")
+
+            # Check rate limiting
+            context = self.context_from_config(config)
+            is_rate_limited, error_msg = await self.check_rate_limit(context)
+            if is_rate_limited:
+                return FetchBlockResponse(chain=normalized_chain, error=error_msg)
+
+            # Fetch block data from API
+            result = await fetch_block(chain=normalized_chain)
+
+            # Check for API errors
+            if isinstance(result, dict) and "error" in result:
+                return FetchBlockResponse(chain=normalized_chain, error=result["error"])
+
+            # Return the response matching the API structure
+            return FetchBlockResponse(
+                chain=normalized_chain,
+                height=result["height"],
+                timestamp=result["timestamp"],
+            )
+
+        except Exception as e:
+            return FetchBlockResponse(chain=chain, error=str(e))

intentkit/skills/defillama/coins/fetch_current_prices.py

@@ -0,0 +1,105 @@
+"""Tool for fetching token prices via DeFi Llama API."""
+
+from typing import Dict, List, Optional, Type
+
+from langchain.schema.runnable import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.defillama.api import fetch_current_prices
+from intentkit.skills.defillama.base import DefiLlamaBaseTool
+
+FETCH_PRICES_PROMPT = """
+This tool fetches current token prices from DeFi Llama with a 4-hour search window.
+Provide a list of token identifiers in the format:
+- Ethereum tokens: 'ethereum:0x...'
+- Other chains: 'chainname:0x...'
+- CoinGecko IDs: 'coingecko:bitcoin'
+Returns price data including:
+- Current price in USD
+- Token symbol
+- Price confidence score
+- Token decimals (if available)
+- Last update timestamp
+"""
+
+
+class TokenPrice(BaseModel):
+    """Model representing token price data."""
+
+    price: float = Field(..., description="Current token price in USD")
+    symbol: str = Field(..., description="Token symbol")
+    timestamp: int = Field(..., description="Unix timestamp of last price update")
+    confidence: float = Field(..., description="Confidence score for the price data")
+    decimals: Optional[int] = Field(None, description="Token decimals, if available")
+
+
+class FetchCurrentPricesInput(BaseModel):
+    """Input schema for fetching current token prices with a 4-hour search window."""
+
+    coins: List[str] = Field(
+        ...,
+        description="List of token identifiers (e.g. 'ethereum:0x...', 'coingecko:ethereum')",
+    )
+
+
+class FetchCurrentPricesResponse(BaseModel):
+    """Response schema for current token prices."""
+
+    coins: Dict[str, TokenPrice] = Field(
+        default_factory=dict, description="Token prices keyed by token identifier"
+    )
+    error: Optional[str] = Field(None, description="Error message if any")
+
+
+class DefiLlamaFetchCurrentPrices(DefiLlamaBaseTool):
+    """Tool for fetching current token prices from DeFi Llama.
+
+    This tool retrieves current prices for multiple tokens in a single request,
+    using a 4-hour search window to ensure fresh data.
+
+    Example:
+        prices_tool = DefiLlamaFetchCurrentPrices(
+            skill_store=store,
+            agent_id="agent_123",
+            agent_store=agent_store
+        )
+        result = await prices_tool._arun(
+            coins=["ethereum:0x...", "coingecko:bitcoin"]
+        )
+    """
+
+    name: str = "defillama_fetch_current_prices"
+    description: str = FETCH_PRICES_PROMPT
+    args_schema: Type[BaseModel] = FetchCurrentPricesInput
+
+    async def _arun(
+        self, config: RunnableConfig, coins: List[str]
+    ) -> FetchCurrentPricesResponse:
+        """Fetch current prices for the given tokens.
+
+        Args:
+            config: Runnable configuration
+            coins: List of token identifiers to fetch prices for
+
+        Returns:
+            FetchCurrentPricesResponse containing token prices or error
+        """
+        try:
+            # Check rate limiting
+            context = self.context_from_config(config)
+            is_rate_limited, error_msg = await self.check_rate_limit(context)
+            if is_rate_limited:
+                return FetchCurrentPricesResponse(error=error_msg)
+
+            # Fetch prices from API
+            result = await fetch_current_prices(coins=coins)
+
+            # Check for API errors
+            if isinstance(result, dict) and "error" in result:
+                return FetchCurrentPricesResponse(error=result["error"])
+
+            # Return the response matching the API structure
+            return FetchCurrentPricesResponse(coins=result["coins"])
+
+        except Exception as e:
+            return FetchCurrentPricesResponse(error=str(e))

intentkit/skills/defillama/coins/fetch_first_price.py

@@ -0,0 +1,100 @@
+"""Tool for fetching first recorded token prices via DeFi Llama API."""
+
+from typing import Dict, List, Optional, Type
+
+from langchain.schema.runnable import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.defillama.api import fetch_first_price
+from intentkit.skills.defillama.base import DefiLlamaBaseTool
+
+FETCH_FIRST_PRICE_PROMPT = """
+This tool fetches the first recorded price data from DeFi Llama for multiple tokens.
+Provide a list of token identifiers in the format:
+- Ethereum tokens: 'ethereum:0x...'
+- Other chains: 'chainname:0x...'
+- CoinGecko IDs: 'coingecko:bitcoin'
+Returns first price data including:
+- Initial price in USD
+- Token symbol
+- Timestamp of first recorded price
+"""
+
+
+class FirstPriceData(BaseModel):
+    """Model representing first price data for a single token."""
+
+    symbol: str = Field(..., description="Token symbol")
+    price: float = Field(..., description="First recorded price in USD")
+    timestamp: int = Field(..., description="Unix timestamp of first recorded price")
+
+
+class FetchFirstPriceInput(BaseModel):
+    """Input schema for fetching first token prices."""
+
+    coins: List[str] = Field(
+        ..., description="List of token identifiers to fetch first prices for"
+    )
+
+
+class FetchFirstPriceResponse(BaseModel):
+    """Response schema for first token prices."""
+
+    coins: Dict[str, FirstPriceData] = Field(
+        default_factory=dict, description="First price data keyed by token identifier"
+    )
+    error: Optional[str] = Field(None, description="Error message if any")
+
+
+class DefiLlamaFetchFirstPrice(DefiLlamaBaseTool):
+    """Tool for fetching first recorded token prices from DeFi Llama.
+
+    This tool retrieves the first price data recorded for multiple tokens,
+    including the initial price, symbol, and timestamp.
+
+    Example:
+        first_price_tool = DefiLlamaFetchFirstPrice(
+            skill_store=store,
+            agent_id="agent_123",
+            agent_store=agent_store
+        )
+        result = await first_price_tool._arun(
+            coins=["ethereum:0x...", "coingecko:ethereum"]
+        )
+    """
+
+    name: str = "defillama_fetch_first_price"
+    description: str = FETCH_FIRST_PRICE_PROMPT
+    args_schema: Type[BaseModel] = FetchFirstPriceInput
+
+    async def _arun(
+        self, config: RunnableConfig, coins: List[str]
+    ) -> FetchFirstPriceResponse:
+        """Fetch first recorded prices for the given tokens.
+
+        Args:
+            config: Runnable configuration
+            coins: List of token identifiers to fetch first prices for
+
+        Returns:
+            FetchFirstPriceResponse containing first price data or error
+        """
+        try:
+            # Check rate limiting
+            context = self.context_from_config(config)
+            is_rate_limited, error_msg = await self.check_rate_limit(context)
+            if is_rate_limited:
+                return FetchFirstPriceResponse(error=error_msg)
+
+            # Fetch first price data from API
+            result = await fetch_first_price(coins=coins)
+
+            # Check for API errors
+            if isinstance(result, dict) and "error" in result:
+                return FetchFirstPriceResponse(error=result["error"])
+
+            # Return the response matching the API structure
+            return FetchFirstPriceResponse(coins=result["coins"])
+
+        except Exception as e:
+            return FetchFirstPriceResponse(error=str(e))

intentkit/skills/defillama/coins/fetch_historical_prices.py

@@ -0,0 +1,110 @@
+"""Tool for fetching historical token prices via DeFi Llama API."""
+
+from typing import Dict, List, Optional, Type
+
+from langchain.schema.runnable import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.defillama.api import fetch_historical_prices
+from intentkit.skills.defillama.base import DefiLlamaBaseTool
+
+FETCH_HISTORICAL_PRICES_PROMPT = """
+This tool fetches historical token prices from DeFi Llama for a specific timestamp.
+Provide a timestamp and list of token identifiers in the format:
+- Ethereum tokens: 'ethereum:0x...'
+- Other chains: 'chainname:0x...'
+- CoinGecko IDs: 'coingecko:bitcoin'
+Returns historical price data including:
+- Price in USD at the specified time
+- Token symbol
+- Token decimals (if available)
+- Actual timestamp of the price data
+Uses a 4-hour search window around the specified timestamp.
+"""
+
+
+class HistoricalTokenPrice(BaseModel):
+    """Model representing historical token price data."""
+
+    price: float = Field(..., description="Token price in USD at the specified time")
+    symbol: Optional[str] = Field(None, description="Token symbol")
+    timestamp: int = Field(..., description="Unix timestamp of the price data")
+    decimals: Optional[int] = Field(None, description="Token decimals, if available")
+
+
+class FetchHistoricalPricesInput(BaseModel):
+    """Input schema for fetching historical token prices."""
+
+    timestamp: int = Field(
+        ..., description="Unix timestamp for historical price lookup"
+    )
+    coins: List[str] = Field(
+        ...,
+        description="List of token identifiers (e.g. 'ethereum:0x...', 'coingecko:ethereum')",
+    )
+
+
+class FetchHistoricalPricesResponse(BaseModel):
+    """Response schema for historical token prices."""
+
+    coins: Dict[str, HistoricalTokenPrice] = Field(
+        default_factory=dict,
+        description="Historical token prices keyed by token identifier",
+    )
+    error: Optional[str] = Field(None, description="Error message if any")
+
+
+class DefiLlamaFetchHistoricalPrices(DefiLlamaBaseTool):
+    """Tool for fetching historical token prices from DeFi Llama.
+
+    This tool retrieves historical prices for multiple tokens at a specific
+    timestamp, using a 4-hour search window around the requested time.
+
+    Example:
+        prices_tool = DefiLlamaFetchHistoricalPrices(
+            skill_store=store,
+            agent_id="agent_123",
+            agent_store=agent_store
+        )
+        result = await prices_tool._arun(
+            timestamp=1640995200,  # Jan 1, 2022
+            coins=["ethereum:0x...", "coingecko:bitcoin"]
+        )
+    """
+
+    name: str = "defillama_fetch_historical_prices"
+    description: str = FETCH_HISTORICAL_PRICES_PROMPT
+    args_schema: Type[BaseModel] = FetchHistoricalPricesInput
+
+    async def _arun(
+        self, config: RunnableConfig, timestamp: int, coins: List[str]
+    ) -> FetchHistoricalPricesResponse:
+        """Fetch historical prices for the given tokens at the specified time.
+
+        Args:
+            config: Runnable configuration
+            timestamp: Unix timestamp for historical price lookup
+            coins: List of token identifiers to fetch prices for
+
+        Returns:
+            FetchHistoricalPricesResponse containing historical token prices or error
+        """
+        try:
+            # Check rate limiting
+            context = self.context_from_config(config)
+            is_rate_limited, error_msg = await self.check_rate_limit(context)
+            if is_rate_limited:
+                return FetchHistoricalPricesResponse(error=error_msg)
+
+            # Fetch historical prices from API
+            result = await fetch_historical_prices(timestamp=timestamp, coins=coins)
+
+            # Check for API errors
+            if isinstance(result, dict) and "error" in result:
+                return FetchHistoricalPricesResponse(error=result["error"])
+
+            # Return the response matching the API structure
+            return FetchHistoricalPricesResponse(coins=result["coins"])
+
+        except Exception as e:
+            return FetchHistoricalPricesResponse(error=str(e))