fact_db 0.0.1

data/examples/temporal_queries.rb

@@ -0,0 +1,245 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Temporal Queries Example for FactDb
+#
+# This example demonstrates:
+# - Creating facts with temporal bounds
+# - Querying facts at specific points in time
+# - Superseding facts (replacing old with new)
+# - Detecting fact changes over time
+# - Building temporal diffs
+
+require "bundler/setup"
+require "fact_db"
+
+FactDb.configure do |config|
+  config.database_url = ENV.fetch("DATABASE_URL", "postgres://#{ENV['USER']}@localhost/fact_db_demo")
+end
+
+# Ensure database tables exist
+FactDb::Database.migrate!
+
+clock = FactDb.new
+entity_service = clock.entity_service
+fact_service = clock.fact_service
+
+puts "=" * 60
+puts "FactDb Temporal Queries Demo"
+puts "=" * 60
+
+# Setup: Create entities for our scenario
+puts "\n--- Setup: Creating Entities ---\n"
+
+company = entity_service.create(
+  "TechCorp Ltd",
+  type: :organization,
+  description: "Technology company"
+)
+
+ceo = entity_service.create(
+  "Alice Chen",
+  type: :person,
+  description: "Executive"
+)
+
+new_ceo = entity_service.create(
+  "David Park",
+  type: :person,
+  description: "Executive"
+)
+
+cfo = entity_service.create(
+  "Sarah Miller",
+  type: :person,
+  description: "Finance executive"
+)
+
+puts "Created entities: #{company.canonical_name}, #{ceo.canonical_name}, #{new_ceo.canonical_name}, #{cfo.canonical_name}"
+
+# Section 1: Creating Temporal Facts
+puts "\n--- Section 1: Creating Temporal Facts ---\n"
+
+# Fact with open-ended validity (still true)
+fact1 = fact_service.create(
+  "TechCorp Ltd is headquartered in Austin, Texas",
+  valid_at: Date.new(2015, 1, 1),
+  mentions: [{ entity_id: company.id, role: :subject, text: "TechCorp Ltd" }]
+)
+puts "Created: #{fact1.fact_text}"
+puts "  Valid: #{fact1.valid_at} - present"
+
+# Fact with closed validity (historical)
+fact2 = fact_service.create(
+  "Alice Chen is CEO of TechCorp Ltd",
+  valid_at: Date.new(2018, 3, 1),
+  invalid_at: Date.new(2024, 12, 31),
+  mentions: [
+    { entity_id: ceo.id, role: :subject, text: "Alice Chen" },
+    { entity_id: company.id, role: :object, text: "TechCorp Ltd" }
+  ]
+)
+puts "\nCreated: #{fact2.fact_text}"
+puts "  Valid: #{fact2.valid_at} - #{fact2.invalid_at}"
+
+# Current CEO
+fact3 = fact_service.create(
+  "David Park is CEO of TechCorp Ltd",
+  valid_at: Date.new(2025, 1, 1),
+  mentions: [
+    { entity_id: new_ceo.id, role: :subject, text: "David Park" },
+    { entity_id: company.id, role: :object, text: "TechCorp Ltd" }
+  ]
+)
+puts "\nCreated: #{fact3.fact_text}"
+puts "  Valid: #{fact3.valid_at} - present"
+
+# Another current fact
+fact4 = fact_service.create(
+  "Sarah Miller is CFO of TechCorp Ltd",
+  valid_at: Date.new(2020, 6, 15),
+  mentions: [
+    { entity_id: cfo.id, role: :subject, text: "Sarah Miller" },
+    { entity_id: company.id, role: :object, text: "TechCorp Ltd" }
+  ]
+)
+puts "\nCreated: #{fact4.fact_text}"
+puts "  Valid: #{fact4.valid_at} - present"
+
+# Section 2: Point-in-Time Queries
+puts "\n--- Section 2: Point-in-Time Queries ---\n"
+
+# Query facts valid at different dates
+dates_to_query = [
+  Date.new(2019, 6, 1),  # Alice was CEO
+  Date.new(2024, 6, 1),  # Alice still CEO
+  Date.new(2025, 6, 1),  # David is CEO
+  Date.today
+]
+
+dates_to_query.each do |date|
+  puts "\nFacts about TechCorp on #{date}:"
+  facts = fact_service.facts_at(date, entity: company.id)
+  facts.each do |fact|
+    puts "  - #{fact.fact_text}"
+  end
+end
+
+# Section 3: Current vs Historical Facts
+puts "\n--- Section 3: Current vs Historical Facts ---\n"
+
+puts "Currently valid facts about TechCorp:"
+current = fact_service.current_facts(entity: company.id)
+current.each { |f| puts "  - #{f.fact_text}" }
+
+puts "\nAll historical facts:"
+FactDb::Models::Fact.historical.each do |fact|
+  puts "  - #{fact.fact_text} (ended: #{fact.invalid_at})"
+end
+
+# Section 4: Superseding Facts
+puts "\n--- Section 4: Superseding Facts ---\n"
+
+# Company valuation that changes over time
+valuation_2020 = fact_service.create(
+  "TechCorp Ltd has a market valuation of $500 million",
+  valid_at: Date.new(2020, 1, 1),
+  mentions: [{ entity_id: company.id, role: :subject, text: "TechCorp Ltd" }]
+)
+puts "Created valuation fact: #{valuation_2020.fact_text}"
+
+# Supersede with new valuation
+valuation_2023 = fact_service.supersede(
+  valuation_2020.id,
+  "TechCorp Ltd has a market valuation of $1.2 billion",
+  valid_at: Date.new(2023, 1, 1),
+  mentions: [{ entity_id: company.id, role: :subject, text: "TechCorp Ltd" }]
+)
+puts "\nSuperseded with: #{valuation_2023.fact_text}"
+
+# Check the old fact status
+valuation_2020.reload
+puts "\nOriginal fact status: #{valuation_2020.status}"
+puts "Original fact now invalid at: #{valuation_2020.invalid_at}"
+
+# Section 5: Temporal Timeline
+puts "\n--- Section 5: Temporal Timeline for Company ---\n"
+
+timeline = fact_service.timeline(
+  entity_id: company.id,
+  from: Date.new(2015, 1, 1),
+  to: Date.today
+)
+
+puts "Complete timeline for #{company.canonical_name}:"
+timeline.each do |entry|
+  end_date = entry[:invalid_at] || "present"
+  status_indicator = entry[:status] == "canonical" ? "" : " [#{entry[:status]}]"
+  puts "  #{entry[:valid_at]} - #{end_date}: #{entry[:fact_text]}#{status_indicator}"
+end
+
+# Section 6: Temporal Diff
+puts "\n--- Section 6: Temporal Diff ---\n"
+
+temporal_query = FactDb::Temporal::Query.new
+
+# Compare company facts between two dates
+puts "Changes to TechCorp facts between 2020-01-01 and 2025-06-01:"
+diff = temporal_query.diff(
+  entity_id: company.id,
+  from_date: Date.new(2020, 1, 1),
+  to_date: Date.new(2025, 6, 1)
+)
+
+if diff[:added].any?
+  puts "\n  Added:"
+  diff[:added].each { |f| puts "    + #{f.fact_text}" }
+end
+
+if diff[:removed].any?
+  puts "\n  Removed:"
+  diff[:removed].each { |f| puts "    - #{f.fact_text}" }
+end
+
+if diff[:unchanged].any?
+  puts "\n  Unchanged:"
+  diff[:unchanged].each { |f| puts "    = #{f.fact_text}" }
+end
+
+# Section 7: Facts Created/Invalidated in Date Range
+puts "\n--- Section 7: Facts by Creation/Invalidation Period ---\n"
+
+puts "Facts that became valid in 2025:"
+new_facts = temporal_query.facts_created_between(
+  from: Date.new(2025, 1, 1),
+  to: Date.new(2025, 12, 31)
+)
+new_facts.each { |f| puts "  - #{f.fact_text} (valid from #{f.valid_at})" }
+
+puts "\nFacts that ended in 2024:"
+ended_facts = temporal_query.facts_invalidated_between(
+  from: Date.new(2024, 1, 1),
+  to: Date.new(2024, 12, 31)
+)
+ended_facts.each { |f| puts "  - #{f.fact_text} (ended #{f.invalid_at})" }
+
+# Section 8: Entity Role Queries
+puts "\n--- Section 8: Query by Entity Role ---\n"
+
+puts "Facts where TechCorp is the subject:"
+subject_facts = temporal_query.facts_with_entity_role(
+  entity_id: company.id,
+  role: :subject
+)
+subject_facts.each { |f| puts "  - #{f.fact_text}" }
+
+puts "\nFacts where TechCorp is the object:"
+object_facts = temporal_query.facts_with_entity_role(
+  entity_id: company.id,
+  role: :object
+)
+object_facts.each { |f| puts "  - #{f.fact_text}" }
+
+puts "\n" + "=" * 60
+puts "Temporal Queries Demo Complete!"
+puts "=" * 60

data/lib/fact_db/config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "anyway_config"
+require "logger"
+
+module FactDb
+  class Config < Anyway::Config
+    config_name :fact_db
+
+    # Database configuration
+    attr_config :database_url
+    attr_config database_pool_size: 5,
+                database_timeout: 30_000
+
+    # Embedding configuration
+    attr_config :embedding_generator
+    attr_config embedding_dimensions: 1536
+
+    # LLM configuration
+    attr_config :llm_client, :llm_provider, :llm_model, :llm_api_key
+
+    # Extraction configuration
+    attr_config default_extractor: :manual
+
+    # Entity resolution thresholds
+    attr_config fuzzy_match_threshold: 0.85,
+                auto_merge_threshold: 0.95
+
+    # Logging
+    attr_config :logger
+    attr_config log_level: :info
+
+    # Build LLM client from configuration if not explicitly set
+    def llm_client
+      return super if super
+
+      return nil unless llm_provider
+
+      @llm_client ||= LLM::Adapter.new(
+        provider: llm_provider.to_sym,
+        model: llm_model,
+        api_key: llm_api_key
+      )
+    end
+
+    def logger
+      super || Logger.new($stdout, level: log_level)
+    end
+
+    def validate!
+      raise ConfigurationError, "Database URL required" unless database_url
+
+      self
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield(config) if block_given?
+      config
+    end
+
+    def reset_configuration!
+      @config = nil
+    end
+  end
+end

data/lib/fact_db/database.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "neighbor"
+
+module FactDb
+  module Database
+    class << self
+      def establish_connection!(config = FactDb.config)
+        ActiveRecord::Base.establish_connection(config.database_url)
+        ActiveRecord::Base.logger = config.logger if config.logger
+      end
+
+      def connected?
+        ActiveRecord::Base.connected?
+      end
+
+      def migrate!
+        establish_connection! unless connected?
+        migrations_path = File.expand_path("../../db/migrate", __dir__)
+        ActiveRecord::MigrationContext.new(migrations_path).migrate
+      end
+
+      def rollback!(steps = 1)
+        establish_connection! unless connected?
+        migrations_path = File.expand_path("../../db/migrate", __dir__)
+        ActiveRecord::MigrationContext.new(migrations_path).rollback(steps)
+      end
+
+      def reset!
+        establish_connection! unless connected?
+        ActiveRecord::Base.connection.tables.each do |table|
+          next if table == "schema_migrations"
+          ActiveRecord::Base.connection.drop_table(table, if_exists: true, force: :cascade)
+        end
+        migrate!
+      end
+
+      def schema_version
+        establish_connection! unless connected?
+        ActiveRecord::SchemaMigration.all.map(&:version).max || 0
+      end
+    end
+  end
+end

data/lib/fact_db/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module FactDb
+  class Error < StandardError; end
+  class ValidationError < Error; end
+  class NotFoundError < Error; end
+  class ResolutionError < Error; end
+  class ExtractionError < Error; end
+  class ConfigurationError < Error; end
+end

data/lib/fact_db/extractors/base.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Extractors
+    class Base
+      attr_reader :config
+
+      def initialize(config = FactDb.config)
+        @config = config
+      end
+
+      # Extract facts from text
+      # @param text [String] Raw text to extract from
+      # @param context [Hash] Additional context (captured_at, source_uri, etc.)
+      # @return [Array<Hash>] Array of fact data hashes
+      def extract(text, context = {})
+        raise NotImplementedError, "#{self.class} must implement #extract"
+      end
+
+      # Extract entities from text
+      # @param text [String] Raw text to extract from
+      # @return [Array<Hash>] Array of { name:, type:, aliases: }
+      def extract_entities(text)
+        raise NotImplementedError, "#{self.class} must implement #extract_entities"
+      end
+
+      # Get the extraction method name
+      def extraction_method
+        self.class.name.split("::").last.sub("Extractor", "").underscore
+      end
+
+      class << self
+        def for(type, config = FactDb.config)
+          case type.to_sym
+          when :manual
+            ManualExtractor.new(config)
+          when :llm
+            LLMExtractor.new(config)
+          when :rule_based
+            RuleBasedExtractor.new(config)
+          else
+            raise ArgumentError, "Unknown extractor type: #{type}"
+          end
+        end
+
+        def available_types
+          %i[manual llm rule_based]
+        end
+      end
+
+      protected
+
+      # Parse a date string, returning nil if invalid
+      def parse_date(date_str)
+        return nil if date_str.nil? || date_str.to_s.empty?
+
+        # Try chronic for natural language dates
+        if defined?(Chronic)
+          chronic_result = Chronic.parse(date_str)
+          return chronic_result.to_date if chronic_result
+        end
+
+        Date.parse(date_str.to_s)
+      rescue Date::Error, ArgumentError
+        nil
+      end
+
+      # Parse a timestamp string, returning nil if invalid
+      def parse_timestamp(timestamp_str)
+        return nil if timestamp_str.nil? || timestamp_str.to_s.empty?
+
+        # Try chronic for natural language dates
+        if defined?(Chronic)
+          chronic_result = Chronic.parse(timestamp_str)
+          return chronic_result if chronic_result
+        end
+
+        Time.parse(timestamp_str.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      # Build a standardized fact hash
+      def build_fact(text:, valid_at:, invalid_at: nil, mentions: [], confidence: 1.0, metadata: {})
+        {
+          text: text.strip,
+          valid_at: valid_at,
+          invalid_at: invalid_at,
+          mentions: mentions,
+          confidence: confidence,
+          metadata: metadata,
+          extraction_method: extraction_method
+        }
+      end
+
+      # Build a standardized entity hash
+      def build_entity(name:, type:, aliases: [], attributes: {})
+        {
+          name: name.strip,
+          type: type.to_s,
+          aliases: aliases.map(&:strip),
+          attributes: attributes
+        }
+      end
+
+      # Build a standardized mention hash
+      def build_mention(name:, type:, role: nil, confidence: 1.0)
+        {
+          name: name.strip,
+          type: type.to_s,
+          role: role&.to_s,
+          confidence: confidence
+        }
+      end
+    end
+  end
+end

data/lib/fact_db/extractors/llm_extractor.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FactDb
+  module Extractors
+    class LLMExtractor < Base
+      FACT_EXTRACTION_PROMPT = <<~PROMPT
+        Extract factual assertions from the following text. For each fact:
+        1. State the assertion clearly and concisely
+        2. Identify when it became true (valid_at) if mentioned
+        3. Identify when it stopped being true (invalid_at) if mentioned
+        4. Identify entities mentioned (people, organizations, places, products)
+        5. Assign a confidence score (0.0 to 1.0) based on how explicitly stated the fact is
+
+        Text:
+        %<text>s
+
+        Return as a JSON array with this structure:
+        [
+          {
+            "text": "Paula works at Microsoft as Principal Engineer",
+            "valid_at": "2024-01-10",
+            "invalid_at": null,
+            "confidence": 0.95,
+            "mentions": [
+              {"name": "Paula", "type": "person", "role": "subject"},
+              {"name": "Microsoft", "type": "organization", "role": "object"}
+            ]
+          }
+        ]
+
+        Rules:
+        - Extract only factual assertions, not opinions or speculation
+        - Use ISO 8601 date format (YYYY-MM-DD) when possible
+        - Set invalid_at to null if the fact is still true or unknown
+        - Set valid_at to null if the timing is not mentioned
+        - Entity types: person, organization, place, product, event, concept
+        - Roles: subject, object, location, temporal, instrument, beneficiary
+
+        Return only valid JSON, no additional text.
+      PROMPT
+
+      ENTITY_EXTRACTION_PROMPT = <<~PROMPT
+        Extract all named entities from the following text.
+        For each entity:
+        1. Identify the canonical name
+        2. Classify the type (person, organization, place, product, event, concept)
+        3. List any aliases or alternative names mentioned
+
+        Text:
+        %<text>s
+
+        Return as a JSON array:
+        [
+          {
+            "name": "Paula Chen",
+            "type": "person",
+            "aliases": ["Paula", "P. Chen"]
+          }
+        ]
+
+        Return only valid JSON, no additional text.
+      PROMPT
+
+      def extract(text, context = {})
+        return [] if text.nil? || text.strip.empty?
+
+        client = config.llm_client
+        raise ConfigurationError, "LLM client not configured" unless client
+
+        prompt = format(FACT_EXTRACTION_PROMPT, text: text)
+        response = call_llm(client, prompt)
+
+        parse_fact_response(response, context)
+      end
+
+      def extract_entities(text)
+        return [] if text.nil? || text.strip.empty?
+
+        client = config.llm_client
+        raise ConfigurationError, "LLM client not configured" unless client
+
+        prompt = format(ENTITY_EXTRACTION_PROMPT, text: text)
+        response = call_llm(client, prompt)
+
+        parse_entity_response(response)
+      end
+
+      private
+
+      def call_llm(client, prompt)
+        # Support multiple LLM client interfaces
+        if client.respond_to?(:chat)
+          # Standard chat interface (most LLM gems)
+          client.chat(prompt)
+        elsif client.respond_to?(:complete)
+          # Completion interface
+          client.complete(prompt)
+        elsif client.respond_to?(:call)
+          # Callable/lambda interface
+          client.call(prompt)
+        else
+          raise ConfigurationError, "LLM client must respond to :chat, :complete, or :call"
+        end
+      end
+
+      def parse_fact_response(response, context)
+        json = extract_json(response)
+        parsed = JSON.parse(json)
+
+        parsed.map do |fact_data|
+          valid_at = parse_timestamp(fact_data["valid_at"]) ||
+                     context[:captured_at] ||
+                     Time.current
+
+          build_fact(
+            text: fact_data["text"],
+            valid_at: valid_at,
+            invalid_at: parse_timestamp(fact_data["invalid_at"]),
+            mentions: parse_mentions(fact_data["mentions"]),
+            confidence: fact_data["confidence"]&.to_f || 0.8,
+            metadata: { llm_response: fact_data }
+          )
+        end
+      rescue JSON::ParserError => e
+        config.logger&.warn("Failed to parse LLM fact response: #{e.message}")
+        []
+      end
+
+      def parse_entity_response(response)
+        json = extract_json(response)
+        parsed = JSON.parse(json)
+
+        parsed.map do |entity_data|
+          build_entity(
+            name: entity_data["name"],
+            type: entity_data["type"] || "concept",
+            aliases: entity_data["aliases"] || [],
+            attributes: entity_data["attributes"] || {}
+          )
+        end
+      rescue JSON::ParserError => e
+        config.logger&.warn("Failed to parse LLM entity response: #{e.message}")
+        []
+      end
+
+      def parse_mentions(mentions_data)
+        return [] unless mentions_data.is_a?(Array)
+
+        mentions_data.map do |mention|
+          build_mention(
+            name: mention["name"],
+            type: mention["type"] || "concept",
+            role: mention["role"],
+            confidence: mention["confidence"]&.to_f || 1.0
+          )
+        end
+      end
+
+      def extract_json(response)
+        # Handle responses that may have markdown code blocks
+        text = response.to_s.strip
+
+        # Remove markdown code blocks if present
+        if text.start_with?("```")
+          text = text.sub(/\A```(?:json)?\n?/, "").sub(/\n?```\z/, "")
+        end
+
+        # Find JSON array in response
+        if (match = text.match(/\[[\s\S]*\]/))
+          match[0]
+        else
+          text
+        end
+      end
+    end
+  end
+end