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

intentkit/skills/dune_analytics/__init__.py

@@ -0,0 +1,103 @@
+"""Dune Analytics skill module for IntentKit.
+
+Loads and initializes skills for fetching data from Dune Analytics API.
+"""
+
+import logging
+from typing import Dict, List, Optional, TypedDict
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import SkillConfig, SkillState
+from intentkit.skills.dune_analytics.base import DuneBaseTool
+
+logger = logging.getLogger(__name__)
+
+# Cache for skill instances
+_skill_cache: Dict[str, DuneBaseTool] = {}
+
+
+class SkillStates(TypedDict):
+    """Type definition for Dune Analytics skill states."""
+
+    fetch_nation_metrics: SkillState
+    fetch_kol_buys: SkillState
+
+
+class Config(SkillConfig):
+    """Configuration schema for Dune Analytics skills."""
+
+    states: SkillStates
+    api_key: str
+
+
+async def get_skills(
+    config: Config,
+    is_private: bool,
+    store: SkillStoreABC,
+    **kwargs,
+) -> List[DuneBaseTool]:
+    """Load Dune Analytics skills based on configuration.
+
+    Args:
+        config: Skill configuration with states and API key.
+        is_private: Whether the context is private (affects skill visibility).
+        store: Skill store for accessing other skills.
+        **kwargs: Additional keyword arguments.
+
+    Returns:
+        List of loaded Dune Analytics skill instances.
+    """
+    logger.info("Loading Dune Analytics skills")
+    available_skills = []
+
+    for skill_name, state in config["states"].items():
+        logger.debug("Checking skill: %s, state: %s", skill_name, state)
+        if state == "disabled":
+            continue
+        if state == "public" or (state == "private" and is_private):
+            available_skills.append(skill_name)
+
+    loaded_skills = []
+    for name in available_skills:
+        skill = get_dune_skill(name, store)
+        if skill:
+            logger.info("Successfully loaded skill: %s", name)
+            loaded_skills.append(skill)
+        else:
+            logger.warning("Failed to load skill: %s", name)
+
+    return loaded_skills
+
+
+def get_dune_skill(name: str, store: SkillStoreABC) -> Optional[DuneBaseTool]:
+    """Retrieve a Dune Analytics skill instance by name.
+
+    Args:
+        name: Name of the skill (e.g., 'fetch_nation_metrics', 'fetch_kol_buys').
+        store: Skill store for accessing other skills.
+
+    Returns:
+        Dune Analytics skill instance or None if not found or import fails.
+    """
+    if name in _skill_cache:
+        logger.debug("Retrieved cached skill: %s", name)
+        return _skill_cache[name]
+
+    try:
+        if name == "fetch_nation_metrics":
+            from .fetch_nation_metrics import FetchNationMetrics
+
+            _skill_cache[name] = FetchNationMetrics(skill_store=store)
+        elif name == "fetch_kol_buys":
+            from .fetch_kol_buys import FetchKOLBuys
+
+            _skill_cache[name] = FetchKOLBuys(skill_store=store)
+        else:
+            logger.warning("Unknown Dune Analytics skill: %s", name)
+            return None
+
+        logger.debug("Cached new skill instance: %s", name)
+        return _skill_cache[name]
+    except ImportError as e:
+        logger.error("Failed to import skill %s: %s", name, e)
+        return None

intentkit/skills/dune_analytics/base.py

@@ -0,0 +1,46 @@
+"""Base module for Dune Analytics skills.
+
+Provides shared functionality for interacting with the Dune Analytics API.
+"""
+
+from typing import Type
+
+from langchain.tools.base import ToolException
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import IntentKitSkill, SkillContext
+
+
+class DuneBaseTool(IntentKitSkill):
+    """Base class for Dune Analytics skills.
+
+    Offers common functionality like API key retrieval and Dune API interaction.
+    """
+
+    name: str = Field(description="Tool name")
+    description: str = Field(description="Tool description")
+    args_schema: Type[BaseModel]
+    skill_store: SkillStoreABC = Field(description="Skill store for data persistence")
+
+    def get_api_key(self, context: SkillContext) -> str:
+        """Retrieve the Dune Analytics API key from context.
+
+        Args:
+            context: Skill context containing configuration.
+
+        Returns:
+            API key string.
+
+        Raises:
+            ToolException: If the API key is not found.
+        """
+        api_key = context.config.get("api_key")
+        if not api_key:
+            raise ToolException("Dune API key not found in context.config['api_key']")
+        return api_key
+
+    @property
+    def category(self) -> str:
+        """Category of the skill."""
+        return "dune_analytics"

intentkit/skills/dune_analytics/fetch_kol_buys.py

@@ -0,0 +1,128 @@
+"""Skill to fetch KOL memecoin buys on Solana from Dune Analytics API.
+
+Uses query ID 4832844 to retrieve a list of KOL buy transactions.
+"""
+
+from typing import Any, Dict, Type
+
+import httpx
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.dune_analytics.base import DuneBaseTool
+
+BASE_URL = "https://api.dune.com/api/v1/query"
+KOL_BUYS_QUERY_ID = 4832844
+
+
+class KOLBuysInput(BaseModel):
+    """Input schema for fetching KOL memecoin buys."""
+
+    limit: int = Field(
+        default=10,
+        description="Maximum number of buy transactions to fetch (default 10).",
+        ge=1,
+    )
+
+
+class KOLBuyData(BaseModel):
+    """Data model for KOL buy results."""
+
+    data: Dict[str, Any] = Field(description="KOL buy data from Dune API")
+    error: str = Field(default="", description="Error message if fetch failed")
+
+
+class KOLBuysOutput(BaseModel):
+    """Output schema for KOL memecoin buys."""
+
+    buys: KOLBuyData = Field(description="KOL buy transaction data")
+    summary: str = Field(description="Summary of fetched data")
+
+
+class FetchKOLBuys(DuneBaseTool):
+    """Skill to fetch KOL memecoin buys on Solana from Dune Analytics API."""
+
+    name: str = "dune_fetch_kol_buys"
+    description: str = (
+        "Fetches a list of KOL memecoin buy transactions on Solana from Dune Analytics API using query ID 4832844. "
+        "Supports a configurable limit for the number of results. Handles rate limits with retries."
+    )
+    args_schema: Type[BaseModel] = KOLBuysInput
+    skill_store: SkillStoreABC = Field(description="Skill store for data persistence")
+
+    @retry(
+        stop=stop_after_attempt(3), wait=wait_exponential(multiplier=5, min=5, max=60)
+    )
+    async def fetch_data(
+        self, query_id: int, api_key: str, limit: int = 10
+    ) -> Dict[str, Any]:
+        """Fetch data for a specific Dune query.
+
+        Args:
+            query_id: Dune query ID.
+            api_key: Dune API key.
+            limit: Maximum number of results (default 10).
+
+        Returns:
+            Dictionary of query results.
+
+        Raises:
+            ToolException: If the API request fails.
+        """
+        from langchain.tools.base import ToolException
+
+        url = f"{BASE_URL}/{query_id}/results?limit={limit}"
+        headers = {"X-Dune-API-Key": api_key}
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(url, headers=headers, timeout=10)
+                response.raise_for_status()
+                return response.json().get("result", {})
+            except (httpx.RequestError, httpx.HTTPStatusError) as e:
+                raise ToolException(f"Error fetching data from Dune API: {e}")
+
+    async def _arun(
+        self,
+        limit: int = 10,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> str:
+        """Fetch KOL memecoin buys asynchronously and return formatted output.
+
+        Args:
+            limit: Maximum number of buy transactions to fetch (default 10).
+            config: Runnable configuration.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            Formatted string with KOL buy transactions or error message.
+        """
+        import logging
+
+        logger = logging.getLogger(__name__)
+        context = self.context_from_config(config)
+        api_key = self.get_api_key(context)
+
+        try:
+            data = await self.fetch_data(KOL_BUYS_QUERY_ID, api_key, limit)
+            rows = data.get("rows", [])
+            if not rows:
+                return "No KOL buy transactions found."
+
+            output = f"Fetched {len(rows)} KOL memecoin buy transactions:\n"
+            for row in rows:
+                output += (
+                    f"- {row['kol_with_link']} bought {row['token_with_chart']} "
+                    f"(${row['amount_usd']:.2f}) at {row['buy_time']}\n"
+                )
+            return output.strip()
+        except Exception as e:
+            error_msg = f"Error fetching KOL memecoin buys: {str(e)}"
+            logger.warning(error_msg)
+            return error_msg
+
+    def _run(self, question: str):
+        raise NotImplementedError("Use _arun for async execution")

intentkit/skills/dune_analytics/fetch_nation_metrics.py

@@ -0,0 +1,237 @@
+"""Skill to fetch Crestal Nation metrics from Dune Analytics API.
+
+Supports predefined metrics (e.g., total_users, unique_ai_citizens) or direct query IDs.
+"""
+
+import difflib
+import re
+from typing import Any, Dict, Type
+
+import httpx
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.dune_analytics.base import DuneBaseTool
+
+SUPPORTED_QUERIES = {
+    "total_users": 4858003,
+    "weekly_active_users": 4867200,
+    "unique_ai_citizens": 4857629,
+    "unique_creators": 4844506,
+    "ai_citizens_over_time": 4857629,
+    "chat_messages_over_time": 4857870,
+    "onchain_transactions": 4859895,
+    "total_chat_messages": 4857870,
+    "daily_skill_executions": 4861785,
+    "goods_services": 4859895,
+    "agent_tvl": 4859887,
+    "citizen_market_cap": 4859887,
+}
+QUERY_ALIASES = {
+    "agents": "unique_ai_citizens",
+    "citizens": "unique_ai_citizens",
+    "market_cap": "citizen_market_cap",
+    "nation_market_cap": "citizen_market_cap",
+    "number_of_agents": "unique_ai_citizens",
+    "number_of_citizens": "unique_ai_citizens",
+    "ai_citizens": "unique_ai_citizens",
+    "users": "total_users",
+    "active_users": "weekly_active_users",
+    "creators": "unique_creators",
+    "transactions": "onchain_transactions",
+    "messages": "total_chat_messages",
+    "skill_executions": "daily_skill_executions",
+    "tvl": "agent_tvl",
+}
+BASE_URL = "https://api.dune.com/api/v1/query"
+
+
+class NationMetricsInput(BaseModel):
+    """Input schema for fetching Crestal Nation metrics."""
+
+    metric: str = Field(
+        default="",
+        description="Metric name (e.g., total_users, agents) or query ID (e.g., 4858003). Empty for all configured metrics.",
+    )
+    limit: int = Field(
+        default=1000, description="Maximum number of results to fetch (default 1000)."
+    )
+
+
+class MetricData(BaseModel):
+    """Data model for a single metric result."""
+
+    metric: str = Field(description="Metric name or query ID")
+    data: Dict[str, Any] = Field(description="Metric data from Dune API")
+    error: str = Field(default="", description="Error message if fetch failed")
+
+
+class NationMetricsOutput(BaseModel):
+    """Output schema for Crestal Nation metrics."""
+
+    metrics: Dict[str, MetricData] = Field(
+        description="Dictionary of metric names or query IDs to their data"
+    )
+    summary: str = Field(description="Summary of fetched metrics")
+
+
+class FetchNationMetrics(DuneBaseTool):
+    """Skill to fetch Crestal Nation metrics from Dune Analytics API."""
+
+    name: str = "dune_fetch_nation_metrics"
+    description: str = (
+        "Fetches Crestal Nation metrics (e.g., total_users, agents/citizens, market_cap) from Dune Analytics API. "
+        "Supports predefined metrics, direct query IDs, or all configured metrics if none specified. "
+        "Handles rate limits with retries."
+    )
+    args_schema: Type[BaseModel] = NationMetricsInput
+    skill_store: SkillStoreABC = Field(description="Skill store for data persistence")
+
+    def normalize_metric(self, metric: str) -> str:
+        """Normalize a metric string for matching.
+
+        Args:
+            metric: Raw metric string from input.
+
+        Returns:
+            Normalized metric string (lowercase, underscores, no punctuation).
+        """
+        if not metric:
+            return ""
+        metric = re.sub(r"[^\w\s]", "", metric.lower()).replace(" ", "_")
+        return re.sub(r"_+", "_", metric).strip("_")
+
+    def find_closest_metrics(self, metric: str, max_suggestions: int = 3) -> list[str]:
+        """Find the closest matching metrics using fuzzy matching.
+
+        Args:
+            metric: Input metric to match against.
+            max_suggestions: Maximum number of suggestions to return.
+
+        Returns:
+            List of closest metric names.
+        """
+        all_metrics = list(SUPPORTED_QUERIES.keys()) + list(QUERY_ALIASES.keys())
+        if not metric or not all_metrics:
+            return []
+        return difflib.get_close_matches(
+            metric, all_metrics, n=max_suggestions, cutoff=0.6
+        )
+
+    @retry(
+        stop=stop_after_attempt(3), wait=wait_exponential(multiplier=5, min=5, max=60)
+    )
+    async def fetch_data(
+        self, query_id: int, api_key: str, limit: int = 1000
+    ) -> Dict[str, Any]:
+        """Fetch data for a specific Dune query.
+
+        Args:
+            query_id: Dune query ID.
+            api_key: Dune API key.
+            limit: Maximum number of results (default 1000).
+
+        Returns:
+            Dictionary of query results.
+
+        Raises:
+            ToolException: If the API request fails.
+        """
+        from langchain.tools.base import ToolException
+
+        url = f"{BASE_URL}/{query_id}/results?limit={limit}"
+        headers = {"X-Dune-API-Key": api_key}
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(url, headers=headers, timeout=10)
+                response.raise_for_status()
+                return response.json().get("result", {})
+            except (httpx.RequestError, httpx.HTTPStatusError) as e:
+                raise ToolException(f"Error fetching data from Dune API: {e}")
+
+    async def _arun(
+        self,
+        metric: str = "",
+        limit: int = 1000,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> NationMetricsOutput:
+        """Fetch Crestal Nation metrics asynchronously.
+
+        Args:
+            metric: Metric name (e.g., total_users) or query ID (e.g., 4858003). Empty for all configured metrics.
+            limit: Maximum number of results (default 1000).
+            config: Runnable configuration.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            NationMetricsOutput with metric data and summary.
+        """
+        import logging
+
+        logger = logging.getLogger(__name__)
+        context = self.context_from_config(config)
+        api_key = self.get_api_key(context)
+
+        metric = self.normalize_metric(metric)
+        metric = QUERY_ALIASES.get(metric, metric)
+
+        results = {}
+        metrics_to_fetch = {}
+
+        try:
+            query_id = int(metric)
+            metrics_to_fetch[str(query_id)] = query_id
+        except (ValueError, TypeError):
+            metrics_to_fetch = (
+                SUPPORTED_QUERIES
+                if not metric
+                else (
+                    {metric: SUPPORTED_QUERIES[metric]}
+                    if metric in SUPPORTED_QUERIES
+                    else {}
+                )
+            )
+
+        if not metrics_to_fetch:
+            closest_metrics = self.find_closest_metrics(metric)
+            supported = ", ".join(SUPPORTED_QUERIES.keys())
+            suggestions = (
+                f" Did you mean: {', '.join(closest_metrics)}?"
+                if closest_metrics
+                else ""
+            )
+            logger.warning(
+                "Unrecognized metric or query ID: %s. Suggested: %s",
+                metric,
+                closest_metrics,
+            )
+            return NationMetricsOutput(
+                metrics={},
+                summary=(
+                    f"Invalid metric or query ID: {metric}. Supported metrics include: {supported}.{suggestions} "
+                    "Try 'fetch nation metrics total_users' or a valid query ID, or submit a feature request at "
+                    "https://github.com/crestalnetwork/intentkit."
+                ),
+            )
+
+        for metric_name, query_id in metrics_to_fetch.items():
+            try:
+                data = await self.fetch_data(query_id, api_key, limit)
+                results[metric_name] = MetricData(metric=metric_name, data=data)
+            except Exception as e:
+                results[metric_name] = MetricData(
+                    metric=metric_name, data={}, error=str(e)
+                )
+
+        summary = f"Fetched data for {len([m for m in results.values() if not m.error])}/{len(metrics_to_fetch)} metrics."
+        if any(m.error for m in results.values()):
+            summary += f" Errors occurred for: {', '.join(m.metric for m in results.values() if m.error)}."
+
+        return NationMetricsOutput(metrics=results, summary=summary)
+
+    def _run(self, question: str):
+        raise NotImplementedError("Use _arun for async execution")

intentkit/skills/dune_analytics/schema.json

@@ -0,0 +1,99 @@
+{
+  "title": "Dune Analytics",
+  "description": "Dune Analytics skills to fetch data from Dune Analytics API.",
+  "x-icon": "https://ai.service.crestal.dev/skills/dune_analytics/dune.png",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enabled",
+      "description": "Whether this skill is enabled",
+      "default": false
+    },
+    "states": {
+      "title": "Skill States",
+      "type": "object",
+      "properties": {
+        "fetch_nation_metrics": {
+          "type": "string",
+          "title": "Fetch Crestal Nation Metrics",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Fetches Crestal Nation metrics (e.g., total_users, agents/citizens, market_cap) from Dune Analytics API.",
+          "default": "disabled"
+        },
+        "fetch_kol_buys": {
+          "type": "string",
+          "title": "Fetch KOL Memecoin Buys",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Fetches a list of KOL memecoin buy transactions on Solana from Dune Analytics API.",
+          "default": "disabled"
+        }
+      }
+    },
+    "api_key_provider": {
+      "type": "string",
+      "title": "API Key Provider",
+      "description": "Provider of the API key for Dune service",
+      "enum": [
+        "agent_owner"
+      ],
+      "x-enum-title": [
+        "Owner Provided"
+      ],
+      "default": "agent_owner"
+    }
+  },
+  "required": [
+    "states",
+    "enabled"
+  ],
+  "if": {
+    "properties": {
+      "api_key_provider": {
+        "const": "agent_owner"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "api_key": {
+        "type": "string",
+        "title": "Dune API Key",
+        "description": "API key for Dune Analytics (X-Dune-API-Key).",
+        "x-link": "[Get your API key](https://docs.dune.com/api-reference/overview/authentication)",
+        "x-sensitive": true
+      }
+    },
+    "if": {
+      "properties": {
+        "enabled": {
+          "const": true
+        }
+      }
+    },
+    "then": {
+      "required": [
+        "api_key"
+      ]
+    }
+  },
+  "additionalProperties": true
+}