fact_db 0.0.2 → 0.0.3

data/examples/070_introspection.rb

@@ -0,0 +1,252 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Introspection Example for FactDb
+#
+# This example demonstrates:
+# - Schema introspection - discovering what the system knows
+# - Topic introspection - examining specific entities
+# - Query suggestions based on available data
+# - Retrieval strategy recommendations
+# - New service methods for entity analysis
+
+require_relative "utilities"
+
+demo_setup!("FactDb Introspection Demo")
+demo_configure_logging(__FILE__)
+
+facts = FactDb.new
+entity_service = facts.entity_service
+fact_service = facts.fact_service
+
+demo_section("Setup: Creating Sample Data")
+
+# Create entities
+maria = entity_service.resolve_or_create(
+  "Maria Santos",
+  kind: :person,
+  aliases: ["M. Santos"],
+  description: "Engineering Manager"
+)
+
+raj = entity_service.resolve_or_create(
+  "Raj Patel",
+  kind: :person,
+  description: "Senior Engineer"
+)
+
+sarah = entity_service.resolve_or_create(
+  "Sarah Kim",
+  kind: :person,
+  description: "Software Engineer"
+)
+
+techcorp = entity_service.resolve_or_create(
+  "TechCorp",
+  kind: :organization,
+  description: "Software company"
+)
+
+austin = entity_service.resolve_or_create(
+  "Austin",
+  kind: :place,
+  description: "City in Texas"
+)
+
+puts "Created 5 entities"
+
+# Create facts with various relationships
+fact_service.create(
+  "Maria Santos is Engineering Manager at TechCorp",
+  valid_at: Date.new(2023, 1, 1),
+  extraction_method: :manual,
+  confidence: 1.0,
+  mentions: [
+    { entity_id: maria.id, role: :subject, text: "Maria Santos" },
+    { entity_id: techcorp.id, role: :object, text: "TechCorp" }
+  ]
+)
+
+fact_service.create(
+  "Raj Patel reports to Maria Santos",
+  valid_at: Date.new(2023, 6, 1),
+  extraction_method: :manual,
+  mentions: [
+    { entity_id: raj.id, role: :subject, text: "Raj Patel" },
+    { entity_id: maria.id, role: :object, text: "Maria Santos" }
+  ]
+)
+
+fact_service.create(
+  "Sarah Kim reports to Maria Santos",
+  valid_at: Date.new(2024, 1, 1),
+  extraction_method: :manual,
+  mentions: [
+    { entity_id: sarah.id, role: :subject, text: "Sarah Kim" },
+    { entity_id: maria.id, role: :object, text: "Maria Santos" }
+  ]
+)
+
+# Historical fact (superseded)
+old_role = fact_service.create(
+  "Maria Santos was Senior Engineer at TechCorp",
+  valid_at: Date.new(2020, 1, 1),
+  invalid_at: Date.new(2022, 12, 31),
+  extraction_method: :manual,
+  status: :superseded,
+  mentions: [
+    { entity_id: maria.id, role: :subject, text: "Maria Santos" },
+    { entity_id: techcorp.id, role: :object, text: "TechCorp" }
+  ]
+)
+
+fact_service.create(
+  "Maria Santos works at Austin office",
+  valid_at: Date.new(2023, 1, 1),
+  extraction_method: :rule_based,
+  mentions: [
+    { entity_id: maria.id, role: :subject, text: "Maria Santos" },
+    { entity_id: austin.id, role: :location, text: "Austin" }
+  ]
+)
+
+puts "Created facts with various relationships and history"
+
+demo_section("Section 1: Schema Introspection - facts.introspect()")
+
+schema = facts.introspect
+puts "\nSystem Capabilities:"
+schema[:capabilities].each { |c| puts "  - #{c}" }
+
+puts "\nEntity Types in Database:"
+schema[:entity_kinds].each { |t| puts "  - #{t}" }
+
+puts "\nAvailable Fact Statuses:"
+schema[:fact_statuses].each { |s| puts "  - #{s}" }
+
+puts "\nExtraction Methods:"
+schema[:extraction_methods].each { |m| puts "  - #{m}" }
+
+puts "\nSupported Output Formats:"
+schema[:output_formats].each { |f| puts "  - #{f}" }
+
+puts "\nRetrieval Strategies:"
+schema[:retrieval_strategies].each { |s| puts "  - #{s}" }
+
+puts "\nStatistics:"
+puts JSON.pretty_generate(schema[:statistics])
+
+demo_section("Section 2: Topic Introspection - facts.introspect('Maria Santos')")
+
+maria_info = facts.introspect("Maria Santos")
+if maria_info
+  puts "\nEntity Information:"
+  puts "  Name: #{maria_info[:entity][:name]}"
+  puts "  Type: #{maria_info[:entity][:kind]}"
+  puts "  Status: #{maria_info[:entity][:resolution_status]}"
+
+  puts "\nFact Coverage:"
+  puts "  Canonical: #{maria_info[:coverage][:facts][:canonical]}"
+  puts "  Superseded: #{maria_info[:coverage][:facts][:superseded]}"
+  puts "  Corroborated: #{maria_info[:coverage][:facts][:corroborated]}"
+  puts "  Synthesized: #{maria_info[:coverage][:facts][:synthesized]}"
+
+  puts "\nTimespan:"
+  puts "  From: #{maria_info[:coverage][:timespan][:from]}"
+  puts "  To: #{maria_info[:coverage][:timespan][:to]}"
+
+  puts "\nRelationship Types:"
+  maria_info[:relationships].each { |r| puts "  - #{r}" }
+
+  puts "\nSuggested Queries:"
+  maria_info[:suggested_queries].each { |q| puts "  - #{q}" }
+else
+  puts "Entity not found"
+end
+
+demo_section("Section 3: Query Suggestions - facts.suggest_queries()")
+
+%w[Maria\ Santos Raj\ Patel TechCorp].each do |topic|
+  suggestions = facts.suggest_queries(topic)
+  puts "\nSuggested queries for '#{topic}':"
+  if suggestions.empty?
+    puts "  (no suggestions available)"
+  else
+    suggestions.each { |s| puts "  - #{s}" }
+  end
+end
+
+demo_section("Section 4: Strategy Suggestions")
+
+test_queries = [
+  "What happened last week?",
+  "Who works at TechCorp?",
+  "Find similar projects",
+  "Current team members",
+  "Changes since January"
+]
+
+test_queries.each do |query|
+  strategies = facts.suggest_strategies(query)
+  puts "\nQuery: \"#{query}\""
+  puts "  Recommended strategies:"
+  strategies.each do |s|
+    puts "    - #{s[:strategy]}: #{s[:description]}"
+  end
+end
+
+demo_section("Section 5: New Entity Service Methods")
+
+puts "\n--- relationship_types ---"
+puts "All relationship types in database:"
+all_relationships = entity_service.relationship_types
+all_relationships.each { |r| puts "  - #{r}" }
+
+puts "\n--- relationship_types_for(entity_id) ---"
+puts "Relationship types for Maria Santos:"
+maria_relationships = entity_service.relationship_types_for(maria.id)
+maria_relationships.each { |r| puts "  - #{r}" }
+
+puts "\n--- timespan_for(entity_id) ---"
+puts "Timespan of facts for Maria Santos:"
+timespan = entity_service.timespan_for(maria.id)
+puts "  From: #{timespan[:from]}"
+puts "  To: #{timespan[:to]}"
+
+demo_section("Section 6: New Fact Service Methods")
+
+puts "\n--- fact_stats(entity_id) ---"
+puts "Fact statistics for Maria Santos:"
+maria_stats = fact_service.fact_stats(maria.id)
+maria_stats.each { |status, count| puts "  #{status}: #{count}" }
+
+puts "\nFact statistics for all facts:"
+all_stats = fact_service.fact_stats
+all_stats.each { |status, count| puts "  #{status}: #{count}" }
+
+demo_section("Section 7: Practical Use Case - LLM Context Building")
+
+puts "\nBuilding context for an LLM query about Maria Santos:\n"
+
+# Step 1: Introspect the topic
+topic_info = facts.introspect("Maria Santos")
+
+puts "1. Entity identified: #{topic_info[:entity][:name]} (#{topic_info[:entity][:kind]})"
+puts "   Coverage: #{topic_info[:coverage][:facts][:canonical]} current facts, #{topic_info[:coverage][:facts][:superseded]} historical"
+
+# Step 2: Get facts in LLM-friendly format
+puts "\n2. Facts in text format for LLM consumption:"
+facts_text = facts.current_facts_for(maria.id, format: :text)
+puts facts_text
+
+# Step 3: Get facts in structured format for reasoning
+puts "\n3. Facts as triples for structured reasoning:"
+facts_triples = facts.current_facts_for(maria.id, format: :triples)
+facts_triples.take(5).each { |t| puts "   #{t.inspect}" }
+puts "   ..." if facts_triples.size > 5
+
+# Step 4: Suggest follow-up queries
+puts "\n4. Suggested follow-up queries:"
+topic_info[:suggested_queries].each { |q| puts "   - #{q}" }
+
+demo_footer

data/examples/{hr_system.rb → 080_hr_system.rb}

@@ -10,33 +10,26 @@
 # - Auditing changes with temporal queries
 # - Detecting conflicts in employee data
 
-require "bundler/setup"
-require "fact_db"
+require_relative "utilities"
+
+demo_setup!("HR Knowledge Management System Demo")
+demo_configure_logging(__FILE__)
 
 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
+facts = FactDb.new
+entity_service = facts.entity_service
+fact_service = facts.fact_service
+source_service = facts.source_service
 
-# Section 1: Setup Company Structure
-puts "\n--- Section 1: Setting Up Organization ---\n"
+demo_section("Section 1: Setting Up Organization")
 
 # Create the company
 company = entity_service.create(
   "Innovate Corp",
-  type: :organization,
+  kind: :organization,
   description: "Technology company specializing in AI solutions",
   attributes: { industry: "Technology", founded: "2010" }
 )
@@ -44,54 +37,53 @@ company = entity_service.create(
 # Create departments
 engineering = entity_service.create(
   "Engineering Department",
-  type: :organization,
+  kind: :organization,
   description: "Software engineering team",
   attributes: { parent: company.id }
 )
 
 product = entity_service.create(
   "Product Department",
-  type: :organization,
+  kind: :organization,
   description: "Product management team",
   attributes: { parent: company.id }
 )
 
 hr_dept = entity_service.create(
   "Human Resources",
-  type: :organization,
+  kind: :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}"
+puts "Created company: #{company.name}"
+puts "Created departments: #{engineering.name}, #{product.name}, #{hr_dept.name}"
 
 # Create locations
 hq = entity_service.create(
   "San Francisco HQ",
-  type: :place,
+  kind: :place,
   aliases: ["SF Office", "Headquarters"],
   attributes: { city: "San Francisco", state: "CA" }
 )
 
 remote_office = entity_service.create(
   "Austin Office",
-  type: :place,
+  kind: :place,
   aliases: ["Austin TX Office"],
   attributes: { city: "Austin", state: "TX" }
 )
 
-puts "Created locations: #{hq.canonical_name}, #{remote_office.canonical_name}"
+puts "Created locations: #{hq.name}, #{remote_office.name}"
 
-# Section 2: Create Employee Profiles
-puts "\n--- Section 2: Creating Employee Profiles ---\n"
+demo_section("Section 2: Create Employee Profiles")
 
 employees = {}
 
 # CEO
 employees[:ceo] = entity_service.create(
   "Katherine Rodriguez",
-  type: :person,
+  kind: :person,
   aliases: ["Kate Rodriguez", "K. Rodriguez"],
   attributes: { employee_id: "EMP001", email: "krodriguez@innovatecorp.com" },
   description: "Chief Executive Officer"
@@ -100,7 +92,7 @@ employees[:ceo] = entity_service.create(
 # VP Engineering
 employees[:vp_eng] = entity_service.create(
   "Marcus Chen",
-  type: :person,
+  kind: :person,
   aliases: ["Marc Chen"],
   attributes: { employee_id: "EMP002", email: "mchen@innovatecorp.com" },
   description: "VP of Engineering"
@@ -109,7 +101,7 @@ employees[:vp_eng] = entity_service.create(
 # Senior Engineer
 employees[:senior_eng] = entity_service.create(
   "Priya Sharma",
-  type: :person,
+  kind: :person,
   attributes: { employee_id: "EMP003", email: "psharma@innovatecorp.com" },
   description: "Senior Software Engineer"
 )
@@ -117,7 +109,7 @@ employees[:senior_eng] = entity_service.create(
 # Junior Engineer (will be promoted)
 employees[:junior_eng] = entity_service.create(
   "Alex Kim",
-  type: :person,
+  kind: :person,
   attributes: { employee_id: "EMP004", email: "akim@innovatecorp.com" },
   description: "Software Engineer"
 )
@@ -125,7 +117,7 @@ employees[:junior_eng] = entity_service.create(
 # Product Manager
 employees[:pm] = entity_service.create(
   "Jordan Taylor",
-  type: :person,
+  kind: :person,
   attributes: { employee_id: "EMP005", email: "jtaylor@innovatecorp.com" },
   description: "Product Manager"
 )
@@ -133,18 +125,17 @@ employees[:pm] = entity_service.create(
 # HR Manager
 employees[:hr_mgr] = entity_service.create(
   "Michelle Brown",
-  type: :person,
+  kind: :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"
+demo_section("Section 3: Record Initial Employment Facts")
 
 # Ingest an onboarding document
-onboarding_doc = content_service.create(
+onboarding_doc = source_service.create(
   <<~DOC,
     EMPLOYEE ONBOARDING RECORDS - 2020-2024
 
@@ -155,7 +146,7 @@ onboarding_doc = content_service.create(
     Jordan Taylor - Hired as Associate PM on February 1, 2022
     Michelle Brown - Hired as HR Coordinator on April 1, 2021
   DOC
-  type: :document,
+  kind: :document,
   title: "Historical Onboarding Records"
 )
 
@@ -168,7 +159,7 @@ ceo_employment = fact_service.create(
     { entity_id: company.id, role: :object, text: "Innovate Corp" }
   ]
 )
-ceo_employment.add_source(content: onboarding_doc, type: :primary)
+ceo_employment.add_source(source: onboarding_doc, kind: :primary)
 
 ceo_location = fact_service.create(
   "Katherine Rodriguez works at San Francisco HQ",
@@ -259,11 +250,10 @@ hr_current = fact_service.create(
 
 puts "Recorded employment history facts"
 
-# Section 4: Process a Promotion
-puts "\n--- Section 4: Processing a Promotion ---\n"
+demo_section("Section 4: Process a Promotion")
 
 # Ingest the promotion memo
-promotion_memo = content_service.create(
+promotion_memo = source_service.create(
   <<~MEMO,
     INTERNAL MEMO
     Date: January 8, 2026
@@ -277,7 +267,7 @@ promotion_memo = content_service.create(
 
     Congratulations Alex!
   MEMO
-  type: :document,
+  kind: :document,
   title: "Promotion Memo - Alex Kim"
 )
 
@@ -291,17 +281,16 @@ promoted_fact = fact_service.supersede(
     { entity_id: engineering.id, role: :object, text: "Engineering Department" }
   ]
 )
-promoted_fact.add_source(content: promotion_memo, type: :primary)
+promoted_fact.add_source(source: promotion_memo, kind: :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"
+demo_section("Section 5: Record a Transfer")
 
 # Jordan is transferring to Austin
-transfer_memo = content_service.create(
+transfer_memo = source_service.create(
   <<~MEMO,
     INTERNAL MEMO
     Date: January 10, 2026
@@ -311,7 +300,7 @@ transfer_memo = content_service.create(
     effective February 1, 2026. Jordan will continue in the
     Product Manager role but will lead our Texas expansion efforts.
   MEMO
-  type: :document,
+  kind: :document,
   title: "Transfer Notice - Jordan Taylor"
 )
 
@@ -336,52 +325,48 @@ jordan_austin_location = fact_service.create(
     { entity_id: remote_office.id, role: :location, text: "Austin Office" }
   ]
 )
-jordan_austin_location.add_source(content: transfer_memo, type: :primary)
+jordan_austin_location.add_source(source: transfer_memo, kind: :primary)
 
 puts "Recorded Jordan Taylor's transfer to Austin Office"
 
-# Section 6: Query Employee Information
-puts "\n--- Section 6: HR Queries ---\n"
+demo_section("Section 6: Query Employee Information")
 
 # Current state of all employees
 puts "\nCurrent Employee Status:"
 puts "-" * 50
 
 employees.each do |key, employee|
-  puts "\n#{employee.canonical_name}:"
+  puts "\n#{employee.name}:"
   current_facts = fact_service.current_facts(entity: employee.id)
   current_facts.each do |fact|
-    puts "  - #{fact.fact_text}"
+    puts "  - #{fact.text}"
   end
 end
 
-# Section 7: Historical Query
-puts "\n--- Section 7: Historical Employee Query ---\n"
+demo_section("Section 7: Historical Query")
 
 # 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}" }
+past_facts.each { |f| puts "  - #{f.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}" }
+current_facts.each { |f| puts "  - #{f.text}" }
 
-# Section 8: Organization Chart Query
-puts "\n--- Section 8: Organization Chart ---\n"
+demo_section("Section 8: Organization Chart Query")
 
 puts "\nReporting relationships:"
 # Find all "reports to" facts
 reporting_facts = fact_service.search("reports to")
-reporting_facts.each { |f| puts "  #{f.fact_text}" }
+reporting_facts.each { |f| puts "  #{f.text}" }
 
 puts "\nEngineering Department members:"
 engineering_facts = fact_service.current_facts(entity: engineering.id)
-engineering_facts.each { |f| puts "  #{f.fact_text}" }
+engineering_facts.each { |f| puts "  #{f.text}" }
 
-# Section 9: Employee Timeline
-puts "\n--- Section 9: Marcus Chen Career Timeline ---\n"
+demo_section("Section 9: Employee Timeline")
 
 timeline = fact_service.timeline(
   entity_id: employees[:vp_eng].id,
@@ -392,11 +377,10 @@ timeline = fact_service.timeline(
 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}"
+  puts "  #{entry[:valid_at].strftime('%Y-%m-%d')} - #{end_date}: #{entry[:text]}#{status_marker}"
 end
 
-# Section 10: Audit Trail
-puts "\n--- Section 10: Audit Trail for Alex Kim ---\n"
+demo_section("Section 10: Audit Trail")
 
 alex_facts = FactDb::Models::Fact.joins(:entity_mentions)
   .where(entity_mentions: { entity_id: employees[:junior_eng].id })
@@ -406,23 +390,20 @@ 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}"
+  puts "  [#{validity}] #{fact.text}#{status_info}"
 
   fact.fact_sources.each do |source|
-    puts "    Source: #{source.content.title} (#{source.source_type})"
+    puts "    Source: #{source.source.title} (#{source.kind})"
   end
 end
 
-# Section 11: Statistics
-puts "\n--- Section 11: HR System Statistics ---\n"
+demo_section("Section 11: Statistics")
 
-puts "Total employees tracked: #{entity_service.people.count}"
-puts "Total departments: #{entity_service.organizations.where("description LIKE ?", "%team%").count}"
+puts "Total employees tracked: #{entity_service.by_kind("person").count}"
+puts "Total departments: #{entity_service.by_kind("organization").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 "Documents processed: #{source_service.stats[:total]}"
 
-puts "\n" + "=" * 60
-puts "HR System Demo Complete!"
-puts "=" * 60
+demo_footer