datacircle / neuron-ai-toolkit
Find the best GTM APIs, in Neuron AI: a toolkit of four tools on Datacircle's open API, no key.
Requires
- php: ^8.1
- ext-json: *
- neuron-core/neuron-ai: ^4.1
Requires (Dev)
- phpunit/phpunit: ^10.5|^11.0|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Find the best GTM APIs. We benchmark all the GTM APIs and we put the results on our website.
This package gives Neuron AI a toolkit of four tools that call Datacircle's open 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 name or plan name. Search all APIs or one API. Sort the plans 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
composer require datacircle/neuron-ai-toolkit
The package needs PHP 8.1 or later and Neuron AI 4.1 or later.
Use the toolkit
Add DatacircleToolkit to your agent's tools():
<?php namespace App\Neuron; use Datacircle\NeuronAI\DatacircleToolkit; use NeuronAI\Agent\Agent; use NeuronAI\Providers\AIProviderInterface; use NeuronAI\Providers\Anthropic\Anthropic; class ApiAgent extends Agent { protected function provider(): AIProviderInterface { return new Anthropic( key: 'ANTHROPIC_API_KEY', model: 'claude-sonnet-5-5', ); } protected function tools(): array { return [ DatacircleToolkit::make(), ]; } }
Then ask the agent:
use NeuronAI\Chat\Messages\UserMessage; $response = ApiAgent::make()->setThreadId('demo')->chat( new UserMessage('Who is the best provider for the email-finder API?') )->getMessage(); echo $response->getContent();
The tools work the same with stream(). The toolkit also adds a few lines of guidelines to the agent's instructions: call datacircle_list_apis first to find a slug, and look up a provider by its name with datacircle_provider or datacircle_search_plans.
The four tool classes are in Datacircle\NeuronAI: ListApisTool, BestPlansTool, SearchPlansTool and ProviderTool. You can give the agent only some of the tools:
use Datacircle\NeuronAI\BestPlansTool; use Datacircle\NeuronAI\ProviderTool; DatacircleToolkit::make()->only([BestPlansTool::class, ProviderTool::class]);
You can also run a tool yourself:
$tool = BestPlansTool::make(); $tool->setInputs(['slug' => 'email-finder', 'limit' => 3]); $tool->execute(); echo $tool->getResult();
Each tool gives back 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. That page lists every field. When the API gives no data, the tool returns an error result (ToolOutput::error) with the API's own message, like {"error": "no API has the slug bright-data"}. A missing or wrong argument also returns an error result. The model reads the message and can call again. A network failure throws an exception. Set the agent's toolErrorHandler() to give the model that message instead.
The tools call the API with Neuron's own curl client. new Client(baseUrl: ..., timeout: ..., httpClient: ...) sets the API address, the timeout in seconds and the HTTP client, any NeuronAI\HttpClient\HttpClientInterface. The timeout is 30 seconds by default. Pass the client to DatacircleToolkit::make($client) or to each tool's constructor.
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: no key and nothing from your chats or config. The API takes up to 60 calls a minute from one IP address. The tool waits once, for a minute at most, when the API asks the tool to wait. The package depends on Neuron AI alone and stores nothing.
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.