fact_db 0.0.2 → 0.0.3

data/examples/{basic_usage.rb → 010_basic_usage.rb}

@@ -10,28 +10,20 @@
 # - Creating facts manually
 # - Querying facts
 
-require "bundler/setup"
-require "fact_db"
+require_relative "utilities"
+require "amazing_print"
+
+demo_setup!("FactDb Basic Usage Demo")
+demo_configure_logging(__FILE__)
 
-# Configure FactDb
 FactDb.configure do |config|
-  config.database_url = ENV.fetch("DATABASE_URL", "postgres://#{ENV['USER']}@localhost/fact_db_demo")
   config.default_extractor = :manual
-  config.fuzzy_match_threshold = 0.85
 end
 
-# Ensure database tables exist
-FactDb::Database.migrate!
-
-# Create a new FactDb instance (the "clock")
-clock = FactDb.new
-
-puts "=" * 60
-puts "FactDb Basic Usage Demo"
-puts "=" * 60
+# Create a new FactDb instance
+facts = FactDb.new
 
-# Step 1: Ingest some content
-puts "\n--- Step 1: Ingesting Content ---\n"
+demo_section("Step 1: Ingesting Content")
 
 email_content = <<~EMAIL
   From: hr@acme.com
@@ -49,9 +41,9 @@ email_content = <<~EMAIL
   HR Department
 EMAIL
 
-content = clock.ingest(
+content = facts.ingest(
   email_content,
-  type: :email,
+  kind: :email,
   title: "New Hire Announcement - Jane Smith",
   captured_at: Time.new(2026, 1, 8)
 )
@@ -60,42 +52,40 @@ puts "Ingested content ID: #{content.id}"
 puts "Content hash: #{content.content_hash}"
 puts "Word count: #{content.word_count}"
 
-# Step 2: Create entities
-puts "\n--- Step 2: Creating Entities ---\n"
+demo_section("Step 2: Creating/Finding Entities")
 
-entity_service = clock.entity_service
+entity_service = facts.entity_service
 
-jane = entity_service.create(
+jane = entity_service.resolve_or_create(
   "Jane Smith",
-  type: :person,
+  kind: :person,
   aliases: ["J. Smith"],
   description: "Director of Engineering at Acme Corp"
 )
-puts "Created entity: #{jane.canonical_name} (ID: #{jane.id})"
+puts "Entity: #{jane.name} (ID: #{jane.id})"
 
-acme = entity_service.create(
+acme = entity_service.resolve_or_create(
   "Acme Corp",
-  type: :organization,
+  kind: :organization,
   aliases: ["Acme", "Acme Corporation"],
   description: "Technology company"
 )
-puts "Created entity: #{acme.canonical_name} (ID: #{acme.id})"
+puts "Entity: #{acme.name} (ID: #{acme.id})"
 
-techstartup = entity_service.create(
+techstartup = entity_service.resolve_or_create(
   "TechStartup Inc",
-  type: :organization,
+  kind: :organization,
   aliases: ["TechStartup"],
   description: "Technology startup company"
 )
-puts "Created entity: #{techstartup.canonical_name} (ID: #{techstartup.id})"
+puts "Entity: #{techstartup.name} (ID: #{techstartup.id})"
 
-# Step 3: Create facts
-puts "\n--- Step 3: Creating Facts ---\n"
+demo_section("Step 3: Creating/Finding Facts")
 
-fact_service = clock.fact_service
+fact_service = facts.fact_service
 
 # Fact 1: Jane works at Acme
-fact1 = fact_service.create(
+fact1 = fact_service.find_or_create(
   "Jane Smith is Director of Engineering at Acme Corp",
   valid_at: Date.new(2026, 1, 8),
   extraction_method: :manual,
@@ -105,11 +95,11 @@ fact1 = fact_service.create(
     { entity_id: acme.id, role: :object, text: "Acme Corp" }
   ]
 )
-puts "Created fact: #{fact1.fact_text}"
+puts "Fact: #{fact1.text}"
 puts "  Valid from: #{fact1.valid_at}"
 
 # Fact 2: Jane previously worked at TechStartup (now invalid)
-fact2 = fact_service.create(
+fact2 = fact_service.find_or_create(
   "Jane Smith was VP of Engineering at TechStartup Inc",
   valid_at: Date.new(2023, 1, 1),
   invalid_at: Date.new(2026, 1, 7),
@@ -120,45 +110,46 @@ fact2 = fact_service.create(
     { entity_id: techstartup.id, role: :object, text: "TechStartup Inc" }
   ]
 )
-puts "Created fact: #{fact2.fact_text}"
+puts "Fact: #{fact2.text}"
 puts "  Valid from: #{fact2.valid_at} to #{fact2.invalid_at}"
 
-# Link facts to source content
-fact1.add_source(content: content, type: :primary, confidence: 1.0)
-fact2.add_source(content: content, type: :supporting, confidence: 0.8)
+# Link facts to source content (skip if already linked)
+fact1.add_source(source: content, kind: :primary, confidence: 1.0) rescue nil
+fact2.add_source(source: content, kind: :supporting, confidence: 0.8) rescue nil
 
-# Step 4: Query facts
-puts "\n--- Step 4: Querying Facts ---\n"
+demo_section("Step 4: Querying Facts")
 
 # Get current facts about Jane
 puts "\nCurrent facts about Jane Smith:"
 current_facts = fact_service.current_facts(entity: jane.id)
 current_facts.each do |fact|
-  puts "  - #{fact.fact_text}"
+  puts "  - #{fact.text}"
 end
 
 # Get facts valid at a specific date (when Jane was at TechStartup)
 puts "\nFacts about Jane on January 1, 2024:"
 past_facts = fact_service.facts_at(Date.new(2024, 1, 1), entity: jane.id)
 past_facts.each do |fact|
-  puts "  - #{fact.fact_text}"
+  puts "  - #{fact.text}"
 end
 
 # Get all facts (including historical)
 puts "\nAll facts in the system:"
-all_facts = clock.query_facts
-all_facts.each do |fact|
-  status = fact.invalid_at ? "(historical)" : "(current)"
-  puts "  - #{fact.fact_text} #{status}"
+all_facts = facts.query_facts
+all_facts.each_fact do |fact|
+  status = fact[:invalid_at] ? "(historical)" : "(current)"
+  puts "  - #{fact[:text]} #{status}"
 end
 
-# Step 5: Get statistics
-puts "\n--- Step 5: Statistics ---\n"
+demo_section("Step 5: Statistics")
+
+puts "\nSource stats:"
+ap facts.source_service.stats
+
+puts "\nEntity stats:"
+ap entity_service.stats
 
-puts "Content stats: #{clock.content_service.stats}"
-puts "Entity stats: #{entity_service.stats}"
-puts "Fact stats: #{fact_service.stats}"
+puts "\nFact stats:"
+ap fact_service.stats
 
-puts "\n" + "=" * 60
-puts "Demo complete!"
-puts "=" * 60
+demo_footer

data/examples/{entity_management.rb → 020_entity_management.rb}

@@ -11,69 +11,56 @@
 # - Searching entities
 # - Building entity timelines
 
-require "bundler/setup"
-require "fact_db"
+require_relative "utilities"
 
-FactDb.configure do |config|
-  config.database_url = ENV.fetch("DATABASE_URL", "postgres://#{ENV['USER']}@localhost/fact_db_demo")
-  config.fuzzy_match_threshold = 0.85
-  config.auto_merge_threshold = 0.95
-end
-
-# Ensure database tables exist
-FactDb::Database.migrate!
+demo_setup!("FactDb Entity Management Demo")
+demo_configure_logging(__FILE__)
 
-clock = FactDb.new
-entity_service = clock.entity_service
-fact_service = clock.fact_service
+facts = FactDb.new
+entity_service = facts.entity_service
+fact_service = facts.fact_service
 
-puts "=" * 60
-puts "FactDb Entity Management Demo"
-puts "=" * 60
-
-# Section 1: Creating Entities
-puts "\n--- Section 1: Creating Entities ---\n"
+demo_section("Section 1: Creating Entities")
 
 # Create a person entity with aliases
 person = entity_service.create(
   "Robert Johnson",
-  type: :person,
+  kind: :person,
   aliases: ["Bob Johnson", "R. Johnson", "Bobby"],
   attributes: { email: "rjohnson@example.com", department: "Sales" },
   description: "Senior Sales Representative"
 )
-puts "Created person: #{person.canonical_name}"
-puts "  Aliases: #{person.aliases.map(&:alias_text).join(', ')}"
-puts "  Type: #{person.entity_type}"
+puts "Created person: #{person.name}"
+puts "  Aliases: #{person.aliases.map(&:name).join(', ')}"
+puts "  Type: #{person.kind}"
 
 # Create organization entities
 org1 = entity_service.create(
   "Global Industries Inc",
-  type: :organization,
+  kind: :organization,
   aliases: ["Global Industries", "GII"],
   description: "Fortune 500 manufacturing company"
 )
-puts "\nCreated organization: #{org1.canonical_name}"
+puts "\nCreated organization: #{org1.name}"
 
 # Create a location entity
 location = entity_service.create(
   "San Francisco",
-  type: :place,
+  kind: :place,
   aliases: ["SF", "San Fran"],
   attributes: { country: "USA", state: "California" }
 )
-puts "Created place: #{location.canonical_name}"
+puts "Created place: #{location.name}"
 
-# Section 2: Entity Resolution
-puts "\n--- Section 2: Entity Resolution ---\n"
+demo_section("Section 2: Entity Resolution")
 
 # Try to resolve entities using fuzzy matching
 test_names = ["Bob Johnson", "R Johnson", "Robert J", "Global Ind", "GII"]
 
 test_names.each do |name|
-  resolved = entity_service.resolve(name, type: nil)
+  resolved = entity_service.resolve(name, kind: nil)
   if resolved
-    puts "Resolved '#{name}' -> #{resolved.canonical_name} (#{resolved.entity_type})"
+    puts "Resolved '#{name}' -> #{resolved.name} (#{resolved.kind})"
   else
     puts "Could not resolve '#{name}'"
   end
@@ -83,81 +70,82 @@ end
 puts "\nUsing resolve_or_create:"
 new_person = entity_service.resolve_or_create(
   "Maria Garcia",
-  type: :person,
+  kind: :person,
   description: "New employee"
 )
-puts "Result: #{new_person.canonical_name} (new: #{new_person.created_at == new_person.updated_at})"
+puts "Result: #{new_person.name} (new: #{new_person.created_at == new_person.updated_at})"
 
-# Section 3: Managing Aliases
-puts "\n--- Section 3: Managing Aliases ---\n"
+demo_section("Section 3: Managing Aliases")
 
 # Add more aliases to an existing entity
-entity_service.add_alias(person.id, "Robert J.", alias_type: :name, confidence: 0.9)
-entity_service.add_alias(person.id, "rjohnson@example.com", alias_type: :email, confidence: 1.0)
+entity_service.add_alias(person.id, "Robert J.", kind: :name, confidence: 0.9)
+entity_service.add_alias(person.id, "rjohnson@example.com", kind: :email, confidence: 1.0)
 
 person.reload
-puts "Updated aliases for #{person.canonical_name}:"
+puts "Updated aliases for #{person.name}:"
 person.aliases.each do |a|
-  puts "  - #{a.alias_text} (#{a.alias_type}, confidence: #{a.confidence})"
+  puts "  - #{a.name} (#{a.kind}, confidence: #{a.confidence})"
 end
 
-# Section 4: Merging Duplicate Entities
-puts "\n--- Section 4: Merging Entities ---\n"
+demo_section("Section 4: Merging Entities")
 
 # Create a duplicate entity (simulating data entry error)
+# Using "Robert Johnsen" (misspelling) to demonstrate fuzzy matching
 duplicate = entity_service.create(
-  "Bob Johnson",
-  type: :person,
-  description: "Possible duplicate of Robert Johnson"
+  "Robert Johnsen",
+  kind: :person,
+  description: "Possible duplicate of Robert Johnson (typo)"
 )
-puts "Created potential duplicate: #{duplicate.canonical_name} (ID: #{duplicate.id})"
+puts "Created potential duplicate: #{duplicate.name} (ID: #{duplicate.id})"
 
 # Find potential duplicates
 puts "\nSearching for duplicates:"
 duplicates = entity_service.find_duplicates(threshold: 0.8)
-duplicates.each do |dup_pair|
-  puts "  Potential duplicate: #{dup_pair[:entity1].canonical_name} <-> #{dup_pair[:entity2].canonical_name}"
-  puts "    Similarity: #{dup_pair[:similarity]}"
+if duplicates.empty?
+  puts "  No duplicates found above threshold 0.8"
+else
+  duplicates.each do |dup_pair|
+    puts "  Potential duplicate: #{dup_pair[:entity1].name} (ID: #{dup_pair[:entity1].id}) <-> #{dup_pair[:entity2].name} (ID: #{dup_pair[:entity2].id})"
+    puts "    Similarity: #{dup_pair[:similarity].round(3)}"
+  end
 end
 
 # Merge the duplicate into the canonical entity
 puts "\nMerging entities..."
 entity_service.merge(person.id, duplicate.id)
-puts "Merged '#{duplicate.canonical_name}' into '#{person.canonical_name}'"
+puts "Merged '#{duplicate.name}' into '#{person.name}'"
 
 # Verify the duplicate is marked as merged
 duplicate.reload
 puts "Duplicate status: #{duplicate.resolution_status}"
-puts "Merged into: #{duplicate.merged_into_id}"
+puts "Canonical ID: #{duplicate.canonical_id}"
 
-# Section 5: Searching Entities
-puts "\n--- Section 5: Searching Entities ---\n"
+demo_section("Section 5: Searching Entities")
 
 # Create more entities for search demo
-entity_service.create("Jennifer Wilson", type: :person, description: "Marketing Manager")
-entity_service.create("John Williams", type: :person, description: "Software Engineer")
-entity_service.create("Wilson & Associates", type: :organization, description: "Law firm")
+entity_service.create("Jennifer Wilson", kind: :person, description: "Marketing Manager")
+entity_service.create("John Williams", kind: :person, description: "Software Engineer")
+entity_service.create("Wilson & Associates", kind: :organization, description: "Law firm")
 
 # Text search
 puts "Search results for 'Wilson':"
 results = entity_service.search("Wilson")
 results.each do |entity|
-  puts "  - #{entity.canonical_name} (#{entity.entity_type})"
+  puts "  - #{entity.name} (#{entity.kind})"
 end
 
 # Filter by type
 puts "\nPeople only:"
-entity_service.people.each do |entity|
-  puts "  - #{entity.canonical_name}"
+entity_service.by_kind("person").each do |entity|
+  puts "  - #{entity.name}"
 end
 
 puts "\nOrganizations only:"
-entity_service.organizations.each do |entity|
-  puts "  - #{entity.canonical_name}"
+entity_service.by_kind("organization").each do |entity|
+  puts "  - #{entity.name}"
 end
 
-# Section 6: Entity Timeline
-puts "\n--- Section 6: Entity Timeline ---\n"
+demo_section("Section 6: Entity Timeline")
 
 # Create some facts about Bob to build a timeline
 fact_service.create(
@@ -189,28 +177,25 @@ fact_service.create(
 )
 
 # Build timeline for the person
-puts "Timeline for #{person.canonical_name}:"
+puts "Timeline for #{person.name}:"
 timeline = entity_service.timeline_for(person.id, from: Date.new(2017, 1, 1), to: Date.today)
 timeline.each do |entry|
   date_range = entry[:invalid_at] ? "#{entry[:valid_at]} - #{entry[:invalid_at]}" : "#{entry[:valid_at]} - present"
   puts "  [#{date_range}]"
-  puts "    #{entry[:fact_text]}"
+  puts "    #{entry[:text]}"
 end
 
-# Section 7: Statistics
-puts "\n--- Section 7: Entity Statistics ---\n"
+demo_section("Section 7: Entity Statistics")
 
 stats = entity_service.stats
 puts "Total entities: #{stats[:total]}"
-puts "By type:"
-stats[:by_type].each do |type, count|
-  puts "  #{type}: #{count}"
+puts "By kind:"
+stats[:by_kind].each do |kind, count|
+  puts "  #{kind}: #{count}"
 end
 puts "By resolution status:"
 stats[:by_status].each do |status, count|
   puts "  #{status}: #{count}"
 end
 
-puts "\n" + "=" * 60
-puts "Entity Management Demo Complete!"
-puts "=" * 60
+demo_footer("Entity Management Demo Complete!")

data/examples/{temporal_queries.rb → 030_temporal_queries.rb}

@@ -10,55 +10,44 @@
 # - Detecting fact changes over time
 # - Building temporal diffs
 
-require "bundler/setup"
-require "fact_db"
+require_relative "utilities"
 
-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
+demo_setup!("FactDb Temporal Queries Demo")
+demo_configure_logging(__FILE__)
 
-puts "=" * 60
-puts "FactDb Temporal Queries Demo"
-puts "=" * 60
+facts = FactDb.new
+entity_service = facts.entity_service
+fact_service = facts.fact_service
 
-# Setup: Create entities for our scenario
-puts "\n--- Setup: Creating Entities ---\n"
+demo_section("Setup: Creating Entities")
 
 company = entity_service.create(
   "TechCorp Ltd",
-  type: :organization,
+  kind: :organization,
   description: "Technology company"
 )
 
 ceo = entity_service.create(
   "Alice Chen",
-  type: :person,
+  kind: :person,
   description: "Executive"
 )
 
 new_ceo = entity_service.create(
   "David Park",
-  type: :person,
+  kind: :person,
   description: "Executive"
 )
 
 cfo = entity_service.create(
   "Sarah Miller",
-  type: :person,
+  kind: :person,
   description: "Finance executive"
 )
 
-puts "Created entities: #{company.canonical_name}, #{ceo.canonical_name}, #{new_ceo.canonical_name}, #{cfo.canonical_name}"
+puts "Created entities: #{company.name}, #{ceo.name}, #{new_ceo.name}, #{cfo.name}"
 
-# Section 1: Creating Temporal Facts
-puts "\n--- Section 1: Creating Temporal Facts ---\n"
+demo_section("Section 1: Creating Temporal Facts")
 
 # Fact with open-ended validity (still true)
 fact1 = fact_service.create(
@@ -66,7 +55,7 @@ fact1 = fact_service.create(
   valid_at: Date.new(2015, 1, 1),
   mentions: [{ entity_id: company.id, role: :subject, text: "TechCorp Ltd" }]
 )
-puts "Created: #{fact1.fact_text}"
+puts "Created: #{fact1.text}"
 puts "  Valid: #{fact1.valid_at} - present"
 
 # Fact with closed validity (historical)
@@ -79,7 +68,7 @@ fact2 = fact_service.create(
     { entity_id: company.id, role: :object, text: "TechCorp Ltd" }
   ]
 )
-puts "\nCreated: #{fact2.fact_text}"
+puts "\nCreated: #{fact2.text}"
 puts "  Valid: #{fact2.valid_at} - #{fact2.invalid_at}"
 
 # Current CEO
@@ -91,7 +80,7 @@ fact3 = fact_service.create(
     { entity_id: company.id, role: :object, text: "TechCorp Ltd" }
   ]
 )
-puts "\nCreated: #{fact3.fact_text}"
+puts "\nCreated: #{fact3.text}"
 puts "  Valid: #{fact3.valid_at} - present"
 
 # Another current fact
@@ -103,11 +92,10 @@ fact4 = fact_service.create(
     { entity_id: company.id, role: :object, text: "TechCorp Ltd" }
   ]
 )
-puts "\nCreated: #{fact4.fact_text}"
+puts "\nCreated: #{fact4.text}"
 puts "  Valid: #{fact4.valid_at} - present"
 
-# Section 2: Point-in-Time Queries
-puts "\n--- Section 2: Point-in-Time Queries ---\n"
+demo_section("Section 2: Point-in-Time Queries")
 
 # Query facts valid at different dates
 dates_to_query = [
@@ -121,24 +109,22 @@ 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}"
+    puts "  - #{fact.text}"
   end
 end
 
-# Section 3: Current vs Historical Facts
-puts "\n--- Section 3: Current vs Historical Facts ---\n"
+demo_section("Section 3: Current vs Historical Facts")
 
 puts "Currently valid facts about TechCorp:"
 current = fact_service.current_facts(entity: company.id)
-current.each { |f| puts "  - #{f.fact_text}" }
+current.each { |f| puts "  - #{f.text}" }
 
 puts "\nAll historical facts:"
 FactDb::Models::Fact.historical.each do |fact|
-  puts "  - #{fact.fact_text} (ended: #{fact.invalid_at})"
+  puts "  - #{fact.text} (ended: #{fact.invalid_at})"
 end
 
-# Section 4: Superseding Facts
-puts "\n--- Section 4: Superseding Facts ---\n"
+demo_section("Section 4: Superseding Facts")
 
 # Company valuation that changes over time
 valuation_2020 = fact_service.create(
@@ -146,7 +132,7 @@ valuation_2020 = fact_service.create(
   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}"
+puts "Created valuation fact: #{valuation_2020.text}"
 
 # Supersede with new valuation
 valuation_2023 = fact_service.supersede(
@@ -155,15 +141,14 @@ valuation_2023 = fact_service.supersede(
   valid_at: Date.new(2023, 1, 1),
   mentions: [{ entity_id: company.id, role: :subject, text: "TechCorp Ltd" }]
 )
-puts "\nSuperseded with: #{valuation_2023.fact_text}"
+puts "\nSuperseded with: #{valuation_2023.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"
+demo_section("Section 5: Temporal Timeline")
 
 timeline = fact_service.timeline(
   entity_id: company.id,
@@ -171,15 +156,14 @@ timeline = fact_service.timeline(
   to: Date.today
 )
 
-puts "Complete timeline for #{company.canonical_name}:"
+puts "Complete timeline for #{company.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}"
+  puts "  #{entry[:valid_at]} - #{end_date}: #{entry[:text]}#{status_indicator}"
 end
 
-# Section 6: Temporal Diff
-puts "\n--- Section 6: Temporal Diff ---\n"
+demo_section("Section 6: Temporal Diff")
 
 temporal_query = FactDb::Temporal::Query.new
 
@@ -193,53 +177,49 @@ diff = temporal_query.diff(
 
 if diff[:added].any?
   puts "\n  Added:"
-  diff[:added].each { |f| puts "    + #{f.fact_text}" }
+  diff[:added].each { |f| puts "    + #{f.text}" }
 end
 
 if diff[:removed].any?
   puts "\n  Removed:"
-  diff[:removed].each { |f| puts "    - #{f.fact_text}" }
+  diff[:removed].each { |f| puts "    - #{f.text}" }
 end
 
 if diff[:unchanged].any?
   puts "\n  Unchanged:"
-  diff[:unchanged].each { |f| puts "    = #{f.fact_text}" }
+  diff[:unchanged].each { |f| puts "    = #{f.text}" }
 end
 
-# Section 7: Facts Created/Invalidated in Date Range
-puts "\n--- Section 7: Facts by Creation/Invalidation Period ---\n"
+demo_section("Section 7: Facts Created/Invalidated in Date Range")
 
 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})" }
+new_facts.each { |f| puts "  - #{f.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})" }
+ended_facts.each { |f| puts "  - #{f.text} (ended #{f.invalid_at})" }
 
-# Section 8: Entity Role Queries
-puts "\n--- Section 8: Query by Entity Role ---\n"
+demo_section("Section 8: Entity Role Queries")
 
 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}" }
+subject_facts.each { |f| puts "  - #{f.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}" }
+object_facts.each { |f| puts "  - #{f.text}" }
 
-puts "\n" + "=" * 60
-puts "Temporal Queries Demo Complete!"
-puts "=" * 60
+demo_footer