atlas_engine 0.1.0

data/app/models/atlas_engine/address_validation/token.rb

@@ -0,0 +1,113 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class Token
+      extend T::Sig
+
+      sig { returns(String) }
+      attr_reader :value
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :type
+
+      sig { returns(Integer) }
+      attr_accessor :position
+
+      sig { returns(Integer) }
+      attr_accessor :start_offset
+
+      sig { returns(Integer) }
+      attr_accessor :end_offset
+
+      sig { returns(Integer) }
+      attr_reader :position_length
+
+      sig do
+        params(
+          value: String,
+          start_offset: Integer,
+          end_offset: Integer,
+          position: Integer,
+          type: T.nilable(String),
+          position_length: Integer,
+        ).void
+      end
+      def initialize(value:, start_offset:, end_offset:, position:, type: nil, position_length: 1)
+        @value = value
+        @start_offset = start_offset
+        @end_offset = end_offset
+        @type = type
+        @position = position
+        @position_length = position_length
+      end
+
+      sig { returns(T::Range[Integer]) }
+      def offset_range
+        @offset_range ||= start_offset...end_offset
+      end
+
+      sig { returns(String) }
+      def inspect
+        t = " type:#{type}" if type.present?
+        pos_length = " pos_length:#{position_length}" if position_length > 1
+        id = "id:#{object_id.to_s[-4..-1]}"
+        details = " strt:#{start_offset} end:#{end_offset} pos:#{position}#{t}#{pos_length}"
+
+        "<tok #{id} val:\"#{value}\"#{details}/>"
+      end
+
+      sig { returns(String) }
+      def inspect_short
+        id = "id:#{object_id.to_s[-4..-1]}"
+        "<tok #{id} val:\"#{value}\"/>"
+      end
+
+      sig { params(other: Token).returns(T::Boolean) }
+      def ==(other)
+        value == other.value &&
+          start_offset == other.start_offset &&
+          end_offset == other.end_offset &&
+          type == other.type &&
+          position == other.position &&
+          position_length == other.position_length
+      end
+
+      sig { params(other: Token).returns(T::Boolean) }
+      def preceeds?(other)
+        position == other.position - position_length
+      end
+
+      class << self
+        extend T::Sig
+
+        sig { params(field_terms: Hash).returns(T::Array[Token]) }
+        def from_field_term_vector(field_terms)
+          field_terms["terms"].flat_map do |term, term_info|
+            term_info["tokens"].map do |token|
+              new(
+                value: term,
+                position: token["position"],
+                start_offset: token["start_offset"],
+                end_offset: token["end_offset"],
+              )
+            end
+          end.sort_by(&:position)
+        end
+
+        sig { params(token: T::Hash[String, T.untyped]).returns(Token) }
+        def from_analyze(token)
+          new(
+            value: token["token"],
+            start_offset: token["start_offset"],
+            end_offset: token["end_offset"],
+            type: token["type"],
+            position: token["position"],
+            position_length: token["positionLength"] || 1,
+          )
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validator.rb

@@ -0,0 +1,147 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class Validator
+      include RunsValidation
+      extend T::Sig
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :address1,
+        :address2,
+        :city,
+        :province_code,
+        :zip,
+        :country_code,
+        :phone
+
+      sig { returns(Result) }
+      attr_reader :result
+
+      sig { returns(AbstractAddress) }
+      attr_reader :address
+
+      sig { returns(T::Hash[T.untyped, T.untyped]) }
+      attr_reader :context
+
+      sig { returns(T.nilable(FullAddressValidatorBase)) }
+      attr_reader :full_address_validator
+
+      FIELD_MAP = T.let(
+        {
+          country: "country_code",
+          province: "province_code",
+          zip: "zip",
+          city: "city",
+          address1: "address1",
+          address2: "address2",
+          phone: "phone",
+        },
+        T::Hash[Symbol, String],
+      )
+
+      sig do
+        params(
+          address: AbstractAddress,
+          matching_strategy: Strategies,
+          locale: String,
+          context: T::Hash[T.untyped, T.untyped],
+        ).void
+      end
+      def initialize(
+        address:,
+        matching_strategy:,
+        locale: "en",
+        context: {}
+      )
+        @address = T.let(address, AbstractAddress)
+        @address1 = T.let(address.address1, T.nilable(String))
+        @address2 = T.let(address.address2, T.nilable(String))
+        @city = T.let(address.city, T.nilable(String))
+        @province_code = T.let(address.province_code, T.nilable(String))
+        @phone = T.let(address.phone, T.nilable(String))
+        @zip = T.let(address.zip, T.nilable(String))
+        @country_code = T.let(address.country_code, T.nilable(String))
+        @context = T.let(context, T::Hash[T.untyped, T.untyped])
+        @matching_strategy = T.let(matching_strategy, Strategies)
+
+        matching_strategy_name = matching_strategy.serialize
+        @predicate_pipeline = T.let(PredicatePipeline.find(matching_strategy_name), PredicatePipeline)
+
+        @result = T.let(
+          Result.new(
+            client_request_id: context.dig(:client_request_id),
+            origin: context.dig(:origin),
+            locale: locale,
+            matching_strategy: matching_strategy_name,
+          ),
+          Result,
+        )
+
+        @full_address_validator = T.let(
+          @predicate_pipeline.full_address_validator&.new(
+            address: @address,
+            result: @result,
+          ),
+          T.nilable(FullAddressValidatorBase),
+        )
+      end
+
+      sig { override.returns(Result) }
+      def run
+        build_fields
+
+        populate_result(execute_pipeline)
+
+        validate_full_address
+
+        result
+      end
+
+      sig { void }
+      def build_fields
+        result.fields = address.keys.map do |field|
+          Field.new(name: field, value: address[field])
+        end
+      end
+
+      private
+
+      sig { returns(T::Hash[Symbol, T::Array[Concern]]) }
+      def execute_pipeline
+        pipeline_address = Address.from_address(address: address)
+        local_concerns = {}
+        cache = Validators::Predicates::Cache.new(pipeline_address)
+        @predicate_pipeline.pipeline.each do |config|
+          local_concerns[config.field] = [] if local_concerns[config.field].nil?
+          next if local_concerns[config.field].present?
+
+          concern = config.class_name.new(field: config.field, address: pipeline_address, cache: cache).evaluate
+
+          local_concerns[config.field] << concern if concern.present?
+        end
+        local_concerns
+      end
+
+      sig { params(local_concerns: T::Hash[Symbol, T::Array[Concern]]).void }
+      def populate_result(local_concerns)
+        local_concerns.keys.each do |field|
+          if local_concerns[field]&.empty? && [:address2, :phone].exclude?(field)
+            result.validation_scope << T.must(FIELD_MAP[field])
+          end
+
+          local_concerns[field]&.each do |concern|
+            result.concerns << concern
+            result.suggestions << T.must(concern.suggestion) if concern.suggestion.present?
+          end
+        end
+      end
+
+      sig { void }
+      def validate_full_address
+        @full_address_validator&.validate
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/address_comparison.rb

@@ -0,0 +1,97 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class AddressComparison
+          extend T::Sig
+          include Comparable
+
+          attr_reader :street_comparison,
+            :city_comparison,
+            :zip_comparison,
+            :province_code_comparison,
+            :building_comparison
+
+          sig { params(address: AbstractAddress, candidate: Candidate, datastore: DatastoreBase).void }
+          def initialize(address:, candidate:, datastore:)
+            @street_comparison = ComparisonHelper.street_comparison(
+              datastore: datastore,
+              candidate: candidate,
+            )
+            @city_comparison = ComparisonHelper.city_comparison(
+              datastore: datastore,
+              candidate: candidate,
+            )
+            @zip_comparison = ComparisonHelper.zip_comparison(
+              address: address,
+              candidate: candidate,
+            )
+            @province_code_comparison = ComparisonHelper.province_code_comparison(
+              address: address,
+              candidate: candidate,
+            )
+            @building_comparison = ComparisonHelper.building_comparison(
+              datastore: datastore,
+              candidate: candidate,
+            )
+          end
+
+          sig { params(other: AddressComparison).returns(Integer) }
+          def <=>(other)
+            # prefer addresses having more matched fields, e.g. matching on street + city + zip is better than
+            # just matching on street + zip, or street + province
+            matches = comparisons.count(&:match?) <=> other.comparisons.count(&:match?)
+            return matches * -1 if matches.nonzero?
+
+            # merge all sequence comparisons together, erasing the individual field boundaries, and prefer
+            # the most favorable aggregate comparison
+            merged_comparison <=> other.merged_comparison
+          end
+
+          sig { returns(String) }
+          def inspect
+            "<addrcomp street#{comparisons.inspect}/>"
+          end
+
+          sig { returns(T::Boolean) }
+          def potential_match?
+            street_comparison.nil? || T.must(street_comparison).potential_match?
+          end
+
+          protected
+
+          sig do
+            returns(T::Array[T.any(AtlasEngine::AddressValidation::Token::Sequence::Comparison, NumberComparison)])
+          end
+          def comparisons
+            [
+              street_comparison,
+              city_comparison,
+              zip_comparison,
+              province_code_comparison,
+              building_comparison,
+            ].compact_blank
+          end
+
+          sig { returns(T::Array[AtlasEngine::AddressValidation::Token::Sequence::Comparison]) }
+          def text_comparisons
+            [
+              street_comparison,
+              city_comparison,
+              zip_comparison,
+              province_code_comparison,
+            ].compact_blank
+          end
+
+          sig { returns(AtlasEngine::AddressValidation::Token::Sequence::Comparison) }
+          def merged_comparison
+            @merged_comparisons ||= text_comparisons.reduce(&:merge)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/candidate_result.rb

@@ -0,0 +1,164 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class CandidateResult < CandidateResultBase
+          extend T::Sig
+          include LogHelper
+
+          sig do
+            params(
+              candidate: AddressValidation::CandidateTuple,
+              session: Session,
+              result: Result,
+            )
+              .void
+          end
+          def initialize(candidate:, session:, result:)
+            super(session: session, result: result)
+            @candidate = candidate.candidate
+            @address_comparison = candidate.address_comparison
+          end
+
+          sig { override.void }
+          def update_result
+            result.candidate = candidate&.serialize
+            return if unmatched_components.empty?
+
+            update_concerns_and_suggestions
+            update_result_scope
+          end
+
+          sig { returns(T::Boolean) }
+          def suggestable?
+            ConcernBuilder.should_suggest?(session.address, unmatched_components.keys)
+          end
+
+          private
+
+          attr_reader :candidate
+
+          sig { void }
+          def update_concerns_and_suggestions
+            if suggestable?
+              add_concerns_with_suggestions
+            else
+              add_concerns_without_suggestions
+            end
+          end
+
+          sig { void }
+          def add_concerns_without_suggestions
+            concern = InvalidZipConcernBuilder.for(session.address, [])
+            result.concerns << concern if concern
+
+            if ConcernBuilder.too_many_unmatched_components?(unmatched_components.keys)
+              result.concerns << UnknownAddressConcern.new(session.address)
+            end
+          end
+
+          sig { void }
+          def add_concerns_with_suggestions
+            unmatched_components.keys.each do |unmatched_component|
+              field_name = unmatched_field_name(unmatched_component)
+              if field_name.nil?
+                log_unknown_field_name
+                next
+              end
+
+              concern = ConcernBuilder.new(
+                unmatched_component: unmatched_component,
+                unmatched_field: field_name,
+                matched_components: matched_components.keys,
+                address: session.address,
+                suggestion_ids: [suggestion.id].compact,
+              ).build
+              result.concerns << concern
+            end
+            result.suggestions << suggestion
+          end
+
+          sig { returns(Suggestion) }
+          def suggestion
+            unmatched_fields = { street: unmatched_field_name(:street) }.compact
+
+            @suggestion ||= SuggestionBuilder.from_comparisons(
+              session.address.to_h,
+              unmatched_components,
+              candidate,
+              unmatched_fields,
+            )
+          end
+
+          sig { returns(T::Hash[Symbol, AtlasEngine::AddressValidation::Token::Sequence::Comparison]) }
+          def matched_components
+            @matched_components || split_matched_and_unmatched_components.first
+          end
+
+          sig { returns(T::Hash[Symbol, AtlasEngine::AddressValidation::Token::Sequence::Comparison]) }
+          def unmatched_components
+            @unmatched_components || split_matched_and_unmatched_components.second
+          end
+
+          sig { returns(T::Hash[Symbol, T.nilable(AtlasEngine::AddressValidation::Token::Sequence::Comparison)]) }
+          def matched_and_unmatched_components
+            components = {}
+            @matched_and_unmatched_components ||= begin
+              components_to_validate.each do |field|
+                components[field] = @address_comparison.send(:"#{field}_comparison")
+              end
+              components
+            end
+          end
+
+          sig { returns(T::Array[Symbol]) }
+          def components_to_validate
+            ComponentsToValidate.new(session, candidate, street_comparison).run
+          end
+
+          sig do
+            returns(T::Array[T::Hash[Symbol,
+              T.nilable(AtlasEngine::AddressValidation::Token::Sequence::Comparison)]])
+          end
+          def split_matched_and_unmatched_components
+            @matched_components, @unmatched_components = matched_and_unmatched_components.partition do |_, comparison|
+              comparison&.match?
+            end.map(&:to_h)
+          end
+
+          sig { returns(T.nilable(AtlasEngine::AddressValidation::Token::Sequence::Comparison)) }
+          def street_comparison
+            return @street_comparison if defined?(@street_comparison)
+
+            @street_comparison = @address_comparison.street_comparison
+          end
+
+          sig { params(component: Symbol).returns(T.nilable(Symbol)) }
+          def unmatched_field_name(component)
+            return component unless component == :street
+            return if unmatched_components[:street].nil?
+
+            original_street = T.must(unmatched_components[:street]).left_sequence.raw_value
+
+            if session.address.address1.to_s.include?(original_street)
+              :address1
+            elsif session.address.address2.to_s.include?(original_street)
+              :address2
+            end
+          end
+
+          sig { void }
+          def log_unknown_field_name
+            potential_streets = { potential_streets: session.parsings.potential_streets }
+            input_address = session.address.to_h.compact_blank.except(:phone)
+            log_details = input_address.merge(potential_streets)
+            log_info("[AddressValidation] Unable to identify unmatched field name", log_details)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/candidate_result_base.rb

@@ -0,0 +1,46 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class CandidateResultBase
+          extend T::Helpers
+          extend T::Sig
+
+          abstract!
+
+          sig { params(session: Session, result: Result).void }
+          def initialize(session:, result:)
+            @session = session
+            @result = result
+          end
+
+          sig { void }
+          def update_result; end
+
+          private
+
+          attr_reader :session, :result
+
+          delegate :address, to: :session
+
+          sig { void }
+          def update_result_scope
+            concern_fields = result.concerns.flat_map(&:field_names).uniq
+            scopes_to_remove = concern_fields.flat_map { |field| contained_scopes_for(field) }
+            result.validation_scope.reject! { |scope| scope.in?(scopes_to_remove) }
+          end
+
+          sig { params(scope: Symbol).returns(T.nilable(T::Array[Symbol])) }
+          def contained_scopes_for(scope)
+            return [] unless (scope_index = Result::SORTED_VALIDATION_SCOPES.index(scope))
+
+            Result::SORTED_VALIDATION_SCOPES.slice(scope_index..)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/validators/full_address/comparison_helper.rb

@@ -0,0 +1,135 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Validators
+      module FullAddress
+        class ComparisonHelper
+          class << self
+            extend T::Sig
+
+            sig do
+              params(
+                datastore: DatastoreBase,
+                candidate: Candidate,
+              ).returns(T.nilable(Token::Sequence::Comparison))
+            end
+            def street_comparison(datastore:, candidate:)
+              street_sequences = datastore.fetch_street_sequences
+              candidate_sequences = T.must(candidate.component(:street)).sequences
+
+              street_sequences.map do |street_sequence|
+                best_comparison(
+                  street_sequence,
+                  candidate_sequences,
+                )
+              end.min
+            end
+
+            sig do
+              params(
+                datastore: DatastoreBase,
+                candidate: Candidate,
+              ).returns(T.nilable(Token::Sequence::Comparison))
+            end
+            def city_comparison(datastore:, candidate:)
+              best_comparison(
+                datastore.fetch_city_sequence,
+                T.must(candidate.component(:city)).sequences,
+              )
+            end
+
+            sig do
+              params(
+                address: AbstractAddress,
+                candidate: Candidate,
+              ).returns(T.nilable(Token::Sequence::Comparison))
+            end
+            def province_code_comparison(address:, candidate:)
+              normalized_session_province_code = ValidationTranscriber::ProvinceCodeNormalizer.normalize(
+                country_code: address.country_code,
+                province_code: address.province_code,
+              )
+              normalized_candidate_province_code = ValidationTranscriber::ProvinceCodeNormalizer.normalize(
+                country_code: T.must(candidate.component(:country_code)).value,
+                province_code: T.must(candidate.component(:province_code)).value,
+              )
+
+              best_comparison(
+                Token::Sequence.from_string(normalized_session_province_code),
+                [Token::Sequence.from_string(normalized_candidate_province_code)],
+              )
+            end
+
+            sig do
+              params(
+                address: AbstractAddress,
+                candidate: Candidate,
+              ).returns(T.nilable(Token::Sequence::Comparison))
+            end
+            def zip_comparison(address:, candidate:)
+              candidate.component(:zip)&.value = PostalCodeMatcher.new(
+                T.must(address.country_code),
+                T.must(address.zip),
+                candidate.component(:zip)&.value,
+              ).truncate
+
+              normalized_zip = ValidationTranscriber::ZipNormalizer.normalize(
+                country_code: address.country_code, zip: address.zip,
+              )
+              zip_sequence = Token::Sequence.from_string(normalized_zip)
+              best_comparison(
+                zip_sequence,
+                T.must(candidate.component(:zip)).sequences,
+              )
+            end
+
+            sig do
+              params(
+                datastore: DatastoreBase,
+                candidate: Candidate,
+              ).returns(NumberComparison)
+            end
+            def building_comparison(datastore:, candidate:)
+              NumberComparison.new(
+                numbers: datastore.parsings.potential_building_numbers,
+                candidate_ranges: building_ranges_from_candidate(candidate),
+              )
+            end
+
+            private
+
+            sig do
+              params(
+                sequence: Token::Sequence,
+                component_sequences: T::Array[Token::Sequence],
+              ).returns(T.nilable(Token::Sequence::Comparison))
+            end
+            def best_comparison(sequence, component_sequences)
+              component_sequences.map do |component_sequence|
+                Token::Sequence::Comparator.new(
+                  left_sequence: sequence,
+                  right_sequence: component_sequence,
+                ).compare
+              end.min_by.with_index do |comparison, index|
+                # ruby's `min` and `sort` methods are not stable
+                # so we need to prefer the leftmost comparison when two comparisons are equivalent
+                [comparison, index]
+              end
+            end
+
+            sig { params(candidate: Candidate).returns(T::Array[AddressNumberRange]) }
+            def building_ranges_from_candidate(candidate)
+              building_and_unit_ranges = candidate.component(:building_and_unit_ranges)&.value
+              return [] if building_and_unit_ranges.blank?
+
+              building_ranges = JSON.parse(building_and_unit_ranges).keys
+              building_ranges.map { |building_range| AddressNumberRange.new(range_string: building_range) }
+            end
+          end
+        end
+      end
+    end
+  end
+end