langchainrb_datacircle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f51b5257434ed1f0310396bd99c0588774ccb470e3bf8484058aa6a9abede67
+  data.tar.gz: 57136f9d3a9a6fa1a0d8ec54d1dfd51bcea50a3b4f1cacaedc194f7094c1dcf5
+SHA512:
+  metadata.gz: f4b26aa0cb32fe152cc1eb797fde70e112577e181c57f7f3a5c9641aa62a0629a578c9e60b8c5b29f2a6d0e12b7be03935f750da7de052d5f4d370e42de40bd0
+  data.tar.gz: 7b6b7194f874d970ee7d063cd8d7ecad80255245b91480d8837d63603456590d254ac03d06dafd3f1703762987bd5479bdd7d8e5bdce6c6c9c4ec802068ca3af

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,63 @@
+# Datacircle tool for Langchain.rb
+
+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 a [Langchain.rb](https://github.com/patterns-ai-core/langchainrb) assistant one tool, `Langchain::Tool::Datacircle`, that calls Datacircle's open API, https://api.datacircle.dev/v1. You need no key and no account.
+
+| Function | What the function 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 langchainrb_datacircle
+```
+
+The gem needs Langchain.rb 0.19.4 or a later 0.19 release, and Ruby 3.1 or later.
+
+## Use the tool
+
+Give the tool to an assistant:
+
+```ruby
+require "langchainrb_datacircle"
+
+llm = Langchain::LLM::OpenAI.new(api_key: ENV["OPENAI_API_KEY"])
+assistant = Langchain::Assistant.new(
+  llm: llm,
+  instructions: "You help people choose a GTM API.",
+  tools: [Langchain::Tool::Datacircle.new]
+)
+
+assistant.add_message_and_run!(content: "Which email finder API is best for under $5 per 1,000?")
+assistant.messages.last.content
+```
+
+Langchain.rb's OpenAI LLM needs the `ruby-openai` gem in your Gemfile. Other LLMs of Langchain.rb's assistant work the same way, for example `Langchain::LLM::Ollama`. With `Langchain::LLM::Anthropic`, create the assistant with `parallel_tool_calls: false`. Langchain.rb 0.19 runs only the first tool call when Claude makes several at once.
+
+You can call a function yourself:
+
+```ruby
+tool = Langchain::Tool::Datacircle.new
+tool.best_plans(slug: "email-finder", limit: 3).content
+# => "{\"api\":\"Employee email\",\"slug\":\"email-finder\",...,\"plans\":[{\"api\":\"Employee email\",\"rank\":1,\"provider\":\"Emelia\",...}]}"
+```
+
+Each function gives a `Langchain::ToolResponse` with JSON in its content. 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 has no data, for example for an unknown slug, the content is `{"error": ...}` with the API's words. The assistant reads the error and can call the function again.
+
+## Network
+
+Each function call makes one HTTPS GET request to https://api.datacircle.dev/v1. A plan search makes a second request when the model names a provider instead of an API. A request holds only the function's own arguments: no key, no config, nothing from your messages. 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 it to wait. The gem depends only on Langchain.rb 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/langchainrb_datacircle/client.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module LangchainrbDatacircle
+  # 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 initialize(base_url: BASE)
+      @base = base_url.to_s.chomp('/')
+    end
+
+    def get(path, params = {})
+      uri = URI("#{@base}#{path}")
+      query = params.reject { |_, value| value.nil? || value.to_s.strip.empty? }
+      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(words(response), status: response.code.to_i)
+      end
+      raise Error.new("Datacircle's API answered 429 twice: wait a minute and call again", status: 429)
+    end
+
+    private
+
+    def request(uri)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 15, read_timeout: 30) do |http|
+        http.get(uri.request_uri, 'Accept' => 'application/json', 'User-Agent' => "langchainrb_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 own words: its error of a 4xx, else its status.
+    def words(response)
+      parsed = JSON.parse(response.body.to_s)
+      parsed.is_a?(Hash) && parsed['error'] ? parsed['error'].to_s : "Datacircle's API answered #{response.code}"
+    rescue JSON::ParserError
+      "Datacircle's API answered #{response.code}"
+    end
+  end
+end

data/lib/langchainrb_datacircle/tool.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Langchain
+  module Tool
+    # Datacircle's open API as a tool of Langchain::Assistant, with no key: find the best GTM APIs. We benchmark all the
+    # GTM APIs and we put the results on our website, https://datacircle.dev
+    #
+    #   assistant = Langchain::Assistant.new(llm: llm, tools: [Langchain::Tool::Datacircle.new])
+    #
+    # Its four functions are shown to the model as datacircle__list_apis, datacircle__best_plans, datacircle__search_plans
+    # and datacircle__provider, one GET of https://api.datacircle.dev/v1 each. Each answers JSON; the API's error, or why
+    # it could not be reached, is answered as {"error": ...} for the model to read and call again.
+    class Datacircle
+      extend Langchain::ToolDefinition
+
+      # A plan holds about 90 keys (its terms of use, its aggregators...): these 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
+
+      # Where a provider's plans are, for a model that sent a provider's name to an API's function.
+      FOR_PROVIDER = "A provider's plans: datacircle__search_plans with its name as query, like bright data, " \
+                     'or datacircle__provider.'
+
+      # The name the functions' names start with: datacircle__list_apis and so on.
+      def self.tool_name
+        'datacircle'
+      end
+
+      define_function :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." do
+        property :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."
+        property :limit, type: 'integer', description: 'How many APIs to give, 1 to 200. 20 when left out: the sheet has about 150.'
+      end
+
+      define_function :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.' do
+        property :slug, type: 'string', required: true,
+                        description: "The API's slug, like email-finder or linkedin-profile, as datacircle__list_apis gives it."
+        property :limit, type: 'integer', description: 'How many plans to give, 1 to 50. 10 when left out.'
+      end
+
+      define_function :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." do
+        property :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.'
+        property :query, type: 'string', description: "Words that must all appear in the provider's or plan's name, like bright data."
+        property :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).'
+        property :limit, type: 'integer', description: 'How many plans to give, 1 to 50. 10 when left out.'
+        property :offset, type: 'integer', description: 'How many found plans to skip first. 0 when left out.'
+      end
+
+      define_function :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, its best rank first. total is how ' \
+                                   'many APIs it sells, ranked on how many of them it has a rank.' do
+        property :slug, type: 'string', required: true,
+                        description: "The provider's slug, like bright-data, or its name, like Bright Data: the name is made a slug."
+      end
+
+      # base_url: where the functions call, https://api.datacircle.dev/v1 when left out.
+      def initialize(base_url: LangchainrbDatacircle::Client::BASE)
+        @client = LangchainrbDatacircle::Client.new(base_url: base_url)
+      end
+
+      # GET /apis, the APIs whose name or slug holds the most of the query's words first.
+      def list_apis(query: nil, limit: nil, **_others)
+        answer do
+          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.sort_by { |matched, index, _| [matched, index] }
+          found = { 'total' => held.size,
+                    'apis' => held.first(number(limit, 1, 200) || 20).map { |_, _, api| brief(api, %w[api slug plans providers best bestPage sheetPage]) } }
+          if words.any? && (held.empty? || -held.first.first < words.size)
+            # A provider's name sent as an API's, like Bright Data, whose data matches many APIs: where its plans are.
+            found['note'] = "No API's name holds every word of #{query.to_s.strip.inspect}. #{FOR_PROVIDER}"
+          end
+          found
+        end
+      end
+
+      # GET /apis/{slug}/best
+      def best_plans(slug: nil, limit: nil, **_others)
+        api = slugify(slug)
+        return error("Give an API's slug, like email-finder: datacircle__list_apis gives every slug. #{FOR_PROVIDER}") if api.empty?
+
+        answer do
+          found = @client.get("/apis/#{api}/best", limit: number(limit, 1, 50))
+          found.merge('plans' => Array(found['plans']).map { |plan| brief(plan) })
+        rescue LangchainrbDatacircle::Error => e
+          raise unless e.status == 404
+
+          # A provider's name sent as the API's slug: the API's words, and where a provider's plans are.
+          { 'error' => "#{e.message}. datacircle__list_apis gives every API's slug. #{FOR_PROVIDER}" }
+        end
+      end
+
+      # GET /plans
+      def search_plans(api: nil, query: nil, sort: nil, limit: nil, offset: nil, **_others)
+        answer do
+          notes = []
+          begin
+            found = search(api, query, sort, limit, offset)
+          rescue LangchainrbDatacircle::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.
+            api, query = nil, api
+            found = search(api, query, sort, limit, offset)
+            notes << "No API is named #{query.to_s.strip.inspect}: these are the plans whose provider or plan name holds it."
+          end
+          if found['total'].to_i.zero? && query.to_s.include?('-')
+            # A slug sent as a name, like bright-data, which no name holds: its words, like bright data. A name with a
+            # hyphen, like A-Leads, is found as it is first.
+            words = query.to_s.tr('-', ' ').split.join(' ')
+            found = search(api, words, sort, limit, offset)
+            notes << "No provider's or plan's name holds #{query.to_s.strip.inspect}: these are the plans whose name holds #{words.inspect}."
+          end
+          found = found.merge('plans' => Array(found['plans']).map { |plan| brief(plan) })
+          notes.empty? ? found : { 'note' => notes.join(' ') }.merge(found)
+        end
+      end
+
+      # GET /providers/{slug}
+      def provider(slug: nil, **_others)
+        name = slugify(slug)
+        return error("Give a provider's slug or name, like bright-data or Bright Data") if name.empty?
+
+        answer do
+          found = @client.get("/providers/#{name}")
+          apis = Array(found['apis']).map do |entry|
+            plans = Array(entry['plans'])
+            brief(entry, %w[api slug rank bestPage]).merge('plans' => plans.size, 'best' => best(plans)).compact
+          end
+          # Its best rank first, the APIs where it has none last, in the API's order.
+          apis = apis.each_with_index.sort_by { |entry, index| [entry['rank'].is_a?(Numeric) ? entry['rank'] : Float::INFINITY, index] }.map(&:first)
+          found.merge('apis' => apis, 'total' => apis.size, 'ranked' => apis.count { |entry| entry['rank'].is_a?(Numeric) })
+        end
+      end
+
+      private
+
+      # A function's answer as Langchain::Assistant takes it: the call's JSON, or the API's error as {"error": ...}.
+      def answer
+        tool_response(content: JSON.generate(yield))
+      rescue LangchainrbDatacircle::Error => e
+        error(e.message)
+      end
+
+      def error(message)
+        tool_response(content: JSON.generate('error' => message))
+      end
+
+      def search(api, query, sort, limit, offset)
+        @client.get('/plans', api: api.to_s.strip, query: query.to_s.strip,
+                              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 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?
+        return value.to_i.clamp(low, high) if value.is_a?(Numeric)
+
+        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, else its first.
+      def best(plans)
+        top = plans.select { |plan| plan['rank'].is_a?(Numeric) }.min_by { |plan| plan['rank'] } || plans.first
+        top && brief(top, %w[plan score perThousand page])
+      end
+    end
+  end
+end

data/lib/langchainrb_datacircle/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LangchainrbDatacircle
+  VERSION = '0.1.0'
+end

data/lib/langchainrb_datacircle.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'langchain'
+require_relative 'langchainrb_datacircle/version'
+require_relative 'langchainrb_datacircle/client'
+require_relative 'langchainrb_datacircle/tool'

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: langchainrb_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: langchainrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.19.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.19.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+description: 'A Langchain.rb tool 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/langchainrb_datacircle.rb
+- lib/langchainrb_datacircle/client.rb
+- lib/langchainrb_datacircle/tool.rb
+- lib/langchainrb_datacircle/version.rb
+homepage: https://datacircle.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://datacircle.dev
+  source_code_uri: https://github.com/waynehamadi/langchainrb_datacircle
+  documentation_uri: https://github.com/waynehamadi/langchainrb_datacircle#readme
+  bug_tracker_uri: https://github.com/waynehamadi/langchainrb_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 Langchain.rb.
+test_files: []