demografix 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68a9654603c29db7c24af02f7daf2716a3159060dd596a11b300b83abe093d17
+  data.tar.gz: 42f4a7f8d7c1cef1ebbfdc0990660d7a96b67fc5861744bb017880553e4ac080
+SHA512:
+  metadata.gz: 0c71e2fe5ea63acff9cc98c82061bf727bff9b4795252a31718698002cfa81fdc5628594a9efcf6af2fb8aa837e5c766ae7803fb2448c432006518536f68848c
+  data.tar.gz: 26415804ba554e64613ee930464a07a04c5e389b728582d39b7b2dda8de73496911b4f500f30f35c2a69030c56fbc8c227559312eb8abf8588ca2363c3dd5079

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Demografix
+
+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,195 @@
+# demografix (Ruby)
+
+Run demographic analysis over names — predicted gender, age, and nationality — from one Ruby client. The
+gem covers genderize.io, agify.io, and nationalize.io.
+
+## Install
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "demografix"
+```
+
+Then run `bundle install`. To install directly:
+
+```sh
+gem install demografix
+```
+
+The client uses the Ruby standard library (`net/http` and `json`) and has no runtime dependencies. It requires Ruby 3.2 or later.
+
+## Authentication
+
+An API key is required. Creating one is free and includes 2,500 requests per month. Generate a key in your
+dashboard at genderize.io, agify.io, or nationalize.io. One key works across all three services.
+
+## Quickstart
+
+Construct a client, run a batch over a list of names, read the predictions, and read the remaining quota.
+
+```ruby
+require "demografix"
+
+client = Demografix::Client.new(api_key: ENV.fetch("DEMOGRAFIX_API_KEY"))
+
+names = %w[michael matthew jane emily peter lois]
+
+ages = client.agify_batch(names)
+
+# Aggregate the predictions into an age distribution for the list.
+known = ages.results.map(&:age).compact
+average_age = known.sum.to_f / known.length
+
+ages.quota.remaining # => 24987
+```
+
+Each call returns prediction fields plus a `quota`. Batch calls return `results` (one prediction per input
+name, in input order) plus one `quota` for the response. Aggregate the results into a distribution.
+
+## genderize
+
+Predict gender from a name.
+
+```ruby
+result = client.genderize("peter")
+result.gender      # => "male"
+result.probability # => 1.0
+result.count       # => 1352696
+```
+
+Batch a list and reduce it to a gender split:
+
+```ruby
+batch = client.genderize_batch(%w[peter lois meg chris])
+split = batch.results.each_with_object(Hash.new(0)) do |pred, counts|
+  counts[pred.gender || "unknown"] += 1
+end
+# => { "male" => 2, "female" => 2 }
+```
+
+`gender` is `"male"`, `"female"`, or `nil`. A name with no match returns `nil` gender, `0.0` probability,
+and `0` count. That is a successful response, not an error.
+
+## agify
+
+Predict age from a name.
+
+```ruby
+result = client.agify("michael")
+result.age   # => 57
+result.count # => 311558
+```
+
+Batch a list and reduce it to an age distribution:
+
+```ruby
+batch = client.agify_batch(%w[michael matthew jane])
+ages = batch.results.map(&:age).compact
+buckets = ages.group_by { |age| (age / 10) * 10 }
+# => { 50 => [57], 40 => [48], ... }
+```
+
+`age` is an integer or `nil`. A name with no match returns `nil` age and `0` count.
+
+## nationalize
+
+Predict nationality from a name.
+
+```ruby
+result = client.nationalize("nguyen")
+result.country.first.country_id   # => "VN"
+result.country.first.probability  # => 0.891132
+```
+
+Batch a list and reduce it to a nationality mix:
+
+```ruby
+batch = client.nationalize_batch(%w[nguyen schmidt rossi])
+mix = batch.results.each_with_object(Hash.new(0)) do |pred, counts|
+  top = pred.country.first
+  counts[top ? top.country_id : "unknown"] += 1
+end
+# => { "VN" => 1, "DE" => 1, "IT" => 1 }
+```
+
+`country` holds up to five candidates in descending probability order. A name with no match returns an empty
+`country` array.
+
+## country_id
+
+`genderize` and `agify` accept an optional `country_id` (ISO 3166-1 alpha-2) to scope the prediction to a
+country. `nationalize` does not accept it.
+
+```ruby
+result = client.genderize("kim", country_id: "US")
+result.country_id # => "US"
+result.gender     # => "female"
+
+client.agify_batch(%w[andrea andrea], country_id: "IT")
+```
+
+The value is echoed back uppercase in `country_id` on each prediction. When the request sends no
+`country_id`, the field is `nil`.
+
+## Quota
+
+Every result and every raised error carries a `quota` read from the response rate-limit headers:
+
+| Field | Meaning |
+|---|---|
+| `limit` | names allowed in the current window |
+| `remaining` | names left in the current window |
+| `reset` | seconds until the window resets |
+
+```ruby
+result = client.genderize("peter")
+result.quota.limit     # => 25000
+result.quota.remaining # => 24987
+result.quota.reset     # => 1314000
+```
+
+Read quota off the returned value or a raised error. The client does not cache it.
+
+## Errors
+
+Every error subclasses `Demografix::Error` and carries `status`, `message`, and `quota` (when the response
+included rate-limit headers).
+
+| Error | Raised on |
+|---|---|
+| `Demografix::AuthError` | 401, invalid or missing API key |
+| `Demografix::SubscriptionError` | 402, subscription not active |
+| `Demografix::ValidationError` | 422, invalid parameters; also client-side for a batch over 10 names |
+| `Demografix::RateLimitError` | 429, request limit reached (quota always populated) |
+| `Demografix::TransportError` | network failure, timeout, or non-JSON body |
+| `Demografix::Error` | any other non-2xx status |
+
+A batch of more than 10 names raises `ValidationError` before any HTTP call is made.
+
+On a `RateLimitError`, read `quota.reset` for the seconds to wait before retrying:
+
+```ruby
+begin
+  client.genderize_batch(names)
+rescue Demografix::RateLimitError => e
+  sleep(e.quota.reset)
+  retry
+end
+```
+
+## Methods
+
+| Method | Returns | country_id |
+|---|---|---|
+| `genderize(name, country_id:)` | `GenderizeResult` | yes |
+| `genderize_batch(names, country_id:)` | `Batch` of `GenderizePrediction` | yes |
+| `agify(name, country_id:)` | `AgifyResult` | yes |
+| `agify_batch(names, country_id:)` | `Batch` of `AgifyPrediction` | yes |
+| `nationalize(name)` | `NationalizeResult` | no |
+| `nationalize_batch(names)` | `Batch` of `NationalizePrediction` | no |
+
+`Demografix::Client.new` requires `api_key:` and accepts `timeout:` (optional, default 10 seconds). The
+host URLs and the User-Agent are fixed constants, not options.
+
+Full API reference: https://genderize.io/documentation/api

data/lib/demografix/client.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Demografix
+  # Synchronous client for the three Demografix APIs: genderize, agify, and
+  # nationalize. One instance covers all three services. Quota is read from
+  # the returned value or a raised error, never cached on the client.
+  class Client
+    # Per-service hosts. Hardcoded constants, not options.
+    HOSTS = {
+      genderize: "https://api.genderize.io",
+      agify: "https://api.agify.io",
+      nationalize: "https://api.nationalize.io"
+    }.freeze
+
+    USER_AGENT = "demografix-ruby/#{VERSION}"
+
+    MAX_BATCH = 10
+    DEFAULT_TIMEOUT = 10
+
+    # @param api_key [String] required. The same key works across all three
+    #   services. A missing or blank key raises ValidationError before any
+    #   request is made.
+    # @param timeout [Numeric] request timeout in seconds.
+    def initialize(api_key:, timeout: DEFAULT_TIMEOUT)
+      key = api_key.to_s
+      raise ValidationError.new("api_key is required", status: 422) if key.strip.empty?
+
+      @api_key = key
+      @timeout = timeout
+    end
+
+    # --- genderize ---------------------------------------------------------
+
+    def genderize(name, country_id: nil)
+      body, quota = request(:genderize, [name], country_id: country_id, batch: false)
+      pred = parse_genderize(single(body))
+      GenderizeResult.new(**pred.to_h, quota: quota)
+    end
+
+    def genderize_batch(names, country_id: nil)
+      body, quota = request(:genderize, validate_batch(names), country_id: country_id, batch: true)
+      Batch.new(results: array(body).map { |o| parse_genderize(o) }, quota: quota)
+    end
+
+    # --- agify -------------------------------------------------------------
+
+    def agify(name, country_id: nil)
+      body, quota = request(:agify, [name], country_id: country_id, batch: false)
+      pred = parse_agify(single(body))
+      AgifyResult.new(**pred.to_h, quota: quota)
+    end
+
+    def agify_batch(names, country_id: nil)
+      body, quota = request(:agify, validate_batch(names), country_id: country_id, batch: true)
+      Batch.new(results: array(body).map { |o| parse_agify(o) }, quota: quota)
+    end
+
+    # --- nationalize -------------------------------------------------------
+
+    def nationalize(name)
+      body, quota = request(:nationalize, [name], batch: false)
+      pred = parse_nationalize(single(body))
+      NationalizeResult.new(**pred.to_h, quota: quota)
+    end
+
+    def nationalize_batch(names)
+      body, quota = request(:nationalize, validate_batch(names), batch: true)
+      Batch.new(results: array(body).map { |o| parse_nationalize(o) }, quota: quota)
+    end
+
+    private
+
+    # Validate the batch size client-side before any HTTP call.
+    def validate_batch(names)
+      list = Array(names)
+      if list.length > MAX_BATCH
+        raise ValidationError.new(
+          "A batch may contain at most #{MAX_BATCH} names, got #{list.length}.",
+          status: 422
+        )
+      end
+      list
+    end
+
+    # Build and send the request, returning [parsed_body, quota].
+    def request(service, names, country_id: nil, batch:)
+      uri = URI(HOSTS.fetch(service))
+      uri.query = build_query(names, country_id: country_id, batch: batch)
+      send_request(uri)
+    end
+
+    # Build the query string: name=<v> for a single call, repeated name[]=<v>
+    # for a batch. apikey is always sent; country_id is added only when set.
+    def build_query(names, country_id:, batch:)
+      params = []
+      if batch
+        names.each { |n| params << ["name[]", n.to_s] }
+      else
+        params << ["name", names.first.to_s]
+      end
+      params << ["country_id", country_id.to_s] if country_id
+      params << ["apikey", @api_key]
+      URI.encode_www_form(params)
+    end
+
+    # The internal transport seam. Tests stub Net::HTTP at the wire level
+    # (webmock); this method performs the real request and is the single point
+    # where the network is touched.
+    def send_request(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      req = Net::HTTP::Get.new(uri)
+      req["User-Agent"] = USER_AGENT
+
+      response = http.request(req)
+      handle(response)
+    rescue Timeout::Error, IOError, SocketError, SystemCallError, Net::HTTPBadResponse,
+           Net::ProtocolError, OpenSSL::SSL::SSLError => e
+      raise TransportError.new(e.message)
+    end
+
+    # Map the HTTP response to a parsed body + quota, or raise a typed error.
+    def handle(response)
+      quota = parse_quota(response)
+      code = response.code.to_i
+      body = parse_json(response.body)
+
+      return [body, quota] if code.between?(200, 299)
+
+      message = body.is_a?(Hash) ? body["error"] : nil
+      message ||= "HTTP #{code}"
+      raise error_for(code).new(message, status: code, quota: quota)
+    end
+
+    # Select the error class for a status code.
+    def error_for(code)
+      case code
+      when 401 then AuthError
+      when 402 then SubscriptionError
+      when 422 then ValidationError
+      when 429 then RateLimitError
+      else Error
+      end
+    end
+
+    def parse_json(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise TransportError.new("Response body is not valid JSON: #{e.message}")
+    end
+
+    # Read the rate-limit headers case-insensitively into a Quota. Net::HTTP
+    # already normalizes header names to lowercase for lookup.
+    def parse_quota(response)
+      limit = response["x-rate-limit-limit"]
+      remaining = response["x-rate-limit-remaining"]
+      reset = response["x-rate-limit-reset"]
+      return nil if limit.nil? && remaining.nil? && reset.nil?
+
+      Quota.new(
+        limit: to_i_or_nil(limit),
+        remaining: to_i_or_nil(remaining),
+        reset: to_i_or_nil(reset)
+      )
+    end
+
+    def to_i_or_nil(value)
+      value.nil? ? nil : value.to_i
+    end
+
+    def single(body)
+      unless body.is_a?(Hash)
+        raise TransportError.new("Expected a JSON object, got #{body.class}.")
+      end
+      body
+    end
+
+    def array(body)
+      unless body.is_a?(Array)
+        raise TransportError.new("Expected a JSON array, got #{body.class}.")
+      end
+      body
+    end
+
+    def parse_genderize(obj)
+      GenderizePrediction.new(
+        name: obj["name"],
+        gender: obj["gender"],
+        probability: obj["probability"],
+        count: obj["count"],
+        country_id: obj["country_id"]
+      )
+    end
+
+    def parse_agify(obj)
+      AgifyPrediction.new(
+        name: obj["name"],
+        age: obj["age"],
+        count: obj["count"],
+        country_id: obj["country_id"]
+      )
+    end
+
+    def parse_nationalize(obj)
+      countries = Array(obj["country"]).map do |c|
+        NationalizeCountry.new(
+          country_id: c["country_id"],
+          probability: c["probability"]
+        )
+      end
+      NationalizePrediction.new(
+        name: obj["name"],
+        country: countries,
+        count: obj["count"]
+      )
+    end
+  end
+end

data/lib/demografix/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Demografix
+  # Base class for every error the SDK raises. Carries the HTTP status (when
+  # one is known), the server-provided message, and the quota parsed from the
+  # rate-limit headers (when present).
+  class Error < StandardError
+    attr_reader :status, :quota
+
+    def initialize(message = nil, status: nil, quota: nil)
+      super(message)
+      @status = status
+      @quota = quota
+    end
+  end
+
+  # 401 — the API key is missing or invalid.
+  class AuthError < Error; end
+
+  # 402 — the subscription is not active (expired freebie or inactive plan).
+  class SubscriptionError < Error; end
+
+  # 422 — the request parameters are invalid. Also raised client-side, before
+  # any HTTP call, when a batch contains more than the maximum number of names.
+  class ValidationError < Error; end
+
+  # 429 — the request limit for the current window is reached. Read
+  # quota.reset for the seconds to wait before retrying.
+  class RateLimitError < Error; end
+
+  # Network failure, timeout, or a response body that is not valid JSON.
+  # status and quota may be absent.
+  class TransportError < Error; end
+end

data/lib/demografix/models.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Demografix
+  # The rate-limit window, parsed from the x-rate-limit-* response headers.
+  Quota = Data.define(:limit, :remaining, :reset)
+
+  # One nationalize candidate: a country and its probability.
+  NationalizeCountry = Data.define(:country_id, :probability)
+
+  # A single genderize prediction. country_id is set only when the request
+  # carried one.
+  GenderizePrediction = Data.define(:name, :gender, :probability, :count, :country_id)
+
+  # A single agify prediction. country_id is set only when the request carried
+  # one.
+  AgifyPrediction = Data.define(:name, :age, :count, :country_id)
+
+  # A single nationalize prediction. country is an array of NationalizeCountry,
+  # descending by probability, possibly empty.
+  NationalizePrediction = Data.define(:name, :country, :count)
+
+  # A single-name result: every prediction field plus a quota reader.
+  GenderizeResult = Data.define(:name, :gender, :probability, :count, :country_id, :quota)
+  AgifyResult = Data.define(:name, :age, :count, :country_id, :quota)
+  NationalizeResult = Data.define(:name, :country, :count, :quota)
+
+  # A batch result: the per-name predictions plus one quota for the response.
+  Batch = Data.define(:results, :quota)
+end

data/lib/demografix/version.rb

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

data/lib/demografix.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "demografix/version"
+require_relative "demografix/errors"
+require_relative "demografix/models"
+require_relative "demografix/client"
+
+# Demografix is the official Ruby client for the genderize, agify, and
+# nationalize APIs. Construct a Demografix::Client and call genderize, agify,
+# or nationalize (with their _batch forms) to predict gender, age, and
+# nationality from names.
+module Demografix
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: demografix
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Demografix
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: One client for the three Demografix APIs — gender, age, and nationality
+  prediction from names — reporting the remaining quota carried on every response.
+email:
+- info@genderize.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/demografix.rb
+- lib/demografix/client.rb
+- lib/demografix/errors.rb
+- lib/demografix/models.rb
+- lib/demografix/version.rb
+homepage: https://github.com/DemografixGenderize/demografix-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DemografixGenderize/demografix-ruby
+  documentation_uri: https://genderize.io/documentation/api
+  source_code_uri: https://github.com/DemografixGenderize/demografix-ruby
+  bug_tracker_uri: https://github.com/DemografixGenderize/demografix-ruby/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: Official Ruby client for the genderize, agify, and nationalize APIs.
+test_files: []