ai-mirow-projects
/
swarms
mirror of https://github.com/kyegomez/swarms
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[TWITTER AGENTS]

Browse Source
pull/741/merge
Kye Gomez 2 weeks ago
parent c9b2079710
commit be62d30303
1 changed files with 429 additions and 249 deletions
Show Stats Download Patch File Download Diff File

664
docs/swarms_tools/twitter.md
Unescape View File

@ -1,353 +1,533 @@
# TwitterTool Documentation # TwitterTool Technical Documentation
## Overview ## Class Overview
The TwitterTool is a powerful Python-based interface for interacting with Twitter's API, designed specifically for integration with autonomous agents and AI systems. It provides a streamlined way to perform common Twitter operations while maintaining proper error handling and logging capabilities. The TwitterTool class provides a comprehensive interface for interacting with Twitter's API. It encapsulates common Twitter operations and provides error handling, logging, and integration capabilities with AI agents.
## Installation ## Installation Requirements
Before using the TwitterTool, ensure you have the required dependencies installed:
```bash ```bash
pip install tweepy swarms-tools pip install swarms-tools
``` ```
## Basic Configuration ## Class Definition
The TwitterTool requires Twitter API credentials for authentication. Here's how to set up the basic configuration: ### Constructor Parameters
```python The `options` dictionary accepts the following keys:
from swarms_tools.social_media.twitter_tool import TwitterTool
import os | Parameter | Type | Required | Default | Description |
|-----------|------|----------|----------|-------------|
| id | str | No | "twitter_plugin" | Unique identifier for the tool instance |
| name | str | No | "Twitter Plugin" | Display name for the tool |
| description | str | No | Default description | Tool description |
| credentials | Dict[str, str] | Yes | None | Twitter API credentials |
options = { The `credentials` dictionary requires:
"id": "your_unique_id",
"name": "your_tool_name",
"description": "Your tool description",
"credentials": {
"apiKey": os.getenv("TWITTER_API_KEY"),
"apiSecretKey": os.getenv("TWITTER_API_SECRET_KEY"),
"accessToken": os.getenv("TWITTER_ACCESS_TOKEN"),
"accessTokenSecret": os.getenv("TWITTER_ACCESS_TOKEN_SECRET")
}
}
twitter_tool = TwitterTool(options) | Credential | Type | Required | Description |
|------------|------|----------|-------------|
| apiKey | str | Yes | Twitter API key |
| apiSecretKey | str | Yes | Twitter API secret key |
| accessToken | str | Yes | Twitter access token |
| accessTokenSecret | str | Yes | Twitter access token secret |
## Public Methods
### available_functions
```python
@property
def available_functions(self) -> List[str]
``` ```
For security, it's recommended to use environment variables for credentials: Returns a list of available function names that can be executed by the tool.
**Returns:**
- List[str]: Names of available functions ['get_metrics', 'reply_tweet', 'post_tweet', 'like_tweet', 'quote_tweet']
**Example:**
```python ```python
import os twitter_tool = TwitterTool(options)
from dotenv import load_dotenv functions = twitter_tool.available_functions
print(f"Available functions: {functions}")
```
load_dotenv() ### get_function
options = { ```python
"id": "twitter_bot", def get_function(self, fn_name: str) -> Callable
"name": "Twitter Bot",
"credentials": {
"apiKey": os.getenv("TWITTER_API_KEY"),
"apiSecretKey": os.getenv("TWITTER_API_SECRET_KEY"),
"accessToken": os.getenv("TWITTER_ACCESS_TOKEN"),
"accessTokenSecret": os.getenv("TWITTER_ACCESS_TOKEN_SECRET")
}
}
``` ```
## Core Functionality Retrieves a specific function by name for execution.
The TwitterTool provides five main functions: **Parameters:**
- fn_name (str): Name of the function to retrieve
1. **Posting Tweets**: Create new tweets **Returns:**
2. **Replying to Tweets**: Respond to existing tweets - Callable: The requested function
3. **Quoting Tweets**: Share tweets with additional commentary
4. **Liking Tweets**: Engage with other users' content
5. **Fetching Metrics**: Retrieve account statistics
### Basic Usage Examples **Raises:**
- ValueError: If the function name is not found
**Example:**
```python ```python
# Get a specific function
post_tweet = twitter_tool.get_function('post_tweet') post_tweet = twitter_tool.get_function('post_tweet')
reply_tweet = twitter_tool.get_function('reply_tweet') metrics_fn = twitter_tool.get_function('get_metrics')
quote_tweet = twitter_tool.get_function('quote_tweet') ```
like_tweet = twitter_tool.get_function('like_tweet')
get_metrics = twitter_tool.get_function('get_metrics')
# Post a tweet ## Protected Methods
post_tweet("Hello, Twitter!")
# Reply to a tweet ### _get_metrics
reply_tweet(tweet_id=123456789, reply="Great point!")
# Quote a tweet ```python
quote_tweet(tweet_id=123456789, quote="Interesting perspective!") def _get_metrics(self) -> Dict[str, int]
```
Fetches user metrics including followers, following, and tweet counts.
# Like a tweet **Returns:**
like_tweet(tweet_id=123456789) - Dict[str, int]: Dictionary containing metrics
- followers: Number of followers
- following: Number of accounts following
- tweets: Total tweet count
# Get account metrics **Example:**
metrics = get_metrics() ```python
metrics = twitter_tool._get_metrics()
print(f"Followers: {metrics['followers']}") print(f"Followers: {metrics['followers']}")
print(f"Following: {metrics['following']}")
print(f"Total tweets: {metrics['tweets']}")
``` ```
## Integration with Agents ### _reply_tweet
The TwitterTool can be particularly powerful when integrated with AI agents. Here are several examples of agent integrations: ```python
def _reply_tweet(self, tweet_id: int, reply: str) -> None
```
### 1. Medical Information Bot Posts a reply to a specific tweet.
This example shows how to create a medical information bot that shares health facts: **Parameters:**
- tweet_id (int): ID of the tweet to reply to
- reply (str): Text content of the reply
**Example:**
```python ```python
from swarms import Agent twitter_tool._reply_tweet(
from swarms_models import OpenAIChat tweet_id=1234567890,
reply="Thank you for sharing this insight!"
# Initialize the AI model
model = OpenAIChat(
model_name="gpt-4",
max_tokens=3000,
openai_api_key=os.getenv("OPENAI_API_KEY")
) )
```
# Create a medical expert agent ### _post_tweet
medical_expert = Agent(
agent_name="Medical Expert",
system_prompt="""
You are a medical expert sharing evidence-based health information.
Your tweets should be:
- Accurate and scientifically sound
- Easy to understand
- Engaging and relevant
- Within Twitter's character limit
""",
llm=model
)
# Function to generate and post medical tweets ```python
def post_medical_fact(): def _post_tweet(self, tweet: str) -> Dict[str, Any]
prompt = "Share an interesting medical fact that would be helpful for the general public."
tweet_text = medical_expert.run(prompt)
post_tweet = twitter_tool.get_function('post_tweet')
post_tweet(tweet_text)
``` ```
### 2. News Summarization Bot Creates a new tweet.
This example demonstrates how to create a bot that summarizes news articles: **Parameters:**
- tweet (str): Text content of the tweet
**Returns:**
- Dict[str, Any]: Response from Twitter API
**Example:**
```python ```python
# Create a news summarization agent twitter_tool._post_tweet(
news_agent = Agent( tweet="Exploring the fascinating world of AI and machine learning! #AI #ML"
agent_name="News Summarizer",
system_prompt="""
You are a skilled news editor who excels at creating concise,
accurate summaries of news articles while maintaining the key points.
Your summaries should be:
- Factual and unbiased
- Clear and concise
- Properly attributed
- Under 280 characters
""",
llm=model
) )
```
def summarize_and_tweet(article_url): ### _like_tweet
# Generate summary
prompt = f"Summarize this news article in a tweet-length format: {article_url}"
summary = news_agent.run(prompt)
# Post the summary ```python
post_tweet = twitter_tool.get_function('post_tweet') def _like_tweet(self, tweet_id: int) -> None
post_tweet(f"{summary} Source: {article_url}")
``` ```
### 3. Interactive Q&A Bot Likes a specific tweet.
This example shows how to create a bot that responds to user questions: **Parameters:**
- tweet_id (int): ID of the tweet to like
**Example:**
```python ```python
class TwitterQABot: twitter_tool._like_tweet(tweet_id=1234567890)
def __init__(self): ```
self.twitter_tool = TwitterTool(options)
self.qa_agent = Agent( ### _quote_tweet
agent_name="Q&A Expert",
system_prompt=""" ```python
You are an expert at providing clear, concise answers to questions. def _quote_tweet(self, tweet_id: int, quote: str) -> None
Your responses should be: ```
- Accurate and informative
- Conversational in tone
- Limited to 280 characters
- Include relevant hashtags when appropriate
""",
llm=model
)
def handle_question(self, tweet_id, question): Creates a quote tweet.
# Generate response
response = self.qa_agent.run(f"Answer this question: {question}")
# Reply to the tweet **Parameters:**
reply_tweet = self.twitter_tool.get_function('reply_tweet') - tweet_id (int): ID of the tweet to quote
reply_tweet(tweet_id=tweet_id, reply=response) - quote (str): Text content to add to the quote
qa_bot = TwitterQABot() **Example:**
qa_bot.handle_question(123456789, "What causes climate change?") ```python
twitter_tool._quote_tweet(
tweet_id=1234567890,
quote="This is a fascinating perspective on AI development!"
)
``` ```
## Best Practices ## Integration Examples
When using the TwitterTool, especially with agents, consider these best practices: ### Basic Usage with Environment Variables
1. **Rate Limiting**: Implement delays between tweets to comply with Twitter's rate limits:
```python ```python
import time import os
from dotenv import load_dotenv
from swarms_tools import TwitterTool
def post_with_rate_limit(tweet_text, delay=60): load_dotenv()
post_tweet = twitter_tool.get_function('post_tweet')
post_tweet(tweet_text) options = {
time.sleep(delay) # Wait 60 seconds between tweets "id": "twitter_bot",
"name": "AI Twitter Bot",
"description": "An AI-powered Twitter bot",
"credentials": {
"apiKey": os.getenv("TWITTER_API_KEY"),
"apiSecretKey": os.getenv("TWITTER_API_SECRET_KEY"),
"accessToken": os.getenv("TWITTER_ACCESS_TOKEN"),
"accessTokenSecret": os.getenv("TWITTER_ACCESS_TOKEN_SECRET"),
}
}
twitter_tool = TwitterTool(options)
``` ```
2. **Content Tracking**: Maintain a record of posted content to avoid duplicates: ### Integration with AI Agent for Content Generation
```python ```python
posted_tweets = set() from swarms import Agent
from swarms_models import OpenAIChat
from swarms_tools import TwitterTool
import os
def post_unique_tweet(tweet_text): from dotenv import load_dotenv
if tweet_text not in posted_tweets:
post_tweet = twitter_tool.get_function('post_tweet') load_dotenv()
post_tweet(tweet_text)
posted_tweets.add(tweet_text) # Initialize the model
model = OpenAIChat(
model_name="gpt-4",
max_tokens=3000,
openai_api_key=os.getenv("OPENAI_API_KEY")
)
# Create content generation agent
content_agent = Agent(
agent_name="Content Creator",
system_prompt="""
You are an expert content creator for Twitter.
Create engaging, informative tweets that:
1. Are under 280 characters
2. Use appropriate hashtags
3. Maintain a professional tone
4. Include relevant calls to action
""",
llm=model
)
class TwitterContentBot:
def __init__(self, twitter_tool: TwitterTool, agent: Agent):
self.twitter_tool = twitter_tool
self.agent = agent
self.post_tweet = twitter_tool.get_function('post_tweet')
def generate_and_post(self, topic: str) -> None:
"""
Generates and posts content about a specific topic.
Args:
topic (str): The topic to create content about
"""
prompt = f"Create an engaging tweet about {topic}"
tweet_content = self.agent.run(prompt)
self.post_tweet(tweet_content)
# Usage
bot = TwitterContentBot(twitter_tool, content_agent)
bot.generate_and_post("artificial intelligence")
``` ```
3. **Error Handling**: Implement robust error handling for API failures: ### Automated Engagement System
```python ```python
def safe_tweet(tweet_text): import time
from typing import List, Dict
class TwitterEngagementSystem:
def __init__(self, twitter_tool: TwitterTool):
self.twitter_tool = twitter_tool
self.like_tweet = twitter_tool.get_function('like_tweet')
self.reply_tweet = twitter_tool.get_function('reply_tweet')
self.get_metrics = twitter_tool.get_function('get_metrics')
# Track engagement history
self.engagement_history: List[Dict] = []
def engage_with_tweet(self, tweet_id: int, should_like: bool = True,
reply_text: Optional[str] = None) -> None:
"""
Engages with a specific tweet through likes and replies.
Args:
tweet_id (int): The ID of the tweet to engage with
should_like (bool): Whether to like the tweet
reply_text (Optional[str]): Text to reply with, if any
"""
try: try:
post_tweet = twitter_tool.get_function('post_tweet') if should_like:
post_tweet(tweet_text) self.like_tweet(tweet_id)
if reply_text:
self.reply_tweet(tweet_id, reply_text)
# Record engagement
self.engagement_history.append({
'timestamp': time.time(),
'tweet_id': tweet_id,
'actions': {
'liked': should_like,
'replied': bool(reply_text)
}
})
except Exception as e: except Exception as e:
logging.error(f"Failed to post tweet: {e}") print(f"Failed to engage with tweet {tweet_id}: {e}")
# Implement retry logic or fallback behavior
# Usage
engagement_system = TwitterEngagementSystem(twitter_tool)
engagement_system.engage_with_tweet(
tweet_id=1234567890,
should_like=True,
reply_text="Great insights! Thanks for sharing."
)
``` ```
4. **Content Validation**: Validate content before posting: ### Scheduled Content System
```python
def validate_and_post(tweet_text):
if len(tweet_text) > 280:
tweet_text = tweet_text[:277] + "..."
# Check for prohibited content ```python
prohibited_terms = ["spam", "inappropriate"] import schedule
if any(term in tweet_text.lower() for term in prohibited_terms): from datetime import datetime, timedelta
return False
post_tweet = twitter_tool.get_function('post_tweet') class ScheduledTwitterBot:
post_tweet(tweet_text) def __init__(self, twitter_tool: TwitterTool, agent: Agent):
return True self.twitter_tool = twitter_tool
self.agent = agent
self.post_tweet = twitter_tool.get_function('post_tweet')
self.posted_tweets: List[str] = []
def generate_daily_content(self) -> None:
"""
Generates and posts daily content based on the current date.
"""
today = datetime.now()
prompt = f"""
Create an engaging tweet for {today.strftime('%A, %B %d')}.
Focus on technology trends and insights.
"""
tweet_content = self.agent.run(prompt)
# Avoid duplicate content
if tweet_content not in self.posted_tweets:
self.post_tweet(tweet_content)
self.posted_tweets.append(tweet_content)
# Keep only last 100 tweets in memory
if len(self.posted_tweets) > 100:
self.posted_tweets.pop(0)
# Usage
scheduled_bot = ScheduledTwitterBot(twitter_tool, content_agent)
# Schedule daily posts
schedule.every().day.at("10:00").do(scheduled_bot.generate_daily_content)
schedule.every().day.at("15:00").do(scheduled_bot.generate_daily_content)
# Run the scheduler
while True:
schedule.run_pending()
time.sleep(60)
``` ```
## Advanced Features ## Error Handling
### Scheduled Posting
Implement scheduled posting using Python's built-in scheduling capabilities: The TwitterTool implements comprehensive error handling through try-except blocks. All methods catch and handle `tweepy.TweepyException` for Twitter API-specific errors. Here's an example of implementing custom error handling:
```python ```python
from datetime import datetime class TwitterToolWithCustomErrors(TwitterTool):
import schedule def _post_tweet(self, tweet: str) -> Dict[str, Any]:
"""
Enhanced tweet posting with custom error handling.
def scheduled_tweet_job(): Args:
twitter_tool = TwitterTool(options) tweet (str): The tweet content to post
post_tweet = twitter_tool.get_function('post_tweet')
# Generate content using an agent Returns:
content = medical_expert.run("Generate a health tip of the day") Dict[str, Any]: Response from Twitter API
post_tweet(content)
# Schedule tweets for specific times Raises:
schedule.every().day.at("10:00").do(scheduled_tweet_job) ValueError: If tweet exceeds character limit
schedule.every().day.at("15:00").do(scheduled_tweet_job) """
if len(tweet) > 280:
raise ValueError("Tweet exceeds 280 character limit")
while True: try:
schedule.run_pending() return super()._post_tweet(tweet)
time.sleep(60) except tweepy.TweepyException as e:
self.logger.error(f"Twitter API error: {e}")
raise
``` ```
### Analytics Integration ## Rate Limiting
Track the performance of your tweets: Twitter's API has rate limits that should be respected. Here's an example implementation of rate limiting:
```python ```python
class TweetAnalytics: from time import time, sleep
def __init__(self, twitter_tool): from collections import deque
self.twitter_tool = twitter_tool
self.metrics_history = [] class RateLimitedTwitterTool(TwitterTool):
def __init__(self, options: Dict[str, Any]) -> None:
def record_metrics(self): super().__init__(options)
get_metrics = self.twitter_tool.get_function('get_metrics') self.tweet_timestamps = deque(maxlen=300) # Track last 300 tweets
current_metrics = get_metrics() self.max_tweets_per_15min = 300
self.metrics_history.append({
'timestamp': datetime.now(), def _check_rate_limit(self) -> None:
'metrics': current_metrics """
}) Checks if we're within rate limits and waits if necessary.
"""
now = time()
# Remove timestamps older than 15 minutes
while self.tweet_timestamps and self.tweet_timestamps[0] < now - 900:
self.tweet_timestamps.popleft()
if len(self.tweet_timestamps) >= self.max_tweets_per_15min:
sleep_time = 900 - (now - self.tweet_timestamps[0])
if sleep_time > 0:
sleep(sleep_time)
self.tweet_timestamps.append(now)
def _post_tweet(self, tweet: str) -> Dict[str, Any]:
self._check_rate_limit()
return super()._post_tweet(tweet)
```
def get_growth_rate(self): ## Best Practices
if len(self.metrics_history) < 2:
return None
latest = self.metrics_history[-1]['metrics'] 1. Always use environment variables for credentials:
previous = self.metrics_history[-2]['metrics'] ```python
from dotenv import load_dotenv
load_dotenv()
return { options = {
'followers_growth': latest['followers'] - previous['followers'], "credentials": {
'tweets_growth': latest['tweets'] - previous['tweets'] "apiKey": os.getenv("TWITTER_API_KEY"),
"apiSecretKey": os.getenv("TWITTER_API_SECRET_KEY"),
"accessToken": os.getenv("TWITTER_ACCESS_TOKEN"),
"accessTokenSecret": os.getenv("TWITTER_ACCESS_TOKEN_SECRET")
} }
}
``` ```
## Troubleshooting 2. Implement proper logging:
```python
Common issues and their solutions: import logging
1. **Authentication Errors**: Double-check your API credentials and ensure they're properly loaded from environment variables. logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)
```
2. **Rate Limiting**: If you encounter rate limit errors, implement exponential backoff: 3. Use type hints consistently:
```python ```python
import time from typing import Optional, Dict, Any, List
from random import uniform
def process_tweet(
tweet_id: int,
action: str,
content: Optional[str] = None
) -> Dict[str, Any]:
pass
```
def exponential_backoff(attempt): 4. Handle API rate limits gracefully:
wait_time = min(300, (2 ** attempt) + uniform(0, 1)) ```python
time.sleep(wait_time) from time import sleep
def retry_post(tweet_text, max_attempts=5): def retry_with_backoff(func, max_retries: int = 3):
for attempt in range(max_attempts): for attempt in range(max_retries):
try: try:
post_tweet = twitter_tool.get_function('post_tweet') return func()
post_tweet(tweet_text) except tweepy.TweepyException as e:
if attempt == max_retries - 1:
raise
sleep_time = (2 ** attempt) + random.uniform(0, 1)
sleep(sleep_time)
```
5. Validate input data:
```python
def validate_tweet(tweet: str) -> bool:
if not tweet or len(tweet) > 280:
return False
return True return True
except Exception as e:
if attempt < max_attempts - 1:
exponential_backoff(attempt)
else:
raise e
``` ```
3. **Content Length Issues**: Implement automatic content truncation: ## Testing
Example of a basic test suite for the TwitterTool:
```python ```python
def truncate_tweet(text, max_length=280): from swarms_tools import TwitterTool
if len(text) <= max_length: import os
return text from dotenv import load_dotenv
load_dotenv()
def test_twitter_tool():
# Test configuration
options = {
"id": "test_bot",
"credentials": {
"apiKey": os.getenv("TWITTER_API_KEY"),
"apiSecretKey": os.getenv("TWITTER_API_SECRET_KEY"),
"accessToken": os.getenv("TWITTER_ACCESS_TOKEN"),
"accessTokenSecret": os.getenv("TWITTER_ACCESS_TOKEN_SECRET")
}
}
# Initialize tool
tool = TwitterTool(options)
# Test available functions
assert 'post_tweet' in tool.available_functions
assert 'get_metrics' in tool.available_functions
# Try to break at last space before limit # Test function retrieval
truncated = text[:max_length-3] post_tweet = tool.get_function('post_tweet')
last_space = truncated.rfind(' ') assert callable(post_tweet)
if last_space > 0:
truncated = truncated[:last_space]
return truncated + "..." # Test metrics
metrics = tool._get_metrics()
assert isinstance(metrics, dict)
assert 'followers' in metrics
assert 'following' in metrics
assert 'tweets' in metrics
``` ```
Remember to regularly check Twitter's API documentation for any updates or changes to rate limits and functionality. The TwitterTool is designed to be extensible, so you can add new features as needed for your specific use case. Remember to always test your code thoroughly before deploying it in a production environment. The TwitterTool is designed to be extensible, so you can add new features and customizations as needed for your specific use case.
Write Preview
Loading…
Cancel
Save