apologist 1.0.2

data/lib/Apologist/corpus/client.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Corpus
+    class Client
+      # @param client [Apologist::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Performs a semantic search across the agent's corpus of knowledge
+      #
+      # @param request_options [Hash]
+      # @param params [Apologist::Corpus::Types::CorpusSearchRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @example
+      #   client.corpus.search_corpus(query: "query")
+      #
+      # @return [Apologist::Corpus::Types::SearchCorpusResponse]
+      def search_corpus(request_options: {}, **params)
+        params = Apologist::Internal::Types::Utils.normalize_keys(params)
+        request = Apologist::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "corpus/search",
+          body: Apologist::Corpus::Types::CorpusSearchRequest.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Apologist::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Apologist::Corpus::Types::SearchCorpusResponse.load(response.body)
+        else
+          error_class = Apologist::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Records that a user viewed a specific corpus item
+      #
+      # @param request_options [Hash]
+      # @param params [Apologist::Corpus::Types::ViewRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :model
+      # @option params [String] :id
+      #
+      # @example
+      #   client.corpus.log_corpus_view(
+      #     model: "model",
+      #     id: "id",
+      #     prompt_id: "prompt_id"
+      #   )
+      #
+      # @return [Apologist::Types::SuccessResponse]
+      def log_corpus_view(request_options: {}, **params)
+        params = Apologist::Internal::Types::Utils.normalize_keys(params)
+        request_data = Apologist::Corpus::Types::ViewRequest.new(params).to_h
+        non_body_param_names = %w[model id]
+        body = request_data.except(*non_body_param_names)
+
+        request = Apologist::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "corpus/#{URI.encode_uri_component(params[:model].to_s)}/#{URI.encode_uri_component(params[:id].to_s)}/view",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Apologist::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Apologist::Types::SuccessResponse.load(response.body)
+        else
+          error_class = Apologist::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Records that a corpus item was shown to a user
+      #
+      # @param request_options [Hash]
+      # @param params [Apologist::Corpus::Types::ImpressionRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :model
+      # @option params [String] :id
+      #
+      # @example
+      #   client.corpus.log_corpus_impression(
+      #     model: "model",
+      #     id: "id",
+      #     prompt_id: "prompt_id"
+      #   )
+      #
+      # @return [Apologist::Types::SuccessResponse]
+      def log_corpus_impression(request_options: {}, **params)
+        params = Apologist::Internal::Types::Utils.normalize_keys(params)
+        request_data = Apologist::Corpus::Types::ImpressionRequest.new(params).to_h
+        non_body_param_names = %w[model id]
+        body = request_data.except(*non_body_param_names)
+
+        request = Apologist::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "corpus/#{URI.encode_uri_component(params[:model].to_s)}/#{URI.encode_uri_component(params[:id].to_s)}/impression",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Apologist::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Apologist::Types::SuccessResponse.load(response.body)
+        else
+          error_class = Apologist::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Records a referral for a corpus item and, when a `url` is supplied, issues a 302 redirect to it. Without a
+      # `url`, responds with a success message. Requires either the search API entitlement or a same-origin request.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :model
+      # @option params [String] :id
+      # @option params [String] :prompt_id
+      # @option params [String, nil] :user_id
+      # @option params [String, nil] :url
+      #
+      # @example
+      #   client.corpus.log_corpus_referral_redirect(
+      #     model: "model",
+      #     id: "id",
+      #     prompt_id: "prompt_id"
+      #   )
+      #
+      # @return [Apologist::Types::SuccessResponse]
+      def log_corpus_referral_redirect(request_options: {}, **params)
+        params = Apologist::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["prompt_id"] = params[:prompt_id] if params.key?(:prompt_id)
+        query_params["user_id"] = params[:user_id] if params.key?(:user_id)
+        query_params["url"] = params[:url] if params.key?(:url)
+
+        request = Apologist::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "corpus/#{URI.encode_uri_component(params[:model].to_s)}/#{URI.encode_uri_component(params[:id].to_s)}/referral",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Apologist::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Apologist::Types::SuccessResponse.load(response.body)
+        else
+          error_class = Apologist::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Records that a user was referred to a corpus item
+      #
+      # @param request_options [Hash]
+      # @param params [Apologist::Corpus::Types::ReferralRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :model
+      # @option params [String] :id
+      #
+      # @example
+      #   client.corpus.log_corpus_referral(
+      #     model: "model",
+      #     id: "id",
+      #     prompt_id: "prompt_id"
+      #   )
+      #
+      # @return [Apologist::Types::SuccessResponse]
+      def log_corpus_referral(request_options: {}, **params)
+        params = Apologist::Internal::Types::Utils.normalize_keys(params)
+        request_data = Apologist::Corpus::Types::ReferralRequest.new(params).to_h
+        non_body_param_names = %w[model id]
+        body = request_data.except(*non_body_param_names)
+
+        request = Apologist::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "corpus/#{URI.encode_uri_component(params[:model].to_s)}/#{URI.encode_uri_component(params[:id].to_s)}/referral",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Apologist::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Apologist::Types::SuccessResponse.load(response.body)
+        else
+          error_class = Apologist::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/Apologist/corpus/types/corpus_search_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Corpus
+    module Types
+      class CorpusSearchRequest < Internal::Types::Model
+        field :query, -> { String }, optional: false, nullable: false
+
+        field :prompt_id, -> { String }, optional: true, nullable: false
+
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :filters, -> { Apologist::Corpus::Types::CorpusSearchRequestFilters }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/corpus/types/corpus_search_request_filters.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Corpus
+    module Types
+      class CorpusSearchRequestFilters < Internal::Types::Model
+        field :model, -> { String }, optional: true, nullable: false
+
+        field :ids, -> { Internal::Types::Array[Integer] }, optional: true, nullable: false
+
+        field :types, -> { Internal::Types::Array[String] }, optional: true, nullable: false
+
+        field :languages, -> { Internal::Types::Array[String] }, optional: true, nullable: false
+
+        field :collection_ids, -> { Internal::Types::Array[Integer] }, optional: true, nullable: false
+
+        field :contributor_ids, -> { Internal::Types::Array[Integer] }, optional: true, nullable: false
+
+        field :category_ids, -> { Internal::Types::Array[Integer] }, optional: true, nullable: false
+
+        field :classification_ids, -> { Internal::Types::Array[Integer] }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/corpus/types/impression_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Corpus
+    module Types
+      class ImpressionRequest < Internal::Types::Model
+        field :model, -> { String }, optional: false, nullable: false
+
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :prompt_id, -> { String }, optional: false, nullable: false
+
+        field :user_id, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/corpus/types/log_corpus_referral_redirect_request.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Corpus
+    module Types
+      class LogCorpusReferralRedirectRequest < Internal::Types::Model
+        field :model, -> { String }, optional: false, nullable: false
+
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :prompt_id, -> { String }, optional: false, nullable: false
+
+        field :user_id, -> { String }, optional: true, nullable: false
+
+        field :url, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/corpus/types/referral_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Corpus
+    module Types
+      class ReferralRequest < Internal::Types::Model
+        field :model, -> { String }, optional: false, nullable: false
+
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :prompt_id, -> { String }, optional: false, nullable: false
+
+        field :user_id, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/corpus/types/search_corpus_response.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Corpus
+    module Types
+      class SearchCorpusResponse < Internal::Types::Model
+        field :results, -> { Internal::Types::Array[Internal::Types::Hash[String, Object]] }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/corpus/types/view_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Corpus
+    module Types
+      class ViewRequest < Internal::Types::Model
+        field :model, -> { String }, optional: false, nullable: false
+
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :prompt_id, -> { String }, optional: false, nullable: false
+
+        field :user_id, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/ct_as/client.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Apologist
+  module CtAs
+    class Client
+      # @param client [Apologist::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Finds matching CTAs based on conversation context, user, session, device, or messages
+      #
+      # @param request_options [Hash]
+      # @param params [Apologist::Types::CtaMatchRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @example
+      #   client.ct_as.match_ctas(request: {
+      #     key: "value"
+      #   })
+      #
+      # @return [Apologist::CtAs::Types::MatchCtasResponse]
+      def match_ctas(request_options: {}, **params)
+        params = Apologist::Internal::Types::Utils.normalize_keys(params)
+        request = Apologist::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "ctas/match",
+          body: Apologist::Types::CtaMatchRequest.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Apologist::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Apologist::CtAs::Types::MatchCtasResponse.load(response.body)
+        else
+          error_class = Apologist::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Records that a user clicked on a specific CTA
+      #
+      # @param request_options [Hash]
+      # @param params [Apologist::CtAs::Types::CtaClickRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      #
+      # @example
+      #   client.ct_as.log_cta_click(
+      #     id: "id",
+      #     prompt_id: "prompt_id"
+      #   )
+      #
+      # @return [Apologist::Types::SuccessResponse]
+      def log_cta_click(request_options: {}, **params)
+        params = Apologist::Internal::Types::Utils.normalize_keys(params)
+        request_data = Apologist::CtAs::Types::CtaClickRequest.new(params).to_h
+        non_body_param_names = %w[id]
+        body = request_data.except(*non_body_param_names)
+
+        request = Apologist::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "ctas/#{URI.encode_uri_component(params[:id].to_s)}/click",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Apologist::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Apologist::Types::SuccessResponse.load(response.body)
+        else
+          error_class = Apologist::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/Apologist/ct_as/types/cta_click_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Apologist
+  module CtAs
+    module Types
+      class CtaClickRequest < Internal::Types::Model
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :prompt_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/ct_as/types/match_ctas_response.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Apologist
+  module CtAs
+    module Types
+      class MatchCtasResponse < Internal::Types::Model
+        field :ctas, -> { Internal::Types::Array[Internal::Types::Hash[String, Object]] }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/Apologist/environment.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Apologist
+  class Environment
+    DEFAULT = "https://your-agent-domain.com/api/v1"
+  end
+end

data/lib/Apologist/errors/api_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Errors
+    class ApiError < StandardError
+    end
+  end
+end

data/lib/Apologist/errors/client_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Errors
+    class ClientError < ResponseError
+    end
+
+    class UnauthorizedError < ClientError
+    end
+
+    class ForbiddenError < ClientError
+    end
+
+    class NotFoundError < ClientError
+    end
+  end
+end

data/lib/Apologist/errors/redirect_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Errors
+    class RedirectError < ResponseError
+    end
+  end
+end

data/lib/Apologist/errors/response_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Errors
+    class ResponseError < ApiError
+      attr_reader :code
+
+      def initialize(msg, code:)
+        @code = code
+        super(msg)
+      end
+
+      def inspect
+        "#<#{self.class.name} @code=#{code} @body=#{message}>"
+      end
+
+      # Returns the most appropriate error class for the given code.
+      #
+      # @return [Class]
+      def self.subclass_for_code(code)
+        case code
+        when 300..399
+          RedirectError
+        when 401
+          UnauthorizedError
+        when 403
+          ForbiddenError
+        when 404
+          NotFoundError
+        when 400..499
+          ClientError
+        when 503
+          ServiceUnavailableError
+        when 500..599
+          ServerError
+        else
+          ResponseError
+        end
+      end
+    end
+  end
+end

data/lib/Apologist/errors/server_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Errors
+    class ServerError < ResponseError
+    end
+
+    class ServiceUnavailableError < ApiError
+    end
+  end
+end

data/lib/Apologist/errors/timeout_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Apologist
+  module Errors
+    class TimeoutError < ApiError
+    end
+  end
+end