arcade-x 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

arcade_x/tools/tweets.py

@@ -1,12 +1,13 @@
-from typing import Annotated
+from typing import Annotated, Any
 
 import httpx
-
 from arcade.sdk import ToolContext, tool
 from arcade.sdk.auth import X
-from arcade.sdk.errors import ToolExecutionError
+from arcade.sdk.errors import RetryableToolError
+
 from arcade_x.tools.utils import (
     expand_urls_in_tweets,
+    get_headers_with_token,
     get_tweet_url,
     parse_search_recent_tweets_response,
 )
@@ -14,7 +15,10 @@ from arcade_x.tools.utils import (
 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
+# 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"],
@@ -26,19 +30,12 @@ async def post_tweet(
 ) -> 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",
-    }
+    headers = get_headers_with_token(context)
     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}"
-        )
+        response.raise_for_status()
 
     tweet_id = response.json()["data"]["id"]
     return f"Tweet with id {tweet_id} posted successfully. URL: {get_tweet_url(tweet_id)}"
@@ -51,16 +48,12 @@ async def delete_tweet_by_id(
 ) -> Annotated[str, "Success string confirming the tweet deletion"]:
     """Delete a tweet on X (Twitter)."""
 
-    headers = {"Authorization": f"Bearer {context.authorization.token}"}
+    headers = get_headers_with_token(context)
     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}"
-        )
+        response.raise_for_status()
 
     return f"Tweet with id {tweet_id} deleted successfully."
 
@@ -72,33 +65,33 @@ async def search_recent_tweets_by_username(
     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."""
+) -> Annotated[dict[str, Any], "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 = {
+    headers = get_headers_with_token(context)
+    params: dict[str, int | str] = {
         "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"
+    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)
+        response.raise_for_status()
 
-    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()
+    response_data: dict[str, Any] = response.json()
 
-    # Expand the urls that are in the tweets
-    expand_urls_in_tweets(response_data.get("data", []), delete_entities=True)
+    # Expand the URLs that are in the tweets
+    response_data["data"] = expand_urls_in_tweets(
+        response_data.get("data", []), delete_entities=True
+    )
 
-    parse_search_recent_tweets_response(response_data)
+    # Parse the response data
+    response_data = parse_search_recent_tweets_response(response_data)
 
     return response_data
 
@@ -115,44 +108,81 @@ async def search_recent_tweets_by_keywords(
     max_results: Annotated[
         int, "The maximum number of results to return. Cannot be less than 10"
     ] = 10,
-) -> Annotated[dict, "Dictionary containing the search results"]:
+) -> Annotated[dict[str, Any], "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
+    Search for recent tweets (last 7 days) on X (Twitter) by required keywords and phrases.
+    Includes replies and reposts.
+    One of the following input parameters MUST 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."
+        raise RetryableToolError(  # noqa: TRY003
+            "No keywords or phrases provided",
+            developer_message="Predicted inputs didn't contain any keywords or phrases",
+            additional_prompt_content="Please provide at least one keyword or phrase for search",
+            retry_after_ms=500,  # Play nice with X API rate limits
         )
 
-    headers = {
-        "Authorization": f"Bearer {context.authorization.token}",
-        "Content-Type": "application/json",
-    }
+    headers = get_headers_with_token(context)
+
     query = "".join([f'"{phrase}" ' for phrase in (phrases or [])])
     if keywords:
         query += " ".join(keywords or [])
 
-    params = {
-        "query": query,
+    params: dict[str, int | str] = {
+        "query": query.strip(),
         "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"
+    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)
+        response.raise_for_status()
 
-    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: dict[str, Any] = response.json()
+
+    # Expand the URLs that are in the tweets
+    response_data["data"] = expand_urls_in_tweets(
+        response_data.get("data", []), delete_entities=True
+    )
+
+    # Parse the response data
+    response_data = parse_search_recent_tweets_response(response_data)
+
+    return response_data
 
-    response_data = response.json()
 
-    # Expand the urls that are in the tweets
-    expand_urls_in_tweets(response_data.get("data", []), delete_entities=True)
+@tool(requires_auth=X(scopes=["tweet.read", "users.read"]))
+async def lookup_tweet_by_id(
+    context: ToolContext,
+    tweet_id: Annotated[str, "The ID of the tweet you want to look up"],
+) -> Annotated[dict[str, Any], "Dictionary containing the tweet data"]:
+    """Look up a tweet on X (Twitter) by tweet ID."""
+
+    headers = get_headers_with_token(context)
+    params = {
+        "expansions": "author_id",
+        "user.fields": "id,name,username,entities",
+        "tweet.fields": "entities",
+    }
+    url = f"{TWEETS_URL}/{tweet_id}"
 
-    parse_search_recent_tweets_response(response_data)
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, headers=headers, params=params, timeout=10)
+        response.raise_for_status()
+
+    response_data: dict[str, Any] = response.json()
+
+    # Get the tweet data
+    tweet_data = response_data.get("data")
+    if tweet_data:
+        # Expand the URLs that are in the tweet
+        expanded_tweet_list = expand_urls_in_tweets([tweet_data], delete_entities=True)
+        response_data["data"] = expanded_tweet_list[0]
+    else:
+        response_data["data"] = {}
 
     return response_data

arcade_x/tools/users.py

@@ -1,14 +1,20 @@
 from typing import Annotated
 
 import httpx
-
 from arcade.sdk import ToolContext, tool
 from arcade.sdk.auth import X
-from arcade.sdk.errors import ToolExecutionError
-from arcade_x.tools.utils import expand_urls_in_user_description, expand_urls_in_user_url
+from arcade.sdk.errors import RetryableToolError
+
+from arcade_x.tools.utils import (
+    expand_urls_in_user_description,
+    expand_urls_in_user_url,
+    get_headers_with_token,
+)
+
+# Users Lookup Tools. See developer docs for additional available query parameters:
+# https://developer.x.com/en/docs/x-api/users/lookup/api-reference
 
 
-# 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,
@@ -16,49 +22,43 @@ async def lookup_single_user_by_username(
 ) -> 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"
+    headers = get_headers_with_token(context)
+
+    user_fields = ",".join([
+        "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",
+    ])
+    url = f"https://api.x.com/2/users/by/username/{username}?user.fields={user_fields}"
 
     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}"
-        )
-
+        if response.status_code == 404:
+            # User not found
+            raise RetryableToolError(  # noqa: TRY003
+                "User not found",
+                developer_message=f"User with username '{username}' not found.",
+                additional_prompt_content="Please check the username and try again.",
+                retry_after_ms=500,  # Play nice with X API rate limits
+            )
+        response.raise_for_status()
     # 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)
+    user_data = expand_urls_in_user_description(user_data, delete_entities=False)
+    user_data = 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

@@ -1,38 +1,40 @@
 from typing import Any
 
+from arcade.sdk import ToolContext
+from arcade.sdk.errors import ToolExecutionError
+
 
 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:
+def get_headers_with_token(context: ToolContext) -> dict[str, str]:
+    """Get the headers for a request to the X API."""
+    if context.authorization is None or context.authorization.token is None:
+        raise ToolExecutionError(  # noqa: TRY003
+            "Missing Token. Authorization is required to post a tweet.",
+            developer_message="Token is not set in the ToolContext.",
+        )
+    return {
+        "Authorization": f"Bearer {context.authorization.token}",
+        "Content-Type": "application/json",
+    }
+
+
+def parse_search_recent_tweets_response(response_data: dict[str, Any]) -> dict[str, Any]:
     """
     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"
-        },
-    ]
+    Returns the modified response data with added 'tweet_url', 'author_username', and 'author_name'.
     """
-
     if not sanity_check_tweets_data(response_data):
         return {"data": []}
 
+    # Add 'tweet_url' to each tweet
     for tweet in response_data["data"]:
         tweet["tweet_url"] = get_tweet_url(tweet["id"])
 
+    # Add 'author_username' and 'author_name' to each tweet
     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"]
@@ -40,68 +42,71 @@ def parse_search_recent_tweets_response(response_data: Any) -> dict:
     return response_data
 
 
-def sanity_check_tweets_data(tweets_data: dict) -> bool:
+def sanity_check_tweets_data(tweets_data: dict[str, Any]) -> 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", []):
+    if not tweets_data.get("data"):
+        return False
+    # prefer clarity over appeasing linter here
+    if not tweets_data.get("includes", {}).get("users"):  # noqa: SIM103
         return False
-    return tweets_data.get("includes", {}).get("users", [])
+    return True
 
 
-def expand_urls_in_tweets(tweets_data: list[dict], delete_entities: bool = True) -> None:
+def expand_urls_in_tweets(
+    tweets_data: list[dict[str, Any]], delete_entities: bool = True
+) -> list[dict[str, Any]]:
     """
-    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
+    Returns a new list of tweets with expanded URLs.
     """
+    new_tweets = []
     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"]:
+        new_tweet = tweet_data.copy()
+        if "entities" in new_tweet and "urls" in new_tweet["entities"]:
+            for url_entity in new_tweet["entities"]["urls"]:
                 short_url = url_entity["url"]
                 expanded_url = url_entity["expanded_url"]
-                tweet_data["text"] = tweet_data["text"].replace(short_url, expanded_url)
+                new_tweet["text"] = new_tweet["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
+            new_tweet.pop("entities", None)
+        new_tweets.append(new_tweet)
+    return new_tweets
 
 
-def expand_urls_in_user_description(user_data: dict, delete_entities: bool = True) -> None:
+def expand_urls_in_user_description(user_data: dict, delete_entities: bool = True) -> dict:
     """
-    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
+    Returns a new user data dict with expanded URLs in the description.
     """
-    description_urls = user_data.get("entities", {}).get("description", {}).get("urls", [])
-    description = user_data.get("description", "")
+    new_user_data = user_data.copy()
+    description_urls = new_user_data.get("entities", {}).get("description", {}).get("urls", [])
+    description = new_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
+    new_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)
+        new_user_data.pop("entities", None)
+    return new_user_data
 
 
-def expand_urls_in_user_url(user_data: dict, delete_entities: bool = True) -> None:
+def expand_urls_in_user_url(user_data: dict, delete_entities: bool = True) -> dict:
     """
-    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
+    Returns a new user data dict with expanded URLs in the URL field.
     """
-    url_urls = user_data.get("entities", {}).get("url", {}).get("urls", [])
-    url = user_data.get("url", "")
+    new_user_data = user_data.copy()
+    url_urls = new_user_data.get("entities", {}).get("url", {}).get("urls", [])
+    url = new_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
+    new_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)
+        new_user_data.pop("entities", None)
+    return new_user_data

arcade_x-0.1.3.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, arcadeai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{arcade_x-0.1.2.dist-info → arcade_x-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: arcade_x
-Version: 0.1.2
+Version: 0.1.3
 Summary: LLM tools for interacting with X (Twitter)
 Author: Arcade AI
 Author-email: dev@arcade-ai.com
@@ -10,5 +10,5 @@ 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.1.2)
+Requires-Dist: arcade-ai (==0.1.3)
 Requires-Dist: httpx (>=0.27.2,<0.28.0)

arcade_x-0.1.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+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=IDAjx1j_XLoc7ILyuRKVyjTPwQeNtD47lnyKUMO-WpU,6594
+arcade_x/tools/users.py,sha256=zNACU9UhQJkGNnrei-E6GWvFnbDzg0YG9pkdplu8TzM,2148
+arcade_x/tools/utils.py,sha256=VEeUo715m6l6X9Syszy2E72rdvv4h_tc-P7wMaQEbGo,4044
+arcade_x-0.1.3.dist-info/LICENSE,sha256=SphQPbiNmBD1J6yJ7oxG9bIZDbj8lNHKSv5Kl86zA40,1066
+arcade_x-0.1.3.dist-info/METADATA,sha256=ApdteSqGUDAmg1_Wy70XPdfvFLuA5xx_foKjbtRnw1c,510
+arcade_x-0.1.3.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+arcade_x-0.1.3.dist-info/RECORD,,

arcade_x-0.1.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-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=jSpaY0soU-ncouf6mVUoWSgbf_1R88xlgSDdS7dvKr4,6057
-arcade_x/tools/users.py,sha256=P72TE7Pncfjr1CePiaRB0nyT9XEn4As01tRKtKHQ6QY,2401
-arcade_x/tools/utils.py,sha256=VwssFULxj0zysJdZHnbs9NE4h3JLGSm6SCVhfu-lx-Q,4137
-arcade_x-0.1.2.dist-info/METADATA,sha256=9V_QlVdZpirA75y2_uqUTUwxAXk1_ovau3Q0boL9lU0,510
-arcade_x-0.1.2.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-arcade_x-0.1.2.dist-info/RECORD,,