fact_db 0.0.1

data/examples/basic_usage.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic Usage Example for FactDb
+#
+# This example demonstrates:
+# - Configuring FactDb
+# - Ingesting content
+# - Creating entities
+# - Creating facts manually
+# - Querying facts
+
+require "bundler/setup"
+require "fact_db"
+
+# 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
+
+# Step 1: Ingest some content
+puts "\n--- Step 1: Ingesting Content ---\n"
+
+email_content = <<~EMAIL
+  From: hr@acme.com
+  To: all@acme.com
+  Subject: New Hire Announcement
+  Date: January 8, 2026
+
+  We are pleased to announce that Jane Smith has joined Acme Corp
+  as our new Director of Engineering. Jane comes to us from
+  TechStartup Inc where she served as VP of Engineering for 3 years.
+
+  Please join me in welcoming Jane to the team!
+
+  Best regards,
+  HR Department
+EMAIL
+
+content = clock.ingest(
+  email_content,
+  type: :email,
+  title: "New Hire Announcement - Jane Smith",
+  captured_at: Time.new(2026, 1, 8)
+)
+
+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"
+
+entity_service = clock.entity_service
+
+jane = entity_service.create(
+  "Jane Smith",
+  type: :person,
+  aliases: ["J. Smith"],
+  description: "Director of Engineering at Acme Corp"
+)
+puts "Created entity: #{jane.canonical_name} (ID: #{jane.id})"
+
+acme = entity_service.create(
+  "Acme Corp",
+  type: :organization,
+  aliases: ["Acme", "Acme Corporation"],
+  description: "Technology company"
+)
+puts "Created entity: #{acme.canonical_name} (ID: #{acme.id})"
+
+techstartup = entity_service.create(
+  "TechStartup Inc",
+  type: :organization,
+  aliases: ["TechStartup"],
+  description: "Technology startup company"
+)
+puts "Created entity: #{techstartup.canonical_name} (ID: #{techstartup.id})"
+
+# Step 3: Create facts
+puts "\n--- Step 3: Creating Facts ---\n"
+
+fact_service = clock.fact_service
+
+# Fact 1: Jane works at Acme
+fact1 = fact_service.create(
+  "Jane Smith is Director of Engineering at Acme Corp",
+  valid_at: Date.new(2026, 1, 8),
+  extraction_method: :manual,
+  confidence: 1.0,
+  mentions: [
+    { entity_id: jane.id, role: :subject, text: "Jane Smith" },
+    { entity_id: acme.id, role: :object, text: "Acme Corp" }
+  ]
+)
+puts "Created fact: #{fact1.fact_text}"
+puts "  Valid from: #{fact1.valid_at}"
+
+# Fact 2: Jane previously worked at TechStartup (now invalid)
+fact2 = fact_service.create(
+  "Jane Smith was VP of Engineering at TechStartup Inc",
+  valid_at: Date.new(2023, 1, 1),
+  invalid_at: Date.new(2026, 1, 7),
+  extraction_method: :manual,
+  confidence: 0.9,
+  mentions: [
+    { entity_id: jane.id, role: :subject, text: "Jane Smith" },
+    { entity_id: techstartup.id, role: :object, text: "TechStartup Inc" }
+  ]
+)
+puts "Created fact: #{fact2.fact_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)
+
+# Step 4: Query facts
+puts "\n--- Step 4: Querying Facts ---\n"
+
+# 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}"
+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}"
+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}"
+end
+
+# Step 5: Get statistics
+puts "\n--- Step 5: Statistics ---\n"
+
+puts "Content stats: #{clock.content_service.stats}"
+puts "Entity stats: #{entity_service.stats}"
+puts "Fact stats: #{fact_service.stats}"
+
+puts "\n" + "=" * 60
+puts "Demo complete!"
+puts "=" * 60

data/examples/entity_management.rb

@@ -0,0 +1,216 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Entity Management Example for FactDb
+#
+# This example demonstrates:
+# - Creating entities with various types
+# - Managing aliases
+# - Entity resolution (fuzzy matching)
+# - Merging duplicate entities
+# - Searching entities
+# - Building entity timelines
+
+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.fuzzy_match_threshold = 0.85
+  config.auto_merge_threshold = 0.95
+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 Entity Management Demo"
+puts "=" * 60
+
+# Section 1: Creating Entities
+puts "\n--- Section 1: Creating Entities ---\n"
+
+# Create a person entity with aliases
+person = entity_service.create(
+  "Robert Johnson",
+  type: :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}"
+
+# Create organization entities
+org1 = entity_service.create(
+  "Global Industries Inc",
+  type: :organization,
+  aliases: ["Global Industries", "GII"],
+  description: "Fortune 500 manufacturing company"
+)
+puts "\nCreated organization: #{org1.canonical_name}"
+
+# Create a location entity
+location = entity_service.create(
+  "San Francisco",
+  type: :place,
+  aliases: ["SF", "San Fran"],
+  attributes: { country: "USA", state: "California" }
+)
+puts "Created place: #{location.canonical_name}"
+
+# Section 2: Entity Resolution
+puts "\n--- Section 2: Entity Resolution ---\n"
+
+# 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)
+  if resolved
+    puts "Resolved '#{name}' -> #{resolved.canonical_name} (#{resolved.entity_type})"
+  else
+    puts "Could not resolve '#{name}'"
+  end
+end
+
+# Resolve or create - creates if not found
+puts "\nUsing resolve_or_create:"
+new_person = entity_service.resolve_or_create(
+  "Maria Garcia",
+  type: :person,
+  description: "New employee"
+)
+puts "Result: #{new_person.canonical_name} (new: #{new_person.created_at == new_person.updated_at})"
+
+# Section 3: Managing Aliases
+puts "\n--- Section 3: Managing Aliases ---\n"
+
+# 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)
+
+person.reload
+puts "Updated aliases for #{person.canonical_name}:"
+person.aliases.each do |a|
+  puts "  - #{a.alias_text} (#{a.alias_type}, confidence: #{a.confidence})"
+end
+
+# Section 4: Merging Duplicate Entities
+puts "\n--- Section 4: Merging Entities ---\n"
+
+# Create a duplicate entity (simulating data entry error)
+duplicate = entity_service.create(
+  "Bob Johnson",
+  type: :person,
+  description: "Possible duplicate of Robert Johnson"
+)
+puts "Created potential duplicate: #{duplicate.canonical_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]}"
+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}'"
+
+# Verify the duplicate is marked as merged
+duplicate.reload
+puts "Duplicate status: #{duplicate.resolution_status}"
+puts "Merged into: #{duplicate.merged_into_id}"
+
+# Section 5: Searching Entities
+puts "\n--- Section 5: Searching Entities ---\n"
+
+# 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")
+
+# Text search
+puts "Search results for 'Wilson':"
+results = entity_service.search("Wilson")
+results.each do |entity|
+  puts "  - #{entity.canonical_name} (#{entity.entity_type})"
+end
+
+# Filter by type
+puts "\nPeople only:"
+entity_service.people.each do |entity|
+  puts "  - #{entity.canonical_name}"
+end
+
+puts "\nOrganizations only:"
+entity_service.organizations.each do |entity|
+  puts "  - #{entity.canonical_name}"
+end
+
+# Section 6: Entity Timeline
+puts "\n--- Section 6: Entity Timeline ---\n"
+
+# Create some facts about Bob to build a timeline
+fact_service.create(
+  "Robert Johnson joined Global Industries as Sales Associate",
+  valid_at: Date.new(2018, 3, 1),
+  invalid_at: Date.new(2020, 6, 30),
+  mentions: [
+    { entity_id: person.id, role: :subject, text: "Robert Johnson" },
+    { entity_id: org1.id, role: :object, text: "Global Industries" }
+  ]
+)
+
+fact_service.create(
+  "Robert Johnson promoted to Senior Sales Representative at Global Industries",
+  valid_at: Date.new(2020, 7, 1),
+  mentions: [
+    { entity_id: person.id, role: :subject, text: "Robert Johnson" },
+    { entity_id: org1.id, role: :object, text: "Global Industries" }
+  ]
+)
+
+fact_service.create(
+  "Robert Johnson relocated to San Francisco office",
+  valid_at: Date.new(2022, 1, 15),
+  mentions: [
+    { entity_id: person.id, role: :subject, text: "Robert Johnson" },
+    { entity_id: location.id, role: :location, text: "San Francisco" }
+  ]
+)
+
+# Build timeline for the person
+puts "Timeline for #{person.canonical_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]}"
+end
+
+# Section 7: Statistics
+puts "\n--- Section 7: Entity Statistics ---\n"
+
+stats = entity_service.stats
+puts "Total entities: #{stats[:total]}"
+puts "By type:"
+stats[:by_type].each do |type, count|
+  puts "  #{type}: #{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