llama-index-tools-xdataapi 0.1.0__tar.gz

llama_index_tools_xdataapi-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+*.tgz
+uv.lock
+package-lock.json

llama_index_tools_xdataapi-0.1.0/LICENSE

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

llama_index_tools_xdataapi-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: llama-index-tools-xdataapi
+Version: 0.1.0
+Summary: LlamaIndex tool spec for xdataapi.io: read-only public X (Twitter) profiles, tweets, threads, followers and search.
+Project-URL: Homepage, https://xdataapi.io
+Project-URL: Documentation, https://xdataapi.io/docs
+Project-URL: API reference, https://xdataapi.io/reference
+Project-URL: Source code, https://github.com/xdataapi/xdataapi
+Project-URL: Issue tracker, https://github.com/xdataapi/xdataapi/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,llama-index,llamahub,llamaindex,llm,tools,twitter,twitter-api,x,x-api,xdataapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.9
+Requires-Dist: httpx<0.29.0,>=0.27.0
+Requires-Dist: llama-index-core<0.15,>=0.12.0
+Description-Content-Type: text/markdown
+
+# llama-index-tools-xdataapi
+
+LlamaIndex tool spec for [xdataapi.io](https://xdataapi.io): read-only public X (Twitter) data.
+Profiles, posts, threads, replies, quotes, reposters, followers, and search with the x.com operators.
+
+Read-only by design. No posting, no likes, no direct messages, no private data.
+Not affiliated with X Corp.
+
+```bash
+pip install llama-index-tools-xdataapi
+```
+
+## Use
+
+```python
+from llama_index.tools.xdataapi import XdataapiToolSpec
+
+# Reads XDATAAPI_KEY from the environment.
+tool_spec = XdataapiToolSpec()
+tools = tool_spec.to_tool_list()
+```
+
+With an agent:
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.anthropic import Anthropic
+from llama_index.tools.xdataapi import XdataapiToolSpec
+
+agent = FunctionAgent(
+    tools=XdataapiToolSpec(max_results=25).to_tool_list(),
+    llm=Anthropic(model="claude-opus-5"),
+)
+print(await agent.run("What is @vercel posting about this week?"))
+```
+
+One call on its own:
+
+```python
+XdataapiToolSpec().search_tweets(q="from:vercel since:2026-09-01", count=10)
+```
+
+## Tools
+
+| Tool | Reads | Credits |
+|---|---|---|
+| `search_tweets` | Search with the x.com operators | 1 per result |
+| `get_user` | One profile | 1 |
+| `get_users` | Up to 100 profiles in one call | 1 per profile |
+| `get_user_tweets` | Latest posts of a user | 1 per post |
+| `get_tweet` | One post | 1 |
+| `get_tweets` | Up to 100 posts in one call | 1 per post |
+| `get_thread` | A post with its thread and replies | 1 per post |
+| `get_replies` | Direct replies to a post | 1 per reply |
+| `get_quotes` | Posts that quote a post | 1 per post |
+| `get_retweeters` | Accounts that reposted a post | 0.5 per profile |
+| `get_followers` | Followers, as profiles | 0.1 per profile |
+| `get_follower_ids` | Follower ids only | 0.02 per id |
+| `get_following` | Accounts a user follows | 0.1 per profile |
+| `get_balance` | Credits left and rate limit | free |
+
+Empty results and failed requests cost nothing. A repeated read inside the cache window costs half.
+Every response carries `credits_charged` and `balance_remaining`, so the model can watch the budget
+and stop on its own.
+
+## Spending guards
+
+`max_results` caps the page size of every paging tool:
+
+```python
+tool_spec = XdataapiToolSpec(max_results=25)
+```
+
+Narrow the surface with the LlamaIndex argument:
+
+```python
+tools = XdataapiToolSpec().to_tool_list(spec_functions=["search_tweets", "get_user", "get_balance"])
+```
+
+## Errors
+
+A failure the model can act on — no credits, not found, a search product X refused — comes back as a
+dict with `error.code`, so the model can change plan. None of those are charged.
+A missing or revoked key raises `XdataapiAuthError`, because no model can repair it.
+Rate limits and upstream faults raise `XdataapiError`.
+
+## MCP instead
+
+An agent that speaks MCP needs no package. The hosted server is at `https://api.xdataapi.io/mcp`
+(Streamable HTTP, OAuth or `x-api-key`), on the official MCP Registry as `io.xdataapi/xdataapi`.
+
+## Keys and pricing
+
+Get a key at [xdataapi.io/dashboard](https://xdataapi.io/dashboard). 5,000 credits to start, no card.
+Prepaid packs from $10; credits never expire. Live status: [xdataapi.io/status](https://xdataapi.io/status).
+
+MIT licensed.

llama_index_tools_xdataapi-0.1.0/README.md

@@ -0,0 +1,97 @@
+# llama-index-tools-xdataapi
+
+LlamaIndex tool spec for [xdataapi.io](https://xdataapi.io): read-only public X (Twitter) data.
+Profiles, posts, threads, replies, quotes, reposters, followers, and search with the x.com operators.
+
+Read-only by design. No posting, no likes, no direct messages, no private data.
+Not affiliated with X Corp.
+
+```bash
+pip install llama-index-tools-xdataapi
+```
+
+## Use
+
+```python
+from llama_index.tools.xdataapi import XdataapiToolSpec
+
+# Reads XDATAAPI_KEY from the environment.
+tool_spec = XdataapiToolSpec()
+tools = tool_spec.to_tool_list()
+```
+
+With an agent:
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.anthropic import Anthropic
+from llama_index.tools.xdataapi import XdataapiToolSpec
+
+agent = FunctionAgent(
+    tools=XdataapiToolSpec(max_results=25).to_tool_list(),
+    llm=Anthropic(model="claude-opus-5"),
+)
+print(await agent.run("What is @vercel posting about this week?"))
+```
+
+One call on its own:
+
+```python
+XdataapiToolSpec().search_tweets(q="from:vercel since:2026-09-01", count=10)
+```
+
+## Tools
+
+| Tool | Reads | Credits |
+|---|---|---|
+| `search_tweets` | Search with the x.com operators | 1 per result |
+| `get_user` | One profile | 1 |
+| `get_users` | Up to 100 profiles in one call | 1 per profile |
+| `get_user_tweets` | Latest posts of a user | 1 per post |
+| `get_tweet` | One post | 1 |
+| `get_tweets` | Up to 100 posts in one call | 1 per post |
+| `get_thread` | A post with its thread and replies | 1 per post |
+| `get_replies` | Direct replies to a post | 1 per reply |
+| `get_quotes` | Posts that quote a post | 1 per post |
+| `get_retweeters` | Accounts that reposted a post | 0.5 per profile |
+| `get_followers` | Followers, as profiles | 0.1 per profile |
+| `get_follower_ids` | Follower ids only | 0.02 per id |
+| `get_following` | Accounts a user follows | 0.1 per profile |
+| `get_balance` | Credits left and rate limit | free |
+
+Empty results and failed requests cost nothing. A repeated read inside the cache window costs half.
+Every response carries `credits_charged` and `balance_remaining`, so the model can watch the budget
+and stop on its own.
+
+## Spending guards
+
+`max_results` caps the page size of every paging tool:
+
+```python
+tool_spec = XdataapiToolSpec(max_results=25)
+```
+
+Narrow the surface with the LlamaIndex argument:
+
+```python
+tools = XdataapiToolSpec().to_tool_list(spec_functions=["search_tweets", "get_user", "get_balance"])
+```
+
+## Errors
+
+A failure the model can act on — no credits, not found, a search product X refused — comes back as a
+dict with `error.code`, so the model can change plan. None of those are charged.
+A missing or revoked key raises `XdataapiAuthError`, because no model can repair it.
+Rate limits and upstream faults raise `XdataapiError`.
+
+## MCP instead
+
+An agent that speaks MCP needs no package. The hosted server is at `https://api.xdataapi.io/mcp`
+(Streamable HTTP, OAuth or `x-api-key`), on the official MCP Registry as `io.xdataapi/xdataapi`.
+
+## Keys and pricing
+
+Get a key at [xdataapi.io/dashboard](https://xdataapi.io/dashboard). 5,000 credits to start, no card.
+Prepaid packs from $10; credits never expire. Live status: [xdataapi.io/status](https://xdataapi.io/status).
+
+MIT licensed.

llama_index_tools_xdataapi-0.1.0/llama_index/tools/xdataapi/__init__.py

@@ -0,0 +1,8 @@
+from llama_index.tools.xdataapi.base import (
+    XdataapiAuthError,
+    XdataapiClient,
+    XdataapiError,
+    XdataapiToolSpec,
+)
+
+__all__ = ["XdataapiToolSpec", "XdataapiClient", "XdataapiError", "XdataapiAuthError"]

llama_index_tools_xdataapi-0.1.0/llama_index/tools/xdataapi/base.py

@@ -0,0 +1,243 @@
+"""LlamaIndex tool spec for xdataapi.io: read-only public X (Twitter) data.
+
+Every method is a tool. The docstring is what the model reads, so each one says
+what the call costs in credits.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+
+from .client import XdataapiAuthError, XdataapiClient, XdataapiError
+
+__all__ = ["XdataapiToolSpec", "XdataapiClient", "XdataapiError", "XdataapiAuthError"]
+
+
+def _handle(value: str) -> str:
+    return value.strip().lstrip("@")
+
+
+class XdataapiToolSpec(BaseToolSpec):
+    """Read public X (Twitter) data: profiles, posts, threads, followers, search.
+
+    Read-only. No posting, no likes, no direct messages, no private data.
+
+    Args:
+        api_key: Key from https://xdataapi.io/dashboard. Read from
+            ``XDATAAPI_KEY`` when not given.
+        max_results: Ceiling on the page size of every paging tool, so one agent
+            step cannot spend more than you allow.
+    """
+
+    spec_functions = [
+        "search_tweets",
+        "get_user",
+        "get_users",
+        "get_user_tweets",
+        "get_tweet",
+        "get_tweets",
+        "get_thread",
+        "get_replies",
+        "get_quotes",
+        "get_retweeters",
+        "get_followers",
+        "get_follower_ids",
+        "get_following",
+        "get_balance",
+    ]
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        max_results: Optional[int] = None,
+        **client_kwargs: Any,
+    ) -> None:
+        self.client = XdataapiClient(api_key, max_results=max_results, **client_kwargs)
+
+    # --- tweets ----------------------------------------------------------
+
+    def search_tweets(
+        self,
+        q: str,
+        product: Optional[str] = None,
+        count: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        """Search public X posts with the x.com operators.
+
+        The entry point when you do not already know a handle or a post id.
+        Costs 1 credit per result; an empty result is free.
+
+        Args:
+            q: x.com search syntax. Operators: from:handle, to:handle,
+                since:YYYY-MM-DD, until:YYYY-MM-DD, min_faves:N, lang:xx,
+                "exact phrase", OR, and - to exclude.
+                Example: from:vercel since:2026-09-01 -filter:replies
+            product: Latest (default, always available), Top (may answer 403,
+                free), People (returns profiles), Photos, Videos.
+            count: Results on this page, 1 to 50.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(
+            "/v1/tweets/search",
+            {"q": q, "product": product, "count": self.client.cap(count), "cursor": cursor},
+        )
+
+    def get_tweet(self, id: str) -> dict:
+        """Read one X post by numeric id, with its author. Costs 1 credit.
+
+        Args:
+            id: Numeric post id, as a string.
+        """
+        return self.client.get(f"/v1/tweets/{id}")
+
+    def get_tweets(self, ids: List[str]) -> dict:
+        """Read up to 100 X posts by id in ONE call.
+
+        Prefer this over repeated single reads: one request, one rate-limit slot.
+        Costs 1 credit per post found; deleted or private posts are listed in
+        ``errors`` and cost nothing.
+
+        Args:
+            ids: Numeric post ids, at most 100.
+        """
+        return self.client.get("/v1/tweets/batch", {"ids": ",".join(str(i) for i in ids)})
+
+    def get_thread(self, id: str, cursor: Optional[str] = None) -> dict:
+        """Read one X post with its thread and replies, focal post first.
+
+        Reads a whole conversation in one call. Costs 1 credit per post returned.
+
+        Args:
+            id: Numeric post id, as a string.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(f"/v1/tweets/{id}/thread", {"cursor": cursor})
+
+    def get_replies(self, id: str, cursor: Optional[str] = None) -> dict:
+        """Read the direct replies to one X post, one page. Costs 1 credit per reply.
+
+        Args:
+            id: Numeric post id, as a string.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(f"/v1/tweets/{id}/replies", {"cursor": cursor})
+
+    def get_quotes(self, id: str, count: Optional[int] = None, cursor: Optional[str] = None) -> dict:
+        """Read the posts that quote one X post, newest first. Costs 1 credit per post.
+
+        Args:
+            id: Numeric post id, as a string.
+            count: Results on this page, 1 to 50.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(
+            f"/v1/tweets/{id}/quotes", {"count": self.client.cap(count), "cursor": cursor}
+        )
+
+    def get_retweeters(self, id: str, count: Optional[int] = None, cursor: Optional[str] = None) -> dict:
+        """Read the accounts that reposted one X post. Costs 0.5 credit per profile.
+
+        Some reading accounts are refused this by X; a 403 is free.
+
+        Args:
+            id: Numeric post id, as a string.
+            count: Results on this page, 1 to 50.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(
+            f"/v1/tweets/{id}/retweeters", {"count": self.client.cap(count), "cursor": cursor}
+        )
+
+    # --- users -----------------------------------------------------------
+
+    def get_user(self, handle: str) -> dict:
+        """Read the public profile of one X user. Costs 1 credit.
+
+        Args:
+            handle: X handle, with or without the leading @.
+        """
+        return self.client.get(f"/v1/users/{_handle(handle)}")
+
+    def get_users(self, handles: List[str]) -> dict:
+        """Read up to 100 X profiles in ONE call.
+
+        Prefer this over repeated single reads. Costs 1 credit per profile found;
+        handles that do not exist are listed in ``errors`` and cost nothing.
+
+        Args:
+            handles: X handles, at most 100.
+        """
+        return self.client.get("/v1/users/batch", {"handles": ",".join(_handle(h) for h in handles)})
+
+    def get_user_tweets(
+        self, user: str, count: Optional[int] = None, cursor: Optional[str] = None
+    ) -> dict:
+        """Read the latest posts of one X user, newest first. Costs 1 credit per post.
+
+        Args:
+            user: X handle (with or without @) or numeric user id.
+            count: Results on this page, 1 to 50.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(
+            f"/v1/users/{_handle(user)}/tweets", {"count": self.client.cap(count), "cursor": cursor}
+        )
+
+    def get_followers(self, user: str, count: Optional[int] = None, cursor: Optional[str] = None) -> dict:
+        """Read the followers of an X user as full profiles. Costs 0.1 credit per profile.
+
+        Use get_follower_ids when ids are enough: it costs five times less.
+        Some reading accounts are refused this by X; a 403 is free.
+
+        Args:
+            user: X handle (with or without @) or numeric user id.
+            count: Results on this page, 1 to 50.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(
+            f"/v1/users/{_handle(user)}/followers", {"count": self.client.cap(count), "cursor": cursor}
+        )
+
+    def get_follower_ids(
+        self, user: str, count: Optional[int] = None, cursor: Optional[str] = None
+    ) -> dict:
+        """Read the numeric ids of an X user's followers, without profiles.
+
+        Costs 0.02 credit per id. Use it to size or intersect an audience.
+
+        Args:
+            user: X handle (with or without @) or numeric user id.
+            count: Results on this page, 1 to 50.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(
+            f"/v1/users/{_handle(user)}/followers/ids",
+            {"count": self.client.cap(count), "cursor": cursor},
+        )
+
+    def get_following(self, user: str, count: Optional[int] = None, cursor: Optional[str] = None) -> dict:
+        """Read the accounts an X user follows. Costs 0.1 credit per profile.
+
+        Some reading accounts are refused this by X; a 403 is free.
+
+        Args:
+            user: X handle (with or without @) or numeric user id.
+            count: Results on this page, 1 to 50.
+            cursor: next_cursor from the previous page.
+        """
+        return self.client.get(
+            f"/v1/users/{_handle(user)}/following", {"count": self.client.cap(count), "cursor": cursor}
+        )
+
+    # --- account ---------------------------------------------------------
+
+    def get_balance(self) -> dict:
+        """Read the credits left on this key and its rate limit. Free.
+
+        Call it before a large read to check the budget covers the plan.
+        """
+        return self.client.get("/v1/me")

llama_index_tools_xdataapi-0.1.0/llama_index/tools/xdataapi/client.py

@@ -0,0 +1,149 @@
+"""HTTP client for the xdataapi.io REST API.
+
+The tools hand the model the JSON the API returns, unchanged, so it sees
+``credits_charged`` and ``balance_remaining`` on every call and can stop before
+the balance runs out.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+import httpx
+
+BASE_URL = "https://api.xdataapi.io"
+
+#: Failures the model can act on: try another handle, ask for a smaller page,
+#: tell the user the balance is empty. These come back as data.
+_REPORTED = frozenset({400, 402, 403, 404})
+
+
+class XdataapiError(RuntimeError):
+    """A call failed in a way the model cannot repair."""
+
+    def __init__(self, message: str, *, code: str = "", status: int = 0, request_id: str = "") -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+
+
+class XdataapiAuthError(XdataapiError):
+    """The key is missing, unknown or revoked. A configuration fault."""
+
+
+def _problem(response: httpx.Response) -> dict[str, Any]:
+    try:
+        body = response.json()
+    except ValueError:
+        body = {}
+    return body if isinstance(body, dict) else {}
+
+
+class XdataapiClient:
+    """Thin wrapper over the REST API. Sync and async, one key.
+
+    Args:
+        api_key: Key from https://xdataapi.io/dashboard. Read from
+            ``XDATAAPI_KEY`` when not given.
+        base_url: Override for testing or for a private deployment.
+        timeout: Seconds per request.
+        max_results: Ceiling on ``count`` for every paging tool. Set it to cap
+            what one agent step can spend. ``None`` leaves the API default.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = BASE_URL,
+        timeout: float = 30.0,
+        max_results: int | None = None,
+        client: httpx.Client | None = None,
+        async_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("XDATAAPI_KEY")
+        if not key:
+            raise XdataapiAuthError(
+                "No API key. Pass api_key=... or set XDATAAPI_KEY. "
+                "Get one at https://xdataapi.io/dashboard."
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_results = max_results
+        self._client = client
+        self._async_client = async_client
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {
+            "x-api-key": self.api_key,
+            "accept": "application/json",
+            "user-agent": "llama-index-tools-xdataapi",
+        }
+
+    def cap(self, count: int | None) -> int | None:
+        """Apply ``max_results`` to a requested page size."""
+        if count is None:
+            return self.max_results
+        if self.max_results is None:
+            return count
+        return min(count, self.max_results)
+
+    def _handle(self, response: httpx.Response) -> dict[str, Any]:
+        if response.status_code < 400:
+            return _problem(response)
+
+        body = _problem(response)
+        error = body.get("error") or {}
+        code = str(error.get("code") or "")
+        message = str(error.get("message") or response.reason_phrase or "request failed")
+        request_id = str(body.get("request_id") or "")
+
+        if response.status_code == 401:
+            raise XdataapiAuthError(
+                f"{message} (code {code or 'invalid_key'}). "
+                "Check XDATAAPI_KEY against https://xdataapi.io/dashboard.",
+                code=code,
+                status=401,
+                request_id=request_id,
+            )
+        if response.status_code in _REPORTED:
+            # Nothing was charged for these. Let the model read and decide.
+            return body
+        raise XdataapiError(
+            f"{message} (HTTP {response.status_code}, code {code}, request {request_id})",
+            code=code,
+            status=response.status_code,
+            request_id=request_id,
+        )
+
+    @staticmethod
+    def _clean(params: Mapping[str, Any] | None) -> dict[str, Any]:
+        return {k: v for k, v in (params or {}).items() if v is not None}
+
+    def get(self, path: str, params: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        client = self._client
+        if client is None:
+            with httpx.Client(timeout=self.timeout) as fresh:
+                return self._handle(
+                    fresh.get(f"{self.base_url}{path}", params=self._clean(params), headers=self._headers)
+                )
+        return self._handle(
+            client.get(f"{self.base_url}{path}", params=self._clean(params), headers=self._headers)
+        )
+
+    async def aget(self, path: str, params: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        client = self._async_client
+        if client is None:
+            async with httpx.AsyncClient(timeout=self.timeout) as fresh:
+                return self._handle(
+                    await fresh.get(
+                        f"{self.base_url}{path}", params=self._clean(params), headers=self._headers
+                    )
+                )
+        return self._handle(
+            await client.get(f"{self.base_url}{path}", params=self._clean(params), headers=self._headers)
+        )

llama_index_tools_xdataapi-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "llama-index-tools-xdataapi"
+version = "0.1.0"
+description = "LlamaIndex tool spec for xdataapi.io: read-only public X (Twitter) profiles, tweets, threads, followers and search."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9,<4.0"
+keywords = [
+  "llama-index", "llamaindex", "llamahub", "agents", "tools", "twitter", "x",
+  "twitter-api", "x-api", "llm", "xdataapi",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "llama-index-core>=0.12.0,<0.15",
+  "httpx>=0.27.0,<0.29.0",
+]
+
+[project.urls]
+Homepage = "https://xdataapi.io"
+Documentation = "https://xdataapi.io/docs"
+"API reference" = "https://xdataapi.io/reference"
+"Source code" = "https://github.com/xdataapi/xdataapi"
+"Issue tracker" = "https://github.com/xdataapi/xdataapi/issues"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "respx>=0.21"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["llama_index"]
+
+[tool.llamahub]
+contains_example = false
+import_path = "llama_index.tools.xdataapi"
+
+[tool.llamahub.class_authors]
+XdataapiToolSpec = "xdataapi"

llama_index_tools_xdataapi-0.1.0/tests/test_tools.py

@@ -0,0 +1,105 @@
+import httpx
+import pytest
+import respx
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+
+from llama_index.tools.xdataapi import XdataapiAuthError, XdataapiError, XdataapiToolSpec
+
+BASE = "https://api.xdataapi.io"
+
+
+def spec(**kwargs):
+    return XdataapiToolSpec("xd_live_test", **kwargs)
+
+
+def test_it_is_a_tool_spec():
+    assert isinstance(spec(), BaseToolSpec)
+
+
+def test_every_named_function_exists():
+    s = spec()
+    for name in s.spec_functions:
+        assert callable(getattr(s, name)), name
+
+
+def test_the_tool_list_carries_all_of_them():
+    tools = spec().to_tool_list()
+    assert len(tools) == 14
+    assert {t.metadata.name for t in tools} == set(XdataapiToolSpec.spec_functions)
+
+
+def test_every_tool_describes_what_it_costs():
+    for tool in spec().to_tool_list():
+        text = (tool.metadata.description or "").lower()
+        assert "credit" in text or "free" in text, tool.metadata.name
+
+
+@respx.mock
+def test_get_user_strips_the_at_sign():
+    route = respx.get(f"{BASE}/v1/users/vercel").mock(
+        return_value=httpx.Response(200, json={"data": {"handle": "vercel"}, "credits_charged": 1})
+    )
+    assert spec().get_user("@vercel")["credits_charged"] == 1
+    assert route.called
+
+
+@respx.mock
+def test_search_passes_the_operators_through_untouched():
+    route = respx.get(f"{BASE}/v1/tweets/search").mock(return_value=httpx.Response(200, json={"data": []}))
+    spec().search_tweets(q="from:x since:2026-09-01 -filter:replies", count=10)
+    assert route.calls.last.request.url.params["q"] == "from:x since:2026-09-01 -filter:replies"
+
+
+@respx.mock
+def test_none_valued_arguments_are_not_sent():
+    route = respx.get(f"{BASE}/v1/tweets/search").mock(return_value=httpx.Response(200, json={"data": []}))
+    spec().search_tweets(q="hello")
+    params = route.calls.last.request.url.params
+    assert "cursor" not in params and "product" not in params
+
+
+@respx.mock
+def test_max_results_caps_a_bigger_request():
+    route = respx.get(f"{BASE}/v1/tweets/search").mock(return_value=httpx.Response(200, json={"data": []}))
+    spec(max_results=25).search_tweets(q="hello", count=50)
+    assert route.calls.last.request.url.params["count"] == "25"
+
+
+@respx.mock
+def test_batch_sends_one_comma_separated_list():
+    route = respx.get(f"{BASE}/v1/users/batch").mock(return_value=httpx.Response(200, json={"data": []}))
+    spec().get_users(["@x", "github"])
+    assert route.calls.last.request.url.params["handles"] == "x,github"
+
+
+@respx.mock
+def test_no_credits_comes_back_as_data_so_the_model_can_stop():
+    respx.get(f"{BASE}/v1/users/x").mock(
+        return_value=httpx.Response(402, json={"error": {"code": "no_credits", "message": "balance is zero"}})
+    )
+    assert spec().get_user("x")["error"]["code"] == "no_credits"
+
+
+@respx.mock
+def test_a_bad_key_raises_because_no_model_can_repair_it():
+    respx.get(f"{BASE}/v1/users/x").mock(
+        return_value=httpx.Response(401, json={"error": {"code": "invalid_key", "message": "unknown key"}})
+    )
+    with pytest.raises(XdataapiAuthError):
+        spec().get_user("x")
+
+
+@respx.mock
+def test_a_rate_limit_raises_so_the_framework_can_retry():
+    respx.get(f"{BASE}/v1/users/x").mock(
+        return_value=httpx.Response(429, json={"error": {"code": "too_many_requests"}})
+    )
+    with pytest.raises(XdataapiError):
+        spec().get_user("x")
+
+
+@respx.mock
+def test_balance_reads_me():
+    route = respx.get(f"{BASE}/v1/me").mock(return_value=httpx.Response(200, json={"balance": 4679.87}))
+    assert spec().get_balance()["balance"] == 4679.87
+    assert route.called