ruby_llm-datacircle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4bfba388f78279248bbc165d86adca4e355af696236758d383fe6f1cd5535f9
+  data.tar.gz: e9228d52d62157f904af52980df41dd4f88bcc8a9a2f5b8a239c0d4dc320f2a0
+SHA512:
+  metadata.gz: 16a4fb27eac737385c868828fc300517af5113ba18825d89986efde76cc3432865cdf8155bce1663291b905eb7dfeff282fc996d893a1153c866e2eb6c072855
+  data.tar.gz: 82913369c82cda9cede723680a35af7480efddb41080703c8dbdd6c615858f21f6ebc7d98721510e234776fcee9696ca8a82173a1e887a2c82062e7cbf6f718f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Datacircle
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

data/README.md

@@ -0,0 +1,65 @@
+# Datacircle tools for RubyLLM
+
+Find the best GTM APIs. We benchmark all the GTM APIs and we put the results on our website: https://datacircle.dev
+
+This gem gives your [RubyLLM](https://github.com/crmne/ruby_llm) chats four tools on 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 or plan name, on all APIs or on one API. Sort 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
+gem install ruby_llm-datacircle
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem 'ruby_llm-datacircle'
+```
+
+It needs RubyLLM 2.2 or later and Ruby 3.2 or later.
+
+## Use the tools
+
+```ruby
+require 'ruby_llm/datacircle'
+
+chat = RubyLLM.chat.with_tools(*RubyLLM::Datacircle.tools)
+chat.ask 'Which email finder API is best for under $5 per 1,000?'
+```
+
+Each tool is a class: `RubyLLM::Datacircle::ListApis`, `BestPlans`, `SearchPlans` and `Provider`. Give an agent only the ones it needs:
+
+```ruby
+class PlanFinder < RubyLLM::Agent
+  tools RubyLLM::Datacircle::BestPlans, RubyLLM::Datacircle::SearchPlans
+end
+```
+
+You can also call a tool yourself:
+
+```ruby
+RubyLLM::Datacircle::BestPlans.new.call(slug: 'email-finder', limit: 3)
+# => {"api" => "Employee email", "slug" => "email-finder", ..., "plans" => [{"api" => "Employee email", "rank" => 1, "provider" => "Emelia", ...}, ...]}
+```
+
+Each plan comes with its rank, provider, plan, score, price per 1,000 (`perThousand`, in dollars) and its page on datacircle.dev. That page lists every field. When the API gives no data, like for a slug it doesn't know, a chat gets the API's error as the tool's result. A call of your own raises `RubyLLM::Datacircle::Error`.
+
+## 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, no config, nothing from your chats. 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 gem has no dependency but RubyLLM 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.

data/lib/ruby_llm/datacircle/client.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module RubyLLM
+  module Datacircle
+    # What Datacircle's API answered when it gave no data (its HTTP status in #status), or why it could not be reached.
+    class Error < StandardError
+      attr_reader :status
+
+      def initialize(message = nil, status: nil)
+        super(message)
+        @status = status
+      end
+    end
+
+    # One HTTPS GET to Datacircle's open API, with no key: its answer as a Hash or an Array.
+    class Client
+      BASE = 'https://api.datacircle.dev/v1'
+
+      def get(path, params = {})
+        uri = URI("#{BASE}#{path}")
+        query = params.reject { |_, value| value.nil? || value == '' }
+        uri.query = URI.encode_www_form(query) unless query.empty?
+        2.times do |attempt|
+          response = request(uri)
+          return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
+
+          if response.code == '429' && attempt.zero?
+            sleep(wait(response))
+            next
+          end
+          raise Error.new("Datacircle's API answered #{response.code}: #{words(response.body)}", status: response.code.to_i)
+        end
+        raise Error, "Datacircle's API answered 429 twice: wait a minute and call again"
+      end
+
+      private
+
+      def request(uri)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 15, read_timeout: 30) do |http|
+          http.get(uri.request_uri, 'Accept' => 'application/json', 'User-Agent' => "ruby_llm-datacircle/#{VERSION}")
+        end
+      rescue SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse => e
+        raise Error, "Datacircle's API could not be reached: #{e.message}"
+      end
+
+      # The API asks to wait in Retry-After: its seconds, a minute at most.
+      def wait(response)
+        Integer(response['Retry-After'] || 30).clamp(1, 60)
+      rescue ArgumentError
+        30
+      end
+
+      # The API's error, with the slugs it knows when it gives them.
+      def words(body)
+        parsed = JSON.parse(body)
+        return body[0, 3000] unless parsed.is_a?(Hash) && parsed['error']
+        return parsed['error'] unless parsed['slugs']
+
+        "#{parsed['error']}; the slugs: #{Array(parsed['slugs']).join(', ')}"[0, 3000]
+      rescue JSON::ParserError
+        body.to_s[0, 3000]
+      end
+    end
+  end
+end

data/lib/ruby_llm/datacircle/tools.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Datacircle
+    # What the four tools share: the client, the keys of a plan the model gets, and the API's errors given back as a result.
+    class Base < RubyLLM::Tool
+      # A plan holds about 90 keys (its terms of use, its aggregators...): the model gets the ones that choose a plan,
+      # the rest is on its page.
+      PLAN_KEYS = %w[api rank provider plan score perThousand notFoundPerThousand billing pay currency units unit
+                     strengths latencyMs page pricingPage docs].freeze
+
+      rescue_from(Error) { |error| { error: error.message } }
+
+      private
+
+      def client
+        @client ||= Client.new
+      end
+
+      def brief(item, keys = PLAN_KEYS)
+        keys.each_with_object({}) { |key, kept| kept[key] = item[key] unless item[key].nil? }
+      end
+
+      # A number the model sent, within the API's range, or nil when it sent none.
+      def number(value, low, high)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        Integer(value.to_s.strip, 10).clamp(low, high)
+      rescue ArgumentError
+        nil
+      end
+
+      # The API's rule for a slug: the name in lowercase letters and digits, the rest a hyphen.
+      def slugify(value)
+        value.to_s.strip.downcase.unicode_normalize(:nfkd).gsub(/\p{Mn}/, '').gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')
+      end
+    end
+
+    # GET /apis
+    class ListApis < Base
+      def self.tool_name = 'datacircle_list_apis'
+
+      description "Lists the GTM APIs on Datacircle's sheet (https://datacircle.dev), with each API's slug, " \
+                  "how many plans and providers it has and its best plan. Call it first to find an API's slug."
+      parameters(
+        type: 'object',
+        properties: {
+          query: { type: 'string',
+                   description: "Words of the API's name or slug, like 'email' or 'linkedin profile': the APIs " \
+                                "that hold the most of them come first. The sheet's order when left out." },
+          limit: { type: 'integer', minimum: 1, maximum: 200,
+                   description: 'How many APIs to give, 1 to 200. 20 when left out: the sheet has about 150.' }
+        },
+        required: []
+      )
+
+      def execute(query: nil, limit: nil)
+        words = query.to_s.downcase.tr('-', ' ').split
+        held = client.get('/apis').each_with_index.filter_map do |api, index|
+          name = "#{api['api']} #{api['slug'].to_s.tr('-', ' ')}".downcase
+          matched = words.count { |word| name.include?(word) }
+          [-matched, index, api] if matched.positive? || words.empty?
+        end
+        found = held.sort_by { |matched, index, _| [matched, index] }
+                    .map { |_, _, api| brief(api, %w[api slug plans providers best bestPage sheetPage]) }
+        { total: found.size, apis: found.first(number(limit, 1, 200) || 20) }
+      end
+    end
+
+    # GET /apis/{slug}/best
+    class BestPlans < Base
+      def self.tool_name = 'datacircle_best_plans'
+
+      description "Gives an API's plans best first by their score out of 100 on Datacircle's benchmark " \
+                  '(https://datacircle.dev), each with its rank, provider, plan, $ per 1,000 calls and its page. ' \
+                  "perThousand is a plan's price of 1,000 items in dollars, pay the plan's whole price in its currency."
+      parameters(
+        type: 'object',
+        properties: {
+          slug: { type: 'string',
+                  description: "The API's slug, like 'email-finder' or 'linkedin-profile', as datacircle_list_apis gives it." },
+          limit: { type: 'integer', minimum: 1, maximum: 50, description: 'How many plans to give, 1 to 50. 10 when left out.' }
+        },
+        required: ['slug']
+      )
+
+      def execute(slug:, limit: nil)
+        api = slugify(slug)
+        raise Error, "Give an API's slug, like 'email-finder': datacircle_list_apis gives every slug" if api.empty?
+
+        answer = client.get("/apis/#{api}/best", limit: number(limit, 1, 50))
+        answer.merge('plans' => Array(answer['plans']).map { |plan| brief(plan) })
+      end
+    end
+
+    # GET /plans
+    class SearchPlans < Base
+      def self.tool_name = 'datacircle_search_plans'
+
+      description "Searches every plan on Datacircle's sheet (https://datacircle.dev), or one API's, by provider or plan " \
+                  'name, sorted by score, provider or price. Gives how many were found and up to limit of them. ' \
+                  "perThousand is a plan's price of 1,000 items in dollars, pay the plan's whole price in its currency."
+      parameters(
+        type: 'object',
+        properties: {
+          api: { type: 'string',
+                 description: "Only this API's plans: its name or slug, like 'email-finder'. A provider's name goes in " \
+                              'query, never here. Every API when left out.' },
+          query: { type: 'string', description: "Words that must all appear in the provider's or plan's name, like 'bright data'." },
+          sort: { type: 'string', enum: %w[score provider price],
+                  description: 'score (best first, the default), provider (A to Z) or price ($ per 1,000, lowest first).' },
+          limit: { type: 'integer', minimum: 1, maximum: 50, description: 'How many plans to give, 1 to 50. 10 when left out.' },
+          offset: { type: 'integer', minimum: 0, description: 'How many found plans to skip first. 0 when left out.' }
+        },
+        required: []
+      )
+
+      def execute(api: nil, query: nil, sort: nil, limit: nil, offset: nil)
+        answer = search(api, query, sort, limit, offset)
+        answer.merge('plans' => Array(answer['plans']).map { |plan| brief(plan) })
+      rescue Error => e
+        raise unless e.status == 400 && e.message.include?('api must be') && query.to_s.strip.empty?
+
+        # A provider's name sent as the API, as models do: the plans whose provider or plan name holds it.
+        answer = search(nil, api, sort, limit, offset)
+        { 'note' => "No API is named #{api.inspect}: these are the plans whose provider or plan name holds it." }
+          .merge(answer, 'plans' => Array(answer['plans']).map { |plan| brief(plan) })
+      end
+
+      private
+
+      def search(api, query, sort, limit, offset)
+        client.get('/plans', api: api, query: query, sort: (sort if %w[score provider price].include?(sort)),
+                             limit: number(limit, 1, 50), offset: number(offset, 0, 1_000_000))
+      end
+    end
+
+    # GET /providers/{slug}
+    class Provider < Base
+      def self.tool_name = 'datacircle_provider'
+
+      description "Gives each API one provider sells and its rank on each on Datacircle's benchmark " \
+                  '(https://datacircle.dev), with its best plan there.'
+      parameters(
+        type: 'object',
+        properties: {
+          slug: { type: 'string',
+                  description: "The provider's slug, like 'bright-data', or its name, like 'Bright Data': the name is made a slug." }
+        },
+        required: ['slug']
+      )
+
+      def execute(slug:)
+        provider = slugify(slug)
+        raise Error, "Give a provider's slug or name, like 'bright-data' or 'Bright Data'" if provider.empty?
+
+        answer = client.get("/providers/#{provider}")
+        apis = Array(answer['apis']).map do |entry|
+          plans = Array(entry['plans'])
+          brief(entry, %w[api slug rank bestPage]).merge('plans' => plans.size, 'best' => best(plans))
+        end
+        answer.merge('apis' => apis)
+      end
+
+      private
+
+      # A provider's best plan on an API: its lowest rank, a plan with no score having none.
+      def best(plans)
+        top = plans.min_by { |plan| plan['rank'].is_a?(Numeric) ? plan['rank'] : Float::INFINITY }
+        top && brief(top, %w[plan score perThousand page])
+      end
+    end
+  end
+end

data/lib/ruby_llm/datacircle/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Datacircle
+    VERSION = '0.1.0'
+  end
+end

data/lib/ruby_llm/datacircle.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require_relative 'datacircle/version'
+require_relative 'datacircle/client'
+require_relative 'datacircle/tools'
+
+module RubyLLM
+  # Four RubyLLM tools on Datacircle's open API (https://api.datacircle.dev/v1), with no key.
+  module Datacircle
+    # The four tools, for chat.with_tools(*RubyLLM::Datacircle.tools).
+    def self.tools
+      [ListApis, BestPlans, SearchPlans, Provider]
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-datacircle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Wayne Hamadi
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: 'Four RubyLLM tools on Datacircle''s open API, with no key: list the
+  GTM APIs, the best plans of one API, a search of every plan and one provider''s
+  ranks. We benchmark all the GTM APIs and we put the results on our website: https://datacircle.dev'
+email:
+- wayne@datacircle.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/ruby_llm/datacircle.rb
+- lib/ruby_llm/datacircle/client.rb
+- lib/ruby_llm/datacircle/tools.rb
+- lib/ruby_llm/datacircle/version.rb
+homepage: https://datacircle.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://datacircle.dev
+  source_code_uri: https://github.com/waynehamadi/ruby_llm-datacircle
+  documentation_uri: https://github.com/waynehamadi/ruby_llm-datacircle#readme
+  bug_tracker_uri: https://github.com/waynehamadi/ruby_llm-datacircle/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Find the best GTM APIs, in RubyLLM.
+test_files: []