Metadata-Version: 2.5
Name: strands-datacircle
Version: 0.1.0
Summary: Strands Agents tools for the Datacircle API: find the best GTM APIs
Project-URL: Homepage, https://datacircle.dev
Project-URL: Documentation, https://api.datacircle.dev/v1/openapi.json
Project-URL: Repository, https://github.com/waynehamadi/strands-datacircle
License-Expression: MIT
License-File: LICENSE
Keywords: agents,api,api-pricing,b2b-data,datacircle,gtm,strands,strands-agents,tools
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: strands-agents>=1.30.0
Description-Content-Type: text/markdown

# strands-datacircle

Find the best GTM APIs. We benchmark all the GTM APIs and we put the results on our website.

Our website: https://datacircle.dev

This package gives [Strands Agents](https://github.com/strands-agents/harness-sdk) four tools that call Datacircle's public API, https://api.datacircle.dev/v1. You need no key and no account.

| Tool | What the tool gives | Call |
| --- | --- | --- |
| `datacircle_list_apis` | Every GTM API on Datacircle, with the API's slug, number of plans, number of providers and best plan | `GET /apis` |
| `datacircle_best_plans` | One API's plans, sorted by score out of 100, best first. Each plan comes with a rank and a price per 1,000 calls | `GET /apis/{slug}/best` |
| `datacircle_search_plans` | Plans that match a provider or plan name, on all APIs or on one API. You can sort them by score, provider or price | `GET /plans` |
| `datacircle_provider` | The APIs a provider sells, and the provider's rank on each API | `GET /providers/{slug}` |

## Install

```bash
pip install strands-datacircle
```

The package needs Strands Agents 1.30 or later and Python 3.10 or later.

## Use the tools in an agent

Give the tools to an agent:

```python
from strands import Agent
from strands_datacircle import datacircle_tools

agent = Agent(tools=datacircle_tools())
agent("Which email finder API is best for under $5 per 1,000?")
```

The agent runs on Strands' default model. To pick a model, pass `model=` to `Agent`. To use our tools next to your own, put them all in one list: `tools=[*datacircle_tools(), my_tool]`.

`Agent(tools=["strands_datacircle"])` loads the same four tools. A config file with `"tools": ["strands_datacircle"]` loads all four Datacircle tools too.

## Call a tool yourself

You can call each tool as a plain function. The function returns our API's answer as a dict:

```python
from strands_datacircle import datacircle_best_plans

print(datacircle_best_plans("email-finder", limit=3))
```

`agent.tool.datacircle_best_plans(slug="email-finder")` runs the tool just as an agent does.

## What the model reads

Each tool gives the model a JSON object. Each plan comes with a rank, provider, plan, score, price per 1,000 (`perThousand`, in dollars) and a page on datacircle.dev. The page on datacircle.dev lists every field.

You can give a provider's name in place of a slug. The tool turns `Bright Data` into `bright-data`.

An unknown slug raises `DatacircleError` with the API's message. For an unknown API slug, the message lists every valid slug. A number out of range also raises `DatacircleError`. The agent gives the error to the model. The model can then call the tool again.

## Network

Each tool call makes one HTTPS GET request to https://api.datacircle.dev/v1 and nothing else. The request holds only the tool's own arguments. The API takes up to 60 calls a minute from one IP address. When the API asks the tool to wait, the tool waits up to a minute. The tool waits once per call at most. All plans are in one file at https://datacircle.dev/datacircle.json.

## Links

- Datacircle: https://datacircle.dev
- The API: https://datacircle.dev/api
- The API's spec: https://api.datacircle.dev/v1/openapi.json
- What each key means: https://datacircle.dev/fields

MIT license.
