exaonruby 1.0.0 → 1.2.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/types.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require "sorbet-runtime"
+
+module Exa
+  module Types
+    extend T::Sig
+
+    # Typed request structures for Search API
+    class SearchParams < T::Struct
+      const :query, String
+      const :type, T.nilable(String)
+      const :num_results, T.nilable(Integer)
+      const :include_domains, T.nilable(T::Array[String])
+      const :exclude_domains, T.nilable(T::Array[String])
+      const :start_crawl_date, T.nilable(String)
+      const :end_crawl_date, T.nilable(String)
+      const :start_published_date, T.nilable(String)
+      const :end_published_date, T.nilable(String)
+      const :include_text, T.nilable(T::Array[String])
+      const :exclude_text, T.nilable(T::Array[String])
+      const :category, T.nilable(String)
+      const :country, T.nilable(String)
+      const :text, T.nilable(T::Boolean)
+      const :highlights, T.nilable(T::Boolean)
+      const :summary, T.nilable(T::Boolean)
+      const :livecrawl, T.nilable(String)
+    end
+
+    class ContentsParams < T::Struct
+      const :ids, T::Array[String]
+      const :text, T.nilable(T::Boolean)
+      const :highlights, T.nilable(T::Boolean)
+      const :summary, T.nilable(T::Boolean)
+      const :livecrawl, T.nilable(String)
+      const :subpages, T.nilable(Integer)
+    end
+
+    class AnswerParams < T::Struct
+      const :query, String
+      const :text, T.nilable(T::Boolean)
+      const :stream, T.nilable(T::Boolean)
+      const :num_results, T.nilable(Integer)
+    end
+
+    class ResearchParams < T::Struct
+      const :instructions, String
+      const :model, T.nilable(String)
+      const :output_schema, T.nilable(T::Hash[Symbol, T.untyped])
+    end
+
+    # Typed response structures
+    class SearchResultData < T::Struct
+      const :id, String
+      const :url, String
+      const :title, T.nilable(String)
+      const :score, T.nilable(Float)
+      const :published_date, T.nilable(String)
+      const :author, T.nilable(String)
+      const :text, T.nilable(String)
+      const :highlights, T.nilable(T::Array[String])
+      const :summary, T.nilable(String)
+      const :image, T.nilable(String)
+      const :favicon, T.nilable(String)
+    end
+
+    class CostBreakdown < T::Struct
+      const :neural_search, T.nilable(Float)
+      const :deep_search, T.nilable(Float)
+      const :content_text, T.nilable(Float)
+      const :content_highlight, T.nilable(Float)
+      const :content_summary, T.nilable(Float)
+    end
+
+    class CostData < T::Struct
+      const :total, Float
+      const :search, T.nilable(Float)
+      const :contents, T.nilable(Float)
+      const :breakdown, T.nilable(CostBreakdown)
+    end
+
+    class SearchResponseData < T::Struct
+      const :request_id, T.nilable(String)
+      const :results, T::Array[SearchResultData]
+      const :cost_dollars, T.nilable(CostData)
+    end
+
+    class AnswerResponseData < T::Struct
+      const :answer, String
+      const :citations, T::Array[SearchResultData]
+      const :cost_dollars, T.nilable(CostData)
+    end
+
+    class ResearchTaskData < T::Struct
+      const :research_id, String
+      const :model, String
+      const :instructions, String
+      const :status, String
+      const :created_at, T.nilable(Integer)
+      const :completed_at, T.nilable(Integer)
+      const :output, T.nilable(T.any(String, T::Hash[Symbol, T.untyped]))
+      const :error, T.nilable(String)
+    end
+
+    # Websets types
+    class WebsetData < T::Struct
+      const :id, String
+      const :object, String
+      const :status, String
+      const :external_id, T.nilable(String)
+      const :title, T.nilable(String)
+      const :metadata, T.nilable(T::Hash[Symbol, T.untyped])
+      const :created_at, T.nilable(String)
+      const :updated_at, T.nilable(String)
+    end
+
+    class WebsetItemData < T::Struct
+      const :id, String
+      const :object, String
+      const :webset_id, String
+      const :url, String
+      const :type, T.nilable(String)
+      const :status, T.nilable(String)
+      const :created_at, T.nilable(String)
+    end
+
+    class MonitorData < T::Struct
+      const :id, String
+      const :object, String
+      const :status, String
+      const :webset_id, String
+      const :cron, T.nilable(String)
+      const :timezone, T.nilable(String)
+      const :next_run_at, T.nilable(String)
+      const :created_at, T.nilable(String)
+    end
+
+    class ImportData < T::Struct
+      const :id, String
+      const :object, String
+      const :status, String
+      const :format, String
+      const :title, T.nilable(String)
+      const :count, T.nilable(Integer)
+      const :upload_url, T.nilable(String)
+      const :upload_valid_until, T.nilable(String)
+      const :created_at, T.nilable(String)
+    end
+
+    class WebhookData < T::Struct
+      const :id, String
+      const :object, String
+      const :status, String
+      const :url, String
+      const :events, T::Array[String]
+      const :secret, T.nilable(String)
+      const :created_at, T.nilable(String)
+    end
+
+    class EventData < T::Struct
+      const :id, String
+      const :object, String
+      const :type, String
+      const :data, T::Hash[Symbol, T.untyped]
+      const :created_at, T.nilable(String)
+    end
+
+    # Pagination types
+    class PaginatedResponseData < T::Struct
+      const :data, T::Array[T.untyped]
+      const :has_more, T.nilable(T::Boolean)
+      const :next_cursor, T.nilable(String)
+    end
+
+    # Type aliases for common patterns
+    SearchType = T.type_alias { T.any(String, Symbol) }
+    LivecrawlOption = T.type_alias { T.any(String, Symbol) }
+    DateInput = T.type_alias { T.any(String, Time, Date) }
+
+    # Valid enum values
+    SEARCH_TYPES = T.let(%w[auto neural fast deep].freeze, T::Array[String])
+    LIVECRAWL_OPTIONS = T.let(%w[never fallback preferred always].freeze, T::Array[String])
+    CATEGORIES = T.let(%w[
+      company person research_paper news pdf github tweet 
+      personal_site financial_report
+    ].freeze, T::Array[String])
+    RESEARCH_MODELS = T.let(%w[exa-research-fast exa-research exa-research-pro].freeze, T::Array[String])
+    WEBSET_STATUSES = T.let(%w[idle pending running paused].freeze, T::Array[String])
+    IMPORT_STATUSES = T.let(%w[pending processing completed failed].freeze, T::Array[String])
+    MONITOR_STATUSES = T.let(%w[enabled disabled].freeze, T::Array[String])
+
+    WEBHOOK_EVENTS = T.let(%w[
+      webset.created webset.deleted webset.paused webset.idle
+      webset.search.created webset.search.canceled webset.search.completed webset.search.updated
+      import.created import.completed
+      webset.item.created webset.item.enriched
+      monitor.created monitor.updated monitor.deleted
+      monitor.run.created monitor.run.completed
+      webset.export.created webset.export.completed
+    ].freeze, T::Array[String])
+  end
+end