hindsight-ruby 0.1.0

data/lib/hindsight/resources/banks.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Banks < Base
+      BANK_PAYLOAD_KEYS = %i[
+        name
+        mission
+        reflect_mission
+        disposition
+        disposition_skepticism
+        disposition_literalism
+        disposition_empathy
+        skepticism
+        literalism
+        empathy
+        enable_observations
+        observations_mission
+        retain_mission
+        retain_extraction_mode
+        retain_custom_instructions
+        retain_chunk_size
+      ].freeze
+
+      endpoint :list, method: :get, path: '' do |params|
+        {
+          query: {
+            **extract_pagination!(params)
+          }
+        }
+      end
+
+      def get(bank_id)
+        id = normalize_required_id(bank_id, key: :bank_id)
+        request_json(:get, '/%{bank_id}/profile', path_params: { bank_id: id })
+      end
+
+      def stats(bank_id)
+        id = normalize_required_id(bank_id, key: :bank_id)
+        request_json(:get, '/%{bank_id}/stats', path_params: { bank_id: id })
+      end
+
+      endpoint :create, method: :put, path: '/%{bank_id}' do |params|
+        bank_id = normalize_required_id(params.delete(:bank_id), key: :bank_id)
+        body = normalize_bank_payload(extract_bank_payload!(params))
+        { path_params: { bank_id: bank_id }, body: body }
+      end
+
+      endpoint :update, method: :patch, path: '/%{bank_id}' do |params|
+        bank_id = normalize_required_id(params.delete(:bank_id), key: :bank_id)
+        body = normalize_bank_payload(extract_bank_payload!(params))
+        { path_params: { bank_id: bank_id }, body: body }
+      end
+
+      def delete(bank_id)
+        id = normalize_required_id(bank_id, key: :bank_id)
+        request_json(:delete, '/%{bank_id}', path_params: { bank_id: id })
+      end
+
+      private
+
+      def extract_bank_payload!(params)
+        BANK_PAYLOAD_KEYS.each_with_object({}) do |key, attributes|
+          next unless params.key?(key)
+
+          attributes[key] = params.delete(key)
+        end
+      end
+
+      def normalize_bank_payload(attributes)
+        payload = Types::Payload.stringify_keys(attributes || {})
+        normalize_disposition!(payload)
+        normalize_disposition_traits!(payload)
+        normalize_observations_flag!(payload)
+        normalize_extraction_mode!(payload)
+        normalize_chunk_size!(payload)
+
+        payload.compact
+      end
+
+      def normalize_disposition!(payload)
+        return unless payload.key?('disposition')
+
+        payload['disposition'] = OptionValidation.normalize_disposition(payload['disposition'], key: :disposition)
+      end
+
+      def normalize_disposition_traits!(payload)
+        %w[skepticism literalism empathy].each do |trait|
+          api_key = "disposition_#{trait}"
+          if payload.key?(trait) && payload.key?(api_key)
+            raise ValidationError,
+                  "Conflicting disposition keys: provide either #{trait} or #{api_key}, not both"
+          end
+          payload[api_key] = payload.delete(trait) if payload.key?(trait) && !payload.key?(api_key)
+          payload.delete(trait)
+          next unless payload.key?(api_key) && !payload[api_key].nil?
+
+          payload[api_key] = OptionValidation.normalize_integer_in_range(
+            payload[api_key], key: api_key.to_sym, minimum: 1, maximum: 5
+          )
+        end
+      end
+
+      def normalize_observations_flag!(payload)
+        return unless payload.key?('enable_observations')
+
+        payload['enable_observations'] =
+          OptionValidation.normalize_boolean(payload['enable_observations'], key: :enable_observations)
+      end
+
+      def normalize_extraction_mode!(payload)
+        return unless payload.key?('retain_extraction_mode') && !payload['retain_extraction_mode'].nil?
+
+        payload['retain_extraction_mode'] =
+          OptionValidation.normalize_extraction_mode(payload['retain_extraction_mode']).to_s
+      end
+
+      def normalize_chunk_size!(payload)
+        return unless payload.key?('retain_chunk_size') && !payload['retain_chunk_size'].nil?
+
+        payload['retain_chunk_size'] =
+          OptionValidation.normalize_positive_integer(payload['retain_chunk_size'], key: :retain_chunk_size)
+      end
+
+    end
+  end
+end

data/lib/hindsight/resources/base.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../option_validation'
+
+module Hindsight
+  module Resources
+    class Base
+      def self.endpoint(name, method:, path:, &builder)
+        path_keys = path.scan(/%\{([a-zA-Z0-9_]+)\}/).flatten.map(&:to_sym).uniq.freeze
+
+        define_method(name) do |*args, **kwargs|
+          params = normalize_endpoint_params(name, args, kwargs, path_keys)
+          specification = builder ? instance_exec(params, &builder) : {}
+          specification = {} if specification.nil?
+          unless specification.is_a?(Hash)
+            raise ValidationError, "Invalid endpoint definition for #{self.class}##{name}: expected Hash"
+          end
+
+          ensure_no_unknown_kwargs!(params)
+
+          request_json(
+            method,
+            path,
+            path_params: specification[:path_params] || {},
+            query: specification[:query] || {},
+            body: specification[:body]
+          )
+        end
+      end
+
+      attr_reader :client, :base_path
+
+      def initialize(client:, base_path:)
+        @client = client
+        @base_path = base_path
+      end
+
+      private
+
+      def request_json(method, path_template, path_params: nil, query: nil, body: nil)
+        path = interpolate_path(path_template, path_params || {})
+        normalized_query = normalize_query_hash(query || {})
+        client.request_json(method, "#{base_path}#{path}", body, query: normalized_query)
+      end
+
+      def interpolate_path(template, values)
+        template.gsub(/%\{([a-zA-Z0-9_]+)\}/) do
+          key = Regexp.last_match(1).to_sym
+          raise ValidationError, "Missing required path parameter: #{key}" unless values.key?(key)
+
+          client.escape(values.fetch(key))
+        end
+      end
+
+      def normalize_query_hash(params)
+        params.each_with_object({}) do |(key, value), normalized|
+          next if value.nil?
+
+          normalized[key.to_s] = normalize_query_value(value)
+        end
+      end
+
+      def normalize_query_value(value)
+        if value.is_a?(Array)
+          value.compact.map(&:to_s)
+        else
+          value.to_s
+        end
+      end
+
+      def ensure_no_unknown_kwargs!(kwargs)
+        return if kwargs.empty?
+
+        raise ValidationError, "Unknown keyword arguments: #{kwargs.keys.join(', ')}"
+      end
+
+      def normalize_endpoint_params(name, args, kwargs, path_keys)
+        raise ValidationError, "Invalid arguments for #{self.class}##{name}: expected at most one positional argument" if args.length > 1
+        return kwargs.dup if args.empty?
+        unless kwargs.empty?
+          raise ValidationError,
+                "Invalid arguments for #{self.class}##{name}: cannot mix positional and keyword arguments"
+        end
+
+        arg = args.first
+        if arg.is_a?(Hash)
+          return arg.each_with_object({}) do |(key, value), params|
+            params[key.to_sym] = value
+          end
+        end
+
+        return { path_keys.first => arg } if path_keys.length == 1
+
+        raise ValidationError, "Invalid arguments for #{self.class}##{name}: expected keyword arguments"
+      end
+
+      def normalize_required_id(value, key:)
+        OptionValidation.normalize_non_empty_string(value, key: key)
+      end
+
+      def normalize_fact_type_filter(value)
+        OptionValidation.normalize_fact_type(value, key: :type)&.to_s
+      end
+
+      def normalize_tags_match(value)
+        OptionValidation.normalize_tags_match(value, key: :tags_match)&.to_s
+      end
+
+      def extract_pagination!(params)
+        {
+          limit: OptionValidation.normalize_optional_positive_integer(params.delete(:limit), key: :limit),
+          offset: OptionValidation.normalize_optional_non_negative_integer(params.delete(:offset), key: :offset)
+        }
+      end
+    end
+  end
+end

data/lib/hindsight/resources/chunks.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hindsight
+  module Resources
+    class Chunks < Base
+      def get(chunk_id)
+        id = normalize_required_id(chunk_id, key: :chunk_id)
+        request_json(:get, '/chunks/%{chunk_id}', path_params: { chunk_id: id })
+      end
+    end
+  end
+end

data/lib/hindsight/resources/config.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Config < Base
+      endpoint :get, method: :get, path: '/config'
+
+      endpoint :patch, method: :patch, path: '/config' do |params|
+        {
+          body: {
+            updates: OptionValidation.normalize_required_hash(params.delete(:updates), key: :updates)
+          }
+        }
+      end
+
+      endpoint :reset, method: :delete, path: '/config'
+    end
+  end
+end

data/lib/hindsight/resources/directives.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Directives < Base
+      endpoint :list, method: :get, path: '/directives' do |params|
+        active_only = params.delete(:active_only)
+        {
+          query: {
+            tags: OptionValidation.normalize_tags(params.delete(:tags)),
+            tags_match: normalize_tags_match(params.delete(:tags_match)),
+            active_only: OptionValidation.normalize_optional_boolean(active_only, key: :active_only),
+            **extract_pagination!(params)
+          }
+        }
+      end
+
+      endpoint :create, method: :post, path: '/directives' do |params|
+        active = params.delete(:is_active)
+        {
+          body: {
+            name: OptionValidation.normalize_non_empty_string(params.delete(:name), key: :name),
+            content: OptionValidation.normalize_non_empty_string(params.delete(:content), key: :content),
+            priority: OptionValidation.normalize_optional_integer(params.delete(:priority), key: :priority),
+            is_active: OptionValidation.normalize_optional_boolean(active, key: :is_active),
+            tags: OptionValidation.normalize_tags(params.delete(:tags))
+          }.compact
+        }
+      end
+
+      def get(directive_id)
+        id = normalize_required_id(directive_id, key: :directive_id)
+        request_json(:get, '/directives/%{directive_id}', path_params: { directive_id: id })
+      end
+
+      endpoint :update, method: :patch, path: '/directives/%{directive_id}' do |params|
+        active = params.delete(:is_active)
+        {
+          path_params: { directive_id: normalize_required_id(params.delete(:directive_id), key: :directive_id) },
+          body: {
+            name: OptionValidation.normalize_optional_non_empty_string(params.delete(:name), key: :name),
+            content: OptionValidation.normalize_optional_non_empty_string(params.delete(:content), key: :content),
+            priority: OptionValidation.normalize_optional_integer(params.delete(:priority), key: :priority),
+            is_active: OptionValidation.normalize_optional_boolean(active, key: :is_active),
+            tags: OptionValidation.normalize_tags(params.delete(:tags))
+          }.compact
+        }
+      end
+
+      def delete(directive_id)
+        id = normalize_required_id(directive_id, key: :directive_id)
+        request_json(:delete, '/directives/%{directive_id}', path_params: { directive_id: id })
+      end
+    end
+  end
+end

data/lib/hindsight/resources/documents.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Documents < Base
+      endpoint :list, method: :get, path: '/documents' do |params|
+        {
+          query: {
+            q: OptionValidation.normalize_optional_non_empty_string(params.delete(:q), key: :q),
+            tags: OptionValidation.normalize_tags(params.delete(:tags)),
+            tags_match: normalize_tags_match(params.delete(:tags_match)),
+            **extract_pagination!(params)
+          }
+        }
+      end
+
+      def get(document_id)
+        id = normalize_required_id(document_id, key: :document_id)
+        request_json(:get, '/documents/%{document_id}', path_params: { document_id: id })
+      end
+
+      def delete(document_id)
+        id = normalize_required_id(document_id, key: :document_id)
+        request_json(:delete, '/documents/%{document_id}', path_params: { document_id: id })
+      end
+    end
+  end
+end

data/lib/hindsight/resources/entities.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Entities < Base
+      endpoint :list, method: :get, path: '/entities' do |params|
+        {
+          query: {
+            **extract_pagination!(params)
+          }
+        }
+      end
+
+      def get(entity_id)
+        id = normalize_required_id(entity_id, key: :entity_id)
+        request_json(:get, '/entities/%{entity_id}', path_params: { entity_id: id })
+      end
+
+      def regenerate(entity_id)
+        id = normalize_required_id(entity_id, key: :entity_id)
+        request_json(:post, '/entities/%{entity_id}/regenerate', path_params: { entity_id: id })
+      end
+    end
+  end
+end

data/lib/hindsight/resources/graph.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Graph < Base
+      endpoint :get, method: :get, path: '/graph' do |params|
+        {
+          query: {
+            type: OptionValidation.normalize_optional_non_empty_string(params.delete(:type), key: :type),
+            q: OptionValidation.normalize_optional_non_empty_string(params.delete(:q), key: :q),
+            tags: OptionValidation.normalize_tags(params.delete(:tags)),
+            tags_match: normalize_tags_match(params.delete(:tags_match)),
+            limit: OptionValidation.normalize_optional_positive_integer(params.delete(:limit), key: :limit)
+          }
+        }
+      end
+    end
+  end
+end

data/lib/hindsight/resources/memories.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Memories < Base
+      endpoint :list, method: :get, path: '/memories/list' do |params|
+        {
+          query: {
+            type: normalize_fact_type_filter(params.delete(:type)),
+            q: OptionValidation.normalize_optional_non_empty_string(params.delete(:q), key: :q),
+            **extract_pagination!(params)
+          }
+        }
+      end
+
+      def get(memory_id)
+        id = normalize_required_id(memory_id, key: :memory_id)
+        request_json(:get, '/memories/%{memory_id}', path_params: { memory_id: id })
+      end
+
+      endpoint :delete, method: :delete, path: '/memories' do |params|
+        {
+          query: { type: normalize_fact_type_filter(params.delete(:type)) }
+        }
+      end
+    end
+  end
+end

data/lib/hindsight/resources/mental_models.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class MentalModels < Base
+      endpoint :list, method: :get, path: '/mental-models' do |params|
+        {
+          query: {
+            tags: OptionValidation.normalize_tags(params.delete(:tags)),
+            tags_match: normalize_tags_match(params.delete(:tags_match)),
+            **extract_pagination!(params)
+          }
+        }
+      end
+
+      endpoint :create, method: :post, path: '/mental-models' do |params|
+        {
+          body: {
+            id: OptionValidation.normalize_optional_non_empty_string(params.delete(:id), key: :id),
+            name: OptionValidation.normalize_non_empty_string(params.delete(:name), key: :name),
+            source_query: OptionValidation.normalize_non_empty_string(params.delete(:source_query), key: :source_query),
+            tags: OptionValidation.normalize_tags(params.delete(:tags)),
+            max_tokens: OptionValidation.normalize_optional_positive_integer(params.delete(:max_tokens),
+                                                                             key: :max_tokens),
+            trigger: OptionValidation.normalize_hash(params.delete(:trigger), key: :trigger)
+          }.compact
+        }
+      end
+
+      def get(mental_model_id)
+        id = normalize_required_id(mental_model_id, key: :mental_model_id)
+        request_json(:get, '/mental-models/%{mental_model_id}', path_params: { mental_model_id: id })
+      end
+
+      endpoint :update, method: :patch, path: '/mental-models/%{mental_model_id}' do |params|
+        {
+          path_params: {
+            mental_model_id: normalize_required_id(params.delete(:mental_model_id), key: :mental_model_id)
+          },
+          body: {
+            name: OptionValidation.normalize_optional_non_empty_string(params.delete(:name), key: :name),
+            source_query: OptionValidation.normalize_optional_non_empty_string(params.delete(:source_query),
+                                                                               key: :source_query),
+            tags: OptionValidation.normalize_tags(params.delete(:tags)),
+            max_tokens: OptionValidation.normalize_optional_positive_integer(params.delete(:max_tokens),
+                                                                             key: :max_tokens),
+            trigger: OptionValidation.normalize_hash(params.delete(:trigger), key: :trigger)
+          }.compact
+        }
+      end
+
+      def delete(mental_model_id)
+        id = normalize_required_id(mental_model_id, key: :mental_model_id)
+        request_json(:delete, '/mental-models/%{mental_model_id}', path_params: { mental_model_id: id })
+      end
+
+      def refresh(mental_model_id)
+        id = normalize_required_id(mental_model_id, key: :mental_model_id)
+        request_json(:post, '/mental-models/%{mental_model_id}/refresh', path_params: { mental_model_id: id })
+      end
+    end
+  end
+end

data/lib/hindsight/resources/observations.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Observations < Base
+      endpoint :delete, method: :delete, path: '/observations'
+
+      def delete_for_memory(memory_id)
+        id = normalize_required_id(memory_id, key: :memory_id)
+        request_json(:delete, '/memories/%{memory_id}/observations', path_params: { memory_id: id })
+      end
+    end
+  end
+end

data/lib/hindsight/resources/operations.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../types/operation_status'
+
+module Hindsight
+  module Resources
+    class Operations < Base
+      VALID_BACKOFF_MODES = %i[fixed exponential].freeze
+
+      endpoint :list, method: :get, path: '/operations' do |params|
+        {
+          query: {
+            status: OptionValidation.normalize_optional_non_empty_string(params.delete(:status), key: :status),
+            **extract_pagination!(params)
+          }
+        }
+      end
+
+      def get(operation_id)
+        id = normalize_required_id(operation_id, key: :operation_id)
+        body = request_json(:get, '/operations/%{operation_id}', path_params: { operation_id: id })
+        Types::OperationStatus.from_api(body, operation_id: id)
+      end
+
+      def wait(operation_ids, interval: 1.0, timeout: 120.0, backoff: :exponential, max_interval: 30.0)
+        ids = normalize_operation_ids(operation_ids)
+        interval_seconds = OptionValidation.normalize_positive_number(interval, key: :interval)
+        timeout_seconds = OptionValidation.normalize_positive_number(timeout, key: :timeout)
+        max_interval_seconds = OptionValidation.normalize_positive_number(max_interval, key: :max_interval)
+        backoff_mode = OptionValidation.normalize_enum(backoff, key: :backoff, valid: VALID_BACKOFF_MODES)
+        deadline = monotonic_now + timeout_seconds
+
+        completed = {}
+        pending_ids = ids.dup
+        attempts = 0
+
+        loop do
+          cycle_start = monotonic_now
+          statuses = pending_ids.map { |id| get(id) }
+          statuses.each do |status|
+            completed[status.id] = status if status.terminal?
+          end
+          pending_ids = pending_ids.reject { |id| completed.key?(id) }
+          return ids.map { |id| completed[id] } if pending_ids.empty?
+
+          now = monotonic_now
+          raise TimeoutError, "Timed out waiting for operations: #{pending_ids.join(', ')}" if now >= deadline
+
+          elapsed = now - cycle_start
+          cycle_interval = next_interval_seconds(
+            attempts: attempts,
+            interval_seconds: interval_seconds,
+            max_interval_seconds: max_interval_seconds,
+            backoff_mode: backoff_mode
+          )
+          remaining_interval = cycle_interval - elapsed
+          remaining_timeout = deadline - now
+          sleep_seconds = [remaining_interval, remaining_timeout].min
+          sleep(sleep_seconds) if sleep_seconds.positive?
+          attempts += 1
+        end
+      end
+
+      def cancel(operation_id)
+        id = normalize_required_id(operation_id, key: :operation_id)
+        request_json(:delete, '/operations/%{operation_id}', path_params: { operation_id: id })
+      end
+
+      private
+
+      def normalize_operation_ids(operation_ids)
+        ids = Array(operation_ids).flatten.compact.map do |operation_id|
+          normalize_required_id(operation_id, key: :operation_id)
+        end
+        return ids unless ids.empty?
+
+        raise ValidationError, 'operation_ids must contain at least one entry'
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def next_interval_seconds(attempts:, interval_seconds:, max_interval_seconds:, backoff_mode:)
+        return interval_seconds if backoff_mode == :fixed
+
+        [interval_seconds * (2**attempts), max_interval_seconds].min
+      end
+    end
+  end
+end

data/lib/hindsight/resources/tags.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Hindsight
+  module Resources
+    class Tags < Base
+      endpoint :list, method: :get, path: '/tags' do |params|
+        {
+          query: {
+            q: OptionValidation.normalize_optional_non_empty_string(params.delete(:q), key: :q),
+            **extract_pagination!(params)
+          }
+        }
+      end
+    end
+  end
+end