camel-datacircle 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,9 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Datacircle
4
+
5
+ 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:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ 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.
@@ -0,0 +1,82 @@
1
+ Metadata-Version: 2.5
2
+ Name: camel-datacircle
3
+ Version: 0.1.0
4
+ Summary: A CAMEL toolkit for the Datacircle API: find the best GTM APIs
5
+ Project-URL: Homepage, https://datacircle.dev
6
+ Project-URL: Documentation, https://api.datacircle.dev/v1/openapi.json
7
+ Project-URL: Repository, https://github.com/waynehamadi/camel-datacircle
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: agents,api,api-pricing,b2b-data,camel,camel-ai,datacircle,gtm,mcp,toolkit,tools
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Software Development :: Libraries
14
+ Requires-Python: >=3.10
15
+ Requires-Dist: camel-ai>=0.2.61
16
+ Requires-Dist: httpx>=0.28
17
+ Requires-Dist: mcp<2,>=1.3.0
18
+ Description-Content-Type: text/markdown
19
+
20
+ # camel-datacircle
21
+
22
+ Find the best GTM APIs. We benchmark all the GTM APIs and we put the results on our website: https://datacircle.dev
23
+
24
+ This package gives [CAMEL](https://github.com/camel-ai/camel) a toolkit of four tools on Datacircle's open API, https://api.datacircle.dev/v1. You need no key and no account.
25
+
26
+ ```bash
27
+ pip install camel-datacircle
28
+ ```
29
+
30
+ | Tool | What it gives | Call |
31
+ | --- | --- | --- |
32
+ | `datacircle_list_apis` | Every GTM API on Datacircle, with its slug, number of plans and providers, and its best plan | `GET /apis` |
33
+ | `datacircle_best_plans` | One API's plans, best first by score out of 100, each with its rank and price per 1,000 calls | `GET /apis/{slug}/best` |
34
+ | `datacircle_search_plans` | Plans by provider or plan name, on every API or one, sorted by score, provider or price | `GET /plans` |
35
+ | `datacircle_provider` | The APIs a provider sells and its rank on each | `GET /providers/{slug}` |
36
+
37
+ ## Use
38
+
39
+ ```python
40
+ from camel.agents import ChatAgent
41
+ from camel_datacircle import DatacircleToolkit
42
+
43
+ agent = ChatAgent(
44
+ system_message="Answer from the datacircle tools.",
45
+ tools=DatacircleToolkit().get_tools(),
46
+ )
47
+ response = agent.step("Which email finder API is best for under $5 per 1,000?")
48
+ print(response.msgs[0].content)
49
+ ```
50
+
51
+ The agent runs on CAMEL's default model, or the one you give it with `model=ModelFactory.create(...)`. The tools work with `step` and `astep`, beside any other toolkit's, and with a streamed model from CAMEL 0.2.74. CAMEL 0.2.61 and later, Python 3.10 and later.
52
+
53
+ The same calls without an agent, each giving a dict:
54
+
55
+ ```python
56
+ from camel_datacircle import DatacircleToolkit
57
+
58
+ print(DatacircleToolkit().datacircle_best_plans("email-finder", limit=3))
59
+ ```
60
+
61
+ Each plan comes with its rank, provider, plan, score, price per 1,000 (`perThousand`, in dollars) and its page on datacircle.dev, which lists every field. A slug can be a name: `Bright Data` is sent as `bright-data`. An unknown slug or an argument out of range comes back as `{"error": ...}` with the API's words (an unknown API's answer lists every slug), so the model can call again.
62
+
63
+ ## As an MCP server
64
+
65
+ Like CAMEL's own toolkits, it serves its four tools over MCP:
66
+
67
+ ```bash
68
+ python -c "from camel_datacircle import DatacircleToolkit; DatacircleToolkit().run_mcp_server('stdio')"
69
+ ```
70
+
71
+ ## Network
72
+
73
+ Each call makes one HTTPS GET to https://api.datacircle.dev/v1 with the tool's arguments and nothing else. The API takes up to 60 calls a minute from one address; the tools wait once, a minute at most, when it asks them to. `DatacircleToolkit(timeout=10)` sets how long a call may take. Every plan is also one file at https://datacircle.dev/datacircle.json.
74
+
75
+ ## Links
76
+
77
+ - Datacircle: https://datacircle.dev
78
+ - The API: https://datacircle.dev/api
79
+ - Its spec: https://api.datacircle.dev/v1/openapi.json
80
+ - What each key means: https://datacircle.dev/fields
81
+
82
+ MIT license.
@@ -0,0 +1,63 @@
1
+ # camel-datacircle
2
+
3
+ Find the best GTM APIs. We benchmark all the GTM APIs and we put the results on our website: https://datacircle.dev
4
+
5
+ This package gives [CAMEL](https://github.com/camel-ai/camel) a toolkit of four tools on Datacircle's open API, https://api.datacircle.dev/v1. You need no key and no account.
6
+
7
+ ```bash
8
+ pip install camel-datacircle
9
+ ```
10
+
11
+ | Tool | What it gives | Call |
12
+ | --- | --- | --- |
13
+ | `datacircle_list_apis` | Every GTM API on Datacircle, with its slug, number of plans and providers, and its best plan | `GET /apis` |
14
+ | `datacircle_best_plans` | One API's plans, best first by score out of 100, each with its rank and price per 1,000 calls | `GET /apis/{slug}/best` |
15
+ | `datacircle_search_plans` | Plans by provider or plan name, on every API or one, sorted by score, provider or price | `GET /plans` |
16
+ | `datacircle_provider` | The APIs a provider sells and its rank on each | `GET /providers/{slug}` |
17
+
18
+ ## Use
19
+
20
+ ```python
21
+ from camel.agents import ChatAgent
22
+ from camel_datacircle import DatacircleToolkit
23
+
24
+ agent = ChatAgent(
25
+ system_message="Answer from the datacircle tools.",
26
+ tools=DatacircleToolkit().get_tools(),
27
+ )
28
+ response = agent.step("Which email finder API is best for under $5 per 1,000?")
29
+ print(response.msgs[0].content)
30
+ ```
31
+
32
+ The agent runs on CAMEL's default model, or the one you give it with `model=ModelFactory.create(...)`. The tools work with `step` and `astep`, beside any other toolkit's, and with a streamed model from CAMEL 0.2.74. CAMEL 0.2.61 and later, Python 3.10 and later.
33
+
34
+ The same calls without an agent, each giving a dict:
35
+
36
+ ```python
37
+ from camel_datacircle import DatacircleToolkit
38
+
39
+ print(DatacircleToolkit().datacircle_best_plans("email-finder", limit=3))
40
+ ```
41
+
42
+ Each plan comes with its rank, provider, plan, score, price per 1,000 (`perThousand`, in dollars) and its page on datacircle.dev, which lists every field. A slug can be a name: `Bright Data` is sent as `bright-data`. An unknown slug or an argument out of range comes back as `{"error": ...}` with the API's words (an unknown API's answer lists every slug), so the model can call again.
43
+
44
+ ## As an MCP server
45
+
46
+ Like CAMEL's own toolkits, it serves its four tools over MCP:
47
+
48
+ ```bash
49
+ python -c "from camel_datacircle import DatacircleToolkit; DatacircleToolkit().run_mcp_server('stdio')"
50
+ ```
51
+
52
+ ## Network
53
+
54
+ Each call makes one HTTPS GET to https://api.datacircle.dev/v1 with the tool's arguments and nothing else. The API takes up to 60 calls a minute from one address; the tools wait once, a minute at most, when it asks them to. `DatacircleToolkit(timeout=10)` sets how long a call may take. Every plan is also one file at https://datacircle.dev/datacircle.json.
55
+
56
+ ## Links
57
+
58
+ - Datacircle: https://datacircle.dev
59
+ - The API: https://datacircle.dev/api
60
+ - Its spec: https://api.datacircle.dev/v1/openapi.json
61
+ - What each key means: https://datacircle.dev/fields
62
+
63
+ MIT license.
@@ -0,0 +1,32 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "camel-datacircle"
7
+ version = "0.1.0"
8
+ description = "A CAMEL toolkit for the Datacircle API: find the best GTM APIs"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.10"
12
+ dependencies = ["camel-ai>=0.2.61", "mcp>=1.3.0,<2", "httpx>=0.28"]
13
+ keywords = ["camel", "camel-ai", "toolkit", "agents", "tools", "mcp", "gtm", "api", "api-pricing", "b2b-data", "datacircle"]
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "Operating System :: OS Independent",
17
+ "Topic :: Software Development :: Libraries",
18
+ ]
19
+
20
+ [project.urls]
21
+ Homepage = "https://datacircle.dev"
22
+ Documentation = "https://api.datacircle.dev/v1/openapi.json"
23
+ Repository = "https://github.com/waynehamadi/camel-datacircle"
24
+
25
+ [dependency-groups]
26
+ test = ["pytest>=8"]
27
+
28
+ [tool.hatch.build.targets.wheel]
29
+ packages = ["src/camel_datacircle"]
30
+
31
+ [tool.hatch.build.targets.sdist]
32
+ include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
@@ -0,0 +1,6 @@
1
+ """A CAMEL toolkit for Datacircle's open API (https://api.datacircle.dev/v1): find the best GTM APIs, no key."""
2
+
3
+ from camel_datacircle.toolkit import DatacircleToolkit
4
+
5
+ __version__ = "0.1.0"
6
+ __all__ = ["DatacircleToolkit", "__version__"]
@@ -0,0 +1,87 @@
1
+ """One HTTPS GET to Datacircle's open API (https://api.datacircle.dev/v1), no key, and what its answers are cut to for a model."""
2
+
3
+ import re
4
+ import time
5
+ import unicodedata
6
+ from typing import Any, Dict, List, Optional
7
+
8
+ import httpx
9
+
10
+ BASE_URL = "https://api.datacircle.dev/v1"
11
+ USER_AGENT = "camel-datacircle/0.1.0"
12
+
13
+ # A plan holds about 90 keys (its terms of use, its aggregators...): the tools keep the ones that choose a plan, the rest is on its page.
14
+ PLAN_KEYS = ["api", "rank", "provider", "plan", "score", "perThousand", "notFoundPerThousand", "billing", "pay",
15
+ "currency", "units", "unit", "strengths", "latencyMs", "page", "pricingPage", "docs"]
16
+ API_KEYS = ["api", "slug", "plans", "providers", "best", "bestPage", "sheetPage"]
17
+
18
+
19
+ class DatacircleError(Exception):
20
+ """The API's refusal in its own words, or why it could not be reached: a tool gives it to the model as its answer."""
21
+
22
+
23
+ def brief(item: Dict[str, Any], keys: List[str] = PLAN_KEYS) -> Dict[str, Any]:
24
+ return {key: item[key] for key in keys if item.get(key) is not None}
25
+
26
+
27
+ def slug(value: Any) -> str:
28
+ """The API's rule for a slug: the name in lowercase letters and digits, the rest a hyphen."""
29
+ plain = unicodedata.normalize("NFKD", str(value or "").strip().lower())
30
+ plain = "".join(char for char in plain if not unicodedata.combining(char))
31
+ return re.sub(r"[^a-z0-9]+", "-", plain).strip("-")
32
+
33
+
34
+ def number(value: Any, name: str, low: int, high: Optional[int]) -> Optional[int]:
35
+ """A model's limit or offset as a whole number in its range, or None when left out."""
36
+ if value is None or value == "":
37
+ return None
38
+ if isinstance(value, bool):
39
+ raise DatacircleError(f"{name} must be a whole number, not {value!r}")
40
+ try:
41
+ made = int(value)
42
+ except (TypeError, ValueError):
43
+ raise DatacircleError(f"{name} must be a whole number, not {value!r}") from None
44
+ if made != value and str(made) != str(value).strip():
45
+ raise DatacircleError(f"{name} must be a whole number, not {value!r}")
46
+ if made < low or (high is not None and made > high):
47
+ raise DatacircleError(f"{name} must be {low} or more" + (f" and {high} or less" if high is not None else ""))
48
+ return made
49
+
50
+
51
+ def _words(answer: httpx.Response) -> str:
52
+ """A refusal's words: the API's error, with every slug when the slug was unknown."""
53
+ try:
54
+ parsed = answer.json()
55
+ if parsed.get("slugs"):
56
+ return f"{parsed['error']}; the slugs: {', '.join(parsed['slugs'])}"
57
+ return str(parsed.get("error", answer.text))
58
+ except (ValueError, KeyError, TypeError, AttributeError):
59
+ return answer.text
60
+
61
+
62
+ def get(path: str, params: Optional[Dict[str, Any]] = None, base_url: str = BASE_URL, timeout: float = 30) -> Any:
63
+ """The API's JSON answer, or a DatacircleError with its words: an unknown slug's answer lists every slug."""
64
+ query = {key: value for key, value in (params or {}).items() if value not in (None, "")}
65
+ url = f"{base_url.rstrip('/')}{path}"
66
+ headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
67
+ for attempt in range(2):
68
+ try:
69
+ answer = httpx.get(url, params=query, headers=headers, timeout=timeout, follow_redirects=True)
70
+ except httpx.HTTPError as error:
71
+ raise DatacircleError(f"Datacircle's API could not be reached: {error!r}") from None
72
+ if answer.status_code == 429:
73
+ if attempt:
74
+ break
75
+ try:
76
+ wait = int(answer.headers.get("Retry-After") or 30)
77
+ except ValueError:
78
+ wait = 30
79
+ time.sleep(min(max(wait, 1), 60))
80
+ continue
81
+ if answer.status_code >= 400:
82
+ raise DatacircleError(f"Datacircle's API answered {answer.status_code}: {_words(answer)[:3000]}")
83
+ try:
84
+ return answer.json()
85
+ except ValueError as error:
86
+ raise DatacircleError(f"Datacircle's API gave no JSON: {error}") from None
87
+ raise DatacircleError("Datacircle's API answered 429 twice: wait a minute and call again")
File without changes
@@ -0,0 +1,184 @@
1
+ """A CAMEL toolkit on Datacircle's open API, https://api.datacircle.dev/v1: no key, no account."""
2
+
3
+ import urllib.parse
4
+ from typing import Any, Callable, Dict, List, Literal, Optional
5
+
6
+ from camel.toolkits import BaseToolkit, FunctionTool
7
+ from camel.utils import MCPServer
8
+
9
+ from camel_datacircle import _api
10
+
11
+ SORTS = ("score", "provider", "price")
12
+
13
+
14
+ def _answer(make: Callable[[], Dict[str, Any]]) -> Dict[str, Any]:
15
+ """What the API gave, or {"error": ...} with its words for the model to read."""
16
+ try:
17
+ return make()
18
+ except _api.DatacircleError as error:
19
+ return {"error": str(error)}
20
+
21
+
22
+ def _best(plans: Any) -> Optional[Dict[str, Any]]:
23
+ """A provider's best plan on an API: its lowest rank, a plan with no score having none."""
24
+ ranked = sorted(plans, key=lambda plan: plan.get("rank") if isinstance(plan.get("rank"), (int, float)) else float("inf"))
25
+ return _api.brief(ranked[0], ["plan", "score", "perThousand", "page"]) if ranked else None
26
+
27
+
28
+ def _list_apis(base_url: str, timeout: float, query: Optional[str], limit: Optional[int]) -> Dict[str, Any]:
29
+ most = _api.number(limit, "limit", 1, 200) or 20
30
+ apis = _api.get("/apis", base_url=base_url, timeout=timeout)
31
+ words = [word for word in str(query or "").lower().replace("-", " ").split() if word]
32
+ held = []
33
+ for index, api in enumerate(apis):
34
+ name = f"{api.get('api', '')} {str(api.get('slug', '')).replace('-', ' ')}".lower()
35
+ matched = sum(word in name for word in words)
36
+ if matched or not words:
37
+ held.append((-matched, index, api))
38
+ found = [_api.brief(api, _api.API_KEYS) for _, _, api in sorted(held, key=lambda h: h[:2])]
39
+ return {"total": len(found), "apis": found[:most]}
40
+
41
+
42
+ def _best_plans(base_url: str, timeout: float, slug: str, limit: Optional[int]) -> Dict[str, Any]:
43
+ made = _api.slug(slug)
44
+ if not made:
45
+ raise _api.DatacircleError("Give an API's slug, like 'email-finder': datacircle_list_apis gives every slug")
46
+ answer = _api.get(f"/apis/{urllib.parse.quote(made)}/best", {"limit": _api.number(limit, "limit", 1, 50)},
47
+ base_url=base_url, timeout=timeout)
48
+ return {**answer, "plans": [_api.brief(plan) for plan in answer.get("plans") or []]}
49
+
50
+
51
+ def _search_plans(base_url: str, timeout: float, api: Optional[str], query: Optional[str], sort: Optional[str],
52
+ limit: Optional[int], offset: Optional[int]) -> Dict[str, Any]:
53
+ order = str(sort).strip().lower() if sort not in (None, "") else None
54
+ if order is not None and order not in SORTS:
55
+ raise _api.DatacircleError(f"sort must be score, provider or price, not {sort!r}")
56
+ params = {"api": api, "query": query, "sort": order, "limit": _api.number(limit, "limit", 1, 50),
57
+ "offset": _api.number(offset, "offset", 0, None)}
58
+ answer = _api.get("/plans", params, base_url=base_url, timeout=timeout)
59
+ return {**answer, "plans": [_api.brief(plan) for plan in answer.get("plans") or []]}
60
+
61
+
62
+ def _provider(base_url: str, timeout: float, slug: str) -> Dict[str, Any]:
63
+ made = _api.slug(slug)
64
+ if not made:
65
+ raise _api.DatacircleError("Give a provider's slug or name, like 'bright-data' or 'Bright Data'")
66
+ answer = _api.get(f"/providers/{urllib.parse.quote(made)}", base_url=base_url, timeout=timeout)
67
+ apis = [{**_api.brief(entry, ["api", "slug", "rank", "bestPage"]), "plans": len(entry.get("plans") or []),
68
+ "best": _best(entry.get("plans") or [])} for entry in answer.get("apis") or []]
69
+ return {**answer, "apis": apis}
70
+
71
+
72
+ @MCPServer()
73
+ class DatacircleToolkit(BaseToolkit):
74
+ r"""A toolkit for Datacircle's benchmark of GTM APIs (https://datacircle.dev): every API it lists, who is best
75
+ for each, every plan and each provider's ranks, from its open API at https://api.datacircle.dev/v1, with no key.
76
+
77
+ Each tool makes one HTTPS GET and gives the answer as a dict, or ``{"error": ...}`` with the API's words, so the
78
+ model can call again.
79
+
80
+ Args:
81
+ timeout (Optional[float]): Seconds each call may take, and the toolkit's timeout. 30 seconds for the HTTP
82
+ request when None. (default: :obj:`None`)
83
+ base_url (str): The API's address. (default: :obj:`"https://api.datacircle.dev/v1"`)
84
+ """
85
+
86
+ def __init__(self, timeout: Optional[float] = None, base_url: str = _api.BASE_URL) -> None:
87
+ super().__init__(timeout=timeout)
88
+ self.base_url = base_url
89
+
90
+ @property
91
+ def _seconds(self) -> float:
92
+ return self.timeout or 30
93
+
94
+ def datacircle_list_apis(self, query: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]:
95
+ r"""Lists the GTM APIs on Datacircle's sheet (https://datacircle.dev), with each API's slug, how many plans
96
+ and providers it has and its best plan. Call it first to find an API's slug. Gives total, the APIs found,
97
+ and apis, up to limit of them.
98
+
99
+ Args:
100
+ query (Optional[str]): Words of the API's name or slug, like 'email' or 'linkedin profile': the APIs
101
+ that hold the most of them come first. The sheet's order when left out.
102
+ limit (Optional[int]): How many APIs to give, 1 to 200. 20 when left out: the sheet has about 160.
103
+
104
+ Returns:
105
+ Dict[str, Any]: total and apis, or error with the API's words.
106
+ """
107
+ return _answer(lambda: _list_apis(self.base_url, self._seconds, query, limit))
108
+
109
+ def datacircle_best_plans(self, slug: str, limit: Optional[int] = None) -> Dict[str, Any]:
110
+ r"""Gives an API's plans best first by their score out of 100 on Datacircle's benchmark
111
+ (https://datacircle.dev), each with its rank, provider, plan, $ per 1,000 calls and its page. perThousand
112
+ is a plan's price of 1,000 items in dollars, pay the plan's whole price in its currency.
113
+
114
+ Args:
115
+ slug (str): The API's slug, like 'email-finder' or 'linkedin-profile', as datacircle_list_apis gives
116
+ it.
117
+ limit (Optional[int]): How many plans to give, 1 to 50. 10 when left out.
118
+
119
+ Returns:
120
+ Dict[str, Any]: the API, its pages, total and plans, or error with the API's words.
121
+ """
122
+ return _answer(lambda: _best_plans(self.base_url, self._seconds, slug, limit))
123
+
124
+ def datacircle_search_plans(
125
+ self,
126
+ api: Optional[str] = None,
127
+ query: Optional[str] = None,
128
+ sort: Optional[Literal["score", "provider", "price"]] = None,
129
+ limit: Optional[int] = None,
130
+ offset: Optional[int] = None,
131
+ ) -> Dict[str, Any]:
132
+ r"""Searches every plan on Datacircle's sheet (https://datacircle.dev), or one API's, by provider or plan
133
+ name, sorted by score, provider or price. Gives total, offset and up to limit plans. perThousand is a
134
+ plan's price of 1,000 items in dollars, pay the plan's whole price in its currency.
135
+
136
+ Args:
137
+ api (Optional[str]): Only this API's plans: its name or slug, like 'email-finder'. A provider's name
138
+ goes in query, never here. Every API when left out.
139
+ query (Optional[str]): Words that must all appear in the provider's or plan's name, like
140
+ 'bright data'.
141
+ sort (Optional[Literal["score", "provider", "price"]]): score (best first, the default), provider
142
+ (A to Z) or price ($ per 1,000, lowest first).
143
+ limit (Optional[int]): How many plans to give, 1 to 50. 10 when left out.
144
+ offset (Optional[int]): How many found plans to skip first. 0 when left out.
145
+
146
+ Returns:
147
+ Dict[str, Any]: total, offset and plans, or error with the API's words.
148
+ """
149
+ return _answer(lambda: _search_plans(self.base_url, self._seconds, api, query, sort, limit, offset))
150
+
151
+ def datacircle_provider(self, slug: str) -> Dict[str, Any]:
152
+ r"""Gives each API one provider sells and its rank on each on Datacircle's benchmark
153
+ (https://datacircle.dev), with its best plan there.
154
+
155
+ Args:
156
+ slug (str): The provider's slug, like 'bright-data', or its name, like 'Bright Data': the name is made
157
+ a slug.
158
+
159
+ Returns:
160
+ Dict[str, Any]: the provider, its website and apis, or error with the API's words.
161
+ """
162
+ return _answer(lambda: _provider(self.base_url, self._seconds, slug))
163
+
164
+ def get_tools(self) -> List[FunctionTool]:
165
+ r"""Returns the toolkit's four tools as FunctionTool, for ChatAgent(tools=...).
166
+
167
+ Returns:
168
+ List[FunctionTool]: datacircle_list_apis, datacircle_best_plans, datacircle_search_plans and
169
+ datacircle_provider.
170
+ """
171
+ tools = [
172
+ FunctionTool(self.datacircle_list_apis),
173
+ FunctionTool(self.datacircle_best_plans),
174
+ FunctionTool(self.datacircle_search_plans),
175
+ FunctionTool(self.datacircle_provider),
176
+ ]
177
+ # The docstrings' line breaks are no part of what the model reads.
178
+ for tool in tools:
179
+ function = tool.openai_tool_schema["function"]
180
+ function["description"] = " ".join(function["description"].split())
181
+ for field in function["parameters"]["properties"].values():
182
+ if "description" in field:
183
+ field["description"] = " ".join(field["description"].split())
184
+ return tools
@@ -0,0 +1,101 @@
1
+ """Offline tests: the toolkit against a local stand-in for the API on 127.0.0.1."""
2
+
3
+ import json
4
+ import threading
5
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
6
+ from urllib.parse import parse_qs, urlparse
7
+
8
+ import pytest
9
+
10
+ from camel_datacircle import DatacircleToolkit
11
+
12
+ PLAN = {"api": "Employee email", "rank": 1, "provider": "Hunter", "plan": "Starter", "score": 80.1, "perThousand": 4.9,
13
+ "page": "https://datacircle.dev/x", "terms": "long", "aggregators": ["a"]}
14
+ SEEN = []
15
+
16
+
17
+ class Handler(BaseHTTPRequestHandler):
18
+ def log_message(self, *args):
19
+ pass
20
+
21
+ def do_GET(self):
22
+ url = urlparse(self.path)
23
+ query = {key: values[0] for key, values in parse_qs(url.query).items()}
24
+ SEEN.append((url.path, query, self.headers.get("User-Agent")))
25
+ if url.path == "/v1/apis":
26
+ status, body = 200, [{"api": "Employee email", "slug": "email-finder", "plans": 9, "providers": 3, "extra": 1},
27
+ {"api": "Employee profile", "slug": "linkedin-profile", "plans": 4, "providers": 2}]
28
+ elif url.path == "/v1/apis/email-finder/best":
29
+ status, body = 200, {"api": "Employee email", "slug": "email-finder", "total": 1, "plans": [PLAN]}
30
+ elif url.path.startswith("/v1/apis/"):
31
+ status, body = 404, {"error": "no API has the slug nope", "slugs": ["email-finder", "linkedin-profile"]}
32
+ elif url.path == "/v1/plans" and query.get("query") == "refused":
33
+ status, body = 400, {"error": "query refused by the stand-in"}
34
+ elif url.path == "/v1/plans":
35
+ status, body = 200, {"total": 1, "offset": 0, "plans": [PLAN]}
36
+ elif url.path == "/v1/providers/bright-data":
37
+ status, body = 200, {"provider": "Bright Data", "slug": "bright-data", "website": "https://brightdata.com",
38
+ "apis": [{"api": "Employee email", "slug": "email-finder", "rank": 7, "sheetPage": "s",
39
+ "plans": [dict(PLAN, rank=9, plan="B"), dict(PLAN, rank=7, plan="A")]}]}
40
+ else:
41
+ status, body = 404, {"error": "no provider has this slug"}
42
+ data = json.dumps(body).encode()
43
+ self.send_response(status)
44
+ self.send_header("Content-Type", "application/json")
45
+ self.send_header("Content-Length", str(len(data)))
46
+ self.end_headers()
47
+ self.wfile.write(data)
48
+
49
+
50
+ @pytest.fixture(scope="module")
51
+ def toolkit():
52
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
53
+ threading.Thread(target=server.serve_forever, daemon=True).start()
54
+ yield DatacircleToolkit(timeout=10, base_url=f"http://127.0.0.1:{server.server_address[1]}/v1")
55
+ server.shutdown()
56
+
57
+
58
+ def test_tools_and_schemas(toolkit):
59
+ tools = {tool.get_function_name(): tool for tool in toolkit.get_tools()}
60
+ assert list(tools) == ["datacircle_list_apis", "datacircle_best_plans", "datacircle_search_plans", "datacircle_provider"]
61
+ search = tools["datacircle_search_plans"].get_openai_tool_schema()["function"]
62
+ assert search["parameters"]["properties"]["sort"]["anyOf"][0]["enum"] == ["score", "provider", "price"]
63
+ assert "\n" not in search["description"] and "https://datacircle.dev" in search["description"]
64
+ assert all(field.get("description") for tool in tools.values()
65
+ for field in tool.get_openai_tool_schema()["function"]["parameters"]["properties"].values())
66
+
67
+
68
+ def test_calls_sent_and_answers_cut(toolkit):
69
+ SEEN.clear()
70
+ tools = {tool.get_function_name(): tool for tool in toolkit.get_tools()}
71
+ apis = tools["datacircle_list_apis"](query="profile", limit=None)
72
+ assert apis == {"total": 1, "apis": [{"api": "Employee profile", "slug": "linkedin-profile", "plans": 4, "providers": 2}]}
73
+ best = tools["datacircle_best_plans"](slug="Email Finder", limit="3")
74
+ assert best["plans"] == [{key: PLAN[key] for key in ["api", "rank", "provider", "plan", "score", "perThousand", "page"]}]
75
+ plans = tools["datacircle_search_plans"](api="email-finder", query="hunter", sort="PRICE", limit=None, offset=None)
76
+ assert plans["total"] == 1
77
+ provider = tools["datacircle_provider"](slug="Bright Data")
78
+ assert provider["apis"][0]["best"]["plan"] == "A" and provider["apis"][0]["plans"] == 2
79
+ assert [path for path, _, _ in SEEN] == ["/v1/apis", "/v1/apis/email-finder/best", "/v1/plans", "/v1/providers/bright-data"]
80
+ assert SEEN[1][1] == {"limit": "3"}
81
+ assert SEEN[2][1] == {"api": "email-finder", "query": "hunter", "sort": "price"}
82
+ assert all(agent.startswith("camel-datacircle/") for _, _, agent in SEEN)
83
+
84
+
85
+ def test_refusals_reach_the_model(toolkit):
86
+ SEEN.clear()
87
+ unknown = toolkit.datacircle_best_plans("nope")
88
+ assert "no API has the slug nope" in unknown["error"] and "email-finder, linkedin-profile" in unknown["error"]
89
+ assert toolkit.datacircle_search_plans(query="refused") == {"error": "Datacircle's API answered 400: query refused by the stand-in"}
90
+ assert "50 or less" in toolkit.datacircle_search_plans(limit=51)["error"]
91
+ assert "no provider" in toolkit.datacircle_provider("nobody")["error"]
92
+ for refused in (toolkit.datacircle_best_plans("email-finder", limit=0), toolkit.datacircle_best_plans("email-finder", limit=2.5),
93
+ toolkit.datacircle_search_plans(sort="cheapest"), toolkit.datacircle_search_plans(offset=-1),
94
+ toolkit.datacircle_list_apis(limit="many"), toolkit.datacircle_best_plans(""), toolkit.datacircle_provider(" ")):
95
+ assert set(refused) == {"error"}
96
+ assert [path for path, _, _ in SEEN] == ["/v1/apis/nope/best", "/v1/plans", "/v1/providers/nobody"]
97
+
98
+
99
+ def test_api_out_of_reach_is_an_answer():
100
+ answer = DatacircleToolkit(timeout=2, base_url="http://127.0.0.1:9/v1").datacircle_list_apis()
101
+ assert answer["error"].startswith("Datacircle's API could not be reached")