Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

Revert "[feat] add XquikToolkit for read-only X/Twitter search (#3997)" (#4052)

Tao Suna9680d2ef3ee
diff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.py
index 5beea9c77..76f768fe9 100644
--- a/camel/toolkits/__init__.py
+++ b/camel/toolkits/__init__.py
@@ -46,7 +46,6 @@ from .wechat_official_toolkit import WeChatOfficialToolkit
from .dingtalk import DingtalkToolkit
from .lark_toolkit import LarkToolkit
from .twitter_toolkit import TwitterToolkit
-from .xquik_toolkit import XquikToolkit
from .open_api_toolkit import OpenAPIToolkit
from .retrieval_toolkit import RetrievalToolkit
from .notion_toolkit import NotionToolkit
@@ -129,7 +128,6 @@ __all__ = [
'LarkToolkit',
'ImageGenToolkit',
'TwitterToolkit',
- 'XquikToolkit',
'WeatherToolkit',
'RetrievalToolkit',
'OpenAPIToolkit',
diff --git a/camel/toolkits/xquik_toolkit.py b/camel/toolkits/xquik_toolkit.py
deleted file mode 100644
index 6c236df23..000000000
--- a/camel/toolkits/xquik_toolkit.py
+++ /dev/null
@@ -1,260 +0,0 @@
-# ========= 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.py
deleted file mode 100644
index 3021cb52e..000000000
--- a/examples/toolkits/xquik_toolkit.py
+++ /dev/null
@@ -1,66 +0,0 @@
-# ========= 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.py
deleted file mode 100644
index 9d255ee36..000000000
--- a/test/toolkits/test_xquik_toolkit.py
+++ /dev/null
@@ -1,288 +0,0 @@
-# ========= 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()