exa-rb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba7c3d6444e98f398c76d223c995409c7b835df4c42c543c0ce67b7e1b059137
+  data.tar.gz: c5480dc30c83a9d4510261dbfbbd8d3b5fbd28be6adaf4a109b8a289b7f37799
+SHA512:
+  metadata.gz: f8742c3096bac80fbd171db29c67c5ac2fc40bd181f27fcc6de5135e7e1a8cca005b63f26f96c799130a75fc01421b8d2026adc81c932a10ef8bfe2a2a33f9c8
+  data.tar.gz: 9a48a2842a556c4407cb826e5748eff67b8d4dc83c8657d40a7c9bbd094e3e87edfa67550988c2931117da2d68e6fd20a2f364fbf4a5c627b2a3d587cc558e48

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Endless International
+
+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,286 @@
+# Exa
+
+The **Exa** gem provides a Ruby interface to the [Exa API](https://exa.ai), enabling powerful neural and keyword-based web search with content retrieval capabilities. Exa goes beyond traditional keyword matching to understand semantic meaning and context, making it particularly useful for applications that need intelligent search, including those using Large Language Models.
+
+```ruby
+require 'exa'
+
+Exa.api_key ENV[ 'EXA_API_KEY' ]
+
+response = Exa.search( 'best practices for Ruby API design' )
+if response.success?
+  response.result.results.each do | result |
+    puts result.title
+    puts result.url
+  end
+end
+```
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Command Line](#command-line)
+- [Quick Start](#quick-start)
+- [Endpoints](#endpoints)
+  - [Search](#search)
+  - [Find Similar](#find-similar)
+  - [Answer](#answer)
+  - [Contents](#contents)
+- [Responses and Errors](#responses-and-errors)
+- [Connections](#connections)
+- [License](#license)
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'exa-rb'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install exa-rb
+```
+
+## Command Line
+
+The gem includes an `exa` command for quick searches from the terminal:
+
+```bash
+exa search "Ruby programming best practices"
+exa answer "What is the Ruby programming language?"
+exa similar https://www.ruby-lang.org/en/
+```
+
+Set your API key via environment variable:
+
+```bash
+export EXA_API_KEY=your_api_key
+```
+
+## Quick Start
+
+The simplest way to use the gem is through the module-level convenience methods. Set your API key once, then call any endpoint:
+
+```ruby
+require 'exa'
+
+Exa.api_key ENV[ 'EXA_API_KEY' ]
+
+response = Exa.search( 'machine learning tutorials' )
+if response.success?
+  response.result.results.each do | result |
+    puts result.title
+    puts result.url
+  end
+end
+```
+
+For more control, instantiate request objects directly. This allows you to configure options using a block-based DSL and reuse request instances:
+
+```ruby
+request = Exa::SearchRequest.new( api_key: ENV[ 'EXA_API_KEY' ] )
+
+options = Exa::SearchOptions.build do
+  num_results 10
+  type :neural
+  contents do
+    text { max_characters 1000 }
+    highlights { num_sentences 2 }
+  end
+end
+
+response = request.submit( 'Ruby web frameworks', options )
+```
+
+---
+
+## Endpoints
+
+### Search
+
+The search endpoint performs web searches using neural or keyword-based methods and returns relevant results with optional content retrieval.
+
+```ruby
+options = Exa::SearchOptions.build do
+  num_results 5
+  type :neural
+  include_domains [ 'github.com', 'stackoverflow.com' ]
+  contents do
+    summary { query 'Summarize the key points' }
+  end
+end
+
+response = Exa.search( 'Ruby dependency injection patterns', options )
+
+if response.success?
+  response.result.results.each do | result |
+    puts result.title
+    puts result.url
+    puts result.summary
+  end
+end
+```
+
+For complete documentation of all search options and response fields, see [Search Documentation](readme/search.md).
+
+### Find Similar
+
+The find similar endpoint finds pages that are similar to a given URL:
+
+```ruby
+options = Exa::FindSimilarOptions.build do
+  num_results 5
+  exclude_source_domain true
+  contents do
+    summary { query 'Summarize the content' }
+  end
+end
+
+response = Exa.find_similar( 'https://www.ruby-lang.org/en/', options )
+
+if response.success?
+  response.result.results.each do | result |
+    puts result.title
+    puts result.url
+    puts result.summary
+  end
+end
+```
+
+For complete documentation of all find similar options and response fields, see [Find Similar Documentation](readme/find_similar.md).
+
+### Answer
+
+The answer endpoint provides AI-generated answers to questions using web sources:
+
+```ruby
+response = Exa.answer( 'What is the Ruby programming language?' )
+
+if response.success?
+  puts response.result.answer
+
+  puts "\nCitations:"
+  response.result.citations.each do | citation |
+    puts "- #{ citation.title }: #{ citation.url }"
+  end
+end
+```
+
+To include full text from citations:
+
+```ruby
+options = Exa::AnswerOptions.build do
+  text true
+end
+
+response = Exa.answer( 'How does garbage collection work in Ruby?', options )
+```
+
+For complete documentation of all answer options and response fields, see [Answer Documentation](readme/answer.md).
+
+### Contents
+
+The contents endpoint retrieves full page content, summaries, and highlights for a list of URLs:
+
+```ruby
+urls = [
+  'https://ruby-doc.org/core/Array.html',
+  'https://ruby-doc.org/core/Hash.html'
+]
+
+options = Exa::ContentsOptions.build do
+  text { max_characters 2000 }
+  highlights do
+    num_sentences 3
+    highlights_per_url 5
+  end
+end
+
+response = Exa.contents( urls, options )
+
+if response.success?
+  response.result.results.each do | result |
+    puts result.title
+    puts result.text
+  end
+end
+```
+
+For complete documentation of all contents options and response fields, see [Contents Documentation](readme/contents.md).
+
+---
+
+## Responses and Errors
+
+All request methods return a `Faraday::Response` object. Check `response.success?` to determine if the HTTP request succeeded. When successful, `response.result` contains the parsed result object specific to the endpoint.
+
+```ruby
+response = Exa.search( query, options )
+
+if response.success?
+  result = response.result
+  result.results.each do | item |
+    puts item.title
+  end
+else
+  error = response.result
+  puts error.error_type         # :authentication_error, :rate_limit_error, etc.
+  puts error.error_description  # human-readable message
+end
+```
+
+The gem maps HTTP status codes to error types:
+
+| Status | Error Type | Description |
+|--------|------------|-------------|
+| 400 | `:invalid_request_error` | Invalid request parameters or malformed JSON |
+| 401 | `:authentication_error` | Missing or invalid API key |
+| 403 | `:forbidden_error` | Insufficient permissions or rate limit exceeded |
+| 404 | `:not_found_error` | The requested resource was not found |
+| 409 | `:conflict_error` | Resource already exists |
+| 429 | `:rate_limit_error` | Rate limit exceeded |
+| 500-599 | `:server_error` | A server error occurred |
+
+---
+
+## Connections
+
+The gem uses Faraday for HTTP requests, which means you can customize the connection configuration. To use a custom connection:
+
+```ruby
+connection = Faraday.new do | faraday |
+  faraday.request :json
+  faraday.response :logger
+  faraday.adapter :net_http
+end
+
+Exa.connection connection
+```
+
+Or pass it directly to a request:
+
+```ruby
+request = Exa::SearchRequest.new(
+  api_key: ENV[ 'EXA_API_KEY' ],
+  connection: connection
+)
+```
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/exa

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+
+require 'exa'
+
+COMMANDS = %w[ search answer similar help ]
+
+def usage
+  puts "Usage: exa <command> [arguments]"
+  puts
+  puts "Commands:"
+  puts "  search <query>    Search the web and show results with summaries"
+  puts "  answer <question> Get an AI-generated answer with citations"
+  puts "  similar <url>     Find pages similar to a URL"
+  puts "  help              Show this help message"
+  puts
+  puts "Environment:"
+  puts "  EXA_API_KEY       Your Exa API key (required)"
+  puts
+  puts "Options:"
+  puts "  -n, --num <n>     Number of results (default: 5)"
+  puts
+  puts "Examples:"
+  puts "  exa search \"Ruby programming best practices\""
+  puts "  exa answer \"What is the Ruby programming language?\""
+  puts "  exa similar https://www.ruby-lang.org/en/"
+  puts "  exa search -n 10 \"machine learning tutorials\""
+end
+
+def check_api_key!
+  unless ENV[ 'EXA_API_KEY' ]
+    $stderr.puts "Error: An EXA_API_KEY environment variable is required."
+    exit 1
+  end
+  Exa.api_key ENV[ 'EXA_API_KEY' ]
+end
+
+def parse_options( args )
+  options = { num_results: 5 }
+
+  while args.first&.start_with?( '-' )
+    case args.shift
+    when '-n', '--num'
+      options[ :num_results ] = args.shift.to_i
+    end
+  end
+
+  options
+end
+
+def cmd_search( args )
+  options = parse_options( args )
+  query = args.join( ' ' )
+
+  if query.empty?
+    $stderr.puts "Error: search query required"
+    $stderr.puts "Usage: exa search <query>"
+    exit 1
+  end
+
+  check_api_key!
+
+  search_options = Exa::SearchOptions.build do
+    num_results options[ :num_results ]
+    contents do
+      summary { query 'Summarize in a single paragraph' }
+    end
+  end
+
+  response = Exa.search( query, search_options )
+
+  unless response.success?
+    $stderr.puts "Error: #{ response.result.error_description }"
+    exit 1
+  end
+
+  response.result.results.each_with_index do | result, index |
+    puts if index > 0
+    puts result.title
+    puts result.url
+    puts result.summary if result.summary
+  end
+end
+
+def cmd_answer( args )
+  options = parse_options( args )
+  question = args.join( ' ' )
+
+  if question.empty?
+    $stderr.puts "Error: question required"
+    $stderr.puts "Usage: exa answer <question>"
+    exit 1
+  end
+
+  check_api_key!
+
+  response = Exa.answer( question )
+
+  unless response.success?
+    $stderr.puts "Error: #{ response.result.error_description }"
+    exit 1
+  end
+
+  result = response.result
+  puts result.answer
+  puts
+  puts "Sources:"
+  result.citations.each do | citation |
+    puts "  #{ citation.title }"
+    puts "  #{ citation.url }"
+  end
+end
+
+def cmd_similar( args )
+  options = parse_options( args )
+  url = args.first
+
+  if url.nil? || url.empty?
+    $stderr.puts "Error: URL required"
+    $stderr.puts "Usage: exa similar <url>"
+    exit 1
+  end
+
+  check_api_key!
+
+  similar_options = Exa::FindSimilarOptions.build do
+    num_results options[ :num_results ]
+    exclude_source_domain true
+    contents do
+      summary { query 'Summarize in a single paragraph' }
+    end
+  end
+
+  response = Exa.find_similar( url, similar_options )
+
+  unless response.success?
+    $stderr.puts "Error: #{ response.result.error_description }"
+    exit 1
+  end
+
+  response.result.results.each_with_index do | result, index |
+    puts if index > 0
+    puts result.title
+    puts result.url
+    puts result.summary if result.summary
+  end
+end
+
+# Main
+command = ARGV.shift
+
+case command
+when 'search'
+  cmd_search( ARGV )
+when 'answer'
+  cmd_answer( ARGV )
+when 'similar'
+  cmd_similar( ARGV )
+when 'help', '-h', '--help', nil
+  usage
+else
+  $stderr.puts "Unknown command: #{ command }"
+  $stderr.puts "Run 'exa help' for usage"
+  exit 1
+end

data/exa-rb.gemspec

@@ -0,0 +1,41 @@
+require_relative 'lib/exa/version'
+
+Gem::Specification.new do | spec |
+
+  spec.name             = 'exa-rb'
+  spec.version          = Exa::VERSION
+  spec.authors          = [ 'Kristoph Cichocki-Romanov' ]
+  spec.email            = [ 'rubygems.org@kristoph.net' ]
+
+  spec.summary          =
+    "The Exa gem implements a lightweight interface to the Exa.ai API for neural " \
+    "and keyword-based web search with content retrieval capabilities."
+  spec.description      =
+    "The Exa gem implements a lightweight interface to the Exa.ai API. Exa provides " \
+    "powerful neural search capabilities that go beyond traditional keyword matching " \
+    "to understand semantic meaning and context.\n" \
+    "\n" \
+    "This gem supports search, find similar, answer, and contents endpoints. It " \
+    "includes both a Ruby API and a command-line interface (exa) for quick searches " \
+    "from the terminal."
+  spec.license          = 'MIT'
+  spec.homepage         = 'https://github.com/EndlessInternational/exa-rb'
+  spec.metadata         = {
+    'source_code_uri'   => 'https://github.com/EndlessInternational/exa-rb',
+    'bug_tracker_uri'   => 'https://github.com/EndlessInternational/exa-rb/issues',
+  }
+
+  spec.required_ruby_version = '>= 3.0'
+  spec.files            = Dir[ "lib/**/*.rb", "bin/exa", "LICENSE", "README.md", "exa-rb.gemspec" ]
+  spec.bindir           = 'bin'
+  spec.executables      = [ 'exa' ]
+  spec.require_paths    = [ "lib" ]
+
+  spec.add_runtime_dependency 'faraday', '~> 2'
+  spec.add_runtime_dependency 'dynamicschema', '~> 2'
+
+  spec.add_development_dependency 'minitest', '~> 5.25'
+  spec.add_development_dependency 'debug', '~> 1.9'
+  spec.add_development_dependency 'vcr', '~> 6.3'
+
+end

data/lib/exa/answer_options.rb

@@ -0,0 +1,29 @@
+module Exa
+  class AnswerOptions
+    include DynamicSchema::Definable
+    include Helpers
+
+    schema do
+      text    [ TrueClass, FalseClass ]
+      stream  [ TrueClass, FalseClass ]
+    end
+
+    def self.build( options = nil, &block )
+      new( api_options: builder.build( options, &block ) )
+    end
+
+    def self.build!( options = nil, &block )
+      new( api_options: builder.build!( options, &block ) )
+    end
+
+    def initialize( options = {}, api_options: nil )
+      @options = self.class.builder.build( options || {} )
+      @options = api_options.merge( @options ) if api_options
+    end
+
+    def to_h
+      @options.to_h
+    end
+
+  end
+end

data/lib/exa/answer_request.rb

@@ -0,0 +1,26 @@
+module Exa
+  class AnswerRequest < Request
+
+    def submit( query, options = nil, &block )
+      if options
+        options = options.is_a?( AnswerOptions ) ? options : AnswerOptions.build!( options.to_h )
+        options = options.to_h
+      else
+        options = {}
+      end
+      options[ :query ] = query.to_s
+
+      response = post( "#{ BASE_URI }/answer", options, &block )
+      attributes = ( JSON.parse( response.body, symbolize_names: true ) rescue nil )
+
+      result = if response.success?
+        AnswerResult.new( attributes )
+      else
+        ErrorResult.new( response.status, attributes )
+      end
+
+      ResponseMethods.install( response, result )
+    end
+
+  end
+end

data/lib/exa/answer_result.rb

@@ -0,0 +1,29 @@
+module Exa
+
+  CitationSchema = DynamicSchema::Struct.define do
+    id                  String
+    url                 String
+    title               String
+    author              String
+    published_date      String, as: :publishedDate
+    text                String
+    image               String
+    favicon             String
+  end
+
+  class Citation < CitationSchema
+  end
+
+  AnswerResultSchema = DynamicSchema::Struct.define do
+    request_id          String, as: :requestId
+    answer              String
+    citations           Citation, array: true
+  end
+
+  class AnswerResult < AnswerResultSchema
+    def success?
+      true
+    end
+  end
+
+end

data/lib/exa/contents_options.rb

@@ -0,0 +1,56 @@
+module Exa
+  class ContentsOptions
+    include DynamicSchema::Definable
+    include Helpers
+
+    LIVECRAWL_OPTIONS = [ :never, :fallback, :always ]
+
+    schema do
+
+      # text retrieval
+      text                  do
+        max_characters      Integer, as: :maxCharacters
+        include_html_tags   [ TrueClass, FalseClass ], as: :includeHtmlTags
+      end
+
+      # highlights
+      highlights            do
+        num_sentences       Integer, as: :numSentences
+        highlights_per_url  Integer, as: :highlightsPerUrl
+        query               String
+      end
+
+      # summary
+      summary               do
+        query               String
+      end
+
+      # crawling control
+      livecrawl             Symbol, in: LIVECRAWL_OPTIONS
+      livecrawl_timeout     Integer, as: :livecrawlTimeout
+
+      # subpages
+      subpages              Integer
+      subpage_target        String, as: :subpageTarget
+
+    end
+
+    def self.build( options = nil, &block )
+      new( api_options: builder.build( options, &block ) )
+    end
+
+    def self.build!( options = nil, &block )
+      new( api_options: builder.build!( options, &block ) )
+    end
+
+    def initialize( options = {}, api_options: nil )
+      @options = self.class.builder.build( options || {} )
+      @options = api_options.merge( @options ) if api_options
+    end
+
+    def to_h
+      @options.to_h
+    end
+
+  end
+end

data/lib/exa/contents_request.rb

@@ -0,0 +1,28 @@
+module Exa
+  class ContentsRequest < Request
+
+    def submit( urls, options = nil, &block )
+      urls = Array( urls ).map( &:to_s )
+
+      if options
+        options = options.is_a?( ContentsOptions ) ? options : ContentsOptions.build!( options.to_h )
+        options = options.to_h
+      else
+        options = {}
+      end
+      options[ :urls ] = urls
+
+      response = post( "#{ BASE_URI }/contents", options, &block )
+      attributes = ( JSON.parse( response.body, symbolize_names: true ) rescue nil )
+
+      result = if response.success?
+        ContentsResult.new( attributes )
+      else
+        ErrorResult.new( response.status, attributes )
+      end
+
+      ResponseMethods.install( response, result )
+    end
+
+  end
+end

data/lib/exa/contents_result.rb

@@ -0,0 +1,30 @@
+module Exa
+
+  ContentsResultItemSchema = DynamicSchema::Struct.define do
+    id                  String
+    url                 String
+    title               String
+    author              String
+    text                String
+    highlights          String, array: true
+    highlight_scores    Float, array: true, as: :highlightScores
+    summary             String
+    image               String
+    favicon             String
+  end
+
+  class ContentsResultItem < ContentsResultItemSchema
+  end
+
+  ContentsResultSchema = DynamicSchema::Struct.define do
+    request_id          String, as: :requestId
+    results             ContentsResultItem, array: true
+  end
+
+  class ContentsResult < ContentsResultSchema
+    def success?
+      true
+    end
+  end
+
+end

data/lib/exa/error_result.rb

@@ -0,0 +1,46 @@
+module Exa
+  class ErrorResult
+
+    attr_reader :error_type, :error_description
+
+    def initialize( status_code, attributes = nil )
+      @error_type, @error_description = status_code_to_error( status_code )
+      @error_description = attributes[ :error ] if attributes&.respond_to?( :[] ) && attributes[ :error ]
+    end
+
+  private
+
+    def status_code_to_error( status_code )
+      case status_code
+      when 200
+        [ :unexpected_error,
+          "The response was successful but it did not include a valid payload." ]
+      when 400
+        [ :invalid_request_error,
+          "Invalid request parameters, malformed JSON, or missing required fields." ]
+      when 401
+        [ :authentication_error,
+          "Missing or invalid API key." ]
+      when 403
+        [ :forbidden_error,
+          "Valid API key but insufficient permissions or rate limit exceeded." ]
+      when 404
+        [ :not_found_error,
+          "The requested resource was not found." ]
+      when 409
+        [ :conflict_error,
+          "Resource already exists." ]
+      when 429
+        [ :rate_limit_error,
+          "Rate limit exceeded." ]
+      when 500..599
+        [ :server_error,
+          "An error occurred on the Exa servers." ]
+      else
+        [ :unknown_error,
+          "The Exa service returned an unexpected status code: '#{ status_code }'." ]
+      end
+    end
+
+  end
+end

data/lib/exa/find_similar_options.rb

@@ -0,0 +1,66 @@
+module Exa
+  class FindSimilarOptions
+    include DynamicSchema::Definable
+    include Helpers
+
+    LIVECRAWL_OPTIONS = [ :never, :fallback, :always ]
+
+    schema do
+
+      # result control
+      num_results           Integer, as: :numResults
+      exclude_source_domain [ TrueClass, FalseClass ], as: :excludeSourceDomain
+
+      # domain filtering
+      include_domains       String, array: true, as: :includeDomains
+      exclude_domains       String, array: true, as: :excludeDomains
+
+      # date filtering
+      start_crawl_date      String, as: :startCrawlDate
+      end_crawl_date        String, as: :endCrawlDate
+      start_published_date  String, as: :startPublishedDate
+      end_published_date    String, as: :endPublishedDate
+
+      # content filtering
+      include_text          String, array: true, as: :includeText
+      exclude_text          String, array: true, as: :excludeText
+
+      # content retrieval options
+      contents              do
+        text                do
+          max_characters    Integer, as: :maxCharacters
+          include_html_tags [ TrueClass, FalseClass ], as: :includeHtmlTags
+        end
+        highlights          do
+          num_sentences       Integer, as: :numSentences
+          highlights_per_url  Integer, as: :highlightsPerUrl
+          query               String
+        end
+        summary             do
+          query             String
+        end
+        livecrawl           Symbol, in: LIVECRAWL_OPTIONS
+        livecrawl_timeout   Integer, as: :livecrawlTimeout
+      end
+
+    end
+
+    def self.build( options = nil, &block )
+      new( api_options: builder.build( options, &block ) )
+    end
+
+    def self.build!( options = nil, &block )
+      new( api_options: builder.build!( options, &block ) )
+    end
+
+    def initialize( options = {}, api_options: nil )
+      @options = self.class.builder.build( options || {} )
+      @options = api_options.merge( @options ) if api_options
+    end
+
+    def to_h
+      @options.to_h
+    end
+
+  end
+end

data/lib/exa/find_similar_request.rb

@@ -0,0 +1,26 @@
+module Exa
+  class FindSimilarRequest < Request
+
+    def submit( url, options = nil, &block )
+      if options
+        options = options.is_a?( FindSimilarOptions ) ? options : FindSimilarOptions.build!( options.to_h )
+        options = options.to_h
+      else
+        options = {}
+      end
+      options[ :url ] = url.to_s
+
+      response = post( "#{ BASE_URI }/findSimilar", options, &block )
+      attributes = ( JSON.parse( response.body, symbolize_names: true ) rescue nil )
+
+      result = if response.success?
+        FindSimilarResult.new( attributes )
+      else
+        ErrorResult.new( response.status, attributes )
+      end
+
+      ResponseMethods.install( response, result )
+    end
+
+  end
+end

data/lib/exa/find_similar_result.rb

@@ -0,0 +1,32 @@
+module Exa
+
+  FindSimilarResultItemSchema = DynamicSchema::Struct.define do
+    id                  String
+    url                 String
+    title               String
+    score               Float
+    published_date      String, as: :publishedDate
+    author              String
+    text                String
+    highlights          String, array: true
+    highlight_scores    Float, array: true, as: :highlightScores
+    summary             String
+    image               String
+    favicon             String
+  end
+
+  class FindSimilarResultItem < FindSimilarResultItemSchema
+  end
+
+  FindSimilarResultSchema = DynamicSchema::Struct.define do
+    request_id          String, as: :requestId
+    results             FindSimilarResultItem, array: true
+  end
+
+  class FindSimilarResult < FindSimilarResultSchema
+    def success?
+      true
+    end
+  end
+
+end

data/lib/exa/helpers.rb

@@ -0,0 +1,8 @@
+module Exa
+  module Helpers
+    def string_camelize( string )
+      words = string.split( /[\s_\-]/ )
+      words.map.with_index { | word, index | index.zero? ? word.downcase : word.capitalize }.join
+    end
+  end
+end

data/lib/exa/module_methods.rb

@@ -0,0 +1,31 @@
+module Exa
+  module ModuleMethods
+
+    def connection( connection = nil )
+      @connection = connection if connection
+      @connection ||= Faraday.new { | builder | builder.adapter Faraday.default_adapter }
+    end
+
+    def api_key( api_key = nil )
+      @api_key = api_key || @api_key
+      @api_key
+    end
+
+    def search( query, options = nil, &block )
+      Exa::SearchRequest.new.submit( query, options, &block )
+    end
+
+    def contents( urls, options = nil, &block )
+      Exa::ContentsRequest.new.submit( urls, options, &block )
+    end
+
+    def find_similar( url, options = nil, &block )
+      Exa::FindSimilarRequest.new.submit( url, options, &block )
+    end
+
+    def answer( query, options = nil, &block )
+      Exa::AnswerRequest.new.submit( query, options, &block )
+    end
+
+  end
+end

data/lib/exa/request.rb

@@ -0,0 +1,41 @@
+module Exa
+  class Request
+
+    BASE_URI = 'https://api.exa.ai'
+
+    def initialize( connection: nil, api_key: nil )
+      @connection = connection || Exa.connection
+      @api_key = api_key || Exa.api_key
+      raise ArgumentError, "An 'api_key' is required unless configured using 'Exa.api_key'." \
+        unless @api_key
+    end
+
+  protected
+
+    def post( uri, body, &block )
+      headers = {
+        'x-api-key' => @api_key,
+        'Content-Type' => 'application/json'
+      }
+
+      @connection.post( uri ) do | request |
+        headers.each { | key, value | request.headers[ key ] = value }
+        request.body = body.is_a?( String ) ? body : JSON.generate( body )
+        block.call( request ) if block
+      end
+    end
+
+    def get( uri, &block )
+      headers = {
+        'x-api-key' => @api_key,
+        'Content-Type' => 'application/json'
+      }
+
+      @connection.get( uri ) do | request |
+        headers.each { | key, value | request.headers[ key ] = value }
+        block.call( request ) if block
+      end
+    end
+
+  end
+end

data/lib/exa/response_methods.rb

@@ -0,0 +1,12 @@
+module Exa
+  module ResponseMethods
+    def self.install( response, result )
+      response.instance_variable_set( "@_exa_result", result )
+      response.extend( ResponseMethods )
+    end
+
+    def result
+      @_exa_result
+    end
+  end
+end

data/lib/exa/search_options.rb

@@ -0,0 +1,74 @@
+module Exa
+  class SearchOptions
+    include DynamicSchema::Definable
+    include Helpers
+
+    SEARCH_TYPES = [ :neural, :keyword, :auto ]
+    CATEGORIES = [ :company, :research_paper, :news, :pdf, :github, :tweet, :personal_site,
+                   :linkedin_profile, :financial_report ]
+    LIVECRAWL_OPTIONS = [ :never, :fallback, :always ]
+
+    schema do
+
+      # search configuration
+      type                  Symbol, in: SEARCH_TYPES
+      category              Symbol, in: CATEGORIES
+      use_autoprompt        [ TrueClass, FalseClass ], as: :useAutoprompt
+      user_location         String, as: :userLocation
+
+      # result control
+      num_results           Integer, as: :numResults
+
+      # domain filtering
+      include_domains       String, array: true, as: :includeDomains
+      exclude_domains       String, array: true, as: :excludeDomains
+
+      # date filtering
+      start_crawl_date      String, as: :startCrawlDate
+      end_crawl_date        String, as: :endCrawlDate
+      start_published_date  String, as: :startPublishedDate
+      end_published_date    String, as: :endPublishedDate
+
+      # content filtering
+      include_text          String, array: true, as: :includeText
+      exclude_text          String, array: true, as: :excludeText
+
+      # content retrieval options
+      contents              do
+        text                do
+          max_characters    Integer, as: :maxCharacters
+          include_html_tags [ TrueClass, FalseClass ], as: :includeHtmlTags
+        end
+        highlights          do
+          num_sentences       Integer, as: :numSentences
+          highlights_per_url  Integer, as: :highlightsPerUrl
+          query               String
+        end
+        summary             do
+          query             String
+        end
+        livecrawl           Symbol, in: LIVECRAWL_OPTIONS
+        livecrawl_timeout   Integer, as: :livecrawlTimeout
+      end
+
+    end
+
+    def self.build( options = nil, &block )
+      new( api_options: builder.build( options, &block ) )
+    end
+
+    def self.build!( options = nil, &block )
+      new( api_options: builder.build!( options, &block ) )
+    end
+
+    def initialize( options = {}, api_options: nil )
+      @options = self.class.builder.build( options || {} )
+      @options = api_options.merge( @options ) if api_options
+    end
+
+    def to_h
+      @options.to_h
+    end
+
+  end
+end

data/lib/exa/search_request.rb

@@ -0,0 +1,26 @@
+module Exa
+  class SearchRequest < Request
+
+    def submit( query, options = nil, &block )
+      if options
+        options = options.is_a?( SearchOptions ) ? options : SearchOptions.build!( options.to_h )
+        options = options.to_h
+      else
+        options = {}
+      end
+      options[ :query ] = query.to_s
+
+      response = post( "#{ BASE_URI }/search", options, &block )
+      attributes = ( JSON.parse( response.body, symbolize_names: true ) rescue nil )
+
+      result = if response.success?
+        SearchResult.new( attributes )
+      else
+        ErrorResult.new( response.status, attributes )
+      end
+
+      ResponseMethods.install( response, result )
+    end
+
+  end
+end

data/lib/exa/search_result.rb

@@ -0,0 +1,42 @@
+module Exa
+
+  SearchResultItemSchema = DynamicSchema::Struct.define do
+    id                  String
+    url                 String
+    title               String
+    score               Float
+    published_date      String, as: :publishedDate
+    author              String
+    text                String
+    highlights          String, array: true
+    highlight_scores    Float, array: true, as: :highlightScores
+    summary             String
+    image               String
+    favicon             String
+  end
+
+  class SearchResultItem < SearchResultItemSchema
+  end
+
+  AutopromptSchema = DynamicSchema::Struct.define do
+    query               String
+  end
+
+  class Autoprompt < AutopromptSchema
+  end
+
+  SearchResultSchema = DynamicSchema::Struct.define do
+    request_id          String, as: :requestId
+    resolved_search_type String, as: :resolvedSearchType
+    autoprompt_string   String, as: :autopromptString
+    autoprompt          Autoprompt
+    results             SearchResultItem, array: true
+  end
+
+  class SearchResult < SearchResultSchema
+    def success?
+      true
+    end
+  end
+
+end

data/lib/exa/version.rb

@@ -0,0 +1,3 @@
+module Exa
+  VERSION = '1.0.0'
+end

data/lib/exa.rb

@@ -0,0 +1,34 @@
+require 'json'
+require 'uri'
+
+require 'faraday'
+require 'dynamic_schema'
+
+require_relative 'exa/version'
+
+require_relative 'exa/helpers'
+require_relative 'exa/error_result'
+require_relative 'exa/request'
+require_relative 'exa/response_methods'
+
+require_relative 'exa/search_options'
+require_relative 'exa/search_result'
+require_relative 'exa/search_request'
+
+require_relative 'exa/contents_options'
+require_relative 'exa/contents_result'
+require_relative 'exa/contents_request'
+
+require_relative 'exa/find_similar_options'
+require_relative 'exa/find_similar_result'
+require_relative 'exa/find_similar_request'
+
+require_relative 'exa/answer_options'
+require_relative 'exa/answer_result'
+require_relative 'exa/answer_request'
+
+require_relative 'exa/module_methods'
+
+module Exa
+  extend ModuleMethods
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: exa-rb
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kristoph Cichocki-Romanov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: dynamicschema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+description: |-
+  The Exa gem implements a lightweight interface to the Exa.ai API. Exa provides powerful neural search capabilities that go beyond traditional keyword matching to understand semantic meaning and context.
+
+  This gem supports search, find similar, answer, and contents endpoints. It includes both a Ruby API and a command-line interface (exa) for quick searches from the terminal.
+email:
+- rubygems.org@kristoph.net
+executables:
+- exa
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/exa
+- exa-rb.gemspec
+- lib/exa.rb
+- lib/exa/answer_options.rb
+- lib/exa/answer_request.rb
+- lib/exa/answer_result.rb
+- lib/exa/contents_options.rb
+- lib/exa/contents_request.rb
+- lib/exa/contents_result.rb
+- lib/exa/error_result.rb
+- lib/exa/find_similar_options.rb
+- lib/exa/find_similar_request.rb
+- lib/exa/find_similar_result.rb
+- lib/exa/helpers.rb
+- lib/exa/module_methods.rb
+- lib/exa/request.rb
+- lib/exa/response_methods.rb
+- lib/exa/search_options.rb
+- lib/exa/search_request.rb
+- lib/exa/search_result.rb
+- lib/exa/version.rb
+homepage: https://github.com/EndlessInternational/exa-rb
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/EndlessInternational/exa-rb
+  bug_tracker_uri: https://github.com/EndlessInternational/exa-rb/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: The Exa gem implements a lightweight interface to the Exa.ai API for neural
+  and keyword-based web search with content retrieval capabilities.
+test_files: []