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

intentkit/models/user.py

@@ -0,0 +1,243 @@
+import logging
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import Annotated, Optional
+
+from intentkit.models.base import Base
+from intentkit.models.credit import CreditAccount
+from intentkit.models.db import get_session
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy import Column, DateTime, Index, Integer, String, func, select
+from sqlalchemy.dialects.postgresql import JSON, JSONB
+from sqlalchemy.ext.asyncio import AsyncSession
+
+logger = logging.getLogger(__name__)
+
+
+class UserTable(Base):
+    """User database table model."""
+
+    __tablename__ = "users"
+    __table_args__ = (
+        Index("ix_users_x_username", "x_username"),
+        Index("ix_users_telegram_username", "telegram_username"),
+    )
+
+    id = Column(
+        String,
+        primary_key=True,
+    )
+    nft_count = Column(
+        Integer,
+        default=0,
+        nullable=False,
+    )
+    email = Column(
+        String,
+        nullable=True,
+    )
+    x_username = Column(
+        String,
+        nullable=True,
+    )
+    github_username = Column(
+        String,
+        nullable=True,
+    )
+    telegram_username = Column(
+        String,
+        nullable=True,
+    )
+    extra = Column(
+        JSON().with_variant(JSONB(), "postgresql"),
+        nullable=True,
+    )
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )
+
+
+class UserUpdate(BaseModel):
+    """User update model without id and timestamps."""
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        json_encoders={
+            datetime: lambda v: v.isoformat(timespec="milliseconds"),
+        },
+    )
+
+    nft_count: Annotated[
+        int, Field(default=0, description="Number of NFTs owned by the user")
+    ]
+    email: Annotated[Optional[str], Field(None, description="User's email address")]
+    x_username: Annotated[
+        Optional[str], Field(None, description="User's X (Twitter) username")
+    ]
+    github_username: Annotated[
+        Optional[str], Field(None, description="User's GitHub username")
+    ]
+    telegram_username: Annotated[
+        Optional[str], Field(None, description="User's Telegram username")
+    ]
+    extra: Annotated[
+        Optional[dict], Field(None, description="Additional user information")
+    ]
+
+    async def _update_quota_for_nft_count(
+        self, db: AsyncSession, id: str, new_nft_count: int
+    ) -> None:
+        """Update user's daily quota based on NFT count.
+
+        Args:
+            db: Database session
+            id: User ID
+            new_nft_count: Current NFT count
+        """
+        # Generate upstream_tx_id
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+        upstream_tx_id = f"nft_{id}_{timestamp}"
+
+        # Calculate new quota values based on nft_count
+        free_quota = Decimal(480 + 48 * new_nft_count)
+        refill_amount = Decimal(20 + 2 * new_nft_count)
+        note = f"NFT count changed to {new_nft_count}"
+
+        # Update daily quota
+        logger.info(
+            f"Updating daily quota for user {id} due to NFT count change to {new_nft_count}"
+        )
+        await CreditAccount.update_daily_quota(
+            db,
+            id,
+            free_quota=free_quota,
+            refill_amount=refill_amount,
+            upstream_tx_id=upstream_tx_id,
+            note=note,
+        )
+
+    async def patch(self, id: str) -> "User":
+        """Update only the provided fields of a user in the database.
+        If the user doesn't exist, create a new one with the provided ID and fields.
+        If nft_count changes, update the daily quota accordingly.
+
+        Args:
+            id: ID of the user to update or create
+
+        Returns:
+            Updated or newly created User model
+        """
+        async with get_session() as db:
+            db_user = await db.get(UserTable, id)
+            old_nft_count = 0  # Default for new users
+
+            if not db_user:
+                # Create new user if it doesn't exist
+                db_user = UserTable(id=id)
+                db.add(db_user)
+            else:
+                old_nft_count = db_user.nft_count
+
+            # Update only the fields that were provided
+            update_data = self.model_dump(exclude_unset=True)
+            for key, value in update_data.items():
+                setattr(db_user, key, value)
+
+            # Check if nft_count has changed and is in the update data
+            if "nft_count" in update_data and old_nft_count != update_data["nft_count"]:
+                await self._update_quota_for_nft_count(db, id, update_data["nft_count"])
+
+            await db.commit()
+            await db.refresh(db_user)
+
+            return User.model_validate(db_user)
+
+    async def put(self, id: str) -> "User":
+        """Replace all fields of a user in the database with the provided values.
+        If the user doesn't exist, create a new one with the provided ID and fields.
+        If nft_count changes, update the daily quota accordingly.
+
+        Args:
+            id: ID of the user to update or create
+
+        Returns:
+            Updated or newly created User model
+        """
+        async with get_session() as db:
+            db_user = await db.get(UserTable, id)
+            old_nft_count = 0  # Default for new users
+
+            if not db_user:
+                # Create new user if it doesn't exist
+                db_user = UserTable(id=id)
+                db.add(db_user)
+            else:
+                old_nft_count = db_user.nft_count
+
+            # Replace all fields with the provided values
+            for key, value in self.model_dump().items():
+                setattr(db_user, key, value)
+
+            # Check if nft_count has changed
+            if old_nft_count != self.nft_count:
+                await self._update_quota_for_nft_count(db, id, self.nft_count)
+
+            await db.commit()
+            await db.refresh(db_user)
+
+            return User.model_validate(db_user)
+
+
+class User(UserUpdate):
+    """User model with all fields including id and timestamps."""
+
+    id: Annotated[
+        str,
+        Field(description="Unique identifier for the user"),
+    ]
+    created_at: Annotated[
+        datetime, Field(description="Timestamp when this user was created")
+    ]
+    updated_at: Annotated[
+        datetime, Field(description="Timestamp when this user was last updated")
+    ]
+
+    @classmethod
+    async def get(cls, user_id: str) -> Optional["User"]:
+        """Get a user by ID.
+
+        Args:
+            user_id: ID of the user to get
+
+        Returns:
+            User model or None if not found
+        """
+        async with get_session() as session:
+            return await cls.get_in_session(session, user_id)
+
+    @classmethod
+    async def get_in_session(
+        cls, session: AsyncSession, user_id: str
+    ) -> Optional["User"]:
+        """Get a user by ID using the provided session.
+
+        Args:
+            session: Database session
+            user_id: ID of the user to get
+
+        Returns:
+            User model or None if not found
+        """
+        result = await session.execute(select(UserTable).where(UserTable.id == user_id))
+        user = result.scalars().first()
+        if user is None:
+            return None
+        return cls.model_validate(user)

intentkit/skills/__init__.py

@@ -0,0 +1,12 @@
+import os
+import pkgutil
+
+# Get the directory containing this __init__.py file
+package_dir = os.path.dirname(__file__)
+
+# Discover all modules in the skills directory
+__all__ = [
+    name
+    for _, name, _ in pkgutil.iter_modules([package_dir])
+    if not name.startswith("_") and not name == "base"
+]

intentkit/skills/acolyt/__init__.py

@@ -0,0 +1,83 @@
+"""Acolyt skill module."""
+
+import logging
+from typing import NotRequired, TypedDict
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.acolyt.ask import AcolytAskGpt
+from intentkit.skills.acolyt.base import AcolytBaseTool
+from intentkit.skills.base import SkillConfig, SkillState
+
+# Cache skills at the system level, because they are stateless
+_cache: dict[str, AcolytBaseTool] = {}
+
+logger = logging.getLogger(__name__)
+
+
+class SkillStates(TypedDict):
+    ask_gpt: SkillState
+
+
+class Config(SkillConfig):
+    """Configuration for Acolyt skills."""
+
+    states: SkillStates
+    api_key: NotRequired[str]
+
+
+async def get_skills(
+    config: "Config",
+    is_private: bool,
+    store: SkillStoreABC,
+    **_,
+) -> list[AcolytBaseTool]:
+    """Get all Acolyt skills.
+
+    Args:
+        config: The configuration for Acolyt skills.
+        is_private: Whether to include private skills.
+        store: The skill store for persisting data.
+
+    Returns:
+        A list of Acolyt 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_acolyt_skill(name, store)
+        if skill:
+            result.append(skill)
+    return result
+
+
+def get_acolyt_skill(
+    name: str,
+    store: SkillStoreABC,
+) -> AcolytBaseTool | None:
+    """Get an Acolyt skill by name.
+
+    Args:
+        name: The name of the skill to get
+        store: The skill store for persisting data
+
+    Returns:
+        The requested Acolyt skill
+    """
+    if name == "ask_gpt":
+        if name not in _cache:
+            _cache[name] = AcolytAskGpt(
+                skill_store=store,
+            )
+        return _cache[name]
+    else:
+        logger.warning(f"Unknown Acolyt skill: {name}")
+        return None

intentkit/skills/acolyt/ask.py

@@ -0,0 +1,128 @@
+import logging
+from typing import Dict, Type
+
+import httpx
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+from intentkit.skills.acolyt.base import AcolytBaseTool
+
+from .base import base_url
+
+logger = logging.getLogger(__name__)
+
+
+class AcolytAskGptInput(BaseModel):
+    question: str
+
+
+class InputMessage(BaseModel):
+    role: Literal["system", "user", "assistant", "tool", "function"] = Field(
+        "user", description="The role of the message sender."
+    )
+    content: str
+
+
+class AcolytAskGptRequest(BaseModel):
+    messages: list[InputMessage]
+    model: str | None = Field("gpt-4o", description="The AI model to be used.")
+    stream: bool | None = Field(
+        False, description="To request for response of type stream."
+    )
+    temperature: float | None = Field(
+        0.7,
+        le=2,
+        ge=0,
+        description="Controls the degree of randomness in the generated text.",
+    )
+
+
+class AcolytAskGpt(AcolytBaseTool):
+    """
+    The Acolyt Data Fetcher is a versatile LangChain tool designed to interact with the Acolyt chat API to retrieve insightful data
+    across various categories, including Twitter Metrics, Onchain Analysis, DEX & Trading, and Overall Metrics. This tool seamlessly
+    processes user queries, fetches relevant data from the Acolyt API, and returns concise, summarized responses for easy consumption.
+
+    Features:
+    - Twitter Metrics: Retrieve engagement metrics for specific Twitter accounts, Identify which AI agents have the highest count of smart followers, Display the best tweets from specified accounts, Compare the mindshare between different AI agents, Determine which agents have the highest impressions-to-followers ratio.
+    - Onchain Analysis: Fetch the current market capitalization for tokens, Show the distribution of top holders for tokens, Identify tokens with the highest whale concentration, Compare holder retention rates between tokens, Calculate the Herfindahl index for tokens, List tokens with large amount of holders.
+    - DEX & Trading: Get the 24-hour trading volume for tokens, Identify which DEX has the highest liquidity for tokens, Obtain the buy/sell ratio for tokens over specific time periods. Compare price changes across different timeframes for tokens. List trading pairs with over a value in liquidity for tokens.
+    - Overall Metrics: Identify projects with the highest smart engagement relative to their market cap, Determine which agents have the best mindshare relative to their market cap. Compare the percentage of smart followers across the top n AI agents by market cap
+
+
+    Attributes:
+        name (str): Name of the tool, specifically "acolyt_ask_gpt".
+        description (str): Comprehensive description of the tool's purpose and functionality.
+        args_schema (Type[BaseModel]): Schema for input arguments, specifying expected parameters.
+    """
+
+    name: str = "acolyt_ask_gpt"
+    description: str = """
+        The Acolyt Data Fetcher is a LangChain tool accessing the Acolyt chat API for data across Twitter Metrics, Onchain Analysis, DEX & Trading, and Overall Metrics.  It processes queries, fetches data, and returns summarized responses. Features include:
+
+        Twitter: Engagement metrics, top smart follower counts, best tweets, mindshare comparison, impressions/follower ratio.
+        Onchain: Market cap, holder distribution, whale concentration, holder retention, Herfindahl index, high holder count tokens.
+        DEX & Trading: 24h volume, top DEX liquidity, buy/sell ratio, price change comparison, high liquidity pairs.
+        Overall: Smart engagement/market cap ratio, mindshare/market cap ratio, smart follower percentage comparison across top AI agents.
+        """
+    args_schema: Type[BaseModel] = AcolytAskGptInput
+
+    async def _arun(self, question: str, config: RunnableConfig, **kwargs) -> Dict:
+        """Run the tool to get answer from Acolyt GPT.
+
+        Args:
+            question (str): The question body from user.
+            config (RunnableConfig): The configuration for the runnable, containing agent context.
+
+        Returns:
+            Dict: The response from the API with message content.
+
+        Raises:
+            Exception: If there's an error accessing the Acolyt API.
+        """
+        context = self.context_from_config(config)
+        api_key = self.get_api_key(context)
+        if not api_key:
+            raise ValueError("Acolyt API key not found")
+
+        url = f"{base_url}/api/chat/completions"
+        headers = {
+            "accept": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        }
+
+        body = AcolytAskGptRequest(
+            messages=[InputMessage(content=question)],
+        ).model_dump(exclude_none=True)
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(
+                    url, headers=headers, timeout=30, json=body
+                )
+                response.raise_for_status()
+                json_dict = response.json()
+
+                # Extract message content directly
+                if "choices" in json_dict and len(json_dict["choices"]) > 0:
+                    if (
+                        "message" in json_dict["choices"][0]
+                        and "content" in json_dict["choices"][0]["message"]
+                    ):
+                        return json_dict
+                    else:
+                        raise ValueError("Unexpected response format from Acolyt API")
+                else:
+                    raise ValueError("Empty response from Acolyt API")
+
+            except httpx.RequestError as req_err:
+                raise ValueError(
+                    f"Request error from Acolyt API: {req_err}"
+                ) from req_err
+            except httpx.HTTPStatusError as http_err:
+                raise ValueError(
+                    f"HTTP error from Acolyt API: {http_err}"
+                ) from http_err
+            except Exception as e:
+                raise ValueError(f"Error from Acolyt API: {e}") from e

intentkit/skills/acolyt/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://acolyt-oracle-poc.vercel.app"
+
+
+class AcolytBaseTool(IntentKitSkill):
+    """Base class for Acolyt 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("acolyt_api_key")
+
+    @property
+    def category(self) -> str:
+        return "acolyt"

intentkit/skills/acolyt/schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Acolyt",
+  "description": "Integration with Acolyt Oracle providing blockchain oracle services for accessing and verifying off-chain data with secure API connections",
+  "x-icon": "https://ai.service.crestal.dev/skills/acolyt/acolyt.jpg",
+  "x-tags": [
+    "Blockchain",
+    "Oracle"
+  ],
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enabled",
+      "description": "Whether this skill is enabled",
+      "default": false
+    },
+    "states": {
+      "type": "object",
+      "properties": {
+        "ask_gpt": {
+          "type": "string",
+          "title": "Ask GPT",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "The Acolyt Data Fetcher is a LangChain tool accessing the Acolyt chat API for data across X Metrics, Onchain Analysis, DEX & Trading, and Overall Metrics. It processes queries, fetches data, and returns summarized responses. Features include:\n        Twitter: Engagement metrics, top smart follower counts, best tweets, mindshare comparison, impressions/follower ratio.\n        Onchain: Market cap, holder distribution, whale concentration, holder retention, Herfindahl index, high holder count tokens.\n        DEX & Trading: 24h volume, top DEX liquidity, buy/sell ratio, price change comparison, high liquidity pairs.\n        Overall: Smart engagement/market cap ratio, mindshare/market cap ratio, smart follower percentage comparison across top AI agents.",
+          "default": "disabled"
+        }
+      },
+      "description": "States for each Acolyt skill (disabled, public, or private)"
+    },
+    "api_key_provider": {
+      "type": "string",
+      "title": "API Key Provider",
+      "description": "Who provides 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": "Acolyt API Key",
+        "x-sensitive": true,
+        "description": "Acolyt API key for authentication"
+      }
+    },
+    "if": {
+      "properties": {
+        "enabled": {
+          "const": true
+        }
+      }
+    },
+    "then": {
+      "required": [
+        "api_key"
+      ]
+    }
+  },
+  "additionalProperties": true
+}

intentkit/skills/aixbt/README.md

@@ -0,0 +1,71 @@
+# AIXBT Skill
+
+This skill provides access to cryptocurrency project data and analytics through the AIXBT API.
+
+## Features
+
+- Search for cryptocurrency projects by name, ticker, or blockchain
+- Get detailed analysis and information about crypto projects
+- Filter projects by minimum score
+- View recent project updates and developments
+- Access project contact information and social media handles
+- Special "alpha" trigger for direct access to crypto research
+
+## Available Skills
+
+### aixbt_projects
+
+Searches for cryptocurrency projects and retrieves detailed information about them.
+
+#### Special Trigger
+
+This skill has a special trigger word: **"alpha"**
+
+When a user mentions the word "alpha" anywhere in their message, the AIXBT skill will be automatically triggered. This works with phrases like:
+- "Show me some alpha"
+- "What's the latest alpha on crypto?"
+- "Give me alpha on Bitcoin"
+- "I'm looking for alpha in DeFi projects"
+- Any other message containing the word "alpha"
+
+This gives users a convenient way to access crypto research data just by mentioning "alpha" in their questions or requests.
+
+#### Parameters
+
+| Name | Type | Description | Required | Default |
+|------|------|-------------|----------|---------|
+| limit | integer | Number of projects to return (max 50) | No | 10 |
+| name | string | Filter projects by name (case-insensitive regex match) | No | null |
+| ticker | string | Filter projects by ticker symbol (case-insensitive match) | No | null |
+| xHandle | string | Filter projects by X/Twitter handle | No | null |
+| minScore | number | Minimum score threshold | No | null |
+| chain | string | Filter projects by blockchain | No | null |
+
+## Example Usage
+
+### "Alpha" Trigger Examples
+
+**User:** "Show me some alpha"
+
+**Agent:** *Uses the aixbt_projects skill to search for trending cryptocurrency projects and provides comprehensive information about them.*
+
+**User:** "What's the latest alpha on Bitcoin?"
+
+**Agent:** *Uses the aixbt_projects skill to search specifically for Bitcoin and provides detailed information.*
+
+### Standard Query
+
+When a user asks about a cryptocurrency project:
+
+**User:** "Tell me about the Bitcoin project"
+
+**Agent:** *Uses the aixbt_projects skill to search for "bitcoin" and provides information including:*
+- Project score and analysis
+- Recent project updates
+- Social media information
+- Blockchain and token details
+
+## Links
+
+- [AIXBT Website](https://aixbt.tech/)
+- [API Documentation](https://api.aixbt.tech/v1/docs/)