exa-ai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca5a6bcb0b981d51fcc93e1dc9f1e7037d1d6346e082826e1b1c003d586cce45
+  data.tar.gz: e598e0c91c2815a5abea958adb9f5112def140b78f13ba29872d07009c4056cc
+SHA512:
+  metadata.gz: 4b648ebe500a28dbb8d31aa936fd0d30a09ff94c372a3f3caec463d648993ae26473fc9724aea0157395b8e78ac9a25fc3f2752c8d6fd1cc68745bb8758b0ca7
+  data.tar.gz: 512d79543838b4b82ba263586c9cd029f8e19f350ff9c744b85dcb5b8f4e62236b442b70d07316721bc844f6ca9ac79bac6c1b42d57d5f0ef1214c5be407818e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benjamin Jackson
+
+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,562 @@
+# exa-ruby
+
+Ruby client for the Exa.ai API with comprehensive command-line interface.
+
+**Status**: Phase 9 CLI implementation complete. All commands working with full option support.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'exa-ai'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install exa-ai
+```
+
+## Configuration
+
+### Setting Your API Key
+
+Get your API key from [dashboard.exa.ai](https://dashboard.exa.ai).
+
+**Option 1: Environment Variable (recommended)**
+
+```bash
+export EXA_API_KEY="your-api-key-here"
+```
+
+**Option 2: Ruby Code**
+
+```ruby
+require 'exa'
+
+Exa.configure do |config|
+  config.api_key = "your-api-key-here"
+end
+
+# Or pass directly to client
+client = Exa::Client.new(api_key: "your-api-key-here")
+```
+
+**Option 3: CLI Flag**
+
+```bash
+exa-ai search "query" --api-key YOUR_API_KEY
+```
+
+## Ruby API Usage
+
+### Quick Start
+
+```ruby
+require 'exa'
+
+Exa.configure do |config|
+  config.api_key = ENV['EXA_API_KEY']
+end
+
+client = Exa::Client.new
+
+# Search the web
+results = client.search("ruby programming")
+puts results.results.first["title"]
+
+# Get an answer to a question
+answer = client.answer("What are the latest trends in AI?")
+puts answer.answer
+puts answer.citations
+
+# Get code context
+code = client.context("React hooks")
+puts code.response
+
+# Retrieve page contents
+contents = client.get_contents(["https://example.com"])
+puts contents.results.first["text"]
+```
+
+### Search
+
+```ruby
+client = Exa::Client.new(api_key: "your-key")
+
+# Basic search
+results = client.search("machine learning")
+
+# With options
+results = client.search("AI",
+  num_results: 10,
+  type: "neural",
+  include_domains: ["arxiv.org", "github.com"]
+)
+
+# Access results
+results.results.each do |item|
+  puts item["title"]
+  puts item["url"]
+  puts item["score"]
+end
+```
+
+### Answer
+
+```ruby
+client = Exa::Client.new(api_key: "your-key")
+
+# Get an answer to a question
+answer = client.answer("What are the best practices for API design?")
+
+puts answer.answer        # The generated answer
+puts answer.citations     # Array of source citations
+puts answer.cost_dollars  # API cost
+
+# With text content from sources
+answer = client.answer("Latest AI breakthroughs", text: true)
+puts answer.answer
+answer.citations.each do |citation|
+  puts "#{citation["title"]} (#{citation['url']})"
+end
+```
+
+### Context (Code Search)
+
+```ruby
+code = client.context("authentication in Rails")
+
+puts code.response        # The code context
+puts code.results_count   # Number of results
+puts code.cost_dollars    # API cost
+```
+
+### Get Contents
+
+```ruby
+contents = client.get_contents([
+  "https://example.com/page1",
+  "https://example.com/page2"
+])
+
+contents.results.each do |content|
+  puts content["url"]
+  puts content["title"]
+  puts content["text"]
+end
+```
+
+### Research (Async Tasks)
+
+```ruby
+# Start a research task
+task = client.research_start(
+  instructions: "Analyze recent AI breakthroughs",
+  model: "gpt-4"
+)
+puts task.research_id  # Save for later polling
+
+# Check status
+status = client.research_get(task.research_id)
+if status.completed?
+  puts status.output
+end
+
+# List all tasks
+list = client.research_list(limit: 20)
+list.data.each do |task|
+  puts "#{task.research_id}: #{task.status}"
+end
+```
+
+## CLI Usage
+
+### Main Commands
+
+```bash
+exa-ai <command> [options]
+
+Commands:
+  search          Search the web
+  answer          Generate answers to questions
+  context         Get code context from repositories
+  get-contents    Retrieve page contents
+  research-start  Start a research task
+  research-get    Get research task status
+  research-list   List research tasks
+```
+
+### Search Command
+
+Search the web using Exa's neural search:
+
+```bash
+# Basic search
+exa-ai search "ruby programming"
+
+# With options
+exa-ai search "machine learning" --num-results 10 --type keyword
+
+# Filter by domains
+exa-ai search "tutorials" \
+  --include-domains "github.com,dev.to" \
+  --exclude-domains "outdated-site.com"
+
+# Pretty output
+exa-ai search "AI" --output-format pretty
+```
+
+**Options:**
+- `QUERY` - Search query (required)
+- `--num-results N` - Number of results (default: 10)
+- `--type TYPE` - Search type: keyword, neural, or auto (default: auto)
+- `--include-domains DOMAINS` - Comma-separated domains to include
+- `--exclude-domains DOMAINS` - Comma-separated domains to exclude
+- `--use-autoprompt` - Use Exa's autoprompt feature
+- `--output-format FORMAT` - json or pretty (default: json)
+- `--api-key KEY` - API key (or set EXA_API_KEY env var)
+
+### Answer Command
+
+Generate comprehensive answers to questions using Exa's answer generation feature:
+
+```bash
+# Basic question
+exa-ai answer "What is the capital of France?"
+
+# Get answer with source citations
+exa-ai answer "Latest developments in quantum computing"
+
+# Include full text from sources
+exa-ai answer "Ruby on Rails best practices" --text
+
+# Pretty formatted output
+exa-ai answer "How do I learn machine learning?" --output-format pretty
+```
+
+**Options:**
+- `QUERY` - Question to answer (required)
+- `--text` - Include full text content from source pages
+- `--output-format FORMAT` - json or pretty (default: json)
+- `--api-key KEY` - API key (or set EXA_API_KEY env var)
+
+**Response fields:**
+- `answer` - The generated answer to your question
+- `citations` - Array of source citations with URLs
+- `cost_dollars` - Cost of the API request
+
+### Context Command (Code Search)
+
+Find code snippets and context from open-source repositories:
+
+```bash
+# Basic query
+exa-ai context "authentication with JWT"
+
+# With custom token allocation
+exa-ai context "React hooks" --tokens-num 5000
+
+# Text output
+exa-ai context "async/await patterns" --output-format text
+```
+
+**Options:**
+- `QUERY` - Search query (required)
+- `--tokens-num NUM` - Token allocation, integer or "dynamic" (default: dynamic)
+- `--output-format FORMAT` - json or text (default: json)
+- `--api-key KEY` - API key
+
+### Get-Contents Command
+
+Retrieve the full text content from web pages:
+
+```bash
+# Single page
+exa-ai get-contents "https://example.com/article"
+
+# Multiple pages (comma-separated)
+exa-ai get-contents "https://site1.com,https://site2.com"
+
+# With options
+exa-ai get-contents "id1,id2,id3" \
+  --text \
+  --highlights \
+  --output-format pretty
+```
+
+**Options:**
+- `IDS` - Page IDs or URLs (required, comma-separated)
+- `--text` - Include full text content
+- `--highlights` - Include highlighted sections
+- `--summary` - Include summary
+- `--output-format FORMAT` - json or pretty (default: json)
+- `--api-key KEY` - API key
+
+### Research Commands
+
+Start and manage long-running research tasks:
+
+#### research-start
+
+```bash
+# Start a task
+exa-ai research-start --instructions "Find Ruby performance tips"
+
+# Start and wait for completion
+exa-ai research-start \
+  --instructions "Analyze AI safety papers" \
+  --model gpt-4 \
+  --wait
+
+# With output schema
+exa-ai research-start \
+  --instructions "Extract key metrics" \
+  --output-schema '{"format":"json","fields":["metric","value"]}'
+```
+
+**Options:**
+- `--instructions TEXT` - Research instructions (required)
+- `--model MODEL` - Model to use (e.g., gpt-4)
+- `--output-schema SCHEMA` - JSON schema for structured output
+- `--wait` - Wait for task to complete (with polling)
+- `--events` - Show event log during polling
+- `--output-format FORMAT` - json or pretty (default: json)
+- `--api-key KEY` - API key
+
+#### research-get
+
+```bash
+# Check task status
+exa-ai research-get abc-123
+
+# With events
+exa-ai research-get abc-123 --events
+
+# Pretty output
+exa-ai research-get abc-123 --output-format pretty
+```
+
+**Options:**
+- `RESEARCH_ID` - Task ID (required)
+- `--events` - Include event log
+- `--stream` - Stream results (premium feature)
+- `--output-format FORMAT` - json or pretty (default: json)
+- `--api-key KEY` - API key
+
+#### research-list
+
+```bash
+# List all tasks
+exa-ai research-list
+
+# With pagination
+exa-ai research-list --limit 20
+
+# Next page
+exa-ai research-list --cursor "next_page_cursor"
+
+# Pretty table format
+exa-ai research-list --output-format pretty
+```
+
+**Options:**
+- `--cursor CURSOR` - Pagination cursor
+- `--limit N` - Results per page (default: 10)
+- `--output-format FORMAT` - json or pretty (default: json)
+- `--api-key KEY` - API key
+
+### Global Options
+
+All commands support:
+- `--api-key KEY` - Override API key
+- `--output-format FORMAT` - json, pretty, or text (varies by command)
+- `--help, -h` - Show command help
+- `exa-ai --version` - Show version
+- `exa-ai --help` - Show available commands
+
+### Output Formats
+
+**JSON (default)**
+```bash
+exa-ai search "ruby" --output-format json
+# Returns formatted JSON object
+```
+
+**Pretty**
+```bash
+exa-ai search "ruby" --output-format pretty
+# Returns human-readable format with titles, URLs, scores
+```
+
+**Text**
+```bash
+exa-ai context "React" --output-format text
+# Returns plain text output
+```
+
+## Error Handling
+
+The CLI provides helpful error messages:
+
+```bash
+# Missing API key
+$ exa search "test"
+❌ Configuration Error
+
+Missing API key. Set EXA_API_KEY or use --api-key
+
+Solutions:
+  1. Set the EXA_API_KEY environment variable:
+     export EXA_API_KEY='your-api-key'
+  ...
+
+# Invalid credentials
+$ exa search "test" --api-key bad-key
+❌ Authentication Error
+
+Your API key is invalid or has expired.
+...
+
+# Rate limited
+$ exa search "test"  # After many requests
+❌ Request Error
+
+You've exceeded the rate limit. Please wait before trying again.
+```
+
+### Ruby API Error Handling
+
+```ruby
+client = Exa::Client.new(api_key: "test")
+
+begin
+  results = client.search("test")
+rescue Exa::Unauthorized => e
+  puts "Invalid API key: #{e.message}"
+rescue Exa::TooManyRequests => e
+  puts "Rate limited, please wait"
+rescue Exa::ServerError => e
+  puts "API error: #{e.message}"
+end
+```
+
+## Examples
+
+### CLI Examples
+
+```bash
+# Find Ruby tutorials
+exa search "Ruby best practices" --num-results 5
+
+# Get an answer to a question
+exa answer "What is machine learning?"
+
+# Get code examples for async/await
+exa context "async/await error handling"
+
+# Research AI trends
+exa research-start --instructions "What are latest AI trends?" --wait
+
+# Retrieve and analyze multiple pages
+exa get-contents "url1,url2,url3" --text --output-format pretty
+```
+
+### Ruby API Examples
+
+```ruby
+require 'exa'
+
+Exa.configure do |config|
+  config.api_key = ENV['EXA_API_KEY']
+end
+
+client = Exa::Client.new
+
+# Search with filtering
+results = client.search("kubernetes tutorial",
+  num_results: 20,
+  type: "neural",
+  include_domains: ["kubernetes.io", "github.com"],
+  use_autoprompt: true
+)
+
+results.results.each do |item|
+  puts "#{item['title']} (#{item['url']})"
+end
+
+# Get code context
+code_result = client.context("Docker best practices", tokens_num: 5000)
+puts code_result.response
+
+# Start async research
+task = client.research_start(
+  instructions: "Summarize recent ML papers",
+  model: "gpt-4"
+)
+puts "Task started: #{task.research_id}"
+
+# Poll for results
+loop do
+  status = client.research_get(task.research_id)
+  break if status.completed? || status.failed?
+  sleep 5
+end
+
+if status.completed?
+  puts status.output
+end
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run specific test file
+bundle exec ruby test/cli/search_test.rb
+
+# Run with verbose output
+bundle exec rake test TESTOPTS="-v"
+```
+
+### Building the Gem
+
+```bash
+bundle exec rake build
+bundle exec rake install
+```
+
+## Documentation
+
+- [Exa API Documentation](https://docs.exa.ai)
+- [API Reference](https://docs.exa.ai/reference)
+- [Status Page](https://status.exa.ai)
+
+## Support
+
+- **Documentation**: https://docs.exa.ai
+- **API Key**: https://dashboard.exa.ai
+- **Status**: https://status.exa.ai
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
+
+---
+
+**Built with Exa.ai** - Search and discovery API for the web

data/exe/exa-ai

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "exa"
+require "exa/cli/base"
+
+# Global CLI interface for Exa API
+
+module ExaCLI
+  AVAILABLE_COMMANDS = {
+    "search" => "Search the web",
+    "answer" => "Generate an answer to a question",
+    "context" => "Get code context from repositories",
+    "get-contents" => "Retrieve page contents",
+    "research-start" => "Start a research task",
+    "research-get" => "Get research task status",
+    "research-list" => "List research tasks"
+  }.freeze
+
+  def self.run
+    case ARGV[0]
+    when "--version"
+      puts Exa::VERSION
+      exit 0
+    when "--help", "help", "-h", nil
+      print_help
+      exit 0
+    when "--api-key"
+      puts "Use --api-key flag with specific commands"
+      exit 1
+    when "search"
+      exec File.expand_path("../exa-ai-search", __FILE__), *ARGV[1..]
+    when "answer"
+      exec File.expand_path("../exa-ai-answer", __FILE__), *ARGV[1..]
+    when "context"
+      exec File.expand_path("../exa-ai-context", __FILE__), *ARGV[1..]
+    when "get-contents"
+      exec File.expand_path("../exa-ai-get-contents", __FILE__), *ARGV[1..]
+    when "research-start"
+      exec File.expand_path("../exa-ai-research-start", __FILE__), *ARGV[1..]
+    when "research-get"
+      exec File.expand_path("../exa-ai-research-get", __FILE__), *ARGV[1..]
+    when "research-list"
+      exec File.expand_path("../exa-ai-research-list", __FILE__), *ARGV[1..]
+    else
+      print_error_for_command(ARGV[0])
+      exit 1
+    end
+  end
+
+  def self.print_help
+    puts "Exa CLI v#{Exa::VERSION}"
+    puts ""
+    puts "Usage: exa-ai <command> [options]"
+    puts ""
+    puts "Commands:"
+    AVAILABLE_COMMANDS.each do |cmd, desc|
+      puts "  #{cmd.ljust(20)} #{desc}"
+    end
+    puts ""
+    puts "Global Options:"
+    puts "  --help, -h         Show this help message"
+    puts "  --version          Show version number"
+    puts ""
+    puts "Examples:"
+    puts "  exa-ai search 'ruby programming'"
+    puts "  exa-ai context 'React hooks' --tokens-num 5000"
+    puts "  exa-ai research-start --instructions 'Find AI papers'"
+  end
+
+  def self.print_error_for_command(cmd)
+    return print_help if cmd.nil?
+
+    puts "Error: Unknown command '#{cmd}'"
+    puts ""
+
+    # Try to suggest similar commands
+    suggestion = suggest_command(cmd)
+    puts "Did you mean: #{suggestion}?" if suggestion
+
+    puts ""
+    puts "Run 'exa-ai --help' for usage information."
+  end
+
+  def self.suggest_command(input)
+    # Simple suggestion based on string similarity
+    # If first char matches and length is similar, suggest it
+    input_start = input[0]
+    candidates = AVAILABLE_COMMANDS.keys.select { |c| c[0] == input_start }
+    candidates.first
+  end
+end
+
+ExaCLI.run