Metadata-Version: 2.4
Name: crewai-xpoz
Version: 0.1.2
Summary: CrewAI tools for Xpoz social media intelligence — Twitter/X, Instagram, Reddit, TikTok
Author-email: Xpoz <support@xpoz.ai>
License-Expression: MIT
Project-URL: Homepage, https://xpoz.ai
Project-URL: Repository, https://github.com/XPOZpublic/crewai-xpoz
Project-URL: Issues, https://github.com/XPOZpublic/crewai-xpoz/issues
Keywords: crewai,xpoz,social-media,twitter,instagram,reddit,tiktok,osint,social-listening,brand-monitoring,influencer-discovery,ai-tools,llm-tools,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: crewai[tools]>=0.100.0
Requires-Dist: xpoz>=0.7.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"

# crewai-xpoz

CrewAI tools for [Xpoz](https://xpoz.ai) social media intelligence — access Twitter/X, Instagram, Reddit, and TikTok data in your CrewAI agents.

## Installation

```bash
pip install crewai-xpoz
```

Or via the CrewAI Tool Repository:

```bash
crewai tool install crewai-xpoz
```

## Quick Start

```python
import os
from crewai import Agent, Task, Crew
from crewai_xpoz import XpozTwitterSearch, XpozInstagramUser

os.environ["XPOZ_API_KEY"] = "your-xpoz-key"  # Get one at xpoz.ai/get-token
os.environ["OPENAI_API_KEY"] = "your-openai-key"

tools = [
    XpozTwitterSearch(),
    XpozInstagramUser(),
]

researcher = Agent(
    role="Social Media Analyst",
    goal="Analyze social media trends and brand presence",
    backstory="An expert social media analyst with deep knowledge of online trends",
    tools=tools,
    verbose=True,
)

task = Task(
    description="What are people saying about AI agents on Twitter this week?",
    expected_output="A summary of the key themes and sentiment around AI agents on Twitter",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()
```

You can also pass the API key directly:

```python
tools = [
    XpozTwitterSearch(api_key="your-xpoz-key"),
]
```

## Available Tools

### Twitter/X (13 tools)

| Tool | Description |
|------|-------------|
| `XpozTwitterSearch` | Search posts by keywords, hashtags, or phrases |
| `XpozTwitterUser` | Get a user profile by username or ID |
| `XpozTwitterUserPosts` | Get tweets posted by a specific user |
| `XpozTwitterPostComments` | Get replies/comments on a post |
| `XpozTwitterSearchUsers` | Search for users by name |
| `XpozTwitterUserConnections` | Get a user's followers or following |
| `XpozTwitterUsersByKeywords` | Find users who posted about specific topics |
| `XpozTwitterCountPosts` | Count posts matching a phrase |
| `XpozTwitterPostsByIds` | Get specific posts by their IDs |
| `XpozTwitterPostRetweets` | Get retweets of a post |
| `XpozTwitterPostQuotes` | Get quote tweets of a post |
| `XpozTwitterPostInteractingUsers` | Get users who liked/retweeted/quoted a post |
| `XpozTwitterUsers` | Get multiple user profiles by usernames or IDs |

### Instagram (9 tools)

| Tool | Description |
|------|-------------|
| `XpozInstagramSearch` | Search posts by keywords or phrases |
| `XpozInstagramUser` | Get a user profile by username or ID |
| `XpozInstagramUserPosts` | Get posts by a specific user |
| `XpozInstagramPostComments` | Get comments on a post |
| `XpozInstagramSearchUsers` | Search for users by name |
| `XpozInstagramUsersByKeywords` | Find users who posted about specific topics |
| `XpozInstagramPostsByIds` | Get specific posts by their IDs |
| `XpozInstagramUserConnections` | Get a user's followers or following |
| `XpozInstagramPostInteractingUsers` | Get users who liked or commented on a post |

### Reddit (9 tools)

| Tool | Description |
|------|-------------|
| `XpozRedditSearch` | Search posts by keywords or phrases |
| `XpozRedditUser` | Get a user profile by username |
| `XpozRedditPostWithComments` | Get a post with its comments |
| `XpozRedditSearchComments` | Search comments by keywords |
| `XpozRedditSearchSubreddits` | Search for subreddits by name or topic |
| `XpozRedditSubreddit` | Get a subreddit's info and recent posts |
| `XpozRedditUsersByKeywords` | Find users who posted about specific topics |
| `XpozRedditSearchUsers` | Search for users by name |
| `XpozRedditSubredditsByKeywords` | Find subreddits related to keywords |

### TikTok (9 tools)

| Tool | Description |
|------|-------------|
| `XpozTiktokSearch` | Search posts by keywords or phrases |
| `XpozTiktokUser` | Get a user profile by username or ID |
| `XpozTiktokUserPosts` | Get videos posted by a specific user |
| `XpozTiktokPostComments` | Get comments on a video |
| `XpozTiktokSearchUsers` | Search for users by name |
| `XpozTiktokPostsByHashtags` | Search posts by hashtags |
| `XpozTiktokUsersByKeywords` | Find creators who posted about specific topics |
| `XpozTiktokPostsByIds` | Get specific videos by their IDs |
| `XpozTiktokUsersByHashtags` | Find creators who posted with specific hashtags |

### Tracking (3 tools)

| Tool | Description |
|------|-------------|
| `XpozGetTrackedItems` | List all currently tracked items |
| `XpozAddTrackedItems` | Add items to track across platforms |
| `XpozRemoveTrackedItems` | Remove items from tracking |

### Account (1 tool)

| Tool | Description |
|------|-------------|
| `XpozAccountDetails` | Get account details, plan info, and credit usage |

## Authentication

Get a free API key at [xpoz.ai/get-token](https://xpoz.ai/get-token).

Set it via environment variable:

```bash
export XPOZ_API_KEY=your-key
```

Or pass it directly when creating tools:

```python
tool = XpozTwitterSearch(api_key="your-key")
```

## Publishing

To publish to the CrewAI Tool Repository:

```bash
crewai tool publish --public
```

## Links

- [Xpoz Platform](https://xpoz.ai)
- [Documentation](https://xpoz.ai/docs)
- [Get API Key](https://xpoz.ai/get-token)
