fact_db 0.0.2 → 0.0.3

data/lib/fact_db/resolution/entity_resolver.rb

@@ -2,44 +2,89 @@
 
 module FactDb
   module Resolution
+    # Resolves entity names to canonical entities in the database
+    #
+    # Provides entity resolution through exact alias matching, canonical name matching,
+    # and fuzzy matching using Levenshtein distance. Also handles entity merging,
+    # splitting, and duplicate detection.
+    #
+    # @example Basic usage
+    #   resolver = EntityResolver.new
+    #   resolved = resolver.resolve("John Smith", kind: :person)
+    #   if resolved
+    #     puts "Found: #{resolved.entity.name} (confidence: #{resolved.confidence})"
+    #   end
+    #
     class EntityResolver
+      # @return [FactDb::Config] the configuration object
       attr_reader :config
 
+      # Initializes a new EntityResolver instance
+      #
+      # @param config [FactDb::Config] configuration object (defaults to FactDb.config)
       def initialize(config = FactDb.config)
         @config = config
         @threshold = config.fuzzy_match_threshold
         @auto_merge_threshold = config.auto_merge_threshold
       end
 
-      # Resolve a name to an entity
-      def resolve(name, type: nil)
+      # Resolves a name to an existing entity
+      #
+      # Tries resolution in order: exact alias match, canonical name match, fuzzy match.
+      #
+      # @param name [String] the name to resolve
+      # @param kind [Symbol, nil] optional entity kind filter (:person, :organization, etc.)
+      # @return [ResolvedEntity, nil] resolved entity with confidence score, or nil if not found
+      #
+      # @example Resolve with kind filter
+      #   resolver.resolve("Acme", kind: :organization)
+      def resolve(name, kind: nil)
         return nil if name.nil? || name.empty?
 
         # 1. Exact alias match
-        exact = find_by_exact_alias(name, type: type)
+        exact = find_by_exact_alias(name, kind: kind)
         return ResolvedEntity.new(exact, confidence: 1.0, match_type: :exact_alias) if exact
 
         # 2. Canonical name match
-        canonical = find_by_canonical_name(name, type: type)
-        return ResolvedEntity.new(canonical, confidence: 1.0, match_type: :canonical_name) if canonical
+        canonical = find_by_name(name, kind: kind)
+        return ResolvedEntity.new(canonical, confidence: 1.0, match_type: :name) if canonical
 
         # 3. Fuzzy matching
-        fuzzy = find_by_fuzzy_match(name, type: type)
+        fuzzy = find_by_fuzzy_match(name, kind: kind)
         return fuzzy if fuzzy && fuzzy.confidence >= @threshold
 
         # 4. No match found
         nil
       end
 
-      # Resolve or create an entity
-      def resolve_or_create(name, type:, aliases: [], attributes: {})
-        resolved = resolve(name, type: type)
+      # Resolves a name to an entity, creating one if not found
+      #
+      # @param name [String] the name to resolve or create
+      # @param kind [Symbol] the entity kind (required for creation)
+      # @param aliases [Array<String>] additional aliases to add
+      # @param attributes [Hash] additional attributes for new entity
+      # @return [FactDb::Models::Entity] the resolved or created entity
+      #
+      # @example Create with aliases
+      #   resolver.resolve_or_create("John Smith", kind: :person, aliases: ["J. Smith", "Johnny"])
+      def resolve_or_create(name, kind:, aliases: [], attributes: {})
+        resolved = resolve(name, kind: kind)
         return resolved.entity if resolved
 
-        create_entity(name, type: type, aliases: aliases, attributes: attributes)
+        create_entity(name, kind: kind, aliases: aliases, attributes: attributes)
       end
 
-      # Merge two entities, keeping one as canonical
+      # Merges two entities, keeping one as canonical
+      #
+      # Transfers all aliases and mentions from the merged entity to the kept entity.
+      #
+      # @param keep_id [Integer] ID of the entity to keep
+      # @param merge_id [Integer] ID of the entity to merge (will be marked as merged)
+      # @return [FactDb::Models::Entity] the kept entity with updated aliases
+      # @raise [ResolutionError] if attempting to merge into itself or merge already merged entity
+      #
+      # @example Merge duplicate entities
+      #   resolver.merge(primary_entity.id, duplicate_entity.id)
       def merge(keep_id, merge_id)
         keep = Models::Entity.find(keep_id)
         merge_entity = Models::Entity.find(merge_id)
@@ -50,15 +95,15 @@ module FactDb
         Models::Entity.transaction do
           # Move all aliases to kept entity
           merge_entity.aliases.each do |alias_record|
-            keep.aliases.find_or_create_by!(alias_text: alias_record.alias_text) do |a|
-              a.alias_type = alias_record.alias_type
+            keep.aliases.find_or_create_by!(name: alias_record.name) do |a|
+              a.kind = alias_record.kind
               a.confidence = alias_record.confidence
             end
           end
 
           # Add the merged entity's canonical name as an alias
-          keep.aliases.find_or_create_by!(alias_text: merge_entity.canonical_name) do |a|
-            a.alias_type = "name"
+          keep.aliases.find_or_create_by!(name: merge_entity.name) do |a|
+            a.kind = "name"
             a.confidence = 1.0
           end
 
@@ -68,14 +113,26 @@ module FactDb
           # Mark merged entity
           merge_entity.update!(
             resolution_status: "merged",
-            merged_into_id: keep_id
+            canonical_id: keep_id
           )
         end
 
         keep.reload
       end
 
-      # Split an entity into multiple entities
+      # Splits an entity into multiple new entities
+      #
+      # Creates new entities based on the split configuration and marks the original as split.
+      #
+      # @param entity_id [Integer] ID of the entity to split
+      # @param split_configs [Array<Hash>] array of hashes with :name, :kind, :aliases, :attributes
+      # @return [Array<FactDb::Models::Entity>] array of newly created entities
+      #
+      # @example Split an ambiguous entity
+      #   resolver.split(entity.id, [
+      #     { name: "John Smith (Sales)", kind: :person },
+      #     { name: "John Smith (Engineering)", kind: :person }
+      #   ])
       def split(entity_id, split_configs)
         original = Models::Entity.find(entity_id)
 
@@ -83,7 +140,7 @@ module FactDb
           new_entities = split_configs.map do |config|
             create_entity(
               config[:name],
-              type: config[:type] || original.entity_type,
+              kind: config[:kind] || original.kind,
               aliases: config[:aliases] || [],
               attributes: config[:attributes] || {}
             )
@@ -95,7 +152,14 @@ module FactDb
         end
       end
 
-      # Find potential duplicate entities
+      # Finds potential duplicate entities based on name similarity
+      #
+      # @param threshold [Float, nil] minimum similarity score (defaults to config threshold)
+      # @return [Array<Hash>] array of hashes with :entity1, :entity2, :similarity keys
+      #
+      # @example Find duplicates with custom threshold
+      #   duplicates = resolver.find_duplicates(threshold: 0.85)
+      #   duplicates.each { |d| puts "#{d[:entity1].name} ~ #{d[:entity2].name} (#{d[:similarity]})" }
       def find_duplicates(threshold: nil)
         threshold ||= @threshold
         duplicates = []
@@ -104,7 +168,7 @@ module FactDb
 
         entities.each_with_index do |entity, i|
           entities[(i + 1)..].each do |other|
-            similarity = calculate_similarity(entity.canonical_name, other.canonical_name)
+            similarity = calculate_similarity(entity.name, other.name)
             if similarity >= threshold
               duplicates << {
                 entity1: entity,
@@ -118,7 +182,11 @@ module FactDb
         duplicates.sort_by { |d| -d[:similarity] }
       end
 
-      # Auto-merge high-confidence duplicates
+      # Automatically merges high-confidence duplicates
+      #
+      # Uses the auto_merge_threshold from config and keeps the entity with more mentions.
+      #
+      # @return [void]
       def auto_merge_duplicates!
         duplicates = find_duplicates(threshold: @auto_merge_threshold)
 
@@ -138,29 +206,29 @@ module FactDb
 
       private
 
-      def find_by_exact_alias(name, type:)
-        scope = Models::EntityAlias.where(["LOWER(alias_text) = ?", name.downcase])
-        scope = scope.joins(:entity).where(fact_db_entities: { entity_type: type }) if type
+      def find_by_exact_alias(name, kind:)
+        scope = Models::EntityAlias.where(["LOWER(fact_db_entity_aliases.name) = ?", name.downcase])
+        scope = scope.joins(:entity).where(fact_db_entities: { kind: kind }) if kind
         scope = scope.joins(:entity).where.not(fact_db_entities: { resolution_status: "merged" })
         scope.first&.entity
       end
 
-      def find_by_canonical_name(name, type:)
-        scope = Models::Entity.where(["LOWER(canonical_name) = ?", name.downcase])
-        scope = scope.where(entity_type: type) if type
+      def find_by_name(name, kind:)
+        scope = Models::Entity.where(["LOWER(name) = ?", name.downcase])
+        scope = scope.where(kind: kind) if kind
         scope.not_merged.first
       end
 
-      def find_by_fuzzy_match(name, type:)
+      def find_by_fuzzy_match(name, kind:)
         candidates = Models::Entity.not_merged
-        candidates = candidates.where(entity_type: type) if type
+        candidates = candidates.where(kind: kind) if kind
 
         best_match = nil
         best_similarity = 0
 
         candidates.find_each do |entity|
           # Check canonical name
-          similarity = calculate_similarity(name, entity.canonical_name)
+          similarity = calculate_similarity(name, entity.name)
           if similarity > best_similarity
             best_similarity = similarity
             best_match = entity
@@ -168,7 +236,7 @@ module FactDb
 
           # Check aliases
           entity.aliases.each do |alias_record|
-            alias_similarity = calculate_similarity(name, alias_record.alias_text)
+            alias_similarity = calculate_similarity(name, alias_record.name)
             if alias_similarity > best_similarity
               best_similarity = alias_similarity
               best_match = entity
@@ -181,10 +249,10 @@ module FactDb
         ResolvedEntity.new(best_match, confidence: best_similarity, match_type: :fuzzy)
       end
 
-      def create_entity(name, type:, aliases: [], attributes: {})
+      def create_entity(name, kind:, aliases: [], attributes: {})
         entity = Models::Entity.create!(
-          canonical_name: name,
-          entity_type: type,
+          name: name,
+          kind: kind,
           attributes: attributes,
           resolution_status: "resolved"
         )
@@ -228,33 +296,65 @@ module FactDb
       end
     end
 
+    # Represents a resolved entity with confidence metadata
+    #
+    # Wraps an entity with information about how it was resolved
+    # and the confidence level of the match.
+    #
     class ResolvedEntity
-      attr_reader :entity, :confidence, :match_type
+      # @return [FactDb::Models::Entity] the resolved entity
+      attr_reader :entity
 
+      # @return [Float] confidence score from 0.0 to 1.0
+      attr_reader :confidence
+
+      # @return [Symbol] how the entity was matched (:exact_alias, :name, :fuzzy)
+      attr_reader :match_type
+
+      # Initializes a new ResolvedEntity
+      #
+      # @param entity [FactDb::Models::Entity] the resolved entity
+      # @param confidence [Float] confidence score (0.0 to 1.0)
+      # @param match_type [Symbol] match type (:exact_alias, :name, :fuzzy)
       def initialize(entity, confidence:, match_type:)
         @entity = entity
         @confidence = confidence
         @match_type = match_type
       end
 
+      # Checks if this was an exact match (confidence == 1.0)
+      #
+      # @return [Boolean] true if confidence is 1.0
       def exact_match?
         confidence == 1.0
       end
 
+      # Checks if this was a fuzzy match
+      #
+      # @return [Boolean] true if match_type is :fuzzy
       def fuzzy_match?
         match_type == :fuzzy
       end
 
+      # Returns the entity ID
+      #
+      # @return [Integer] the entity's database ID
       def id
         entity.id
       end
 
-      def canonical_name
-        entity.canonical_name
+      # Returns the entity name
+      #
+      # @return [String] the entity's canonical name
+      def name
+        entity.name
       end
 
-      def entity_type
-        entity.entity_type
+      # Returns the entity kind
+      #
+      # @return [String] the entity's kind
+      def kind
+        entity.kind
       end
     end
   end

data/lib/fact_db/resolution/fact_resolver.rb

@@ -2,22 +2,51 @@
 
 module FactDb
   module Resolution
+    # Handles fact lifecycle operations including supersession, synthesis, and conflict resolution
+    #
+    # Provides methods for managing fact relationships: superseding outdated facts,
+    # synthesizing new facts from multiple sources, handling corroboration,
+    # and detecting/resolving conflicts.
+    #
+    # @example Supersede an outdated fact
+    #   resolver = FactResolver.new
+    #   new_fact = resolver.supersede(old_fact.id, "Updated information", valid_at: Date.today)
+    #
     class FactResolver
+      # @return [FactDb::Config] the configuration object
       attr_reader :config
 
+      # Initializes a new FactResolver instance
+      #
+      # @param config [FactDb::Config] configuration object (defaults to FactDb.config)
       def initialize(config = FactDb.config)
         @config = config
       end
 
-      # Supersede an existing fact with a new one
-      def supersede(old_fact_id, new_fact_text, valid_at:, mentions: [])
+      # Supersedes an existing fact with a new one
+      #
+      # Creates a new canonical fact and marks the old one as superseded.
+      # Copies mentions and sources from the old fact unless new mentions are provided.
+      #
+      # @param old_fact_id [Integer] ID of the fact to supersede
+      # @param new_text [String] the updated fact text
+      # @param valid_at [Date, Time] when the new fact became valid
+      # @param mentions [Array<Hash>] optional entity mentions for the new fact
+      # @return [FactDb::Models::Fact] the new canonical fact
+      # @raise [ResolutionError] if the fact is already superseded
+      #
+      # @example Supersede with new mentions
+      #   resolver.supersede(fact.id, "John now works at NewCo",
+      #     valid_at: Date.today,
+      #     mentions: [{ entity_id: john.id, text: "John", role: :subject }])
+      def supersede(old_fact_id, new_text, valid_at:, mentions: [])
         old_fact = Models::Fact.find(old_fact_id)
 
         raise ResolutionError, "Cannot supersede already superseded fact" if old_fact.superseded?
 
         Models::Fact.transaction do
           new_fact = Models::Fact.create!(
-            fact_text: new_fact_text,
+            text: new_text,
             valid_at: valid_at,
             status: "canonical",
             extraction_method: old_fact.extraction_method,
@@ -49,8 +78,8 @@ module FactDb
           # Copy sources from old fact
           old_fact.fact_sources.each do |source|
             new_fact.add_source(
-              content: source.content,
-              type: source.source_type,
+              source: source.source,
+              kind: source.kind,
               excerpt: source.excerpt,
               confidence: source.confidence
             )
@@ -67,7 +96,21 @@ module FactDb
         end
       end
 
-      # Synthesize a new fact from multiple source facts
+      # Synthesizes a new fact from multiple source facts
+      #
+      # Creates a single synthesized fact that aggregates information from multiple facts.
+      # Automatically aggregates entity mentions and links to all source content.
+      #
+      # @param source_fact_ids [Array<Integer>] IDs of the source facts
+      # @param synthesized_text [String] the synthesized summary text
+      # @param valid_at [Date, Time] when the synthesis is valid from
+      # @param invalid_at [Date, Time, nil] when the synthesis becomes invalid
+      # @param mentions [Array<Hash>] optional entity mentions (aggregated from sources if empty)
+      # @return [FactDb::Models::Fact] the synthesized fact
+      # @raise [ResolutionError] if no source facts are found
+      #
+      # @example Synthesize multiple facts
+      #   resolver.synthesize([fact1.id, fact2.id], "Summary of events", valid_at: Date.today)
       def synthesize(source_fact_ids, synthesized_text, valid_at:, invalid_at: nil, mentions: [])
         source_facts = Models::Fact.where(id: source_fact_ids)
 
@@ -75,7 +118,7 @@ module FactDb
 
         Models::Fact.transaction do
           synthesized = Models::Fact.create!(
-            fact_text: synthesized_text,
+            text: synthesized_text,
             valid_at: valid_at,
             invalid_at: invalid_at,
             status: "synthesized",
@@ -117,7 +160,15 @@ module FactDb
         end
       end
 
-      # Mark a fact as corroborated by another fact
+      # Marks a fact as corroborated by another fact
+      #
+      # Adds the corroborating fact ID to the corroborated_by_ids array.
+      # If 2+ facts corroborate, status changes to "corroborated".
+      #
+      # @param fact_id [Integer] ID of the fact being corroborated
+      # @param corroborating_fact_id [Integer] ID of the supporting fact
+      # @return [FactDb::Models::Fact] the updated fact
+      # @raise [ResolutionError] if attempting to corroborate with the same fact
       def corroborate(fact_id, corroborating_fact_id)
         fact = Models::Fact.find(fact_id)
         _corroborating = Models::Fact.find(corroborating_fact_id)
@@ -134,14 +185,24 @@ module FactDb
         fact
       end
 
-      # Invalidate a fact without replacement
+      # Invalidates a fact without replacement
+      #
+      # @param fact_id [Integer] ID of the fact to invalidate
+      # @param at [Time] when the fact became invalid (defaults to now)
+      # @return [FactDb::Models::Fact] the invalidated fact
       def invalidate(fact_id, at: Time.current)
         fact = Models::Fact.find(fact_id)
         fact.update!(invalid_at: at)
         fact
       end
 
-      # Find potentially conflicting facts
+      # Finds potentially conflicting facts
+      #
+      # Identifies facts with similar text (50-95% similarity) that might be contradictory.
+      #
+      # @param entity_id [Integer, nil] entity ID to filter by
+      # @param topic [String, nil] topic to search for
+      # @return [Array<Hash>] array of hashes with :fact1, :fact2, :similarity keys
       def find_conflicts(entity_id: nil, topic: nil)
         scope = Models::Fact.canonical.currently_valid
 
@@ -159,7 +220,7 @@ module FactDb
 
         facts.each_with_index do |fact, i|
           facts[(i + 1)..].each do |other|
-            similarity = text_similarity(fact.fact_text, other.fact_text)
+            similarity = text_similarity(fact.text, other.text)
             if similarity > 0.5 && similarity < 0.95
               conflicts << {
                 fact1: fact,
@@ -173,7 +234,12 @@ module FactDb
         conflicts.sort_by { |c| -c[:similarity] }
       end
 
-      # Resolve conflicts by keeping one fact and superseding others
+      # Resolves conflicts by keeping one fact and superseding others
+      #
+      # @param keep_fact_id [Integer] ID of the fact to keep as canonical
+      # @param supersede_fact_ids [Array<Integer>] IDs of facts to mark as superseded
+      # @param reason [String, nil] reason for the resolution (stored in metadata)
+      # @return [FactDb::Models::Fact] the kept fact
       def resolve_conflict(keep_fact_id, supersede_fact_ids, reason: nil)
         Models::Fact.transaction do
           supersede_fact_ids.each do |fact_id|
@@ -190,7 +256,13 @@ module FactDb
         Models::Fact.find(keep_fact_id)
       end
 
-      # Build a timeline fact from point-in-time facts
+      # Builds a timeline fact from point-in-time facts for an entity
+      #
+      # Creates a synthesized fact summarizing the entity's history on a topic.
+      #
+      # @param entity_id [Integer] the entity ID
+      # @param topic [String, nil] optional topic filter
+      # @return [FactDb::Models::Fact, nil] synthesized timeline fact or nil if no facts found
       def build_timeline_fact(entity_id:, topic: nil)
         facts = Models::Fact.mentioning_entity(entity_id)
         facts = facts.search_text(topic) if topic
@@ -203,7 +275,7 @@ module FactDb
         end_date = facts.select { |f| f.invalid_at }.map(&:invalid_at).max
 
         entity = Models::Entity.find(entity_id)
-        synthesized_text = "#{entity.canonical_name}: #{topic || 'timeline'} from #{start_date.to_date}"
+        synthesized_text = "#{entity.name}: #{topic || 'timeline'} from #{start_date.to_date}"
         synthesized_text += " to #{end_date.to_date}" if end_date
 
         synthesize(