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

intentkit/skills/enso/tokens.py

@@ -0,0 +1,223 @@
+from typing import Type
+
+import httpx
+from langchain.tools.base import ToolException
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.base import SkillContext
+from intentkit.skills.enso.base import (
+    EnsoBaseTool,
+    base_url,
+    default_chain_id,
+)
+
+# Actual Enso output types
+# class UnderlyingToken(BaseModel):
+#     address: str | None = Field(None, description="The address of the token")
+#     chainId: int | None = Field(None, description="The blockchain chain ID")
+#     type: str | None = Field(None, description="The type of the token (e.g., base token)")
+#     decimals: int | None = Field(None, description="The number of decimals for the token")
+#     name: str | None = Field(None, description="The name of the token")
+#     symbol: str | None = Field(None, description="The symbol of the token")
+#     logosUri: list[HttpUrl] | None = Field(None, description="List of URLs to token's logos")
+#
+#
+# class TokenData(BaseModel):
+#     chainId: int | None = Field(None, description="The blockchain chain ID")
+#     address: str | None = Field(None, description="The address of the token")
+#     decimals: int | None = Field(None, description="The number of decimals for the token")
+#     name: str | None = Field(None, description="The name of the token")
+#     symbol: str | None = Field(None, description="The symbol of the token")
+#     logosUri: list[HttpUrl] | None = Field(None, description="List of URLs to token's logos")
+#     type: str | None = Field(None, description="The type of the token (e.g., defi, base, etc.)")
+#     protocolSlug: str | None = Field(None, description="The protocol slug associated with the token")
+#     underlyingTokens: list[UnderlyingToken] | None = Field(None, description="List of underlying tokens")
+#     primaryAddress: str | None = Field(None, description="The primary address associated with the token")
+#     apy: float | None = Field(None, description="The annual percentage yield (APY) for the token")
+#
+#
+# class MetaData(BaseModel):
+#     total: int | None = Field(None, description="Total number of records")
+#     lastPage: int | None = Field(None, description="Last page of the data")
+#     currentPage: int | None = Field(None, description="Current page of the data")
+#     perPage: int | None = Field(None, description="Number of records per page")
+#     prev: int | None = Field(None, description="Previous page number, if applicable")
+#     next: int | None = Field(None, description="Next page number, if applicable")
+#
+#
+# class TokenResponse(BaseModel):
+#     data: list[TokenData] | None = Field(None, description="List of token data")
+#     meta: MetaData | None = Field(None, description="Metadata regarding pagination")
+
+
+class EnsoGetTokensInput(BaseModel):
+    chainId: int = Field(
+        default_chain_id,
+        description="The blockchain chain ID",
+    )
+    protocolSlug: str | None = Field(
+        None,
+        description="The protocol slug (e.g., 'aave-v2', 'aave-v3', 'compound-v2')",
+    )
+    # address: str | None = Field(
+    #     None,
+    #     description="Ethereum address of the token",
+    # )
+    # underlyingTokens: str | list[str] | None = Field(
+    #     None,
+    #     description="Underlying tokens (e.g. 0xdAC17F958D2ee523a2206206994597C13D831ec7)",
+    # )
+    # primaryAddress: str | None = Field(
+    #     None,
+    #     description="Ethereum address for contract interaction of defi token",
+    # )
+    # type: Literal["defi", "base"] | None = Field(
+    #     None,
+    #     description="The type of the token (e.g., 'defi', 'base'). Note: Base Network also exists, it should not be confused with type.",
+    # )
+
+
+class UnderlyingTokenCompact(BaseModel):
+    address: str | None = Field(None, description="The address of the token")
+    type: str | None = Field(
+        None, description="The type of the token (e.g., base token)"
+    )
+    name: str | None = Field(None, description="The name of the token")
+    symbol: str | None = Field(None, description="The symbol of the token")
+    decimals: int | None = Field(
+        None, description="The number of decimals for the token"
+    )
+
+
+class TokenResponseCompact(BaseModel):
+    name: str | None = Field(None, description="The name of the token")
+    symbol: str | None = Field(None, description="The symbol of the token")
+    address: str | None = Field(None, description="The address of the token")
+    primaryAddress: str | None = Field(
+        None, description="The primary address associated with the token"
+    )
+    type: str | None = Field(
+        None, description="The type of the token (e.g., defi, base, etc.)"
+    )
+    apy: float | None = Field(
+        None, description="The annual percentage yield (APY) for the token"
+    )
+    underlyingTokens: list[UnderlyingTokenCompact] | None = Field(
+        None, description="List of underlying tokens"
+    )
+    decimals: int | None = Field(
+        None, description="The number of decimals for the token"
+    )
+
+
+class EnsoGetTokensOutput(BaseModel):
+    res: list[TokenResponseCompact] | None
+
+
+class EnsoGetTokens(EnsoBaseTool):
+    """
+    Tool for interacting with the Enso API to retrieve cryptocurrency token information, including APY, symbol, address,
+    protocol slug, token type, and underlying tokens.
+
+    This class is designed to provide detailed insights into tokens managed by the Enso platform.
+    It integrates with the Enso API and offers various options for filtering tokens based on optional inputs such as
+    chain ID, protocol slug, token type, and underlying tokens. The main objective is to retrieve APY data
+    and relevant information for the specified tokens, delivering structured output for further processing.
+
+    Attributes:
+        name (str): Name of the tool, specifically "enso_get_tokens".
+        description (str): Comprehensive description of the tool's purpose and functionality.
+        args_schema (Type[BaseModel]): Schema for input arguments, specifying expected parameters.
+    """
+
+    name: str = "enso_get_tokens"
+    description: str = (
+        "Enso Finance Token Information Tool: Retrieves detailed token information from the Enso Finance API, "
+        "including APY, symbol, address, protocol slug, token type, and underlying tokens."
+    )
+    args_schema: Type[BaseModel] = EnsoGetTokensInput
+
+    async def _arun(
+        self,
+        config: RunnableConfig,
+        chainId: int = default_chain_id,
+        protocolSlug: str | None = None,
+        **kwargs,
+    ) -> EnsoGetTokensOutput:
+        """Run the tool to get Tokens and APY.
+        Args:
+            chainId (int): The chain id of the network.
+            protocolSlug (str): The protocol slug (e.g., 'aave-v2', 'aave-v3', 'compound-v2').
+        Returns:
+            EnsoGetTokensOutput: A structured output containing the tokens APY data.
+
+        Raises:
+            Exception: If there's an error accessing the Enso API.
+        """
+        url = f"{base_url}/api/v1/tokens"
+
+        context: SkillContext = self.context_from_config(config)
+        agent_id = context.agent.id
+        api_token = self.get_api_token(context)
+        main_tokens = self.get_main_tokens(context)
+        headers = {
+            "accept": "application/json",
+            "Authorization": f"Bearer {api_token}",
+        }
+
+        params = EnsoGetTokensInput(
+            chainId=chainId,
+            protocolSlug=protocolSlug,
+        ).model_dump(exclude_none=True)
+
+        params["page"] = 1
+        params["includeMetadata"] = "true"
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(url, headers=headers, params=params)
+                response.raise_for_status()
+                json_dict = response.json()
+
+                token_decimals = await self.skill_store.get_agent_skill_data(
+                    agent_id,
+                    "enso_get_tokens",
+                    "decimals",
+                )
+                if not token_decimals:
+                    token_decimals = {}
+
+                # filter the main tokens from config or the ones that have apy assigned.
+                res = EnsoGetTokensOutput(res=list[TokenResponseCompact]())
+                for item in json_dict["data"]:
+                    main_tokens = [item.upper() for item in main_tokens]
+                    if item.get("apy") or (item.get("symbol").upper() in main_tokens):
+                        token_response = TokenResponseCompact(**item)
+                        res.res.append(token_response)
+                        token_decimals[token_response.address] = token_response.decimals
+                        if (
+                            token_response.underlyingTokens
+                            and len(token_response.underlyingTokens) > 0
+                        ):
+                            for u_token in token_response.underlyingTokens:
+                                token_decimals[u_token.address] = u_token.decimals
+
+                await self.skill_store.save_agent_skill_data(
+                    agent_id,
+                    "enso_get_tokens",
+                    "decimals",
+                    token_decimals,
+                )
+
+                return res
+            except httpx.RequestError as req_err:
+                raise ToolException(
+                    f"request error from Enso API: {req_err}"
+                ) from req_err
+            except httpx.HTTPStatusError as http_err:
+                raise ToolException(
+                    f"http error from Enso API: {http_err}"
+                ) from http_err
+            except Exception as e:
+                raise ToolException(f"error from Enso API: {e}") from e

intentkit/skills/enso/wallet.py

@@ -0,0 +1,381 @@
+from typing import Literal, Tuple, Type
+
+import httpx
+from langchain.tools.base import ToolException
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.base import SkillContext
+from intentkit.utils.tx import EvmContractWrapper
+
+from .abi.erc20 import ABI_ERC20
+from .base import EnsoBaseTool, base_url, default_chain_id
+
+
+class EnsoGetBalancesInput(BaseModel):
+    """
+    Input model for retrieving wallet balances.
+    """
+
+    chainId: int = Field(
+        default_chain_id, description="Chain ID of the blockchain network"
+    )
+    # eoaAddress: str = Field(
+    #     description="Address of the eoa with which to associate the ensoWallet for balances"
+    # )
+    # useEoa: bool = Field(
+    #     description="If true returns balances for the provided eoaAddress, instead of the associated ensoWallet"
+    # )
+
+
+class WalletBalance(BaseModel):
+    token: str | None = Field(None, description="The address of the token")
+    amount: str | None = Field(None, description="The unformatted balance of the token")
+    decimals: int | None = Field(None, ge=0, description="The number of decimals")
+    price: float | None = Field(None, description="Price of the token in usd")
+
+
+class EnsoGetBalancesOutput(BaseModel):
+    """
+    Output model for retrieving wallet balances.
+    """
+
+    res: list[WalletBalance] | None = Field(
+        None, description="The wallet's balances along with token details."
+    )
+
+
+class EnsoGetWalletBalances(EnsoBaseTool):
+    """
+    This tool allows querying for first 20 token balances of a specific wallet
+    and blockchain network.
+
+    Attributes:
+        name (str): Name of the tool, specifically "enso_get_wallet_balances".
+        description (str): Comprehensive description of the tool's purpose and functionality.
+        args_schema (Type[BaseModel]): Schema for input arguments, specifying expected parameters.
+    """
+
+    name: str = "enso_get_wallet_balances"
+    description: str = (
+        "Retrieve token balances of a wallet on a specified blockchain network."
+    )
+    args_schema: Type[BaseModel] = EnsoGetBalancesInput
+
+    async def _arun(
+        self,
+        config: RunnableConfig,
+        chainId: int = default_chain_id,
+        **kwargs,
+    ) -> EnsoGetBalancesOutput:
+        """
+        Run the tool to get token balances of a wallet.
+
+        Args:
+            chainId (int): Chain ID of the blockchain network.
+
+        Returns:
+            EnsoGetBalancesOutput: The list of balances or an error message.
+        """
+        url = f"{base_url}/api/v1/wallet/balances"
+
+        context: SkillContext = self.context_from_config(config)
+        api_token = self.get_api_token(context)
+        wallet = await self.get_wallet(context)
+        headers = {
+            "accept": "application/json",
+            "Authorization": f"Bearer {api_token}",
+        }
+
+        params = EnsoGetBalancesInput(chainId=chainId).model_dump(exclude_none=True)
+        params["eoaAddress"] = wallet.addresses[0].address_id
+        params["useEoa"] = True
+
+        async with httpx.AsyncClient() as client:
+            try:
+                # Send the GET request
+                response = await client.get(url, headers=headers, params=params)
+                response.raise_for_status()
+
+                # Map the response JSON into the WalletBalance model
+                json_dict = response.json()[:20]
+                res = [WalletBalance(**item) for item in json_dict]
+
+                # Return the parsed response
+                return EnsoGetBalancesOutput(res=res)
+            except httpx.RequestError as req_err:
+                raise ToolException("request error from Enso API") from req_err
+            except httpx.HTTPStatusError as http_err:
+                raise ToolException("http error from Enso API") from http_err
+            except Exception as e:
+                raise ToolException(f"error from Enso API: {e}") from e
+
+
+class EnsoGetApprovalsInput(BaseModel):
+    """
+    Input model for retrieving wallet approvals.
+    """
+
+    chainId: int = Field(
+        default_chain_id, description="Chain ID of the blockchain network"
+    )
+    fromAddress: str = Field(description="Address of the wallet")
+    routingStrategy: Literal["ensowallet", "router", "delegate"] | None = Field(
+        None, description="Routing strategy to use"
+    )
+
+
+class WalletAllowance(BaseModel):
+    token: str | None = Field(None, description="The token address")
+    allowance: str | None = Field(None, description="The amount of tokens approved")
+    spender: str | None = Field(None, description="The spender address")
+
+
+class EnsoGetApprovalsOutput(BaseModel):
+    """
+    Output model for retrieving wallet approvals.
+    """
+
+    res: list[WalletAllowance] | None = Field(
+        None, description="Response containing the list of token approvals."
+    )
+
+
+class EnsoGetWalletApprovals(EnsoBaseTool):
+    """
+    This tool allows querying for first 50 token spend approvals associated with a specific wallet
+    and blockchain network.
+
+    Attributes:
+        name (str): Name of the tool, specifically "enso_get_wallet_approvals".
+        description (str): Comprehensive description of the tool's purpose and functionality.
+        args_schema (Type[BaseModel]): Schema for input arguments, specifying expected parameters.
+    """
+
+    name: str = "enso_get_wallet_approvals"
+    description: str = (
+        "Retrieve token spend approvals for a wallet on a specified blockchain network."
+    )
+    args_schema: Type[BaseModel] = EnsoGetApprovalsOutput
+
+    async def _arun(
+        self,
+        config: RunnableConfig,
+        chainId: int = default_chain_id,
+        **kwargs,
+    ) -> EnsoGetApprovalsOutput:
+        """
+        Run the tool to get token approvals for a wallet.
+
+        Args:
+            chainId (int): Chain ID of the blockchain network.
+            **kwargs: optional kwargs for the tool with args schema defined in EnsoGetApprovalsInput.
+
+        Returns:
+            EnsoGetApprovalsOutput: The list of approvals or an error message.
+        """
+        url = f"{base_url}/api/v1/wallet/approvals"
+
+        context: SkillContext = self.context_from_config(config)
+        api_token = self.get_api_token(context)
+        wallet = await self.get_wallet(context)
+
+        headers = {
+            "accept": "application/json",
+            "Authorization": f"Bearer {api_token}",
+        }
+
+        params = EnsoGetApprovalsInput(
+            chainId=chainId,
+            fromAddress=wallet.addresses[0].address_id,
+        )
+
+        if kwargs.get("routingStrategy"):
+            params.routingStrategy = kwargs["routingStrategy"]
+
+        async with httpx.AsyncClient() as client:
+            try:
+                # Send the GET request
+                response = await client.get(
+                    url, headers=headers, params=params.model_dump(exclude_none=True)
+                )
+                response.raise_for_status()
+
+                # Map the response JSON into the ApprovalsResponse model
+                json_dict = response.json()[:50]
+                res = [WalletAllowance(**item) for item in json_dict]
+
+                # Return the parsed response
+                return EnsoGetApprovalsOutput(res=res)
+            except httpx.RequestError as req_err:
+                raise ToolException(
+                    f"request error from Enso API: {req_err}"
+                ) from req_err
+            except httpx.HTTPStatusError as http_err:
+                raise ToolException(
+                    f"http error from Enso API: {http_err}"
+                ) from http_err
+            except Exception as e:
+                raise ToolException(f"error from Enso API: {e}") from e
+
+
+class EnsoWalletApproveInput(BaseModel):
+    """
+    Input model for approve the wallet.
+    """
+
+    tokenAddress: str = Field(description="ERC20 token address of the token to approve")
+    amount: int = Field(description="Amount of tokens to approve in wei")
+    chainId: int = Field(
+        default_chain_id, description="Chain ID of the blockchain network"
+    )
+    routingStrategy: Literal["ensowallet", "router", "delegate"] | None = Field(
+        None, description="Routing strategy to use"
+    )
+
+
+class EnsoWalletApproveOutput(BaseModel):
+    """
+    Output model for approve token for the wallet.
+    """
+
+    gas: str | None = Field(None, description="The gas estimate for the transaction")
+    token: str | None = Field(None, description="The token address to approve")
+    amount: str | None = Field(None, description="The amount of tokens to approve")
+    spender: str | None = Field(None, description="The spender address to approve")
+
+
+class EnsoWalletApproveArtifact(BaseModel):
+    """
+    Output model for approve token for the wallet.
+    """
+
+    tx: object | None = Field(None, description="The tx object to use in `ethers`")
+    txHash: str | None = Field(None, description="The transaction hash")
+
+
+class EnsoWalletApprove(EnsoBaseTool):
+    """
+    This tool is used specifically for broadcasting a ERC20 token spending approval transaction to the network.
+    It should only be used when the user explicitly requests to broadcast an approval transaction with a specific amount for a certain token.
+
+    **Example Usage:**
+
+    "Broadcast an approval transaction for 10 USDC to the wallet."
+
+    **Important:**
+    - This tool should be used with extreme caution.
+    - Approving token spending grants another account permission to spend your tokens.
+
+    Attributes:
+        name (str): Name of the tool, specifically "enso_wallet_approve".
+        description (str): Comprehensive description of the tool's purpose and functionality.
+        args_schema (Type[BaseModel]): Schema for input arguments, specifying expected parameters.
+    """
+
+    name: str = "enso_wallet_approve"
+    description: str = "This tool is used specifically for broadcasting a ERC20 token spending approval transaction to the network. It should only be used when the user explicitly requests to broadcast an approval transaction with a specific amount for a certain token."
+    args_schema: Type[BaseModel] = EnsoWalletApproveInput
+    response_format: str = "content_and_artifact"
+
+    # def _run(
+    #     self,
+    #     tokenAddress: str,
+    #     amount: int,
+    #     chainId: int = default_chain_id,
+    #     **kwargs,
+    # ) -> Tuple[EnsoBroadcastWalletApproveOutput, EnsoBroadcastWalletApproveArtifact]:
+    #     """Run the tool to approve enso router for a wallet.
+
+    #     Returns:
+    #         Tuple[EnsoBroadcastWalletApproveOutput, EnsoBroadcastWalletApproveArtifact]: A structured output containing the result of token approval.
+
+    #     Raises:
+    #         Exception: If there's an error accessing the Enso API.
+    #     """
+    #     raise NotImplementedError("Use _arun instead")
+
+    async def _arun(
+        self,
+        tokenAddress: str,
+        amount: int,
+        config: RunnableConfig,
+        chainId: int = default_chain_id,
+        **kwargs,
+    ) -> Tuple[EnsoWalletApproveOutput, EnsoWalletApproveArtifact]:
+        """
+        Run the tool to approve enso router for a wallet.
+
+        Args:
+            tokenAddress (str): ERC20 token address of the token to approve.
+            amount (int): Amount of tokens to approve in wei.
+            chainId (int): Chain ID of the blockchain network.
+            **kwargs: optional kwargs for the tool with args schema defined in EnsoGetApproveInput.
+
+        Returns:
+            Tuple[EnsoBroadcastWalletApproveOutput, EnsoBroadcastWalletApproveArtifact]: The list of approve transaction output or an error message.
+        """
+        url = f"{base_url}/api/v1/wallet/approve"
+        context: SkillContext = self.context_from_config(config)
+        api_token = self.get_api_token(context)
+        chain_provider = self.get_chain_provider(context)
+        wallet = await self.get_wallet(context)
+
+        headers = {
+            "accept": "application/json",
+            "Authorization": f"Bearer {api_token}",
+        }
+
+        from_address = wallet.addresses[0].address_id
+
+        params = EnsoWalletApproveInput(
+            tokenAddress=tokenAddress,
+            amount=amount,
+            chainId=chainId,
+        )
+
+        if kwargs.get("routingStrategy"):
+            params.routingStrategy = kwargs["routingStrategy"]
+
+        params = params.model_dump(exclude_none=True)
+
+        params["fromAddress"] = from_address
+
+        with httpx.Client() as client:
+            try:
+                # Send the GET request
+                response = client.get(url, headers=headers, params=params)
+                response.raise_for_status()
+
+                # Map the response JSON into the WalletApproveTransaction model
+                json_dict = response.json()
+                content = EnsoWalletApproveOutput(**json_dict)
+                artifact = EnsoWalletApproveArtifact(**json_dict)
+
+                rpc_url = chain_provider.get_chain_config_by_id(chainId).rpc_url
+                contract = EvmContractWrapper(rpc_url, ABI_ERC20, artifact.tx)
+
+                fn, fn_args = contract.fn_and_args
+                fn_args["value"] = str(fn_args["value"])
+
+                invocation = wallet.invoke_contract(
+                    contract_address=contract.dst_addr,
+                    method=fn.fn_name,
+                    abi=ABI_ERC20,
+                    args=fn_args,
+                ).wait()
+
+                artifact.txHash = invocation.transaction.transaction_hash
+
+                # Return the parsed response
+                return (content, artifact)
+            except httpx.RequestError as req_err:
+                raise ToolException(
+                    f"request error from Enso API: {req_err}"
+                ) from req_err
+            except httpx.HTTPStatusError as http_err:
+                raise ToolException(
+                    f"http error from Enso API: {http_err}"
+                ) from http_err
+            except Exception as e:
+                raise ToolException(f"error from Enso API: {e}") from e

intentkit/skills/github/README.md

@@ -0,0 +1,63 @@
+# GitHub Skill
+
+This skill enables agents to search GitHub for repositories, users, and code using GitHub's public API endpoints.
+
+## Features
+
+- Search GitHub repositories by name, description, or topics
+- Search GitHub users by username or real name
+- Search code snippets across GitHub repositories
+- No authentication required (uses public API endpoints)
+- Rate limit aware (respects GitHub's public API limits)
+
+## Configuration
+
+Add the GitHub skill to your agent's configuration:
+
+```yaml
+skills:
+  github:
+    states:
+      github_search: public  # or private if you want to restrict access
+```
+
+## Usage Examples
+
+The agent can use the GitHub skill to answer questions like:
+
+- "Find repositories about blockchain development"
+- "Search for users who work on web3 projects"
+- "Find code examples of smart contracts in Solidity"
+- "Show me popular Python machine learning repositories"
+- "Find developers who contribute to Ethereum"
+
+## Rate Limits
+
+The skill uses GitHub's public API which has the following rate limits:
+- 60 requests per hour per IP address
+- No authentication required
+- Results are limited to public repositories and users
+
+## Implementation Details
+
+The skill uses the following GitHub API endpoints:
+- `/search/repositories` - For searching repositories
+- `/search/users` - For searching users
+- `/search/code` - For searching code
+
+Each search result includes:
+- For repositories: name, description, language, stars count, and URL
+- For users: username, name, bio, and profile URL
+- For code: repository name, file path, and URL
+
+## Error Handling
+
+The skill handles various error cases:
+- API rate limits
+- Network errors
+- Invalid queries
+- No results found
+
+## Logging
+
+All operations are logged with the prefix `github_search.py:` for easy debugging and monitoring.