omniai-datacircle 0.1.0
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.
- checksums.yaml +7 -0
- data/LICENSE.txt +21 -0
- data/README.md +71 -0
- data/lib/omniai/datacircle/calls.rb +146 -0
- data/lib/omniai/datacircle/client.rb +76 -0
- data/lib/omniai/datacircle/mcp_server.rb +42 -0
- data/lib/omniai/datacircle/tools.rb +124 -0
- data/lib/omniai/datacircle/version.rb +7 -0
- data/lib/omniai/datacircle.rb +43 -0
- metadata +74 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 7b766078e07b53f578a4b3df115ead887bd70abafa4e251fd8c13afbd9c8ce57
|
|
4
|
+
data.tar.gz: 0aa4b4ed088ca4742db95c9f75871be13777cc558d52931eac74d2fa66a60ca2
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: ea64613db0b8e2584799eb2bf915b2affb697dc64197ada67a69119dbb6c4a920f5742e2eacd0e05efbc5fba111f7a604affb963fbfa8ca33ba2b50288fc84ec
|
|
7
|
+
data.tar.gz: 513b7d2348fdd4eedbdfef0622c46daebe1d4879718d3acb78cce0ed9322e05af6c9c9e47d51b952fd40e060c68bca201122680eee4976c8651b5b4d3e465535
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Datacircle
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Datacircle tools for OmniAI
|
|
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 gem gives [OmniAI](https://github.com/ksylvest/omniai) four tools that call Datacircle's API at https://api.datacircle.dev/v1. You need no key and no account to call the API.
|
|
6
|
+
|
|
7
|
+
| Tool | What the tool gives | Call |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `datacircle_list_apis` | Every GTM API on Datacircle, with the API's slug, number of plans, number of providers and best plan | `GET /apis` |
|
|
10
|
+
| `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` |
|
|
11
|
+
| `datacircle_search_plans` | Plans that match a provider or plan name. Search all APIs or one API. Sort by score, provider or price | `GET /plans` |
|
|
12
|
+
| `datacircle_provider` | The APIs a provider sells, and the provider's rank on each API | `GET /providers/{slug}` |
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
bundle add omniai-datacircle
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The gem needs OmniAI 2.8.4 or later, and Ruby 3.2 or later. Add your provider's OmniAI gem too, like `omniai-openai`.
|
|
21
|
+
|
|
22
|
+
## Use the tools in a chat
|
|
23
|
+
|
|
24
|
+
```ruby
|
|
25
|
+
require "omniai/openai"
|
|
26
|
+
require "omniai/datacircle"
|
|
27
|
+
|
|
28
|
+
client = OmniAI::OpenAI::Client.new
|
|
29
|
+
response = client.chat("Which email finder API is best for under $5 per 1,000?", tools: OmniAI::Datacircle.tools)
|
|
30
|
+
puts response.text
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
OmniAI runs each tool call from the model. OmniAI then sends the tool's answer back to the model and returns the model's text. Every OmniAI provider works the same way, like `OmniAI::Anthropic::Client.new` or `OmniAI::Google::Client.new`. To offer fewer tools, pass a shorter list, like `tools: [OmniAI::Datacircle::BestPlans.new]`.
|
|
34
|
+
|
|
35
|
+
You can call a tool yourself:
|
|
36
|
+
|
|
37
|
+
```ruby
|
|
38
|
+
OmniAI::Datacircle::BestPlans.new.call({ "slug" => "email-finder", "limit" => 3 })
|
|
39
|
+
# => {"api" => "Employee email", "slug" => "email-finder", ..., "plans" => [{"api" => "Employee email", "rank" => 1, "provider" => "Emelia", ...}]}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Each tool returns a Hash. OmniAI sends the Hash to the model as JSON. Each plan comes with a rank, provider, plan, score, price per 1,000 (`perThousand`, in dollars) and a page on datacircle.dev. The plan's page lists every field of the plan. For an unknown slug or any other API error, the tool returns `{"error" => ...}` with the API's error message. The model reads the error and can call the tool again. A tool never raises an exception for an API error. Your chat keeps running.
|
|
43
|
+
|
|
44
|
+
OmniAI sends tools to OpenAI in strict mode, and strict mode requires every key. For OpenAI the gem marks the optional keys as nullable. The model then sends null for an unused key.
|
|
45
|
+
|
|
46
|
+
## Serve the tools to an MCP client
|
|
47
|
+
|
|
48
|
+
**mcp.rb**
|
|
49
|
+
|
|
50
|
+
```ruby
|
|
51
|
+
require "omniai/datacircle"
|
|
52
|
+
|
|
53
|
+
OmniAI::Datacircle.mcp_server.run
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`ruby mcp.rb` serves the four tools on stdio. Each tool answers in JSON text. Set your MCP client to start mcp.rb with the command `ruby` and the argument `/path/to/mcp.rb`.
|
|
57
|
+
|
|
58
|
+
The server is OmniAI's MCP server. We made three changes for MCP clients. The server sends no answer to a notification. A request with no params works. The server flushes each answer to stdout.
|
|
59
|
+
|
|
60
|
+
## Network
|
|
61
|
+
|
|
62
|
+
Each tool call makes one HTTPS GET request to https://api.datacircle.dev/v1. A tool makes a second request when the model sends a name in place of a slug. A tool also makes a second request when the model sends a provider in place of an API. A request holds the tool's own arguments and nothing else: no key and nothing from your config or messages. The API takes up to 60 calls a minute from one IP address. A tool waits once, for a minute at most, when the API replies with a wait. The gem depends only on OmniAI. The gem stores nothing.
|
|
63
|
+
|
|
64
|
+
## Links
|
|
65
|
+
|
|
66
|
+
- Datacircle: https://datacircle.dev
|
|
67
|
+
- The API: https://datacircle.dev/api
|
|
68
|
+
- The API's spec: https://api.datacircle.dev/v1/openapi.json
|
|
69
|
+
- The meaning of each key: https://datacircle.dev/fields
|
|
70
|
+
|
|
71
|
+
MIT license.
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module OmniAI
|
|
4
|
+
module Datacircle
|
|
5
|
+
# A plan holds about 90 keys (its terms of use, its aggregators...): these choose a plan, the rest is on its page.
|
|
6
|
+
PLAN_KEYS = %w[api rank provider plan score perThousand notFoundPerThousand billing pay currency units unit
|
|
7
|
+
strengths latencyMs page pricingPage docs].freeze
|
|
8
|
+
|
|
9
|
+
# Where a provider's plans are, for a model that sent a provider's name to an API's tool.
|
|
10
|
+
FOR_PROVIDER = "A provider's plans: datacircle_search_plans with its name as query, like bright data, " \
|
|
11
|
+
'or datacircle_provider.'
|
|
12
|
+
|
|
13
|
+
PRICE = "perThousand is a plan's price of 1,000 items in dollars, pay the plan's whole price in its currency."
|
|
14
|
+
|
|
15
|
+
# The four calls of https://api.datacircle.dev/v1 behind the tools, each answering a Hash. Each raises Error when the
|
|
16
|
+
# API gives no data: the tools answer it as {"error" => ...}.
|
|
17
|
+
class Calls
|
|
18
|
+
def initialize(base_url: Client::BASE)
|
|
19
|
+
@client = Client.new(base_url: base_url)
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
# GET /apis, the APIs whose name or slug holds the most of the query's words first.
|
|
23
|
+
def list_apis(query: nil, limit: nil)
|
|
24
|
+
apis = @client.get('/apis')
|
|
25
|
+
words = query.to_s.downcase.tr('-', ' ').split
|
|
26
|
+
held = apis.each_with_index.filter_map do |api, index|
|
|
27
|
+
name = "#{api['api']} #{api['slug'].to_s.tr('-', ' ')}".downcase
|
|
28
|
+
matched = words.count { |word| name.include?(word) }
|
|
29
|
+
[-matched, index, api] if matched.positive? || words.empty?
|
|
30
|
+
end.sort_by { |matched, index, _| [matched, index] }
|
|
31
|
+
note = nil
|
|
32
|
+
if words.any? && (held.empty? || -held.first.first < words.size)
|
|
33
|
+
# A provider's name sent as an API's, like Bright Data, or a question: where its plans are, and the sheet's
|
|
34
|
+
# order when no API holds a word of it.
|
|
35
|
+
note = "No API's name holds every word of #{query.to_s.strip.inspect}. #{FOR_PROVIDER}"
|
|
36
|
+
if held.empty?
|
|
37
|
+
held = apis.each_with_index.map { |api, index| [0, index, api] }
|
|
38
|
+
note += " These are the sheet's APIs in its order."
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
found = { 'total' => held.size,
|
|
42
|
+
'apis' => held.first(number(limit, 1, 200) || 20).map { |_, _, api| brief(api, %w[api slug plans providers best bestPage sheetPage]) } }
|
|
43
|
+
note ? { 'note' => note }.merge(found) : found
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# GET /apis/{slug}/best
|
|
47
|
+
def best_plans(slug: nil, limit: nil)
|
|
48
|
+
api = slugify(slug)
|
|
49
|
+
return { 'error' => "Give an API's slug, like email-finder: datacircle_list_apis gives every slug. #{FOR_PROVIDER}" } if api.empty?
|
|
50
|
+
|
|
51
|
+
begin
|
|
52
|
+
found = @client.get("/apis/#{api}/best", limit: number(limit, 1, 50))
|
|
53
|
+
rescue Error => e
|
|
54
|
+
raise unless e.status == 404
|
|
55
|
+
|
|
56
|
+
# An API's name sent as its slug, like Employee email: the API of that name.
|
|
57
|
+
named = @client.get('/apis').find { |entry| slugify(entry['api']) == api }
|
|
58
|
+
# A provider's name sent as the API's slug: the API's words, and where a provider's plans are.
|
|
59
|
+
return { 'error' => "#{e.message}. datacircle_list_apis gives every API's slug. #{FOR_PROVIDER}" } unless named
|
|
60
|
+
|
|
61
|
+
found = @client.get("/apis/#{named['slug']}/best", limit: number(limit, 1, 50))
|
|
62
|
+
end
|
|
63
|
+
found.merge('plans' => Array(found['plans']).map { |plan| brief(plan) })
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# GET /plans
|
|
67
|
+
def search_plans(query: nil, api: nil, sort: nil, limit: nil, offset: nil)
|
|
68
|
+
notes = []
|
|
69
|
+
begin
|
|
70
|
+
found = search(api, query, sort, limit, offset)
|
|
71
|
+
rescue Error => e
|
|
72
|
+
raise unless e.status == 400 && e.message.include?('api must be') && query.to_s.strip.empty?
|
|
73
|
+
|
|
74
|
+
# A provider's name sent as the API: the plans whose provider or plan name holds it.
|
|
75
|
+
api, query = nil, api
|
|
76
|
+
found = search(api, query, sort, limit, offset)
|
|
77
|
+
notes << "No API is named #{query.to_s.strip.inspect}: these are the plans whose provider or plan name holds it."
|
|
78
|
+
end
|
|
79
|
+
if found['total'].to_i.zero? && query.to_s.include?('-')
|
|
80
|
+
# A slug sent as a name, like bright-data, which no name holds: its words, like bright data. A name with a
|
|
81
|
+
# hyphen, like A-Leads, is found as it is first.
|
|
82
|
+
words = query.to_s.tr('-', ' ').split.join(' ')
|
|
83
|
+
found = search(api, words, sort, limit, offset)
|
|
84
|
+
notes << "No provider's or plan's name holds #{query.to_s.strip.inspect}: these are the plans whose name holds #{words.inspect}."
|
|
85
|
+
end
|
|
86
|
+
found = found.merge('plans' => Array(found['plans']).map { |plan| brief(plan) })
|
|
87
|
+
notes.empty? ? found : { 'note' => notes.join(' ') }.merge(found)
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
# GET /providers/{slug}
|
|
91
|
+
def provider(slug: nil)
|
|
92
|
+
name = slugify(slug)
|
|
93
|
+
return { 'error' => "Give a provider's slug or name, like bright-data or Bright Data" } if name.empty?
|
|
94
|
+
|
|
95
|
+
begin
|
|
96
|
+
found = @client.get("/providers/#{name}")
|
|
97
|
+
rescue Error => e
|
|
98
|
+
raise unless e.status == 404
|
|
99
|
+
|
|
100
|
+
return { 'error' => "#{e.message.split(':').first}. A provider's plans by its name: datacircle_search_plans with " \
|
|
101
|
+
'words of its name as query, like bright data.' }
|
|
102
|
+
end
|
|
103
|
+
apis = Array(found['apis']).map do |entry|
|
|
104
|
+
plans = Array(entry['plans'])
|
|
105
|
+
brief(entry, %w[api slug rank bestPage]).merge('plans' => plans.size, 'best' => best(plans)).compact
|
|
106
|
+
end
|
|
107
|
+
# Its best rank first, the APIs where it has none last, in the API's order.
|
|
108
|
+
apis = apis.each_with_index.sort_by { |entry, index| [entry['rank'].is_a?(Numeric) ? entry['rank'] : Float::INFINITY, index] }.map(&:first)
|
|
109
|
+
found.merge('apis' => apis, 'total' => apis.size, 'ranked' => apis.count { |entry| entry['rank'].is_a?(Numeric) })
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
private
|
|
113
|
+
|
|
114
|
+
def search(api, query, sort, limit, offset)
|
|
115
|
+
@client.get('/plans', api: api.to_s.strip, query: query.to_s.strip,
|
|
116
|
+
sort: (sort.to_s if %w[score provider price].include?(sort.to_s)),
|
|
117
|
+
limit: number(limit, 1, 50), offset: number(offset, 0, 1_000_000))
|
|
118
|
+
end
|
|
119
|
+
|
|
120
|
+
def brief(item, keys = PLAN_KEYS)
|
|
121
|
+
keys.each_with_object({}) { |key, kept| kept[key] = item[key] unless item[key].nil? }
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
# A number the model sent, within the API's range, or nil when it sent none.
|
|
125
|
+
def number(value, low, high)
|
|
126
|
+
return nil if value.nil? || value.to_s.strip.empty?
|
|
127
|
+
return value.to_i.clamp(low, high) if value.is_a?(Numeric)
|
|
128
|
+
|
|
129
|
+
Integer(value.to_s.strip, 10).clamp(low, high)
|
|
130
|
+
rescue ArgumentError
|
|
131
|
+
nil
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
# The API's rule for a slug: the name in lowercase letters and digits, the rest a hyphen.
|
|
135
|
+
def slugify(value)
|
|
136
|
+
value.to_s.strip.downcase.unicode_normalize(:nfkd).gsub(/\p{Mn}/, '').gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')
|
|
137
|
+
end
|
|
138
|
+
|
|
139
|
+
# A provider's best plan on an API: its lowest rank, else its first.
|
|
140
|
+
def best(plans)
|
|
141
|
+
top = plans.select { |plan| plan['rank'].is_a?(Numeric) }.min_by { |plan| plan['rank'] } || plans.first
|
|
142
|
+
top && brief(top, %w[plan score perThousand page])
|
|
143
|
+
end
|
|
144
|
+
end
|
|
145
|
+
end
|
|
146
|
+
end
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'json'
|
|
4
|
+
require 'net/http'
|
|
5
|
+
require 'uri'
|
|
6
|
+
|
|
7
|
+
module OmniAI
|
|
8
|
+
module Datacircle
|
|
9
|
+
# What Datacircle's API answered when it gave no data (its HTTP status in #status), or why it could not be reached.
|
|
10
|
+
class Error < StandardError
|
|
11
|
+
attr_reader :status
|
|
12
|
+
|
|
13
|
+
def initialize(message = nil, status: nil)
|
|
14
|
+
super(message)
|
|
15
|
+
@status = status
|
|
16
|
+
end
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# One HTTPS GET to Datacircle's open API, with no key: its answer as a Hash or an Array.
|
|
20
|
+
class Client
|
|
21
|
+
BASE = 'https://api.datacircle.dev/v1'
|
|
22
|
+
|
|
23
|
+
def initialize(base_url: BASE)
|
|
24
|
+
@base = base_url.to_s.chomp('/')
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
def get(path, params = {})
|
|
28
|
+
uri = URI("#{@base}#{path}")
|
|
29
|
+
query = params.reject { |_, value| value.nil? || value.to_s.strip.empty? }
|
|
30
|
+
uri.query = URI.encode_www_form(query) unless query.empty?
|
|
31
|
+
2.times do |attempt|
|
|
32
|
+
response = request(uri)
|
|
33
|
+
return parse(response) if response.is_a?(Net::HTTPSuccess)
|
|
34
|
+
|
|
35
|
+
if response.code == '429' && attempt.zero?
|
|
36
|
+
sleep(wait(response))
|
|
37
|
+
next
|
|
38
|
+
end
|
|
39
|
+
raise Error.new(words(response), status: response.code.to_i)
|
|
40
|
+
end
|
|
41
|
+
raise Error.new("Datacircle's API answered 429 twice: wait a minute and call again", status: 429)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
private
|
|
45
|
+
|
|
46
|
+
def request(uri)
|
|
47
|
+
Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 15, read_timeout: 30) do |http|
|
|
48
|
+
http.get(uri.request_uri, 'Accept' => 'application/json', 'User-Agent' => "omniai-datacircle/#{VERSION}")
|
|
49
|
+
end
|
|
50
|
+
rescue SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse => e
|
|
51
|
+
raise Error, "Datacircle's API could not be reached: #{e.message}"
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def parse(response)
|
|
55
|
+
JSON.parse(response.body.to_s)
|
|
56
|
+
rescue JSON::ParserError
|
|
57
|
+
raise Error.new("Datacircle's API answered #{response.code} with no JSON", status: response.code.to_i)
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
# The API asks to wait in Retry-After: its seconds, a minute at most.
|
|
61
|
+
def wait(response)
|
|
62
|
+
Integer(response['Retry-After'] || 30).clamp(1, 60)
|
|
63
|
+
rescue ArgumentError
|
|
64
|
+
30
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
# The API's own words: its error of a 4xx, else its status.
|
|
68
|
+
def words(response)
|
|
69
|
+
parsed = JSON.parse(response.body.to_s)
|
|
70
|
+
parsed.is_a?(Hash) && parsed['error'] ? parsed['error'].to_s : "Datacircle's API answered #{response.code}"
|
|
71
|
+
rescue JSON::ParserError
|
|
72
|
+
"Datacircle's API answered #{response.code}"
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
end
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module OmniAI
|
|
4
|
+
module Datacircle
|
|
5
|
+
# OmniAI's MCP server as MCP clients talk to it: a notification (notifications/initialized) gets no answer, a
|
|
6
|
+
# request with no params (tools/list, ping) is read as one with empty params, a method it does not serve gets
|
|
7
|
+
# JSON-RPC's error, and each answer leaves at once on stdio.
|
|
8
|
+
class MCPServer < OmniAI::MCP::Server
|
|
9
|
+
METHODS = %w[initialize ping tools/list tools/call].freeze
|
|
10
|
+
|
|
11
|
+
# Writes each answer through, as a client on a pipe waits for it.
|
|
12
|
+
class Stdio < OmniAI::MCP::Transport::Stdio
|
|
13
|
+
def puts(text)
|
|
14
|
+
super
|
|
15
|
+
@stdout.flush
|
|
16
|
+
end
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
def run(transport: Stdio.new)
|
|
20
|
+
super
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
def process(message)
|
|
24
|
+
data = JSON.parse(message)
|
|
25
|
+
return super unless data.is_a?(Hash)
|
|
26
|
+
return if data['id'].nil?
|
|
27
|
+
return unknown(data) unless METHODS.include?(data['method'])
|
|
28
|
+
|
|
29
|
+
super(JSON.generate(data.merge('params' => data['params'] || {})))
|
|
30
|
+
rescue JSON::ParserError
|
|
31
|
+
super
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
private
|
|
35
|
+
|
|
36
|
+
def unknown(data)
|
|
37
|
+
JSON.generate({ jsonrpc: '2.0', id: data['id'],
|
|
38
|
+
error: { code: -32_601, message: "method not found: #{data['method']}" } })
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
end
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module OmniAI
|
|
4
|
+
module Datacircle
|
|
5
|
+
# A tool of Datacircle's open API: its name is datacircle_ and its class's, like datacircle_best_plans.
|
|
6
|
+
class Tool < OmniAI::Tool
|
|
7
|
+
def self.namify
|
|
8
|
+
"datacircle_#{name.split('::').last.gsub(/(?<=[a-z])(?=[A-Z])/, '_').downcase}"
|
|
9
|
+
end
|
|
10
|
+
|
|
11
|
+
# text: true answers JSON text, as an MCP server sends it, in place of a Hash.
|
|
12
|
+
def initialize(text: false, **)
|
|
13
|
+
super(**)
|
|
14
|
+
@text = text
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
# The tool's answer to the model's arguments, as OmniAI's chat and MCP server call it: the call's Hash (its JSON
|
|
18
|
+
# with text: true), or the API's error as {"error" => ...}, never raised. Arguments it does not take are dropped,
|
|
19
|
+
# a number sent as text is read, one out of range is brought into it.
|
|
20
|
+
def call(args = {})
|
|
21
|
+
given = args.is_a?(Hash) ? args.to_h { |key, value| [key.to_s, value] } : {}
|
|
22
|
+
kept = self.class.parameters.properties.keys.each_with_object({}) do |key, kept|
|
|
23
|
+
kept[key.to_sym] = given[key.to_s] unless given[key.to_s].nil?
|
|
24
|
+
end
|
|
25
|
+
found = begin
|
|
26
|
+
@function.call(**kept)
|
|
27
|
+
rescue Error => e
|
|
28
|
+
{ 'error' => e.message }
|
|
29
|
+
end
|
|
30
|
+
@text ? JSON.generate(found) : found
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# The tool as the provider sends it. A strict tool (OmniAI's OpenAI provider sends strict: true) takes only an
|
|
34
|
+
# object whose every key is required: each key the tool can do without is sent as a null, which #call drops.
|
|
35
|
+
def serialize(context: nil)
|
|
36
|
+
serialized = super
|
|
37
|
+
strict = serialized[:strict] ? serialized : serialized[:function]
|
|
38
|
+
return serialized unless strict.is_a?(Hash) && strict[:strict] && strict[:parameters].is_a?(Hash)
|
|
39
|
+
|
|
40
|
+
strict[:parameters] = every_key_required(strict[:parameters])
|
|
41
|
+
serialized
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
private
|
|
45
|
+
|
|
46
|
+
def every_key_required(schema)
|
|
47
|
+
required = Array(schema[:required]).map(&:to_s)
|
|
48
|
+
properties = schema[:properties].to_h do |key, property|
|
|
49
|
+
next [key, property] if required.include?(key.to_s)
|
|
50
|
+
|
|
51
|
+
nullable = property.merge(type: ['null', *property[:type]].uniq)
|
|
52
|
+
nullable[:enum] = [*property[:enum], nil].uniq if property[:enum]
|
|
53
|
+
[key, nullable]
|
|
54
|
+
end
|
|
55
|
+
schema.merge(properties: properties, required: properties.keys)
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
def calls
|
|
59
|
+
Calls.new(base_url: Datacircle.base_url)
|
|
60
|
+
end
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
# GET /apis
|
|
64
|
+
class ListApis < Tool
|
|
65
|
+
description "Lists the GTM APIs on Datacircle's sheet (https://datacircle.dev), with each API's slug, how many plans " \
|
|
66
|
+
"and providers it has and its best plan. Call it first to find an API's slug."
|
|
67
|
+
parameter :query, :string, description: "Words of the API's name or slug, like email or linkedin profile: the APIs " \
|
|
68
|
+
"that hold the most of them come first. The sheet's order when left out."
|
|
69
|
+
parameter :limit, :integer, description: 'How many APIs to give, 1 to 200. 20 when left out: the sheet has about 150.'
|
|
70
|
+
|
|
71
|
+
def execute(query: nil, limit: nil)
|
|
72
|
+
calls.list_apis(query: query, limit: limit)
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# GET /apis/{slug}/best
|
|
77
|
+
class BestPlans < Tool
|
|
78
|
+
description "Gives an API's plans best first by their score out of 100 on Datacircle's benchmark " \
|
|
79
|
+
'(https://datacircle.dev), each with its rank, provider, plan, $ per 1,000 calls and its page. ' \
|
|
80
|
+
"#{PRICE}"
|
|
81
|
+
parameter :slug, :string, description: "The API's slug, like email-finder or linkedin-profile, as " \
|
|
82
|
+
'datacircle_list_apis gives it.'
|
|
83
|
+
parameter :limit, :integer, description: 'How many plans to give, 1 to 50. 10 when left out.'
|
|
84
|
+
required %i[slug]
|
|
85
|
+
|
|
86
|
+
def execute(slug: nil, limit: nil)
|
|
87
|
+
calls.best_plans(slug: slug, limit: limit)
|
|
88
|
+
end
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
# GET /plans
|
|
92
|
+
class SearchPlans < Tool
|
|
93
|
+
description "Searches every plan on Datacircle's sheet (https://datacircle.dev), or one API's, by provider or plan " \
|
|
94
|
+
'name, sorted by score, provider or price. Gives how many were found and up to limit of them. ' \
|
|
95
|
+
"#{PRICE}"
|
|
96
|
+
parameter :query, :string, description: "Words that must all appear in the provider's or plan's name, like bright data."
|
|
97
|
+
parameter :api, :string, description: "Only this API's plans: its name or slug, like email-finder. A provider's " \
|
|
98
|
+
'name goes in query, never here. Every API when left out.'
|
|
99
|
+
parameter :sort, :string, enum: %w[score provider price],
|
|
100
|
+
description: 'score (best first, the default), provider (A to Z) or price ($ per 1,000, ' \
|
|
101
|
+
'lowest first).'
|
|
102
|
+
parameter :limit, :integer, description: 'How many plans to give, 1 to 50. 10 when left out.'
|
|
103
|
+
parameter :offset, :integer, description: 'How many found plans to skip first. 0 when left out.'
|
|
104
|
+
|
|
105
|
+
def execute(query: nil, api: nil, sort: nil, limit: nil, offset: nil)
|
|
106
|
+
calls.search_plans(query: query, api: api, sort: sort, limit: limit, offset: offset)
|
|
107
|
+
end
|
|
108
|
+
end
|
|
109
|
+
|
|
110
|
+
# GET /providers/{slug}
|
|
111
|
+
class Provider < Tool
|
|
112
|
+
description "Gives each API one provider sells and its rank on each on Datacircle's benchmark " \
|
|
113
|
+
'(https://datacircle.dev), with its best plan there, its best rank first. total is how many APIs it ' \
|
|
114
|
+
'sells, ranked on how many of them it has a rank.'
|
|
115
|
+
parameter :slug, :string, description: "The provider's slug, like bright-data, or its name, like Bright Data: the " \
|
|
116
|
+
'name is made a slug.'
|
|
117
|
+
required %i[slug]
|
|
118
|
+
|
|
119
|
+
def execute(slug: nil)
|
|
120
|
+
calls.provider(slug: slug)
|
|
121
|
+
end
|
|
122
|
+
end
|
|
123
|
+
end
|
|
124
|
+
end
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'json'
|
|
4
|
+
require 'omniai'
|
|
5
|
+
require_relative 'datacircle/version'
|
|
6
|
+
require_relative 'datacircle/client'
|
|
7
|
+
require_relative 'datacircle/calls'
|
|
8
|
+
require_relative 'datacircle/tools'
|
|
9
|
+
require_relative 'datacircle/mcp_server'
|
|
10
|
+
|
|
11
|
+
module OmniAI
|
|
12
|
+
# Datacircle's open API as four OmniAI tools, with no key: find the best GTM APIs. We benchmark all the GTM APIs and
|
|
13
|
+
# we put the results on our website, https://datacircle.dev
|
|
14
|
+
#
|
|
15
|
+
# client.chat("Which email finder API is best?", tools: OmniAI::Datacircle.tools)
|
|
16
|
+
#
|
|
17
|
+
# datacircle_list_apis, datacircle_best_plans, datacircle_search_plans and datacircle_provider make one GET of
|
|
18
|
+
# https://api.datacircle.dev/v1 each. Each answers a Hash; the API's error, or why it could not be reached, is
|
|
19
|
+
# answered as {"error" => ...} for the model to read and call again, never raised.
|
|
20
|
+
module Datacircle
|
|
21
|
+
TOOLS = [ListApis, BestPlans, SearchPlans, Provider].freeze
|
|
22
|
+
|
|
23
|
+
class << self
|
|
24
|
+
# Where the tools call, https://api.datacircle.dev/v1 unless set.
|
|
25
|
+
attr_writer :base_url
|
|
26
|
+
|
|
27
|
+
def base_url
|
|
28
|
+
@base_url || Client::BASE
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
# The four tools, for client.chat(tools: ...). text: true answers JSON text in place of a Hash.
|
|
32
|
+
def tools(text: false)
|
|
33
|
+
TOOLS.map { |tool| tool.new(text: text) }
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# An OmniAI MCP server of the four tools, each answering JSON text: OmniAI::Datacircle.mcp_server.run serves
|
|
37
|
+
# them on stdio to an MCP client.
|
|
38
|
+
def mcp_server(**options)
|
|
39
|
+
MCPServer.new(tools: tools(text: true), name: 'datacircle', version: VERSION, **options)
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: omniai-datacircle
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Wayne Hamadi
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: omniai
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - ">="
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: 2.8.4
|
|
19
|
+
- - "<"
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: '4'
|
|
22
|
+
type: :runtime
|
|
23
|
+
prerelease: false
|
|
24
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
25
|
+
requirements:
|
|
26
|
+
- - ">="
|
|
27
|
+
- !ruby/object:Gem::Version
|
|
28
|
+
version: 2.8.4
|
|
29
|
+
- - "<"
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: '4'
|
|
32
|
+
description: 'Four OmniAI tools on Datacircle''s open API, with no key: list the GTM
|
|
33
|
+
APIs, the best plans of one API, a search of every plan and one provider''s ranks.
|
|
34
|
+
We benchmark all the GTM APIs and we put the results on our website: https://datacircle.dev'
|
|
35
|
+
email:
|
|
36
|
+
- wayne@datacircle.dev
|
|
37
|
+
executables: []
|
|
38
|
+
extensions: []
|
|
39
|
+
extra_rdoc_files: []
|
|
40
|
+
files:
|
|
41
|
+
- LICENSE.txt
|
|
42
|
+
- README.md
|
|
43
|
+
- lib/omniai/datacircle.rb
|
|
44
|
+
- lib/omniai/datacircle/calls.rb
|
|
45
|
+
- lib/omniai/datacircle/client.rb
|
|
46
|
+
- lib/omniai/datacircle/mcp_server.rb
|
|
47
|
+
- lib/omniai/datacircle/tools.rb
|
|
48
|
+
- lib/omniai/datacircle/version.rb
|
|
49
|
+
homepage: https://datacircle.dev
|
|
50
|
+
licenses:
|
|
51
|
+
- MIT
|
|
52
|
+
metadata:
|
|
53
|
+
homepage_uri: https://datacircle.dev
|
|
54
|
+
source_code_uri: https://github.com/waynehamadi/omniai-datacircle
|
|
55
|
+
documentation_uri: https://github.com/waynehamadi/omniai-datacircle#readme
|
|
56
|
+
bug_tracker_uri: https://github.com/waynehamadi/omniai-datacircle/issues
|
|
57
|
+
rdoc_options: []
|
|
58
|
+
require_paths:
|
|
59
|
+
- lib
|
|
60
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
61
|
+
requirements:
|
|
62
|
+
- - ">="
|
|
63
|
+
- !ruby/object:Gem::Version
|
|
64
|
+
version: 3.2.0
|
|
65
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
66
|
+
requirements:
|
|
67
|
+
- - ">="
|
|
68
|
+
- !ruby/object:Gem::Version
|
|
69
|
+
version: '0'
|
|
70
|
+
requirements: []
|
|
71
|
+
rubygems_version: 3.6.9
|
|
72
|
+
specification_version: 4
|
|
73
|
+
summary: Find the best GTM APIs, in OmniAI.
|
|
74
|
+
test_files: []
|