prospector_engine 0.1.1

data/app/jobs/prospector/bulk_approve_job.rb

@@ -0,0 +1,14 @@
+module Prospector
+  class BulkApproveJob < ApplicationJob
+    def perform(run_id)
+      run = Run.find(run_id)
+      run.candidates.where(status: "pending").find_each do |candidate|
+        next unless candidate.approvable?
+
+        candidate.approve!
+      rescue => e
+        Rails.logger.warn "Prospector: skip approve #{candidate.id}: #{e.message}"
+      end
+    end
+  end
+end

data/app/jobs/prospector/classify_job.rb

@@ -0,0 +1,17 @@
+module Prospector
+  class ClassifyJob < ApplicationJob
+    def perform(run_id, force: false, model: nil, classification_run_id: nil)
+      run = Run.find(run_id)
+      classification_run = ClassificationRun.find_by(id: classification_run_id)
+
+      classification_run&.update!(status: "running", started_at: Time.current)
+
+      Classification::Runner.new(
+        run,
+        model: model,
+        include_approved: force,
+        classification_run: classification_run
+      ).perform
+    end
+  end
+end

data/app/jobs/prospector/fetch_job.rb

@@ -0,0 +1,8 @@
+module Prospector
+  class FetchJob < ApplicationJob
+    def perform(run_id)
+      run = Run.find(run_id)
+      Pipeline::Orchestrator.new(run).perform
+    end
+  end
+end

data/app/models/prospector/application_record.rb

@@ -0,0 +1,6 @@
+module Prospector
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name_prefix = "prospector_"
+  end
+end

data/app/models/prospector/candidate.rb

@@ -0,0 +1,93 @@
+module Prospector
+  class Candidate < ApplicationRecord
+    STATUSES = %w[pending approved rejected].freeze
+
+    belongs_to :run
+
+    validates :name, presence: true
+    validates :address, presence: true
+    validates :source_uid, presence: true, uniqueness: { scope: :run_id }
+    validates :status, presence: true, inclusion: { in: STATUSES }
+
+    if defined?(Turbo::Broadcastable)
+      broadcasts_refreshes_to :run
+    end
+
+    scope :by_status, ->(status) { where(status: status) }
+    scope :pending, -> { where(status: "pending") }
+    scope :approved, -> { where(status: "approved") }
+    scope :rejected, -> { where(status: "rejected") }
+    scope :ai_unprocessed, -> { where("NOT (metadata ? 'llm_categories')") }
+    scope :ai_processed, -> { where("metadata ? 'llm_categories'") }
+    scope :auto_rejected, -> { rejected.where("metadata->>'rejection_reason' = ?", "no_relevant_categories") }
+
+    def pending? = status == "pending"
+    def approved? = status == "approved"
+    def rejected? = status == "rejected"
+
+    def approve!
+      raise Error, "Candidate is not approvable" unless approvable?
+
+      update!(status: "approved")
+      complete_approval
+    rescue => e
+      update!(status: "pending") if approved?
+      raise Error, "Approval failed: #{e.message}"
+    end
+
+    def reject!(reason: nil)
+      attrs = { status: "rejected" }
+      attrs[:metadata] = metadata.merge("rejection_reason" => reason) if reason
+      update!(attrs)
+      instrument("prospector.candidate.rejected", candidate: self, reason: reason)
+    end
+
+    def restore_to_pending!
+      new_metadata = metadata.except("rejection_reason")
+      update!(status: "pending", metadata: new_metadata)
+    end
+
+    def normalized_data
+      metadata["normalized_data"] || {}
+    end
+
+    def llm_categories
+      metadata["llm_categories"] || []
+    end
+
+    def llm_confidence
+      metadata["llm_confidence"]
+    end
+
+    def llm_reasoning
+      metadata["llm_reasoning"]
+    end
+
+    SOCIAL_FIELDS = %i[facebook_url instagram_url linkedin_url tiktok_url youtube_url].freeze
+
+    def approvable?
+      pending? && normalized_data["state"].present?
+    end
+
+    def has_contact_info?
+      email.present? || SOCIAL_FIELDS.any? { |f| self[f].present? }
+    end
+
+    private
+
+    def complete_approval
+      record = invoke_on_approve
+      instrument("prospector.candidate.approved", candidate: self, record: record)
+      record
+    end
+
+    def invoke_on_approve
+      callback = Prospector.config.on_approve
+      callback ? callback.call(self) : nil
+    end
+
+    def instrument(event, payload = {})
+      ActiveSupport::Notifications.instrument(event, payload)
+    end
+  end
+end

data/app/models/prospector/classification_run.rb

@@ -0,0 +1,15 @@
+module Prospector
+  class ClassificationRun < ApplicationRecord
+    STATUSES = %w[pending running completed failed].freeze
+
+    belongs_to :run
+
+    validates :ai_model, presence: true
+    validates :status, presence: true, inclusion: { in: STATUSES }
+
+    def pending? = status == "pending"
+    def running? = status == "running"
+    def completed? = status == "completed"
+    def failed? = status == "failed"
+  end
+end

data/app/models/prospector/keyword.rb

@@ -0,0 +1,16 @@
+module Prospector
+  class Keyword < ApplicationRecord
+    validates :domain, presence: true
+    validates :category, presence: true
+    validates :keyword, presence: true, uniqueness: { scope: %i[domain category] }
+    validates :source, presence: true
+
+    scope :active, -> { where(active: true) }
+    scope :for_domain, ->(domain) { where(domain: domain) }
+    scope :for_category, ->(category) { where(category: category) }
+
+    def self.keywords_for(domain:, category:)
+      active.for_domain(domain).for_category(category).pluck(:keyword)
+    end
+  end
+end

data/app/models/prospector/run.rb

@@ -0,0 +1,94 @@
+module Prospector
+  class Run < ApplicationRecord
+    STATUSES = %w[pending running classifying completed failed cancelled].freeze
+
+    has_many :candidates, dependent: :destroy
+    has_many :classification_runs, dependent: :destroy
+
+    validates :status, presence: true, inclusion: { in: STATUSES }
+    validates :source_adapter, presence: true
+    validates :geography_type, presence: true
+
+    if defined?(Turbo::Broadcastable)
+      broadcasts_refreshes
+    end
+
+    after_update_commit :instrument_status_change, if: :saved_change_to_status?
+
+    scope :by_status, ->(status) { where(status: status) }
+    scope :recent, -> { order(created_at: :desc) }
+
+    def pending? = status == "pending"
+    def running? = status == "running"
+    def classifying? = status == "classifying"
+    def completed? = status == "completed"
+    def failed? = status == "failed"
+    def cancelled? = status == "cancelled"
+
+    def cancellable?
+      pending? || running? || classifying?
+    end
+
+    def restartable?
+      completed? || failed? || cancelled?
+    end
+
+    def retryable? = failed?
+
+    def cancel!
+      update!(status: "cancelled", completed_at: Time.current)
+      instrument("prospector.run.cancelled", run: self)
+    end
+
+    def reset_for_retry!
+      update!(
+        status: "pending",
+        error_messages: nil,
+        error_count: 0,
+        started_at: nil,
+        completed_at: nil
+      )
+    end
+
+    def restart!
+      transaction do
+        candidates.where(status: %w[pending rejected]).destroy_all
+        update!(
+          status: "pending",
+          total_found: 0,
+          fetched_count: 0,
+          skipped_count: 0,
+          error_count: 0,
+          error_messages: nil,
+          metadata: {},
+          started_at: nil,
+          completed_at: nil
+        )
+      end
+    end
+
+    def geography
+      Geography::Base.from_h(geography_data.merge("type" => geography_type))
+    end
+
+    def geography=(geo)
+      self.geography_type = geo.type
+      self.geography_data = geo.to_h
+    end
+
+    private
+
+    def instrument_status_change
+      ActiveSupport::Notifications.instrument(
+        "prospector.run.status_changed",
+        run: self,
+        status: status,
+        previous_status: status_before_last_save
+      )
+    end
+
+    def instrument(event, payload = {})
+      ActiveSupport::Notifications.instrument(event, payload)
+    end
+  end
+end

data/app/views/prospector/candidates/show.html.erb

@@ -0,0 +1,63 @@
+<%= link_to "&larr; Back to run".html_safe, run_path(@run, filter: @candidate.status), class: "prospector-text-muted prospector-text-sm" %>
+
+<h1 class="prospector-heading prospector-mt-4"><%= @candidate.name %></h1>
+
+<div class="prospector-flex prospector-gap-2" style="margin-bottom: 1rem;">
+  <span class="prospector-badge prospector-badge-<%= @candidate.status %>"><%= @candidate.status.titleize %></span>
+  <% if @candidate.llm_confidence %>
+    <span class="prospector-text-muted prospector-text-sm">Confidence: <%= (@candidate.llm_confidence * 100).round %>%</span>
+  <% end %>
+</div>
+
+<div class="prospector-card">
+  <h2 class="prospector-subheading">Details</h2>
+  <table class="prospector-table">
+    <tbody>
+      <tr><td><strong>Address</strong></td><td><%= @candidate.address %></td></tr>
+      <tr><td><strong>Phone</strong></td><td><%= @candidate.phone_number || "-" %></td></tr>
+      <tr><td><strong>Website</strong></td><td><%= @candidate.website.present? ? link_to(@candidate.website, @candidate.website, target: "_blank") : "-" %></td></tr>
+      <tr><td><strong>Category</strong></td><td><%= @candidate.category || "-" %></td></tr>
+      <tr><td><strong>Source UID</strong></td><td class="prospector-text-muted"><%= @candidate.source_uid %></td></tr>
+      <tr><td><strong>Rating</strong></td><td><%= @candidate.metadata["rating"] || "-" %> (<%= @candidate.metadata["rating_count"] || 0 %> reviews)</td></tr>
+    </tbody>
+  </table>
+</div>
+
+<% if @candidate.has_contact_info? %>
+  <div class="prospector-card">
+    <h2 class="prospector-subheading">Contact & Social</h2>
+    <table class="prospector-table">
+      <tbody>
+        <% if @candidate.email.present? %>
+          <tr><td><strong>Email</strong></td><td><%= mail_to @candidate.email %></td></tr>
+        <% end %>
+        <% Prospector::Candidate::SOCIAL_FIELDS.each do |field| %>
+          <% url = @candidate[field] %>
+          <% if url.present? %>
+            <tr><td><strong><%= field.to_s.chomp("_url").titleize %></strong></td><td><%= link_to truncate(url, length: 50), url, target: "_blank" %></td></tr>
+          <% end %>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% end %>
+
+<% if @candidate.llm_categories.any? %>
+  <div class="prospector-card">
+    <h2 class="prospector-subheading">AI Classification</h2>
+    <p><strong>Categories:</strong> <%= @candidate.llm_categories.join(", ") %></p>
+    <p class="prospector-text-muted prospector-text-sm"><%= @candidate.llm_reasoning %></p>
+  </div>
+<% end %>
+
+<div class="prospector-flex prospector-gap-2 prospector-mt-4">
+  <% if @candidate.pending? && @candidate.approvable? %>
+    <%= button_to "Approve", run_candidate_path(@run, @candidate, status: "approved"), method: :patch, class: "prospector-btn prospector-btn-primary" %>
+  <% end %>
+  <% if @candidate.pending? %>
+    <%= button_to "Reject", run_candidate_path(@run, @candidate, status: "rejected"), method: :patch, class: "prospector-btn prospector-btn-danger" %>
+  <% end %>
+  <% if @candidate.rejected? %>
+    <%= button_to "Restore to Pending", run_candidate_path(@run, @candidate, status: "pending"), method: :patch, class: "prospector-btn prospector-btn-outline" %>
+  <% end %>
+</div>

data/app/views/prospector/keywords/index.html.erb

@@ -0,0 +1,72 @@
+<div class="prospector-flex prospector-flex-between">
+  <h1 class="prospector-heading">Keywords</h1>
+  <span class="prospector-text-muted prospector-text-sm">Domain: <strong><%= @domain %></strong></span>
+</div>
+
+<div class="prospector-card">
+  <h2 class="prospector-subheading">Add Keyword</h2>
+  <%= form_with model: Prospector::Keyword.new, url: keywords_path, method: :post do |f| %>
+    <%= f.hidden_field :domain, value: @domain %>
+    <div class="prospector-flex prospector-gap-4" style="align-items: flex-end;">
+      <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+        <%= f.label :category, class: "prospector-label" %>
+        <%= f.text_field :category, class: "prospector-input", placeholder: "e.g. mechanic" %>
+      </div>
+      <div class="prospector-form-group" style="flex: 2; margin-bottom: 0;">
+        <%= f.label :keyword, class: "prospector-label" %>
+        <%= f.text_field :keyword, class: "prospector-input", placeholder: "e.g. motorcycle repair shop" %>
+      </div>
+      <div>
+        <%= f.submit "Add", class: "prospector-btn prospector-btn-primary" %>
+      </div>
+    </div>
+  <% end %>
+</div>
+
+<% if @categories.any? %>
+  <% @categories.each do |category| %>
+    <div class="prospector-card">
+      <div class="prospector-flex prospector-flex-between" style="margin-bottom: 0.75rem;">
+        <h2 class="prospector-subheading" style="margin-bottom: 0;"><%= category %></h2>
+        <%= button_to "Generate via AI",
+            keyword_generations_path(domain: @domain, category: category),
+            method: :post,
+            class: "prospector-btn prospector-btn-outline prospector-btn-sm" %>
+      </div>
+      <table class="prospector-table">
+        <thead>
+          <tr>
+            <th>Keyword</th>
+            <th>Source</th>
+            <th>Active</th>
+            <th></th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @keywords.where(category: category).each do |kw| %>
+            <tr>
+              <td><%= kw.keyword %></td>
+              <td>
+                <span class="prospector-badge <%= kw.source == 'llm' ? 'prospector-badge-classifying' : 'prospector-badge-completed' %>">
+                  <%= kw.source %>
+                </span>
+              </td>
+              <td>
+                <%= button_to keyword_path(kw), method: :patch, class: "prospector-btn prospector-btn-outline prospector-btn-sm" do %>
+                  <%= kw.active? ? "Active" : "Disabled" %>
+                <% end %>
+              </td>
+              <td>
+                <%= button_to "Remove", keyword_path(kw), method: :delete, class: "prospector-btn prospector-btn-danger prospector-btn-sm" %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% end %>
+<% else %>
+  <div class="prospector-card" style="text-align: center; padding: 3rem;">
+    <p class="prospector-text-muted">No keywords yet. Add one manually or generate via AI.</p>
+  </div>
+<% end %>

data/app/views/prospector/layouts/prospector.html.erb

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Prospector</title>
+  <%= stylesheet_link_tag "prospector/application", media: "all" %>
+  <%= csrf_meta_tags %>
+</head>
+<body style="margin: 0;">
+  <div class="prospector-ui">
+    <nav class="prospector-nav">
+      <div class="prospector-nav-brand">
+        <%= link_to "Prospector", prospector.root_path, class: "prospector-nav-title" %>
+      </div>
+      <div class="prospector-nav-links">
+        <%= link_to "Runs", prospector.runs_path, class: "prospector-nav-link" %>
+        <%= link_to "Keywords", prospector.keywords_path, class: "prospector-nav-link" %>
+      </div>
+    </nav>
+    <main class="prospector-main">
+      <% if notice.present? %>
+        <div class="prospector-flash prospector-flash-notice"><%= notice %></div>
+      <% end %>
+      <% if alert.present? %>
+        <div class="prospector-flash prospector-flash-alert"><%= alert %></div>
+      <% end %>
+      <%= yield %>
+    </main>
+    <footer class="prospector-footer">
+      <div class="prospector-footer-inner">
+        <span>&copy; <%= Time.current.year %> Prospector</span>
+        <span>An <a href="https://axiumfoundry.com" target="_blank" rel="noopener noreferrer">Axium Foundry</a> product</span>
+      </div>
+    </footer>
+  </div>
+</body>
+</html>

data/app/views/prospector/runs/index.html.erb

@@ -0,0 +1,33 @@
+<div class="prospector-flex prospector-flex-between">
+  <h1 class="prospector-heading">Runs</h1>
+  <%= link_to "New Run", new_run_path, class: "prospector-btn prospector-btn-primary" %>
+</div>
+
+<div class="prospector-card">
+  <table class="prospector-table">
+    <thead>
+      <tr>
+        <th>Label</th>
+        <th>Source</th>
+        <th>Geography</th>
+        <th>Status</th>
+        <th>Found</th>
+        <th>Created</th>
+        <th></th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @runs.each do |run| %>
+        <tr>
+          <td><%= link_to run.label || "##{run.id}", run_path(run) %></td>
+          <td><%= run.source_adapter %></td>
+          <td><%= run.geography.label %></td>
+          <td><span class="prospector-badge prospector-badge-<%= run.status %>"><%= run.status.titleize %></span></td>
+          <td><%= run.total_found %></td>
+          <td class="prospector-text-muted prospector-text-sm"><%= run.created_at.strftime("%b %d, %Y %H:%M") %></td>
+          <td><%= link_to "View", run_path(run), class: "prospector-btn prospector-btn-outline prospector-btn-sm" %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/prospector/runs/new.html.erb

@@ -0,0 +1,109 @@
+<h1 class="prospector-heading">New Run</h1>
+
+<div class="prospector-card">
+  <%= form_with model: @run, url: runs_path, method: :post do |f| %>
+    <div class="prospector-form-group">
+      <%= f.label :label, "Label (optional)", class: "prospector-label" %>
+      <%= f.text_field :label, class: "prospector-input", placeholder: "e.g. Dallas motorcycle shops" %>
+    </div>
+
+    <div class="prospector-form-group">
+      <%= f.label :source_adapter, "Source", class: "prospector-label" %>
+      <%= f.select :source_adapter, Prospector.config.sources.keys.map { |k| [k.to_s.titleize, k] }, {}, class: "prospector-select" %>
+    </div>
+
+    <div class="prospector-form-group">
+      <%= f.label :geography_type, "Geography Type", class: "prospector-label" %>
+      <%= f.select :geography_type,
+          Prospector::Geography::Base::TYPES.map { |t| [t.titleize, t] },
+          {},
+          class: "prospector-select",
+          onchange: "document.querySelectorAll('[data-geo-fields]').forEach(el => el.style.display = el.dataset.geoFields === this.value ? '' : 'none')" %>
+    </div>
+
+    <fieldset data-geo-fields="metro_area" class="prospector-form-group">
+      <legend class="prospector-label">Metro Area</legend>
+      <div class="prospector-form-group" style="margin-bottom: 8px;">
+        <select class="prospector-select" onchange="
+          var opt = this.options[this.selectedIndex];
+          var nameField = this.closest('fieldset').querySelector('[name*=name]');
+          var stateField = this.closest('fieldset').querySelector('[name*=primary_state]');
+          nameField.value = opt.dataset.name || '';
+          stateField.value = opt.dataset.state || '';
+        ">
+          <option value="">Select a metro area or enter custom below</option>
+          <% Prospector::Geography::MetroArea::PRELOADED.each do |metro| %>
+            <option data-name="<%= metro[:name] %>" data-state="<%= metro[:primary_state] %>">
+              <%= metro[:name] %>, <%= metro[:primary_state] %>
+            </option>
+          <% end %>
+        </select>
+      </div>
+      <div class="prospector-flex prospector-gap-4">
+        <div class="prospector-form-group" style="flex: 2; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][name]", nil, class: "prospector-input", placeholder: "Metro area name, e.g. Dallas-Fort Worth" %>
+        </div>
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][primary_state]", nil, class: "prospector-input", placeholder: "State, e.g. TX" %>
+        </div>
+      </div>
+    </fieldset>
+
+    <fieldset data-geo-fields="city" class="prospector-form-group" style="display: none;">
+      <legend class="prospector-label">City</legend>
+      <div class="prospector-flex prospector-gap-4">
+        <div class="prospector-form-group" style="flex: 2; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][city]", nil, class: "prospector-input", placeholder: "City name, e.g. Austin" %>
+        </div>
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][state]", nil, class: "prospector-input", placeholder: "State, e.g. TX" %>
+        </div>
+      </div>
+    </fieldset>
+
+    <fieldset data-geo-fields="coordinates" class="prospector-form-group" style="display: none;">
+      <legend class="prospector-label">Coordinates</legend>
+      <div class="prospector-flex prospector-gap-4">
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][lat]", nil, class: "prospector-input", placeholder: "Latitude, e.g. 30.267" %>
+        </div>
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][lng]", nil, class: "prospector-input", placeholder: "Longitude, e.g. -97.743" %>
+        </div>
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][radius_meters]", "10000", class: "prospector-input", placeholder: "Radius (meters)" %>
+        </div>
+      </div>
+    </fieldset>
+
+    <fieldset data-geo-fields="zip_code" class="prospector-form-group" style="display: none;">
+      <legend class="prospector-label">ZIP Code</legend>
+      <div class="prospector-form-group" style="max-width: 200px; margin-bottom: 0;">
+        <%= text_field_tag "run[geography_data][zip]", nil, class: "prospector-input", placeholder: "e.g. 75201" %>
+      </div>
+    </fieldset>
+
+    <fieldset data-geo-fields="bounding_box" class="prospector-form-group" style="display: none;">
+      <legend class="prospector-label">Bounding Box</legend>
+      <div class="prospector-flex prospector-gap-4">
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][sw_lat]", nil, class: "prospector-input", placeholder: "SW Latitude" %>
+        </div>
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][sw_lng]", nil, class: "prospector-input", placeholder: "SW Longitude" %>
+        </div>
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][ne_lat]", nil, class: "prospector-input", placeholder: "NE Latitude" %>
+        </div>
+        <div class="prospector-form-group" style="flex: 1; margin-bottom: 0;">
+          <%= text_field_tag "run[geography_data][ne_lng]", nil, class: "prospector-input", placeholder: "NE Longitude" %>
+        </div>
+      </div>
+    </fieldset>
+
+    <div class="prospector-form-group">
+      <%= f.submit "Start Run", class: "prospector-btn prospector-btn-primary" %>
+      <%= link_to "Cancel", runs_path, class: "prospector-btn prospector-btn-outline" %>
+    </div>
+  <% end %>
+</div>