intentkit 0.6.7.dev7__py3-none-any.whl → 0.6.7.dev9__py3-none-any.whl

intentkit/skills/elfa/schema.json

@@ -18,22 +18,6 @@
     "states": {
       "type": "object",
       "properties": {
-        "get_mentions": {
-          "type": "string",
-          "title": "Get Mentions",
-          "enum": [
-            "disabled",
-            "public",
-            "private"
-          ],
-          "x-enum-title": [
-            "Disabled",
-            "Agent Owner + All Users",
-            "Agent Owner Only"
-          ],
-          "description": "This tool uses the Elfa AI API to query hourly-updated tweets from \"smart accounts\" \u2013 accounts identified as influential or relevant \u2013 that have received at least 10 interactions (comments, retweets, quote tweets).",
-          "default": "disabled"
-        },
         "get_top_mentions": {
           "type": "string",
           "title": "Get Top Mentions",
@@ -63,7 +47,7 @@
             "Agent Owner + All Users",
             "Agent Owner Only"
           ],
-          "description": "This tool uses the Elfa API to search tweets mentioning up to five keywords. It can search within the past 30 days of data, which is updated every 5 minutes, or access up to six months of historical tweet data.",
+          "description": "This tool uses the Elfa API to search tweets mentioning up to five keywords or from specific accounts. It can search within the past 30 days of data, which is updated every 5 minutes, or access up to six months of historical tweet data.",
           "default": "private"
         },
         "get_trending_tokens": {

intentkit/skills/elfa/stats.py

@@ -1,118 +1,85 @@
-from typing import Type
+"""Smart stats skill for Elfa AI API."""
+
+from typing import Any, Dict, Optional, 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
+from .base import ElfaBaseTool
+from .utils import SmartStatsData, make_elfa_request
 
 
 class ElfaGetSmartStatsInput(BaseModel):
-    username: str = Field(description="username to get stats for")
-
+    """Input parameters for smart stats."""
 
-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"
-    )
+    username: str = Field(description="Account username to get stats for")
 
 
 class ElfaGetSmartStatsOutput(BaseModel):
+    """Output structure for smart stats response."""
+
     success: bool
-    data: SmartStatsData | None = Field(None, description="The stats data")
+    data: Optional[SmartStatsData] = Field(None, description="Smart stats data")
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Response metadata")
 
 
 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.
+    Get smart stats for a specific username.
+
+    This tool uses the Elfa API to retrieve key social media metrics for a given username including:
+    - Smart Following Count: Number of high-quality or influential followers
+    - Average Engagement: Composite score reflecting interaction with user's content
+    - Average Reach: Average reach of the user's content
+    - Smart Follower Count: Number of smart followers
+    - Follower Count: Total follower count
+
+    Use Cases:
+    - Competitor analysis: Compare social media performance to competitors
+    - Influencer identification: Identify influential users in your niche
+    - Social media audits: Assess overall health and effectiveness of social media presence
     """
 
     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.
-        """
+    description: str = """Get comprehensive social media metrics for a username including smart following count, 
+    engagement scores, and follower analytics. Use this for competitor analysis, influencer identification, 
+    and social media performance audits."""
     args_schema: Type[BaseModel] = ElfaGetSmartStatsInput
 
     async def _arun(
-        self, username: str, config: RunnableConfig, **kwargs
+        self, username: str, config: RunnableConfig = None, **kwargs
     ) -> ElfaGetSmartStatsOutput:
-        """Run the tool retrieve smart stats (smart following count) and social metrics (engagement score and ratio) for a given username.
+        """
+        Execute the smart stats request.
 
         Args:
-            username (str): The username to check stats for.
-            config: The configuration for the runnable, containing agent context.
-            **kwargs: Additional parameters.
+            username: The username to check stats for
+            config: LangChain runnable configuration
+            **kwargs: Additional parameters
 
         Returns:
-            ElfaGetSmartStatsOutput: A structured output containing output of Elfa get mentions API.
+            ElfaGetSmartStatsOutput: Structured response with smart stats
 
         Raises:
-            Exception: If there's an error accessing the Elfa API.
+            ValueError: If API key is not found
+            ToolException: If there's an error with the API request
         """
         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
+
+        # Prepare parameters according to API spec
+        params = {"username": username}
+
+        # Make API request using shared utility
+        response = await make_elfa_request(
+            endpoint="account/smart-stats", api_key=api_key, params=params
+        )
+
+        # Parse response data into SmartStatsData object
+        stats_data = None
+        if response.data and isinstance(response.data, dict):
+            stats_data = SmartStatsData(**response.data)
+
+        return ElfaGetSmartStatsOutput(
+            success=response.success, data=stats_data, metadata=response.metadata
+        )

intentkit/skills/elfa/tokens.py

@@ -1,126 +1,122 @@
-from typing import Type
+"""Trending tokens skill for Elfa AI API."""
+
+from typing import Any, Dict, List, Optional, 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
+from .base import ElfaBaseTool
+from .utils import make_elfa_request
 
 
 class ElfaGetTrendingTokensInput(BaseModel):
-    timeWindow: str | None = Field(
-        "24h", description="Time window for trending analysis"
+    """Input parameters for trending tokens."""
+
+    timeWindow: Optional[str] = Field(
+        "7d",
+        description="Time window for trending analysis (e.g., '30m', '1h', '4h', '24h', '7d', '30d')",
     )
-    minMentions: int | None = Field(
+    page: Optional[int] = Field(1, description="Page number for pagination")
+    pageSize: Optional[int] = Field(50, description="Number of items per page")
+    minMentions: Optional[int] = 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 TrendingToken(BaseModel):
+    """Individual trending token data."""
 
-
-class TrendsData(BaseModel):
-    data: list[Trends] | None = Field(None, description="trending tokens")
+    token: Optional[str] = Field(None, description="Token symbol")
+    current_count: Optional[int] = Field(None, description="Current mention count")
+    previous_count: Optional[int] = Field(None, description="Previous mention count")
+    change_percent: Optional[float] = Field(None, description="Change percentage")
 
 
 class ElfaGetTrendingTokensOutput(BaseModel):
+    """Output structure for trending tokens response."""
+
     success: bool
-    data: TrendsData | None = Field(None, description="The result")
+    data: Optional[List[TrendingToken]] = Field(
+        None, description="List of trending tokens"
+    )
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Response metadata")
 
 
 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.
+    Get trending tokens based on smart mentions count.
 
-    **Example Usage:**
+    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.
 
-    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.
+    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
     """
 
     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."""
+    description: str = """Get trending tokens ranked by smart mentions count for a given time period. 
+    Updated every 5 minutes. Smart mentions provide sophisticated discussion volume measurement beyond simple keyword counts.
+    
+    Use this to identify tokens gaining traction, gauge market sentiment, and research potential investments."""
     args_schema: Type[BaseModel] = ElfaGetTrendingTokensInput
 
     async def _arun(
         self,
-        timeWindow: str = "24h",
+        timeWindow: str = "7d",
+        page: int = 1,
+        pageSize: int = 50,
         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.
+        """
+        Execute the trending tokens request.
 
         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.
+            timeWindow: Time window for analysis (default: 7d)
+            page: Page number for pagination (default: 1)
+            pageSize: Items per page (default: 50)
+            minMentions: Minimum mentions required (default: 5)
+            config: LangChain runnable configuration
+            **kwargs: Additional parameters
 
         Returns:
-            ElfaGetMentionsOutput: A structured output containing output of Elfa get mentions API.
+            ElfaGetTrendingTokensOutput: Structured response with trending tokens
 
         Raises:
-            Exception: If there's an error accessing the Elfa API.
+            ValueError: If API key is not found
+            ToolException: If there's an error with the API request
         """
         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,
+        # Prepare parameters according to API spec
+        params = {
+            "timeWindow": timeWindow,
+            "page": page,
+            "pageSize": pageSize,
+            "minMentions": minMentions,
         }
 
-        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
+        # Make API request using shared utility
+        response = await make_elfa_request(
+            endpoint="aggregations/trending-tokens", api_key=api_key, params=params
+        )
+
+        # Parse response data into TrendingToken objects
+        trending_tokens = []
+        if response.data:
+            if isinstance(response.data, list):
+                trending_tokens = [TrendingToken(**item) for item in response.data]
+            elif isinstance(response.data, dict) and "data" in response.data:
+                # Handle nested data structure if present
+                trending_tokens = [
+                    TrendingToken(**item) for item in response.data["data"]
+                ]
+
+        return ElfaGetTrendingTokensOutput(
+            success=response.success, data=trending_tokens, metadata=response.metadata
+        )

intentkit/skills/elfa/utils.py

@@ -0,0 +1,129 @@
+"""Utility functions for Elfa skills."""
+
+from typing import Any, Dict, Optional
+
+import httpx
+from langchain.tools.base import ToolException
+from pydantic import BaseModel, Field
+
+from .base import base_url
+
+
+class ElfaResponse(BaseModel):
+    """Standard Elfa API v2 response format."""
+
+    success: bool
+    data: Any = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+async def make_elfa_request(
+    endpoint: str,
+    api_key: str,
+    params: Optional[Dict[str, Any]] = None,
+    timeout: int = 30,
+) -> ElfaResponse:
+    """
+    Make a standardized request to the Elfa API.
+
+    Args:
+        endpoint: API endpoint path (e.g., "aggregations/trending-tokens")
+        api_key: Elfa API key
+        params: Query parameters
+        timeout: Request timeout in seconds
+
+    Returns:
+        ElfaResponse: Standardized response object
+
+    Raises:
+        ToolException: If there's an error with the API request
+    """
+    if not api_key:
+        raise ValueError("Elfa API key not found")
+
+    url = f"{base_url}/{endpoint}"
+    headers = {
+        "accept": "application/json",
+        "x-elfa-api-key": api_key,
+    }
+
+    # Clean up params - remove None values
+    if params:
+        params = {k: v for k, v in params.items() if v is not None}
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.get(
+                url, headers=headers, timeout=timeout, params=params
+            )
+            response.raise_for_status()
+            json_dict = response.json()
+
+            # Handle v2 response format
+            if isinstance(json_dict, dict) and "success" in json_dict:
+                return ElfaResponse(
+                    success=json_dict["success"],
+                    data=json_dict.get("data"),
+                    metadata=json_dict.get("metadata", {}),
+                )
+            else:
+                # Fallback for unexpected format
+                return ElfaResponse(success=True, data=json_dict, metadata={})
+
+        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
+
+
+# Common Pydantic models for v2 API responses
+class RepostBreakdown(BaseModel):
+    """Repost breakdown data."""
+
+    smart: Optional[int] = None
+    ct: Optional[int] = None
+
+
+class Account(BaseModel):
+    """Account information."""
+
+    username: Optional[str] = None
+    isVerified: Optional[bool] = None
+
+
+class MentionData(BaseModel):
+    """Base mention data structure used across multiple endpoints."""
+
+    tweetId: Optional[str] = Field(None, description="Tweet ID")
+    link: Optional[str] = Field(None, description="Link to the tweet")
+    likeCount: Optional[int] = Field(None, description="Number of likes")
+    repostCount: Optional[int] = Field(None, description="Number of reposts")
+    viewCount: Optional[int] = Field(None, description="Number of views")
+    quoteCount: Optional[int] = Field(None, description="Number of quotes")
+    replyCount: Optional[int] = Field(None, description="Number of replies")
+    bookmarkCount: Optional[int] = Field(None, description="Number of bookmarks")
+    mentionedAt: Optional[str] = Field(None, description="When mentioned")
+    type: Optional[str] = Field(None, description="Post type")
+    account: Optional[Account] = Field(None, description="Account information")
+    repostBreakdown: Optional[RepostBreakdown] = Field(
+        None, description="Repost breakdown"
+    )
+
+
+class SmartStatsData(BaseModel):
+    """Smart stats data structure."""
+
+    smartFollowingCount: Optional[int] = Field(
+        None, description="Smart following count"
+    )
+    averageEngagement: Optional[float] = Field(None, description="Average engagement")
+    averageReach: Optional[float] = Field(None, description="Average reach")
+    smartFollowerCount: Optional[int] = Field(None, description="Smart follower count")
+    followerCount: Optional[int] = Field(None, description="Total follower count")
+
+
+def clean_params(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Remove None values from parameters dict."""
+    return {k: v for k, v in params.items() if v is not None}

intentkit/skills/twitter/get_mentions.py

@@ -58,7 +58,7 @@ class TwitterGetMentions(TwitterBaseTool):
                 await self.check_rate_limit(
                     context.agent_id,
                     max_requests=1,
-                    interval=59,  # TODO: tmp to 59, back to 240 later
+                    interval=15,
                 )
 
             # get since id from store

intentkit/skills/twitter/get_timeline.py

@@ -53,7 +53,7 @@ class TwitterGetTimeline(TwitterBaseTool):
             # Check rate limit only when not using OAuth
             if not twitter.use_key:
                 await self.check_rate_limit(
-                    context.agent_id, max_requests=3, interval=60 * 24
+                    context.agent_id, max_requests=1, interval=15
                 )
 
             # get since id from store

intentkit/skills/twitter/get_user_by_username.py

@@ -51,7 +51,7 @@ class TwitterGetUserByUsername(TwitterBaseTool):
             # Check rate limit only when not using OAuth
             if not twitter.use_key:
                 await self.check_rate_limit(
-                    context.agent_id, max_requests=3, interval=60 * 24
+                    context.agent_id, max_requests=5, interval=60 * 24
                 )
 
             user_data = await client.get_user(

intentkit/skills/twitter/get_user_tweets.py

@@ -67,7 +67,7 @@ class TwitterGetUserTweets(TwitterBaseTool):
             # Check rate limit only when not using OAuth
             if not twitter.use_key:
                 await self.check_rate_limit(
-                    context.agent_id, max_requests=3, interval=60 * 24
+                    context.agent_id, max_requests=1, interval=15
                 )
 
             # get since id from store

intentkit/skills/twitter/search_tweets.py

@@ -50,7 +50,7 @@ class TwitterSearchTweets(TwitterBaseTool):
             # Check rate limit only when not using OAuth
             if not twitter.use_key:
                 await self.check_rate_limit(
-                    context.agent_id, max_requests=3, interval=60 * 24
+                    context.agent_id, max_requests=1, interval=15
                 )
 
             # Get since_id from store to avoid duplicate results

{intentkit-0.6.7.dev7.dist-info → intentkit-0.6.7.dev9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: intentkit
-Version: 0.6.7.dev7
+Version: 0.6.7.dev9
 Summary: Intent-based AI Agent Platform - Core Package
 Project-URL: Homepage, https://github.com/crestal-network/intentkit
 Project-URL: Repository, https://github.com/crestal-network/intentkit