brave_search 0.1.0

data/example.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "lib/brave_search"
+
+# Basic usage
+puts "BraveSearch Ruby Gem Example"
+puts "=" * 40
+
+# Configure
+BraveSearch.configure do |config|
+  config.api_key = ENV["BRAVE_API_KEY"] || "your_api_key_here"
+  config.timeout = 30
+end
+
+begin
+  BraveSearch::Client.new
+  puts "Client initialized successfully!"
+
+  # NOTE: This will fail without a real API key
+  # results = client.search(q: "ruby programming", count: 5)
+  # puts "Found #{results[:web][:results].length} results"
+rescue BraveSearch::AuthenticationError => e
+  puts "Error: #{e.message}"
+  puts "Set BRAVE_API_KEY environment variable with your API key from https://brave.com/search/api/"
+rescue StandardError => e
+  puts "Error: #{e.message}"
+end
+
+puts "\nTo use with a real API key:"
+puts "export BRAVE_API_KEY=your_key_here"
+puts "ruby example.rb"

data/lib/brave_search/async_client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "async"
+
+module BraveSearch
+  class AsyncClient < Client
+    def search(q:, count: 10, **options)
+      Async do
+        super(q: q, count: count, **options)
+      end
+    end
+
+    def news_search(q:, count: 10, **options)
+      Async do
+        super(q: q, count: count, **options)
+      end
+    end
+
+    def video_search(q:, count: 10, **options)
+      Async do
+        super(q: q, count: count, **options)
+      end
+    end
+
+    def image_search(q:, count: 10, **options)
+      Async do
+        super(q: q, count: count, **options)
+      end
+    end
+
+    def concurrent_search(queries)
+      Async do
+        tasks = queries.map do |query_params|
+          Async do
+            if query_params.is_a?(String)
+              params = build_params(q: query_params)
+              response = make_request("/web/search", params)
+              data = handle_response(response)
+              BraveSearch::Results.new(data)
+            else
+              params = build_params(**query_params)
+              response = make_request("/web/search", params)
+              data = handle_response(response)
+              BraveSearch::Results.new(data)
+            end
+          end
+        end
+        tasks.map(&:wait)
+      end
+    end
+  end
+end

data/lib/brave_search/client.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+module BraveSearch
+  class Client
+    include HTTParty
+
+    def initialize(api_key: nil)
+      @api_key = api_key || BraveSearch.config.api_key
+      raise AuthenticationError, "API key is required" unless @api_key
+
+      self.class.base_uri BraveSearch.config.base_url
+      self.class.default_timeout BraveSearch.config.timeout
+    end
+
+    def search(q:, count: 10, **options)
+      params = build_params(q: q, count: count, **options)
+      response = make_request("/web/search", params)
+      data = handle_response(response)
+      Results.new(data)
+    end
+
+    def search_and_download_pdfs(q:, count: 10, storage: nil, folder: "pdfs", &progress_callback)
+      results = search(q: q, count: count)
+      results.download_pdfs(storage: storage, folder: folder, &progress_callback)
+    end
+
+    def search_and_export(q:, format:, storage: nil, key: nil, count: 10, **options)
+      results = search(q: q, count: count, **options)
+
+      if storage && key
+        results.export_to_storage(format: format, storage: storage, key: key)
+      else
+        results.export(format: format)
+      end
+    end
+
+    def search_and_export_async(q:, format:, storage_config: nil, key: nil, **options)
+      return unless defined?(ActiveJob)
+
+      Jobs::ExportJob.perform_later(
+        query: q,
+        format: format,
+        storage_config: storage_config,
+        key: key,
+        **options
+      )
+    end
+
+    def search_and_download_pdfs_async(q:, storage_config: nil, folder: "pdfs", **options)
+      return unless defined?(ActiveJob)
+
+      Jobs::PdfDownloadJob.perform_later(
+        query: q,
+        storage_config: storage_config,
+        folder: folder,
+        **options
+      )
+    end
+
+    def news_search(q:, count: 10, **options)
+      params = build_params(q: q, count: count, **options)
+      response = make_request("/news/search", params)
+      data = handle_response(response)
+      Results.new(data)
+    end
+
+    def video_search(q:, count: 10, **options)
+      params = build_params(q: q, count: count, **options)
+      response = make_request("/videos/search", params)
+      data = handle_response(response)
+      Results.new(data)
+    end
+
+    def image_search(q:, count: 10, **options)
+      params = build_params(q: q, count: count, **options)
+      response = make_request("/images/search", params)
+      data = handle_response(response)
+      Results.new(data)
+    end
+
+    def suggest(q:, **options)
+      params = build_params(q: q, **options)
+      response = make_request("/suggest/search", params)
+      handle_response(response)
+    end
+
+    def spellcheck(q:, **options)
+      params = build_params(q: q, **options)
+      response = make_request("/spellcheck", params)
+      handle_response(response)
+    end
+
+    def summarizer
+      @summarizer ||= Summarizer.new(self)
+    end
+
+    private
+
+    def build_params(q:, count: nil, **options)
+      params = { q: q }
+      params[:count] = count if count
+      params.merge(options)
+    end
+
+    def make_request(endpoint, params, method: :get)
+      headers = {
+        "X-Subscription-Token" => @api_key,
+        "Accept" => "application/json"
+      }
+
+      case method
+      when :get
+        self.class.get(endpoint, { query: params, headers: headers })
+      when :post
+        headers["Content-Type"] = "application/json"
+        self.class.post(endpoint, { body: params.to_json, headers: headers })
+      else
+        raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200
+        JSON.parse(response.body, symbolize_names: true)
+      when 401
+        raise AuthenticationError, "Invalid API key"
+      when 429
+        raise RateLimitError, "Rate limit exceeded"
+      when 402
+        raise QuotaExceededError, "Quota exceeded"
+      else
+        raise Error, "HTTP #{response.code}: #{response.message}"
+      end
+    end
+  end
+end

data/lib/brave_search/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BraveSearch
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :retry_attempts, :storage_provider, :storage_bucket, :storage_endpoint
+
+    def initialize
+      @api_key = ENV.fetch("BRAVE_API_KEY", nil)
+      @base_url = "https://api.search.brave.com/res/v1"
+      @timeout = 30
+      @retry_attempts = 3
+      @storage_provider = :aws
+      @storage_bucket = ENV.fetch("BRAVE_SEARCH_BUCKET", "brave-search-downloads")
+      @storage_endpoint = nil
+    end
+
+    def storage(**options)
+      Storage.for(storage_provider, bucket: storage_bucket, endpoint: storage_endpoint, **options)
+    end
+  end
+end

data/lib/brave_search/exporter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BraveSearch
+  class Exporter
+    def self.for(format)
+      case format
+      when :json
+        require_relative "exporters/json"
+        Exporters::Json.new
+      when :csv
+        require_relative "exporters/csv"
+        Exporters::Csv.new
+      when :xlsx
+        require_relative "exporters/xlsx"
+        Exporters::Xlsx.new
+      else
+        raise ArgumentError, "Unknown export format: #{format}"
+      end
+    end
+
+    def export(results)
+      raise NotImplementedError, "Subclasses must implement #export"
+    end
+
+    def export_to_storage(results, storage:, key:)
+      export_result = export(results)
+      upload_result = storage.upload(export_result[:content], key: key)
+
+      {
+        key: key,
+        url: upload_result[:url],
+        size: export_result[:size],
+        format: format_name
+      }
+    end
+
+    private
+
+    def format_name
+      self.class.name.split("::").last.downcase
+    end
+  end
+end

data/lib/brave_search/exporters/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BraveSearch
+  module Exporters
+    class Base < BraveSearch::Exporter
+      private
+
+      def validate_results(results)
+        raise ArgumentError, "Results cannot be nil" if results.nil?
+        raise ArgumentError, "Results must respond to web_results" unless results.respond_to?(:web_results)
+      end
+
+      def build_metadata(results)
+        {
+          exported_at: Time.now.iso8601,
+          query: results.query,
+          total_results: results.count,
+          format: format_name
+        }
+      end
+    end
+  end
+end

data/lib/brave_search/exporters/csv.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "csv"
+require_relative "base"
+
+module BraveSearch
+  module Exporters
+    class Csv < Base
+      def export(results)
+        validate_results(results)
+        content = generate_csv(results)
+
+        {
+          content: content,
+          size: content.bytesize
+        }
+      end
+
+      private
+
+      def generate_csv(results)
+        CSV.generate do |csv|
+          csv << %w[title url description]
+
+          results.web_results.each do |result|
+            csv << [result[:title], result[:url], result[:description]]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brave_search/exporters/json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module BraveSearch
+  module Exporters
+    class Json < Base
+      def export(results)
+        validate_results(results)
+
+        export_data = results.to_h.merge(
+          metadata: build_metadata(results)
+        )
+
+        content = JSON.pretty_generate(export_data)
+
+        {
+          content: content,
+          size: content.bytesize
+        }
+      end
+    end
+  end
+end

data/lib/brave_search/exporters/xlsx.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "caxlsx"
+require_relative "base"
+
+module BraveSearch
+  module Exporters
+    class Xlsx < Base
+      def export(results)
+        validate_results(results)
+        content = generate_xlsx(results)
+
+        {
+          content: content,
+          size: content.bytesize
+        }
+      end
+
+      private
+
+      def generate_xlsx(results)
+        package = Axlsx::Package.new
+        workbook = package.workbook
+
+        workbook.add_worksheet(name: "Search Results") do |sheet|
+          sheet.add_row %w[Title URL Description]
+
+          results.web_results.each do |result|
+            sheet.add_row [result[:title], result[:url], result[:description]]
+          end
+        end
+
+        add_metadata_sheet(workbook, results)
+        package.to_stream.read
+      end
+
+      def add_metadata_sheet(workbook, results)
+        workbook.add_worksheet(name: "Metadata") do |sheet|
+          metadata = build_metadata(results)
+
+          sheet.add_row %w[Property Value]
+          metadata.each { |key, value| sheet.add_row [key.to_s.tr("_", " ").capitalize, value] }
+        end
+      end
+    end
+  end
+end

data/lib/brave_search/jobs/export_job.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BraveSearch
+  module Jobs
+    class ExportJob < ActiveJob::Base
+      queue_as :brave_search
+
+      def perform(query:, format:, storage_config: nil, key: nil, **search_options)
+        client = BraveSearch::Client.new
+
+        if storage_config && key
+          storage = build_storage(storage_config)
+          result = client.search_and_export(
+            q: query,
+            format: format.to_sym,
+            storage: storage,
+            key: key,
+            **search_options
+          )
+
+          Rails.logger.info "Export completed: #{result[:url]}"
+        else
+          result = client.search_and_export(q: query, format: format.to_sym, **search_options)
+          Rails.logger.info "Export completed locally: #{result[:size]} bytes"
+        end
+
+        result
+      end
+
+      private
+
+      def build_storage(config)
+        BraveSearch::Storage.for(
+          config[:provider],
+          **config[:options]
+        )
+      end
+    end
+  end
+end

data/lib/brave_search/jobs/pdf_download_job.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BraveSearch
+  module Jobs
+    class PdfDownloadJob < ActiveJob::Base
+      queue_as :brave_search
+
+      def perform(query:, storage_config: nil, folder: "pdfs", **search_options)
+        client = BraveSearch::Client.new
+        storage = storage_config ? build_storage(storage_config) : nil
+
+        progress_callback = lambda do |current, total, url|
+          Rails.logger.info "Downloading PDFs: #{current}/#{total} - #{url}"
+        end
+
+        result = client.search_and_download_pdfs(
+          q: query,
+          storage: storage,
+          folder: folder,
+          **search_options,
+          &progress_callback
+        )
+
+        Rails.logger.info "PDF download completed: #{result[:files].size} files"
+        result
+      end
+
+      private
+
+      def build_storage(config)
+        BraveSearch::Storage.for(
+          config[:provider],
+          **config[:options]
+        )
+      end
+    end
+  end
+end

data/lib/brave_search/pdf_downloader.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+
+module BraveSearch
+  class PdfDownloader
+    def initialize(storage: nil)
+      @storage = storage || default_storage
+    end
+
+    def download(url, folder: "pdfs")
+      filename = extract_filename(url)
+      key = "#{folder}/#{filename}"
+
+      @storage.download(url, key: key)
+    end
+
+    def batch_download(urls, folder: "pdfs", &progress_callback)
+      total = urls.length
+      completed = Concurrent::AtomicFixnum.new(0)
+
+      futures = urls.map do |url|
+        Concurrent::Future.execute do
+          result = download(url, folder: folder)
+          current = completed.increment
+          progress_callback&.call(current, total)
+          result
+        end
+      end
+
+      futures.map(&:value)
+    end
+
+    private
+
+    def default_storage
+      Storage.for(:aws, bucket: ENV.fetch("BRAVE_SEARCH_BUCKET", "brave-search-downloads"))
+    end
+
+    def extract_filename(url)
+      uri = URI(url)
+      filename = File.basename(uri.path)
+      filename.empty? ? "document.pdf" : filename
+    end
+  end
+end

data/lib/brave_search/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BraveSearch
+  class Railtie < Rails::Railtie
+    initializer "brave_search.configure" do |app|
+      app.config.to_prepare do
+        if Rails.application.credentials.brave_api_key
+          BraveSearch.configure do |config|
+            config.api_key = Rails.application.credentials.brave_api_key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brave_search/results.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module BraveSearch
+  class Results
+    attr_reader :raw_data, :query
+
+    def initialize(data)
+      @raw_data = data
+      @query = data[:query]
+    end
+
+    def web_results
+      @raw_data.dig(:web, :results) || []
+    end
+
+    def news_results
+      @raw_data.dig(:news, :results) || []
+    end
+
+    def video_results
+      @raw_data.dig(:videos, :results) || []
+    end
+
+    def image_results
+      @raw_data.dig(:images, :results) || []
+    end
+
+    def locations
+      @raw_data.dig(:mixed, :locations) || []
+    end
+
+    def infobox
+      @raw_data.dig(:mixed, :infobox)
+    end
+
+    def spell
+      @raw_data[:spell]
+    end
+
+    def empty?
+      web_results.empty? && news_results.empty? && video_results.empty? && image_results.empty?
+    end
+
+    def count
+      web_results.length + news_results.length + video_results.length + image_results.length
+    end
+
+    # Support pattern matching (Ruby 3+)
+    def deconstruct_keys(keys)
+      @raw_data.slice(*keys) if keys
+      @raw_data
+    end
+
+    # Convert to hash for easy access
+    def to_h
+      @raw_data
+    end
+
+    def [](key)
+      @raw_data[key]
+    end
+
+    def pdf_urls
+      web_results.filter_map { |result| result[:url] if result[:url]&.end_with?(".pdf") }
+    end
+
+    def download_pdfs(storage: nil, folder: "pdfs", &progress_callback)
+      downloader = PdfDownloader.new(storage: storage)
+      downloader.batch_download(pdf_urls, folder: folder, &progress_callback)
+    end
+
+    def export(format:)
+      exporter = Exporter.for(format)
+      exporter.export(self)
+    end
+
+    def export_to_storage(format:, storage:, key:)
+      exporter = Exporter.for(format)
+      exporter.export_to_storage(self, storage: storage, key: key)
+    end
+
+    def summarize_with(client)
+      client.summarizer.search_and_summarize(q: @query || "search results")
+    end
+
+    def all_text_content
+      content = []
+      content += web_results.flat_map { |r| [r[:title], r[:description]].compact }
+      content += news_results.flat_map { |r| [r[:title], r[:description]].compact }
+      content.join(" ")
+    end
+  end
+end