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

intentkit/skills/system/system.svg

@@ -0,0 +1,76 @@
+<svg width="256" height="256" viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <!-- Liquid glass gradient -->
+    <linearGradient id="glassGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#E8F4FD;stop-opacity:0.9"/>
+      <stop offset="25%" style="stop-color:#B8E0FF;stop-opacity:0.8"/>
+      <stop offset="50%" style="stop-color:#7CC7FF;stop-opacity:0.7"/>
+      <stop offset="75%" style="stop-color:#4A9EFF;stop-opacity:0.8"/>
+      <stop offset="100%" style="stop-color:#2563EB;stop-opacity:0.9"/>
+    </linearGradient>
+    
+    <!-- Inner shadow gradient -->
+    <radialGradient id="innerShadow" cx="50%" cy="30%" r="70%">
+      <stop offset="0%" style="stop-color:#FFFFFF;stop-opacity:0.6"/>
+      <stop offset="70%" style="stop-color:#FFFFFF;stop-opacity:0.2"/>
+      <stop offset="100%" style="stop-color:#1E40AF;stop-opacity:0.3"/>
+    </radialGradient>
+    
+    <!-- Highlight gradient -->
+    <linearGradient id="highlight" x1="0%" y1="0%" x2="100%" y2="50%">
+      <stop offset="0%" style="stop-color:#FFFFFF;stop-opacity:0.8"/>
+      <stop offset="100%" style="stop-color:#FFFFFF;stop-opacity:0"/>
+    </linearGradient>
+    
+    <!-- Drop shadow filter -->
+    <filter id="dropShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="2" dy="4" stdDeviation="3" flood-color="#000000" flood-opacity="0.2"/>
+    </filter>
+  </defs>
+  
+  <!-- Background circle -->
+  <circle cx="128" cy="128" r="120" fill="#F8FAFC" stroke="#E2E8F0" stroke-width="2" filter="url(#dropShadow)"/>
+  
+  <!-- Main gear shape -->
+  <g transform="translate(128,128)">
+    <!-- Outer gear teeth -->
+    <g fill="url(#glassGradient)" stroke="#1E40AF" stroke-width="1.5" opacity="0.9">
+      <!-- 12 gear teeth positioned around the circle -->
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(0)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(30)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(60)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(90)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(120)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(150)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(180)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(210)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(240)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(270)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(300)"/>
+      <rect x="-8" y="-65" width="16" height="20" rx="2" transform="rotate(330)"/>
+    </g>
+    
+    <!-- Main gear body -->
+    <circle r="45" fill="url(#glassGradient)" stroke="#1E40AF" stroke-width="2"/>
+    
+    <!-- Inner shadow overlay -->
+    <circle r="45" fill="url(#innerShadow)"/>
+    
+    <!-- Center hole -->
+    <circle r="18" fill="#FFFFFF" stroke="#CBD5E1" stroke-width="2"/>
+    
+    <!-- Inner hole shadow -->
+    <circle r="18" fill="none" stroke="#94A3B8" stroke-width="1" opacity="0.5"/>
+    
+    <!-- Glass highlight effect -->
+    <ellipse cx="-15" cy="-15" rx="25" ry="35" fill="url(#highlight)" opacity="0.6" transform="rotate(-30)"/>
+    
+    <!-- Small decorative bolts -->
+    <circle cx="0" cy="-30" r="3" fill="#64748B"/>
+    <circle cx="26" cy="-15" r="3" fill="#64748B"/>
+    <circle cx="26" cy="15" r="3" fill="#64748B"/>
+    <circle cx="0" cy="30" r="3" fill="#64748B"/>
+    <circle cx="-26" cy="15" r="3" fill="#64748B"/>
+    <circle cx="-26" cy="-15" r="3" fill="#64748B"/>
+  </g>
+</svg>

intentkit/skills/tavily/README.md

@@ -0,0 +1,86 @@
+# Tavily Skills
+
+This skill package enables agents to search the web and extract content from web pages using the [Tavily](https://tavily.com/) API.
+
+## Overview
+
+The Tavily skills allow agents to:
+- Search the internet for current information
+- Retrieve relevant search results with snippets and URLs
+- Extract full content from specific web pages
+- Find answers to questions that may not be in the agent's training data
+- Access real-time information and news
+
+## Available Skills
+
+### 1. Tavily Search
+Allows agents to search the web for current information and retrieve relevant results.
+
+### 2. Tavily Extract
+Allows agents to extract full content from specific URLs, including text and optionally images.
+
+## Configuration
+
+To enable these skills, add the following to your agent configuration:
+
+```yaml
+skills:
+  tavily:
+    enabled: true
+    api_key: "your-tavily-api-key"
+    states:
+      tavily_search: public  # or "private" or "disabled"
+      tavily_extract: public  # or "private" or "disabled"
+```
+
+### Configuration Options
+
+- `enabled`: Whether the skills are enabled (true/false)
+- `api_key`: Your Tavily API key
+- `states.tavily_search`: The state of the Tavily search skill
+  - `public`: Available to agent owner and all users
+  - `private`: Available only to the agent owner
+  - `disabled`: Not available to anyone
+- `states.tavily_extract`: The state of the Tavily extract skill
+  - `public`: Available to agent owner and all users
+  - `private`: Available only to the agent owner
+  - `disabled`: Not available to anyone
+
+## Usage Examples
+
+### Tavily Search
+
+The agent will automatically use Tavily search when:
+- A user asks for current information or news
+- The agent needs to verify facts or find up-to-date information
+- A query seeks information that may not be in the agent's training data
+
+**Example Interaction:**
+
+**User**: "What's the current price of Bitcoin?"
+
+**Agent**: *Uses Tavily search to find current cryptocurrency prices*
+
+### Tavily Extract
+
+The agent will automatically use Tavily extract when:
+- A user wants to extract or scrape content from a specific URL
+- The agent needs to analyze the full content of a web page
+- A query requires detailed information from a particular website
+
+**Example Interaction:**
+
+**User**: "Can you extract the content from https://en.wikipedia.org/wiki/Artificial_intelligence"
+
+**Agent**: *Uses Tavily extract to retrieve the full content from the Wikipedia page*
+
+## API Requirements
+
+These skills require a valid Tavily API key. You can sign up for one at [tavily.com](https://tavily.com/).
+
+## Limitations
+
+- Search results are limited to a maximum of 10 items per query
+- Extract functionality may not work on all websites due to access restrictions
+- The quality of results depends on the Tavily API
+- Rate limits may apply based on your Tavily API plan 

intentkit/skills/tavily/__init__.py

@@ -0,0 +1,91 @@
+"""Tavily search skills."""
+
+import logging
+from typing import TypedDict
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import SkillConfig, SkillState
+from intentkit.skills.tavily.base import TavilyBaseTool
+from intentkit.skills.tavily.tavily_extract import TavilyExtract
+from intentkit.skills.tavily.tavily_search import TavilySearch
+
+# Cache skills at the system level, because they are stateless
+_cache: dict[str, TavilyBaseTool] = {}
+
+logger = logging.getLogger(__name__)
+
+
+class SkillStates(TypedDict):
+    tavily_search: SkillState
+    tavily_extract: SkillState
+
+
+class Config(SkillConfig):
+    """Configuration for Tavily search skills."""
+
+    states: SkillStates
+    api_key: str
+
+
+async def get_skills(
+    config: "Config",
+    is_private: bool,
+    store: SkillStoreABC,
+    **_,
+) -> list[TavilyBaseTool]:
+    """Get all Tavily search skills.
+
+    Args:
+        config: The configuration for Tavily search skills.
+        is_private: Whether to include private skills.
+        store: The skill store for persisting data.
+
+    Returns:
+        A list of Tavily search 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_tavily_skill(name, store)
+        if skill:
+            result.append(skill)
+    return result
+
+
+def get_tavily_skill(
+    name: str,
+    store: SkillStoreABC,
+) -> TavilyBaseTool:
+    """Get a Tavily search skill by name.
+
+    Args:
+        name: The name of the skill to get
+        store: The skill store for persisting data
+
+    Returns:
+        The requested Tavily search skill
+    """
+    if name == "tavily_search":
+        if name not in _cache:
+            _cache[name] = TavilySearch(
+                skill_store=store,
+            )
+        return _cache[name]
+    elif name == "tavily_extract":
+        if name not in _cache:
+            _cache[name] = TavilyExtract(
+                skill_store=store,
+            )
+        return _cache[name]
+    else:
+        logger.warning(f"Unknown Tavily skill: {name}")
+        return None

intentkit/skills/tavily/base.py

@@ -0,0 +1,27 @@
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import IntentKitSkill, SkillContext
+
+
+class TavilyBaseTool(IntentKitSkill):
+    """Base class for Tavily search 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) -> str:
+        skill_config = context.config
+        if skill_config.get("api_key_provider") == "agent_owner":
+            return skill_config.get("api_key")
+        return self.skill_store.get_system_config("tavily_api_key")
+
+    @property
+    def category(self) -> str:
+        return "tavily"

intentkit/skills/tavily/schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Tavily Search and Extract",
+  "description": "Web search and content extraction capabilities using Tavily",
+  "x-icon": "https://ai.service.crestal.dev/skills/tavily/tavily.jpg",
+  "x-tags": [
+    "Internet",
+    "Search",
+    "Information",
+    "Content Extraction"
+  ],
+  "x-nft-requirement": 1,
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enabled",
+      "description": "Whether this skill is enabled",
+      "default": true
+    },
+    "states": {
+      "type": "object",
+      "properties": {
+        "tavily_search": {
+          "type": "string",
+          "title": "Tavily Search",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Search the web for real-time information and recent content using Tavily",
+          "default": "private"
+        },
+        "tavily_extract": {
+          "type": "string",
+          "title": "Tavily Extract",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Extract full content from web pages using Tavily Extract API",
+          "default": "private"
+        }
+      },
+      "description": "States for each Tavily skill (disabled, public, or private)"
+    },
+    "api_key_provider": {
+      "type": "string",
+      "title": "API Key Provider",
+      "description": "Provider of the API key",
+      "enum": [
+        "platform",
+        "agent_owner"
+      ],
+      "x-enum-title": [
+        "Nation Hosted",
+        "Owner Provided"
+      ],
+      "default": "platform"
+    }
+  },
+  "required": [
+    "states",
+    "enabled"
+  ],
+  "if": {
+    "properties": {
+      "api_key_provider": {
+        "const": "agent_owner"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "api_key": {
+        "type": "string",
+        "title": "Tavily API Key",
+        "description": "API key for Tavily services",
+        "x-link": "[Get your API key](https://tavily.com/)",
+        "x-sensitive": true
+      },
+      "rate_limit_number": {
+        "type": "integer",
+        "title": "Rate Limit Number",
+        "description": "Number of requests allowed per time window, only valid if api_key is set"
+      },
+      "rate_limit_minutes": {
+        "type": "integer",
+        "title": "Rate Limit Minutes",
+        "description": "Time window in minutes for rate limiting, only valid if api_key is set"
+      }
+    },
+    "if": {
+      "properties": {
+        "enabled": {
+          "const": true
+        }
+      }
+    },
+    "then": {
+      "required": [
+        "api_key"
+      ]
+    }
+  },
+  "additionalProperties": true
+}

intentkit/skills/tavily/tavily_extract.py

@@ -0,0 +1,147 @@
+import logging
+from typing import Type
+
+import httpx
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.tavily.base import TavilyBaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class TavilyExtractInput(BaseModel):
+    """Input for Tavily extract tool."""
+
+    urls: str = Field(
+        description="The URL to extract content from.",
+    )
+    include_images: bool = Field(
+        description="Include a list of images extracted from the URLs in the response.",
+        default=False,
+    )
+    extract_depth: str = Field(
+        description="The depth of the extraction process. 'advanced' retrieves more data including tables and embedded content with higher success but may increase latency. 'basic' costs 1 credit per 5 successful URL extractions, while 'advanced' costs 2 credits per 5 successful URL extractions.",
+        default="basic",
+    )
+
+
+class TavilyExtract(TavilyBaseTool):
+    """Tool for extracting web page content using Tavily.
+
+    This tool uses Tavily's extract API to retrieve content from specified URLs.
+
+    Attributes:
+        name: The name of the tool.
+        description: A description of what the tool does.
+        args_schema: The schema for the tool's input arguments.
+    """
+
+    name: str = "tavily_extract"
+    description: str = (
+        "Extract web page content from a specified URL using Tavily Extract. "
+        "This tool is useful when you need to get the full text content from a webpage. "
+        "You must call this tool whenever the user asks to extract or scrape content from a specific URL."
+    )
+    args_schema: Type[BaseModel] = TavilyExtractInput
+
+    async def _arun(
+        self,
+        urls: str,
+        include_images: bool = False,
+        extract_depth: str = "basic",
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> str:
+        """Implementation of the Tavily extract tool.
+
+        Args:
+            urls: The URL to extract content from.
+            include_images: Whether to include image URLs in the results.
+            extract_depth: The depth of the extraction process ('basic' or 'advanced').
+            config: The configuration for the tool call.
+
+        Returns:
+            str: Formatted extraction results with content from the URL.
+        """
+        context = self.context_from_config(config)
+        logger.debug(
+            f"tavily_extract.py: Running web extraction with context {context}"
+        )
+
+        if context.config.get("api_key_provider") == "agent_owner":
+            if context.config.get("rate_limit_number") and context.config.get(
+                "rate_limit_minutes"
+            ):
+                await self.user_rate_limit_by_category(
+                    context.user_id,
+                    context.config["rate_limit_number"],
+                    context.config["rate_limit_minutes"],
+                )
+
+        # Get the API key from the agent's configuration
+        api_key = self.get_api_key(context)
+        if not api_key:
+            return "Error: No Tavily API key provided in the configuration."
+
+        # Validate extract_depth
+        if extract_depth not in ["basic", "advanced"]:
+            extract_depth = "basic"
+            logger.warning(
+                "tavily_extract.py: Invalid extract_depth provided. Using default 'basic'."
+            )
+
+        # Call Tavily extract API
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(
+                    "https://api.tavily.com/extract",
+                    headers={"Authorization": f"Bearer {api_key}"},
+                    json={
+                        "urls": urls,
+                        "include_images": include_images,
+                        "extract_depth": extract_depth,
+                    },
+                )
+
+                if response.status_code != 200:
+                    logger.error(
+                        f"tavily_extract.py: Error from Tavily API: {response.status_code} - {response.text}"
+                    )
+                    return f"Error extracting web page content: {response.status_code} - {response.text}"
+
+                data = response.json()
+                results = data.get("results", [])
+
+                if not results:
+                    return f"No content could be extracted from URL: '{urls}'"
+
+                # Format the results
+                formatted_results = f"Web page content extracted from: '{urls}'\n\n"
+
+                for i, result in enumerate(results, 1):
+                    url = result.get("url", "No URL")
+                    raw_content = result.get("raw_content", "No content available")
+
+                    # Truncate the content if it's too long (over 2000 characters)
+                    if len(raw_content) > 2000:
+                        raw_content = raw_content[:2000] + "...[content truncated]"
+
+                    formatted_results += f"{i}. Content from {url}:\n\n"
+                    formatted_results += f"{raw_content}\n\n"
+
+                    # Add images if available and requested
+                    if include_images and "images" in result and result["images"]:
+                        formatted_results += "Images:\n"
+                        for j, image_url in enumerate(result["images"], 1):
+                            formatted_results += f"  {j}. {image_url}\n"
+                        formatted_results += "\n"
+
+                return formatted_results.strip()
+
+        except Exception as e:
+            logger.error(
+                f"tavily_extract.py: Error extracting web page content: {e}",
+                exc_info=True,
+            )
+            return "An error occurred while extracting web page content. Please try again later."

intentkit/skills/tavily/tavily_search.py

@@ -0,0 +1,139 @@
+import logging
+from typing import Type
+
+import httpx
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.tavily.base import TavilyBaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class TavilySearchInput(BaseModel):
+    """Input for Tavily search tool."""
+
+    query: str = Field(
+        description="The search query to look up on the web.",
+    )
+    max_results: int = Field(
+        description="Maximum number of search results to return (1-10).",
+        default=5,
+        ge=1,
+        le=10,
+    )
+    include_images: bool = Field(
+        description="Whether to include image URLs in the results.",
+        default=False,
+    )
+    include_raw_content: bool = Field(
+        description="Whether to include raw HTML content in the results.",
+        default=False,
+    )
+
+
+class TavilySearch(TavilyBaseTool):
+    """Tool for searching the web using Tavily.
+
+    This tool uses Tavily's search API to search the web and return relevant results.
+
+    Attributes:
+        name: The name of the tool.
+        description: A description of what the tool does.
+        args_schema: The schema for the tool's input arguments.
+    """
+
+    name: str = "tavily_search"
+    description: str = (
+        "Search the web for current information on a topic. Use this tool when you need to find"
+        " up-to-date information, facts, news, or any content available online.\n"
+        "You must call this tool whenever the user asks for information that may not be in your training data,"
+        " requires current data, or when you're unsure about facts."
+    )
+    args_schema: Type[BaseModel] = TavilySearchInput
+
+    async def _arun(
+        self,
+        query: str,
+        max_results: int = 5,
+        include_images: bool = False,
+        include_raw_content: bool = False,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> str:
+        """Implementation of the Tavily search tool.
+
+        Args:
+            query: The search query to look up.
+            max_results: Maximum number of search results to return (1-10).
+            include_images: Whether to include image URLs in the results.
+            include_raw_content: Whether to include raw HTML content in the results.
+            config: The configuration for the tool call.
+
+        Returns:
+            str: Formatted search results with titles, snippets, and URLs.
+        """
+        context = self.context_from_config(config)
+        logger.debug(f"tavily.py: Running web search with context {context}")
+
+        if context.config.get("api_key_provider") == "agent_owner":
+            if context.config.get("rate_limit_number") and context.config.get(
+                "rate_limit_minutes"
+            ):
+                await self.user_rate_limit_by_category(
+                    context.user_id,
+                    context.config["rate_limit_number"],
+                    context.config["rate_limit_minutes"],
+                )
+
+        # Get the API key from the agent's configuration
+        api_key = self.get_api_key(context)
+        if not api_key:
+            return "Error: No Tavily API key provided in the configuration."
+
+        # Limit max_results to a reasonable range
+        max_results = max(1, min(max_results, 10))
+
+        # Call Tavily search API
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(
+                    "https://api.tavily.com/search",
+                    json={
+                        "api_key": api_key,
+                        "query": query,
+                        "max_results": max_results,
+                        "include_images": include_images,
+                        "include_raw_content": include_raw_content,
+                    },
+                )
+
+                if response.status_code != 200:
+                    logger.error(
+                        f"tavily.py: Error from Tavily API: {response.status_code} - {response.text}"
+                    )
+                    return f"Error searching the web: {response.status_code} - {response.text}"
+
+                data = response.json()
+                results = data.get("results", [])
+
+                if not results:
+                    return f"No results found for query: '{query}'"
+
+                # Format the results
+                formatted_results = f"Web search results for: '{query}'\n\n"
+
+                for i, result in enumerate(results, 1):
+                    title = result.get("title", "No title")
+                    content = result.get("content", "No content")
+                    url = result.get("url", "No URL")
+
+                    formatted_results += f"{i}. {title}\n"
+                    formatted_results += f"{content}\n"
+                    formatted_results += f"Source: {url}\n\n"
+
+                return formatted_results.strip()
+
+        except Exception as e:
+            logger.error(f"tavily.py: Error searching web: {e}", exc_info=True)
+            return "An error occurred while searching the web. Please try again later."