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

intentkit/skills/elfa/README.md

@@ -0,0 +1,100 @@
+# Elfa Skills - Social Media Intelligence
+
+Integration with [Elfa AI API](https://api.elfa.ai) providing real-time social media data analysis and processing capabilities for crypto and stock market sentiment tracking.
+
+## 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.
+
+**Example Prompts:**
+```
+"What are the trending crypto tokens in the last 24 hours?"
+"Show me the most discussed tokens today with at least 10 mentions"
+"Get trending tokens for the past week"
+"Which tokens are gaining attention on social media?"
+```
+
+**Parameters:**
+- `timeWindow`: "1h", "24h", "7d" (default: "24h")
+- `minMentions`: Minimum mentions required (default: 5)
+
+---
+
+### 2. Get Top Mentions (`get_top_mentions`)
+
+Queries tweets mentioning a specific stock/crypto ticker, ranked by view count for market sentiment analysis.
+
+**Example Prompts:**
+```
+"Get the top mentions for Bitcoin in the last 24 hours"
+"Show me the most viewed tweets about $ETH today"
+"What are people saying about TSLA stock on Twitter?"
+"Find viral tweets mentioning $SOL with account details"
+```
+
+**Parameters:**
+- `ticker`: Stock/crypto symbol (e.g., "BTC", "$ETH", "AAPL")
+- `timeWindow`: "24h", "7d" (default: "24h") 
+- `includeAccountDetails`: Include account info (default: false)
+
+---
+
+### 3. Search Mentions (`search_mentions`)
+
+Searches tweets mentioning up to 5 keywords. Can access 30 days of recent data (updated every 5 minutes) or 6 months of historical data.
+
+**Example Prompts:**
+```
+"Search for tweets mentioning 'DeFi, NFT, blockchain'"
+"Find recent mentions of 'AI, artificial intelligence, machine learning'"
+"Search historical tweets about 'bitcoin, cryptocurrency' from last month"
+"Look for discussions about 'climate change, renewable energy'"
+```
+
+**Parameters:**
+- `keywords`: Up to 5 keywords (comma-separated, phrases accepted)
+- `from_`: Start timestamp (default: 24 hours ago)
+- `to`: End timestamp (default: yesterday)
+
+---
+
+### 4. Get Mentions (`get_mentions`)
+
+Retrieves hourly-updated tweets from "smart accounts" (influential accounts) that have received at least 10 interactions.
+
+**Example Prompts:**
+```
+"Get the latest mentions from smart accounts"
+"Show me recent tweets from influential crypto accounts"
+"What are the smart accounts talking about?"
+"Get the latest buzz from verified influencers"
+```
+
+**Parameters:** None (uses default limits)
+
+---
+
+### 5. Get Smart Stats (`get_smart_stats`)
+
+Retrieves key social media metrics for a specific username including engagement ratios and smart following count.
+
+**Example Prompts:**
+```
+"Get smart stats for @elonmusk"
+"Analyze the social metrics for username 'VitalikButerin'"
+"Show me engagement stats for @cz_binance"
+"What are the social media metrics for @jack?"
+```
+
+**Parameters:**
+- `username`: Twitter username (with or without @)
+

intentkit/skills/elfa/__init__.py

@@ -0,0 +1,123 @@
+"""Elfa skills."""
+
+import logging
+from typing import NotRequired, TypedDict
+
+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,
+)
+from intentkit.skills.elfa.stats import ElfaGetSmartStats
+from intentkit.skills.elfa.tokens import ElfaGetTrendingTokens
+
+# Cache skills at the system level, because they are stateless
+_cache: dict[str, ElfaBaseTool] = {}
+
+logger = logging.getLogger(__name__)
+
+
+class SkillStates(TypedDict):
+    get_mentions: SkillState
+    get_top_mentions: SkillState
+    search_mentions: SkillState
+    get_trending_tokens: SkillState
+    get_smart_stats: SkillState
+
+
+class Config(SkillConfig):
+    """Configuration for Elfa skills."""
+
+    states: SkillStates
+    api_key: NotRequired[str]
+
+
+async def get_skills(
+    config: "Config",
+    is_private: bool,
+    store: SkillStoreABC,
+    **_,
+) -> list[ElfaBaseTool]:
+    """Get all Elfa skills.
+
+    Args:
+        config: The configuration for Elfa skills.
+        is_private: Whether to include private skills.
+        store: The skill store for persisting data.
+
+    Returns:
+        A list of Elfa 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_elfa_skill(name, store)
+        if skill:
+            result.append(skill)
+    return result
+
+
+def get_elfa_skill(
+    name: str,
+    store: SkillStoreABC,
+) -> ElfaBaseTool:
+    """Get an Elfa skill by name.
+
+    Args:
+        name: The name of the skill to get
+        store: The skill store for persisting data
+
+    Returns:
+        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 not in _cache:
+            _cache[name] = ElfaGetTopMentions(
+                skill_store=store,
+            )
+        return _cache[name]
+
+    elif name == "search_mentions":
+        if name not in _cache:
+            _cache[name] = ElfaSearchMentions(
+                skill_store=store,
+            )
+        return _cache[name]
+
+    elif name == "get_trending_tokens":
+        if name not in _cache:
+            _cache[name] = ElfaGetTrendingTokens(
+                skill_store=store,
+            )
+        return _cache[name]
+
+    elif name == "get_smart_stats":
+        if name not in _cache:
+            _cache[name] = ElfaGetSmartStats(
+                skill_store=store,
+            )
+        return _cache[name]
+
+    else:
+        logger.warning(f"Unknown Elfa skill: {name}")
+        return None

intentkit/skills/elfa/base.py

@@ -0,0 +1,28 @@
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import IntentKitSkill, SkillContext
+
+base_url = "https://api.elfa.ai"
+
+
+class ElfaBaseTool(IntentKitSkill):
+    """Base class for Elfa tools."""
+
+    name: str = Field(description="The name of the tool")
+    description: str = Field(description="A description of what the tool does")
+    args_schema: Type[BaseModel]
+    skill_store: SkillStoreABC = Field(
+        description="The skill store for persisting data"
+    )
+
+    def get_api_key(self, context: SkillContext) -> Optional[str]:
+        if "api_key" in context.config and context.config["api_key"]:
+            return context.config["api_key"]
+        return self.skill_store.get_system_config("elfa_api_key")
+
+    @property
+    def category(self) -> str:
+        return "elfa"