arcade-x 0.0.13__py3-none-any.whl

arcade_x/tools/tweets.py

@@ -0,0 +1,159 @@
+from typing import Annotated
+
+import httpx
+
+from arcade.core.errors import ToolExecutionError
+from arcade.core.schema import ToolContext
+from arcade.sdk import tool
+from arcade.sdk.auth import X
+from arcade_x.tools.utils import (
+    expand_urls_in_tweets,
+    get_tweet_url,
+    parse_search_recent_tweets_response,
+)
+
+TWEETS_URL = "https://api.x.com/2/tweets"
+
+
+# Manage Tweets Tools. See developer docs for additional available parameters: https://developer.x.com/en/docs/x-api/tweets/manage-tweets/api-reference
+@tool(
+    requires_auth=X(
+        scopes=["tweet.read", "tweet.write", "users.read"],
+    )
+)
+async def post_tweet(
+    context: ToolContext,
+    tweet_text: Annotated[str, "The text content of the tweet you want to post"],
+) -> Annotated[str, "Success string and the URL of the tweet"]:
+    """Post a tweet to X (Twitter)."""
+
+    headers = {
+        "Authorization": f"Bearer {context.authorization.token}",
+        "Content-Type": "application/json",
+    }
+    payload = {"text": tweet_text}
+
+    async with httpx.AsyncClient() as client:
+        response = await client.post(TWEETS_URL, headers=headers, json=payload, timeout=10)
+
+    if response.status_code != 201:
+        raise ToolExecutionError(
+            f"Failed to post a tweet during execution of '{post_tweet.__name__}' tool. Request returned an error: {response.status_code} {response.text}"
+        )
+
+    tweet_id = response.json()["data"]["id"]
+    return f"Tweet with id {tweet_id} posted successfully. URL: {get_tweet_url(tweet_id)}"
+
+
+@tool(requires_auth=X(scopes=["tweet.read", "tweet.write", "users.read"]))
+async def delete_tweet_by_id(
+    context: ToolContext,
+    tweet_id: Annotated[str, "The ID of the tweet you want to delete"],
+) -> Annotated[str, "Success string confirming the tweet deletion"]:
+    """Delete a tweet on X (Twitter)."""
+
+    headers = {"Authorization": f"Bearer {context.authorization.token}"}
+    url = f"{TWEETS_URL}/{tweet_id}"
+
+    async with httpx.AsyncClient() as client:
+        response = await client.delete(url, headers=headers, timeout=10)
+
+    if response.status_code != 200:
+        raise ToolExecutionError(
+            f"Failed to delete the tweet during execution of '{delete_tweet_by_id.__name__}' tool. Request returned an error: {response.status_code} {response.text}"
+        )
+
+    return f"Tweet with id {tweet_id} deleted successfully."
+
+
+@tool(requires_auth=X(scopes=["tweet.read", "users.read"]))
+async def search_recent_tweets_by_username(
+    context: ToolContext,
+    username: Annotated[str, "The username of the X (Twitter) user to look up"],
+    max_results: Annotated[
+        int, "The maximum number of results to return. Cannot be less than 10"
+    ] = 10,
+) -> Annotated[dict, "Dictionary containing the search results"]:
+    """Search for recent tweets (last 7 days) on X (Twitter) by username. Includes replies and reposts."""
+
+    headers = {
+        "Authorization": f"Bearer {context.authorization.token}",
+        "Content-Type": "application/json",
+    }
+    params = {
+        "query": f"from:{username}",
+        "max_results": max(max_results, 10),  # X API does not allow 'max_results' less than 10
+    }
+    url = "https://api.x.com/2/tweets/search/recent?expansions=author_id&user.fields=id,name,username,entities&tweet.fields=entities"
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, headers=headers, params=params, timeout=10)
+
+    if response.status_code != 200:
+        raise ToolExecutionError(
+            f"Failed to search recent tweets during execution of '{search_recent_tweets_by_username.__name__}' tool. Request returned an error: {response.status_code} {response.text}"
+        )
+
+    response_data = response.json()
+
+    # Expand the urls that are in the tweets
+    expand_urls_in_tweets(response_data.get("data", []), delete_entities=True)
+
+    parse_search_recent_tweets_response(response_data)
+
+    return response_data
+
+
+@tool(requires_auth=X(scopes=["tweet.read", "users.read"]))
+async def search_recent_tweets_by_keywords(
+    context: ToolContext,
+    keywords: Annotated[
+        list[str] | None, "List of keywords that must be present in the tweet"
+    ] = None,
+    phrases: Annotated[
+        list[str] | None, "List of phrases that must be present in the tweet"
+    ] = None,
+    max_results: Annotated[
+        int, "The maximum number of results to return. Cannot be less than 10"
+    ] = 10,
+) -> Annotated[dict, "Dictionary containing the search results"]:
+    """
+    Search for recent tweets (last 7 days) on X (Twitter) by required keywords and phrases. Includes replies and reposts
+    One of the following input parametersMUST be provided: keywords, phrases
+    """
+
+    if not any([keywords, phrases]):
+        raise ValueError(
+            "At least one of keywords or phrases must be provided to the '{search_recent_tweets_by_keywords.__name__}' tool."
+        )
+
+    headers = {
+        "Authorization": f"Bearer {context.authorization.token}",
+        "Content-Type": "application/json",
+    }
+    query = "".join([f'"{phrase}" ' for phrase in (phrases or [])])
+    if keywords:
+        query += " ".join(keywords or [])
+
+    params = {
+        "query": query,
+        "max_results": max(max_results, 10),  # X API does not allow 'max_results' less than 10
+    }
+    url = "https://api.x.com/2/tweets/search/recent?expansions=author_id&user.fields=id,name,username,entities&tweet.fields=entities"
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, headers=headers, params=params, timeout=10)
+
+    if response.status_code != 200:
+        raise ToolExecutionError(
+            f"Failed to search recent tweets during execution of '{search_recent_tweets_by_keywords.__name__}' tool. Request returned an error: {response.status_code} {response.text}"
+        )
+
+    response_data = response.json()
+
+    # Expand the urls that are in the tweets
+    expand_urls_in_tweets(response_data.get("data", []), delete_entities=True)
+
+    parse_search_recent_tweets_response(response_data)
+
+    return response_data

arcade_x/tools/users.py

@@ -0,0 +1,65 @@
+from typing import Annotated
+
+import httpx
+
+from arcade.core.errors import ToolExecutionError
+from arcade.core.schema import ToolContext
+from arcade.sdk import tool
+from arcade.sdk.auth import X
+from arcade_x.tools.utils import expand_urls_in_user_description, expand_urls_in_user_url
+
+
+# Users Lookup Tools. See developer docs for additional available query parameters: https://developer.x.com/en/docs/x-api/users/lookup/api-reference
+@tool(requires_auth=X(scopes=["users.read", "tweet.read"]))
+async def lookup_single_user_by_username(
+    context: ToolContext,
+    username: Annotated[str, "The username of the X (Twitter) user to look up"],
+) -> Annotated[dict, "User information including id, name, username, and description"]:
+    """Look up a user on X (Twitter) by their username."""
+
+    headers = {
+        "Authorization": f"Bearer {context.authorization.token}",
+    }
+    url = f"https://api.x.com/2/users/by/username/{username}?user.fields=created_at,description,id,location,most_recent_tweet_id,name,pinned_tweet_id,profile_image_url,protected,public_metrics,url,username,verified,verified_type,withheld,entities"
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, headers=headers, timeout=10)
+
+    if response.status_code != 200:
+        raise ToolExecutionError(
+            f"Failed to look up user during execution of '{lookup_single_user_by_username.__name__}' tool. Request returned an error: {response.status_code} {response.text}"
+        )
+
+    # Parse the response JSON
+    user_data = response.json()["data"]
+
+    expand_urls_in_user_description(user_data, delete_entities=False)
+    expand_urls_in_user_url(user_data, delete_entities=True)
+
+    """
+    Example response["data"] structure:
+    {
+        "data": {
+            "verified_type": str,
+            "public_metrics": {
+                "followers_count": int,
+                "following_count": int,
+                "tweet_count": int,
+                "listed_count": int,
+                "like_count": int
+            },
+            "id": str,
+            "most_recent_tweet_id": str,
+            "url": str,
+            "verified": bool,
+            "location": str,
+            "description": str,
+            "name": str,
+            "username": str,
+            "profile_image_url": str,
+            "created_at": str,
+            "protected": bool
+        }
+    }
+    """
+    return {"data": user_data}

arcade_x/tools/utils.py

@@ -0,0 +1,107 @@
+from typing import Any
+
+
+def get_tweet_url(tweet_id: str) -> str:
+    """Get the URL of a tweet given its ID."""
+    return f"https://x.com/x/status/{tweet_id}"
+
+
+def parse_search_recent_tweets_response(response_data: Any) -> dict:
+    """
+    Parses response from the X API search recent tweets endpoint.
+    Returns a JSON string with the tweets data.
+
+    Example parsed response:
+    "tweets": [
+        {
+            "author_id": "558248927",
+            "id": "1838272933141319832",
+            "edit_history_tweet_ids": [
+                "1838272933141319832"
+            ],
+            "text": "PR pending on @LangChainAI, will be integrated there soon! https://t.co/DPWd4lccQo",
+            "tweet_url": "https://x.com/x/status/1838272933141319832",
+            "author_username": "tomas_hk",
+            "author_name": "Tomas Hernando Kofman"
+        },
+    ]
+    """
+
+    if not sanity_check_tweets_data(response_data):
+        return {"data": []}
+
+    for tweet in response_data["data"]:
+        tweet["tweet_url"] = get_tweet_url(tweet["id"])
+
+    for tweet_data, user_data in zip(response_data["data"], response_data["includes"]["users"]):
+        tweet_data["author_username"] = user_data["username"]
+        tweet_data["author_name"] = user_data["name"]
+
+    return response_data
+
+
+def sanity_check_tweets_data(tweets_data: dict) -> bool:
+    """
+    Sanity check the tweets data.
+    Returns True if the tweets data is valid and contains tweets, False otherwise.
+    """
+    if not tweets_data.get("data", []):
+        return False
+    return tweets_data.get("includes", {}).get("users", [])
+
+
+def expand_urls_in_tweets(tweets_data: list[dict], delete_entities: bool = True) -> None:
+    """
+    Expands the urls in the test of the provided tweets.
+    X shortens urls, and consequently, this can cause language models to hallucinate.
+    See more about X's link shortner at https://help.x.com/en/using-x/url-shortener
+    """
+    for tweet_data in tweets_data:
+        if "entities" in tweet_data and "urls" in tweet_data["entities"]:
+            for url_entity in tweet_data["entities"]["urls"]:
+                short_url = url_entity["url"]
+                expanded_url = url_entity["expanded_url"]
+                tweet_data["text"] = tweet_data["text"].replace(short_url, expanded_url)
+
+        if delete_entities:
+            tweet_data.pop(
+                "entities", None
+            )  # Now that we've expanded the urls in the tweet, we no longer need the entities
+
+
+def expand_urls_in_user_description(user_data: dict, delete_entities: bool = True) -> None:
+    """
+    Expands the urls in the description of the provided user.
+    X shortens urls, and consequently, this can cause language models to hallucinate.
+    See more about X's link shortner at https://help.x.com/en/using-x/url-shortener
+    """
+    description_urls = user_data.get("entities", {}).get("description", {}).get("urls", [])
+    description = user_data.get("description", "")
+    for url_info in description_urls:
+        t_co_link = url_info["url"]
+        expanded_url = url_info["expanded_url"]
+        description = description.replace(t_co_link, expanded_url)
+    user_data["description"] = description
+
+    if delete_entities:
+        # Entities is no longer needed now that we have expanded the t.co links
+        user_data.pop("entities", None)
+
+
+def expand_urls_in_user_url(user_data: dict, delete_entities: bool = True) -> None:
+    """
+    Expands the urls in the url section of the provided user.
+    X shortens urls, and consequently, this can cause language models to hallucinate.
+    See more about X's link shortner at https://help.x.com/en/using-x/url-shortener
+    """
+    url_urls = user_data.get("entities", {}).get("url", {}).get("urls", [])
+    url = user_data.get("url", "")
+    for url_info in url_urls:
+        t_co_link = url_info["url"]
+        expanded_url = url_info["expanded_url"]
+        url = url.replace(t_co_link, expanded_url)
+    user_data["url"] = url
+
+    if delete_entities:
+        # Entities is no longer needed now that we have expanded the t.co links
+        user_data.pop("entities", None)

arcade_x-0.0.13.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.1
+Name: arcade_x
+Version: 0.0.13
+Summary: LLM tools for interacting with X (Twitter)
+Author: Arcade AI
+Author-email: dev@arcade-ai.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: arcade-ai (==0.0.13)
+Requires-Dist: httpx (>=0.27.2,<0.28.0)

arcade_x-0.0.13.dist-info/RECORD

@@ -0,0 +1,8 @@
+arcade_x/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arcade_x/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arcade_x/tools/tweets.py,sha256=SZht8WD03Kxmgxx9GSYTSC9BuXCkJp6NTUo5-VpiL1w,6088
+arcade_x/tools/users.py,sha256=tGI2KXF_S4YaABKihLS0B7VgG8A5XOfynA-uYXKyxlU,2432
+arcade_x/tools/utils.py,sha256=VwssFULxj0zysJdZHnbs9NE4h3JLGSm6SCVhfu-lx-Q,4137
+arcade_x-0.0.13.dist-info/METADATA,sha256=32mRyE0YEhHzCXdvE0Kp395JV05gpFaanqyZfyKkKPY,512
+arcade_x-0.0.13.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+arcade_x-0.0.13.dist-info/RECORD,,

arcade_x-0.0.13.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.1
+Root-Is-Purelib: true
+Tag: py3-none-any