fact_db 0.0.1

data/lib/fact_db/services/entity_service.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Services
+    class EntityService
+      attr_reader :config, :resolver
+
+      def initialize(config = FactDb.config)
+        @config = config
+        @resolver = Resolution::EntityResolver.new(config)
+      end
+
+      def create(name, type:, aliases: [], attributes: {}, description: nil)
+        embedding = generate_embedding(name)
+
+        entity = Models::Entity.create!(
+          canonical_name: name,
+          entity_type: type.to_s,
+          description: description,
+          metadata: attributes,
+          resolution_status: "resolved",
+          embedding: embedding
+        )
+
+        aliases.each do |alias_text|
+          entity.add_alias(alias_text)
+        end
+
+        entity
+      end
+
+      def find(id)
+        Models::Entity.find(id)
+      end
+
+      def find_by_name(name, type: nil)
+        scope = Models::Entity.where(["LOWER(canonical_name) = ?", name.downcase])
+        scope = scope.where(entity_type: type) if type
+        scope.not_merged.first
+      end
+
+      def resolve(name, type: nil)
+        @resolver.resolve(name, type: type)
+      end
+
+      def resolve_or_create(name, type:, aliases: [], attributes: {}, description: nil)
+        resolved = @resolver.resolve(name, type: type)
+        return resolved.entity if resolved
+
+        create(name, type: type, aliases: aliases, attributes: attributes, description: description)
+      end
+
+      def merge(keep_id, merge_id)
+        @resolver.merge(keep_id, merge_id)
+      end
+
+      def add_alias(entity_id, alias_text, alias_type: nil, confidence: 1.0)
+        entity = Models::Entity.find(entity_id)
+        entity.add_alias(alias_text, type: alias_type, confidence: confidence)
+      end
+
+      def search(query, type: nil, limit: 20)
+        scope = Models::Entity.not_merged
+
+        # Search canonical names and aliases
+        scope = scope.left_joins(:aliases).where(
+          "LOWER(fact_db_entities.canonical_name) LIKE ? OR LOWER(fact_db_entity_aliases.alias_text) LIKE ?",
+          "%#{query.downcase}%",
+          "%#{query.downcase}%"
+        ).distinct
+
+        scope = scope.where(entity_type: type) if type
+        scope.limit(limit)
+      end
+
+      def semantic_search(query, type: nil, limit: 20)
+        embedding = generate_embedding(query)
+        return Models::Entity.none unless embedding
+
+        scope = Models::Entity.not_merged.nearest_neighbors(embedding, limit: limit)
+        scope = scope.where(entity_type: type) if type
+        scope
+      end
+
+      def by_type(type)
+        Models::Entity.by_type(type).not_merged.order(:canonical_name)
+      end
+
+      def people(limit: nil)
+        scope = Models::Entity.people.not_merged.order(:canonical_name)
+        scope = scope.limit(limit) if limit
+        scope
+      end
+
+      def organizations(limit: nil)
+        scope = Models::Entity.organizations.not_merged.order(:canonical_name)
+        scope = scope.limit(limit) if limit
+        scope
+      end
+
+      def places(limit: nil)
+        scope = Models::Entity.places.not_merged.order(:canonical_name)
+        scope = scope.limit(limit) if limit
+        scope
+      end
+
+      def facts_about(entity_id, at: nil, status: :canonical)
+        Temporal::Query.new.execute(
+          entity_id: entity_id,
+          at: at,
+          status: status
+        )
+      end
+
+      def timeline_for(entity_id, from: nil, to: nil)
+        Temporal::Timeline.new.build(entity_id: entity_id, from: from, to: to)
+      end
+
+      def find_duplicates(threshold: nil)
+        @resolver.find_duplicates(threshold: threshold)
+      end
+
+      def auto_merge_duplicates!
+        @resolver.auto_merge_duplicates!
+      end
+
+      def stats
+        {
+          total: Models::Entity.not_merged.count,
+          total_count: Models::Entity.not_merged.count,
+          by_type: Models::Entity.not_merged.group(:entity_type).count,
+          by_status: Models::Entity.group(:resolution_status).count,
+          merged_count: Models::Entity.where(resolution_status: "merged").count,
+          with_facts: Models::Entity.joins(:entity_mentions).distinct.count
+        }
+      end
+
+      private
+
+      def generate_embedding(text)
+        return nil unless config.embedding_generator
+
+        config.embedding_generator.call(text)
+      rescue StandardError => e
+        config.logger&.warn("Failed to generate embedding: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/fact_db/services/fact_service.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Services
+    class FactService
+      attr_reader :config, :resolver, :entity_service
+
+      def initialize(config = FactDb.config)
+        @config = config
+        @resolver = Resolution::FactResolver.new(config)
+        @entity_service = EntityService.new(config)
+      end
+
+      def create(text, valid_at:, invalid_at: nil, status: :canonical, source_content_id: nil, mentions: [], extraction_method: :manual, confidence: 1.0, metadata: {})
+        embedding = generate_embedding(text)
+
+        fact = Models::Fact.create!(
+          fact_text: text,
+          valid_at: valid_at,
+          invalid_at: invalid_at,
+          status: status.to_s,
+          extraction_method: extraction_method.to_s,
+          confidence: confidence,
+          metadata: metadata,
+          embedding: embedding
+        )
+
+        # Link to source content
+        if source_content_id
+          content = Models::Content.find(source_content_id)
+          fact.add_source(content: content, type: "primary")
+        end
+
+        # Add entity mentions
+        mentions.each do |mention|
+          entity = resolve_or_create_entity(mention)
+          fact.add_mention(
+            entity: entity,
+            text: mention[:text] || mention[:name],
+            role: mention[:role],
+            confidence: mention[:confidence] || 1.0
+          )
+        end
+
+        fact
+      end
+
+      def find(id)
+        Models::Fact.find(id)
+      end
+
+      def extract_from_content(content_id, extractor: config.default_extractor)
+        content = Models::Content.find(content_id)
+        extractor_instance = Extractors::Base.for(extractor, config)
+
+        extracted = extractor_instance.extract(
+          content.raw_text,
+          { captured_at: content.captured_at }
+        )
+
+        extracted.map do |fact_data|
+          create(
+            fact_data[:text],
+            valid_at: fact_data[:valid_at],
+            invalid_at: fact_data[:invalid_at],
+            source_content_id: content_id,
+            mentions: fact_data[:mentions],
+            extraction_method: fact_data[:extraction_method] || extractor,
+            confidence: fact_data[:confidence] || 1.0,
+            metadata: fact_data[:metadata] || {}
+          )
+        end
+      end
+
+      def query(topic: nil, at: nil, entity: nil, status: :canonical, limit: nil)
+        Temporal::Query.new.execute(
+          topic: topic,
+          at: at,
+          entity_id: entity,
+          status: status,
+          limit: limit
+        )
+      end
+
+      def current_facts(entity: nil, topic: nil, limit: nil)
+        query(topic: topic, entity: entity, at: nil, status: :canonical, limit: limit)
+      end
+
+      def facts_at(date, entity: nil, topic: nil)
+        query(topic: topic, entity: entity, at: date, status: :canonical)
+      end
+
+      def timeline(entity_id:, from: nil, to: nil)
+        Temporal::Timeline.new.build(entity_id: entity_id, from: from, to: to)
+      end
+
+      def supersede(old_fact_id, new_fact_text, valid_at:, mentions: [])
+        @resolver.supersede(old_fact_id, new_fact_text, valid_at: valid_at, mentions: mentions)
+      end
+
+      def synthesize(source_fact_ids, synthesized_text, valid_at:, invalid_at: nil, mentions: [])
+        @resolver.synthesize(source_fact_ids, synthesized_text, valid_at: valid_at, invalid_at: invalid_at, mentions: mentions)
+      end
+
+      def invalidate(fact_id, at: Time.current)
+        @resolver.invalidate(fact_id, at: at)
+      end
+
+      def corroborate(fact_id, corroborating_fact_id)
+        @resolver.corroborate(fact_id, corroborating_fact_id)
+      end
+
+      def search(query, entity: nil, status: :canonical, limit: 20)
+        scope = Models::Fact.search_text(query)
+        scope = apply_filters(scope, entity: entity, status: status)
+        scope.order(valid_at: :desc).limit(limit)
+      end
+
+      def semantic_search(query, entity: nil, at: nil, limit: 20)
+        embedding = generate_embedding(query)
+        return Models::Fact.none unless embedding
+
+        scope = Models::Fact.canonical.nearest_neighbors(embedding, limit: limit * 2)
+        scope = scope.currently_valid if at.nil?
+        scope = scope.valid_at(at) if at
+        scope = scope.mentioning_entity(entity) if entity
+        scope.limit(limit)
+      end
+
+      def find_conflicts(entity_id: nil, topic: nil)
+        @resolver.find_conflicts(entity_id: entity_id, topic: topic)
+      end
+
+      def resolve_conflict(keep_fact_id, supersede_fact_ids, reason: nil)
+        @resolver.resolve_conflict(keep_fact_id, supersede_fact_ids, reason: reason)
+      end
+
+      def build_timeline_fact(entity_id:, topic: nil)
+        @resolver.build_timeline_fact(entity_id: entity_id, topic: topic)
+      end
+
+      def recent(limit: 10, status: :canonical)
+        scope = Models::Fact.where(status: status.to_s).order(created_at: :desc)
+        scope.limit(limit)
+      end
+
+      def by_extraction_method(method, limit: nil)
+        scope = Models::Fact.extracted_by(method.to_s).order(created_at: :desc)
+        scope = scope.limit(limit) if limit
+        scope
+      end
+
+      def stats
+        {
+          total: Models::Fact.count,
+          total_count: Models::Fact.count,
+          canonical_count: Models::Fact.canonical.count,
+          currently_valid_count: Models::Fact.canonical.currently_valid.count,
+          by_status: Models::Fact.group(:status).count,
+          by_extraction_method: Models::Fact.group(:extraction_method).count,
+          average_confidence: Models::Fact.average(:confidence)&.to_f&.round(3)
+        }
+      end
+
+      private
+
+      def resolve_or_create_entity(mention)
+        # If entity_id is already provided, use that entity directly
+        return Models::Entity.find(mention[:entity_id]) if mention[:entity_id]
+
+        name = mention[:name] || mention[:text]
+        type = mention[:type]&.to_sym || :concept
+
+        @entity_service.resolve_or_create(name, type: type)
+      end
+
+      def apply_filters(scope, entity: nil, status: nil)
+        scope = scope.mentioning_entity(entity) if entity
+        scope = scope.where(status: status.to_s) if status && status != :all
+        scope
+      end
+
+      def generate_embedding(text)
+        return nil unless config.embedding_generator
+
+        config.embedding_generator.call(text)
+      rescue StandardError => e
+        config.logger&.warn("Failed to generate embedding: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/fact_db/temporal/query.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Temporal
+    class Query
+      attr_reader :scope
+
+      def initialize(scope = Models::Fact.all)
+        @scope = scope
+      end
+
+      def execute(topic: nil, at: nil, entity_id: nil, status: :canonical, limit: nil)
+        result = @scope
+
+        # Status filtering
+        result = apply_status_filter(result, status)
+
+        # Temporal filtering
+        result = apply_temporal_filter(result, at)
+
+        # Entity filtering
+        result = apply_entity_filter(result, entity_id)
+
+        # Topic search
+        result = apply_topic_search(result, topic)
+
+        # Ordering - most recently valid first
+        result = result.order(valid_at: :desc)
+
+        # Limit results
+        result = result.limit(limit) if limit
+
+        result
+      end
+
+      # Currently valid facts about an entity
+      def current_facts(entity_id:)
+        execute(entity_id: entity_id, at: nil, status: :canonical)
+      end
+
+      # Facts valid at a specific point in time
+      def facts_at(date, entity_id: nil)
+        execute(at: date, entity_id: entity_id, status: :canonical)
+      end
+
+      # Facts that became valid in a date range
+      def facts_created_between(from:, to:, entity_id: nil)
+        result = @scope.canonical.became_valid_between(from, to)
+        result = result.mentioning_entity(entity_id) if entity_id
+        result.order(valid_at: :asc)
+      end
+
+      # Facts that became invalid in a date range
+      def facts_invalidated_between(from:, to:, entity_id: nil)
+        result = @scope.became_invalid_between(from, to)
+        result = result.mentioning_entity(entity_id) if entity_id
+        result.order(invalid_at: :asc)
+      end
+
+      # Semantic search with temporal filtering
+      def semantic_search(query:, at: nil, entity_id: nil, limit: 20)
+        result = @scope.canonical.search_text(query)
+        result = apply_temporal_filter(result, at)
+        result = result.mentioning_entity(entity_id) if entity_id
+        result.limit(limit)
+      end
+
+      # Find facts where entity has a specific role
+      def facts_with_entity_role(entity_id:, role:, at: nil)
+        result = @scope.canonical.with_role(entity_id, role)
+        result = apply_temporal_filter(result, at)
+        result.order(valid_at: :desc)
+      end
+
+      # Compare facts at two points in time
+      def diff(entity_id:, from_date:, to_date:)
+        facts_at_from = facts_at(from_date, entity_id: entity_id).to_a
+        facts_at_to = facts_at(to_date, entity_id: entity_id).to_a
+
+        {
+          added: facts_at_to - facts_at_from,
+          removed: facts_at_from - facts_at_to,
+          unchanged: facts_at_from & facts_at_to
+        }
+      end
+
+      private
+
+      def apply_status_filter(scope, status)
+        case status.to_sym
+        when :canonical
+          scope.canonical
+        when :superseded
+          scope.superseded
+        when :synthesized
+          scope.synthesized
+        when :all
+          scope
+        else
+          scope.where(status: status.to_s)
+        end
+      end
+
+      def apply_temporal_filter(scope, at)
+        if at.nil?
+          scope.currently_valid
+        else
+          scope.valid_at(at)
+        end
+      end
+
+      def apply_entity_filter(scope, entity_id)
+        return scope if entity_id.nil?
+
+        scope.mentioning_entity(entity_id)
+      end
+
+      def apply_topic_search(scope, topic)
+        return scope if topic.nil? || topic.empty?
+
+        scope.search_text(topic)
+      end
+    end
+  end
+end

data/lib/fact_db/temporal/timeline.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Temporal
+    class Timeline
+      include Enumerable
+
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      def each(&block)
+        to_hash.each(&block)
+      end
+
+      def build(entity_id:, from: nil, to: nil)
+        facts = fetch_facts(entity_id, from, to)
+        @events = facts.map { |fact| TimelineEvent.new(fact) }
+        self
+      end
+
+      def to_a
+        @events.sort_by(&:valid_at)
+      end
+
+      def to_hash
+        to_a.map(&:to_hash)
+      end
+
+      # Group events by year
+      def by_year
+        to_a.group_by { |event| event.valid_at.year }
+      end
+
+      # Group events by month
+      def by_month
+        to_a.group_by { |event| event.valid_at.strftime("%Y-%m") }
+      end
+
+      # Get events in a specific date range
+      def between(from, to)
+        to_a.select { |event| event.valid_at >= from && event.valid_at <= to }
+      end
+
+      # Get currently active events
+      def active
+        to_a.select(&:currently_valid?)
+      end
+
+      # Get historical (no longer valid) events
+      def historical
+        to_a.reject(&:currently_valid?)
+      end
+
+      # Find overlapping events
+      def overlapping
+        result = []
+        sorted = to_a
+
+        sorted.each_with_index do |event, i|
+          sorted[(i + 1)..].each do |other|
+            result << [event, other] if events_overlap?(event, other)
+          end
+        end
+
+        result
+      end
+
+      # Get the state at a specific point in time
+      def state_at(date)
+        to_a.select { |event| event.valid_at?(date) }
+      end
+
+      # Generate a summary of changes
+      def changes_summary
+        sorted = to_a
+
+        sorted.each_cons(2).map do |prev_event, next_event|
+          {
+            from: prev_event,
+            to: next_event,
+            gap_days: (next_event.valid_at.to_date - (prev_event.invalid_at || prev_event.valid_at).to_date).to_i
+          }
+        end
+      end
+
+      private
+
+      def fetch_facts(entity_id, from, to)
+        scope = Models::Fact.mentioning_entity(entity_id).order(valid_at: :asc)
+        scope = scope.where("valid_at >= ?", from) if from
+        scope = scope.where("valid_at <= ?", to) if to
+        scope
+      end
+
+      def events_overlap?(event1, event2)
+        return false if event1.invalid_at && event1.invalid_at <= event2.valid_at
+        return false if event2.invalid_at && event2.invalid_at <= event1.valid_at
+
+        true
+      end
+    end
+
+    class TimelineEvent
+      attr_reader :fact
+
+      delegate :id, :fact_text, :valid_at, :invalid_at, :status,
+               :currently_valid?, :valid_at?, :duration, :duration_days,
+               :entities, :source_contents, to: :fact
+
+      def initialize(fact)
+        @fact = fact
+      end
+
+      def to_hash
+        {
+          id: id,
+          fact_text: fact_text,
+          valid_at: valid_at,
+          invalid_at: invalid_at,
+          status: status,
+          duration_days: duration_days,
+          entities: entities.map(&:canonical_name)
+        }
+      end
+
+      def <=>(other)
+        valid_at <=> other.valid_at
+      end
+    end
+  end
+end

data/lib/fact_db/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FactDb
+  VERSION = "0.0.1"
+end