exa-ai-ruby 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61569eb14ed0573b4f252e3e7279320bd716ea2d044c5af4c830f33c536608da
-  data.tar.gz: 60b89c6b10b38756628c1d0bbefee6bd907309a946d2eac795b0749c456c2d61
+  metadata.gz: cbb55f4b95516f779fda2e4f26d34d38778ce94186683001768348b8378e06ac
+  data.tar.gz: dc31ed93afbc2a1f7d96db620fe975d70c2aaa7647a11eaa7592ae973e9fe5cb
 SHA512:
-  metadata.gz: 6fdd59ce00cfd0b46024db0bff5750770249b06ccd59dc792cc8d46037262bfe2ef864f29981d1f5028ca48e98be4f232b246b6b26edc764c7bbc17ea521c8cb
-  data.tar.gz: 3955736a25363da2379351f8514603509ee976d5130d230de601cd063e185b3c2b1e9143e032cc3d8a5ee7fde9ff688854a55331f6b379db1e40133f9511c3a9
+  metadata.gz: 8bcb3d9fa20d16ac14435ad04c327ab508afa1461fe0aa0f99528a5eb423fb32246bfdf5db732547c52bab9f89107dc5feae65f28879699948ef9d188570929f
+  data.tar.gz: 56019a774cb70ab4a1f73a9586c1e02735d3df867313c6c62d0012b19180f1067d6b0aa8774b5625a71d5b0b0f3ce924e490c86b8d99256444d66bf3da00b4c7

data/CHANGELOG.md

@@ -1,4 +1,19 @@
 # Changelog
 
+## [1.1.1] - 2025-10-26
+- Add CLI output formatters: `--format jsonl` emits one JSON object per line, and `--format markdown` prints share-ready bullet lists/tables.
+- Document copy-paste ready CLI and Ruby API examples in the README so users/LLMs can get started instantly.
+
+## [1.1.0] - 2025-10-26
+- Add the `exa` CLI entrypoint (installed automatically with the gem) including multi-account credential management and JSON-friendly output helpers.
+- Introduce a secure YAML config store (`~/.config/exa/config.yml`) and CLI commands for `accounts:list`, `accounts:add`, `accounts:use`, and `accounts:remove`.
+- Expand the CLI surface to cover search (run/contents/similar/answer), research (create/list/get/cancel), websets (core, items, enrichments, monitors), imports, events, and webhooks, with shared JSON payload helpers and basic streaming support (`search:answer --stream`, `research:get --stream`), all exercised via new unit + Aruba tests following `docs/cli-plan.md`.
+
+## [1.0.0] - 2025-10-26
+- First stable release of the typed Exa API client.
+- Covers search, research, websets, monitors, imports, events, and webhooks resources based on the OpenAPI spec.
+- Adds Sorbet-backed request/response structs, schema-aware structured output helpers, retrying transport, and streaming utilities.
+- Bundles developer ergonomics: connection pooling, pagination helpers, JSON/SSE streaming, and extensive README docs.
+
 ## [0.1.0] - 2025-10-25
 - Initial gem scaffolding.

data/README.md

@@ -1,8 +1,12 @@
 # Exa Ruby Client
 
+[![Gem Version](https://img.shields.io/gem/v/exa-ai-ruby)](https://rubygems.org/gems/exa-ai-ruby)
+[![Total Downloads](https://img.shields.io/gem/dt/exa-ai-ruby)](https://rubygems.org/gems/exa-ai-ruby)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/vicentereig/exa-ruby/ruby.yml?branch=main&label=tests)](https://github.com/vicentereig/exa-ruby/actions/workflows/ruby.yml)
+
 > Typed, Sorbet-friendly Ruby bindings for the Exa API, inspired by `openai-ruby` and aligned with Exa’s OpenAPI specs.
 
-This README doubles as the canonical “llms-full” reference for the project: it documents the architecture, the current API surface, and the functional-programming patterns we’re porting from OpenAI’s client. If you’re building the Exa Ruby SDK—or just trying to understand how to extend it—start here.
+This README is intentionally exhaustive—LLM agents and humans alike should be able to read it and learn how to use or extend the client without digging elsewhere.
 
 ---
 
@@ -11,15 +15,15 @@ This README doubles as the canonical “llms-full” reference for the project:
 1. [Project Goals](#project-goals)
 2. [Environment & Installation](#environment--installation)
 3. [Client Architecture Overview](#client-architecture-overview)
-4. [Typed Resources & Usage Examples](#typed-resources--usage-examples)
+4. [CLI Quickstart](#cli-quickstart)
+5. [Typed Resources & Usage Examples](#typed-resources--usage-examples)
    - [Search stack](#search-stack)
    - [Research](#research)
    - [Websets (core + items + enrichments + monitors)](#websets-core--items--enrichments--monitors)
    - [Events, Imports, Webhooks](#events-imports-webhooks)
-5. [Structured Output via Sorbet + dspy-schema](#structured-output-via-sorbet--dspy-schema)
-6. [Streaming & Transport Helpers](#streaming--transport-helpers)
-7. [Testing & TDD Plan](#testing--tdd-plan)
-8. [Roadmap / TODOs](#roadmap--todos)
+6. [Structured Output via Sorbet + dspy-schema](#structured-output-via-sorbet--dspy-schema)
+7. [Streaming & Transport Helpers](#streaming--transport-helpers)
+8. [Testing & TDD Plan](#testing--tdd-plan)
 
 ---
 
@@ -41,11 +45,25 @@ $ git clone https://github.com/vicentereig/exa-ruby
 $ cd exa-ruby
 $ rbenv install 3.4.5   # .ruby-version already pins this
 $ bundle install
+```
 
-# or install from RubyGems (gem name: exa-ai-ruby)
+### Install via RubyGems
+
+```
 $ gem install exa-ai-ruby
 ```
 
+### Install via Bundler
+
+```ruby
+# Gemfile
+gem "exa-ai-ruby", "~> 1.0"
+```
+
+```
+$ bundle install
+```
+
 Runtime dependencies:
 - `sorbet-runtime` – typed structs/enums and runtime assertions.
 - `connection_pool` – `Net::HTTP` pooling in `PooledNetRequester`.
@@ -53,6 +71,8 @@ Runtime dependencies:
 
 Set the API key via `EXA_API_KEY` or pass `api_key:` when instantiating `Exa::Client`.
 
+If you are building automation that calls this README (e.g., using `curl`/`wget` or a retrieval plug‑in), fetch the raw file from GitHub: `https://raw.githubusercontent.com/vicentereig/exa-ruby/main/README.md`.
+
 ---
 
 ## Client Architecture Overview
@@ -76,7 +96,105 @@ client = Exa::Client.new(
 - Response models live in `lib/exa/responses/*`. Whenever an endpoint returns typed data the resource sets `response_model:` so the client converts the JSON hash into Sorbet structs (e.g., `Exa::Responses::SearchResponse`, `Webset`, `Research`, etc.).
 - Transport stack:
   - `PooledNetRequester` manages per-origin `Net::HTTP` pools via `connection_pool`.
-  - Responses stream through fused enumerators so we can decode JSON/JSONL/SSE lazily and ensure sockets are closed once consumers finish iterating.
+- Responses stream through fused enumerators so we can decode JSON/JSONL/SSE lazily and ensure sockets are closed once consumers finish iterating.
+
+---
+
+## CLI Quickstart
+
+Starting with v1.1.0 the gem ships an `exa` executable that mirrors the API surface defined here. The CLI bootstraps the same typed client, so you get retries, streaming, and Sorbet-backed responses without writing Ruby.
+
+1. **Install / update the gem and confirm the binary**
+
+   ```
+   $ gem install exa-ai-ruby
+   $ exa version
+   exa-ai-ruby 1.1.0
+   ```
+
+2. **Store credentials once** (per account) and let the CLI manage `~/.config/exa/config.yml` (override via `EXA_CONFIG_DIR` or `--config`). Files are chmod’d `0600`.
+
+   ```
+   $ exa accounts:add prod --api-key exa_prod_xxx --base-url https://api.exa.ai
+   $ exa accounts:add staging --api-key exa_stage_xxx --base-url https://staging.exa.ai --no-default
+   $ exa accounts:list
+   * prod        https://api.exa.ai
+     staging     https://staging.exa.ai
+   $ exa accounts:use staging
+   ```
+
+   Every command accepts `--account`, `--api-key`, `--base-url`, `--config`, and `--format`. If omitted they fall back to the config file, environment variables (`EXA_ACCOUNT`, `EXA_API_KEY`, `EXA_BASE_URL`), or defaults.
+
+   3. **Call the API from any shell**
+
+      ```
+      # Run a typed search (pipe `--json` to jq or capture raw data)
+      $ exa search:run "latest reasoning LLM papers" --num-results 3 --json
+
+      # Fetch contents for explicit URLs
+      $ exa search:contents --urls https://exa.ai,https://exa.com --json
+
+      # Stream results as JSON lines (great for logging/piping)
+      $ exa search:run "ai funding" --num-results 2 --format jsonl
+
+      # Share-ready Markdown lists
+      $ exa websets:list --format markdown
+      ```
+
+      Omit `--json` for friendly summaries; include it when scripting so you get the Sorbet structs serialized as plain JSON.
+
+   Prefer `--format jsonl` for streaming-friendly logs or `--format markdown` when you want ready-to-share bullet lists/tables.
+
+### Copy-paste CLI examples
+
+```bash
+# 1) Configure credentials once (stored at ~/.config/exa/config.yml)
+exa accounts:add prod --api-key $EXA_API_KEY --base-url https://api.exa.ai
+
+# 2) Run searches with different outputs
+exa search:run "latest reasoning LLM papers" --num-results 5
+exa search:run "biotech funding" --format jsonl | tee results.jsonl
+
+# 3) Inspect resources in Markdown form (perfect for PRs/notes)
+exa websets:list --format markdown
+exa webhooks:list --format markdown
+
+# 4) Use a one-off API key without mutating config
+exa search:contents --urls https://exa.ai --api-key $EXA_API_KEY --json
+```
+
+### Copy-paste API client example
+
+```ruby
+require "exa"
+
+client = Exa::Client.new(api_key: ENV.fetch("EXA_API_KEY"))
+
+search = client.search.search(
+  query: "latest reasoning LLM papers",
+  num_results: 5,
+  text: true
+)
+
+search.results.each do |result|
+  puts "#{result.title} - #{result.url}"
+end
+
+# Websets + monitors
+websets = client.websets.list(limit: 5)
+websets.data.each_with_index do |webset, idx|
+  puts "#{idx + 1}. #{webset.title} (#{webset.id})"
+end
+```
+
+Command families currently available:
+
+- `exa search:*` – run searches, fetch contents, find similar results, or call `/answer` (with optional streaming).
+- `exa research:*` – create/list/get/cancel research runs.
+- `exa websets:*` – manage websets plus nested items, enrichments, and monitors (including monitor runs).
+- `exa imports:*`, `exa events:*`, and `exa webhooks:*` – work with imports, audit events, and webhook endpoints/attempts.
+
+The detailed roadmap, command matrix, and TDD expectations for future CLI work live in [`docs/cli-plan.md`](docs/cli-plan.md). See `test/cli/accounts_commands_test.rb` and `test/cli/search_commands_test.rb` for examples of the required coverage when you add new commands.
 
 ---
 
@@ -143,7 +261,7 @@ Responses use `Exa::Responses::Research` and `ResearchListResponse`, which prese
 ```ruby
 webset = client.websets.create(name: "Competitive Intelligence")
 webset = client.websets.update(webset.id, title: "Updated title")
-ListResp = client.websets.list(limit: 10)
+list_resp = client.websets.list(limit: 10)
 
 # Items
 items = client.websets.items.list(webset.id, limit: 5)
@@ -212,6 +330,7 @@ Key points:
   - `decode_content` auto-detects JSON/JSONL/SSE vs binary bodies.
   - `decode_lines` + `decode_sse` implement fused enumerators so sockets close exactly once.
 - `PooledNetRequester` calibrates socket timeouts per request deadline and reuses connections via `connection_pool`.
+- Per-request overrides: pass `request_options: {timeout: 30, max_retries: 0, idempotency_key: SecureRandom.uuid}` to `Exa::Client#request` (exposed when constructing custom helpers) for fine-grained control.
 
 See `test/transport/stream_test.rb` for examples.
 
@@ -236,12 +355,6 @@ Future tests:
 
 ---
 
-## Roadmap / TODOs
-
-1. **Typed coverage for the remaining OpenAPI endpoints** – webhooks attempts detail, events schema typing, structured outputs for additional research events, etc.
-2. **Code generation from OpenAPI specs** – automate request/response struct creation so spec updates can be pulled regularly.
-3. **Transport polish** – retries with `Retry-After`, idempotency keys, better error envelopes mirroring Exa’s payloads.
-4. **README “llms-full” expansion** – continue updating this document as new features land so it remains the single source of truth.
-5. **Release packaging** – ensure `.gem` builds exclude dev artifacts (`pkg/`, `.idea/`, etc.) and publish initial versions to RubyGems.
+---
 
 Have ideas or find gaps? Open an issue or PR in `vicentereig/exa-ruby`—contributions welcome!***

data/exe/exa

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  # bundler is optional when installed as a gem
+rescue StandardError => e
+  raise unless defined?(Bundler::GemfileNotFound) && e.is_a?(Bundler::GemfileNotFound)
+end
+
+require "exa/cli"
+
+Exa::CLI::Root.start(ARGV)

data/lib/exa/cli/account_resolver.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "config_store"
+
+module Exa
+  module CLI
+    class AccountResolver
+      DEFAULT_BASE_URL = "https://api.exa.ai"
+
+      Result = Struct.new(:api_key, :base_url, :account, keyword_init: true)
+
+      class MissingCredentialsError < StandardError; end
+      class UnknownAccountError < StandardError; end
+
+      def initialize(config_store:)
+        @config_store = config_store
+      end
+
+      def resolve(options:, env: ENV)
+        data = config_store.read
+        account_name = options[:account] || env["EXA_ACCOUNT"] || data["default"]
+        account_data = fetch_account(data, account_name) if account_name
+
+        api_key = options[:api_key] ||
+                  env["EXA_API_KEY"] ||
+                  account_data&.dig("api_key")
+
+        base_url = options[:base_url] ||
+                   env["EXA_BASE_URL"] ||
+                   account_data&.dig("base_url") ||
+                   DEFAULT_BASE_URL
+
+        unless api_key
+          raise MissingCredentialsError,
+                "Missing API key. Provide --api-key, set EXA_API_KEY, or add an account via `exa accounts:add`."
+        end
+
+        Result.new(api_key: api_key, base_url: base_url, account: account_name)
+      end
+
+      private
+
+      attr_reader :config_store
+
+      def fetch_account(data, name)
+        account = data["accounts"][name]
+        raise UnknownAccountError, "Account #{name.inspect} not found" unless account
+
+        account
+      end
+    end
+  end
+end

data/lib/exa/cli/config_store.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Exa
+  module CLI
+    class ConfigStore
+      DEFAULT_RELATIVE_PATH = File.join(".config", "exa", "config.yml")
+      DEFAULT_DATA = {
+        "version" => 1,
+        "accounts" => {},
+        "default" => nil
+      }.freeze
+
+      class UnknownAccountError < StandardError; end
+
+      attr_reader :path
+
+      def initialize(path: nil, env: ENV)
+        @env = env
+        @path = path || env["EXA_CONFIG_PATH"] || File.join(config_dir(env), "config.yml")
+      end
+
+      def read
+        if File.exist?(path)
+          data = safe_load(File.read(path))
+          normalize_data(data)
+        else
+          default_data
+        end
+      end
+
+      def upsert_account(name, api_key:, base_url:, make_default: true)
+        data = read
+        data["accounts"][name] = {
+          "api_key" => api_key,
+          "base_url" => base_url
+        }.compact
+        data["default"] ||= name if make_default
+        write(data)
+      end
+
+      def remove_account(name)
+        data = read
+        removed = data["accounts"].delete(name)
+        return false unless removed
+
+        data["default"] = nil if data["default"] == name
+        write(data)
+        true
+      end
+
+      def set_default(name)
+        data = read
+        unless data["accounts"].key?(name)
+          raise UnknownAccountError, "Account #{name.inspect} not found"
+        end
+
+        data["default"] = name
+        write(data)
+      end
+
+      private
+
+      def config_dir(env)
+        env["EXA_CONFIG_DIR"] || File.join(Dir.home, ".config", "exa")
+      end
+
+      def write(data)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, YAML.dump(data))
+        File.chmod(0o600, path)
+      end
+
+      def safe_load(content)
+        YAML.safe_load(content, permitted_classes: [], permitted_symbols: [], aliases: false) || {}
+      rescue Psych::SyntaxError
+        default_data
+      end
+
+      def normalize_data(data)
+        normalized = default_data.merge(data.compact)
+        normalized["accounts"] ||= {}
+        normalized
+      end
+
+      def default_data
+        {
+          "version" => DEFAULT_DATA["version"],
+          "accounts" => {},
+          "default" => nil
+        }
+      end
+    end
+  end
+end

data/lib/exa/cli/formatters.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Exa
+  module CLI
+    module Formatters
+      def self.for(name)
+        case name&.to_s&.downcase
+        when "json"
+          JsonFormatter.new
+        when "jsonl"
+          JsonlFormatter.new
+        when "markdown"
+          MarkdownFormatter.new
+        else
+          TableFormatter.new
+        end
+      end
+
+      class BaseFormatter
+        def render(cli:, payload:, collection:)
+          raise NotImplementedError
+        end
+
+        private
+
+        def serialize(cli, object)
+          cli.send(:serializable, object)
+        end
+      end
+
+      class JsonFormatter < BaseFormatter
+        def render(cli:, payload:, collection:)
+          cli.say JSON.pretty_generate(serialize(cli, payload))
+        end
+      end
+
+      class JsonlFormatter < BaseFormatter
+        def render(cli:, payload:, collection:)
+          items = collection && !collection.empty? ? collection : [payload]
+          items.each do |item|
+            cli.say JSON.generate(serialize(cli, item))
+          end
+        end
+      end
+
+      class MarkdownFormatter < BaseFormatter
+        def render(cli:, payload:, collection:)
+          if collection && !collection.empty?
+            collection.each do |item|
+              cli.say "- #{markdown_line(cli, item)}"
+            end
+          else
+            cli.say "```json"
+            cli.say JSON.pretty_generate(serialize(cli, payload))
+            cli.say "```"
+          end
+        end
+
+        private
+
+        def markdown_line(cli, item)
+          title = cli.send(:value_from, item, :title) || cli.send(:value_from, item, :name)
+          url = cli.send(:value_from, item, :url)
+          id = cli.send(:value_from, item, :id)
+          primary = title || id || cli.send(:serializable, item)
+
+          line = primary.is_a?(String) ? primary : primary.to_s
+          line = "[#{line}](#{url})" if url
+          line += " (#{id})" if id && (title || url)
+          line
+        end
+      end
+
+      class TableFormatter < BaseFormatter
+        def render(cli:, payload:, collection:)
+          if collection && !collection.empty?
+            collection.each_with_index do |item, index|
+              cli.say cli.send(:format_collection_entry, item, index)
+            end
+          elsif collection
+            cli.say "No results."
+          else
+            cli.say cli.send(:format_single_entry, payload)
+          end
+        end
+      end
+    end
+  end
+end