fact_db 0.0.2 → 0.0.3

data/lib/fact_db/models/entity.rb

@@ -2,6 +2,19 @@
 
 module FactDb
   module Models
+    # Represents a named entity in the fact database
+    #
+    # Entities are real-world things like people, organizations, places, etc.
+    # that can be referenced in facts. Entities support aliases for name variations
+    # and can be merged to deduplicate records.
+    #
+    # @example Create an entity with aliases
+    #   entity = Entity.create!(name: "John Smith", kind: "person", resolution_status: "resolved")
+    #   entity.add_alias("J. Smith")
+    #
+    # @example Find entities by kind
+    #   people = Entity.by_kind("person").not_merged
+    #
     class Entity < ActiveRecord::Base
       self.table_name = "fact_db_entities"
 
@@ -11,69 +24,128 @@ module FactDb
                foreign_key: :entity_id, dependent: :destroy
       has_many :facts, through: :entity_mentions
 
-      belongs_to :merged_into, class_name: "FactDb::Models::Entity",
-                 foreign_key: :merged_into_id, optional: true
+      belongs_to :canonical, class_name: "FactDb::Models::Entity",
+                 foreign_key: :canonical_id, optional: true
       has_many :merged_entities, class_name: "FactDb::Models::Entity",
-               foreign_key: :merged_into_id
+               foreign_key: :canonical_id
 
-      validates :canonical_name, presence: true
-      validates :entity_type, presence: true
+      validates :name, presence: true
+      validates :kind, presence: true
       validates :resolution_status, presence: true
 
-      # Entity types
-      TYPES = %w[person organization place product event concept].freeze
+      # @return [Array<String>] valid resolution statuses
       STATUSES = %w[unresolved resolved merged split].freeze
 
-      validates :entity_type, inclusion: { in: TYPES }
+      # @return [Array<String>] valid entity kinds
+      ENTITY_KINDS = %w[person organization place product event concept other].freeze
+
       validates :resolution_status, inclusion: { in: STATUSES }
+      validates :kind, inclusion: { in: ENTITY_KINDS }
+
+      # @!method by_kind(k)
+      #   Returns entities of a specific kind
+      #   @param k [String] the entity kind
+      #   @return [ActiveRecord::Relation]
+      scope :by_kind, ->(k) { where(kind: k) }
 
-      scope :by_type, ->(type) { where(entity_type: type) }
+      # @!method resolved
+      #   Returns entities with "resolved" status
+      #   @return [ActiveRecord::Relation]
       scope :resolved, -> { where(resolution_status: "resolved") }
+
+      # @!method unresolved
+      #   Returns entities with "unresolved" status
+      #   @return [ActiveRecord::Relation]
       scope :unresolved, -> { where(resolution_status: "unresolved") }
+
+      # @!method not_merged
+      #   Returns entities that have not been merged
+      #   @return [ActiveRecord::Relation]
       scope :not_merged, -> { where.not(resolution_status: "merged") }
-      scope :people, -> { by_type("person") }
-      scope :organizations, -> { by_type("organization") }
-      scope :places, -> { by_type("place") }
 
+      # Checks if the entity is resolved
+      #
+      # @return [Boolean] true if resolution_status is "resolved"
       def resolved?
         resolution_status == "resolved"
       end
 
+      # Checks if the entity has been merged into another
+      #
+      # @return [Boolean] true if resolution_status is "merged"
       def merged?
         resolution_status == "merged"
       end
 
+      # Returns the canonical entity (follows merge chain)
+      #
+      # If this entity has been merged, recursively follows the canonical_id
+      # chain to find the ultimate canonical entity.
+      #
+      # @return [Entity] the canonical entity or self if not merged
       def canonical_entity
-        merged? ? merged_into&.canonical_entity || merged_into : self
+        merged? ? canonical&.canonical_entity || canonical : self
       end
 
+      # Returns all alias names as an array of strings
+      #
+      # @return [Array<String>] alias names
       def all_aliases
-        aliases.pluck(:alias_text)
+        aliases.pluck(:name)
       end
 
-      def add_alias(text, type: nil, confidence: 1.0)
-        aliases.find_or_create_by!(alias_text: text) do |a|
-          a.alias_type = type
+      # Adds an alias to this entity
+      #
+      # Validates the alias before creation using AliasFilter.
+      # Returns nil if validation fails.
+      #
+      # @param text [String] the alias text
+      # @param kind [String, nil] alias kind (name, nickname, email, handle, abbreviation, title)
+      # @param confidence [Float] confidence score (0.0 to 1.0)
+      # @return [EntityAlias, nil] the created alias or nil if validation failed
+      def add_alias(text, kind: nil, confidence: 1.0)
+        # Pre-validate before attempting to create
+        return nil unless Validation::AliasFilter.valid?(text, name: name)
+
+        aliases.find_or_create_by!(name: text) do |a|
+          a.kind = kind
           a.confidence = confidence
         end
+      rescue ActiveRecord::RecordInvalid
+        # Alias validation failed (pronoun, generic term, etc.)
+        nil
       end
 
-      def matches_name?(name)
-        return true if canonical_name.downcase == name.downcase
+      # Checks if the entity matches a query (by name or alias)
+      #
+      # @param query [String] the name to match (case-insensitive)
+      # @return [Boolean] true if name or any alias matches
+      def matches_name?(query)
+        return true if self.name.downcase == query.downcase
 
-        aliases.exists?(["LOWER(alias_text) = ?", name.downcase])
+        aliases.exists?(["LOWER(name) = ?", query.downcase])
       end
 
-      # Get all facts mentioning this entity
+      # Returns currently valid canonical facts mentioning this entity
+      #
+      # @return [ActiveRecord::Relation] currently valid facts
       def current_facts
         facts.currently_valid.canonical
       end
 
+      # Returns facts valid at a specific date
+      #
+      # @param date [Date, Time] the point in time to query
+      # @return [ActiveRecord::Relation] facts valid at the given date
       def facts_at(date)
         facts.valid_at(date).canonical
       end
 
-      # Vector similarity search for entity matching
+      # Finds entities by vector similarity using pgvector
+      #
+      # @param embedding [Array<Float>] the embedding vector to search with
+      # @param limit [Integer] maximum number of results
+      # @return [ActiveRecord::Relation] entities ordered by similarity
       def self.nearest_neighbors(embedding, limit: 10)
         return none unless embedding
 

data/lib/fact_db/models/entity_alias.rb

@@ -2,24 +2,58 @@
 
 module FactDb
   module Models
+    # Represents an alternative name for an entity
+    #
+    # Aliases allow entities to be found by various name forms (nicknames,
+    # abbreviations, email handles, etc.). Validation prevents invalid aliases
+    # like pronouns or generic terms.
+    #
+    # @example Create an alias
+    #   alias = EntityAlias.create!(entity: person, name: "Johnny", kind: "nickname")
+    #
     class EntityAlias < ActiveRecord::Base
       self.table_name = "fact_db_entity_aliases"
 
       belongs_to :entity, class_name: "FactDb::Models::Entity"
 
-      validates :alias_text, presence: true
-      validates :alias_text, uniqueness: { scope: :entity_id }
+      validates :name, presence: true
+      validates :name, uniqueness: { scope: :entity_id }
+      validate :name_is_valid
 
-      # Alias types
-      TYPES = %w[name nickname email handle abbreviation title].freeze
+      # @return [Array<String>] valid alias kinds
+      KINDS = %w[name nickname email handle abbreviation title].freeze
 
-      validates :alias_type, inclusion: { in: TYPES }, allow_nil: true
+      validates :kind, inclusion: { in: KINDS }, allow_nil: true
 
-      scope :by_type, ->(type) { where(alias_type: type) }
+      # @!method by_kind(k)
+      #   Returns aliases of a specific kind
+      #   @param k [String] the alias kind
+      #   @return [ActiveRecord::Relation]
+      scope :by_kind, ->(k) { where(kind: k) }
+
+      # @!method high_confidence
+      #   Returns aliases with confidence >= 0.9
+      #   @return [ActiveRecord::Relation]
       scope :high_confidence, -> { where("confidence >= ?", 0.9) }
 
+      # Finds an entity by alias text (case-insensitive)
+      #
+      # @param text [String] the alias text to search for
+      # @return [Entity, nil] the entity with this alias or nil
       def self.find_entity_by_alias(text)
-        find_by(["LOWER(alias_text) = ?", text.downcase])&.entity
+        find_by(["LOWER(name) = ?", text.downcase])&.entity
+      end
+
+      private
+
+      def name_is_valid
+        return if name.blank?
+
+        entity_name = entity&.name
+        unless Validation::AliasFilter.valid?(name, name: entity_name)
+          reason = Validation::AliasFilter.rejection_reason(name, name: entity_name)
+          errors.add(:name, "is not a valid alias: #{reason}")
+        end
       end
     end
   end

data/lib/fact_db/models/entity_mention.rb

@@ -2,6 +2,17 @@
 
 module FactDb
   module Models
+    # Join model linking entities to facts with role information
+    #
+    # Represents how an entity is mentioned in a specific fact, including
+    # the exact text used and the semantic role (subject, object, etc.).
+    #
+    # @example Create a mention
+    #   mention = EntityMention.create!(
+    #     fact: fact, entity: person,
+    #     mention_text: "John", mention_role: "subject"
+    #   )
+    #
     class EntityMention < ActiveRecord::Base
       self.table_name = "fact_db_entity_mentions"
 
@@ -11,20 +22,42 @@ module FactDb
       validates :mention_text, presence: true
       validates :fact_id, uniqueness: { scope: [:entity_id, :mention_text] }
 
-      # Mention roles
+      # @return [Array<String>] valid mention roles
       ROLES = %w[subject object location temporal instrument beneficiary].freeze
 
       validates :mention_role, inclusion: { in: ROLES }, allow_nil: true
 
+      # @!method by_role(role)
+      #   Returns mentions with a specific role
+      #   @param role [String] the mention role
+      #   @return [ActiveRecord::Relation]
       scope :by_role, ->(role) { where(mention_role: role) }
+
+      # @!method subjects
+      #   Returns mentions with subject role
+      #   @return [ActiveRecord::Relation]
       scope :subjects, -> { by_role("subject") }
+
+      # @!method objects
+      #   Returns mentions with object role
+      #   @return [ActiveRecord::Relation]
       scope :objects, -> { by_role("object") }
+
+      # @!method high_confidence
+      #   Returns mentions with confidence >= 0.9
+      #   @return [ActiveRecord::Relation]
       scope :high_confidence, -> { where("confidence >= ?", 0.9) }
 
+      # Checks if this mention has the subject role
+      #
+      # @return [Boolean] true if mention_role is "subject"
       def subject?
         mention_role == "subject"
       end
 
+      # Checks if this mention has the object role
+      #
+      # @return [Boolean] true if mention_role is "object"
       def object?
         mention_role == "object"
       end