exaonruby 1.1.0 → 1.3.0

data/lib/exa/middleware/response_cache.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require "digest"
+require "json"
+
+module Exa
+  module Middleware
+    # Response caching middleware for Exa API calls
+    #
+    # Caches GET requests and idempotent POST requests (like search)
+    # to reduce API costs and improve response times.
+    #
+    # @example Enable caching with memory store
+    #   client = Exa::Client.new(api_key: key) do |config|
+    #     config.cache = Exa::Cache::MemoryStore.new
+    #     config.cache_ttl = 300  # 5 minutes
+    #   end
+    #
+    # @example With Redis
+    #   require 'redis'
+    #   client = Exa::Client.new(api_key: key) do |config|
+    #     config.cache = Exa::Cache::RedisStore.new(Redis.new)
+    #     config.cache_ttl = 3600  # 1 hour
+    #   end
+    class ResponseCache < Faraday::Middleware
+      # Cacheable endpoints (idempotent operations)
+      CACHEABLE_PATHS = %w[
+        /search
+        /contents
+        /findSimilar
+      ].freeze
+
+      # @param app [Faraday::Middleware] Next middleware
+      # @param cache [Object] Cache store (must respond to get/set)
+      # @param ttl [Integer] Time to live in seconds
+      # @param cacheable_paths [Array<String>] Paths to cache
+      def initialize(app, cache:, ttl: 300, cacheable_paths: CACHEABLE_PATHS)
+        super(app)
+        @cache = cache
+        @ttl = ttl
+        @cacheable_paths = cacheable_paths
+      end
+
+      def call(env)
+        return @app.call(env) unless cacheable?(env)
+
+        cache_key = build_cache_key(env)
+        
+        # Try to get from cache
+        cached = @cache.get(cache_key)
+        if cached
+          return build_cached_response(env, cached)
+        end
+
+        # Make request and cache response
+        @app.call(env).on_complete do |response_env|
+          if response_env[:status] == 200
+            cache_response(cache_key, response_env)
+          end
+        end
+      end
+
+      private
+
+      def cacheable?(env)
+        path = env[:url].path
+        @cacheable_paths.any? { |p| path.include?(p) }
+      end
+
+      def build_cache_key(env)
+        # Include method, path, and body in cache key
+        components = [
+          env[:method].to_s,
+          env[:url].path,
+          env[:body].to_s
+        ]
+        
+        digest = Digest::SHA256.hexdigest(components.join("|"))
+        "exa:cache:#{digest}"
+      end
+
+      def cache_response(key, env)
+        data = {
+          status: env[:status],
+          headers: env[:response_headers].to_h,
+          body: env[:body]
+        }
+        
+        @cache.set(key, data.to_json, ttl: @ttl)
+      end
+
+      def build_cached_response(env, cached_data)
+        data = JSON.parse(cached_data, symbolize_names: true)
+        
+        env[:status] = data[:status]
+        env[:response_headers] = Faraday::Utils::Headers.new(data[:headers])
+        env[:body] = data[:body]
+        
+        # Add cache hit header
+        env[:response_headers]["X-Exa-Cache"] = "HIT"
+        
+        Faraday::Response.new(env)
+      end
+    end
+
+    Faraday::Middleware.register_middleware(exa_cache: ResponseCache)
+  end
+
+  module Cache
+    # In-memory cache store with TTL support
+    #
+    # Thread-safe, suitable for single-process applications.
+    # For multi-process or distributed apps, use RedisStore.
+    class MemoryStore
+      def initialize
+        @store = {}
+        @expirations = {}
+        @mutex = Mutex.new
+      end
+
+      # Get value from cache
+      # @param key [String] Cache key
+      # @return [String, nil] Cached value or nil
+      def get(key)
+        @mutex.synchronize do
+          cleanup_expired
+          @store[key]
+        end
+      end
+
+      # Set value in cache
+      # @param key [String] Cache key
+      # @param value [String] Value to cache
+      # @param ttl [Integer] Time to live in seconds
+      def set(key, value, ttl: 300)
+        @mutex.synchronize do
+          @store[key] = value
+          @expirations[key] = Time.now + ttl
+        end
+      end
+
+      # Delete from cache
+      # @param key [String] Cache key
+      def delete(key)
+        @mutex.synchronize do
+          @store.delete(key)
+          @expirations.delete(key)
+        end
+      end
+
+      # Clear entire cache
+      def clear
+        @mutex.synchronize do
+          @store.clear
+          @expirations.clear
+        end
+      end
+
+      # Get cache statistics
+      # @return [Hash] Stats including size and hit count
+      def stats
+        @mutex.synchronize do
+          cleanup_expired
+          { size: @store.size }
+        end
+      end
+
+      private
+
+      def cleanup_expired
+        now = Time.now
+        expired_keys = @expirations.select { |_, exp| exp < now }.keys
+        expired_keys.each do |key|
+          @store.delete(key)
+          @expirations.delete(key)
+        end
+      end
+    end
+
+    # Redis cache store for distributed caching
+    #
+    # Requires redis gem to be installed.
+    #
+    # @example
+    #   require 'redis'
+    #   cache = Exa::Cache::RedisStore.new(Redis.new)
+    class RedisStore
+      # @param redis [Redis] Redis client instance
+      # @param prefix [String] Key prefix
+      def initialize(redis, prefix: "exa")
+        @redis = redis
+        @prefix = prefix
+      end
+
+      def get(key)
+        @redis.get(prefixed(key))
+      end
+
+      def set(key, value, ttl: 300)
+        @redis.setex(prefixed(key), ttl, value)
+      end
+
+      def delete(key)
+        @redis.del(prefixed(key))
+      end
+
+      def clear
+        keys = @redis.keys("#{@prefix}:*")
+        @redis.del(*keys) if keys.any?
+      end
+
+      def stats
+        keys = @redis.keys("#{@prefix}:*")
+        { size: keys.size }
+      end
+
+      private
+
+      def prefixed(key)
+        key.start_with?(@prefix) ? key : "#{@prefix}:#{key}"
+      end
+    end
+  end
+end

data/lib/exa/rails.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  # Rails integration for the Exa gem
+  #
+  # Provides generators, Active Job adapters, and Rails-specific configuration.
+  #
+  # Install with: rails generate exa:install
+  module Rails
+    class Railtie < ::Rails::Railtie
+      # Initialize Exa with Rails configuration
+      initializer "exa.configure" do |app|
+        # Load config from Rails credentials or environment
+        Exa.configure do |config|
+          config.api_key = rails_api_key(app)
+          config.logger = ::Rails.logger if defined?(::Rails.logger)
+          config.timeout = ENV.fetch("EXA_TIMEOUT", 60).to_i
+        end
+      end
+
+      # Add Exa rake tasks
+      rake_tasks do
+        namespace :exa do
+          desc "Verify Exa API connection"
+          task verify: :environment do
+            begin
+              client = Exa::Client.new
+              result = client.search("test", num_results: 1)
+              puts "✓ Exa API connection successful"
+              puts "  Request ID: #{result.request_id}"
+            rescue Exa::Error => e
+              puts "✗ Exa API error: #{e.message}"
+              exit 1
+            end
+          end
+
+          desc "Show Exa configuration"
+          task config: :environment do
+            puts "Exa Configuration:"
+            puts "  API Key: #{Exa.configuration&.api_key&.slice(0, 8)}..."
+            puts "  Base URL: #{Exa.configuration&.base_url}"
+            puts "  Timeout: #{Exa.configuration&.timeout}s"
+          end
+        end
+      end
+
+      private
+
+      def rails_api_key(app)
+        # Try Rails credentials first
+        if app.credentials.respond_to?(:exa)
+          app.credentials.exa[:api_key]
+        elsif app.credentials.respond_to?(:dig)
+          app.credentials.dig(:exa, :api_key)
+        end || ENV["EXA_API_KEY"]
+      end
+    end
+
+    # Active Job adapter for async research tasks
+    #
+    # @example Create a research job
+    #   class ExaResearchJob < ApplicationJob
+    #     include Exa::Rails::ResearchJob
+    #
+    #     def perform(instructions)
+    #       research(instructions) do |task|
+    #         # Called when research completes
+    #         save_results(task.output)
+    #       end
+    #     end
+    #   end
+    module ResearchJob
+      extend ActiveSupport::Concern
+
+      included do
+        queue_as :exa_research
+        retry_on Exa::RateLimitError, wait: :exponentially_longer, attempts: 5
+        discard_on Exa::AuthenticationError
+      end
+
+      # Start a research task and poll until complete
+      #
+      # @param instructions [String] Research instructions
+      # @param model [String] Research model
+      # @param poll_interval [Integer] Seconds between status checks
+      #
+      # @yield [Exa::Resources::ResearchTask] Called when complete
+      def research(instructions, model: "exa-research", poll_interval: 5)
+        client = Exa::Client.new
+        task = client.create_research(instructions: instructions, model: model)
+
+        loop do
+          task = client.get_research(task.research_id)
+
+          case task.status
+          when "completed"
+            yield task if block_given?
+            return task
+          when "failed", "canceled"
+            raise Exa::Error, "Research task #{task.status}: #{task.error_message}"
+          else
+            sleep poll_interval
+          end
+        end
+      end
+    end
+
+    # Action Cable channel for real-time updates
+    #
+    # @example Create a channel
+    #   class ExaSearchChannel < ApplicationCable::Channel
+    #     include Exa::Rails::StreamingChannel
+    #
+    #     def search(data)
+    #       stream_answer(data["query"])
+    #     end
+    #   end
+    module StreamingChannel
+      extend ActiveSupport::Concern
+
+      # Stream answer tokens to the client
+      #
+      # @param query [String] Question to answer
+      def stream_answer(query)
+        Exa::Utils::SSEClient.stream_answer(
+          api_key: ENV["EXA_API_KEY"],
+          query: query
+        ) do |event|
+          case event[:type]
+          when :token
+            transmit({ type: "token", data: event[:data] })
+          when :citation
+            transmit({ type: "citation", data: event[:data] })
+          when :done
+            transmit({ type: "done" })
+          when :error
+            transmit({ type: "error", data: event[:data] })
+          end
+        end
+      end
+
+      # Stream research progress to the client
+      #
+      # @param instructions [String] Research instructions
+      def stream_research(instructions)
+        Exa::Utils::SSEClient.stream_research(
+          api_key: ENV["EXA_API_KEY"],
+          instructions: instructions
+        ) do |event|
+          transmit({ type: event[:type].to_s, data: event[:data] })
+        end
+      end
+    end
+  end
+end

data/lib/exa/utils/parallel.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require "concurrent"
+
+module Exa
+  module Utils
+    # Parallel request executor for batch operations
+    #
+    # Execute multiple Exa API calls concurrently with configurable
+    # concurrency limits and automatic error handling.
+    #
+    # @example Parallel searches
+    #   queries = ["AI research", "ML trends", "NLP papers"]
+    #   
+    #   results = Exa::Utils::Parallel.map(queries, client: client) do |query|
+    #     client.search(query, num_results: 10)
+    #   end
+    #
+    # @example With concurrency limit
+    #   results = Exa::Utils::Parallel.map(urls, concurrency: 5) do |url|
+    #     client.get_contents([url])
+    #   end
+    #
+    # @example Error handling
+    #   results = Exa::Utils::Parallel.map(queries, on_error: :skip) do |query|
+    #     client.search(query)
+    #   end
+    class Parallel
+      # Default concurrency limit
+      DEFAULT_CONCURRENCY = 10
+
+      class << self
+        # Execute block for each item in parallel
+        #
+        # @param items [Array] Items to process
+        # @param concurrency [Integer] Max concurrent requests
+        # @param on_error [Symbol] Error handling: :raise, :skip, :return_nil
+        # @param timeout [Integer, nil] Timeout per request in seconds
+        #
+        # @yield [item] Block to execute for each item
+        # @return [Array] Results in same order as input
+        #
+        # @example
+        #   Exa::Utils::Parallel.map(queries) { |q| client.search(q) }
+        def map(items, concurrency: DEFAULT_CONCURRENCY, on_error: :raise, timeout: nil)
+          return [] if items.empty?
+
+          pool = Concurrent::FixedThreadPool.new(concurrency)
+          futures = []
+
+          items.each_with_index do |item, idx|
+            future = Concurrent::Future.execute(executor: pool) do
+              if timeout
+                Concurrent::Promises.future { yield(item) }.value!(timeout)
+              else
+                yield(item)
+              end
+            end
+            futures << { index: idx, future: future }
+          end
+
+          # Collect results in order
+          results = Array.new(items.length)
+          
+          futures.each do |entry|
+            begin
+              results[entry[:index]] = entry[:future].value!
+            rescue StandardError => e
+              case on_error
+              when :raise
+                pool.shutdown
+                raise
+              when :skip
+                next
+              when :return_nil
+                results[entry[:index]] = nil
+              else
+                raise
+              end
+            end
+          end
+
+          pool.shutdown
+          pool.wait_for_termination
+
+          results
+        end
+
+        # Execute block for each item in parallel, returning only successful results
+        #
+        # @param items [Array] Items to process
+        # @param concurrency [Integer] Max concurrent requests
+        #
+        # @yield [item] Block to execute for each item
+        # @return [Array] Successful results only
+        def map_compact(items, concurrency: DEFAULT_CONCURRENCY, &block)
+          map(items, concurrency: concurrency, on_error: :return_nil, &block).compact
+        end
+
+        # Execute block for each item in parallel, ignoring return values
+        #
+        # @param items [Array] Items to process
+        # @param concurrency [Integer] Max concurrent requests
+        #
+        # @yield [item] Block to execute for each item
+        # @return [void]
+        def each(items, concurrency: DEFAULT_CONCURRENCY, &block)
+          map(items, concurrency: concurrency, on_error: :skip, &block)
+          nil
+        end
+
+        # Execute multiple different operations in parallel
+        #
+        # @param operations [Array<Proc>] Procs to execute
+        # @param concurrency [Integer] Max concurrent requests
+        #
+        # @return [Array] Results from each proc
+        #
+        # @example
+        #   results = Exa::Utils::Parallel.all(
+        #     -> { client.search("AI") },
+        #     -> { client.search("ML") },
+        #     -> { client.get_contents([url]) }
+        #   )
+        def all(*operations, concurrency: DEFAULT_CONCURRENCY)
+          operations = operations.first if operations.first.is_a?(Array)
+          
+          map(operations, concurrency: concurrency) { |op| op.call }
+        end
+      end
+    end
+  end
+end

data/lib/exa/version.rb

@@ -3,5 +3,5 @@
 # typed: strict
 
 module Exa
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/exa.rb

@@ -3,12 +3,21 @@
 # typed: strict
 
 require_relative "exa/version"
+require "faraday"
+require "faraday/retry"
 require_relative "exa/errors"
 require_relative "exa/configuration"
 
 require_relative "exa/utils/parameter_converter"
 require_relative "exa/utils/webhook_handler"
 require_relative "exa/utils/sse_client"
+require_relative "exa/utils/parallel"
+
+# Middleware (loaded after Faraday is available in Client)
+require_relative "exa/middleware/request_logger"
+require_relative "exa/middleware/rate_limiter"
+require_relative "exa/middleware/response_cache"
+require_relative "exa/middleware/instrumentation"
 
 # Optional: Sorbet types (only loaded if sorbet-runtime is available)
 begin
@@ -18,7 +27,17 @@ rescue LoadError
   # sorbet-runtime not installed, types module not available
 end
 
+# Optional: Rails integration (only loaded if Rails is available)
+begin
+  if defined?(::Rails::Railtie)
+    require_relative "exa/rails"
+  end
+rescue LoadError
+  # Rails not available
+end
+
 require_relative "exa/resources/base"
+require_relative "exa/resources/paginated_response"
 require_relative "exa/resources/search_result"
 require_relative "exa/resources/search_response"
 require_relative "exa/resources/contents_response"
@@ -26,7 +45,6 @@ require_relative "exa/resources/answer_response"
 require_relative "exa/resources/research_task"
 require_relative "exa/resources/webset"
 require_relative "exa/resources/webset_item"
-require_relative "exa/resources/paginated_response"
 require_relative "exa/resources/monitor"
 require_relative "exa/resources/import"
 require_relative "exa/resources/webhook"

data/lib/generators/exa/install_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Exa
+  module Generators
+    # Rails generator for Exa gem installation
+    #
+    # Usage:
+    #   rails generate exa:install
+    #
+    # This creates:
+    #   - config/initializers/exa.rb
+    #   - Adds EXA_API_KEY to .env if using dotenv
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an Exa initializer and credentials setup"
+
+      def create_initializer
+        create_file "config/initializers/exa.rb", <<~RUBY
+          # frozen_string_literal: true
+
+          # Exa API Configuration
+          # Documentation: https://docs.exa.ai
+          # Gem: https://github.com/tigel-agm/exaonruby
+
+          Exa.configure do |config|
+            # API Key (from Rails credentials or environment)
+            # Run: rails credentials:edit
+            # Add: exa: { api_key: "your-key" }
+            config.api_key = Rails.application.credentials.dig(:exa, :api_key) || ENV["EXA_API_KEY"]
+
+            # Request timeout in seconds (default: 60)
+            config.timeout = 60
+
+            # Maximum retry attempts for failed requests
+            config.max_retries = 3
+
+            # Optional: Enable request logging in development
+            if Rails.env.development?
+              config.logger = Rails.logger
+            end
+
+            # Optional: Enable caching to reduce API costs
+            # config.cache = Exa::Cache::MemoryStore.new
+            # config.cache_ttl = 300  # 5 minutes
+
+            # Optional: Rate limiting (requests per second)
+            # config.rate_limit = 10
+            # config.rate_limit_burst = 20
+          end
+        RUBY
+        say "Created config/initializers/exa.rb", :green
+      end
+
+      def add_to_env
+        if File.exist?(".env")
+          append_to_file ".env" do
+            "\n# Exa API Key\nEXA_API_KEY=your-api-key-here\n"
+          end
+          say "Added EXA_API_KEY to .env", :green
+        elsif File.exist?(".env.example")
+          append_to_file ".env.example" do
+            "\n# Exa API Key\nEXA_API_KEY=\n"
+          end
+          say "Added EXA_API_KEY to .env.example", :green
+        end
+      end
+
+      def show_instructions
+        say ""
+        say "Exa gem installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Add your API key to Rails credentials:"
+        say "     rails credentials:edit"
+        say ""
+        say "     exa:"
+        say "       api_key: your-api-key-here"
+        say ""
+        say "  2. Or set the EXA_API_KEY environment variable"
+        say ""
+        say "  3. Test the connection:"
+        say "     rails exa:verify"
+        say ""
+        say "Usage examples:"
+        say "  client = Exa::Client.new"
+        say "  results = client.search('AI research', num_results: 10)"
+        say ""
+      end
+    end
+  end
+end