activeagent-datacircle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58475383e96566ee06ec3263822783aaaec305f3ba123c143666504e52f60657
+  data.tar.gz: b2822ff8c1197bc3c3c0e544dae7332a9c20e28677ec0ff534ec4fd37d5b5fb1
+SHA512:
+  metadata.gz: a31c2fce17cd6b1b87c7e4185bbc4f5a352a61577487ad53ae01396023cc22d6f64873e9f4e344a146e2403796ab7c65f766eda7a7f89d9d2c314a6a3afdd2c1
+  data.tar.gz: dd90cc8908e835392a9064344e90c2e83a7dc19e653bb304b4f101ea966fe1a8c51b497233cc23b6af523da9269347d2b73da46ca6cc4b255c274c1505a30c50

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,66 @@
+# Datacircle tools for Active Agent
+
+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 [Active Agent](https://github.com/activeagents/activeagent) agents 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 or plan name. Search all APIs or 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
+bundle add activeagent-datacircle
+```
+
+The gem needs Active Agent 1.9 or later and Ruby 3.1 or later.
+
+## Use the tools
+
+Include the module in an agent. Pass `datacircle_tools` to `prompt`. The agent answers each tool call with the method of the same name.
+
+```ruby
+class PlanAgent < ApplicationAgent
+  include ActiveAgent::Datacircle
+
+  def ask
+    prompt(message: params[:question], tools: datacircle_tools)
+  end
+end
+
+PlanAgent.with(question: "Which email finder API is best for under $5 per 1,000?").ask.generate_now
+```
+
+To give an action fewer tools, pass their names to `datacircle_tools`:
+
+```ruby
+prompt(message: params[:question], tools: datacircle_tools(:best_plans, :search_plans))
+```
+
+`ActiveAgent::Datacircle::TOOLS` holds the four tool definitions in Active Agent's common format.
+
+You can call a tool yourself:
+
+```ruby
+PlanAgent.new.datacircle_best_plans(slug: "email-finder", limit: 3)
+# => {"api" => "Employee email", "slug" => "email-finder", ..., "plans" => [{"api" => "Employee email", "rank" => 1, "provider" => "Emelia", ...}, ...]}
+```
+
+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. The tool gives `{"error" => ...}` with the API's words when the API has no data, for example for an unknown slug. The agent reads the error and can call the tool again. Module calls like `ActiveAgent::Datacircle.best_plans(slug: "email-finder")` raise `ActiveAgent::Datacircle::Error` when the API has no data.
+
+## Network
+
+Each tool call makes one HTTPS GET request to https://api.datacircle.dev/v1. A plan search makes a second request when the agent names a provider instead of an API. A request holds only the tool's own arguments: no key, no config, nothing from your prompts. 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 depends only on Active Agent 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/activeagent/datacircle/calls.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Datacircle
+    # A plan holds about 90 keys (its terms of use, its aggregators...): a tool gives 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
+
+    # The four calls, one HTTPS GET each: what a tool gives, or Datacircle::Error.
+    class << self
+      # GET /apis
+      def list_apis(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
+
+      # GET /apis/{slug}/best
+      def best_plans(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
+
+      # GET /plans
+      def search_plans(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: the plans whose provider or plan name holds it.
+        answer = search(nil, api, sort, limit, offset)
+        { 'note' => "No API is named #{api.to_s.inspect}: these are the plans whose provider or plan name holds it." }
+          .merge(answer, 'plans' => Array(answer['plans']).map { |plan| brief(plan) })
+      end
+
+      # GET /providers/{slug}
+      def provider(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
+
+      # A tool's answer: the call's, or the API's error as { 'error' => ... } for the agent to read.
+      def answer
+        yield
+      rescue Error => e
+        { 'error' => e.message }
+      end
+
+      private
+
+      def client
+        @client ||= Client.new
+      end
+
+      def search(api, query, sort, limit, offset)
+        client.get('/plans', api: api, query: query, sort: (sort.to_s if %w[score provider price].include?(sort.to_s)),
+                             limit: number(limit, 1, 50), offset: number(offset, 0, 1_000_000))
+      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 agent 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
+
+      # 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/activeagent/datacircle/client.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module ActiveAgent
+  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' => "activeagent-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/activeagent/datacircle/tools.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Datacircle
+    # The four tools in Active Agent's common format, for prompt(tools: ...): each one's name is the agent's method
+    # that answers it.
+    TOOLS = [
+      {
+        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: []
+        }
+      },
+      {
+        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']
+        }
+      },
+      {
+        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: []
+        }
+      },
+      {
+        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']
+        }
+      }
+    ].freeze
+  end
+end

data/lib/activeagent/datacircle/version.rb

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

data/lib/activeagent/datacircle.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'active_agent'
+require_relative 'datacircle/version'
+require_relative 'datacircle/client'
+require_relative 'datacircle/tools'
+require_relative 'datacircle/calls'
+
+module ActiveAgent
+  # Four Active Agent tools on Datacircle's open API (https://api.datacircle.dev/v1), with no key. An agent that
+  # includes this module answers them with its methods of the same names:
+  #
+  #   class PlanAgent < ApplicationAgent
+  #     include ActiveAgent::Datacircle
+  #
+  #     def ask(question:)
+  #       prompt(message: question, tools: datacircle_tools)
+  #     end
+  #   end
+  module Datacircle
+    # The tools' definitions, all four or those named (:best_plans or 'datacircle_best_plans'), for prompt(tools: ...).
+    def self.tools(*names)
+      wanted = names.flatten.map { |name| name.to_s.delete_prefix('datacircle_') }
+      unknown = wanted - TOOLS.map { |tool| tool[:name].delete_prefix('datacircle_') }
+      raise ArgumentError, "No Datacircle tool is named #{unknown.join(', ')}" if unknown.any?
+
+      TOOLS.select { |tool| wanted.empty? || wanted.include?(tool[:name].delete_prefix('datacircle_')) }.deep_dup
+    end
+
+    # GET /apis: every API on the sheet, those whose name holds query's words first.
+    def datacircle_list_apis(query: nil, limit: nil, **)
+      Datacircle.answer { Datacircle.list_apis(query: query, limit: limit) }
+    end
+
+    # GET /apis/{slug}/best: one API's plans, best first.
+    def datacircle_best_plans(slug: nil, limit: nil, **)
+      Datacircle.answer { Datacircle.best_plans(slug: slug, limit: limit) }
+    end
+
+    # GET /plans: the plans whose provider or plan name holds query, on every API or on one.
+    def datacircle_search_plans(api: nil, query: nil, sort: nil, limit: nil, offset: nil, **)
+      Datacircle.answer { Datacircle.search_plans(api: api, query: query, sort: sort, limit: limit, offset: offset) }
+    end
+
+    # GET /providers/{slug}: one provider's rank on each API it sells.
+    def datacircle_provider(slug: nil, **)
+      Datacircle.answer { Datacircle.provider(slug: slug) }
+    end
+
+    private
+
+    def datacircle_tools(*names)
+      Datacircle.tools(*names)
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: activeagent-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: activeagent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: 'Four Active Agent 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/activeagent/datacircle.rb
+- lib/activeagent/datacircle/calls.rb
+- lib/activeagent/datacircle/client.rb
+- lib/activeagent/datacircle/tools.rb
+- lib/activeagent/datacircle/version.rb
+homepage: https://datacircle.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://datacircle.dev
+  source_code_uri: https://github.com/waynehamadi/activeagent-datacircle
+  documentation_uri: https://github.com/waynehamadi/activeagent-datacircle#readme
+  bug_tracker_uri: https://github.com/waynehamadi/activeagent-datacircle/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+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 Active Agent.
+test_files: []