bandcamp-discover 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2c7501fed34fb2971b6be16d1abb01ea93b25246dc117d0ef5f45f76a884a81
-  data.tar.gz: f3b13208003d5c7473a5fab3c010119f0cafb6cd5e161f1c7a92796af97ed8fa
+  metadata.gz: 0d06bbc06b837c9d82502a0d9e9a61d3d2062af141f2a19e28ff0cb3e7e3fe5d
+  data.tar.gz: 2b2bbe5682ed207b8911f31a74e1a1a0b8bf471326509b35a3849527b39bcab7
 SHA512:
-  metadata.gz: 39337db593351f00eb19f50826342512bd4e7e16fb680074d30734669486db1f56d9e6b7959664acf1ffe77d122984571eabf4c261a02abf52e778c9dbab0fcb
-  data.tar.gz: 32c9359e36d955b34fb9fc36942bbe455dc99e4a41e9032ac0ae3d6420e76bc9b8840f629c90e797669358979b2317bcd42ef55bf54e52ab07f00378ed637f45
+  metadata.gz: 70c78eccc21549dd9c08fe183ec8ddf6a11060d79e913891ebca47de23f01248a07e7b73e27ea5fb45ba463ea93469d98f8be7f7fdcf5e99576600d5f2992c2a
+  data.tar.gz: d345ad2550cd0ea344d0310a2aa8bdf351a5a3b08b999a19395092e7669ba07b9d98d9ea18a96b7480c3e5d4e44774922db943d115c1ca066ab1592cc058ac6c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bandcamp-discover (0.5.0)
+    bandcamp-discover (0.6.0)
       async
       base64
       concurrent-ruby

data/README.rdoc

@@ -2,5 +2,25 @@
 
 Describe your project here
 
+== Configuration
+
+When the +open_router+ gem is loaded and has an access token, +Analyzer+
+asks a model whether a Bandcamp bio belongs to a label and whether it
+accepts demos. The model and both prompts can be set by the host app:
+
+  BandcampDiscover.configure do |config|
+    config.model = "anthropic/claude-3.5-haiku"   # default: "openrouter/auto"
+    config.label_prompt = "..."                    # must ask for {"answer": true|false}
+    config.demos_prompt = "..."
+  end
+
+Before the bio is asked, the /music grid is read: a page whose releases carry
+no artist credit other than the owner is an artist, not a label, and is
+rejected without a model call. The credits that remain are appended to the
+bio for the model and returned as +artists+ in the scrape result.
+
+Without a token, +label?+ falls back to matching /label|platform|records/i
+and +accepts_demos?+ is always false.
+
 :include:bandcamp-discover.rdoc
 

data/lib/bandcamp-discover/analyzer.rb

@@ -1,54 +1,54 @@
+require "json"
+require_relative "configuration"
+
 module BandcampDiscover
   class Analyzer
-    def initialize(description, model = nil)
+    # A per-call model still wins over the configured one so existing callers
+    # keep their behaviour.
+    def initialize(description, model = nil, credits: [])
       @description = description
-      @model = model || "openrouter/auto"
+      @credits = credits
+      @model = model || BandcampDiscover.configuration.model
     end
 
     def label?
-      if defined?(OpenRouter) && !!OpenRouter.configuration.access_token
-        response = OpenRouter::Client.new.complete(
-          [
-            { role: "system", content: "You are given a description that could or could not be that of a record label. Analyze and answer witha JSON object  {\"answer\": true|false}. Be critical: Individuals and bands are not labels, but collectives can be labels." },
-            { role: "user", content: @description }
-          ],
-          model: [
-            @model
-          ],
-          extras: {
-            response_format: {
-              type: "json_object"
-            }
-          }
-        )
-
-        JSON.parse(response["choices"][0]["message"]["content"])["answer"]&.to_s&.downcase == "true"
-      else
-        @description.match? /label|platform|records/i
-      end
+      return ask(BandcampDiscover.configuration.label_prompt) if llm?
+
+      @description.to_s.match?(/label|platform|records/i)
     end
 
     def accepts_demos?
-      if defined?(OpenRouter) && !!OpenRouter.configuration.access_token
-        response = OpenRouter::Client.new.complete(
-          [
-            { role: "system", content: "You are given a description of a record label or music platform. Analyze if they accept demo submissions from artists. Look for mentions of 'demos', 'demo submissions', 'send demos', 'submit music', 'accepting submissions', contact information for demos, or similar language. Be critical, and default to false. Only answer with true when you are certain that the label accepts demos. Answer with a JSON object {\"answer\": true|false}." },
-            { role: "user", content: @description }
-          ],
-          model: [
-            @model
-          ],
-          extras: {
-            response_format: {
-              type: "json_object"
-            }
-          }
-        )
-
-        JSON.parse(response["choices"][0]["message"]["content"])["answer"]&.to_s&.downcase == "true"
-      else
-        false
-      end
+      return false unless llm?
+
+      ask(BandcampDiscover.configuration.demos_prompt)
+    end
+
+    private
+
+    def llm?
+      defined?(OpenRouter) && !!OpenRouter.configuration.access_token
+    end
+
+    def ask(prompt)
+      response = OpenRouter::Client.new.complete(
+        [
+          {role: "system", content: prompt},
+          {role: "user", content: message}
+        ],
+        model: [@model],
+        extras: {response_format: {type: "json_object"}}
+      )
+
+      JSON.parse(response["choices"][0]["message"]["content"])["answer"]&.to_s&.downcase == "true"
+    end
+
+    # The bio alone cannot tell one person releasing under aliases from a
+    # roster; who the releases are credited to is the other half of the answer.
+    def message
+      return @description.to_s if @credits.empty?
+
+      "#{@description}\n\nReleases on this page are credited to #{@credits.size} " \
+        "#{(@credits.size == 1) ? "artist" : "artists"} other than the page owner: #{@credits.join(", ")}."
     end
   end
 end

data/lib/bandcamp-discover/configuration.rb

@@ -0,0 +1,40 @@
+module BandcampDiscover
+  # The prompts decide what enters a catalogue, and tuning them used to mean a
+  # gem release. Hosting apps set them once; the defaults keep every existing
+  # caller behaving as before.
+  class Configuration
+    DEFAULT_MODEL = "openrouter/auto"
+
+    DEFAULT_LABEL_PROMPT = "You are given a description that could or could not be that of a record label. " \
+      "Analyze and answer with a JSON object {\"answer\": true|false}. " \
+      "Be critical: Individuals and bands are not labels, but collectives can be labels."
+
+    DEFAULT_DEMOS_PROMPT = "You are given a description of a record label or music platform. " \
+      "Analyze if they accept demo submissions from artists. Look for mentions of 'demos', 'demo submissions', " \
+      "'send demos', 'submit music', 'accepting submissions', contact information for demos, or similar language. " \
+      "Be critical, and default to false. Only answer with true when you are certain that the label accepts demos. " \
+      "Answer with a JSON object {\"answer\": true|false}."
+
+    attr_accessor :model, :label_prompt, :demos_prompt
+
+    def initialize
+      @model = DEFAULT_MODEL
+      @label_prompt = DEFAULT_LABEL_PROMPT
+      @demos_prompt = DEFAULT_DEMOS_PROMPT
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end

data/lib/bandcamp-discover/roster.rb

@@ -0,0 +1,35 @@
+module BandcampDiscover
+  # A label's /music grid credits each release to its artist; an artist's own
+  # page credits nothing, because the artist is the page. That is the one
+  # structural difference between the two, and it costs no API call.
+  #
+  # It only ever says "no": one person releasing under aliases looks like a
+  # roster, and a bio can say "not a label" over a grid full of credits, so a
+  # positive still has to come from the bio.
+  class Roster
+    attr_reader :band_name, :releases, :credits
+
+    def initialize(band_name:, credits:, releases: credits.size)
+      @band_name = band_name.to_s.strip
+      @releases = releases
+      @credits = credits.compact.map(&:strip).reject { |credit| credit.empty? || own?(credit) }.uniq
+    end
+
+    # A single self-released record is not evidence either way.
+    def solo?
+      credits.empty? && releases >= 2
+    end
+
+    private
+
+    # "Sean Woosley" and "Woosley Band" on woosley.bandcamp.com are the owner,
+    # not a roster.
+    def own?(credit)
+      a = credit.downcase
+      b = band_name.downcase
+      return false if b.empty?
+
+      a.include?(b) || b.include?(a)
+    end
+  end
+end

data/lib/bandcamp-discover/scrapers/base.rb

@@ -15,7 +15,13 @@ module BandcampDiscover
       end
 
       def scrape(force: false)
-        yield @page if block_given?
+        guarded { yield @page if block_given? }
+      end
+
+      private
+
+      def guarded
+        yield
       rescue Playwright::TimeoutError => e
         raise ScrapeError, "Timed out waiting for an element on #{@url}: #{e.message}"
       end

data/lib/bandcamp-discover/scrapers/label.rb

@@ -1,5 +1,5 @@
-require_relative "./base"
-require_relative "./music"
+require_relative "base"
+require_relative "music"
 require_relative "../analyzer"
 
 module BandcampDiscover
@@ -16,9 +16,13 @@ module BandcampDiscover
           name = band_name_location_container.query_selector(".title").inner_text
           location = band_name_location_container.query_selector(".location").inner_text
 
-          if force || Analyzer.new(bio_text&.inner_html).label?
+          music = Scrapers::Music.new(url: "#{@url}/music", browser: @browser, max_tasks: @max_tasks)
+          grid = music.grid
+          roster = music.roster(grid, band_name: name)
+
+          if force || label?(roster, bio_text&.inner_html)
             return Sync do
-              albums, music_tags = Scrapers::Music.new(url: "#{@url}/music", browser: @browser, max_tasks: @max_tasks).scrape
+              albums, music_tags = music.albums(grid)
 
               puts "done scraping #{@url}"
 
@@ -27,6 +31,7 @@ module BandcampDiscover
                 name: name,
                 location: location,
                 bio: bio_text.inner_text,
+                artists: roster.credits,
                 tags_with_weights: music_tags&.compact,
                 albums: albums
               }
@@ -37,6 +42,15 @@ module BandcampDiscover
           end
         end
       end
+
+      private
+
+      # The grid can rule a page out for free; only the rest costs a model call.
+      def label?(roster, bio)
+        return false if roster.solo?
+
+        Analyzer.new(bio, credits: roster.credits).label?
+      end
     end
   end
 end

data/lib/bandcamp-discover/scrapers/music.rb

@@ -1,11 +1,14 @@
 require_relative "base"
 require_relative "album"
+require_relative "../roster"
 require "async"
 require "async/semaphore"
 
 module BandcampDiscover
   module Scrapers
     class Music < Base
+      MAX_ALBUMS = 20
+
       def initialize(url:, browser:, max_tasks:)
         super
 
@@ -14,28 +17,48 @@ module BandcampDiscover
       end
 
       def scrape(force: false)
-        super do |page|
-          page.goto(@url)
-          album_list = page.wait_for_selector("#music-grid")
-          album_links = album_list.query_selector_all("li.music-grid-item > a")
+        albums(grid)
+      end
+
+      # The grid alone tells a label from an artist (see Roster), and it is one
+      # page load against the twenty behind albums, so callers can look at it
+      # before paying for the rest.
+      def grid
+        guarded do
+          @page.goto(@url)
+          items = @page.wait_for_selector("#music-grid").query_selector_all("li.music-grid-item")
+
+          items.map do |item|
+            {
+              url: absolute(item.query_selector("a")[:href]),
+              credit: item.query_selector(".artist-override")&.inner_text
+            }
+          end
+        end
+      end
+
+      def roster(grid, band_name:)
+        Roster.new(band_name: band_name, credits: grid.map { _1[:credit] }, releases: grid.size)
+      end
 
+      def albums(grid)
+        guarded do
           semaphore = Async::Semaphore.new(@max_tasks)
 
-          albums = album_links.take(20).map do |album_link|
+          albums = grid.take(MAX_ALBUMS).map do |item|
             semaphore.async do
-              url = album_link[:href].start_with?("https://") ? album_link[:href] : "#{@base_url}#{album_link[:href]}"
-              puts "starting to scrape #{url}"
+              puts "starting to scrape #{item[:url]}"
 
-              album = Scrapers::Album.new(url: url, browser: @browser).scrape
+              album = Scrapers::Album.new(url: item[:url], browser: @browser).scrape
 
-              puts "done scraping #{url}"
+              puts "done scraping #{item[:url]}"
 
               album
             end
           end.map(&:wait)
 
           albums.map! do |album_url, album_title, album_tags, album_player|
-            { url: album_url, title: album_title, tags: album_tags, player_url: album_player }
+            {url: album_url, title: album_title, tags: album_tags, player_url: album_player}
           end
 
           [albums, normalize_tally(albums.map { _1[:tags] }.flatten.tally)]
@@ -47,6 +70,12 @@ module BandcampDiscover
         tally.transform_values! { |count| count / total }
         tally.sort_by { |k, v| v }.reverse.to_h
       end
+
+      private
+
+      def absolute(href)
+        href.start_with?("https://") ? href : "#{@base_url}#{href}"
+      end
     end
   end
 end

data/lib/bandcamp-discover/version.rb

@@ -1,3 +1,3 @@
 module BandcampDiscover
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/test/analyzer_test.rb

@@ -0,0 +1,106 @@
+require_relative "test_helper"
+require "bandcamp-discover/analyzer"
+
+# OpenRouter is the host app's dependency, not this gem's, so a stand-in that
+# records the request is enough to prove what the Analyzer sends.
+module OpenRouter
+  Configuration = Struct.new(:access_token)
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  class Client
+    class << self
+      attr_accessor :requests, :answer
+    end
+
+    def complete(messages, model:, extras:)
+      self.class.requests << {messages: messages, model: model, extras: extras}
+      {"choices" => [{"message" => {"content" => JSON.generate("answer" => self.class.answer)}}]}
+    end
+  end
+end
+
+class AnalyzerTest < Minitest::Test
+  Analyzer = BandcampDiscover::Analyzer
+
+  def setup
+    BandcampDiscover.reset_configuration!
+    OpenRouter.configuration.access_token = "token"
+    OpenRouter::Client.requests = []
+    OpenRouter::Client.answer = true
+  end
+
+  def teardown
+    BandcampDiscover.reset_configuration!
+    OpenRouter.configuration.access_token = nil
+  end
+
+  def test_defaults_match_the_prompts_and_model_shipped_so_far
+    Analyzer.new("We release tapes.").label?
+
+    request = OpenRouter::Client.requests.last
+    assert_equal ["openrouter/auto"], request[:model]
+    assert_includes request[:messages].first[:content], "Individuals and bands are not labels"
+    assert_equal "We release tapes.", request[:messages].last[:content]
+  end
+
+  def test_configured_prompt_and_model_are_sent
+    BandcampDiscover.configure do |config|
+      config.model = "anthropic/claude-3.5-haiku"
+      config.label_prompt = "Is this a label? Answer {\"answer\": true|false}."
+    end
+
+    Analyzer.new("bio").label?
+
+    request = OpenRouter::Client.requests.last
+    assert_equal ["anthropic/claude-3.5-haiku"], request[:model]
+    assert_equal "Is this a label? Answer {\"answer\": true|false}.", request[:messages].first[:content]
+  end
+
+  def test_per_call_model_wins_over_the_configured_one
+    BandcampDiscover.configure { |config| config.model = "configured/model" }
+
+    Analyzer.new("bio", "explicit/model").label?
+
+    assert_equal ["explicit/model"], OpenRouter::Client.requests.last[:model]
+  end
+
+  def test_demos_prompt_is_configurable_too
+    BandcampDiscover.configure { |config| config.demos_prompt = "Demos?" }
+
+    Analyzer.new("bio").accepts_demos?
+
+    assert_equal "Demos?", OpenRouter::Client.requests.last[:messages].first[:content]
+  end
+
+  def test_credits_are_appended_to_the_bio
+    Analyzer.new("We run a tape label.", credits: ["Helen", "Cate Kennan"]).label?
+
+    message = OpenRouter::Client.requests.last[:messages].last[:content]
+    assert_equal "We run a tape label.\n\nReleases on this page are credited to 2 artists other than the page owner: Helen, Cate Kennan.", message
+  end
+
+  def test_no_credits_sends_the_bio_alone
+    Analyzer.new(nil, credits: []).label?
+
+    assert_equal "", OpenRouter::Client.requests.last[:messages].last[:content]
+  end
+
+  def test_parses_the_answer
+    OpenRouter::Client.answer = false
+
+    refute Analyzer.new("bio").label?
+  end
+
+  def test_falls_back_to_the_regex_without_a_token
+    OpenRouter.configuration.access_token = nil
+
+    assert Analyzer.new("An independent label from Graz").label?
+    refute Analyzer.new("Solo musician").label?
+    refute Analyzer.new(nil).label?
+    refute Analyzer.new("Send demos to ...").accepts_demos?
+    assert_empty OpenRouter::Client.requests
+  end
+end

data/test/roster_test.rb

@@ -0,0 +1,52 @@
+require_relative "test_helper"
+require "bandcamp-discover/roster"
+
+# Cases are real pages from the discover.bandcamp.labels similarity audit.
+class RosterTest < Minitest::Test
+  Roster = BandcampDiscover::Roster
+
+  def test_a_label_credits_other_artists
+    roster = Roster.new(band_name: "kranky", credits: ["Helen", "Cate Kennan", "Ana Roxanne", "Helen"])
+
+    refute roster.solo?
+    assert_equal ["Helen", "Cate Kennan", "Ana Roxanne"], roster.credits
+  end
+
+  def test_an_artist_page_credits_nobody
+    roster = Roster.new(band_name: "Radiohead", credits: [nil] * 15)
+
+    assert roster.solo?
+    assert_empty roster.credits
+  end
+
+  def test_credits_naming_the_owner_are_not_a_roster
+    roster = Roster.new(band_name: "Woosley", credits: ["Sean Woosley", "Woosley Band", nil, nil, nil])
+
+    assert roster.solo?
+  end
+
+  def test_owner_match_is_case_insensitive_and_either_direction
+    roster = Roster.new(band_name: "Soul Juice", credits: ["J Sand (Soul Juice)", "Geechie Dan", "soul juice"])
+
+    assert_equal ["Geechie Dan"], roster.credits
+    refute roster.solo?
+  end
+
+  def test_a_single_self_release_is_not_evidence
+    roster = Roster.new(band_name: "New Label", credits: [nil])
+
+    refute roster.solo?
+  end
+
+  def test_releases_can_outnumber_rendered_credits
+    roster = Roster.new(band_name: "Whoever", credits: [], releases: 12)
+
+    assert roster.solo?
+  end
+
+  def test_blank_band_name_keeps_every_credit
+    roster = Roster.new(band_name: nil, credits: [" A ", "", "B"])
+
+    assert_equal ["A", "B"], roster.credits
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bandcamp-discover
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Julian RUbisch
 bindir: bin
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -195,14 +195,18 @@ files:
 - bin/bandcamp-discover
 - lib/bandcamp-discover.rb
 - lib/bandcamp-discover/analyzer.rb
+- lib/bandcamp-discover/configuration.rb
+- lib/bandcamp-discover/roster.rb
 - lib/bandcamp-discover/scrapers/album.rb
 - lib/bandcamp-discover/scrapers/base.rb
 - lib/bandcamp-discover/scrapers/discover.rb
 - lib/bandcamp-discover/scrapers/label.rb
 - lib/bandcamp-discover/scrapers/music.rb
 - lib/bandcamp-discover/version.rb
+- test/analyzer_test.rb
 - test/default_test.rb
 - test/discover_test.rb
+- test/roster_test.rb
 - test/test_helper.rb
 homepage: https://julianrubisch.at
 licenses: []