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

intentkit/skills/carv/onchain_query.py

@@ -0,0 +1,164 @@
+import logging
+from decimal import Decimal, InvalidOperation
+from typing import Any, Dict, Literal, Type
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.carv.base import CarvBaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class CarvInput(BaseModel):
+    """
+    Input schema for CARV SQL Query API.
+    Defines parameters controllable by the user when invoking the tool.
+    """
+
+    question: str = Field(
+        ...,
+        description="The question to query on-chain data.",
+    )
+    chain: Literal["ethereum", "base", "bitcoin", "solana"] = Field(
+        ...,
+        description="supported chain is ethereum, base, bitcoin, solana",
+    )
+
+
+class OnchainQueryTool(CarvBaseTool):
+    """
+    Tool for querying on-chain data using natural language via the CARV SQL Query API.
+
+    This tool allows you to ask questions about blockchain data in plain English, and it will return
+    the relevant information. Behind the scenes, it uses the CARV API to convert your question into a SQL query
+    and retrieve the results.
+
+    Supported Blockchains: Ethereum, Base, Bitcoin, and Solana.
+
+    If the question is about a blockchain other than the ones listed above, or is not a clear question, the
+    tool will return an error.
+    """
+
+    name: str = "carv_onchain_query"
+    description: str = (
+        "Query blockchain data from Ethereum, Base, Bitcoin, or Solana using natural language. "
+        "This tool provides access to detailed metrics including block information (timestamps, hashes, miners, gas used/limits), "
+        "transaction details (hashes, sender/receiver addresses, amounts, gas prices), and overall network utilization. "
+        "It supports aggregate analytics such as daily transaction counts, average gas prices, top wallet activity, and blockchain growth trends. "
+        "You can filter results by time range, address type, transaction value, and other parameters.\n\n"
+        "IMPORTANT Rules:\n"
+        "- Only Ethereum, Base, Bitcoin, and Solana are supported.\n"
+        "- Always infer the target blockchain from the user's query.\n"
+        "- If an unsupported blockchain is requested, clearly explain the limitation.\n"
+        "- Convert user input into a specific and actionable natural language query (e.g., "
+        '"What\'s the most active address on Ethereum over the past 24 hours?" or '
+        '"Show the largest ETH transaction in the last 30 days").\n'
+        "- Respond in clear, concise natural language using only the data returned by the tool.\n"
+        "- Avoid markdown or bullet points unless explicitly requested.\n"
+        "- ETH values are denominated in 18 decimals—consider 10^18 when interpreting amounts.\n"
+        "- Never fabricate or infer data beyond what the tool provides."
+    )
+    args_schema: Type[BaseModel] = CarvInput
+
+    async def _arun(
+        self,
+        question: str,
+        chain: str,
+        config: RunnableConfig = None,  # type: ignore
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """
+        Queries the CARV SQL Query API and returns the response.
+        """
+        context = self.context_from_config(config)
+        try:
+            await self.apply_rate_limit(context)
+
+            payload = {"question": question}
+
+            result, error = await self._call_carv_api(
+                context=context,
+                endpoint="/ai-agent-backend/sql_query_by_llm",
+                method="POST",
+                payload=payload,
+            )
+
+            if error is not None or result is None:
+                logger.error(f"Error returned from CARV API: {error}")
+                return {
+                    "error": True,
+                    "error_type": "APIError",
+                    "message": "Failed to fetch data from CARV API.",
+                    "details": error,
+                }
+
+            _normalize_unit(result, chain)
+            return {"success": True, **result}
+
+        except Exception as e:
+            logger.error(f"An unexpected error occurred: {e}", exc_info=True)
+            return {
+                "error": True,
+                "error_type": type(e).__name__,
+                "message": "An unexpected error occurred.",
+                "details": str(e),
+            }
+
+
+def _normalize_unit(response_data: Dict[str, Any], chain: str) -> None:
+    """
+    Normalizes the 'value' field in on-chain response data to a human-readable format.
+    Adds the corresponding token ticker after the value.
+
+    Supported chains:
+    - Ethereum: 10^18 -> ETH
+    - Base: 10^18 -> ETH
+    - Solana: 10^9 -> SOL
+    - Bitcoin: 10^8 -> BTC
+    """
+    column_infos = response_data.get("column_infos", [])
+    rows = response_data.get("rows", [])
+
+    if "value" not in column_infos:
+        return
+
+    value_index = column_infos.index("value")
+
+    chain = chain.lower()
+    if chain == "ethereum":
+        divisor = Decimal("1e18")
+        ticker = "ETH"
+    elif chain == "base":
+        divisor = Decimal("1e18")
+        ticker = "ETH"
+    elif chain == "solana":
+        divisor = Decimal("1e9")
+        ticker = "SOL"
+    elif chain == "bitcoin":
+        divisor = Decimal("1e8")
+        ticker = "BTC"
+    else:
+        logger.warning(f"Unsupported chain '{chain}' for unit normalization.")
+        return
+
+    for row in rows:
+        items = row.get("items", [])
+        if len(items) > value_index:
+            original_value = items[value_index]
+            try:
+                normalized = str(original_value).strip()
+                try:
+                    value_decimal = Decimal(normalized)
+                except InvalidOperation:
+                    value_decimal = Decimal.from_float(float(normalized))
+
+                converted = value_decimal / divisor
+                formatted_value = (
+                    format(converted, "f").rstrip("0").rstrip(".")
+                    if "." in format(converted, "f")
+                    else format(converted, "f")
+                )
+                items[value_index] = f"{formatted_value} {ticker}"
+            except Exception as e:
+                logger.warning(f"Unable to normalize value '{original_value}': {e}")

intentkit/skills/carv/schema.json

@@ -0,0 +1,137 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "CARV",
+    "description": "Configuration for the CARV skill.",
+    "type": "object",
+    "x-icon": "https://ai.service.crestal.dev/skills/carv/carv.webp",
+    "x-tags": [
+        "AI",
+        "Data",
+        "Information",
+        "Analytics",
+        "Market Data"
+    ],
+    "properties": {
+        "enabled": {
+            "type": "boolean",
+            "description": "Enable or disable the CARV skill.",
+            "default": false
+        },
+        "states": {
+            "type": "object",
+            "title": "Skill States",
+            "description": "Enable/disable specific tools for CARV",
+            "properties": {
+                "onchain_query": {
+                    "type": "string",
+                    "title": "On-Chain Query",
+                    "enum": [
+                        "disabled",
+                        "public",
+                        "private"
+                    ],
+                    "x-enum-title": [
+                        "Disabled",
+                        "Agent Owner + All Users",
+                        "Agent Owner Only"
+                    ],
+                    "description": "allows you to use the nature language to query the on-chain data. Behind the scean, CARV will use LLM model to interpreate the nature language input and convert into the sql query based on the above schemas",
+                    "default": "public"
+                },
+                "token_info_and_price": {
+                    "type": "string",
+                    "title": "Token Information and Price",
+                    "enum": [
+                        "disabled",
+                        "public",
+                        "private"
+                    ],
+                    "x-enum-title": [
+                        "Disabled",
+                        "Agent Owner + All Users",
+                        "Agent Owner Only"
+                    ],
+                    "description": "Fetches detailed information and current USD price of a cryptocurrency token from CARV API using its ticker symbol (e.g., 'eth', 'btc'), returning metadata like name, symbol, platform, categories, and contract addresses, useful for understanding its identity, ecosystem, market value, and for obtaining comprehensive token data with live pricing.",
+                    "default": "public"
+                },
+                "fetch_news": {
+                    "type": "string",
+                    "title": "Fetch News",
+                    "enum": [
+                        "disabled",
+                        "public",
+                        "private"
+                    ],
+                    "x-enum-title": [
+                        "Disabled",
+                        "Agent Owner + All Users",
+                        "Agent Owner Only"
+                    ],
+                    "description": "retrieves a list of recent news items, each including a title, URL, and a short description",
+                    "default": "disabled"
+                }
+            }
+        },
+        "api_key_provider": {
+            "type": "string",
+            "title": "API Key Provider",
+            "description": "Provider of the API key",
+            "enum": [
+                "agent_owner",
+                "platform"
+            ],
+            "x-enum-title": [
+                "Owner Provided",
+                "Nation Hosted"
+            ],
+            "default": "platform"
+        }
+    },
+    "required": [
+        "enabled",
+        "states"
+    ],
+    "if": {
+        "allOf": [
+            {
+                "properties": {
+                    "enabled": {
+                        "const": true
+                    }
+                }
+            },
+            {
+                "properties": {
+                    "api_key_provider": {
+                        "const": "agent_owner"
+                    }
+                }
+            }
+        ]
+    },
+    "then": {
+        "properties": {
+            "api_key": {
+                "type": "string",
+                "title": "CARV API Key",
+                "x-link": "[Get your API key](https://docs.carv.io/d.a.t.a.-ai-framework/api-documentation#authentication)",
+                "x-sensitive": true,
+                "description": "API Key for authenticating with the CARV API."
+            },
+            "rate_limit_number": {
+                "type": "integer",
+                "title": "Rate Limit Number",
+                "description": "Number of requests allowed per time window."
+            },
+            "rate_limit_minutes": {
+                "type": "integer",
+                "title": "Rate Limit Minutes",
+                "description": "Time window in minutes for rate limiting."
+            }
+        },
+        "required": [
+            "api_key"
+        ]
+    },
+    "additionalProperties": true
+}

intentkit/skills/carv/token_info_and_price.py

@@ -0,0 +1,110 @@
+import logging
+import re
+from typing import Any, Dict, Optional, Type
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.carv.base import CarvBaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class TokenInfoAndPriceInput(BaseModel):
+    ticker: str = Field(
+        description="The token's ticker symbol (e.g., 'eth', 'btc', 'sol', 'xrp')."
+    )
+    token_name: str = Field(
+        description="The token name (e.g ethereum, bitcoin, solana, ripple)"
+    )
+    amount: Optional[float] = Field(
+        description="(optional) amount of token, fill this if user asking for how much x amount of specific token worth"
+    )
+
+
+class TokenInfoAndPriceTool(CarvBaseTool):
+    """
+    Fetches detailed information and the current USD price of a cryptocurrency token from the CARV API,
+    given its ticker symbol (e.g., 'eth', 'btc', 'aave').
+    Returns metadata including the token's name, symbol, platform, category tags, and contract addresses
+    Useful for understanding a token's identity, ecosystem, and market valu
+    Use this tool when you need comprehensive token data and live pricing from CARV
+    """
+
+    name: str = "carv_token_info_and_price"
+    description: str = (
+        "Fetches detailed information and the current USD price of a cryptocurrency token from the CARV API, "
+        "given its ticker symbol (e.g., 'eth', 'btc', 'aave'). or token name"
+        "Returns metadata including the token's name, symbol, platform, category tags, and contract addresses "
+        "Useful for understanding a token's identity, ecosystem, and market value"
+        "Use this tool when you need comprehensive token data and live pricing from CARV."
+    )
+    args_schema: Type[BaseModel] = TokenInfoAndPriceInput
+
+    async def _arun(
+        self,
+        ticker: str,
+        token_name: str,
+        amount: Optional[float] = 1,
+        config: RunnableConfig = None,  # type: ignore
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        if not ticker:
+            return {
+                "error": True,
+                "message": "ticker is null",
+                "suggestion": "ask the user for the specific ticker, and fill the `ticker` field when calling this tool",
+            }
+
+        context = self.context_from_config(config)
+        params = {"ticker": ticker}
+        path = "/ai-agent-backend/token_info"
+        method = "GET"
+
+        result, error = await self._call_carv_api(
+            context=context,
+            endpoint=path,
+            params=params,
+            method=method,
+        )
+
+        if error is not None or result is None:
+            logger.error(f"Error returned from CARV API: {error}")
+            return {
+                "error": True,
+                "error_type": "APIError",
+                "message": "Failed to fetch token info from CARV API.",
+                "details": error,
+            }
+
+        # retry with token_name if price is 0 or missing
+        if "price" not in result or result["price"] == 0:
+            fallback_ticker = re.sub(r"\s+", "-", token_name.strip().lower())
+            logger.info(
+                f"Fallback triggered. Trying with fallback ticker: {fallback_ticker}"
+            )
+
+            fallback_params = {"ticker": fallback_ticker}
+            result, error = await self._call_carv_api(
+                context=context,
+                endpoint=path,
+                params=fallback_params,
+                method=method,
+            )
+
+            if error is not None or result is None or result.get("price") == 0:
+                logger.error(f"Fallback error returned from CARV API: {error}")
+                return {
+                    "error": True,
+                    "error_type": "APIError",
+                    "message": "Failed to fetch token info from CARV API with fallback.",
+                    "details": error,
+                }
+
+        if "price" in result and amount is not None:
+            return {
+                "additional_info": f"{amount} {ticker.upper()} is worth ${round(amount * result['price'], 2)}",
+                **result,
+            }
+
+        return result

intentkit/skills/cdp/__init__.py

@@ -0,0 +1,137 @@
+"""CDP wallet interaction skills."""
+
+from typing import TypedDict
+
+from coinbase_agentkit import (
+    AgentKit,
+    AgentKitConfig,
+    CdpWalletProvider,
+    basename_action_provider,
+    cdp_api_action_provider,
+    cdp_wallet_action_provider,
+    erc20_action_provider,
+    morpho_action_provider,
+    pyth_action_provider,
+    superfluid_action_provider,
+    wallet_action_provider,
+    weth_action_provider,
+    wow_action_provider,
+)
+from coinbase_agentkit.action_providers.erc721 import erc721_action_provider
+from coinbase_agentkit_langchain import get_langchain_tools
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.clients import CdpClient, get_cdp_client
+from intentkit.skills.base import SkillConfig, SkillState
+from intentkit.skills.cdp.base import CDPBaseTool
+from intentkit.skills.cdp.get_balance import GetBalance
+
+# Cache skills at the system level, because they are stateless
+_cache: dict[str, CDPBaseTool] = {}
+
+
+class SkillStates(TypedDict):
+    get_balance: SkillState
+    WalletActionProvider_get_balance: SkillState
+    WalletActionProvider_get_wallet_details: SkillState
+    WalletActionProvider_native_transfer: SkillState
+    CdpApiActionProvider_address_reputation: SkillState
+    CdpApiActionProvider_request_faucet_funds: SkillState
+    CdpWalletActionProvider_deploy_contract: SkillState
+    CdpWalletActionProvider_deploy_nft: SkillState
+    CdpWalletActionProvider_deploy_token: SkillState
+    CdpWalletActionProvider_trade: SkillState
+    PythActionProvider_fetch_price: SkillState
+    PythActionProvider_fetch_price_feed_id: SkillState
+    BasenameActionProvider_register_basename: SkillState
+    ERC20ActionProvider_get_balance: SkillState
+    ERC20ActionProvider_transfer: SkillState
+    Erc721ActionProvider_get_balance: SkillState
+    Erc721ActionProvider_mint: SkillState
+    Erc721ActionProvider_transfer: SkillState
+    WethActionProvider_wrap_eth: SkillState
+    MorphoActionProvider_deposit: SkillState
+    MorphoActionProvider_withdraw: SkillState
+    SuperfluidActionProvider_create_flow: SkillState
+    SuperfluidActionProvider_delete_flow: SkillState
+    SuperfluidActionProvider_update_flow: SkillState
+    WowActionProvider_buy_token: SkillState
+    WowActionProvider_create_token: SkillState
+    WowActionProvider_sell_token: SkillState
+
+
+class Config(SkillConfig):
+    """Configuration for CDP skills."""
+
+    states: SkillStates
+
+
+# CDP skills is not stateless for agents, so we need agent_id here
+# If you are skill contributor, please do not follow this pattern
+async def get_skills(
+    config: "Config",
+    is_private: bool,
+    store: SkillStoreABC,
+    agent_id: str,
+    **_,
+) -> list[CDPBaseTool]:
+    """Get all CDP skills.
+
+    Args:
+        config: The configuration for CDP skills.
+        is_private: Whether to include private skills.
+        store: The skill store for persisting data.
+        agent_id: The ID of the agent using the skills.
+
+    Returns:
+        A list of CDP skills.
+    """
+    available_skills = []
+
+    # Include skills based on their state
+    for skill_name, state in config["states"].items():
+        if state == "disabled":
+            continue
+        elif state == "public" or (state == "private" and is_private):
+            available_skills.append(skill_name)
+
+    # Initialize CDP client
+    cdp_client: CdpClient = await get_cdp_client(agent_id, store)
+    cdp_wallet_provider: CdpWalletProvider = await cdp_client.get_wallet_provider()
+    cdp_provider_config = await cdp_client.get_provider_config()
+    agent_kit = AgentKit(
+        AgentKitConfig(
+            wallet_provider=cdp_wallet_provider,
+            action_providers=[
+                wallet_action_provider(),
+                cdp_api_action_provider(cdp_provider_config),
+                cdp_wallet_action_provider(cdp_provider_config),
+                pyth_action_provider(),
+                basename_action_provider(),
+                erc20_action_provider(),
+                erc721_action_provider(),
+                weth_action_provider(),
+                morpho_action_provider(),
+                superfluid_action_provider(),
+                wow_action_provider(),
+            ],
+        )
+    )
+    cdp_tools = get_langchain_tools(agent_kit)
+    tools = []
+    for skill in available_skills:
+        if skill == "get_balance":
+            tools.append(
+                GetBalance(
+                    wallet=cdp_wallet_provider._wallet,
+                    agent_id=agent_id,
+                    skill_store=store,
+                )
+            )
+            continue
+        for tool in cdp_tools:
+            if tool.name.endswith(skill):
+                tool.handle_tool_error = lambda e: f"tool error: {e}"
+                tool.handle_validation_error = lambda e: f"validation error: {e}"
+                tools.append(tool)
+    return tools

intentkit/skills/cdp/base.py

@@ -0,0 +1,21 @@
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import IntentKitSkill
+
+
+class CDPBaseTool(IntentKitSkill):
+    """Base class for CDP tools."""
+
+    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"
+    )
+
+    @property
+    def category(self) -> str:
+        return "cdp"

intentkit/skills/cdp/get_balance.py

@@ -0,0 +1,81 @@
+from typing import Type
+
+from cdp import Wallet
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.cdp.base import CDPBaseTool
+
+
+class GetBalanceInput(BaseModel):
+    """Input for GetBalance tool."""
+
+    asset_id: str = Field(
+        description="The asset ID to get the balance for (e.g., 'eth', 'usdc', or a valid contract address)"
+    )
+
+
+class GetBalance(CDPBaseTool):
+    """Tool for getting balance from CDP wallet.
+
+    This tool uses the CDP API to get balance for all addresses in a wallet for a given asset.
+
+    Attributes:
+        name: The name of the tool.
+        description: A description of what the tool does.
+        args_schema: The schema for the tool's input arguments.
+    """
+
+    agent_id: str
+    skill_store: SkillStoreABC
+    wallet: Wallet | None = None
+
+    name: str = "cdp_get_balance"
+    description: str = (
+        "This tool will get the balance of all the addresses in the wallet for a given asset. It takes the asset ID as input."
+        "Always use 'eth' for the native asset ETH and 'usdc' for USDC. "
+        "Other valid asset IDs are: weth,dai,reth,brett,w,cbeth,axl,iotx,prime,aero,rsr,mog,tbtc,npc,yfi"
+    )
+    args_schema: Type[BaseModel] = GetBalanceInput
+
+    async def _arun(self, asset_id: str) -> str:
+        """Async implementation of the tool to get balance.
+
+        Args:
+            asset_id (str): The asset ID to get the balance for.
+
+        Returns:
+            str: A message containing the balance information or error message.
+        """
+        try:
+            if not self.wallet:
+                return "Failed to get wallet."
+
+            # for each address in the wallet, get the balance for the asset
+            balances = {}
+
+            try:
+                for address in self.wallet.addresses:
+                    balance = address.balance(asset_id)
+                    balances[address.address_id] = balance
+            except Exception as e:
+                return f"Error getting balance for all addresses in the wallet: {e!s}"
+
+            # Format each balance entry on a new line
+            balance_lines = [
+                f"  {addr}: {balance}" for addr, balance in balances.items()
+            ]
+            formatted_balances = "\n".join(balance_lines)
+            return f"Balances for wallet {self.wallet.id}:\n{formatted_balances}"
+
+        except Exception as e:
+            return f"Error getting balance: {str(e)}"
+
+    def _run(self, asset_id: str) -> str:
+        """Sync implementation of the tool.
+
+        This method is deprecated since we now have native async implementation in _arun.
+        """
+        raise NotImplementedError(
+            "Use _arun instead, which is the async implementation"
+        )