intentkit 0.6.7.dev7__tar.gz → 0.6.7.dev8__tar.gz

{intentkit-0.6.7.dev7 → intentkit-0.6.7.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: intentkit
-Version: 0.6.7.dev7
+Version: 0.6.7.dev8
 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

{intentkit-0.6.7.dev7 → intentkit-0.6.7.dev8}/__init__.py

@@ -3,7 +3,7 @@
 A powerful platform for building AI agents with blockchain and cryptocurrency capabilities.
 """
 
-__version__ = "0.6.7-dev7"
+__version__ = "0.6.7-dev8"
 __author__ = "hyacinthus"
 __email__ = "hyacinthus@gmail.com"
 

{intentkit-0.6.7.dev7 → intentkit-0.6.7.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "intentkit"
-version = "0.6.7-dev7"
+version = "0.6.7-dev8"
 description = "Intent-based AI Agent Platform - Core Package"
 authors = [{ name = "hyacinthus", email = "hyacinthus@gmail.com" }]
 requires-python = ">=3.12"

intentkit-0.6.7.dev8/skills/elfa/README.md

@@ -0,0 +1,152 @@
+# Elfa Skills - Social Media Intelligence
+
+Integration with [Elfa AI API v2](https://api.elfa.ai/v2) providing real-time social media data analysis and processing capabilities for crypto and stock market sentiment tracking.
+
+**Important: V2 API Changes**
+- **No Raw Content**: V2 API removes raw tweet content for platform compliance
+- **Sanitized Data**: Returns engagement metrics, timestamps, and account metadata only
+- **New Endpoints**: Updated endpoints with consistent response format
+- **Enhanced Pagination**: Different pagination patterns for search vs aggregation endpoints
+
+## Setup
+
+Add your Elfa API key to your environment:
+```bash
+ELFA_API_KEY=your_elfa_api_key_here
+```
+
+## Available Skills
+
+### 1. Get Trending Tokens (`get_trending_tokens`)
+
+Ranks the most discussed tokens based on smart mentions count for a given period, updated every 5 minutes.
+
+**Endpoint**: `v2/aggregations/trending-tokens` - Direct Migration
+
+**Example Prompts:**
+```
+"What are the trending crypto tokens in the last 24 hours?"
+"Get trending tokens with minimum 50 mentions in the past week"
+```
+
+**Parameters:**
+- `timeWindow`: "30m", "1h", "4h", "24h", "7d", "30d" (default: "7d")
+- `page`: Page number for pagination (default: 1)
+- `pageSize`: Number of items per page (default: 50)
+- `minMentions`: Minimum mentions required (default: 5)
+
+**V2 Changes:**
+- Same functionality and parameters
+- Enhanced response format with metadata
+- Uses page+pageSize pagination for aggregations
+
+---
+
+### 2. Get Top Mentions (`get_top_mentions`)
+
+Queries tweets mentioning a specific stock/crypto ticker, ranked by view count for market sentiment analysis.
+
+**Endpoint**: `v2/data/top-mentions` - Breaking Changes
+
+**Example Prompts:**
+```
+"Get the top mentions for Bitcoin in the last 24 hours"
+"Show me engagement metrics for tweets about $ETH today"
+```
+
+**Parameters:**
+- `ticker`: Stock/crypto symbol (e.g., "BTC", "$ETH", "AAPL") - required
+- `timeWindow`: "1h", "24h", "7d" (default: "1h")
+- `page`: Page number for pagination (default: 1)
+- `pageSize`: Number of items per page (default: 10)
+
+**V2 Changes:**
+- **Removed**: Raw tweet content/text
+- **Removed**: `includeAccountDetails` parameter (always included)
+- **Preserved**: Engagement metrics (view_count, like_count, etc.)
+- **Preserved**: Account information and verification status
+- **Enhanced**: Account tags (e.g., "smart" accounts)
+
+---
+
+### 3. Search Mentions (`search_mentions`)
+
+Searches tweets mentioning up to 5 keywords or from specific accounts with sanitized engagement data.
+
+**Endpoint**: `v2/data/keyword-mentions` - Breaking Changes
+
+**Example Prompts:**
+```
+"Search for engagement metrics of tweets mentioning 'DeFi, NFT, blockchain'"
+"Find tweets from account 'elonmusk' about cryptocurrency"
+```
+
+**Parameters:**
+- `keywords`: Up to 5 keywords (comma-separated, phrases accepted) - optional if accountName provided
+- `accountName`: Account username to filter by - optional if keywords provided  
+- `timeWindow`: Time window for search (default: "7d")
+- `limit`: Number of results to return, max 30 (default: 20)
+- `searchType`: Type of search - "and" or "or" (default: "or")
+- `cursor`: Cursor for pagination (optional)
+
+**V2 Changes:**
+- **Removed**: Raw tweet content/text
+- **Preserved**: Engagement metrics and sentiment analysis
+- **Enhanced**: Account filtering with `accountName` parameter
+- **Updated**: Uses limit+cursor pagination for search
+- **Added**: Account tags and metadata
+
+---
+
+### 4. Get Smart Stats (`get_smart_stats`)
+
+Retrieves key social media metrics for a specific username including engagement ratios and smart following count.
+
+**Endpoint**: `v2/account/smart-stats` - Direct Migration
+
+**Example Prompts:**
+```
+"Get smart stats for @elonmusk"
+"Analyze the social metrics for username 'VitalikButerin'"
+```
+
+**Parameters:**
+- `username`: Twitter username (with or without @) - required
+
+**V2 Changes:**
+- Same functionality and parameters
+- Consistent response format with metadata
+
+## V2 Response Format
+
+All V2 endpoints return a consistent format:
+
+```json
+{
+  "success": boolean,
+  "data": [...], // Array or object with actual data
+  "metadata": {  // Pagination and additional info
+    "total": number,
+    "page": number,
+    "pageSize": number,
+    "cursor": "string" // For search endpoints
+  }
+}
+```
+
+## Migration Notes
+
+### What's Removed in V2:
+- Raw tweet content/text (compliance requirement)
+- Direct access to tweet body/message content
+- `includeAccountDetails` parameter (always included)
+- **Deprecated**: `get_mentions` skill (no v2 equivalent)
+
+### What's Preserved:
+- Engagement metrics (likes, views, reposts, replies)
+- Account information and verification status
+- Timestamps and metadata
+- Sentiment analysis
+- Core functionality for trend analysis
+
+

{intentkit-0.6.7.dev7 → intentkit-0.6.7.dev8}/skills/elfa/__init__.py

@@ -7,7 +7,6 @@ from intentkit.abstracts.skill import SkillStoreABC
 from intentkit.skills.base import SkillConfig, SkillState
 from intentkit.skills.elfa.base import ElfaBaseTool
 from intentkit.skills.elfa.mention import (
-    ElfaGetMentions,
     ElfaGetTopMentions,
     ElfaSearchMentions,
 )
@@ -21,7 +20,6 @@ logger = logging.getLogger(__name__)
 
 
 class SkillStates(TypedDict):
-    get_mentions: SkillState
     get_top_mentions: SkillState
     search_mentions: SkillState
     get_trending_tokens: SkillState
@@ -83,14 +81,7 @@ def get_elfa_skill(
         The requested Elfa skill
     """
 
-    if name == "get_mentions":
-        if name not in _cache:
-            _cache[name] = ElfaGetMentions(
-                skill_store=store,
-            )
-        return _cache[name]
-
-    elif name == "get_top_mentions":
+    if name == "get_top_mentions":
         if name not in _cache:
             _cache[name] = ElfaGetTopMentions(
                 skill_store=store,

{intentkit-0.6.7.dev7 → intentkit-0.6.7.dev8}/skills/elfa/base.py

@@ -5,7 +5,7 @@ from pydantic import BaseModel, Field
 from intentkit.abstracts.skill import SkillStoreABC
 from intentkit.skills.base import IntentKitSkill, SkillContext
 
-base_url = "https://api.elfa.ai"
+base_url = "https://api.elfa.ai/v2"
 
 
 class ElfaBaseTool(IntentKitSkill):

intentkit-0.6.7.dev8/skills/elfa/mention.py

@@ -0,0 +1,223 @@
+"""Mention-related skills for Elfa AI API."""
+
+from typing import Any, Dict, List, Optional, Type
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from .base import ElfaBaseTool
+from .utils import MentionData, make_elfa_request
+
+
+class ElfaGetTopMentionsInput(BaseModel):
+    """Input parameters for top mentions."""
+
+    ticker: str = Field(description="Stock ticker symbol (e.g., ETH, $ETH, BTC, $BTC)")
+    timeWindow: Optional[str] = Field(
+        "1h", description="Time window (e.g., '1h', '24h', '7d')"
+    )
+    page: Optional[int] = Field(1, description="Page number for pagination")
+    pageSize: Optional[int] = Field(10, description="Number of items per page")
+
+
+class ElfaGetTopMentionsOutput(BaseModel):
+    """Output structure for top mentions response."""
+
+    success: bool
+    data: Optional[List[MentionData]] = Field(None, description="List of top mentions")
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Response metadata")
+
+
+class ElfaGetTopMentions(ElfaBaseTool):
+    """
+    Get top mentions for a specific ticker.
+
+    This tool uses the Elfa API to query tweets mentioning a specific stock ticker.
+    The tweets are ranked by view count, providing insight into the most visible and
+    potentially influential discussions surrounding the stock. Results are updated hourly.
+
+    Use Cases:
+    - Real-time sentiment analysis: Track changes in public opinion about a stock
+    - News monitoring: Identify trending news and discussions related to a specific ticker
+    - Investor insights: Monitor conversations and opinions of investors and traders
+    """
+
+    name: str = "elfa_get_top_mentions"
+    description: str = """Get top mentions for a specific ticker symbol ranked by view count. 
+    Updated hourly. Returns engagement metrics and account information for market sentiment analysis.
+    
+    Use this to track public opinion, identify trending news, and monitor investor discussions."""
+    args_schema: Type[BaseModel] = ElfaGetTopMentionsInput
+
+    async def _arun(
+        self,
+        ticker: str,
+        timeWindow: str = "1h",
+        page: int = 1,
+        pageSize: int = 10,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> ElfaGetTopMentionsOutput:
+        """
+        Execute the top mentions request.
+
+        Args:
+            ticker: Stock ticker symbol
+            timeWindow: Time window for mentions (default: 1h)
+            page: Page number for pagination (default: 1)
+            pageSize: Items per page (default: 10)
+            config: LangChain runnable configuration
+            **kwargs: Additional parameters
+
+        Returns:
+            ElfaGetTopMentionsOutput: Structured response with top mentions
+
+        Raises:
+            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)
+
+        # Prepare parameters according to API spec
+        params = {
+            "ticker": ticker,
+            "timeWindow": timeWindow,
+            "page": page,
+            "pageSize": pageSize,
+        }
+
+        # Make API request using shared utility
+        response = await make_elfa_request(
+            endpoint="data/top-mentions", api_key=api_key, params=params
+        )
+
+        # Parse response data into MentionData objects
+        mentions = []
+        if response.data and isinstance(response.data, list):
+            mentions = [MentionData(**item) for item in response.data]
+
+        return ElfaGetTopMentionsOutput(
+            success=response.success, data=mentions, metadata=response.metadata
+        )
+
+
+class ElfaSearchMentionsInput(BaseModel):
+    """Input parameters for search mentions."""
+
+    keywords: Optional[str] = Field(
+        None,
+        description="Up to 5 keywords to search for, separated by commas. Phrases accepted",
+    )
+    accountName: Optional[str] = Field(
+        None,
+        description="Account username to filter by (optional if keywords provided)",
+    )
+    timeWindow: Optional[str] = Field("7d", description="Time window for search")
+    limit: Optional[int] = Field(20, description="Number of results to return (max 30)")
+    searchType: Optional[str] = Field(
+        "or", description="Type of search ('and' or 'or')"
+    )
+    cursor: Optional[str] = Field(None, description="Cursor for pagination")
+
+
+class ElfaSearchMentionsOutput(BaseModel):
+    """Output structure for search mentions response."""
+
+    success: bool
+    data: Optional[List[MentionData]] = Field(
+        None, description="List of matching mentions"
+    )
+    metadata: Optional[Dict[str, Any]] = Field(
+        None, description="Response metadata with cursor"
+    )
+
+
+class ElfaSearchMentions(ElfaBaseTool):
+    """
+    Search mentions by keywords or account name.
+
+    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 (updated every 5 minutes) or access historical data.
+    Returns sanitized engagement metrics and sentiment data.
+
+    Use Cases:
+    - Market research: Track conversations and sentiment around specific products or industries
+    - Brand monitoring: Monitor mentions of your brand and identify potential PR issues
+    - Public opinion tracking: Analyze public opinion on various topics
+    - Competitive analysis: See what people are saying about your competitors
+    """
+
+    name: str = "elfa_search_mentions"
+    description: str = """Search tweets by keywords or account name with engagement data and sentiment analysis. 
+    Updated every 5 minutes. Access 30 days of recent data or historical archives.
+    
+    Use this for market research, brand monitoring, opinion tracking, and competitive analysis."""
+    args_schema: Type[BaseModel] = ElfaSearchMentionsInput
+
+    async def _arun(
+        self,
+        keywords: Optional[str] = None,
+        accountName: Optional[str] = None,
+        timeWindow: str = "7d",
+        limit: int = 20,
+        searchType: str = "or",
+        cursor: Optional[str] = None,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> ElfaSearchMentionsOutput:
+        """
+        Execute the search mentions request.
+
+        Args:
+            keywords: Keywords to search for (optional if accountName provided)
+            accountName: Account username to filter by (optional if keywords provided)
+            timeWindow: Time window for search (default: 7d)
+            limit: Number of results to return (default: 20, max 30)
+            searchType: Type of search - 'and' or 'or' (default: 'or')
+            cursor: Pagination cursor (optional)
+            config: LangChain runnable configuration
+            **kwargs: Additional parameters
+
+        Returns:
+            ElfaSearchMentionsOutput: Structured response with matching mentions
+
+        Raises:
+            ValueError: If API key is not found or neither keywords nor accountName provided
+            ToolException: If there's an error with the API request
+        """
+        context = self.context_from_config(config)
+        api_key = self.get_api_key(context)
+
+        # Validate that at least one search criteria is provided
+        if not keywords and not accountName:
+            raise ValueError("Either keywords or accountName must be provided")
+
+        # Prepare parameters according to API spec
+        params = {
+            "timeWindow": timeWindow,
+            "limit": min(limit, 30),  # API max is 30
+            "searchType": searchType,
+        }
+
+        # Add optional parameters
+        if keywords:
+            params["keywords"] = keywords
+        if accountName:
+            params["accountName"] = accountName
+        if cursor:
+            params["cursor"] = cursor
+
+        # Make API request using shared utility
+        response = await make_elfa_request(
+            endpoint="data/keyword-mentions", api_key=api_key, params=params
+        )
+
+        # Parse response data into MentionData objects
+        mentions = []
+        if response.data and isinstance(response.data, list):
+            mentions = [MentionData(**item) for item in response.data]
+
+        return ElfaSearchMentionsOutput(
+            success=response.success, data=mentions, metadata=response.metadata
+        )

{intentkit-0.6.7.dev7 → intentkit-0.6.7.dev8}/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-0.6.7.dev8/skills/elfa/stats.py

@@ -0,0 +1,85 @@
+"""Smart stats skill for Elfa AI API."""
+
+from typing import Any, Dict, Optional, Type
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from .base import ElfaBaseTool
+from .utils import SmartStatsData, make_elfa_request
+
+
+class ElfaGetSmartStatsInput(BaseModel):
+    """Input parameters for smart stats."""
+
+    username: str = Field(description="Account username to get stats for")
+
+
+class ElfaGetSmartStatsOutput(BaseModel):
+    """Output structure for smart stats response."""
+
+    success: bool
+    data: Optional[SmartStatsData] = Field(None, description="Smart stats data")
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Response metadata")
+
+
+class ElfaGetSmartStats(ElfaBaseTool):
+    """
+    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 = """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 = None, **kwargs
+    ) -> ElfaGetSmartStatsOutput:
+        """
+        Execute the smart stats request.
+
+        Args:
+            username: The username to check stats for
+            config: LangChain runnable configuration
+            **kwargs: Additional parameters
+
+        Returns:
+            ElfaGetSmartStatsOutput: Structured response with smart stats
+
+        Raises:
+            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)
+
+        # 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-0.6.7.dev8/skills/elfa/tokens.py

@@ -0,0 +1,122 @@
+"""Trending tokens skill for Elfa AI API."""
+
+from typing import Any, Dict, List, Optional, Type
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from .base import ElfaBaseTool
+from .utils import make_elfa_request
+
+
+class ElfaGetTrendingTokensInput(BaseModel):
+    """Input parameters for trending tokens."""
+
+    timeWindow: Optional[str] = Field(
+        "7d",
+        description="Time window for trending analysis (e.g., '30m', '1h', '4h', '24h', '7d', '30d')",
+    )
+    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 TrendingToken(BaseModel):
+    """Individual trending token data."""
+
+    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: Optional[List[TrendingToken]] = Field(
+        None, description="List of trending tokens"
+    )
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Response metadata")
+
+
+class ElfaGetTrendingTokens(ElfaBaseTool):
+    """
+    Get trending tokens based on smart mentions count.
+
+    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
+    """
+
+    name: str = "elfa_get_trending_tokens"
+    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 = "7d",
+        page: int = 1,
+        pageSize: int = 50,
+        minMentions: int = 5,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> ElfaGetTrendingTokensOutput:
+        """
+        Execute the trending tokens request.
+
+        Args:
+            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:
+            ElfaGetTrendingTokensOutput: Structured response with trending tokens
+
+        Raises:
+            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)
+
+        # Prepare parameters according to API spec
+        params = {
+            "timeWindow": timeWindow,
+            "page": page,
+            "pageSize": pageSize,
+            "minMentions": minMentions,
+        }
+
+        # 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
+        )