twittrapi-haystack 0.1.0__py3-none-any.whl

haystack_integrations/components/websearch/twittrapi/__init__.py

@@ -0,0 +1,3 @@
+from .tweet_search import TwittrAPITweetSearch, tweet_to_document, user_to_document
+
+__all__ = ["TwittrAPITweetSearch", "tweet_to_document", "user_to_document"]

haystack_integrations/components/websearch/twittrapi/tweet_search.py

@@ -0,0 +1,179 @@
+"""Haystack component that searches X (Twitter) through TwittrAPI and returns Documents."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from haystack import Document, component, default_from_dict, default_to_dict, logging
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+from twittrapi import TwittrAPI, TwittrAPIError
+
+logger = logging.getLogger(__name__)
+
+SearchCategory = Literal["Top", "Latest", "People", "Photos", "Videos"]
+
+
+def tweet_to_document(tweet: dict[str, Any]) -> Document:
+    """Turns one simple-format tweet into a Document: the text as content, the rest as meta."""
+    author = tweet.get("author") or {}
+    counts = tweet.get("counts") or {}
+    username = author.get("username")
+    url = tweet.get("url") or (
+        f"https://x.com/{username}/status/{tweet['id']}" if username and tweet.get("id") else None
+    )
+    meta = {
+        "id": tweet.get("id"),
+        "url": url,
+        "created_at": tweet.get("createdAt"),
+        "lang": tweet.get("lang"),
+        "author_id": author.get("id"),
+        "author_username": username,
+        "author_name": author.get("name"),
+        "likes": counts.get("likes", 0),
+        "retweets": counts.get("retweets", 0),
+        "replies": counts.get("replies", 0),
+        "quotes": counts.get("quotes", 0),
+        "views": counts.get("views", 0),
+        "conversation_id": tweet.get("conversationId"),
+    }
+    return Document(content=tweet.get("text") or "", meta={k: v for k, v in meta.items() if v is not None})
+
+
+def user_to_document(user: dict[str, Any]) -> Document:
+    """Turns one simple-format user (category People) into a Document."""
+    counts = user.get("counts") or {}
+    username = user.get("username")
+    content = f"{user.get('name') or username} (@{username})"
+    if user.get("description"):
+        content += f": {user['description']}"
+    meta = {
+        "id": user.get("id"),
+        "url": f"https://x.com/{username}" if username else None,
+        "username": username,
+        "name": user.get("name"),
+        "followers": counts.get("followers", 0),
+        "following": counts.get("following", 0),
+        "verified": user.get("verified"),
+        "created_at": user.get("createdAt"),
+    }
+    return Document(content=content, meta={k: v for k, v in meta.items() if v is not None})
+
+
+@component
+class TwittrAPITweetSearch:
+    """
+    Searches X (Twitter) through [TwittrAPI](https://www.twittrapi.com) and returns the results as Documents.
+
+    The query takes the same operators as the X search box (`from:`, `lang:`, `since:`,
+    `min_faves:`, `"exact phrase"`, `-filter:replies`, ...). Each tweet becomes one Document: the
+    full text as `content`, the author, URL, time and engagement counts in `meta`. With
+    `category="People"` the results are accounts instead of tweets.
+
+    The output has the same `documents` and `links` keys as the other web-search components,
+    plus `next_cursor` for the next page.
+
+    Usage example:
+    ```python
+    from haystack_integrations.components.websearch.twittrapi import TwittrAPITweetSearch
+
+    search = TwittrAPITweetSearch(top_k=20)  # reads TWITTRAPI_API_KEY
+    result = search.run(query="haystack lang:en -filter:replies")
+    for doc in result["documents"]:
+        print(doc.meta["author_username"], doc.content)
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: Secret = Secret.from_env_var("TWITTRAPI_API_KEY"),
+        category: SearchCategory = "Latest",
+        top_k: int | None = 20,
+        base_url: str | None = None,
+    ) -> None:
+        """
+        Creates a TwittrAPITweetSearch component.
+
+        :param api_key: TwittrAPI key, sent as `X-API-KEY`. Defaults to the `TWITTRAPI_API_KEY`
+            environment variable.
+        :param category: Search tab: `"Latest"` (newest first), `"Top"`, `"People"`,
+            `"Photos"` or `"Videos"`. Can be changed per `run`.
+        :param top_k: Results to request per page (1 to 100) and the most Documents returned.
+            `None` uses the API default of 20 and keeps everything X returns.
+        :param base_url: Override the API base URL. Rarely needed.
+        """
+        if top_k is not None and not 1 <= top_k <= 100:
+            raise ValueError("top_k must be between 1 and 100, or None.")
+        self.api_key = api_key
+        self.category = category
+        self.top_k = top_k
+        self.base_url = base_url
+        self._client: TwittrAPI | None = None
+
+    def warm_up(self) -> None:
+        """Creates the API client."""
+        if self._client is None:
+            kwargs: dict[str, Any] = {"api_key": self.api_key.resolve_value()}
+            if self.base_url:
+                kwargs["base_url"] = self.base_url
+            self._client = TwittrAPI(**kwargs)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serializes the component to a dictionary."""
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            category=self.category,
+            top_k=self.top_k,
+            base_url=self.base_url,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TwittrAPITweetSearch:
+        """Deserializes the component from a dictionary."""
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)
+
+    @component.output_types(documents=list[Document], links=list[str], next_cursor=str | None)
+    def run(
+        self,
+        query: str,
+        category: SearchCategory | None = None,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Searches X and returns one page of results.
+
+        :param query: Search query in X search syntax, e.g. `from:deepset_ai lang:en`.
+        :param category: Overrides the search tab set at init.
+        :param cursor: `next_cursor` from a previous run, to get the next page.
+        :returns: A dictionary with:
+            - `documents`: one Document per tweet (or per account for `People`).
+            - `links`: the URL of each result, in the same order.
+            - `next_cursor`: cursor for the next page, `None` on the last page.
+        :raises TwittrAPIError: when the API answers with an error (invalid key, no balance,
+            bad query).
+        """
+        self.warm_up()
+        assert self._client is not None
+        tab = category or self.category
+        page = self._client.search.tweets(
+            query,
+            category=tab,
+            count=self.top_k,
+            cursor=cursor,
+            response_format="simple",
+        )
+        items = page.get("data") if isinstance(page, dict) else None
+        rows = [row for row in (items or []) if isinstance(row, dict) and not row.get("unavailable")]
+        if self.top_k is not None:
+            rows = rows[: self.top_k]
+        to_doc = user_to_document if tab == "People" else tweet_to_document
+        documents = [to_doc(row) for row in rows]
+        links = [doc.meta["url"] for doc in documents if doc.meta.get("url")]
+        next_cursor = page.get("nextCursor") if isinstance(page, dict) and page.get("hasNextPage") else None
+        logger.debug("TwittrAPI search returned {count} documents", count=len(documents))
+        return {"documents": documents, "links": links, "next_cursor": next_cursor}
+
+
+__all__ = ["TwittrAPIError", "TwittrAPITweetSearch", "tweet_to_document", "user_to_document"]

haystack_integrations/tools/twittrapi/__init__.py

@@ -0,0 +1,3 @@
+from .toolset import TOOL_NAMES, TwittrAPIToolset
+
+__all__ = ["TOOL_NAMES", "TwittrAPIToolset"]

haystack_integrations/tools/twittrapi/toolset.py

@@ -0,0 +1,324 @@
+"""Haystack Toolset with read-only X (Twitter) tools backed by TwittrAPI."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from haystack.core.serialization import generate_qualified_class_name
+from haystack.tools import Tool, Toolset
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+from twittrapi import TwittrAPI, TwittrAPIError
+
+DEFAULT_MAX_CHARS = 20_000
+
+_NUMERIC = {"type": "string", "pattern": r"^\d{1,30}$"}
+_CURSOR = {
+    "type": "string",
+    "description": "Pagination cursor. Leave out for the first page; pass next_cursor from a "
+    "previous result to get the next page.",
+}
+
+
+def _count(what: str) -> dict[str, Any]:
+    return {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 100,
+        "description": f"How many {what} to request per page (default 20).",
+    }
+
+
+_USER_TARGET = {
+    "user_id": {**_NUMERIC, "description": "Numeric X user ID. Preferred over username."},
+    "username": {"type": "string", "description": 'X handle, e.g. "deepset_ai" (a leading @ is fine).'},
+}
+
+
+def _schema(properties: dict[str, Any], required: list[str] | None = None) -> dict[str, Any]:
+    schema: dict[str, Any] = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def _user_target(args: dict[str, Any]) -> dict[str, Any]:
+    """Returns user_id or username for the SDK's per-user methods (the ID wins)."""
+    if args.get("user_id"):
+        return {"user_id": args["user_id"]}
+    handle = str(args.get("username") or "").strip().lstrip("@").strip()
+    if handle:
+        return {"username": handle}
+    raise ValueError("Provide either user_id or username.")
+
+
+def _page(args: dict[str, Any]) -> dict[str, Any]:
+    return {"count": args.get("count"), "cursor": args.get("cursor")}
+
+
+def _truncate(text: str, max_chars: int) -> str:
+    if len(text) <= max_chars:
+        return text
+    return (
+        text[:max_chars] + f"\n\n[TRUNCATED: showing the first {max_chars} of {len(text)} characters. The JSON above "
+        "is incomplete. Request a smaller count or use the cursor to see the rest.]"
+    )
+
+
+def format_result(data: Any, max_chars: int, paginated: bool) -> str:
+    """Compact JSON for the model, cut at max_chars. Paginated results print the cursor first,
+    outside the budget, so the agent can keep paging even when the JSON is cut."""
+    text = _truncate(json.dumps(data, ensure_ascii=False, separators=(",", ":")), max_chars)
+    if not paginated or not isinstance(data, dict):
+        return text
+    cursor = data.get("nextCursor") if data.get("hasNextPage") else None
+    if not cursor:
+        return f"next_cursor: none (last page)\n\n{text}"
+    return f"next_cursor: {cursor}\nPass next_cursor as `cursor` to get the next page.\n\n{text}"
+
+
+@dataclass(frozen=True)
+class _Spec:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    call: Callable[[TwittrAPI, dict[str, Any]], Any]
+    paginated: bool = False
+
+
+_SPECS: list[_Spec] = [
+    _Spec(
+        "search_tweets",
+        "Search X (Twitter) like the search box. Supports X search operators in the query, e.g. "
+        'from:user, to:user, "exact phrase", lang:en, since:2026-01-01, until:2026-02-01, '
+        "min_faves:100, filter:media, -filter:replies. category Latest gives newest first; "
+        "People returns accounts instead of tweets. Paginated.",
+        _schema(
+            {
+                "query": {"type": "string", "description": "Search query in X search syntax."},
+                "category": {
+                    "type": "string",
+                    "enum": ["Top", "Latest", "People", "Photos", "Videos"],
+                    "description": "Search tab (default Top).",
+                },
+                "count": _count("results"),
+                "cursor": _CURSOR,
+            },
+            ["query"],
+        ),
+        lambda api, a: api.search.tweets(a["query"], category=a.get("category"), **_page(a), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_user_by_username",
+        "Get an X user's profile by handle: name, bio, follower and following counts, "
+        "verification, created date and the numeric user ID other tools take.",
+        _schema({"username": _USER_TARGET["username"]}, ["username"]),
+        lambda api, a: api.users.get_by_username(_user_target(a)["username"], response_format="simple"),
+    ),
+    _Spec(
+        "get_user_by_id",
+        "Get an X user's profile by numeric user ID.",
+        _schema({"user_id": _USER_TARGET["user_id"]}, ["user_id"]),
+        lambda api, a: api.users.get_by_id(a["user_id"], response_format="simple"),
+    ),
+    _Spec(
+        "get_user_tweets",
+        "Get a user's recent tweets, newest first. Takes user_id or username. Paginated.",
+        _schema({**_USER_TARGET, "count": _count("tweets"), "cursor": _CURSOR}),
+        lambda api, a: api.users.tweets(**_user_target(a), **_page(a), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_followers",
+        "Get accounts that follow a user. Takes user_id or username. Paginated.",
+        _schema({**_USER_TARGET, "count": _count("accounts"), "cursor": _CURSOR}),
+        lambda api, a: api.users.followers(**_user_target(a), **_page(a), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_following",
+        "Get accounts a user follows. Takes user_id or username. Paginated.",
+        _schema({**_USER_TARGET, "count": _count("accounts"), "cursor": _CURSOR}),
+        lambda api, a: api.users.following(**_user_target(a), **_page(a), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_tweet",
+        "Get a tweet by ID with full text, author, media, engagement counts and its reply "
+        "thread. Use cursor to load more replies.",
+        _schema({"tweet_id": {**_NUMERIC, "description": "Numeric tweet ID."}, "cursor": _CURSOR}, ["tweet_id"]),
+        lambda api, a: api.tweets.get(a["tweet_id"], cursor=a.get("cursor"), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_tweet_retweets",
+        "Get the accounts that retweeted a tweet. Paginated.",
+        _schema(
+            {
+                "tweet_id": {**_NUMERIC, "description": "Numeric tweet ID."},
+                "count": _count("accounts"),
+                "cursor": _CURSOR,
+            },
+            ["tweet_id"],
+        ),
+        lambda api, a: api.tweets.retweeters(a["tweet_id"], **_page(a), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_tweet_quotes",
+        "Get tweets that quote a given tweet. Paginated.",
+        _schema(
+            {
+                "tweet_id": {**_NUMERIC, "description": "Numeric tweet ID."},
+                "count": _count("tweets"),
+                "cursor": _CURSOR,
+            },
+            ["tweet_id"],
+        ),
+        lambda api, a: api.tweets.quotes(a["tweet_id"], **_page(a), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_list_tweets",
+        "Get the latest tweets from an X List. Paginated.",
+        _schema(
+            {"list_id": {**_NUMERIC, "description": "Numeric List ID."}, "count": _count("tweets"), "cursor": _CURSOR},
+            ["list_id"],
+        ),
+        lambda api, a: api.lists.tweets(a["list_id"], **_page(a), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_community_tweets",
+        "Get tweets posted in an X Community. Paginated.",
+        _schema(
+            {
+                "community_id": {**_NUMERIC, "description": "Numeric Community ID."},
+                "count": _count("tweets"),
+                "cursor": _CURSOR,
+            },
+            ["community_id"],
+        ),
+        lambda api, a: api.communities.tweets(a["community_id"], **_page(a), response_format="simple"),
+        paginated=True,
+    ),
+    _Spec(
+        "get_trends",
+        "Get trending topics for a location. location_id is a WOEID: 1 is worldwide, "
+        "23424977 the United States; get_trend_locations lists them all.",
+        _schema({"location_id": {**_NUMERIC, "description": "WOEID, default 1 (worldwide)."}}),
+        lambda api, a: api.trends.get(a.get("location_id") or 1, response_format="simple"),
+    ),
+    _Spec(
+        "get_trend_locations",
+        "List the locations (WOEIDs) that have trends.",
+        _schema({}),
+        lambda api, a: api.trends.locations(response_format="simple"),
+    ),
+]
+
+TOOL_NAMES: list[str] = [spec.name for spec in _SPECS]
+
+
+class TwittrAPIToolset(Toolset):
+    """
+    Read-only X (Twitter) tools for Haystack Agents, backed by [TwittrAPI](https://www.twittrapi.com).
+
+    Tools: search_tweets, get_user_by_username, get_user_by_id, get_user_tweets,
+    get_followers, get_following, get_tweet, get_tweet_retweets, get_tweet_quotes,
+    get_list_tweets, get_community_tweets, get_trends, get_trend_locations.
+
+    Results are the API's compact simple format (flat camelCase JSON), cut at `max_chars`.
+    Paginated tools print `next_cursor` first so the agent can ask for the next page. API errors
+    (bad ID, no balance) come back to the agent as the tool result instead of raising.
+
+    Usage example:
+    ```python
+    from haystack.components.agents import Agent
+    from haystack.components.generators.chat import OpenAIChatGenerator
+    from haystack.dataclasses import ChatMessage
+    from haystack_integrations.tools.twittrapi import TwittrAPIToolset
+
+    agent = Agent(
+        chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+        tools=TwittrAPIToolset(),  # reads TWITTRAPI_API_KEY
+    )
+    result = agent.run(messages=[ChatMessage.from_user("What is @deepset_ai posting about this week?")])
+    print(result["messages"][-1].text)
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: Secret = Secret.from_env_var("TWITTRAPI_API_KEY"),
+        tool_names: list[str] | None = None,
+        max_chars: int = DEFAULT_MAX_CHARS,
+        base_url: str | None = None,
+    ) -> None:
+        """
+        Creates the toolset.
+
+        :param api_key: TwittrAPI key, sent as `X-API-KEY`. Defaults to the `TWITTRAPI_API_KEY`
+            environment variable.
+        :param tool_names: Only include these tools. `None` includes all of them.
+        :param max_chars: Most characters of JSON a tool returns; longer output is cut with a marker.
+        :param base_url: Override the API base URL. Rarely needed.
+        """
+        unknown = sorted(set(tool_names or []) - set(TOOL_NAMES))
+        if unknown:
+            raise ValueError(f"Unknown TwittrAPI tools: {', '.join(unknown)}. Available: {', '.join(TOOL_NAMES)}")
+        if max_chars < 100:
+            raise ValueError("max_chars must be at least 100.")
+        self.api_key = api_key
+        self.tool_names = list(tool_names) if tool_names is not None else None
+        self.max_chars = max_chars
+        self.base_url = base_url
+        self._client: TwittrAPI | None = None
+        selected = [spec for spec in _SPECS if tool_names is None or spec.name in tool_names]
+        super().__init__(tools=[self._make_tool(spec) for spec in selected])
+
+    def _get_client(self) -> TwittrAPI:
+        if self._client is None:
+            kwargs: dict[str, Any] = {"api_key": self.api_key.resolve_value()}
+            if self.base_url:
+                kwargs["base_url"] = self.base_url
+            self._client = TwittrAPI(**kwargs)
+        return self._client
+
+    def _make_tool(self, spec: _Spec) -> Tool:
+        def invoke(**kwargs: Any) -> str:
+            try:
+                data = spec.call(self._get_client(), kwargs)
+            except TwittrAPIError as exc:
+                return f"TwittrAPI error: {exc}"
+            except (ValueError, TypeError) as exc:
+                return f"Invalid arguments: {exc}"
+            return format_result(data, self.max_chars, spec.paginated)
+
+        return Tool(name=spec.name, description=spec.description, parameters=spec.parameters, function=invoke)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serializes the toolset by its settings, not by its tools."""
+        return {
+            "type": generate_qualified_class_name(type(self)),
+            "data": {
+                "api_key": self.api_key.to_dict(),
+                "tool_names": self.tool_names,
+                "max_chars": self.max_chars,
+                "base_url": self.base_url,
+            },
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TwittrAPIToolset:
+        """Rebuilds the toolset from its settings."""
+        inner = dict(data["data"])
+        deserialize_secrets_inplace(inner, keys=["api_key"])
+        return cls(**inner)
+
+
+__all__ = ["TOOL_NAMES", "TwittrAPIToolset", "format_result"]

twittrapi_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: twittrapi-haystack
+Version: 0.1.0
+Summary: Haystack integration for TwittrAPI: search X (Twitter) into Documents and give Agents read-only X tools.
+Project-URL: Homepage, https://www.twittrapi.com
+Project-URL: Documentation, https://www.twittrapi.com/docs
+Project-URL: Source, https://github.com/twittrapi/twittrapi-haystack
+Project-URL: Issues, https://github.com/twittrapi/twittrapi-haystack/issues
+Project-URL: Changelog, https://github.com/twittrapi/twittrapi-haystack/blob/main/CHANGELOG.md
+Author: TwittrAPI
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,haystack,haystack-ai,rag,tweets,twitter,twitter api,twitter search,twittrapi,x
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=2.14.0
+Requires-Dist: twittrapi<2,>=1.4.0
+Description-Content-Type: text/markdown
+
+# twittrapi-haystack
+
+[![PyPI](https://img.shields.io/pypi/v/twittrapi-haystack.svg)](https://pypi.org/project/twittrapi-haystack/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[Haystack](https://haystack.deepset.ai) integration for [TwittrAPI](https://www.twittrapi.com), a
+pay-per-call REST API for public X (Twitter) data. No X developer account needed.
+
+- **`TwittrAPITweetSearch`**: a component that searches X and returns each tweet as a Haystack
+  `Document`, with the same `documents` and `links` outputs as the web-search components.
+- **`TwittrAPIToolset`**: read-only X tools for Haystack Agents (search, profiles, timelines,
+  followers, tweets with replies, quotes, retweets, Lists, Communities, trends).
+
+## Installation
+
+```bash
+pip install twittrapi-haystack
+```
+
+Create an API key at [twittrapi.com](https://www.twittrapi.com) and set it as `TWITTRAPI_API_KEY`.
+New accounts get test credit.
+
+## TwittrAPITweetSearch
+
+```python
+from haystack_integrations.components.websearch.twittrapi import TwittrAPITweetSearch
+
+search = TwittrAPITweetSearch(top_k=20)  # reads TWITTRAPI_API_KEY
+result = search.run(query="haystack lang:en -filter:replies")
+
+for doc in result["documents"]:
+    print(doc.meta["author_username"], doc.meta["likes"], doc.content)
+print(result["next_cursor"])  # pass as cursor= for the next page
+```
+
+The query takes the operators of the X search box: `from:user`, `to:user`, `"exact phrase"`,
+`lang:en`, `since:2026-01-01`, `until:2026-02-01`, `min_faves:100`, `filter:media`,
+`-filter:replies` and more.
+
+**Parameters**
+
+- `api_key`: TwittrAPI key. Defaults to the `TWITTRAPI_API_KEY` environment variable.
+- `category`: `"Latest"` (default, newest first), `"Top"`, `"People"` (accounts instead of tweets),
+  `"Photos"` or `"Videos"`. Can be changed per `run`.
+- `top_k`: results per page, 1 to 100 (default 20).
+
+**Outputs**
+
+- `documents`: one `Document` per tweet. `content` is the full text; `meta` holds `id`, `url`,
+  `created_at`, `lang`, `author_id`, `author_username`, `author_name`, `likes`, `retweets`,
+  `replies`, `quotes`, `views` and `conversation_id`.
+- `links`: the tweet URLs, in the same order.
+- `next_cursor`: cursor for the next page, `None` on the last page.
+
+### In a pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import ChatPromptBuilder
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.websearch.twittrapi import TwittrAPITweetSearch
+
+template = [
+    ChatMessage.from_user(
+        "Summarize what people say about {{ topic }} on X.\n"
+        "{% for doc in documents %}- @{{ doc.meta.author_username }}: {{ doc.content }}\n{% endfor %}"
+    )
+]
+
+pipe = Pipeline()
+pipe.add_component("search", TwittrAPITweetSearch(top_k=30))
+pipe.add_component("prompt", ChatPromptBuilder(template=template, required_variables=["topic", "documents"]))
+pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
+pipe.connect("search.documents", "prompt.documents")
+pipe.connect("prompt.prompt", "llm.messages")
+
+result = pipe.run({"search": {"query": "haystack lang:en"}, "prompt": {"topic": "Haystack"}})
+print(result["llm"]["replies"][0].text)
+```
+
+## TwittrAPIToolset
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.tools.twittrapi import TwittrAPIToolset
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+    tools=TwittrAPIToolset(),  # reads TWITTRAPI_API_KEY
+)
+result = agent.run(messages=[ChatMessage.from_user("What has @deepset_ai posted this week?")])
+print(result["messages"][-1].text)
+```
+
+| Tool | What it does |
+| --- | --- |
+| `search_tweets` | Search X with search operators; `People` returns accounts |
+| `get_user_by_username` / `get_user_by_id` | A profile with counts and the numeric user ID |
+| `get_user_tweets` | A user's recent tweets |
+| `get_followers` / `get_following` | Followers and followed accounts |
+| `get_tweet` | A tweet with its reply thread |
+| `get_tweet_retweets` / `get_tweet_quotes` | Who retweeted a tweet, and the tweets quoting it |
+| `get_list_tweets` | Latest tweets from an X List |
+| `get_community_tweets` | Tweets in an X Community |
+| `get_trends` / `get_trend_locations` | Trending topics by location (WOEID) |
+
+Pick a subset with `TwittrAPIToolset(tool_names=["search_tweets", "get_user_tweets"])`. Results are
+TwittrAPI's compact [simple format](https://www.twittrapi.com/docs/simple-format) (flat JSON), cut at
+`max_chars` (default 20,000). Paginated tools print `next_cursor` first so the agent can page on. API
+errors, such as an empty balance, are returned to the agent as the tool result.
+
+## Pricing
+
+Every call is billed to your prepaid TwittrAPI balance. Prices are on
+[twittrapi.com/pricing](https://www.twittrapi.com/pricing).
+
+## Links
+
+- [TwittrAPI docs](https://www.twittrapi.com/docs)
+- [Python SDK](https://github.com/twittrapi/twittrapi-python)
+- [MCP server](https://github.com/twittrapi/twittrapi-mcp)
+- Support: support@twittrapi.com or [GitHub issues](https://github.com/twittrapi/twittrapi-haystack/issues)
+
+## License
+
+MIT

twittrapi_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+haystack_integrations/components/websearch/twittrapi/__init__.py,sha256=UT4asxBXRyE9y7515Sva8W5QqPnNQGRei_YJhiRsF1k,161
+haystack_integrations/components/websearch/twittrapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/components/websearch/twittrapi/tweet_search.py,sha256=yDgyoGB1sXn3L_pKB7bwOLCetpB5C-JDuRhYEkJmBZA,7411
+haystack_integrations/tools/twittrapi/__init__.py,sha256=eGmmt2rHHsENqa1zZgJ2xjlo2ne5e8TPoD3Is48qi6Y,96
+haystack_integrations/tools/twittrapi/toolset.py,sha256=w0MQC_7LJUgTFnGLCBb5w27Y6Jt0Y_XNMnRZcBQcATU,12877
+twittrapi_haystack-0.1.0.dist-info/METADATA,sha256=YDFC03AqHuorVJB-DHpuNv5cZ9G_IcONU89DzvNTPVc,6740
+twittrapi_haystack-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+twittrapi_haystack-0.1.0.dist-info/licenses/LICENSE,sha256=-GJ5-iBXn7frztmb-DL8pU5HC57TKnyojHFqNkuqneU,1066
+twittrapi_haystack-0.1.0.dist-info/RECORD,,

twittrapi_haystack-0.1.0.dist-info/WHEEL

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

twittrapi_haystack-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TwittrAPI
+
+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.