fact_db 0.0.2 → 0.0.3

data/examples/040_output_formats.rb

@@ -0,0 +1,177 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Output Formats Example for FactDb
+#
+# This example demonstrates:
+# - Different output formats for LLM consumption
+# - JSON, Triples, Cypher, and Text transformers
+# - How each format represents the same data differently
+
+require_relative "utilities"
+
+demo_setup!("FactDb Output Formats 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
+paula = entity_service.resolve_or_create(
+  "Paula Chen",
+  kind: :person,
+  aliases: ["P. Chen"],
+  description: "Principal Engineer"
+)
+
+microsoft = entity_service.resolve_or_create(
+  "Microsoft",
+  kind: :organization,
+  aliases: ["MSFT"],
+  description: "Technology company"
+)
+
+seattle = entity_service.resolve_or_create(
+  "Seattle",
+  kind: :place,
+  description: "City in Washington state"
+)
+
+puts "Created entities: #{paula.name}, #{microsoft.name}, #{seattle.name}"
+
+# Create facts
+fact_service.create(
+  "Paula Chen is Principal Engineer at Microsoft",
+  valid_at: Date.new(2024, 1, 10),
+  extraction_method: :manual,
+  confidence: 1.0,
+  mentions: [
+    { entity_id: paula.id, role: :subject, text: "Paula Chen" },
+    { entity_id: microsoft.id, role: :object, text: "Microsoft" }
+  ]
+)
+
+fact_service.create(
+  "Paula Chen works at the Seattle office",
+  valid_at: Date.new(2024, 1, 10),
+  extraction_method: :manual,
+  confidence: 0.95,
+  mentions: [
+    { entity_id: paula.id, role: :subject, text: "Paula Chen" },
+    { entity_id: seattle.id, role: :location, text: "Seattle" }
+  ]
+)
+
+fact_service.create(
+  "Paula Chen reports to Sarah Kim",
+  valid_at: Date.new(2024, 1, 10),
+  extraction_method: :manual,
+  confidence: 0.9,
+  mentions: [
+    { entity_id: paula.id, role: :subject, text: "Paula Chen" }
+  ]
+)
+
+puts "Created facts about Paula Chen"
+
+demo_section("Section 1: JSON Format (Default)")
+
+json_results = facts.query_facts(entity: paula.id, format: :json)
+puts "\nJSON output:"
+puts JSON.pretty_generate(json_results.to_h)
+
+demo_section("Section 2: Triples Format (Subject-Predicate-Object)")
+
+triples_results = facts.query_facts(entity: paula.id, format: :triples)
+puts "\nTriples output:"
+triples_results.each do |triple|
+  puts "  #{triple.inspect}"
+end
+
+puts <<~EXPLANATION
+
+  Triples format is ideal for:
+  - Knowledge graph representations
+  - Semantic reasoning
+  - LLM structured understanding
+EXPLANATION
+
+demo_section("Section 3: Cypher Format (Graph Notation)")
+
+cypher_results = facts.query_facts(entity: paula.id, format: :cypher)
+puts "\nCypher output:"
+puts cypher_results
+
+puts <<~EXPLANATION
+
+  Cypher format is ideal for:
+  - Graph database imports (Neo4j compatible)
+  - Visualizing entity relationships
+  - Understanding connection patterns
+EXPLANATION
+
+demo_section("Section 4: Text Format (Human-Readable)")
+
+text_results = facts.query_facts(entity: paula.id, format: :text)
+puts "\nText output:"
+puts text_results
+
+puts <<~EXPLANATION
+
+  Text format is ideal for:
+  - Direct LLM consumption
+  - Human debugging
+  - Report generation
+EXPLANATION
+
+demo_section("Section 5: Raw Format (ActiveRecord Objects)")
+
+raw_results = facts.query_facts(entity: paula.id, format: :raw)
+puts "\nRaw output (first result):"
+if raw_results.respond_to?(:raw_facts) && raw_results.raw_facts.any?
+  fact = raw_results.raw_facts.first
+  puts "  Class: #{fact.class}"
+  puts "  ID: #{fact.id}"
+  puts "  Text: #{fact.text}"
+  puts "  Valid at: #{fact.valid_at}"
+else
+  puts "  Results: #{raw_results.inspect}"
+end
+
+demo_section("Section 6: Format Comparison - Same Query, Different Views")
+
+puts "\nQuerying current facts for Paula Chen in all formats:\n"
+
+formats = %i[json triples cypher text]
+
+formats.each do |format|
+  puts "\n--- #{format.upcase} ---"
+  result = facts.current_facts_for(paula.id, format: format)
+
+  case format
+  when :json
+    if result.respond_to?(:to_h)
+      puts "#{result.fact_count} facts, #{result.entity_count} entities"
+    else
+      puts "#{result.size} facts" if result.respond_to?(:size)
+    end
+  when :triples
+    puts "#{result.size} triples generated"
+  when :cypher
+    puts "#{result.lines.count} lines of Cypher notation"
+  when :text
+    puts result.lines.first(5).join
+    puts "..." if result.lines.count > 5
+  end
+end
+
+demo_section("Section 7: Temporal Queries with Formats")
+
+puts "\nFacts at specific date (2024-06-01) in Cypher format:"
+temporal_cypher = facts.facts_at(Date.new(2024, 6, 1), entity: paula.id, format: :cypher)
+puts temporal_cypher
+
+demo_footer

data/examples/{rule_based_extraction.rb → 050_rule_based_extraction.rb}

@@ -9,28 +9,22 @@
 # - Processing extracted facts into the database
 # - Handling extraction results
 
-require "bundler/setup"
-require "fact_db"
+require_relative "utilities"
+
+demo_setup!("FactDb Rule-Based Extraction 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 = :rule_based
 end
 
-# Ensure database tables exist
-FactDb::Database.migrate!
-
-clock = FactDb.new
-
-puts "=" * 60
-puts "FactDb Rule-Based Extraction Demo"
-puts "=" * 60
+facts = FactDb.new
 
 # Sample documents to process
 documents = [
   {
     title: "Company Announcement",
-    type: :document,
+    kind: :document,
     text: <<~TEXT
       FOR IMMEDIATE RELEASE - January 15, 2026
 
@@ -51,7 +45,7 @@ documents = [
   },
   {
     title: "HR Update Email",
-    type: :email,
+    kind: :email,
     text: <<~TEXT
       From: hr@example.com
       Subject: Team Updates - Q1 2026
@@ -77,7 +71,7 @@ documents = [
   },
   {
     title: "Meeting Notes",
-    type: :meeting_notes,
+    kind: :meeting_notes,
     text: <<~TEXT
       Project Status Meeting - January 22, 2026
 
@@ -99,8 +93,10 @@ documents = [
 # Create the rule-based extractor
 extractor = FactDb::Extractors::Base.for(:rule_based)
 
-# Section 1: Process Each Document
-puts "\n--- Section 1: Processing Documents ---\n"
+# Store ingested content for later use
+ingested_content = {}
+
+demo_section("Section 1: Process Each Document")
 
 documents.each_with_index do |doc, index|
   puts "\n#{'=' * 40}"
@@ -108,12 +104,13 @@ documents.each_with_index do |doc, index|
   puts "=" * 40
 
   # Ingest the content
-  content = clock.ingest(
+  content = facts.ingest(
     doc[:text],
-    type: doc[:type],
+    kind: doc[:kind],
     title: doc[:title],
     captured_at: Time.now
   )
+  ingested_content[index] = content
   puts "Ingested content ID: #{content.id}"
 
   # Extract facts and entities
@@ -136,23 +133,25 @@ documents.each_with_index do |doc, index|
   if entities.any?
     puts "\nExtracted #{entities.length} entities:"
     entities.each do |entity|
-      puts "  - #{entity[:name]} (#{entity[:type]})"
+      puts "  - #{entity[:name]} (#{entity[:kind]})"
     end
   end
 end
 
-# Section 2: Save Extracted Facts to Database
-puts "\n\n--- Section 2: Saving Extracted Facts ---\n"
+demo_section("Section 2: Saving Extracted Facts")
 
-entity_service = clock.entity_service
-fact_service = clock.fact_service
+entity_service = facts.entity_service
+fact_service = facts.fact_service
 
-# Process first document in detail
-sample_doc = documents.first
-content = clock.content_service.search(sample_doc[:title]).first
+# Process the third document (Meeting Notes) which has extractable facts
+sample_doc = documents[2]  # "Meeting Notes" extracts 2 facts
+content = ingested_content[2]
 context = { source_id: content.id, captured_at: content.captured_at }
 result = extractor.extract(sample_doc[:text], context)
 
+puts "Processing: #{sample_doc[:title]}"
+puts "Found #{result.length} facts to save"
+
 result.each do |fact_data|
   # Resolve or create mentioned entities
   mention_records = []
@@ -161,7 +160,7 @@ result.each do |fact_data|
     # Try to resolve the entity, create if not found
     entity = entity_service.resolve_or_create(
       mention[:name],
-      type: mention[:type] || :unknown,
+      kind: mention[:kind] || :unknown,
       description: "Auto-extracted entity"
     )
 
@@ -184,30 +183,28 @@ result.each do |fact_data|
   )
 
   # Link to source content
-  fact.add_source(content: content, type: :primary, confidence: fact_data[:confidence])
+  fact.add_source(source: content, kind: :primary, confidence: fact_data[:confidence])
 
-  puts "Saved fact: #{fact.fact_text}"
+  puts "Saved 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"
+demo_section("Section 3: Query the Extracted Data")
 
 # Find all extracted entities
 puts "\nAll extracted entities:"
-FactDb::Models::Entity.where(resolution_status: :resolved).order(:canonical_name).each do |entity|
+FactDb::Models::Entity.where(resolution_status: :resolved).order(:name).each do |entity|
   fact_count = entity.facts.count
-  puts "  #{entity.canonical_name} (#{entity.entity_type}) - #{fact_count} facts"
+  puts "  #{entity.name} (#{entity.kind}) - #{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}"
+  puts "  [#{fact.confidence}] #{fact.text}"
 end
 
-# Section 4: Pattern Examples
-puts "\n--- Section 4: Extraction Pattern Examples ---\n"
+demo_section("Section 4: Pattern Examples")
 
 test_patterns = [
   "John Smith works at Acme Corp as a Senior Engineer.",
@@ -235,14 +232,13 @@ test_patterns.each do |pattern|
   end
 end
 
-# Section 5: Statistics
-puts "\n--- Section 5: Extraction Statistics ---\n"
+demo_section("Section 5: Statistics")
 
-content_stats = clock.content_service.stats
-fact_stats = clock.fact_service.stats
-entity_stats = entity_service.stats
+source_stats = facts.source_service.stats
+fact_stats = facts.fact_service.stats
+entity_stats = facts.entity_service.stats
 
-puts "Content ingested: #{content_stats[:total]}"
+puts "Content ingested: #{source_stats[:total]}"
 puts "Entities created: #{entity_stats[:total]}"
 puts "Facts extracted: #{fact_stats[:total]}"
 
@@ -253,6 +249,4 @@ if fact_stats[:by_extraction_method]
   end
 end
 
-puts "\n" + "=" * 60
-puts "Rule-Based Extraction Demo Complete!"
-puts "=" * 60
+demo_footer

data/examples/060_fluent_temporal_api.rb

@@ -0,0 +1,217 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Fluent Temporal API Example for FactDb
+#
+# This example demonstrates:
+# - The new fluent query builder API: facts.at(date).query(...)
+# - Comparing facts between two dates with diff()
+# - Point-in-time queries with chaining
+# - Getting entity state at specific moments
+
+require_relative "utilities"
+
+demo_setup!("FactDb Fluent Temporal API Demo")
+demo_configure_logging(__FILE__)
+
+facts = FactDb.new
+entity_service = facts.entity_service
+fact_service = facts.fact_service
+
+demo_section("Setup: Creating Career Progression Data")
+
+# Create entities
+alex = entity_service.resolve_or_create(
+  "Alex Rivera",
+  kind: :person,
+  description: "Software professional"
+)
+
+startup = entity_service.resolve_or_create(
+  "TechStartup Inc",
+  kind: :organization,
+  description: "Early stage company"
+)
+
+bigcorp = entity_service.resolve_or_create(
+  "BigCorp Systems",
+  kind: :organization,
+  description: "Enterprise software company"
+)
+
+sf = entity_service.resolve_or_create(
+  "San Francisco",
+  kind: :place
+)
+
+nyc = entity_service.resolve_or_create(
+  "New York City",
+  kind: :place
+)
+
+puts "Created entities for Alex's career story"
+
+# Create temporal facts showing career progression
+# 2020: Alex joins TechStartup as Junior Developer
+fact_service.find_or_create(
+  "Alex Rivera is Junior Developer at TechStartup Inc",
+  valid_at: Date.new(2020, 3, 1),
+  invalid_at: Date.new(2022, 6, 30),
+  extraction_method: :manual,
+  mentions: [
+    { entity_id: alex.id, role: :subject, text: "Alex Rivera" },
+    { entity_id: startup.id, role: :object, text: "TechStartup Inc" }
+  ]
+)
+
+fact_service.find_or_create(
+  "Alex Rivera works at San Francisco office",
+  valid_at: Date.new(2020, 3, 1),
+  invalid_at: Date.new(2023, 8, 31),
+  extraction_method: :manual,
+  mentions: [
+    { entity_id: alex.id, role: :subject, text: "Alex Rivera" },
+    { entity_id: sf.id, role: :location, text: "San Francisco" }
+  ]
+)
+
+# 2022: Promoted to Senior Developer
+fact_service.find_or_create(
+  "Alex Rivera is Senior Developer at TechStartup Inc",
+  valid_at: Date.new(2022, 7, 1),
+  invalid_at: Date.new(2023, 8, 31),
+  extraction_method: :manual,
+  mentions: [
+    { entity_id: alex.id, role: :subject, text: "Alex Rivera" },
+    { entity_id: startup.id, role: :object, text: "TechStartup Inc" }
+  ]
+)
+
+# 2023: Moves to BigCorp
+fact_service.find_or_create(
+  "Alex Rivera is Principal Engineer at BigCorp Systems",
+  valid_at: Date.new(2023, 9, 1),
+  extraction_method: :manual,
+  mentions: [
+    { entity_id: alex.id, role: :subject, text: "Alex Rivera" },
+    { entity_id: bigcorp.id, role: :object, text: "BigCorp Systems" }
+  ]
+)
+
+fact_service.find_or_create(
+  "Alex Rivera works at New York City office",
+  valid_at: Date.new(2023, 9, 1),
+  extraction_method: :manual,
+  mentions: [
+    { entity_id: alex.id, role: :subject, text: "Alex Rivera" },
+    { entity_id: nyc.id, role: :location, text: "New York City" }
+  ]
+)
+
+puts "Created career progression facts (2020-2024)"
+
+demo_section("Section 1: Fluent Query Builder - Basic Usage")
+
+puts "\nQuery: What was Alex's role in 2021?"
+results_2021 = facts.at("2021-06-15").facts_for(alex.id)
+puts "Date: 2021-06-15"
+results_2021.each_fact do |fact|
+  puts "  - #{fact[:text]}"
+end
+
+puts "\nQuery: What was Alex's role in 2022 (after promotion)?"
+results_2022 = facts.at("2022-09-01").facts_for(alex.id)
+puts "Date: 2022-09-01"
+results_2022.each_fact do |fact|
+  puts "  - #{fact[:text]}"
+end
+
+puts "\nQuery: What is Alex's current situation?"
+results_now = facts.at(Date.today).facts_for(alex.id)
+puts "Date: #{Date.today}"
+results_now.each_fact do |fact|
+  puts "  - #{fact[:text]}"
+end
+
+demo_section("Section 2: Query Builder with Output Formats")
+
+puts "\nAlex's 2023 state as Cypher graph:"
+cypher_2023 = facts.at("2023-10-01").facts_for(alex.id, format: :cypher)
+puts cypher_2023
+
+puts "\nAlex's 2023 state as Triples:"
+triples_2023 = facts.at("2023-10-01").facts_for(alex.id, format: :triples)
+triples_2023.each { |t| puts "  #{t.inspect}" }
+
+demo_section("Section 3: Comparing Two Points in Time")
+
+puts "\nComparing Alex's situation: 2021-06-01 vs 2024-01-01"
+diff_result = facts.diff(nil, from: "2021-06-01", to: "2024-01-01")
+
+puts "\nRemoved facts (no longer true):"
+diff_result[:removed].each do |fact|
+  puts "  - #{fact.text}"
+end
+
+puts "\nAdded facts (became true):"
+diff_result[:added].each do |fact|
+  puts "  - #{fact.text}"
+end
+
+puts "\nUnchanged facts:"
+if diff_result[:unchanged].empty?
+  puts "  (none - everything changed!)"
+else
+  diff_result[:unchanged].each do |fact|
+    puts "  - #{fact.text}"
+  end
+end
+
+demo_section("Section 4: Query Builder - Compare To")
+
+puts "\nUsing fluent API to compare dates:"
+comparison = facts.at("2020-06-01").compare_to("2023-10-01")
+
+puts "\nFrom #{comparison[:from]} to #{comparison[:to]}:"
+puts "  Added: #{comparison[:added].count} facts"
+puts "  Removed: #{comparison[:removed].count} facts"
+puts "  Unchanged: #{comparison[:unchanged].count} facts"
+
+demo_section("Section 5: Career Timeline View")
+
+checkpoints = [
+  Date.new(2020, 6, 1),
+  Date.new(2021, 6, 1),
+  Date.new(2022, 6, 1),
+  Date.new(2022, 8, 1),
+  Date.new(2023, 6, 1),
+  Date.new(2023, 10, 1),
+  Date.new(2024, 1, 1)
+]
+
+puts "\nAlex Rivera's Career Timeline:\n"
+checkpoints.each do |date|
+  snapshot = facts.at(date).facts_for(alex.id, format: :text)
+  fact_count = facts.at(date).facts_for(alex.id).fact_count
+
+  puts "#{date.strftime('%Y-%m-%d')} (#{fact_count} facts):"
+  if fact_count.zero?
+    puts "  (no facts yet)"
+  else
+    facts.at(date).facts_for(alex.id).each_fact do |fact|
+      puts "  - #{fact[:text]}"
+    end
+  end
+  puts
+end
+
+demo_section("Section 6: State For - Entity State at a Date")
+
+puts "\nSnapshot of Alex's state on 2022-08-01:"
+state = facts.at("2022-08-01").state_for(alex.id)
+puts "Facts at this moment:"
+state.each_fact do |fact|
+  puts "  - #{fact[:text]}"
+end
+
+demo_footer