exaonruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2da95920bde51eb7724ef7c1cfa01d25906d4cb04cde2d2dc9d1055ec1267f9e
+  data.tar.gz: 190c39f5437c045f60067856033ad54330ce05425dd0edea79cb0fa74fed989f
+SHA512:
+  metadata.gz: dea6072b3c1b149c869a4d76854cd36a3aa1a18241cbdea6a105f1331e2fb297723def00c59a30e13c4c044d93095b03b1bd7594f9dc9815e8c20b3bc59c3546
+  data.tar.gz: 12db1ecb3e8b3528bcaf74c03ea9a259136d794a9c68125562d69fe1d031808582f140cb2e50eb06b2faf3b9ec476c2eefc56809fe013ad3439d63fba35a7776

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Exa Labs
+
+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,614 @@
+# Exa Ruby
+
+A production-ready Ruby gem wrapper for the [Exa.ai](https://exa.ai) API, providing intelligent web search, content extraction, and structured data collection capabilities.
+
+## Features
+
+- **Search API**: Neural search, deep search, and content extraction
+- **Contents API**: Fetch full page contents with livecrawl support
+- **Find Similar**: Discover semantically similar pages
+- **Answer API**: LLM-powered question answering with citations
+- **Research API**: Async research tasks with structured output
+- **Websets API**: Build and manage structured web data collections
+- **Monitors**: Automated scheduled searches and content refresh
+- **Imports**: Upload CSV data into Websets
+- **Webhooks & Events**: Real-time notifications for Websets activity
+- **Beautiful CLI**: Colorful command-line interface
+- **n8n/Zapier Integration**: Webhook signature verification utilities
+- **Automatic Retries**: Built-in retry logic for transient failures
+- **Rate Limit Handling**: Proper error handling with retry information
+- **Type Documentation**: Comprehensive YARD documentation
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'exa'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install exa
+```
+
+## Quick Start
+
+### Configuration
+
+Configure the client with your API key:
+
+```ruby
+require 'exa'
+
+# Option 1: Environment variable (recommended)
+# Set EXA_API_KEY environment variable
+
+# Option 2: Global configuration
+Exa.configure do |config|
+  config.api_key = 'your-api-key'
+  config.timeout = 60          # Request timeout in seconds
+  config.max_retries = 3       # Retry attempts for transient failures
+end
+
+# Option 3: Direct client initialization
+client = Exa::Client.new(api_key: 'your-api-key')
+```
+
+### Basic Search
+
+```ruby
+# Simple search
+results = Exa.search("Latest developments in LLMs")
+
+# Access results
+results.each do |result|
+  puts "#{result.title}: #{result.url}"
+end
+
+# Search with content extraction
+results = Exa.search(
+  "AI research papers",
+  text: true,
+  num_results: 20
+)
+
+results.each do |result|
+  puts result.title
+  puts result.text[0..500] if result.text
+end
+```
+
+### Deep Search
+
+For comprehensive results with query expansion:
+
+```ruby
+results = client.search(
+  "Machine learning startups",
+  type: :deep,
+  additional_queries: ["AI companies", "ML ventures"],
+  category: :company,
+  include_domains: ["linkedin.com", "crunchbase.com"],
+  start_published_date: "2024-01-01T00:00:00.000Z",
+  num_results: 50
+)
+```
+
+### Get Contents
+
+Fetch full page contents from URLs:
+
+```ruby
+contents = client.get_contents(
+  ["https://arxiv.org/abs/2307.06435"],
+  text: true,
+  summary: true,
+  livecrawl: :preferred
+)
+
+contents.results.each do |page|
+  puts page.title
+  puts page.summary
+end
+
+# Check for failures
+if !contents.all_success?
+  contents.failed_statuses.each do |status|
+    puts "Failed to fetch #{status.id}: #{status.error_tag}"
+  end
+end
+```
+
+### Find Similar Links
+
+Discover pages similar to a given URL:
+
+```ruby
+similar = client.find_similar(
+  "https://arxiv.org/abs/2307.06435",
+  num_results: 20,
+  include_domains: ["arxiv.org", "paperswithcode.com"],
+  text: true
+)
+
+similar.each do |result|
+  puts "#{result.title}: #{result.url}"
+end
+```
+
+## Answer API
+
+Get LLM-powered answers to questions with citations from web sources:
+
+```ruby
+# Simple question
+response = client.answer("What is the latest valuation of SpaceX?")
+puts response.answer  # => "$350 billion."
+
+# Access citations
+response.citations.each do |citation|
+  puts "Source: #{citation.title}"
+  puts "URL: #{citation.url}"
+end
+
+# With search options
+response = client.answer(
+  "What are the latest AI safety developments?",
+  text: true,
+  num_results: 10,
+  start_published_date: "2024-01-01T00:00:00.000Z"
+)
+```
+
+## Research API
+
+Create async research tasks for in-depth web research:
+
+```ruby
+# Create a research task
+task = client.create_research(
+  instructions: "Summarize the latest developments in AI safety research",
+  model: "exa-research"  # or "exa-research-fast", "exa-research-pro"
+)
+
+puts "Task ID: #{task.research_id}"
+puts "Status: #{task.status}"  # => "pending" or "running"
+
+# Poll for results
+loop do
+  task = client.get_research(task.research_id)
+  
+  case task.status
+  when "completed"
+    puts task.output
+    break
+  when "running"
+    puts "Progress: #{task.operations_completed}/#{task.operations_total}"
+    sleep 5
+  when "failed"
+    puts "Error: #{task.error_message}"
+    break
+  end
+end
+
+# With structured output schema
+schema = {
+  type: "object",
+  properties: {
+    companies: { type: "array", items: { type: "string" } },
+    summary: { type: "string" }
+  }
+}
+
+task = client.create_research(
+  instructions: "Find the top 5 AI startups in 2024",
+  model: "exa-research-pro",
+  output_schema: schema
+)
+
+# List all research tasks
+response = client.list_research(limit: 10)
+response.data.each { |t| puts "#{t.research_id}: #{t.status}" }
+
+# Cancel a running task
+client.cancel_research(task.research_id)
+```
+
+## Websets API
+
+Websets allow you to build structured collections of web data with automated search, verification, and enrichment.
+
+### Create a Webset
+
+```ruby
+webset = client.create_webset(
+  search: {
+    query: "AI startups founded in 2024",
+    count: 100,
+    entity: { type: "company" },
+    criteria: [
+      { description: "Company must be focused on artificial intelligence" },
+      { description: "Founded in 2024" }
+    ]
+  },
+  enrichments: [
+    { description: "Company's total funding amount", format: "number" },
+    { description: "Number of employees", format: "number" },
+    { 
+      description: "Primary industry vertical",
+      format: "enum",
+      options: [
+        { label: "Healthcare" },
+        { label: "Finance" },
+        { label: "Enterprise" },
+        { label: "Consumer" },
+        { label: "Other" }
+      ]
+    }
+  ],
+  external_id: "my-ai-startups-2024"
+)
+
+puts "Created Webset: #{webset.id}"
+puts "Status: #{webset.status}"
+```
+
+### Monitor Webset Progress
+
+```ruby
+webset = client.get_webset(webset.id)
+
+webset.searches.each do |search|
+  puts "Search: #{search.query}"
+  puts "Found: #{search.found_count}"
+  puts "Completion: #{search.completion_percentage}%"
+end
+```
+
+### List Webset Items
+
+```ruby
+response = client.list_webset_items(webset.id, limit: 50)
+
+response.data.each do |item|
+  puts "Item: #{item.url}"
+  puts "Type: #{item.type}"
+  
+  # Check criteria evaluations
+  item.evaluations.each do |eval|
+    status = eval.satisfied? ? "✓" : "✗"
+    puts "  #{status} #{eval.criterion}"
+  end
+  
+  # Access enrichment results
+  item.enrichments.each do |enrichment|
+    puts "  #{enrichment.format}: #{enrichment.result}"
+  end
+end
+
+# Paginate through all items
+while response.has_more?
+  response = client.list_webset_items(webset.id, cursor: response.next_cursor)
+  # Process items...
+end
+```
+
+### Add Searches to Existing Webset
+
+```ruby
+search = client.create_webset_search(
+  webset.id,
+  query: "AI healthcare startups",
+  count: 50,
+  entity: { type: "company" },
+  criteria: [{ description: "Must be in healthcare industry" }]
+)
+
+puts "Search ID: #{search.id}"
+```
+
+### Add Enrichments
+
+```ruby
+enrichment = client.create_webset_enrichment(
+  webset.id,
+  description: "CEO or founder name",
+  format: "text"
+)
+```
+
+### Delete Resources
+
+```ruby
+# Delete an item
+client.delete_webset_item(webset.id, item.id)
+
+# Delete an enrichment
+client.delete_webset_enrichment(webset.id, enrichment.id)
+
+# Cancel an in-progress search
+client.cancel_webset_search(webset.id, search.id)
+
+# Delete entire webset
+client.delete_webset(webset.id)
+```
+
+## Search Options Reference
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `type` | Symbol | `:neural`, `:auto`, `:fast`, `:deep` |
+| `category` | Symbol | `:people`, `:company`, `:research_paper`, `:news`, `:pdf`, `:github`, `:tweet`, `:personal_site`, `:financial_report` |
+| `num_results` | Integer | Number of results (max 100) |
+| `include_domains` | Array | Domains to include |
+| `exclude_domains` | Array | Domains to exclude |
+| `start_crawl_date` | String/Time | Results crawled after this date |
+| `end_crawl_date` | String/Time | Results crawled before this date |
+| `start_published_date` | String/Time | Results published after this date |
+| `end_published_date` | String/Time | Results published before this date |
+| `include_text` | Array | Keywords that must be present |
+| `exclude_text` | Array | Keywords to exclude |
+| `country` | String | Two-letter ISO country code |
+| `text` | Boolean/Hash | Return text content |
+| `highlights` | Boolean/Hash | Return highlights |
+| `summary` | Boolean/Hash | Return AI summary |
+| `context` | Boolean/Integer | Return context string for LLM |
+| `moderation` | Boolean | Filter unsafe content |
+| `livecrawl` | Symbol | `:never`, `:fallback`, `:preferred`, `:always` |
+
+## Error Handling
+
+The gem provides specific error classes for different failure modes:
+
+```ruby
+begin
+  results = client.search("query")
+rescue Exa::AuthenticationError => e
+  puts "Invalid API key: #{e.message}"
+rescue Exa::RateLimitError => e
+  puts "Rate limited. Retry after: #{e.retry_after} seconds"
+rescue Exa::InvalidRequestError => e
+  puts "Invalid request: #{e.message}"
+  puts "Validation errors: #{e.validation_errors}" if e.validation_errors
+rescue Exa::NotFoundError => e
+  puts "Resource not found: #{e.message}"
+rescue Exa::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Exa::TimeoutError => e
+  puts "Request timed out: #{e.message}"
+rescue Exa::Error => e
+  puts "General error: #{e.message}"
+end
+```
+
+## Advanced Configuration
+
+```ruby
+Exa.configure do |config|
+  config.api_key = ENV['EXA_API_KEY']
+  config.base_url = 'https://api.exa.ai'
+  config.websets_base_url = 'https://api.exa.ai/websets/v0'
+  config.timeout = 120
+  config.max_retries = 5
+  config.retry_delay = 1.0
+  config.max_retry_delay = 60.0
+  config.retry_statuses = [429, 500, 502, 503, 504]
+end
+
+# Enable logging
+Exa.logger = Logger.new(STDOUT)
+```
+
+## Response Objects
+
+### SearchResponse
+
+```ruby
+response = client.search("query")
+
+response.request_id        # Unique request ID
+response.results           # Array of SearchResult
+response.context           # Combined context string
+response.cost              # CostInfo object
+response.total_cost        # Cost in dollars
+
+# Enumerable
+response.each { |r| puts r.title }
+response.first
+response.count
+```
+
+### SearchResult
+
+```ruby
+result.id                  # Unique identifier
+result.title               # Page title
+result.url                 # Page URL
+result.published_date      # Publication date (Time)
+result.author              # Author name
+result.text                # Full text content
+result.highlights          # Highlighted snippets
+result.summary             # AI-generated summary
+result.subpages            # Related subpages
+```
+
+### Webset
+
+```ruby
+webset.id                  # Unique identifier
+webset.status              # idle, pending, running, paused
+webset.title               # Webset title
+webset.searches            # Array of WebsetSearch
+webset.items               # Array of WebsetItem
+webset.enrichments         # Array of WebsetEnrichment
+webset.created_at          # Creation timestamp
+```
+
+## Monitors
+
+Create automated schedules to keep Websets updated:
+
+```ruby
+# Create a monitor to search daily
+monitor = client.create_monitor(
+  webset_id: "webset_abc123",
+  cadence: { cron: "0 9 * * *", timezone: "America/New_York" },
+  behavior: {
+    type: "search",
+    config: {
+      count: 50,
+      query: "AI news today",
+      entity: { type: "article" },
+      behavior: "append"
+    }
+  }
+)
+
+# List monitors
+client.list_monitors(webset_id: "webset_abc123")
+
+# Update monitor
+client.update_monitor(monitor.id, status: "disabled")
+
+# Delete monitor
+client.delete_monitor(monitor.id)
+```
+
+## Imports
+
+Upload CSV data into Websets:
+
+```ruby
+# Create an import
+import = client.create_import(
+  size: 1024,
+  count: 100,
+  format: "csv",
+  entity: { type: "company" },
+  title: "Q4 Leads",
+  csv: { identifier: 1 }
+)
+
+# Upload file to the returned URL
+puts "Upload to: #{import.upload_url}"
+puts "Valid until: #{import.upload_valid_until}"
+
+# Check import status
+import = client.get_import(import.id)
+puts "Status: #{import.status}"
+```
+
+## Webhooks & Events
+
+Subscribe to real-time notifications:
+
+```ruby
+# Create a webhook
+webhook = client.create_webhook(
+  url: "https://example.com/webhooks/exa",
+  events: ["webset.item.created", "webset.item.enriched"]
+)
+puts "Secret (save this!): #{webhook.secret}"
+
+# List events
+events = client.list_events(
+  types: ["webset.item.created"],
+  limit: 50
+)
+
+events.data.each { |e| puts "#{e.type} at #{e.created_at}" }
+```
+
+## n8n & Zapier Integration
+
+Verify webhook signatures in your integrations:
+
+```ruby
+# In your webhook receiver (Rails, Sinatra, etc.)
+raw_body = request.raw_post
+signature = request.headers["X-Exa-Signature"]
+
+if Exa::Utils::WebhookHandler.verify_signature(
+  raw_body, 
+  signature, 
+  secret: ENV["EXA_WEBHOOK_SECRET"]
+)
+  event = Exa::Utils::WebhookHandler.parse_event(raw_body)
+  
+  case event.type
+  when "webset.item.created"
+    # Handle new item
+  when "webset.item.enriched"
+    # Handle enriched item
+  end
+  
+  head :ok
+else
+  head :unauthorized
+end
+
+# One-liner with automatic error handling
+event = Exa::Utils::WebhookHandler.construct_event(
+  raw_body,
+  request.headers,
+  secret: ENV["EXA_WEBHOOK_SECRET"]
+)
+```
+
+## Command-Line Interface
+
+The gem includes a beautiful CLI:
+
+```bash
+# Search
+exa search "latest AI research"
+exa search "ML startups" -n 20 --type deep
+
+# Answer questions
+exa answer "What is the valuation of SpaceX?"
+
+# Find similar pages
+exa similar "https://arxiv.org/abs/2307.06435"
+
+# Research
+exa research "Summarize AI safety developments in 2024" --wait
+
+# Manage Websets
+exa websets list
+exa websets get ws_abc123
+exa websets items ws_abc123
+
+# Output as JSON
+exa search "AI news" --json
+
+# Show version
+exa version
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- faraday >= 2.0
+- faraday-retry >= 2.0
+- thor >= 1.0
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/exa-labs/exa-ruby.
+

data/exaonruby.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/exa/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "exaonruby"
+  spec.version = Exa::VERSION
+  spec.authors = ["tigel-agm"]
+  spec.email = []
+
+  spec.summary = "Complete Ruby client for the Exa.ai API with beautiful CLI"
+  spec.description = "A production-ready Ruby gem wrapper for the Exa.ai Search and Websets APIs. " \
+                     "Features neural search, LLM-powered answers, async research tasks, " \
+                     "Websets management (monitors, imports, webhooks), and a beautiful CLI. " \
+                     "Includes n8n/Zapier webhook signature verification utilities."
+  spec.homepage = "https://github.com/tigel-agm/exaonruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/tigel-agm/exaonruby"
+  spec.metadata["changelog_uri"] = "https://github.com/tigel-agm/exaonruby/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://github.com/tigel-agm/exaonruby#readme"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Include all lib files explicitly since we may not have git
+  spec.files = Dir.glob("{lib,exe}/**/*") + %w[LICENSE.txt README.md]
+  spec.files += Dir.glob("*.gemspec")
+
+  spec.bindir = "exe"
+  spec.executables = ["exa"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", ">= 2.0", "< 3.0"
+  spec.add_dependency "faraday-retry", ">= 2.0", "< 3.0"
+  spec.add_dependency "thor", ">= 1.0", "< 3.0"
+end

data/exe/exa

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/exa"
+require_relative "../lib/exa/cli"
+
+Exa::CLI.start(ARGV)