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

intentkit/skills/elfa/stats.py

@@ -0,0 +1,118 @@
+from typing import Type
+
+import httpx
+from langchain.tools.base import ToolException
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from .base import ElfaBaseTool, base_url
+
+
+class ElfaGetSmartStatsInput(BaseModel):
+    username: str = Field(description="username to get stats for")
+
+
+class SmartStatsData(BaseModel):
+    followerEngagementRatio: float | None = Field(
+        description="the ratio of engagement by followers"
+    )
+    averageEngagement: float | None = Field(
+        description="the average engagement of acount"
+    )
+    smartFollowingCount: float | None = Field(
+        description="the count of smart followings"
+    )
+
+
+class ElfaGetSmartStatsOutput(BaseModel):
+    success: bool
+    data: SmartStatsData | None = Field(None, description="The stats data")
+
+
+class ElfaGetSmartStats(ElfaBaseTool):
+    """
+    This tool uses the Elfa API to retrieve key social media metrics for a given username.  These metrics include:
+
+    * **Smart Following Count:** A metric representing the number of high-quality or influential followers.
+    * **Engagement Score:** A composite score reflecting the level of interaction with the user's content.
+    * **Engagement Ratio:** The ratio of engagement (likes, comments, shares) to the number of followers.
+
+    This tool is useful for:
+
+    * **Competitor Analysis:** Compare your social media performance to that of your competitors.
+    * **Influencer Identification:** Identify influential users in your niche.
+    * **Social Media Audits:**  Assess the overall health and effectiveness of a social media presence.
+
+    To use this tool, simply provide the desired username.  The tool will return the requested metrics.
+
+    Attributes:
+        name (str): Name of the tool, specifically "elfa_get_smart_stats".
+        description (str): Comprehensive description of the tool's purpose and functionality.
+        args_schema (Type[BaseModel]): Schema for input arguments, specifying expected parameters.
+    """
+
+    name: str = "elfa_get_smart_stats"
+    description: str = """This tool uses the Elfa API to retrieve key social media metrics for a given username.  These metrics include:
+
+        * **Smart Following Count:** A metric representing the number of high-quality or influential followers.
+        * **Engagement Score:** A composite score reflecting the level of interaction with the user's content.
+        * **Engagement Ratio:** The ratio of engagement (likes, comments, shares) to the number of followers.
+
+        This tool is useful for:
+
+        * **Competitor Analysis:** Compare your social media performance to that of your competitors.
+        * **Influencer Identification:** Identify influential users in your niche.
+        * **Social Media Audits:**  Assess the overall health and effectiveness of a social media presence.
+        """
+    args_schema: Type[BaseModel] = ElfaGetSmartStatsInput
+
+    async def _arun(
+        self, username: str, config: RunnableConfig, **kwargs
+    ) -> ElfaGetSmartStatsOutput:
+        """Run the tool retrieve smart stats (smart following count) and social metrics (engagement score and ratio) for a given username.
+
+        Args:
+            username (str): The username to check stats for.
+            config: The configuration for the runnable, containing agent context.
+            **kwargs: Additional parameters.
+
+        Returns:
+            ElfaGetSmartStatsOutput: A structured output containing output of Elfa get mentions API.
+
+        Raises:
+            Exception: If there's an error accessing the Elfa API.
+        """
+        context = self.context_from_config(config)
+        api_key = self.get_api_key(context)
+        if not api_key:
+            raise ValueError("Elfa API key not found")
+
+        url = f"{base_url}/v1/account/smart-stats"
+        headers = {
+            "accept": "application/json",
+            "x-elfa-api-key": api_key,
+        }
+
+        params = ElfaGetSmartStatsInput(username=username).model_dump(exclude_none=True)
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(
+                    url, headers=headers, timeout=30, params=params
+                )
+                response.raise_for_status()
+                json_dict = response.json()
+
+                res = ElfaGetSmartStatsOutput(**json_dict)
+
+                return res
+            except httpx.RequestError as req_err:
+                raise ToolException(
+                    f"request error from Elfa API: {req_err}"
+                ) from req_err
+            except httpx.HTTPStatusError as http_err:
+                raise ToolException(
+                    f"http error from Elfa API: {http_err}"
+                ) from http_err
+            except Exception as e:
+                raise ToolException(f"error from Elfa API: {e}") from e

intentkit/skills/elfa/tokens.py

@@ -0,0 +1,126 @@
+from typing import Type
+
+import httpx
+from langchain.tools.base import ToolException
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from .base import ElfaBaseTool, base_url
+
+
+class ElfaGetTrendingTokensInput(BaseModel):
+    timeWindow: str | None = Field(
+        "24h", description="Time window for trending analysis"
+    )
+    minMentions: int | None = Field(
+        5, description="Minimum number of mentions required"
+    )
+
+
+class Trends(BaseModel):
+    change_percent: int | None = Field(description="change percentage of token trend")
+    previous_count: int | None = Field(description="previous count")
+    current_count: int | None = Field(description="current count")
+    token: str | None = Field(description="token")
+
+
+class TrendsData(BaseModel):
+    data: list[Trends] | None = Field(None, description="trending tokens")
+
+
+class ElfaGetTrendingTokensOutput(BaseModel):
+    success: bool
+    data: TrendsData | None = Field(None, description="The result")
+
+
+class ElfaGetTrendingTokens(ElfaBaseTool):
+    """
+    This tool ranks the most discussed tokens based on smart mentions count for a given period, with updates every 5 minutes via the Elfa API.  Smart mentions provide a more sophisticated measure of discussion volume than simple keyword counts.
+
+    **Use Cases:**
+
+    * Identify trending tokens: Quickly see which tokens are gaining traction in online discussions.
+    * Gauge market sentiment:  Track changes in smart mention counts to understand shifts in market opinion.
+    * Research potential investments: Use the ranking as a starting point for further due diligence.
+
+    **Example Usage:**
+
+    To use this tool, you would typically specify a time window (e.g., the last hour, the last 24 hours). The tool will then return a ranked list of tokens, along with their corresponding smart mention counts.
+
+    Attributes:
+        name (str): Name of the tool, specifically "elfa_get_trending_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 = "elfa_get_trending_tokens"
+    description: str = """This tool ranks the most discussed tokens based on smart mentions count for a given period, with updates every 5 minutes via the Elfa API.  Smart mentions provide a more sophisticated measure of discussion volume than simple keyword counts.
+
+        **Use Cases:**
+
+        * Identify trending tokens: Quickly see which tokens are gaining traction in online discussions.
+        * Gauge market sentiment:  Track changes in smart mention counts to understand shifts in market opinion.
+        * Research potential investments: Use the ranking as a starting point for further due diligence.
+
+        **Example Usage:**
+
+        To use this tool, you would typically specify a time window (e.g., the last hour, the last 24 hours). The tool will then return a ranked list of tokens, along with their corresponding smart mention counts."""
+    args_schema: Type[BaseModel] = ElfaGetTrendingTokensInput
+
+    async def _arun(
+        self,
+        timeWindow: str = "24h",
+        minMentions: int = 5,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> ElfaGetTrendingTokensOutput:
+        """Run the tool to ranks the most discussed tokens by smart mentions count for a given period, updated every 5 minutes via the Elfa API.
+
+        Args:
+            timeWindow: Time window for trending tokens (e.g., '1h', '24h', '7d').
+            minMentions: Minimum number of mentions for a token.
+            config: The configuration for the runnable, containing agent context.
+            **kwargs: Additional parameters.
+
+        Returns:
+            ElfaGetMentionsOutput: A structured output containing output of Elfa get mentions API.
+
+        Raises:
+            Exception: If there's an error accessing the Elfa API.
+        """
+        context = self.context_from_config(config)
+        api_key = self.get_api_key(context)
+        if not api_key:
+            raise ValueError("Elfa API key not found")
+
+        url = f"{base_url}/v1/trending-tokens"
+        headers = {
+            "accept": "application/json",
+            "x-elfa-api-key": api_key,
+        }
+
+        params = ElfaGetTrendingTokensInput(
+            timeWindow=timeWindow, page=1, pageSize=50, minMentions=minMentions
+        ).model_dump(exclude_none=True)
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(
+                    url, headers=headers, timeout=30, params=params
+                )
+                response.raise_for_status()
+                json_dict = response.json()
+
+                res = ElfaGetTrendingTokensOutput(**json_dict)
+
+                return res
+            except httpx.RequestError as req_err:
+                raise ToolException(
+                    f"request error from Elfa API: {req_err}"
+                ) from req_err
+            except httpx.HTTPStatusError as http_err:
+                raise ToolException(
+                    f"http error from Elfa API: {http_err}"
+                ) from http_err
+            except Exception as e:
+                raise ToolException(f"error from Elfa API: {e}") from e

intentkit/skills/enso/README.md

@@ -0,0 +1,75 @@
+# Enso Finance Skills
+
+Integration with Enso Finance API for DeFi protocols, portfolio management, and yield optimization.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `enso_get_networks` | List supported networks |
+| `enso_get_tokens` | Get token info (APY, symbol, address) |
+| `enso_get_prices` | Get token prices |
+| `enso_get_wallet_balances` | Get wallet token balances |
+| `enso_get_wallet_approvals` | Get token spend approvals |
+| `enso_wallet_approve` | Broadcast approval transactions |
+| `enso_route_shortcut` | Broadcast route transactions |
+| `enso_get_best_yield` | Find best yield options across protocols |
+
+## Configuration
+
+```yaml
+# Agent configuration example
+skills:
+  enso:
+    enabled: true
+    api_token: "${ENSO_API_TOKEN}"  # Optional if set at system level
+    main_tokens: ["USDC", "ETH", "USDT"]
+    states:
+      get_networks: public
+      get_tokens: public
+      get_prices: public
+      get_best_yield: public
+      # Sensitive operations should be private or disabled
+      get_wallet_approvals: private
+      get_wallet_balances: private
+      wallet_approve: private
+      route_shortcut: disabled
+```
+
+## Get Best Yield Skill
+
+Finds highest yield options for a token across protocols. Default: USDC on Base network.
+
+### Parameters
+
+- `token_symbol`: Token symbol (default: "USDC")
+- `chain_id`: Blockchain network ID (default: 8453 for Base)
+- `top_n`: Number of options to return (default: 5)
+
+### Example
+
+```
+# Query: What are the best USDC yield options on Base?
+
+# Response format:
+{
+  "best_options": [
+    {
+      "protocol_name": "Protocol Name",
+      "token_name": "Token Name",
+      "apy": 12.5,
+      "tvl": 5000000,
+      "underlying_tokens": ["USDC"]
+    },
+    // Additional results...
+  ],
+  "token_symbol": "USDC",
+  "chain_name": "Base"
+}
+```
+
+The skill fetches protocols, retrieves token data, filters for the target token, and sorts by APY.
+
+## Authentication
+
+Requires an Enso API token in agent config or system config.

intentkit/skills/enso/__init__.py

@@ -0,0 +1,114 @@
+"""Enso skills."""
+
+import logging
+from typing import List, NotRequired, TypedDict
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import SkillConfig, SkillState
+from intentkit.skills.enso.base import EnsoBaseTool
+from intentkit.skills.enso.best_yield import EnsoGetBestYield
+from intentkit.skills.enso.networks import EnsoGetNetworks
+from intentkit.skills.enso.prices import EnsoGetPrices
+from intentkit.skills.enso.route import EnsoRouteShortcut
+from intentkit.skills.enso.tokens import EnsoGetTokens
+from intentkit.skills.enso.wallet import (
+    EnsoGetWalletApprovals,
+    EnsoGetWalletBalances,
+    EnsoWalletApprove,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SkillStates(TypedDict):
+    get_networks: SkillState
+    get_tokens: SkillState
+    get_prices: SkillState
+    get_wallet_approvals: SkillState
+    get_wallet_balances: SkillState
+    wallet_approve: SkillState
+    route_shortcut: SkillState
+    get_best_yield: SkillState
+
+
+class Config(SkillConfig):
+    """Configuration for Enso skills."""
+
+    states: SkillStates
+    api_token: NotRequired[str]
+    main_tokens: List[str]
+
+
+async def get_skills(
+    config: Config,
+    is_private: bool,
+    store: SkillStoreABC,
+    **_,
+) -> list[EnsoBaseTool]:
+    """Get all Enso 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)
+
+    # Get each skill using the cached getter
+    result = []
+    for name in available_skills:
+        skill = get_enso_skill(name, store)
+        if skill:
+            result.append(skill)
+    return result
+
+
+def get_enso_skill(
+    name: str,
+    skill_store: SkillStoreABC,
+) -> EnsoBaseTool:
+    """Get an Enso skill by name.
+
+    Args:
+        name: The name of the skill to get
+        skill_store: The skill store for persisting data
+
+    Returns:
+        The requested Enso skill
+    """
+    if name == "get_networks":
+        return EnsoGetNetworks(
+            skill_store=skill_store,
+        )
+    if name == "get_tokens":
+        return EnsoGetTokens(
+            skill_store=skill_store,
+        )
+    if name == "get_prices":
+        return EnsoGetPrices(
+            skill_store=skill_store,
+        )
+    if name == "get_wallet_approvals":
+        return EnsoGetWalletApprovals(
+            skill_store=skill_store,
+        )
+    if name == "get_wallet_balances":
+        return EnsoGetWalletBalances(
+            skill_store=skill_store,
+        )
+    if name == "wallet_approve":
+        return EnsoWalletApprove(
+            skill_store=skill_store,
+        )
+    if name == "route_shortcut":
+        return EnsoRouteShortcut(
+            skill_store=skill_store,
+        )
+    if name == "get_best_yield":
+        return EnsoGetBestYield(
+            skill_store=skill_store,
+        )
+    else:
+        logger.warning(f"Unknown Enso skill: {name}")
+        return None