hindsight-ruby 0.1.0

data/lib/hindsight/client.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'json'
+require 'uri'
+require 'faraday'
+require 'faraday/multipart'
+require_relative 'errors'
+require_relative 'option_validation'
+
+module Hindsight
+  class Client
+    ALLOWED_HTTP_METHODS = %i[get post put patch delete head options].freeze
+    FEATURE_PROBE_FAILURE_COOLDOWN_SECONDS = 5.0
+    LOGGER_SENSITIVE_HEADERS = %w[
+      Authorization
+      Proxy-Authorization
+      Cookie
+      Set-Cookie
+      X-Api-Key
+      X-Auth-Token
+      Api-Key
+      X-Webhook-Secret
+    ].freeze
+
+    attr_reader :base_url
+
+    def initialize(
+      base_url,
+      api_key: nil,
+      headers: nil,
+      open_timeout: 10,
+      timeout: 30,
+      logger: nil,
+      connection: nil,
+      allow_insecure: false
+    )
+      @base_url = OptionValidation.normalize_non_empty_string(base_url, key: :base_url)
+      validate_url_scheme!
+      @api_key = OptionValidation.normalize_optional_non_empty_string(api_key, key: :api_key)
+      @default_headers = normalize_headers(headers)
+      @default_headers['Authorization'] = "Bearer #{@api_key}" if @api_key
+      @open_timeout = open_timeout
+      @timeout = timeout
+      @logger = logger
+      @allow_insecure = OptionValidation.normalize_boolean(allow_insecure, key: :allow_insecure)
+      validate_insecure_transport!
+      warn_insecure_transport
+      @connection = connection || build_connection
+      @feature_mutex = Mutex.new
+      @feature_probe_error_until = nil
+    end
+
+    def marshal_dump
+      raise TypeError, "#{self.class} cannot be serialized (contains credentials)"
+    end
+
+    def inspect
+      "#<#{self.class} base_url=#{@base_url.inspect} api_key=[REDACTED]>"
+    end
+
+    def bank(bank_id)
+      Bank.new(client: self, bank_id: bank_id)
+    end
+
+    def banks
+      @banks ||= Resources::Banks.new(client: self, base_path: '/v1/default/banks')
+    end
+
+    def chunks
+      @chunks ||= Resources::Chunks.new(client: self, base_path: '/v1/default')
+    end
+
+    def version
+      request_json(:get, '/version')
+    end
+
+    def health
+      request_json(:get, '/health')
+    end
+
+    def features
+      payload = version
+      payload['features'] || {}
+    rescue APIError => e
+      raise if auth_api_error?(e)
+
+      {}
+    end
+
+    def file_upload_api_supported?
+      @feature_mutex.synchronize do
+        return @file_upload_api_supported unless @file_upload_api_supported.nil?
+        return nil if @feature_probe_error_until && monotonic_now < @feature_probe_error_until
+
+        payload = version
+        value = (payload['features'] || {})['file_upload_api']
+        # Cache false when the flag is missing to avoid repeated /version calls.
+        @file_upload_api_supported = (value == true)
+        @feature_probe_error_until = nil
+        @file_upload_api_supported
+      rescue APIError => e
+        raise if auth_api_error?(e)
+
+        # Treat API failures as unknown, and retry on next call.
+        nil
+      rescue TimeoutError, ConnectionError
+        @feature_probe_error_until = monotonic_now + FEATURE_PROBE_FAILURE_COOLDOWN_SECONDS
+        nil
+      end
+    end
+
+    def retain_json(bank_path, payload)
+      request_json(:post, "#{bank_path}/memories", payload)
+    end
+
+    def request_json(method, path, payload = nil, query: nil)
+      validate_http_method!(method)
+      wrap_faraday_errors do
+        response = connection.public_send(method, path) do |req|
+          req.headers.update(@default_headers) unless @default_headers.empty?
+          configure_request_options(req)
+          req.params.update(query) if query && !query.empty?
+          req.body = payload unless payload.nil?
+        end
+
+        validate_json_body(response)
+      end
+    end
+
+    def request_multipart_files(method, path, uploads, extra_fields: {})
+      validate_http_method!(method)
+      payload = extra_fields.merge(
+        files: uploads.map { |u| Faraday::Multipart::FilePart.new(u[:io], u[:content_type], u[:filename]) }
+      )
+      wrap_faraday_errors do
+        response = connection.public_send(method, path) do |req|
+          req.headers.update(@default_headers) unless @default_headers.empty?
+          configure_request_options(req)
+          req.body = payload
+        end
+
+        validate_json_body(response)
+      end
+    end
+
+    def escape(value)
+      CGI.escape(value.to_s).gsub('+', '%20')
+    end
+
+    private
+
+    attr_reader :connection
+
+    def build_connection
+      Faraday.new(url: base_url) do |faraday|
+        faraday.options.params_encoder = Faraday::FlatParamsEncoder
+        faraday.headers.update(@default_headers) unless @default_headers.empty?
+        # Send repeated multipart keys as `files`, not `files[]`.
+        faraday.request :multipart, flat_encode: true
+        faraday.request :json
+        faraday.response :json, content_type: /json/
+        if @logger
+          faraday.response :logger, @logger, headers: true, bodies: false do |log|
+            sensitive_log_header_names.each do |header_name|
+              log.filter(/^(\s*#{Regexp.escape(header_name)}:\s*)(.*)$/i, '\1[REDACTED]')
+            end
+          end
+        end
+        faraday.response :raise_error
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def wrap_faraday_errors
+      yield
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Hindsight request timed out: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Hindsight connection failed: #{e.message}"
+    rescue Faraday::Error => e
+      raise_api_error(e)
+    end
+
+    def configure_request_options(req)
+      req.options.open_timeout = @open_timeout if @open_timeout
+      req.options.timeout = @timeout if @timeout
+    end
+
+    def validate_http_method!(method)
+      return if method.respond_to?(:to_sym) && ALLOWED_HTTP_METHODS.include?(method.to_sym)
+
+      raise ValidationError,
+            "Invalid HTTP method: #{method.inspect}. Expected one of #{ALLOWED_HTTP_METHODS.join(', ')}"
+    end
+
+    def normalize_headers(value)
+      return {} if value.nil?
+      raise ValidationError, "Invalid headers: #{value.inspect}. Expected a Hash" unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, header_value), headers|
+        raw_name = String(key)
+        raise ValidationError, "Invalid header name: #{raw_name.inspect}" if raw_name.match?(/[\r\n\0]/)
+
+        name = raw_name.strip
+        raise ValidationError, 'headers keys must not be empty' if name.empty?
+
+        str_value = String(header_value)
+        raise ValidationError, "Invalid header value for #{name}" if str_value.match?(/[\r\n\0]/)
+
+        headers[name] = str_value
+      rescue TypeError
+        raise ValidationError,
+              "Invalid header #{key.inspect}: #{header_value.inspect}. Expected string-like key/value"
+      end
+    end
+
+    def validate_json_body(response)
+      body = response.body
+      return body if body.is_a?(Hash)
+      return {} if body.nil?
+
+      raise APIError.new(
+        "Unexpected response: expected JSON object, got #{body.class}. " \
+        'If you injected a custom connection:, ensure it includes the :json response middleware.',
+        status: response.status,
+        body: body
+      )
+    end
+
+    def raise_api_error(error)
+      status = error.response && error.response[:status]
+      body = error.response && error.response[:body]
+      status_label = status.nil? ? 'unknown' : status
+      raise APIError.new(
+        "Hindsight API error (status #{status_label})",
+        status: status,
+        body: body
+      )
+    end
+
+    def validate_url_scheme!
+      raise ValidationError, 'base_url contains invalid characters' if @base_url.match?(/[\r\n\0]/)
+      uri = URI.parse(@base_url)
+      has_http_scheme = uri.is_a?(URI::HTTP)
+      has_host = !uri.host.to_s.strip.empty?
+      return if has_http_scheme && has_host
+
+      raise ValidationError, "base_url must be a valid http(s) URL with a host, got: #{@base_url.inspect}"
+    rescue URI::InvalidURIError
+      raise ValidationError, "base_url must be a valid http(s) URL with a host, got: #{@base_url.inspect}"
+    end
+
+    def validate_insecure_transport!
+      return unless insecure_transport_with_credentials?
+      return if @allow_insecure || localhost_base_url?
+
+      raise ValidationError,
+            'Refusing to send credentials over insecure http:// transport. ' \
+            'Use https:// or pass allow_insecure: true to override.'
+    end
+
+    def warn_insecure_transport
+      return unless insecure_transport_with_credentials?
+
+      warn '[Hindsight] WARNING: Credentials detected with an http:// base_url. ' \
+           'Credentials will be sent in plain text. Use https:// in production.'
+    end
+
+    def insecure_transport_with_credentials?
+      @base_url.match?(%r{\Ahttp://}i) &&
+        (@api_key || @default_headers&.keys&.any? { |k| k.match?(/\Aauthorization\z/i) })
+    end
+
+    def localhost_base_url?
+      host = URI.parse(@base_url).host&.downcase
+      %w[localhost 127.0.0.1 ::1].include?(host)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def auth_api_error?(error)
+      [401, 403].include?(Integer(error.status))
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    def sensitive_log_header_names
+      (LOGGER_SENSITIVE_HEADERS + @default_headers.keys).uniq
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/hindsight/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hindsight
+  class Error < StandardError
+    def retriable? = false
+  end
+
+  class ValidationError < Error; end
+
+  class ConnectionError < Error
+    def retriable? = true
+  end
+
+  class TimeoutError < Error
+    def retriable? = true
+  end
+
+  class FeatureNotSupported < Error; end
+
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+
+    def retriable?
+      return true if status.nil?
+
+      code = status.to_i
+      code >= 500 || code == 429
+    end
+  end
+end

data/lib/hindsight/option_validation.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Hindsight
+  module OptionValidation
+    module_function
+
+    VALID_BUDGETS = %i[low mid high].freeze
+    VALID_FACT_TYPES = %i[world experience observation].freeze
+    VALID_TAG_MATCH_MODES = %i[any all exact all_strict].freeze
+    VALID_EXTRACTION_MODES = %i[concise verbose custom].freeze
+
+    def normalize_enum(value, key:, valid:)
+      symbol = normalize_symbol(value, key: key)
+      return symbol if valid.include?(symbol)
+
+      raise ValidationError,
+            "Invalid #{key}: #{value.inspect}. Expected one of #{valid.join(', ')}"
+    end
+
+    def normalize_budget(value)
+      normalize_enum(value, key: :budget, valid: VALID_BUDGETS)
+    end
+
+    def normalize_symbol(value, key:)
+      return nil if value.nil?
+      return value.to_sym if value.respond_to?(:to_sym)
+
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected symbol or string"
+    end
+
+    def normalize_positive_integer(value, key:)
+      int = Integer(value)
+      return int if int.positive?
+
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected a positive integer"
+    rescue ArgumentError, TypeError
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected a positive integer"
+    end
+
+    def normalize_non_negative_integer(value, key:)
+      int = Integer(value)
+      return int if int >= 0
+
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected a non-negative integer"
+    rescue ArgumentError, TypeError
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected a non-negative integer"
+    end
+
+    def normalize_integer_in_range(value, key:, minimum:, maximum:)
+      int = Integer(value)
+      return int if int.between?(minimum, maximum)
+
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected an integer between #{minimum} and #{maximum}"
+    rescue ArgumentError, TypeError
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected an integer between #{minimum} and #{maximum}"
+    end
+
+    def normalize_positive_number(value, key:)
+      number = Float(value)
+      return number if number.positive?
+
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected a positive number"
+    rescue ArgumentError, TypeError
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected a positive number"
+    end
+
+    def normalize_tags(value)
+      return nil if value.nil?
+      raise ValidationError, "Invalid tags: #{value.inspect}. Expected an Array" unless value.is_a?(Array)
+
+      value.map do |tag|
+        unless tag.is_a?(String) || tag.is_a?(Symbol)
+          raise ValidationError, "Invalid tag: #{tag.inspect}. Expected a String or Symbol"
+        end
+
+        tag.to_s
+      end
+    end
+
+    def normalize_hash(value, key:)
+      return nil if value.nil?
+      return value if value.is_a?(Hash)
+
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected a Hash"
+    end
+
+    def normalize_include_options(value, key: :include)
+      include_options = normalize_hash(value, key: key)
+      return nil if include_options.nil?
+
+      include_options.each_with_object({}) do |(raw_name, raw_options), normalized|
+        name = raw_name.to_s
+
+        case raw_options
+        when nil, false
+          next
+        when true
+          normalized[name] = {}
+        when Hash
+          normalized[name] = raw_options
+        else
+          raise ValidationError,
+                "Invalid #{key}.#{name}: #{raw_options.inspect}. Expected true, false, nil, or a Hash"
+        end
+      end
+    end
+
+    def normalize_fact_type(value, key: :type)
+      return nil if value.nil?
+
+      normalize_enum(value, key: key, valid: VALID_FACT_TYPES)
+    end
+
+    def normalize_fact_types(value, key: :types)
+      return nil if value.nil?
+
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected an Array" unless value.is_a?(Array)
+
+      value.map do |item|
+        normalize_enum(item, key: key, valid: VALID_FACT_TYPES).to_s
+      end
+    end
+
+    def normalize_non_empty_string(value, key:)
+      string = String(value).strip
+      return string unless string.empty?
+
+      raise ValidationError, "#{key} must not be empty"
+    rescue TypeError
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected a string-like value"
+    end
+
+    def normalize_optional_non_empty_string(value, key:)
+      return nil if value.nil?
+
+      normalize_non_empty_string(value, key: key)
+    end
+
+    def normalize_optional_positive_integer(value, key:)
+      return nil if value.nil?
+
+      normalize_positive_integer(value, key: key)
+    end
+
+    def normalize_optional_non_negative_integer(value, key:)
+      return nil if value.nil?
+
+      normalize_non_negative_integer(value, key: key)
+    end
+
+    def normalize_optional_integer(value, key:)
+      return nil if value.nil?
+
+      Integer(value)
+    rescue ArgumentError, TypeError
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected an integer"
+    end
+
+    def normalize_required_hash(value, key:)
+      hash = normalize_hash(value, key: key)
+      return hash if hash
+
+      raise ValidationError, "#{key} must not be nil"
+    end
+
+    def normalize_boolean(value, key:)
+      return value if [true, false].include?(value)
+
+      raise ValidationError, "Invalid #{key}: #{value.inspect}. Expected true or false"
+    end
+
+    def normalize_optional_boolean(value, key:)
+      return nil if value.nil?
+
+      normalize_boolean(value, key: key)
+    end
+
+    def normalize_tags_match(value, key: :tags_match)
+      return nil if value.nil?
+
+      normalize_enum(value, key: key, valid: VALID_TAG_MATCH_MODES)
+    end
+
+    def normalize_extraction_mode(value, key: :retain_extraction_mode)
+      return nil if value.nil?
+
+      normalize_enum(value, key: key, valid: VALID_EXTRACTION_MODES)
+    end
+
+    def normalize_entities(value)
+      return nil if value.nil?
+      raise ValidationError, "Invalid entities: #{value.inspect}. Expected an Array" unless value.is_a?(Array)
+
+      value.each do |entity|
+        raise ValidationError, "Invalid entity: #{entity.inspect}. Expected a Hash" unless entity.is_a?(Hash)
+
+        text = entity[:text] || entity['text']
+        raise ValidationError, 'Each entity must have a :text key' if text.nil? || String(text).strip.empty?
+      end
+      value
+    end
+
+    def normalize_files_metadata(value)
+      return nil if value.nil?
+      raise ValidationError, "Invalid files_metadata: #{value.inspect}. Expected an Array" unless value.is_a?(Array)
+
+      value.each do |entry|
+        unless entry.is_a?(Hash)
+          raise ValidationError,
+                "Invalid files_metadata entry: #{entry.inspect}. Expected a Hash"
+        end
+      end
+      value
+    end
+
+    def normalize_query(value, key: :query)
+      string = String(value)
+      return string unless string.strip.empty?
+
+      raise ValidationError, "#{key} must not be empty"
+    end
+
+    def normalize_response_schema(value, key: :response_schema)
+      return nil if value.nil?
+      return value if value.is_a?(Hash)
+      return value.to_json_schema if value.respond_to?(:to_json_schema)
+
+      raise ValidationError,
+            "Invalid #{key}: expected a Hash or object responding to #to_json_schema"
+    end
+
+    def normalize_disposition(value, key: :disposition)
+      disposition = normalize_hash(value, key: key)
+      return nil if disposition.nil?
+
+      skepticism = disposition[:skepticism] || disposition['skepticism']
+      literalism = disposition[:literalism] || disposition['literalism']
+      empathy = disposition[:empathy] || disposition['empathy']
+
+      missing = []
+      missing << 'skepticism' if skepticism.nil?
+      missing << 'literalism' if literalism.nil?
+      missing << 'empathy' if empathy.nil?
+      raise ValidationError, "Invalid #{key}: missing #{missing.join(', ')}" unless missing.empty?
+
+      {
+        skepticism: normalize_integer_in_range(skepticism, key: :skepticism, minimum: 1, maximum: 5),
+        literalism: normalize_integer_in_range(literalism, key: :literalism, minimum: 1, maximum: 5),
+        empathy: normalize_integer_in_range(empathy, key: :empathy, minimum: 1, maximum: 5)
+      }
+    end
+  end
+end