🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
[feat] add XquikToolkit for read-only X/Twitter search (#3997) (#3998)
Burak Bayır158bb8c1fd3c
diff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.pyindex 76f768fe9..5beea9c77 100644--- a/camel/toolkits/__init__.py+++ b/camel/toolkits/__init__.py@@ -46,6 +46,7 @@ from .wechat_official_toolkit import WeChatOfficialToolkitfrom .dingtalk import DingtalkToolkitfrom .lark_toolkit import LarkToolkitfrom .twitter_toolkit import TwitterToolkit+from .xquik_toolkit import XquikToolkitfrom .open_api_toolkit import OpenAPIToolkitfrom .retrieval_toolkit import RetrievalToolkitfrom .notion_toolkit import NotionToolkit@@ -128,6 +129,7 @@ __all__ = ['LarkToolkit','ImageGenToolkit','TwitterToolkit',+ 'XquikToolkit','WeatherToolkit','RetrievalToolkit','OpenAPIToolkit',diff --git a/camel/toolkits/xquik_toolkit.py b/camel/toolkits/xquik_toolkit.pynew file mode 100644index 000000000..6c236df23--- /dev/null+++ b/camel/toolkits/xquik_toolkit.py@@ -0,0 +1,260 @@+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========+import json+import os+import urllib.parse+import urllib.request+from typing import Any, Dict, List, Optional++from camel.logger import get_logger+from camel.toolkits import FunctionTool+from camel.toolkits.base import BaseToolkit+from camel.utils import MCPServer, api_keys_required++logger = get_logger(__name__)++_BASE = "https://xquik.com/api/v1"+++@MCPServer()+class XquikToolkit(BaseToolkit):+ r"""A toolkit for read-only X (Twitter) operations via the Xquik API.++ Provides tweet search, tweet lookup, user profile lookup, and trending+ topics. Requires only ``XQUIK_API_KEY`` (1 env var) and no OAuth setup.++ For write operations (posting, deleting tweets), use+ :class:`TwitterToolkit` instead.++ References:+ https://xquik.com++ Notes:+ To use this toolkit, set the ``XQUIK_API_KEY`` environment variable.+ Get a key at https://xquik.com+ """++ @api_keys_required([(None, "XQUIK_API_KEY")])+ def __init__(self, timeout: Optional[float] = None):+ r"""Initialize the XquikToolkit with API credentials from env vars."""+ super().__init__(timeout=timeout)+ self.api_key = os.environ.get("XQUIK_API_KEY", "")++ def _xquik_get(+ self, path: str, params: Optional[Dict[str, Any]] = None+ ) -> Dict[str, Any]:+ r"""Make a GET request to the Xquik API.++ Args:+ path (str): API endpoint path.+ params (Optional[Dict[str, Any]]): Query parameters.++ Returns:+ Dict[str, Any]: Parsed JSON response.++ Raises:+ RuntimeError: If the API request fails.+ """+ url = f"{_BASE}{path}"+ if params:+ qs = urllib.parse.urlencode(+ {k: v for k, v in params.items() if v is not None}+ )+ url = f"{url}?{qs}"++ req = urllib.request.Request(+ url,+ headers={+ "X-API-Key": self.api_key,+ "Accept": "application/json",+ "User-Agent": "camel-ai/1.0",+ },+ )+ with urllib.request.urlopen(req, timeout=15) as resp:+ return json.loads(resp.read().decode("utf-8"))++ def xquik_search_tweets(+ self,+ query: str,+ max_results: int = 10,+ sort_order: str = "Top",+ ) -> str:+ r"""Search for tweets on X (Twitter).++ Supports X search operators: ``from:user``, ``#hashtag``,+ ``"exact phrase"``, ``since:YYYY-MM-DD``, ``until:YYYY-MM-DD``,+ ``-is:retweet``, ``-is:reply``, ``has:media``.++ Args:+ query (str): The search query.+ max_results (int): Maximum number of tweets to return (1-200).+ (default: :obj:`10`)+ sort_order (str): Sort order, "Top" (engagement) or "Latest"+ (chronological). (default: :obj:`"Top"`)++ Returns:+ str: A JSON-formatted string containing the search results with+ tweet text, author info, engagement metrics, and URLs.+ """+ try:+ max_results = max(1, min(max_results, 200))+ data = self._xquik_get(+ "/x/tweets/search",+ {"q": query, "limit": max_results, "queryType": sort_order},+ )+ tweets = data.get("tweets", [])+ results = []+ for tweet in tweets:+ author = tweet.get("author", {})+ results.append(+ {+ "id": tweet.get("id", ""),+ "text": tweet.get("text", ""),+ "created_at": tweet.get("createdAt", ""),+ "author": {+ "username": author.get("username", ""),+ "name": author.get("name", ""),+ "verified": author.get("verified", False),+ },+ "metrics": {+ "likes": tweet.get("likeCount", 0),+ "retweets": tweet.get("retweetCount", 0),+ "replies": tweet.get("replyCount", 0),+ "quotes": tweet.get("quoteCount", 0),+ "views": tweet.get("viewCount", 0),+ "bookmarks": tweet.get("bookmarkCount", 0),+ },+ "url": (+ "https://x.com/"+ f"{author.get('username', 'unknown')}"+ f"/status/{tweet.get('id', '')}"+ ),+ }+ )+ return json.dumps(+ {"query": query, "count": len(results), "tweets": results},+ indent=2,+ )+ except Exception as e:+ logger.exception("Error searching tweets via Xquik")+ return json.dumps({"error": str(e), "query": query})++ def xquik_get_tweet(self, tweet_id: str) -> str:+ r"""Retrieve a single tweet by ID with full engagement metrics.++ Args:+ tweet_id (str): The tweet ID to look up.++ Returns:+ str: A JSON-formatted string containing the tweet text, author+ info, and engagement metrics.+ """+ try:+ data = self._xquik_get(f"/x/tweets/{tweet_id}")+ tweet = data.get("tweet")+ if not isinstance(tweet, dict):+ tweet = data+ author = data.get("author")+ if not isinstance(author, dict):+ author = tweet.get("author", {})+ result = {+ "id": tweet.get("id", ""),+ "text": tweet.get("text", ""),+ "created_at": tweet.get("createdAt", ""),+ "author": {+ "username": author.get("username", ""),+ "name": author.get("name", ""),+ "verified": author.get("verified", False),+ },+ "metrics": {+ "likes": tweet.get("likeCount", 0),+ "retweets": tweet.get("retweetCount", 0),+ "replies": tweet.get("replyCount", 0),+ "quotes": tweet.get("quoteCount", 0),+ "views": tweet.get("viewCount", 0),+ "bookmarks": tweet.get("bookmarkCount", 0),+ },+ "url": (+ f"https://x.com/{author.get('username', 'unknown')}"+ f"/status/{tweet.get('id', '')}"+ ),+ }+ return json.dumps(result, indent=2)+ except Exception as e:+ logger.exception("Error fetching tweet via Xquik")+ return json.dumps({"error": str(e)})++ def xquik_get_user_info(self, username: str) -> str:+ r"""Retrieve information about a specific X (Twitter) user.++ Args:+ username (str): The username (without @) to look up.++ Returns:+ str: A JSON-formatted string with the user's profile information.+ """+ try:+ data = self._xquik_get(f"/x/users/{username.lstrip('@')}")+ result = {+ "id": data.get("id", ""),+ "name": data.get("name", ""),+ "username": data.get("username", ""),+ "description": data.get("description", ""),+ "followers": data.get("followers", 0),+ "following": data.get("following", 0),+ "tweet_count": data.get("statusesCount", 0),+ "verified": data.get("verified", False),+ "url": f"https://x.com/{data.get('username', username)}",+ }+ return json.dumps(result, indent=2)+ except Exception as e:+ logger.exception("Error fetching user info via Xquik")+ return json.dumps({"error": str(e)})++ def xquik_get_trends(self, woeid: int = 1, count: int = 20) -> str:+ r"""Get trending topics on X (Twitter).++ Args:+ woeid (int): WOEID for region. 1=Global, 23424977=US,+ 23424975=UK. (default: :obj:`1`)+ count (int): Number of trends to return (1-50).+ (default: :obj:`20`)++ Returns:+ str: A JSON-formatted string with a list of trending topics.+ """+ try:+ count = max(1, min(count, 50))+ data = self._xquik_get(+ "/x/trends", {"woeid": woeid, "count": count}+ )+ return json.dumps({"trends": data.get("trends", [])}, indent=2)+ except Exception as e:+ logger.exception("Error fetching trends via Xquik")+ return json.dumps({"error": str(e)})++ def get_tools(self) -> List[FunctionTool]:+ r"""Returns a list of FunctionTool objects representing the+ functions in the toolkit.++ Returns:+ List[FunctionTool]: A list of FunctionTool objects+ representing the functions in the toolkit.+ """+ return [+ FunctionTool(self.xquik_search_tweets),+ FunctionTool(self.xquik_get_tweet),+ FunctionTool(self.xquik_get_user_info),+ FunctionTool(self.xquik_get_trends),+ ]diff --git a/examples/toolkits/xquik_toolkit.py b/examples/toolkits/xquik_toolkit.pynew file mode 100644index 000000000..3021cb52e--- /dev/null+++ b/examples/toolkits/xquik_toolkit.py@@ -0,0 +1,66 @@+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========++import os++from camel.agents import ChatAgent+from camel.models import ModelFactory+from camel.toolkits import XquikToolkit+from camel.types import ModelPlatformType, ModelType+++def main() -> None:+ r"""Run read-only X (Twitter) research with ChatAgent and XquikToolkit.++ Set ``XQUIK_API_KEY`` and your model provider credentials before running+ this example.+ """+ if not os.environ.get("XQUIK_API_KEY"):+ raise RuntimeError("Set XQUIK_API_KEY before running this example.")++ tools = XquikToolkit().get_tools()+ model = ModelFactory.create(+ model_platform=ModelPlatformType.DEFAULT,+ model_type=ModelType.DEFAULT,+ )++ agent = ChatAgent(+ system_message=(+ "You are a social research assistant. Use Xquik tools for "+ "read-only X/Twitter search, profile lookup, and trends. "+ "Summarize results concisely and include source URLs when present."+ ),+ model=model,+ tools=tools,+ )+ agent.reset()++ user_messages = [+ (+ "Search X for recent posts about CAMEL-AI and multi-agent "+ "frameworks. Return three concise findings."+ ),+ "Look up the X profile CamelAIOrg and summarize the public profile.",+ "Get the top five global X trends and group them by topic.",+ ]++ for user_message in user_messages:+ response = agent.step(user_message)+ print(f"User: {user_message}")+ print(f"Tool calls: {response.info.get('tool_calls', [])}")+ print(f"Agent: {response.msg.content}\n")+++if __name__ == "__main__":+ main()diff --git a/test/toolkits/test_xquik_toolkit.py b/test/toolkits/test_xquik_toolkit.pynew file mode 100644index 000000000..9d255ee36--- /dev/null+++ b/test/toolkits/test_xquik_toolkit.py@@ -0,0 +1,288 @@+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========++import json+from typing import Any, Dict, List, Tuple+from urllib.parse import parse_qs, urlparse++import pytest++from camel.toolkits import FunctionTool, XquikToolkit+++class FakeResponse:+ def __init__(self, payload: Dict[str, Any]) -> None:+ self.payload = payload++ def __enter__(self) -> "FakeResponse":+ return self++ def __exit__(self, *args: Any) -> None:+ return None++ def read(self) -> bytes:+ return json.dumps(self.payload).encode("utf-8")++[email protected](autouse=True)+def set_xquik_api_key(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("XQUIK_API_KEY", "test-api-key")+++def test_xquik_get_builds_authorized_request(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ captured: Dict[str, Any] = {}++ def fake_urlopen(request: Any, timeout: int) -> FakeResponse:+ captured["url"] = request.full_url+ captured["timeout"] = timeout+ captured["headers"] = {+ key.lower(): value for key, value in request.header_items()+ }+ return FakeResponse({"ok": True})++ monkeypatch.setattr(+ "camel.toolkits.xquik_toolkit.urllib.request.urlopen",+ fake_urlopen,+ )++ result = XquikToolkit()._xquik_get(+ "/x/tweets/search",+ {"q": "camel ai", "limit": 10, "empty": None},+ )++ parsed_url = urlparse(captured["url"])+ assert result == {"ok": True}+ assert parsed_url.scheme == "https"+ assert parsed_url.netloc == "xquik.com"+ assert parsed_url.path == "/api/v1/x/tweets/search"+ assert parse_qs(parsed_url.query) == {+ "limit": ["10"],+ "q": ["camel ai"],+ }+ assert captured["timeout"] == 15+ assert captured["headers"]["x-api-key"] == "test-api-key"+ assert captured["headers"]["accept"] == "application/json"+ assert captured["headers"]["user-agent"] == "camel-ai/1.0"+++def test_xquik_search_tweets_formats_results(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ calls: List[Tuple[str, Dict[str, Any]]] = []+ toolkit = XquikToolkit()++ def fake_xquik_get(+ path: str, params: Dict[str, Any] | None = None+ ) -> Dict[str, Any]:+ calls.append((path, params or {}))+ return {+ "tweets": [+ {+ "id": "123",+ "text": "CAMEL adds a toolkit",+ "createdAt": "2026-05-12T00:00:00Z",+ "author": {+ "username": "CamelAIOrg",+ "name": "CAMEL-AI",+ "verified": True,+ },+ "likeCount": 12,+ "retweetCount": 3,+ "replyCount": 2,+ "quoteCount": 1,+ "viewCount": 1000,+ "bookmarkCount": 4,+ }+ ]+ }++ monkeypatch.setattr(toolkit, "_xquik_get", fake_xquik_get)++ result = json.loads(+ toolkit.xquik_search_tweets(+ "from:CamelAIOrg -is:retweet",+ max_results=500,+ sort_order="Latest",+ )+ )++ assert calls == [+ (+ "/x/tweets/search",+ {+ "limit": 200,+ "q": "from:CamelAIOrg -is:retweet",+ "queryType": "Latest",+ },+ )+ ]+ assert result == {+ "count": 1,+ "query": "from:CamelAIOrg -is:retweet",+ "tweets": [+ {+ "author": {+ "name": "CAMEL-AI",+ "username": "CamelAIOrg",+ "verified": True,+ },+ "created_at": "2026-05-12T00:00:00Z",+ "id": "123",+ "metrics": {+ "bookmarks": 4,+ "likes": 12,+ "quotes": 1,+ "replies": 2,+ "retweets": 3,+ "views": 1000,+ },+ "text": "CAMEL adds a toolkit",+ "url": "https://x.com/CamelAIOrg/status/123",+ }+ ],+ }++ calls.clear()+ toolkit.xquik_search_tweets("CAMEL-AI", max_results=1)++ assert calls == [+ (+ "/x/tweets/search",+ {"limit": 1, "q": "CAMEL-AI", "queryType": "Top"},+ )+ ]+++def test_xquik_get_tweet_formats_single_tweet(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ calls: List[Tuple[str, Dict[str, Any] | None]] = []+ toolkit = XquikToolkit()++ def fake_xquik_get(+ path: str, params: Dict[str, Any] | None = None+ ) -> Dict[str, Any]:+ calls.append((path, params))+ return {+ "tweet": {+ "id": "456",+ "text": "A specific tweet",+ "createdAt": "2026-05-12T01:00:00Z",+ "likeCount": 5,+ "retweetCount": 4,+ "replyCount": 3,+ "quoteCount": 2,+ "viewCount": 100,+ "bookmarkCount": 1,+ },+ "author": {"username": "CamelAIOrg", "name": "CAMEL-AI"},+ }++ monkeypatch.setattr(toolkit, "_xquik_get", fake_xquik_get)++ result = json.loads(toolkit.xquik_get_tweet("456"))++ assert calls == [("/x/tweets/456", None)]+ assert result["id"] == "456"+ assert result["author"]["username"] == "CamelAIOrg"+ assert result["metrics"]["likes"] == 5+ assert result["url"] == "https://x.com/CamelAIOrg/status/456"+++def test_xquik_get_user_info_strips_at_sign(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ calls: List[Tuple[str, Dict[str, Any] | None]] = []+ toolkit = XquikToolkit()++ def fake_xquik_get(+ path: str, params: Dict[str, Any] | None = None+ ) -> Dict[str, Any]:+ calls.append((path, params))+ return {+ "description": "Multi-agent framework",+ "followers": 100,+ "following": 10,+ "id": "789",+ "name": "CAMEL-AI",+ "statusesCount": 50,+ "username": "CamelAIOrg",+ "verified": True,+ }++ monkeypatch.setattr(toolkit, "_xquik_get", fake_xquik_get)++ result = json.loads(toolkit.xquik_get_user_info("@CamelAIOrg"))++ assert calls == [("/x/users/CamelAIOrg", None)]+ assert result == {+ "description": "Multi-agent framework",+ "followers": 100,+ "following": 10,+ "id": "789",+ "name": "CAMEL-AI",+ "tweet_count": 50,+ "url": "https://x.com/CamelAIOrg",+ "username": "CamelAIOrg",+ "verified": True,+ }+++def test_xquik_get_trends_clamps_count(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ calls: List[Tuple[str, Dict[str, Any]]] = []+ toolkit = XquikToolkit()++ def fake_xquik_get(+ path: str, params: Dict[str, Any] | None = None+ ) -> Dict[str, Any]:+ calls.append((path, params or {}))+ return {"trends": [{"name": "CAMEL", "tweet_volume": 1234}]}++ monkeypatch.setattr(toolkit, "_xquik_get", fake_xquik_get)++ result = json.loads(toolkit.xquik_get_trends(woeid=23424977, count=99))++ assert calls == [("/x/trends", {"count": 50, "woeid": 23424977})]+ assert result == {"trends": [{"name": "CAMEL", "tweet_volume": 1234}]}++ result = json.loads(toolkit.xquik_get_trends(woeid=1, count=-1))++ assert calls[-1] == ("/x/trends", {"count": 1, "woeid": 1})+ assert result == {"trends": [{"name": "CAMEL", "tweet_volume": 1234}]}+++def test_xquik_toolkit_get_tools() -> None:+ tools = XquikToolkit().get_tools()++ assert len(tools) == 4+ assert all(isinstance(tool, FunctionTool) for tool in tools)+ assert [tool.get_function_name() for tool in tools] == [+ "xquik_search_tweets",+ "xquik_get_tweet",+ "xquik_get_user_info",+ "xquik_get_trends",+ ]+++def test_xquik_toolkit_requires_api_key(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.delenv("XQUIK_API_KEY")++ with pytest.raises(ValueError, match="XQUIK_API_KEY"):+ XquikToolkit()