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

intentkit/skills/base.py

@@ -0,0 +1,174 @@
+import logging
+from typing import Any, Callable, Dict, Literal, NotRequired, Optional, TypedDict, Union
+
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from langchain_core.tools.base import ToolException
+from pydantic import (
+    BaseModel,
+    ValidationError,
+)
+from pydantic.v1 import ValidationError as ValidationErrorV1
+from redis.exceptions import RedisError
+
+from intentkit.abstracts.exception import RateLimitExceeded
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.models.agent import Agent
+from intentkit.models.redis import get_redis
+
+SkillState = Literal["disabled", "public", "private"]
+SkillOwnerState = Literal["disabled", "private"]
+
+
+class SkillConfig(TypedDict):
+    """Abstract base class for skill configuration."""
+
+    enabled: bool
+    states: Dict[str, SkillState | SkillOwnerState]
+    api_key_provider: NotRequired[str]
+    __extra__: NotRequired[Dict[str, Any]]
+
+
+class SkillContext(BaseModel):
+    agent: Agent
+    config: Dict[str, Any]
+    user_id: Optional[str]
+    entrypoint: Literal["web", "twitter", "telegram", "trigger", "api"]
+
+
+class IntentKitSkill(BaseTool):
+    """Abstract base class for IntentKit skills.
+    Will have predefined abilities.
+    """
+
+    skill_store: SkillStoreABC
+    # overwrite the value of BaseTool
+    handle_tool_error: Optional[Union[bool, str, Callable[[ToolException], str]]] = (
+        lambda e: f"tool error: {e}"
+    )
+    """Handle the content of the ToolException thrown."""
+
+    # overwrite the value of BaseTool
+    handle_validation_error: Optional[
+        Union[bool, str, Callable[[Union[ValidationError, ValidationErrorV1]], str]]
+    ] = lambda e: f"validation error: {e}"
+    """Handle the content of the ValidationError thrown."""
+
+    # Logger for the class
+    logger: logging.Logger = logging.getLogger(__name__)
+
+    @property
+    def category(self) -> str:
+        """Get the category of the skill."""
+        raise NotImplementedError
+
+    async def user_rate_limit(
+        self, user_id: str, limit: int, minutes: int, key: str
+    ) -> None:
+        """Check if a user has exceeded the rate limit for this skill.
+
+        Args:
+            user_id: The ID of the user to check
+            limit: Maximum number of requests allowed
+            minutes: Time window in minutes
+            key: The key to use for rate limiting (e.g., skill name or category)
+
+        Raises:
+            RateLimitExceeded: If the user has exceeded the rate limit
+
+        Returns:
+            None: Always returns None if no exception is raised
+        """
+        if not user_id:
+            return None  # No rate limiting for users without ID
+
+        try:
+            redis = get_redis()
+            # Create a unique key for this rate limit and user
+            rate_limit_key = f"rate_limit:{key}:{user_id}"
+
+            # Get the current count
+            count = await redis.incr(rate_limit_key)
+
+            # Set expiration if this is the first request
+            if count == 1:
+                await redis.expire(
+                    rate_limit_key, minutes * 60
+                )  # Convert minutes to seconds
+
+            # Check if user has exceeded the limit
+            if count > limit:
+                raise RateLimitExceeded(f"Rate limit exceeded for {key}")
+
+            return None
+
+        except RuntimeError:
+            # Redis client not initialized, log and allow the request
+            self.logger.info(f"Redis not initialized, skipping rate limit for {key}")
+            return None
+        except RedisError as e:
+            # Redis error, log and allow the request
+            self.logger.info(
+                f"Redis error in rate limiting: {e}, skipping rate limit for {key}"
+            )
+            return None
+
+    async def user_rate_limit_by_skill(
+        self, user_id: str, limit: int, minutes: int
+    ) -> None:
+        """Check if a user has exceeded the rate limit for this specific skill.
+
+        This uses the skill name as the rate limit key.
+
+        Args:
+            user_id: The ID of the user to check
+            limit: Maximum number of requests allowed
+            minutes: Time window in minutes
+
+        Raises:
+            RateLimitExceeded: If the user has exceeded the rate limit
+        """
+        return await self.user_rate_limit(user_id, limit, minutes, self.name)
+
+    async def user_rate_limit_by_category(
+        self, user_id: str, limit: int, minutes: int
+    ) -> None:
+        """Check if a user has exceeded the rate limit for this skill category.
+
+        This uses the skill category as the rate limit key, which means the limit
+        is shared across all skills in the same category.
+
+        Args:
+            user_id: The ID of the user to check
+            limit: Maximum number of requests allowed
+            minutes: Time window in minutes
+
+        Raises:
+            RateLimitExceeded: If the user has exceeded the rate limit
+        """
+        return await self.user_rate_limit(user_id, limit, minutes, self.category)
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError(
+            "Use _arun instead, IntentKit only supports synchronous skill calls"
+        )
+
+    def context_from_config(self, runner_config: RunnableConfig) -> SkillContext:
+        if "configurable" not in runner_config:
+            raise ValueError("configurable not in runner_config")
+        if "agent" not in runner_config["configurable"]:
+            raise ValueError("agent not in runner_config['configurable']")
+        agent: Agent = runner_config["configurable"].get("agent")
+        config = None
+        if agent.skills:
+            config = agent.skills.get(self.category)
+        if not config:
+            config = getattr(agent, self.category + "_config", {})
+        if not config:
+            config = {}
+        return SkillContext(
+            agent=agent,
+            config=config,
+            user_id=runner_config["configurable"].get("user_id"),
+            entrypoint=runner_config["configurable"].get("entrypoint"),
+        )

intentkit/skills/carv/README.md

@@ -0,0 +1,95 @@
+# CARV API Skills: Your Gateway to Blockchain & Crypto Data
+
+This collection of tools helps your AI agent connect to the [CARV API](https://docs.carv.io/d.a.t.a.-ai-framework/api-documentation) to get useful information about cryptocurrencies, blockchain activity, and the latest news in the space. Think of them as special abilities your agent can use!
+
+**Icon:** ![](skills/carv/carv.webp)
+**Tags:** AI, Data, Information, Analytics, Market Data
+
+## What Can Your Agent Do With These Skills?
+
+Here are the tools available:
+
+### 1. Fetch News (`FetchNewsTool`)
+
+*   **What it does:** Gets the latest news articles from CARV.
+*   **What you need to provide:** Nothing! Just ask for the news.
+*   **Example Agent Interaction:** "Hey agent, what's the latest crypto news?"
+*   **What it returns:** A list of news items, each with a:
+    *   `title`: The headline of the news.
+    *   `url`: A link to the full article.
+    *   `card_text`: A short summary.
+    *   *Example output snippet:*
+      ```json
+      {
+        "infos": [
+          {
+            "title": "Big Blockchain Conference Announced",
+            "url": "https://example.com/news/conference",
+            "card_text": "A major conference focusing on blockchain technology will be held next month..."
+          }
+          // ... more news items
+        ]
+      }
+      ```
+
+### 2. On-Chain Query (`OnchainQueryTool`)
+
+*   **What it does:** Lets you ask questions in plain English about what's happening on blockchains like Ethereum, Base, Bitcoin, or Solana. CARV figures out how to get the answer from the blockchain data.
+*   **What you need to provide:**
+    *   `question` (text): Your question about blockchain data (e.g., "What was the biggest Bitcoin transaction yesterday?").
+    *   `chain` (text): The blockchain you're interested in (e.g., "ethereum", "bitcoin").
+*   **Example Agent Interaction:** "Agent, show me the top 5 most active wallets on Solana in the last week."
+*   **What it returns:** A structured table of data that answers your question. If your question involves token amounts (like ETH or BTC), the tool automatically converts them into easy-to-read numbers (e.g., "1.5 ETH" instead of a very long number).
+    *   *Example output snippet (conceptual for "biggest ETH transaction last 24h"):*
+      ```json
+      {
+        "data": {
+          "column_infos": ["transaction_hash", "from_address", "to_address", "value", "timestamp"],
+          "rows": [
+            {
+              "items": ["0xabc...", "0x123...", "0x456...", "1500.75 ETH", "2023-10-27T10:30:00Z"]
+            }
+            // ... potentially more rows if your question implies multiple results
+          ]
+        },
+        "query": "SELECT ... FROM ethereum.transactions ... ORDER BY value DESC LIMIT 1" // The SQL CARV generated
+      }
+      ```
+    *   If something goes wrong (e.g., you ask about an unsupported blockchain), it will return an error message.
+
+### 3. Token Information and Price (`TokenInfoAndPriceTool`)
+
+*   **What it does:** Gets details about a specific cryptocurrency (like its name, symbol, what platform it's on) and its current price in USD.
+*   **What you need to provide:**
+    *   `ticker` (text): The token's symbol (e.g., "BTC", "ETH", "SOL").
+    *   `token_name` (text): The full name of the token (e.g., "Bitcoin", "Ethereum").
+    *   `amount` (number, optional): If you want to know the value of a specific amount of the token, include this (e.g., if you provide `amount: 2.5` and `ticker: "BTC"`, it will tell you what 2.5 BTC is worth).
+*   **Example Agent Interaction:** "Agent, what's the current price of Ethereum? Also, what would 5 ETH be worth?"
+*   **What it returns:** Information about the token, including its price. If you provided an amount, it also tells you the total value.
+    *   *Example output snippet (for `ticker: "ETH"`, `token_name: "Ethereum"`, `amount: 5`):*
+      ```json
+      {
+        "name": "Ethereum",
+        "symbol": "ETH",
+        "price": 2000.50, // Current price of 1 ETH in USD
+        "platform": {"id": "ethereum", "name": "Ethereum"},
+        "categories": ["Smart Contract Platform"],
+        // ... other details
+        "additional_info": "5 ETH is worth $10002.50" // Calculated if amount was given
+      }
+      ```
+    *   If it can't find the token or its price, it will return an error.
+
+## How to Get Started (For Developers)
+
+These tools are designed to be integrated into AI agent systems.
+
+*   **Configuration:** You'll need to set up how these tools access the CARV API. This usually involves:
+    *   Enabling the CARV skills.
+    *   Deciding if the tools can be used by everyone or just the agent owner.
+    *   Providing a CARV API key. This key can either be supplied directly in your agent's settings or managed by the platform your agent runs on.
+    *   Details on how to configure this are in a `schema.json` file within the `skills/carv/` directory.
+
+*   **Using the Tools:** Your agent's code will call these tools, providing the necessary inputs (like the ticker for `TokenInfoAndPriceTool`). The tools will then contact the CARV API and return the information.
+
+These CARV skills make it easy for your AI agent to become knowledgeable about the crypto world!

intentkit/skills/carv/__init__.py

@@ -0,0 +1,121 @@
+import logging
+from typing import List, Literal, Optional, TypedDict
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import SkillConfig, SkillState
+from intentkit.skills.carv.base import CarvBaseTool
+from intentkit.skills.carv.fetch_news import FetchNewsTool
+from intentkit.skills.carv.onchain_query import OnchainQueryTool
+from intentkit.skills.carv.token_info_and_price import TokenInfoAndPriceTool
+
+logger = logging.getLogger(__name__)
+
+
+_cache: dict[str, CarvBaseTool] = {}
+
+_SKILL_NAME_TO_CLASS_MAP: dict[str, type[CarvBaseTool]] = {
+    "onchain_query": OnchainQueryTool,
+    "token_info_and_price": TokenInfoAndPriceTool,
+    "fetch_news": FetchNewsTool,
+}
+
+
+class SkillStates(TypedDict):
+    onchain_query: SkillState
+    token_info_and_price: SkillState
+    fetch_news: SkillState
+
+
+class Config(SkillConfig):
+    enabled: bool
+    states: SkillStates  # type: ignore
+    api_key_provider: Optional[Literal["agent_owner", "platform"]]
+
+    # conditionally required
+    api_key: Optional[str]
+
+    # optional
+    rate_limit_number: Optional[int]
+    rate_limit_minutes: Optional[int]
+
+
+async def get_skills(
+    config: "Config",
+    is_private: bool,
+    store: SkillStoreABC,
+    **_,
+) -> list[CarvBaseTool]:
+    """
+    Factory function to create and return CARV skill tools based on the provided configuration.
+
+    Args:
+        config: The configuration object for the CARV skill.
+        is_private: A boolean indicating whether the request is from a private context.
+        store: An instance of `SkillStoreABC`.
+
+    Returns:
+        A list of `CarvBaseTool` instances.
+    """
+    # Check if the entire category is disabled first
+    if not config.get("enabled", False):
+        return []
+
+    available_skills: List[CarvBaseTool] = []
+    skill_states = config.get("states", {})
+
+    # Iterate through all known skills defined in the map
+    for skill_name in _SKILL_NAME_TO_CLASS_MAP:
+        state = skill_states.get(
+            skill_name, "disabled"
+        )  # Default to disabled if not in config
+
+        if state == "disabled":
+            continue
+        elif state == "public" or (state == "private" and is_private):
+            # If enabled, get the skill instance using the factory function
+            skill_instance = get_carv_skill(skill_name, store)
+            if skill_instance:
+                available_skills.append(skill_instance)
+            else:
+                logger.warning(f"Could not instantiate known skill: {skill_name}")
+
+    return available_skills
+
+
+def get_carv_skill(
+    name: str,
+    store: SkillStoreABC,
+) -> Optional[CarvBaseTool]:
+    """
+    Factory function to retrieve a cached CARV skill instance by name.
+
+    Args:
+        name: The name of the CARV skill to retrieve.
+        store: An instance of `SkillStoreABC`.
+
+    Returns:
+        The requested `CarvBaseTool` instance if found and enabled, otherwise None.
+    """
+
+    # Return from cache immediately if already exists
+    if name in _cache:
+        return _cache[name]
+
+    # Get the class from the map
+    skill_class = _SKILL_NAME_TO_CLASS_MAP.get(name)
+
+    if skill_class:
+        try:
+            # Instantiate the skill and add to cache
+            instance = skill_class(skill_store=store)  # type: ignore
+            _cache[name] = instance
+            return instance
+        except Exception as e:
+            logger.error(
+                f"Failed to instantiate Carv skill '{name}': {e}", exc_info=True
+            )
+            return None  # Failed to instantiate
+    else:
+        # This handles cases where a name might be in config but not in our map
+        logger.warning(f"Attempted to get unknown Carv skill: {name}")
+        return None

intentkit/skills/carv/base.py

@@ -0,0 +1,183 @@
+import logging
+from typing import Any, Dict, Optional, Tuple, Type
+
+import httpx  # Ensure httpx is installed: pip install httpx
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import IntentKitSkill, SkillContext, ToolException
+
+logger = logging.getLogger(__name__)
+
+CARV_API_BASE_URL = "https://interface.carv.io"
+
+
+class CarvBaseTool(IntentKitSkill):
+    """Base class for CARV API tools."""
+
+    name: str = Field(description="Tool name")  # type: ignore
+    description: str = Field(description="Tool description")
+    args_schema: Type[BaseModel]  # type: ignore
+    skill_store: SkillStoreABC = Field(description="Skill store for data persistence")
+
+    @property
+    def category(self) -> str:
+        return "carv"
+
+    def get_api_key(self, context: SkillContext) -> str:
+        """
+        Retrieves the CARV API key based on the api_key_provider setting.
+
+        Returns:
+            The API key if found.
+
+        Raises:
+            ToolException: If the API key is not found or provider is invalid.
+        """
+        try:
+            skillConfig = context.config
+            api_key_provider = skillConfig.get("api_key_provider")
+            if api_key_provider == "agent_owner":
+                agent_api_key: Optional[str] = context.config.get("api_key")
+                if agent_api_key:
+                    logger.debug(
+                        f"Using agent-specific CARV API key for skill {self.name} in category {self.category}"
+                    )
+                    return agent_api_key
+                raise ToolException(
+                    f"No agent-owned CARV API key found for skill '{self.name}' in category '{self.category}'."
+                )
+
+            elif api_key_provider == "platform":
+                system_api_key = self.skill_store.get_system_config("carv_api_key")
+                if system_api_key:
+                    logger.debug(
+                        f"Using system CARV API key for skill {self.name} in category {self.category}"
+                    )
+                    return system_api_key
+                raise ToolException(
+                    f"No platform-hosted CARV API key found for skill '{self.name}' in category '{self.category}'."
+                )
+
+            else:
+                raise ToolException(
+                    f"Invalid API key provider '{api_key_provider}' for skill '{self.name}'"
+                )
+
+        except Exception as e:
+            # Re-raise ToolException if it's already one, otherwise wrap
+            if isinstance(e, ToolException):
+                raise
+            raise ToolException(f"Failed to retrieve CARV API key: {str(e)}") from e
+
+    async def apply_rate_limit(self, context: SkillContext) -> None:
+        """
+        Applies rate limiting ONLY if specified in the agent's config ('skill_config').
+        Checks for 'rate_limit_number' and 'rate_limit_minutes'.
+        If not configured, NO rate limiting is applied.
+        Raises ConnectionAbortedError if the configured limit is exceeded.
+        """
+        skill_config = context.config
+        user_id = context.user_id
+
+        limit_num = skill_config.get("rate_limit_number")
+        limit_min = skill_config.get("rate_limit_minutes")
+
+        # Apply limit ONLY if both values are present and valid (truthy check handles None and 0)
+        if limit_num and limit_min:
+            logger.debug(
+                f"Applying rate limit ({limit_num}/{limit_min} min) for user {user_id} on {self.name}"
+            )
+            if user_id:
+                await self.user_rate_limit_by_category(user_id, limit_num, limit_min)
+        else:
+            # No valid agent configuration found, so do nothing.
+            logger.debug(
+                f"No agent rate limits configured for category '{self.category}'. Skipping rate limit for user {user_id}."
+            )
+
+    async def _call_carv_api(
+        self,
+        context: SkillContext,
+        endpoint: str,
+        method: str = "GET",
+        params: Optional[Dict[str, Any]] = None,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]:
+        """
+        Makes a call to the CARV API and returns a tuple of (success, error).
+
+        Args:
+            context: The skill context.
+            endpoint: The API endpoint path (e.g., "/ai-agent-backend/token_info").
+            method: HTTP method ("GET", "POST", etc.).
+            params: Query parameters for the request.
+            payload: JSON payload for POST/PUT requests.
+
+        Returns:
+            Tuple where the first element is the response data if successful,
+            and the second element is an error dict if an error occurred.
+        """
+
+        url = f"{CARV_API_BASE_URL}{endpoint}"
+
+        try:
+            api_key = self.get_api_key(context)
+
+            headers = {
+                "Authorization": api_key,
+                "Content-Type": "application/json",
+            }
+
+            logger.debug(
+                f"Calling CARV API: {method} {url} with params {params}, payload {payload}"
+            )
+
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                if method == "GET":
+                    response = await client.get(url, headers=headers, params=params)
+                elif method == "POST":
+                    response = await client.post(
+                        url, headers=headers, json=payload, params=params
+                    )
+                else:
+                    return None, {"error": f"Unsupported HTTP method: {method}"}
+
+                # Do NOT raise for status here; always parse JSON
+                try:
+                    response_json: dict[str, Any] = response.json()
+                except Exception as json_err:
+                    err_msg = f"Failed to parse JSON response: {json_err}"
+                    logger.error(err_msg)
+                    return None, {"error": err_msg}
+
+                logger.debug(
+                    f"CARV API Response (status {response.status_code}): {response_json}"
+                )
+
+                # Check if response_json signals an error explicitly (custom API error)
+                if response.status_code >= 400 or "error" in response_json:
+                    # Return full error info (including status code, body, etc.)
+                    return None, {
+                        "error": response_json.get("error", "Unknown API error"),
+                        "status_code": response.status_code,
+                        "response": response_json,
+                        "url": url,
+                        "method": method,
+                        "params": params,
+                        "payload": payload,
+                    }
+
+                # Otherwise return the 'data' field if present, else full response
+                return response_json.get("data", response_json), None
+
+        except Exception as e:
+            logger.error(
+                f"Error calling CARV API to {method} > {url}: {e}", exc_info=True
+            )
+            return None, {
+                "error": str(e),
+                "url": url,
+                "method": method,
+                "params": params,
+            }

intentkit/skills/carv/fetch_news.py

@@ -0,0 +1,92 @@
+import logging
+from typing import Any, Dict, Type
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel
+
+from intentkit.skills.carv.base import CarvBaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class CarvNewsInput(BaseModel):
+    """
+    Input schema for CARV News API.
+    This API endpoint does not require any specific parameters from the user.
+    """
+
+    pass
+
+
+class FetchNewsTool(CarvBaseTool):
+    """
+    Tool for fetching the latest news articles from the CARV API.
+    This tool retrieves a list of recent news items, each including a title, URL, and a short description (card_text).
+    It's useful for getting up-to-date information on various topics covered by CARV's news aggregation.
+    """
+
+    name: str = "carv_fetch_news"
+    description: str = (
+        "Fetches the latest news articles from the CARV API. "
+        "Returns a list of news items, each with a title, URL, and a short summary (card_text)."
+    )
+    args_schema: Type[BaseModel] = CarvNewsInput
+
+    async def _arun(
+        self,
+        config: RunnableConfig = None,  # type: ignore
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """
+        Fetches news from the CARV API and returns the response.
+        The expected successful response structure is a dictionary containing an "infos" key,
+        which holds a list of news articles.
+        Example: {"infos": [{"title": "...", "url": "...", "card_text": "..."}, ...]}
+        """
+        context = self.context_from_config(config)
+
+        try:
+            await self.apply_rate_limit(context)
+
+            result, error = await self._call_carv_api(
+                context=context,
+                endpoint="/ai-agent-backend/news",
+                method="GET",
+            )
+
+            if error is not None or result is None:
+                logger.error(f"Error returned from CARV API (News): {error}")
+                return {
+                    "error": True,
+                    "error_type": "APIError",
+                    "message": "Failed to fetch news from CARV API.",
+                    "details": error,  # error is the detailed error dict from _call_carv_api
+                }
+
+            # _call_carv_api returns response_json.get("data", response_json) on success.
+            # For this endpoint, the "data" field should be {"infos": [...]}.
+            # So, 'result' should be {"infos": [...]}.
+            if "infos" not in result or not isinstance(result.get("infos"), list):
+                logger.warning(
+                    f"CARV API (News) response did not contain 'infos' list as expected: {result}"
+                )
+                return {
+                    "error": True,
+                    "error_type": "UnexpectedResponseFormat",
+                    "message": "News data from CARV API is missing the 'infos' list or has incorrect format.",
+                    "details": result,
+                }
+
+            # Successfully fetched and validated news data
+            return result  # This will be {"infos": [...]}
+
+        except Exception as e:
+            logger.error(
+                f"An unexpected error occurred while fetching news: {e}", exc_info=True
+            )
+            return {
+                "error": True,
+                "error_type": type(e).__name__,
+                "message": "An unexpected error occurred while processing the news request.",
+                "details": str(e),
+            }