Metadata-Version: 2.4
Name: llama-index-tools-xpoz
Version: 0.1.1
Summary: Xpoz social media intelligence tools for LlamaIndex agents — Twitter/X, Instagram, Reddit, and TikTok
Project-URL: Homepage, https://xpoz.ai
Project-URL: Repository, https://github.com/XPOZpublic/llama-index-tools-xpoz
Project-URL: Issues, https://github.com/XPOZpublic/llama-index-tools-xpoz/issues
Project-URL: Documentation, https://xpoz.ai/docs
Author-email: Xpoz <support@xpoz.ai>
Maintainer-email: Xpoz <support@xpoz.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,instagram,llama-index,llamaindex,osint,reddit,social-listening,social-media,tiktok,twitter,xpoz
Requires-Python: <4.0,>=3.10
Requires-Dist: llama-index-core<0.15,>=0.13.0
Requires-Dist: xpoz>=0.7.0
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# llama-index-tools-xpoz

Xpoz social media intelligence tools for LlamaIndex agents: search and analyze **Twitter/X, Instagram, Reddit, and TikTok** (posts, user profiles, comments, engagement data) with no social media API keys required.

## Installation

```bash
pip install llama-index-tools-xpoz
```

Get a free access key at [xpoz.ai/get-token](https://xpoz.ai/get-token) (no credit card) and set it:

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

## Usage

Five tool specs, one per domain. Give an agent only the platforms it needs:

```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.xpoz import XpozTwitterToolSpec, XpozRedditToolSpec

tools = XpozTwitterToolSpec().to_tool_list() + XpozRedditToolSpec().to_tool_list()

agent = FunctionAgent(
    tools=tools,
    llm=OpenAI(model="gpt-5.4"),
    system_prompt="You are a social media research assistant. Use the Xpoz tools for data.",
)

response = await agent.run("What are people saying about AI agents on Twitter and Reddit?")
print(response)
```

Or call tools directly:

```python
from llama_index.tools.xpoz import XpozTwitterToolSpec

spec = XpozTwitterToolSpec()
result = spec.search_twitter_posts("AI agents", limit=5)
```

Pass `api_key` explicitly instead of using the environment variable: `XpozTwitterToolSpec(api_key="...")`.

## Tool specs

| Spec | Tools |
| --- | --- |
| `XpozTwitterToolSpec` | search posts, user profile, user posts, post comments, search users, followers/following, users by keywords, count posts |
| `XpozInstagramToolSpec` | search posts, user profile, user posts, post comments, search users, users by keywords |
| `XpozRedditToolSpec` | search posts, post with comments, search comments, user profile, search subreddits, subreddit with posts, subreddits by keywords |
| `XpozTiktokToolSpec` | search videos, videos by hashtags, creator profile, creator videos, video comments, search creators, creators by hashtags |
| `XpozTrackingToolSpec` | list/add/remove tracked items, account details |

## Tips

- When you want the most recent posts, omit `start_date` / `end_date`.
- Use the `fields` parameter to keep responses small, e.g. `["text", "like_count", "created_at"]`.
- Tracked keywords and users are crawled continuously, which gives later searches better coverage.

## Links

[Xpoz](https://xpoz.ai) · [Docs](https://xpoz.ai/docs) · [Get a token](https://xpoz.ai/get-token) · support@xpoz.ai

## License

MIT
