fact_db 0.0.1

data/examples/hr_system.rb

@@ -0,0 +1,428 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# HR System Example for FactDb
+#
+# This example demonstrates a practical HR knowledge management system:
+# - Tracking employee information over time
+# - Managing organizational hierarchy
+# - Recording promotions, transfers, and departures
+# - Auditing changes with temporal queries
+# - Detecting conflicts in employee data
+
+require "bundler/setup"
+require "fact_db"
+
+FactDb.configure do |config|
+  config.database_url = ENV.fetch("DATABASE_URL", "postgres://#{ENV['USER']}@localhost/fact_db_demo")
+  config.default_extractor = :manual
+end
+
+# Ensure database tables exist
+FactDb::Database.migrate!
+
+clock = FactDb.new
+entity_service = clock.entity_service
+fact_service = clock.fact_service
+content_service = clock.content_service
+
+puts "=" * 60
+puts "HR Knowledge Management System Demo"
+puts "=" * 60
+
+# Section 1: Setup Company Structure
+puts "\n--- Section 1: Setting Up Organization ---\n"
+
+# Create the company
+company = entity_service.create(
+  "Innovate Corp",
+  type: :organization,
+  description: "Technology company specializing in AI solutions",
+  attributes: { industry: "Technology", founded: "2010" }
+)
+
+# Create departments
+engineering = entity_service.create(
+  "Engineering Department",
+  type: :organization,
+  description: "Software engineering team",
+  attributes: { parent: company.id }
+)
+
+product = entity_service.create(
+  "Product Department",
+  type: :organization,
+  description: "Product management team",
+  attributes: { parent: company.id }
+)
+
+hr_dept = entity_service.create(
+  "Human Resources",
+  type: :organization,
+  description: "HR team",
+  attributes: { parent: company.id }
+)
+
+puts "Created company: #{company.canonical_name}"
+puts "Created departments: #{engineering.canonical_name}, #{product.canonical_name}, #{hr_dept.canonical_name}"
+
+# Create locations
+hq = entity_service.create(
+  "San Francisco HQ",
+  type: :place,
+  aliases: ["SF Office", "Headquarters"],
+  attributes: { city: "San Francisco", state: "CA" }
+)
+
+remote_office = entity_service.create(
+  "Austin Office",
+  type: :place,
+  aliases: ["Austin TX Office"],
+  attributes: { city: "Austin", state: "TX" }
+)
+
+puts "Created locations: #{hq.canonical_name}, #{remote_office.canonical_name}"
+
+# Section 2: Create Employee Profiles
+puts "\n--- Section 2: Creating Employee Profiles ---\n"
+
+employees = {}
+
+# CEO
+employees[:ceo] = entity_service.create(
+  "Katherine Rodriguez",
+  type: :person,
+  aliases: ["Kate Rodriguez", "K. Rodriguez"],
+  attributes: { employee_id: "EMP001", email: "krodriguez@innovatecorp.com" },
+  description: "Chief Executive Officer"
+)
+
+# VP Engineering
+employees[:vp_eng] = entity_service.create(
+  "Marcus Chen",
+  type: :person,
+  aliases: ["Marc Chen"],
+  attributes: { employee_id: "EMP002", email: "mchen@innovatecorp.com" },
+  description: "VP of Engineering"
+)
+
+# Senior Engineer
+employees[:senior_eng] = entity_service.create(
+  "Priya Sharma",
+  type: :person,
+  attributes: { employee_id: "EMP003", email: "psharma@innovatecorp.com" },
+  description: "Senior Software Engineer"
+)
+
+# Junior Engineer (will be promoted)
+employees[:junior_eng] = entity_service.create(
+  "Alex Kim",
+  type: :person,
+  attributes: { employee_id: "EMP004", email: "akim@innovatecorp.com" },
+  description: "Software Engineer"
+)
+
+# Product Manager
+employees[:pm] = entity_service.create(
+  "Jordan Taylor",
+  type: :person,
+  attributes: { employee_id: "EMP005", email: "jtaylor@innovatecorp.com" },
+  description: "Product Manager"
+)
+
+# HR Manager
+employees[:hr_mgr] = entity_service.create(
+  "Michelle Brown",
+  type: :person,
+  attributes: { employee_id: "EMP006", email: "mbrown@innovatecorp.com" },
+  description: "HR Manager"
+)
+
+puts "Created #{employees.length} employee profiles"
+
+# Section 3: Record Initial Employment Facts
+puts "\n--- Section 3: Recording Employment History ---\n"
+
+# Ingest an onboarding document
+onboarding_doc = content_service.create(
+  <<~DOC,
+    EMPLOYEE ONBOARDING RECORDS - 2020-2024
+
+    Katherine Rodriguez - Hired as CEO on January 15, 2020
+    Marcus Chen - Hired as Engineering Manager on March 1, 2020
+    Priya Sharma - Hired as Software Engineer on June 15, 2021
+    Alex Kim - Hired as Junior Developer on September 1, 2023
+    Jordan Taylor - Hired as Associate PM on February 1, 2022
+    Michelle Brown - Hired as HR Coordinator on April 1, 2021
+  DOC
+  type: :document,
+  title: "Historical Onboarding Records"
+)
+
+# CEO facts
+ceo_employment = fact_service.create(
+  "Katherine Rodriguez is CEO of Innovate Corp",
+  valid_at: Date.new(2020, 1, 15),
+  mentions: [
+    { entity_id: employees[:ceo].id, role: :subject, text: "Katherine Rodriguez" },
+    { entity_id: company.id, role: :object, text: "Innovate Corp" }
+  ]
+)
+ceo_employment.add_source(content: onboarding_doc, type: :primary)
+
+ceo_location = fact_service.create(
+  "Katherine Rodriguez works at San Francisco HQ",
+  valid_at: Date.new(2020, 1, 15),
+  mentions: [
+    { entity_id: employees[:ceo].id, role: :subject, text: "Katherine Rodriguez" },
+    { entity_id: hq.id, role: :location, text: "San Francisco HQ" }
+  ]
+)
+
+# VP Engineering - with promotion history
+vp_eng_original = fact_service.create(
+  "Marcus Chen is Engineering Manager at Innovate Corp",
+  valid_at: Date.new(2020, 3, 1),
+  invalid_at: Date.new(2023, 1, 1),
+  status: :superseded,
+  mentions: [
+    { entity_id: employees[:vp_eng].id, role: :subject, text: "Marcus Chen" },
+    { entity_id: company.id, role: :object, text: "Innovate Corp" }
+  ]
+)
+
+vp_eng_current = fact_service.create(
+  "Marcus Chen is VP of Engineering at Innovate Corp",
+  valid_at: Date.new(2023, 1, 1),
+  mentions: [
+    { entity_id: employees[:vp_eng].id, role: :subject, text: "Marcus Chen" },
+    { entity_id: company.id, role: :object, text: "Innovate Corp" }
+  ]
+)
+
+# Other employees
+fact_service.create(
+  "Priya Sharma is Senior Software Engineer at Innovate Corp",
+  valid_at: Date.new(2021, 6, 15),
+  mentions: [
+    { entity_id: employees[:senior_eng].id, role: :subject, text: "Priya Sharma" },
+    { entity_id: engineering.id, role: :object, text: "Engineering Department" }
+  ]
+)
+
+fact_service.create(
+  "Priya Sharma reports to Marcus Chen",
+  valid_at: Date.new(2021, 6, 15),
+  mentions: [
+    { entity_id: employees[:senior_eng].id, role: :subject, text: "Priya Sharma" },
+    { entity_id: employees[:vp_eng].id, role: :object, text: "Marcus Chen" }
+  ]
+)
+
+junior_original = fact_service.create(
+  "Alex Kim is Junior Developer at Innovate Corp",
+  valid_at: Date.new(2023, 9, 1),
+  mentions: [
+    { entity_id: employees[:junior_eng].id, role: :subject, text: "Alex Kim" },
+    { entity_id: engineering.id, role: :object, text: "Engineering Department" }
+  ]
+)
+
+fact_service.create(
+  "Jordan Taylor is Product Manager at Innovate Corp",
+  valid_at: Date.new(2022, 2, 1),
+  mentions: [
+    { entity_id: employees[:pm].id, role: :subject, text: "Jordan Taylor" },
+    { entity_id: product.id, role: :object, text: "Product Department" }
+  ]
+)
+
+hr_original = fact_service.create(
+  "Michelle Brown is HR Coordinator at Innovate Corp",
+  valid_at: Date.new(2021, 4, 1),
+  invalid_at: Date.new(2024, 7, 1),
+  status: :superseded,
+  mentions: [
+    { entity_id: employees[:hr_mgr].id, role: :subject, text: "Michelle Brown" },
+    { entity_id: hr_dept.id, role: :object, text: "Human Resources" }
+  ]
+)
+
+hr_current = fact_service.create(
+  "Michelle Brown is HR Manager at Innovate Corp",
+  valid_at: Date.new(2024, 7, 1),
+  mentions: [
+    { entity_id: employees[:hr_mgr].id, role: :subject, text: "Michelle Brown" },
+    { entity_id: hr_dept.id, role: :object, text: "Human Resources" }
+  ]
+)
+
+puts "Recorded employment history facts"
+
+# Section 4: Process a Promotion
+puts "\n--- Section 4: Processing a Promotion ---\n"
+
+# Ingest the promotion memo
+promotion_memo = content_service.create(
+  <<~MEMO,
+    INTERNAL MEMO
+    Date: January 8, 2026
+    From: Marcus Chen, VP Engineering
+    Subject: Promotion Announcement
+
+    I am pleased to announce that Alex Kim has been promoted to
+    Software Engineer, effective January 15, 2026. Alex has demonstrated
+    exceptional growth and technical skills during their time as
+    Junior Developer.
+
+    Congratulations Alex!
+  MEMO
+  type: :document,
+  title: "Promotion Memo - Alex Kim"
+)
+
+# Supersede the old fact
+promoted_fact = fact_service.supersede(
+  junior_original.id,
+  "Alex Kim is Software Engineer at Innovate Corp",
+  valid_at: Date.new(2026, 1, 15),
+  mentions: [
+    { entity_id: employees[:junior_eng].id, role: :subject, text: "Alex Kim" },
+    { entity_id: engineering.id, role: :object, text: "Engineering Department" }
+  ]
+)
+promoted_fact.add_source(content: promotion_memo, type: :primary)
+
+puts "Promoted Alex Kim from Junior Developer to Software Engineer"
+puts "Previous fact (#{junior_original.id}) now superseded"
+puts "New fact ID: #{promoted_fact.id}"
+
+# Section 5: Record a Transfer
+puts "\n--- Section 5: Recording a Transfer ---\n"
+
+# Jordan is transferring to Austin
+transfer_memo = content_service.create(
+  <<~MEMO,
+    INTERNAL MEMO
+    Date: January 10, 2026
+    Subject: Transfer Notice - Jordan Taylor
+
+    Jordan Taylor will be transferring to our Austin office
+    effective February 1, 2026. Jordan will continue in the
+    Product Manager role but will lead our Texas expansion efforts.
+  MEMO
+  type: :document,
+  title: "Transfer Notice - Jordan Taylor"
+)
+
+# Old location fact
+jordan_sf_location = fact_service.create(
+  "Jordan Taylor works at San Francisco HQ",
+  valid_at: Date.new(2022, 2, 1),
+  invalid_at: Date.new(2026, 2, 1),
+  status: :superseded,
+  mentions: [
+    { entity_id: employees[:pm].id, role: :subject, text: "Jordan Taylor" },
+    { entity_id: hq.id, role: :location, text: "San Francisco HQ" }
+  ]
+)
+
+# New location fact
+jordan_austin_location = fact_service.create(
+  "Jordan Taylor works at Austin Office",
+  valid_at: Date.new(2026, 2, 1),
+  mentions: [
+    { entity_id: employees[:pm].id, role: :subject, text: "Jordan Taylor" },
+    { entity_id: remote_office.id, role: :location, text: "Austin Office" }
+  ]
+)
+jordan_austin_location.add_source(content: transfer_memo, type: :primary)
+
+puts "Recorded Jordan Taylor's transfer to Austin Office"
+
+# Section 6: Query Employee Information
+puts "\n--- Section 6: HR Queries ---\n"
+
+# Current state of all employees
+puts "\nCurrent Employee Status:"
+puts "-" * 50
+
+employees.each do |key, employee|
+  puts "\n#{employee.canonical_name}:"
+  current_facts = fact_service.current_facts(entity: employee.id)
+  current_facts.each do |fact|
+    puts "  - #{fact.fact_text}"
+  end
+end
+
+# Section 7: Historical Query
+puts "\n--- Section 7: Historical Employee Query ---\n"
+
+# What was Alex Kim's role in December 2024?
+puts "\nAlex Kim's facts as of December 2024:"
+past_facts = fact_service.facts_at(Date.new(2024, 12, 1), entity: employees[:junior_eng].id)
+past_facts.each { |f| puts "  - #{f.fact_text}" }
+
+# What is Alex Kim's role now?
+puts "\nAlex Kim's facts as of today:"
+current_facts = fact_service.facts_at(Date.today, entity: employees[:junior_eng].id)
+current_facts.each { |f| puts "  - #{f.fact_text}" }
+
+# Section 8: Organization Chart Query
+puts "\n--- Section 8: Organization Chart ---\n"
+
+puts "\nReporting relationships:"
+# Find all "reports to" facts
+reporting_facts = fact_service.search("reports to")
+reporting_facts.each { |f| puts "  #{f.fact_text}" }
+
+puts "\nEngineering Department members:"
+engineering_facts = fact_service.current_facts(entity: engineering.id)
+engineering_facts.each { |f| puts "  #{f.fact_text}" }
+
+# Section 9: Employee Timeline
+puts "\n--- Section 9: Marcus Chen Career Timeline ---\n"
+
+timeline = fact_service.timeline(
+  entity_id: employees[:vp_eng].id,
+  from: Date.new(2020, 1, 1),
+  to: Date.today
+)
+
+timeline.each do |entry|
+  end_date = entry[:invalid_at]&.strftime("%Y-%m-%d") || "present"
+  status_marker = entry[:status] != "canonical" ? " [#{entry[:status]}]" : ""
+  puts "  #{entry[:valid_at].strftime('%Y-%m-%d')} - #{end_date}: #{entry[:fact_text]}#{status_marker}"
+end
+
+# Section 10: Audit Trail
+puts "\n--- Section 10: Audit Trail for Alex Kim ---\n"
+
+alex_facts = FactDb::Models::Fact.joins(:entity_mentions)
+  .where(entity_mentions: { entity_id: employees[:junior_eng].id })
+  .order(:created_at)
+
+puts "Complete fact history:"
+alex_facts.each do |fact|
+  status_info = fact.status != "canonical" ? " [#{fact.status}]" : ""
+  validity = fact.invalid_at ? "#{fact.valid_at} - #{fact.invalid_at}" : "#{fact.valid_at} - present"
+  puts "  [#{validity}] #{fact.fact_text}#{status_info}"
+
+  fact.fact_sources.each do |source|
+    puts "    Source: #{source.content.title} (#{source.source_type})"
+  end
+end
+
+# Section 11: Statistics
+puts "\n--- Section 11: HR System Statistics ---\n"
+
+puts "Total employees tracked: #{entity_service.people.count}"
+puts "Total departments: #{entity_service.organizations.where("description LIKE ?", "%team%").count}"
+puts "Total employment facts: #{fact_service.stats[:total]}"
+puts "Current facts: #{FactDb::Models::Fact.currently_valid.count}"
+puts "Historical facts: #{FactDb::Models::Fact.historical.count}"
+puts "Documents processed: #{content_service.stats[:total]}"
+
+puts "\n" + "=" * 60
+puts "HR System Demo Complete!"
+puts "=" * 60

data/examples/rule_based_extraction.rb

@@ -0,0 +1,258 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Rule-Based Extraction Example for FactDb
+#
+# This example demonstrates:
+# - Using the rule-based extractor
+# - Automatic pattern detection for employment, relationships, and locations
+# - Processing extracted facts into the database
+# - Handling extraction results
+
+require "bundler/setup"
+require "fact_db"
+
+FactDb.configure do |config|
+  config.database_url = ENV.fetch("DATABASE_URL", "postgres://#{ENV['USER']}@localhost/fact_db_demo")
+  config.default_extractor = :rule_based
+end
+
+# Ensure database tables exist
+FactDb::Database.migrate!
+
+clock = FactDb.new
+
+puts "=" * 60
+puts "FactDb Rule-Based Extraction Demo"
+puts "=" * 60
+
+# Sample documents to process
+documents = [
+  {
+    title: "Company Announcement",
+    type: :document,
+    text: <<~TEXT
+      FOR IMMEDIATE RELEASE - January 15, 2026
+
+      Global Tech Solutions Appoints New Leadership Team
+
+      Global Tech Solutions announced today that Jennifer Martinez has joined
+      the company as Chief Technology Officer. Martinez, who previously served
+      as VP of Engineering at DataFlow Inc from 2020 to 2025, will lead the
+      company's technical strategy.
+
+      Additionally, Michael Chen has been promoted to Chief Operating Officer,
+      effective February 1, 2026. Chen has been with Global Tech Solutions
+      since 2018.
+
+      The company, headquartered in Seattle, Washington, continues to expand
+      its presence in the cloud computing market.
+    TEXT
+  },
+  {
+    title: "HR Update Email",
+    type: :email,
+    text: <<~TEXT
+      From: hr@example.com
+      Subject: Team Updates - Q1 2026
+      Date: January 20, 2026
+
+      Hi team,
+
+      Please welcome our new hires:
+      - Sarah Williams joined our Marketing team on January 10, 2026
+      - David Lee started as Senior Developer on January 15, 2026
+      - Emma Thompson works at our London office as Regional Manager
+
+      Also note that James Wilson left the company on December 31, 2025
+      to pursue other opportunities.
+
+      Recent relocations:
+      - Lisa Anderson moved to the Austin office
+      - Robert Kim now lives in San Francisco
+
+      Best regards,
+      Human Resources
+    TEXT
+  },
+  {
+    title: "Meeting Notes",
+    type: :meeting_notes,
+    text: <<~TEXT
+      Project Status Meeting - January 22, 2026
+
+      Attendees: Tom Baker (Project Manager), Anna Kowalski (Lead Developer)
+
+      Updates:
+      - Tom Baker is leading the Alpha project launch scheduled for Q2
+      - Anna Kowalski is responsible for the backend infrastructure
+      - Partnership discussion: Maria Santos is CEO of TechPartner Corp
+      - TechPartner Corp is headquartered in Miami, Florida
+
+      Action Items:
+      - Tom to schedule follow-up with Maria Santos
+      - Anna reports to Tom Baker for the Alpha project
+    TEXT
+  }
+]
+
+# Create the rule-based extractor
+extractor = FactDb::Extractors::Base.for(:rule_based)
+
+# Section 1: Process Each Document
+puts "\n--- Section 1: Processing Documents ---\n"
+
+documents.each_with_index do |doc, index|
+  puts "\n#{'=' * 40}"
+  puts "Document #{index + 1}: #{doc[:title]}"
+  puts "=" * 40
+
+  # Ingest the content
+  content = clock.ingest(
+    doc[:text],
+    type: doc[:type],
+    title: doc[:title],
+    captured_at: Time.now
+  )
+  puts "Ingested content ID: #{content.id}"
+
+  # Extract facts and entities
+  context = { source_id: content.id, captured_at: content.captured_at }
+  extracted_facts = extractor.extract(doc[:text], context)
+
+  puts "\nExtracted #{extracted_facts.length} facts:"
+  extracted_facts.each_with_index do |fact, i|
+    puts "  #{i + 1}. #{fact[:text]}"
+    puts "     Confidence: #{fact[:confidence]}"
+    puts "     Valid from: #{fact[:valid_at]}" if fact[:valid_at]
+    puts "     Valid until: #{fact[:invalid_at]}" if fact[:invalid_at]
+    if fact[:mentions]&.any?
+      puts "     Mentions: #{fact[:mentions].map { |m| "#{m[:name]} (#{m[:role]})" }.join(', ')}"
+    end
+  end
+
+  # Also extract entities
+  entities = extractor.extract_entities(doc[:text])
+  if entities.any?
+    puts "\nExtracted #{entities.length} entities:"
+    entities.each do |entity|
+      puts "  - #{entity[:name]} (#{entity[:type]})"
+    end
+  end
+end
+
+# Section 2: Save Extracted Facts to Database
+puts "\n\n--- Section 2: Saving Extracted Facts ---\n"
+
+entity_service = clock.entity_service
+fact_service = clock.fact_service
+
+# Process first document in detail
+sample_doc = documents.first
+content = clock.content_service.search(sample_doc[:title]).first
+context = { source_id: content.id, captured_at: content.captured_at }
+result = extractor.extract(sample_doc[:text], context)
+
+result.each do |fact_data|
+  # Resolve or create mentioned entities
+  mention_records = []
+
+  fact_data[:mentions]&.each do |mention|
+    # Try to resolve the entity, create if not found
+    entity = entity_service.resolve_or_create(
+      mention[:name],
+      type: mention[:type] || :unknown,
+      description: "Auto-extracted entity"
+    )
+
+    mention_records << {
+      entity_id: entity.id,
+      role: mention[:role],
+      text: mention[:name],
+      confidence: mention[:confidence] || fact_data[:confidence]
+    }
+  end
+
+  # Create the fact
+  fact = fact_service.create(
+    fact_data[:text],
+    valid_at: fact_data[:valid_at] || Date.today,
+    invalid_at: fact_data[:invalid_at],
+    extraction_method: :rule_based,
+    confidence: fact_data[:confidence],
+    mentions: mention_records
+  )
+
+  # Link to source content
+  fact.add_source(content: content, type: :primary, confidence: fact_data[:confidence])
+
+  puts "Saved fact: #{fact.fact_text}"
+  puts "  ID: #{fact.id}, Mentions: #{fact.entity_mentions.count}"
+end
+
+# Section 3: Query the Extracted Data
+puts "\n--- Section 3: Querying Extracted Data ---\n"
+
+# Find all extracted entities
+puts "\nAll extracted entities:"
+FactDb::Models::Entity.where(resolution_status: :resolved).order(:canonical_name).each do |entity|
+  fact_count = entity.facts.count
+  puts "  #{entity.canonical_name} (#{entity.entity_type}) - #{fact_count} facts"
+end
+
+# Find facts by extraction method
+puts "\nFacts extracted by rule-based extractor:"
+FactDb::Models::Fact.by_extraction_method(:rule_based).limit(10).each do |fact|
+  puts "  [#{fact.confidence}] #{fact.fact_text}"
+end
+
+# Section 4: Pattern Examples
+puts "\n--- Section 4: Extraction Pattern Examples ---\n"
+
+test_patterns = [
+  "John Smith works at Acme Corp as a Senior Engineer.",
+  "Mary Johnson joined Microsoft on March 15, 2024.",
+  "The CEO of Apple is Tim Cook.",
+  "Sarah left Google on December 1, 2025.",
+  "Amazon is headquartered in Seattle.",
+  "Bob lives in New York City.",
+  "Dr. Lisa Chen married James Wong in 2023.",
+]
+
+puts "Testing individual patterns:\n"
+test_patterns.each do |pattern|
+  result = extractor.extract(pattern, {})
+  if result.any?
+    puts "Input: \"#{pattern}\""
+    result.each do |fact|
+      puts "  -> #{fact[:text]} (confidence: #{fact[:confidence]})"
+    end
+    puts
+  else
+    puts "Input: \"#{pattern}\""
+    puts "  -> No facts extracted"
+    puts
+  end
+end
+
+# Section 5: Statistics
+puts "\n--- Section 5: Extraction Statistics ---\n"
+
+content_stats = clock.content_service.stats
+fact_stats = clock.fact_service.stats
+entity_stats = entity_service.stats
+
+puts "Content ingested: #{content_stats[:total]}"
+puts "Entities created: #{entity_stats[:total]}"
+puts "Facts extracted: #{fact_stats[:total]}"
+
+if fact_stats[:by_extraction_method]
+  puts "\nFacts by extraction method:"
+  fact_stats[:by_extraction_method].each do |method, count|
+    puts "  #{method}: #{count}"
+  end
+end
+
+puts "\n" + "=" * 60
+puts "Rule-Based Extraction Demo Complete!"
+puts "=" * 60