langchain-xdataapi 0.1.0__tar.gz

langchain_xdataapi-0.1.0/.gitignore

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

langchain_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.

langchain_xdataapi-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: langchain-xdataapi
+Version: 0.1.0
+Summary: LangChain tools 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,langchain,langgraph,llm,mcp,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: >=3.10
+Requires-Dist: httpx<0.29.0,>=0.27.0
+Requires-Dist: langchain-core<2.0.0,>=0.3.0
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Description-Content-Type: text/markdown
+
+# langchain-xdataapi
+
+LangChain tools 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 langchain-xdataapi
+```
+
+## Use
+
+```python
+from langchain_xdataapi import XdataapiToolkit
+
+# Reads XDATAAPI_KEY from the environment.
+tools = XdataapiToolkit.from_api_key().get_tools()
+```
+
+With an agent:
+
+```python
+from langchain.agents import create_agent
+from langchain_xdataapi import XdataapiToolkit
+
+agent = create_agent(
+    "anthropic:claude-opus-5",
+    tools=XdataapiToolkit.from_api_key(max_results=25).get_tools(),
+)
+result = agent.invoke({"messages": [{"role": "user", "content": "What is @vercel posting about this week?"}]})
+```
+
+One tool on its own:
+
+```python
+from langchain_xdataapi import SearchTweets, XdataapiClient
+
+search = SearchTweets(client=XdataapiClient())
+print(search.invoke({"q": "from:vercel since:2026-09-01", "count": 10}))
+```
+
+## Tools
+
+| Tool | Reads | Credits |
+|---|---|---|
+| `x_search_tweets` | Search with the x.com operators | 1 per result |
+| `x_get_user` | One profile | 1 |
+| `x_get_users` | Up to 100 profiles in one call | 1 per profile |
+| `x_get_user_tweets` | Latest posts of a user | 1 per post |
+| `x_get_tweet` | One post | 1 |
+| `x_get_tweets` | Up to 100 posts in one call | 1 per post |
+| `x_get_thread` | A post with its thread and replies | 1 per post |
+| `x_get_replies` | Direct replies to a post | 1 per reply |
+| `x_get_quotes` | Posts that quote a post | 1 per post |
+| `x_get_retweeters` | Accounts that reposted a post | 0.5 per profile |
+| `x_get_followers` | Followers, as profiles | 0.1 per profile |
+| `x_get_follower_ids` | Follower ids only | 0.02 per id |
+| `x_get_following` | Accounts a user follows | 0.1 per profile |
+| `x_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 see the budget shrink
+and stop on its own.
+
+## Spending guards
+
+`max_results` caps the page size of every paging tool, so one agent step cannot ask for more than you allow:
+
+```python
+toolkit = XdataapiToolkit.from_api_key(max_results=25)
+```
+
+Narrow the surface with `include` or `exclude`:
+
+```python
+toolkit = XdataapiToolkit.from_api_key(include=["x_search_tweets", "x_get_user", "x_get_balance"])
+```
+
+## Errors
+
+A failure the model can act on — no credits, not found, a search product X refused — comes back as JSON
+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`, so your framework's retry policy sees them.
+
+## MCP instead
+
+An agent that speaks MCP needs no package. Connect the hosted server:
+
+```bash
+claude mcp add --transport http xdataapi https://api.xdataapi.io/mcp
+```
+
+It signs in with OAuth on first use. It is 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.

langchain_xdataapi-0.1.0/README.md

@@ -0,0 +1,103 @@
+# langchain-xdataapi
+
+LangChain tools 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 langchain-xdataapi
+```
+
+## Use
+
+```python
+from langchain_xdataapi import XdataapiToolkit
+
+# Reads XDATAAPI_KEY from the environment.
+tools = XdataapiToolkit.from_api_key().get_tools()
+```
+
+With an agent:
+
+```python
+from langchain.agents import create_agent
+from langchain_xdataapi import XdataapiToolkit
+
+agent = create_agent(
+    "anthropic:claude-opus-5",
+    tools=XdataapiToolkit.from_api_key(max_results=25).get_tools(),
+)
+result = agent.invoke({"messages": [{"role": "user", "content": "What is @vercel posting about this week?"}]})
+```
+
+One tool on its own:
+
+```python
+from langchain_xdataapi import SearchTweets, XdataapiClient
+
+search = SearchTweets(client=XdataapiClient())
+print(search.invoke({"q": "from:vercel since:2026-09-01", "count": 10}))
+```
+
+## Tools
+
+| Tool | Reads | Credits |
+|---|---|---|
+| `x_search_tweets` | Search with the x.com operators | 1 per result |
+| `x_get_user` | One profile | 1 |
+| `x_get_users` | Up to 100 profiles in one call | 1 per profile |
+| `x_get_user_tweets` | Latest posts of a user | 1 per post |
+| `x_get_tweet` | One post | 1 |
+| `x_get_tweets` | Up to 100 posts in one call | 1 per post |
+| `x_get_thread` | A post with its thread and replies | 1 per post |
+| `x_get_replies` | Direct replies to a post | 1 per reply |
+| `x_get_quotes` | Posts that quote a post | 1 per post |
+| `x_get_retweeters` | Accounts that reposted a post | 0.5 per profile |
+| `x_get_followers` | Followers, as profiles | 0.1 per profile |
+| `x_get_follower_ids` | Follower ids only | 0.02 per id |
+| `x_get_following` | Accounts a user follows | 0.1 per profile |
+| `x_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 see the budget shrink
+and stop on its own.
+
+## Spending guards
+
+`max_results` caps the page size of every paging tool, so one agent step cannot ask for more than you allow:
+
+```python
+toolkit = XdataapiToolkit.from_api_key(max_results=25)
+```
+
+Narrow the surface with `include` or `exclude`:
+
+```python
+toolkit = XdataapiToolkit.from_api_key(include=["x_search_tweets", "x_get_user", "x_get_balance"])
+```
+
+## Errors
+
+A failure the model can act on — no credits, not found, a search product X refused — comes back as JSON
+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`, so your framework's retry policy sees them.
+
+## MCP instead
+
+An agent that speaks MCP needs no package. Connect the hosted server:
+
+```bash
+claude mcp add --transport http xdataapi https://api.xdataapi.io/mcp
+```
+
+It signs in with OAuth on first use. It is 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.

langchain_xdataapi-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "langchain-xdataapi"
+version = "0.1.0"
+description = "LangChain tools 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.10"
+keywords = [
+  "langchain", "langgraph", "agents", "tools", "twitter", "x", "twitter-api",
+  "x-api", "mcp", "llm", "xdataapi",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "langchain-core>=0.3.0,<2.0.0",
+  "httpx>=0.27.0,<0.29.0",
+  "pydantic>=2.7.0,<3.0.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", "pytest-asyncio>=0.24", "respx>=0.21"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_xdataapi"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

langchain_xdataapi-0.1.0/src/langchain_xdataapi/__init__.py

@@ -0,0 +1,54 @@
+"""LangChain tools for xdataapi.io: read-only public X (Twitter) data.
+
+    from langchain_xdataapi import XdataapiToolkit
+
+    tools = XdataapiToolkit.from_api_key().get_tools()
+
+Read-only by design. No posting, no likes, no direct messages, no private data.
+Docs: https://xdataapi.io/docs
+"""
+
+from .client import XdataapiAuthError, XdataapiClient, XdataapiError
+from .toolkit import XdataapiToolkit
+from .tools import (
+    ALL_TOOLS,
+    GetBalance,
+    GetFollowerIds,
+    GetFollowers,
+    GetFollowing,
+    GetQuotes,
+    GetReplies,
+    GetRetweeters,
+    GetThread,
+    GetTweet,
+    GetTweets,
+    GetUser,
+    GetUserTweets,
+    GetUsers,
+    SearchTweets,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ALL_TOOLS",
+    "GetBalance",
+    "GetFollowerIds",
+    "GetFollowers",
+    "GetFollowing",
+    "GetQuotes",
+    "GetReplies",
+    "GetRetweeters",
+    "GetThread",
+    "GetTweet",
+    "GetTweets",
+    "GetUser",
+    "GetUserTweets",
+    "GetUsers",
+    "SearchTweets",
+    "XdataapiAuthError",
+    "XdataapiClient",
+    "XdataapiError",
+    "XdataapiToolkit",
+    "__version__",
+]

langchain_xdataapi-0.1.0/src/langchain_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": "langchain-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)
+        )

langchain_xdataapi-0.1.0/src/langchain_xdataapi/toolkit.py

@@ -0,0 +1,64 @@
+"""The whole read surface as one toolkit."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from langchain_core.tools import BaseTool
+from langchain_core.tools.base import BaseToolkit
+from pydantic import ConfigDict
+
+from .client import XdataapiClient
+from .tools import ALL_TOOLS
+
+
+class XdataapiToolkit(BaseToolkit):
+    """Every read tool, sharing one client and one credit budget.
+
+    Example:
+        >>> from langchain_xdataapi import XdataapiToolkit
+        >>> toolkit = XdataapiToolkit.from_api_key(max_results=25)
+        >>> tools = toolkit.get_tools()
+
+    Args:
+        client: A configured :class:`XdataapiClient`.
+        include: Tool names to keep. ``None`` keeps them all.
+        exclude: Tool names to drop, applied after ``include``.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    client: XdataapiClient
+    include: tuple[str, ...] | None = None
+    exclude: tuple[str, ...] = ()
+
+    @classmethod
+    def from_api_key(
+        cls,
+        api_key: str | None = None,
+        *,
+        max_results: int | None = None,
+        include: Iterable[str] | None = None,
+        exclude: Iterable[str] = (),
+        **client_kwargs: object,
+    ) -> "XdataapiToolkit":
+        """Build a toolkit from a key, or from ``XDATAAPI_KEY``.
+
+        ``max_results`` caps the page size of every paging tool, which caps what
+        one agent step can spend.
+        """
+        return cls(
+            client=XdataapiClient(api_key, max_results=max_results, **client_kwargs),  # type: ignore[arg-type]
+            include=tuple(include) if include is not None else None,
+            exclude=tuple(exclude),
+        )
+
+    def get_tools(self) -> list[BaseTool]:
+        tools = [tool(client=self.client) for tool in ALL_TOOLS]
+        if self.include is not None:
+            wanted = set(self.include)
+            tools = [t for t in tools if t.name in wanted]
+        if self.exclude:
+            unwanted = set(self.exclude)
+            tools = [t for t in tools if t.name not in unwanted]
+        return tools

langchain_xdataapi-0.1.0/src/langchain_xdataapi/tools.py

@@ -0,0 +1,348 @@
+"""LangChain tools over the xdataapi.io read endpoints.
+
+Every tool is read-only. The credit cost is written into each description, so a
+model that plans a multi-step read knows what the plan costs before it runs it.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal, Sequence
+
+from langchain_core.callbacks import AsyncCallbackManagerForToolRun, CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field
+
+from .client import XdataapiClient
+
+
+def _handle(value: str) -> str:
+    return value.strip().lstrip("@")
+
+
+def _dump(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+class _Base(BaseTool):
+    """Shared plumbing: one client, JSON in and JSON out."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    client: XdataapiClient
+    response_format: str = "content"
+
+    def _call(self, **kwargs: Any) -> tuple[str, dict[str, Any] | None]:
+        raise NotImplementedError
+
+    def _run(self, run_manager: CallbackManagerForToolRun | None = None, **kwargs: Any) -> str:
+        path, params = self._call(**kwargs)
+        return _dump(self.client.get(path, params))
+
+    async def _arun(self, run_manager: AsyncCallbackManagerForToolRun | None = None, **kwargs: Any) -> str:
+        path, params = self._call(**kwargs)
+        return _dump(await self.client.aget(path, params))
+
+
+# --- users ---------------------------------------------------------------
+
+
+class _UserArgs(BaseModel):
+    handle: str = Field(description="X handle, with or without the leading @.")
+    fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
+
+
+class GetUser(_Base):
+    name: str = "x_get_user"
+    description: str = (
+        "Public profile of one X (Twitter) user by handle: bio, counts, verified state, "
+        "created date. Costs 1 credit."
+    )
+    args_schema: type[BaseModel] = _UserArgs
+
+    def _call(self, handle: str, fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/users/{_handle(handle)}", {"fresh": fresh}
+
+
+class _UsersArgs(BaseModel):
+    handles: Sequence[str] = Field(description="Up to 100 handles in one call.")
+    fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
+
+
+class GetUsers(_Base):
+    name: str = "x_get_users"
+    description: str = (
+        "Profiles of up to 100 X users in ONE call. Prefer this over repeated single reads: "
+        "it is one request and one rate-limit slot. Costs 1 credit per profile found; "
+        "handles that do not exist are listed in errors and cost nothing."
+    )
+    args_schema: type[BaseModel] = _UsersArgs
+
+    def _call(self, handles: Sequence[str], fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
+        return "/v1/users/batch", {"handles": ",".join(_handle(h) for h in handles), "fresh": fresh}
+
+
+class _PageArgs(BaseModel):
+    user: str = Field(description="X handle (with or without @) or numeric user id.")
+    count: int | None = Field(default=None, description="Results on this page. 1 to 50.")
+    cursor: str | None = Field(default=None, description="next_cursor from the previous page.")
+    fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
+
+
+class GetUserTweets(_Base):
+    name: str = "x_get_user_tweets"
+    description: str = (
+        "Latest posts of one X user, newest first. Pages with next_cursor. Costs 1 credit per post."
+    )
+    args_schema: type[BaseModel] = _PageArgs
+
+    def _call(
+        self, user: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/users/{_handle(user)}/tweets", {
+            "count": self.client.cap(count),
+            "cursor": cursor,
+            "fresh": fresh,
+        }
+
+
+class GetFollowers(_Base):
+    name: str = "x_get_followers"
+    description: str = (
+        "Followers of an X user, as full profiles. Costs 0.1 credit per profile. "
+        "Some accounts refuse this read; a 403 is free. Use x_get_follower_ids when ids are enough."
+    )
+    args_schema: type[BaseModel] = _PageArgs
+
+    def _call(
+        self, user: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/users/{_handle(user)}/followers", {
+            "count": self.client.cap(count),
+            "cursor": cursor,
+            "fresh": fresh,
+        }
+
+
+class GetFollowerIds(_Base):
+    name: str = "x_get_follower_ids"
+    description: str = (
+        "Numeric ids of an X user's followers, without the profiles. Costs 0.02 credit per id, "
+        "five times less than x_get_followers. Use it to size or intersect an audience."
+    )
+    args_schema: type[BaseModel] = _PageArgs
+
+    def _call(
+        self, user: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/users/{_handle(user)}/followers/ids", {
+            "count": self.client.cap(count),
+            "cursor": cursor,
+            "fresh": fresh,
+        }
+
+
+class GetFollowing(_Base):
+    name: str = "x_get_following"
+    description: str = (
+        "Accounts an X user follows. Costs 0.1 credit per profile. Some accounts refuse this read; "
+        "a 403 is free."
+    )
+    args_schema: type[BaseModel] = _PageArgs
+
+    def _call(
+        self, user: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/users/{_handle(user)}/following", {
+            "count": self.client.cap(count),
+            "cursor": cursor,
+            "fresh": fresh,
+        }
+
+
+# --- tweets --------------------------------------------------------------
+
+
+class _SearchArgs(BaseModel):
+    q: str = Field(
+        description=(
+            "Query in 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: Literal["Latest", "Top", "People", "Photos", "Videos"] | None = Field(
+        default=None,
+        description=(
+            "Latest (default, always available), Top (may answer 403, free), People (returns "
+            "profiles), Photos, Videos."
+        ),
+    )
+    count: int | None = Field(default=None, description="Results on this page. 1 to 50.")
+    cursor: str | None = Field(default=None, description="next_cursor from the previous page.")
+    fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
+
+
+class SearchTweets(_Base):
+    name: str = "x_search_tweets"
+    description: str = (
+        "Search public X posts with the x.com operators. The main entry point when you do not "
+        "already know a handle or a post id. Costs 1 credit per result returned; an empty result "
+        "is free. Pages with next_cursor."
+    )
+    args_schema: type[BaseModel] = _SearchArgs
+
+    def _call(
+        self,
+        q: str,
+        product: str | None = None,
+        count: int | None = None,
+        cursor: str | None = None,
+        fresh: bool | None = None,
+    ) -> tuple[str, dict[str, Any] | None]:
+        return "/v1/tweets/search", {
+            "q": q,
+            "product": product,
+            "count": self.client.cap(count),
+            "cursor": cursor,
+            "fresh": fresh,
+        }
+
+
+class _TweetArgs(BaseModel):
+    id: str = Field(description="Numeric post id, as a string.")
+    fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
+
+
+class GetTweet(_Base):
+    name: str = "x_get_tweet"
+    description: str = "One X post by numeric id, with its author. Costs 1 credit."
+    args_schema: type[BaseModel] = _TweetArgs
+
+    def _call(self, id: str, fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/tweets/{id}", {"fresh": fresh}
+
+
+class _TweetsArgs(BaseModel):
+    ids: Sequence[str] = Field(description="Up to 100 numeric post ids in one call.")
+    fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
+
+
+class GetTweets(_Base):
+    name: str = "x_get_tweets"
+    description: str = (
+        "Up to 100 X posts by id in ONE call. Prefer this over repeated single reads. "
+        "Costs 1 credit per post found; deleted or private posts are listed in errors and cost nothing."
+    )
+    args_schema: type[BaseModel] = _TweetsArgs
+
+    def _call(self, ids: Sequence[str], fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
+        return "/v1/tweets/batch", {"ids": ",".join(str(i) for i in ids), "fresh": fresh}
+
+
+class _ThreadArgs(BaseModel):
+    id: str = Field(description="Numeric post id, as a string.")
+    cursor: str | None = Field(default=None, description="next_cursor from the previous page.")
+    fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
+
+
+class GetThread(_Base):
+    name: str = "x_get_thread"
+    description: str = (
+        "One X post with its thread and replies, the focal post first. Use it to read a whole "
+        "conversation in one call. Costs 1 credit per post returned."
+    )
+    args_schema: type[BaseModel] = _ThreadArgs
+
+    def _call(
+        self, id: str, cursor: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/tweets/{id}/thread", {"cursor": cursor, "fresh": fresh}
+
+
+class GetReplies(_Base):
+    name: str = "x_get_replies"
+    description: str = "Direct replies to one X post, one page. Costs 1 credit per reply."
+    args_schema: type[BaseModel] = _ThreadArgs
+
+    def _call(
+        self, id: str, cursor: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/tweets/{id}/replies", {"cursor": cursor, "fresh": fresh}
+
+
+class _CountedTweetArgs(BaseModel):
+    id: str = Field(description="Numeric post id, as a string.")
+    count: int | None = Field(default=None, description="Results on this page. 1 to 50.")
+    cursor: str | None = Field(default=None, description="next_cursor from the previous page.")
+    fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
+
+
+class GetQuotes(_Base):
+    name: str = "x_get_quotes"
+    description: str = "Posts that quote one X post, newest first. Costs 1 credit per post."
+    args_schema: type[BaseModel] = _CountedTweetArgs
+
+    def _call(
+        self, id: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/tweets/{id}/quotes", {
+            "count": self.client.cap(count),
+            "cursor": cursor,
+            "fresh": fresh,
+        }
+
+
+class GetRetweeters(_Base):
+    name: str = "x_get_retweeters"
+    description: str = (
+        "Accounts that reposted one X post. Costs 0.5 credit per profile. Some accounts refuse "
+        "this read; a 403 is free."
+    )
+    args_schema: type[BaseModel] = _CountedTweetArgs
+
+    def _call(
+        self, id: str, count: int | None = None, cursor: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        return f"/v1/tweets/{id}/retweeters", {
+            "count": self.client.cap(count),
+            "cursor": cursor,
+            "fresh": fresh,
+        }
+
+
+# --- account -------------------------------------------------------------
+
+
+class _NoArgs(BaseModel):
+    pass
+
+
+class GetBalance(_Base):
+    name: str = "x_get_balance"
+    description: str = (
+        "Credits left on this key and its rate limit. Free. Call it before a large read to check "
+        "the budget covers the plan."
+    )
+    args_schema: type[BaseModel] = _NoArgs
+
+    def _call(self) -> tuple[str, dict[str, Any] | None]:
+        return "/v1/me", None
+
+
+ALL_TOOLS: tuple[type[_Base], ...] = (
+    SearchTweets,
+    GetUser,
+    GetUsers,
+    GetUserTweets,
+    GetTweet,
+    GetTweets,
+    GetThread,
+    GetReplies,
+    GetQuotes,
+    GetRetweeters,
+    GetFollowers,
+    GetFollowerIds,
+    GetFollowing,
+    GetBalance,
+)

langchain_xdataapi-0.1.0/tests/test_tools.py

@@ -0,0 +1,171 @@
+import json
+
+import httpx
+import pytest
+import respx
+
+from langchain_xdataapi import (
+    GetBalance,
+    GetTweets,
+    GetUser,
+    SearchTweets,
+    XdataapiAuthError,
+    XdataapiClient,
+    XdataapiError,
+    XdataapiToolkit,
+)
+
+BASE = "https://api.xdataapi.io"
+
+
+def client(**kwargs):
+    return XdataapiClient("xd_live_test", **kwargs)
+
+
+@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})
+    )
+    out = GetUser(client=client()).invoke({"handle": "@vercel"})
+    assert route.called
+    assert json.loads(out)["credits_charged"] == 1
+
+
+@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": [], "credits_charged": 0})
+    )
+    SearchTweets(client=client()).invoke({"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"
+    assert route.calls.last.request.url.params["count"] == "10"
+
+
+@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": []}))
+    SearchTweets(client=client()).invoke({"q": "hello"})
+    params = route.calls.last.request.url.params
+    assert "cursor" not in params and "fresh" 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": []}))
+    SearchTweets(client=client(max_results=25)).invoke({"q": "hello", "count": 50})
+    assert route.calls.last.request.url.params["count"] == "25"
+
+
+@respx.mock
+def test_max_results_applies_when_the_model_names_no_count():
+    route = respx.get(f"{BASE}/v1/tweets/search").mock(return_value=httpx.Response(200, json={"data": []}))
+    SearchTweets(client=client(max_results=5)).invoke({"q": "hello"})
+    assert route.calls.last.request.url.params["count"] == "5"
+
+
+@respx.mock
+def test_max_results_never_raises_a_smaller_request():
+    route = respx.get(f"{BASE}/v1/tweets/search").mock(return_value=httpx.Response(200, json={"data": []}))
+    SearchTweets(client=client(max_results=25)).invoke({"q": "hello", "count": 5})
+    assert route.calls.last.request.url.params["count"] == "5"
+
+
+@respx.mock
+def test_batch_sends_one_comma_separated_list():
+    route = respx.get(f"{BASE}/v1/tweets/batch").mock(return_value=httpx.Response(200, json={"data": []}))
+    GetTweets(client=client()).invoke({"ids": ["20", "21"]})
+    assert route.calls.last.request.url.params["ids"] == "20,21"
+
+
+@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"}})
+    )
+    out = json.loads(GetUser(client=client()).invoke({"handle": "x"}))
+    assert out["error"]["code"] == "no_credits"
+
+
+@respx.mock
+def test_not_found_comes_back_as_data():
+    respx.get(f"{BASE}/v1/users/nope").mock(
+        return_value=httpx.Response(404, json={"error": {"code": "not_found", "message": "no such object"}})
+    )
+    out = json.loads(GetUser(client=client()).invoke({"handle": "nope"}))
+    assert out["error"]["code"] == "not_found"
+
+
+@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) as caught:
+        GetUser(client=client()).invoke({"handle": "x"})
+    assert caught.value.code == "invalid_key"
+
+
+@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", "message": "slow down"}})
+    )
+    with pytest.raises(XdataapiError) as caught:
+        GetUser(client=client()).invoke({"handle": "x"})
+    assert caught.value.status == 429
+
+
+@respx.mock
+def test_an_upstream_fault_raises():
+    respx.get(f"{BASE}/v1/users/x").mock(return_value=httpx.Response(503, json={"error": {"code": "upstream"}}))
+    with pytest.raises(XdataapiError):
+        GetUser(client=client()).invoke({"handle": "x"})
+
+
+def test_a_missing_key_is_reported_before_any_request():
+    with pytest.raises(XdataapiAuthError):
+        XdataapiClient(None, base_url=BASE)
+
+
+@respx.mock
+def test_balance_takes_no_arguments_and_reads_me():
+    route = respx.get(f"{BASE}/v1/me").mock(return_value=httpx.Response(200, json={"balance": 4679.87}))
+    out = json.loads(GetBalance(client=client()).invoke({}))
+    assert route.called and out["balance"] == 4679.87
+
+
+@respx.mock
+async def test_the_async_path_calls_the_same_url():
+    route = respx.get(f"{BASE}/v1/users/x").mock(return_value=httpx.Response(200, json={"data": {}}))
+    await GetUser(client=client()).ainvoke({"handle": "x"})
+    assert route.called
+
+
+def test_the_toolkit_offers_every_tool_once():
+    tools = XdataapiToolkit.from_api_key("xd_live_test").get_tools()
+    names = [t.name for t in tools]
+    assert len(names) == 14
+    assert len(set(names)) == 14
+    assert "x_search_tweets" in names
+
+
+def test_include_narrows_the_surface():
+    tools = XdataapiToolkit.from_api_key("xd_live_test", include=["x_search_tweets"]).get_tools()
+    assert [t.name for t in tools] == ["x_search_tweets"]
+
+
+def test_exclude_drops_the_expensive_reads():
+    tools = XdataapiToolkit.from_api_key("xd_live_test", exclude=["x_get_followers"]).get_tools()
+    assert "x_get_followers" not in [t.name for t in tools]
+
+
+def test_the_toolkit_shares_one_capped_client():
+    tools = XdataapiToolkit.from_api_key("xd_live_test", max_results=10).get_tools()
+    assert {t.client for t in tools}.__len__() == 1
+    assert tools[0].client.max_results == 10
+
+
+def test_every_tool_describes_what_it_costs():
+    for tool in XdataapiToolkit.from_api_key("xd_live_test").get_tools():
+        assert "credit" in tool.description.lower() or "free" in tool.description.lower()