brave_search 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c976d8ab5da9bc80fd7d218034420f86f57088716d8dca2d482e1e27e6e48d4e
+  data.tar.gz: fec4b6454ea240e5e65a5489f8e3a1f04ac046ad174c648ef2766e5015704496
+SHA512:
+  metadata.gz: 42b474a7ebec418ae7ff28e91e157aa91471c450e5ed07e75bf82449106754ef9dfa4241133387c912fceee9b433f5231dd018bdaea9ae1e4e7b959dc9c949c3
+  data.tar.gz: 9b326af2244876c3cfa68ece7db49334b945e33bd5b0bb58f719c7b2a596be08fdfffdb92fbf254a2942af61584ee7601296f4c94354d23a93bbe4ff244123bc

data/.rubocop.yml

@@ -0,0 +1,27 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'dummy_app/**/*'
+    - 'vendor/**/*'
+    - 'bin/**/*'
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true

data/README.md

@@ -0,0 +1,179 @@
+# BraveSearch Ruby Gem
+
+Ruby client for the Brave Search API with Rails 8 integration, Ruby 3+ pattern matching, and async support.
+
+## Features
+
+- 🔍 **Multiple Search Types**: Web, news, video, image, suggest, and spellcheck
+- ⚡ **Async Support**: Concurrent searches using Ruby 3+ Fiber.schedule
+- 🎯 **Pattern Matching**: Ruby 3+ pattern matching support for results
+- 🚆 **Rails 8 Integration**: Automatic configuration with Rails credentials
+- 🧪 **Comprehensive Testing**: RSpec tests with WebMock
+- 💎 **Modern Ruby**: Requires Ruby 3.0+ for modern features
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'brave_search'
+```
+
+And then execute:
+
+    $ bundle install
+
+## Usage
+
+### Basic Usage
+
+```ruby
+client = BraveSearch::Client.new(api_key: 'your_api_key')
+results = client.search(q: 'ruby programming', count: 10)
+
+# Results wrapper with convenience methods
+puts results.web_results.first[:title]  
+puts "Found #{results.count} total results"
+```
+
+### Multiple Search Types
+
+```ruby
+# Different search types
+web_results = client.search(q: 'ruby programming')
+news_results = client.news_search(q: 'ruby news')  
+video_results = client.video_search(q: 'ruby tutorials')
+image_results = client.image_search(q: 'ruby logo')
+
+# Suggestions and spellcheck
+suggestions = client.suggest(q: 'ruby prog')
+spelling = client.spellcheck(q: 'rubyy')
+```
+
+### Ruby 3+ Pattern Matching
+
+```ruby
+results = client.search(q: 'ruby programming')
+
+case results
+in { web: { results: [first, *rest] }, query: { original: String => query } }
+  puts "Found #{rest.length + 1} results for: '#{query}'"
+  puts "Top result: #{first[:title]}"
+in { web: { results: [] } }
+  puts "No results found"
+else
+  puts "Unexpected response"
+end
+```
+
+### Async Support
+
+```ruby
+require 'async'
+
+async_client = BraveSearch::AsyncClient.new
+
+# Single async search
+Async do
+  result = async_client.search(q: 'ruby programming').wait
+  puts result.web_results.first[:title]
+end
+
+# Concurrent searches
+Async do
+  results = async_client.concurrent_search([
+    'ruby programming',
+    'rails framework',
+    'async ruby'
+  ]).wait
+  
+  results.each { |r| puts "Found #{r.count} results" }
+end
+```
+
+### S3-Compatible Storage & PDF Downloads
+
+```ruby
+# Configure storage
+BraveSearch.configure do |config|
+  config.storage_provider = :hetzner
+  config.storage_bucket = "research-papers"
+  config.storage_endpoint = "https://fsn1.your-objectstorage.com"
+end
+
+# Search and download PDFs automatically
+client = BraveSearch::Client.new
+downloaded = client.search_and_download_pdfs(
+  q: "machine learning papers filetype:pdf",
+  count: 5,
+  folder: "ml-papers/#{Date.today}"
+) do |completed, total|
+  puts "Downloaded #{completed}/#{total} PDFs"
+end
+
+# Manual PDF extraction and download
+results = client.search(q: "research papers filetype:pdf")
+pdf_urls = results.pdf_urls
+puts "Found #{pdf_urls.length} PDFs"
+
+# Download to specific storage
+storage = BraveSearch::Storage.for(:digitalocean, 
+  bucket: "documents", 
+  endpoint: "https://nyc3.digitaloceanspaces.com"
+)
+
+results.download_pdfs(storage: storage, folder: "research") do |completed, total|
+  puts "Progress: #{completed}/#{total}"
+end
+```
+
+### Supported Storage Providers
+
+- **AWS S3**: `:aws`
+- **Hetzner Object Storage**: `:hetzner`
+- **DigitalOcean Spaces**: `:digitalocean`
+- **Any S3-compatible**: `:s3`
+
+### Rails Integration
+
+1. Install the initializer:
+
+```bash
+rails generate brave_search:install
+```
+
+2. Add your API key to Rails credentials:
+
+```bash
+rails credentials:edit
+```
+
+Add:
+```yaml
+brave_api_key: your_api_key_here
+```
+
+3. Use in your Rails app:
+
+```ruby
+client = BraveSearch::Client.new
+results = client.search(q: 'ruby on rails')
+```
+
+## Configuration
+
+```ruby
+BraveSearch.configure do |config|
+  config.api_key = 'your_api_key'
+  config.timeout = 30
+  config.retry_attempts = 3
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/brave_search.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/brave_search/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "brave_search"
+  spec.version = BraveSearch::VERSION
+  spec.authors = ["Remi AI"]
+  spec.email = ["denis@goremi.co.uk"]
+
+  spec.summary = "Ruby client for Brave Search API"
+  spec.description = "Simple Ruby client for Brave Search API with Rails integration"
+  spec.homepage = "https://github.com/Remi-org/brave-search-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z 2>/dev/null`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "async", "~> 2.0"
+  spec.add_dependency "caxlsx", "~> 4.0"
+  spec.add_dependency "concurrent-ruby", "~> 1.2"
+  spec.add_dependency "httparty", "~> 0.21"
+
+  spec.add_development_dependency "rails", "~> 8.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
+  spec.add_development_dependency "webmock", "~> 3.18"
+end

data/dummy_app/.dockerignore

@@ -0,0 +1,45 @@
+# See https://docs.docker.com/engine/reference/builder/#dockerignore-file for more about ignoring files.
+
+# Ignore git directory.
+/.git/
+/.gitignore
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all environment files.
+/.env*
+
+# Ignore all default key files.
+/config/master.key
+/config/credentials/*.key
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/.keep
+
+# Ignore storage (uploaded files in development and any SQLite databases).
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/.keep
+
+# Ignore CI service files.
+/.github
+
+# Ignore Kamal files.
+/config/deploy*.yml
+/.kamal
+
+# Ignore development files
+/.devcontainer
+
+# Ignore Docker-related files
+/.dockerignore
+/Dockerfile*

data/dummy_app/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10

data/dummy_app/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  scan_ruby:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+
+      - name: Scan for common Rails security vulnerabilities using static analysis
+        run: bin/brakeman --no-pager
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+
+      - name: Lint code for consistent style
+        run: bin/rubocop -f github
+
+  test:
+    runs-on: ubuntu-latest
+
+    # services:
+    #  redis:
+    #    image: redis
+    #    ports:
+    #      - 6379:6379
+    #    options: --health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5
+    steps:
+      - name: Install packages
+        run: sudo apt-get update && sudo apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+
+      - name: Run tests
+        env:
+          RAILS_ENV: test
+          # REDIS_URL: redis://localhost:6379/0
+        run: bin/rails db:test:prepare test

data/dummy_app/.rubocop.yml

@@ -0,0 +1,8 @@
+# Omakase Ruby styling for Rails
+inherit_gem: { rubocop-rails-omakase: rubocop.yml }
+
+# Overwrite or add rules to create your own house style
+#
+# # Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
+# Layout/SpaceInsideArrayLiteralBrackets:
+#   Enabled: false

data/dummy_app/Dockerfile

@@ -0,0 +1,69 @@
+# syntax=docker/dockerfile:1
+# check=error=true
+
+# This Dockerfile is designed for production, not development. Use with Kamal or build'n'run by hand:
+# docker build -t dummy_app .
+# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name dummy_app dummy_app
+
+# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html
+
+# Make sure RUBY_VERSION matches the Ruby version in .ruby-version
+ARG RUBY_VERSION=3.4.1
+FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
+
+# Rails app lives here
+WORKDIR /rails
+
+# Install base packages
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y curl libjemalloc2 libvips sqlite3 && \
+    rm -rf /var/lib/apt/lists /var/cache/apt/archives
+
+# Set production environment
+ENV RAILS_ENV="production" \
+    BUNDLE_DEPLOYMENT="1" \
+    BUNDLE_PATH="/usr/local/bundle" \
+    BUNDLE_WITHOUT="development"
+
+# Throw-away build stage to reduce size of final image
+FROM base AS build
+
+# Install packages needed to build gems
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config && \
+    rm -rf /var/lib/apt/lists /var/cache/apt/archives
+
+# Install application gems
+COPY Gemfile Gemfile.lock ./
+RUN bundle install && \
+    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \
+    bundle exec bootsnap precompile --gemfile
+
+# Copy application code
+COPY . .
+
+# Precompile bootsnap code for faster boot times
+RUN bundle exec bootsnap precompile app/ lib/
+
+
+
+
+# Final stage for app image
+FROM base
+
+# Copy built artifacts: gems, application
+COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
+COPY --from=build /rails /rails
+
+# Run and own only the runtime files as a non-root user for security
+RUN groupadd --system --gid 1000 rails && \
+    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
+    chown -R rails:rails db log storage tmp
+USER 1000:1000
+
+# Entrypoint prepares the database.
+ENTRYPOINT ["/rails/bin/docker-entrypoint"]
+
+# Start server via Thruster by default, this can be overwritten at runtime
+EXPOSE 80
+CMD ["./bin/thrust", "./bin/rails", "server"]

data/dummy_app/Gemfile

@@ -0,0 +1,48 @@
+source "https://rubygems.org"
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem "rails", "~> 8.0.2"
+gem "brave_search", path: "../"
+# Use sqlite3 as the database for Active Record
+gem "sqlite3", ">= 2.1"
+# Use the Puma web server [https://github.com/puma/puma]
+gem "puma", ">= 5.0"
+# Build JSON APIs with ease [https://github.com/rails/jbuilder]
+# gem "jbuilder"
+
+# Use Active Model has_secure_password [https://guides.rubyonrails.org/active_model_basics.html#securepassword]
+# gem "bcrypt", "~> 3.1.7"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: %i[ windows jruby ]
+
+# Use the database-backed adapters for Rails.cache, Active Job, and Action Cable
+gem "solid_cache"
+gem "solid_queue"
+gem "solid_cable"
+
+# Reduces boot times through caching; required in config/boot.rb
+gem "bootsnap", require: false
+
+# Deploy this application anywhere as a Docker container [https://kamal-deploy.org]
+gem "kamal", require: false
+
+# Add HTTP asset caching/compression and X-Sendfile acceleration to Puma [https://github.com/basecamp/thruster/]
+gem "thruster", require: false
+
+# Use Active Storage variants [https://guides.rubyonrails.org/active_storage_overview.html#transforming-images]
+# gem "image_processing", "~> 1.2"
+
+# Use Rack CORS for handling Cross-Origin Resource Sharing (CORS), making cross-origin Ajax possible
+# gem "rack-cors"
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem "debug", platforms: %i[ mri windows ], require: "debug/prelude"
+
+  # Static analysis for security vulnerabilities [https://brakemanscanner.org/]
+  gem "brakeman", require: false
+
+  # Omakase Ruby styling [https://github.com/rails/rubocop-rails-omakase/]
+  gem "rubocop-rails-omakase", require: false
+end

data/dummy_app/README.md

@@ -0,0 +1,24 @@
+# README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...

data/dummy_app/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/dummy_app/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::API
+end

data/dummy_app/app/controllers/searches_controller.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+class SearchesController < ApplicationController
+  def show
+    query = params[:q] || "ruby programming papers filetype:pdf"
+    @client = BraveSearch::Client.new
+    @results = @client.search(q: query, count: 5)
+    
+    render json: {
+      query: query,
+      web_results: @results.web_results.length,
+      pdf_urls: extract_pdf_urls(@results)
+    }
+  end
+
+  def download_pdfs
+    query = params[:q] || "ruby programming papers filetype:pdf"
+    
+    client = BraveSearch::Client.new
+    storage = BraveSearch::Storage.for(:hetzner, 
+      bucket: "research-papers",
+      endpoint: "https://fsn1.your-objectstorage.com"
+    )
+
+    downloaded = client.search_and_download_pdfs(
+      q: query, 
+      count: 3, 
+      storage: storage,
+      folder: "papers/#{Date.today}"
+    ) do |completed, total|
+      puts "Downloaded #{completed}/#{total} PDFs"
+    end
+
+    render json: {
+      query: query,
+      downloaded: downloaded.length,
+      files: downloaded.map { |d| d[:key] }
+    }
+  rescue StandardError => e
+    render json: { error: e.message }, status: 422
+  end
+
+  def export
+    query = params[:q] || "ruby programming"
+    format = params[:format] || "json"
+    
+    client = BraveSearch::Client.new
+    
+    if params[:async]
+      storage_config = {
+        provider: :hetzner,
+        options: {
+          bucket: "research-exports", 
+          endpoint: "https://fsn1.your-objectstorage.com"
+        }
+      }
+      
+      key = "exports/#{Date.today}/#{SecureRandom.hex(8)}.#{format}"
+      job = client.search_and_export_async(
+        q: query,
+        format: format,
+        storage_config: storage_config,
+        key: key
+      )
+      
+      render json: { job_id: job.job_id, key: key }
+    else
+      result = client.search_and_export(q: query, format: format.to_sym)
+      
+      respond_to do |format_type|
+        format_type.json { render json: result[:content] }
+        format_type.any { send_data result[:content], filename: "search_results.#{format}" }
+      end
+    end
+  rescue StandardError => e
+    render json: { error: e.message }, status: 422
+  end
+
+  def summarize
+    query = params[:q] || "AI research trends 2024"
+    
+    client = BraveSearch::Client.new
+    
+    if params[:key]
+      # Summarize existing search results
+      summary = client.summarizer.summarize(key: params[:key])
+      render json: {
+        type: "summary",
+        summary: summary.summary,
+        status: summary.status
+      }
+    else
+      # Search and summarize in one step
+      result = client.summarizer.search_and_summarize(q: query)
+      
+      render json: {
+        type: "search_and_summarize",
+        query: query,
+        summary: result.summary,
+        key: result.key,
+        status: result.status,
+        enriched_results: result.enriched_results.map(&:to_h)
+      }
+    end
+  rescue StandardError => e
+    render json: { error: e.message }, status: 422
+  end
+
+  private
+
+  def extract_pdf_urls(results)
+    results.web_results
+           .select { |r| r[:url]&.end_with?(".pdf") }
+           .map { |r| r[:url] }
+           .first(3)
+  end
+end

data/dummy_app/app/jobs/application_job.rb

@@ -0,0 +1,7 @@
+class ApplicationJob < ActiveJob::Base
+  # Automatically retry jobs that encountered a deadlock
+  # retry_on ActiveRecord::Deadlocked
+
+  # Most jobs are safe to ignore if the underlying records are no longer available
+  # discard_on ActiveJob::DeserializationError
+end

data/dummy_app/app/mailers/application_mailer.rb

@@ -0,0 +1,4 @@
+class ApplicationMailer < ActionMailer::Base
+  default from: "from@example.com"
+  layout "mailer"
+end

data/dummy_app/app/models/application_record.rb

@@ -0,0 +1,3 @@
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+end