fact_db 0.0.2 → 0.0.3

data/docs/architecture/index.md

@@ -48,7 +48,7 @@ graph TB
     end
 
     subgraph FactDb["FactDb Core"]
-        CS[ContentService]
+        SS[SourceService]
         ES[EntityService]
         FS[FactService]
 
@@ -70,17 +70,17 @@ graph TB
     end
 
     subgraph Storage["PostgreSQL + pgvector"]
-        Contents[(Contents)]
+        Sources[(Sources)]
         Entities[(Entities)]
         Facts[(Facts)]
     end
 
-    Email --> CS
-    Doc --> CS
-    News --> CS
-    API --> CS
+    Email --> SS
+    Doc --> SS
+    News --> SS
+    API --> SS
 
-    CS --> Contents
+    SS --> Sources
     ES --> Entities
     FS --> Facts
 
@@ -93,7 +93,7 @@ graph TB
     style Doc fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
     style News fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
     style API fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
-    style CS fill:#B45309,stroke:#92400E,color:#FFFFFF
+    style SS fill:#B45309,stroke:#92400E,color:#FFFFFF
     style ES fill:#B45309,stroke:#92400E,color:#FFFFFF
     style FS fill:#B45309,stroke:#92400E,color:#FFFFFF
     style ME fill:#047857,stroke:#065F46,color:#FFFFFF
@@ -103,7 +103,7 @@ graph TB
     style FR fill:#C2410C,stroke:#9A3412,color:#FFFFFF
     style EP fill:#7C3AED,stroke:#6D28D9,color:#FFFFFF
     style RP fill:#7C3AED,stroke:#6D28D9,color:#FFFFFF
-    style Contents fill:#B91C1C,stroke:#991B1B,color:#FFFFFF
+    style Sources fill:#B91C1C,stroke:#991B1B,color:#FFFFFF
     style Entities fill:#B91C1C,stroke:#991B1B,color:#FFFFFF
     style Facts fill:#B91C1C,stroke:#991B1B,color:#FFFFFF
 ```
@@ -112,7 +112,7 @@ graph TB
 
 ### Services
 
-- **ContentService** - Ingests and manages source content
+- **SourceService** - Ingests and manages source content
 - **EntityService** - Creates and resolves entities
 - **FactService** - Extracts, creates, and queries facts
 

data/docs/architecture/temporal-facts.md

@@ -20,7 +20,7 @@ Facts with `invalid_at: nil` are currently valid:
 ```ruby
 # Paula is currently a Principal Engineer
 {
-  fact_text: "Paula Chen is Principal Engineer",
+  text: "Paula Chen is Principal Engineer",
   valid_at: "2024-01-10",
   invalid_at: nil
 }
@@ -33,7 +33,7 @@ Facts with both dates represent historical periods:
 ```ruby
 # Paula was Senior Engineer before promotion
 {
-  fact_text: "Paula Chen is Senior Engineer",
+  text: "Paula Chen is Senior Engineer",
   valid_at: "2022-03-15",
   invalid_at: "2024-01-10"
 }
@@ -168,7 +168,7 @@ timeline = facts.timeline_for(paula.id)
 
 # Returns chronological list of facts
 timeline.each do |entry|
-  puts "#{entry.valid_at}: #{entry.fact_text}"
+  puts "#{entry.valid_at}: #{entry.text}"
   puts "  Until: #{entry.invalid_at || 'present'}"
 end
 ```
@@ -198,8 +198,8 @@ conflicts = facts.fact_service.resolver.find_conflicts(
 
 conflicts.each do |conflict|
   puts "Potential conflict:"
-  puts "  Fact 1: #{conflict[:fact1].fact_text}"
-  puts "  Fact 2: #{conflict[:fact2].fact_text}"
+  puts "  Fact 1: #{conflict[:fact1].text}"
+  puts "  Fact 2: #{conflict[:fact2].text}"
   puts "  Similarity: #{conflict[:similarity]}"
 end
 ```

data/docs/architecture/three-layer-model.md

@@ -68,7 +68,7 @@ The content layer stores raw source material that serves as evidence for facts.
 ### Example
 
 ```ruby
-content = facts.ingest(
+source = facts.ingest(
   "Paula Chen accepted the offer for Principal Engineer...",
   type: :email,
   title: "RE: Offer Letter - Paula Chen",
@@ -142,7 +142,7 @@ Facts are temporal assertions about entities, extracted from content.
 
 ```ruby
 fact = Models::Fact.new(
-  fact_text: "Paula Chen is Principal Engineer at Microsoft",
+  text: "Paula Chen is Principal Engineer at Microsoft",
   valid_at: Date.parse("2024-01-10"),
   invalid_at: nil,  # Still valid
   status: "canonical",
@@ -185,11 +185,11 @@ Facts connect to both content and entities:
 
 ```mermaid
 graph LR
-    C[Content] -->|fact_sources| F[Fact]
+    S[Source] -->|fact_sources| F[Fact]
     F -->|entity_mentions| E1[Entity 1]
     F -->|entity_mentions| E2[Entity 2]
 
-    style C fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
+    style S fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
     style F fill:#B91C1C,stroke:#991B1B,color:#FFFFFF
     style E1 fill:#047857,stroke:#065F46,color:#FFFFFF
     style E2 fill:#047857,stroke:#065F46,color:#FFFFFF
@@ -197,18 +197,18 @@ graph LR
 
 ## Layer Interactions
 
-### Content to Facts
+### Source to Facts
 
-Facts are extracted from content and maintain source links:
+Facts are extracted from sources and maintain source links:
 
 ```ruby
-# Extract facts from content
-extracted = facts.extract_facts(content.id, extractor: :llm)
+# Extract facts from source
+extracted = facts.extract_facts(source.id, extractor: :llm)
 
 # Each fact links back to source
-extracted.first.fact_sources.each do |source|
-  puts source.content.title
-  puts source.excerpt
+extracted.first.fact_sources.each do |fs|
+  puts fs.source.title
+  puts fs.excerpt
 end
 ```
 
@@ -218,7 +218,7 @@ Facts mention entities with specific roles:
 
 ```ruby
 fact.entity_mentions.each do |mention|
-  puts "#{mention.entity.canonical_name}: #{mention.mention_role}"
+  puts "#{mention.entity.name}: #{mention.mention_role}"
 end
 # Output:
 # Paula Chen: subject
@@ -231,12 +231,12 @@ end
 Query across all layers:
 
 ```ruby
-# Find all content about an entity
-contents = facts.content_service.mentioning_entity(paula.id)
+# Find all sources about an entity
+sources = facts.source_service.mentioning_entity(paula.id)
 
-# Find all entities mentioned in content
-entities = facts.entity_service.in_content(content.id)
+# Find all entities mentioned in source
+entities = facts.entity_service.in_source(source.id)
 
 # Find all facts from a specific source
-source_facts = facts.fact_service.from_content(content.id)
+source_facts = facts.fact_service.from_source(source.id)
 ```

data/docs/concepts.md

@@ -38,7 +38,7 @@ Facts are temporal assertions about entities:
 
 ```ruby
 # A fact has:
-# - fact_text: The assertion itself
+# - text: The assertion itself
 # - valid_at: When the fact became true
 # - invalid_at: When the fact stopped being true (nil if still valid)
 # - status: canonical, superseded, corroborated, synthesized
@@ -167,11 +167,11 @@ Resolution strategies (in order):
 Every fact maintains links to its source:
 
 ```ruby
-fact.fact_sources.each do |source|
-  puts "Source: #{source.content.title}"
-  puts "Type: #{source.source_type}"  # primary, supporting, contradicting
-  puts "Excerpt: #{source.excerpt}"
-  puts "Confidence: #{source.confidence}"
+fact.fact_sources.each do |fact_source|
+  puts "Source: #{fact_source.source.title}"
+  puts "Kind: #{fact_source.kind}"  # primary, supporting, corroborating
+  puts "Excerpt: #{fact_source.excerpt}"
+  puts "Confidence: #{fact_source.confidence}"
 end
 ```
 

data/docs/examples/basic-usage.md

@@ -9,9 +9,9 @@ require 'fact_db'
 
 # Configure
 FactDb.configure do |config|
-  config.database_url = ENV['DATABASE_URL']
-  config.llm_provider = :openai
-  config.llm_api_key = ENV['OPENAI_API_KEY']
+  config.database.url = ENV['DATABASE_URL']
+  config.llm.provider = :openai
+  config.llm.api_key = ENV['OPENAI_API_KEY']
 end
 
 # Create facts instance
@@ -85,7 +85,7 @@ fact1 = facts.fact_service.create(
     { entity: microsoft, role: "organization", text: "Microsoft" }
   ],
   sources: [
-    { content: email, type: "primary" }
+    { source: email, type: "primary" }
   ]
 )
 
@@ -97,7 +97,7 @@ fact2 = facts.fact_service.create(
     { entity: sarah, role: "object", text: "Sarah Johnson" }
   ],
   sources: [
-    { content: email, type: "primary" }
+    { source: email, type: "primary" }
   ]
 )
 
@@ -109,7 +109,7 @@ fact3 = facts.fact_service.create(
     { entity: platform_team, role: "organization", text: "Platform Team" }
   ],
   sources: [
-    { content: email, type: "primary" }
+    { source: email, type: "primary" }
   ]
 )
 
@@ -124,7 +124,7 @@ extracted = facts.extract_facts(email.id, extractor: :llm)
 
 puts "LLM extracted #{extracted.count} facts:"
 extracted.each do |fact|
-  puts "  - #{fact.fact_text}"
+  puts "  - #{fact.text}"
 end
 ```
 
@@ -134,13 +134,13 @@ end
 # Current facts about Paula
 puts "\nCurrent facts about Paula:"
 facts.current_facts_for(paula.id).each do |fact|
-  puts "  - #{fact.fact_text}"
+  puts "  - #{fact.text}"
 end
 
 # Facts about Microsoft
 puts "\nFacts about Microsoft:"
 facts.query_facts(entity: microsoft.id).each do |fact|
-  puts "  - #{fact.fact_text}"
+  puts "  - #{fact.text}"
 end
 ```
 
@@ -149,11 +149,11 @@ end
 ```ruby
 # Resolve a name
 resolved = facts.resolve_entity("Paula")
-puts "\n'Paula' resolves to: #{resolved&.canonical_name}"
+puts "\n'Paula' resolves to: #{resolved&.name}"
 
 # Type-constrained resolution
 person = facts.resolve_entity("Paula", type: :person)
-puts "'Paula' as person: #{person&.canonical_name}"
+puts "'Paula' as person: #{person&.name}"
 ```
 
 ## Update Facts (Supersession)
@@ -167,8 +167,8 @@ new_fact = facts.fact_service.resolver.supersede(
 )
 
 puts "\nSuperseded fact:"
-puts "  Old: #{fact1.reload.fact_text} (#{fact1.status})"
-puts "  New: #{new_fact.fact_text} (#{new_fact.status})"
+puts "  Old: #{fact1.reload.text} (#{fact1.status})"
+puts "  New: #{new_fact.text} (#{new_fact.status})"
 ```
 
 ## Timeline
@@ -178,7 +178,7 @@ puts "  New: #{new_fact.fact_text} (#{new_fact.status})"
 puts "\nPaula's timeline:"
 facts.timeline_for(paula.id).each do |fact|
   valid = fact.invalid_at ? "#{fact.valid_at} - #{fact.invalid_at}" : "#{fact.valid_at} - present"
-  puts "  #{valid}: #{fact.fact_text}"
+  puts "  #{valid}: #{fact.text}"
 end
 ```
 
@@ -188,13 +188,13 @@ end
 # What did we know before promotion?
 puts "\nFacts about Paula on March 1, 2024:"
 facts.facts_at(Date.parse("2024-03-01"), entity: paula.id).each do |fact|
-  puts "  - #{fact.fact_text}"
+  puts "  - #{fact.text}"
 end
 
 # What do we know after promotion?
 puts "\nFacts about Paula on July 1, 2024:"
 facts.facts_at(Date.parse("2024-07-01"), entity: paula.id).each do |fact|
-  puts "  - #{fact.fact_text}"
+  puts "  - #{fact.text}"
 end
 ```
 
@@ -206,13 +206,13 @@ require 'fact_db'
 
 # Setup
 FactDb.configure do |config|
-  config.database_url = ENV['DATABASE_URL'] || 'postgresql://localhost/fact_db'
+  config.database.url = ENV['DATABASE_URL'] || 'postgresql://localhost/fact_db'
 end
 
 facts = FactDb.new
 
 # Ingest
-content = facts.ingest("Paula joined Microsoft on Jan 10, 2024", type: :note)
+source = facts.ingest("Paula joined Microsoft on Jan 10, 2024", type: :note)
 
 # Create entities
 paula = facts.entity_service.create("Paula", type: :person)
@@ -226,10 +226,10 @@ fact = facts.fact_service.create(
     { entity: paula, role: "subject", text: "Paula" },
     { entity: microsoft, role: "organization", text: "Microsoft" }
   ],
-  sources: [{ content: content, type: "primary" }]
+  sources: [{ source: source, type: "primary" }]
 )
 
 # Query
 puts "Current facts about Paula:"
-facts.current_facts_for(paula.id).each { |f| puts "  - #{f.fact_text}" }
+facts.current_facts_for(paula.id).each { |f| puts "  - #{f.text}" }
 ```

data/docs/examples/hr-onboarding.md

@@ -12,9 +12,9 @@ An HR system that tracks employee facts over time, maintaining a complete audit
 require 'fact_db'
 
 FactDb.configure do |config|
-  config.database_url = ENV['DATABASE_URL']
-  config.llm_provider = :openai
-  config.llm_api_key = ENV['OPENAI_API_KEY']
+  config.database.url = ENV['DATABASE_URL']
+  config.llm.provider = :openai
+  config.llm.api_key = ENV['OPENAI_API_KEY']
 end
 
 facts = FactDb.new
@@ -96,14 +96,14 @@ facts.fact_service.create(
     { entity: paula, role: "subject", text: "Paula Chen" },
     { entity: acme, role: "organization", text: "Acme Corporation" }
   ],
-  sources: [{ content: offer_letter, type: "primary" }]
+  sources: [{ source: offer_letter, type: "primary" }]
 )
 
 facts.fact_service.create(
   "Paula Chen's title is Software Engineer",
   valid_at: Date.parse("2022-03-01"),
   mentions: [{ entity: paula, role: "subject", text: "Paula Chen" }],
-  sources: [{ content: offer_letter, type: "primary" }]
+  sources: [{ source: offer_letter, type: "primary" }]
 )
 
 facts.fact_service.create(
@@ -113,7 +113,7 @@ facts.fact_service.create(
     { entity: paula, role: "subject", text: "Paula Chen" },
     { entity: john, role: "object", text: "John Smith" }
   ],
-  sources: [{ content: offer_letter, type: "primary" }]
+  sources: [{ source: offer_letter, type: "primary" }]
 )
 
 facts.fact_service.create(
@@ -123,7 +123,7 @@ facts.fact_service.create(
     { entity: paula, role: "subject", text: "Paula Chen" },
     { entity: engineering, role: "organization", text: "Engineering" }
   ],
-  sources: [{ content: offer_letter, type: "primary" }]
+  sources: [{ source: offer_letter, type: "primary" }]
 )
 ```
 
@@ -233,7 +233,7 @@ facts.timeline_for(paula.id).each do |fact|
     "#{fact.valid_at.to_date} - present"
 
   status = fact.superseded? ? " [superseded]" : ""
-  puts "#{valid}: #{fact.fact_text}#{status}"
+  puts "#{valid}: #{fact.text}#{status}"
 end
 ```
 
@@ -265,7 +265,7 @@ dates = [
 dates.each do |date|
   puts "\nPaula's status on #{date}:"
   facts.facts_at(date, entity: paula.id).each do |fact|
-    puts "  - #{fact.fact_text}"
+    puts "  - #{fact.text}"
   end
 end
 ```
@@ -278,26 +278,26 @@ def employment_report(facts, employee_id)
   current = facts.current_facts_for(employee_id)
 
   report = {
-    name: employee.canonical_name,
+    name: employee.name,
     current_status: {},
     history: []
   }
 
   # Current status
   current.each do |fact|
-    if fact.fact_text.include?("title is")
-      report[:current_status][:title] = fact.fact_text.split("title is ").last
-    elsif fact.fact_text.include?("works in")
-      report[:current_status][:department] = fact.fact_text.split("works in ").last
-    elsif fact.fact_text.include?("reports to")
-      report[:current_status][:manager] = fact.fact_text.split("reports to ").last
+    if fact.text.include?("title is")
+      report[:current_status][:title] = fact.text.split("title is ").last
+    elsif fact.text.include?("works in")
+      report[:current_status][:department] = fact.text.split("works in ").last
+    elsif fact.text.include?("reports to")
+      report[:current_status][:manager] = fact.text.split("reports to ").last
     end
   end
 
   # Employment history
   report[:history] = facts.timeline_for(employee_id).map do |fact|
     {
-      fact: fact.fact_text,
+      fact: fact.text,
       from: fact.valid_at,
       to: fact.invalid_at,
       status: fact.status

data/docs/examples/index.md

@@ -19,10 +19,10 @@ Practical examples demonstrating FactDb usage patterns.
 facts = FactDb.new
 
 # Ingest content
-content = facts.ingest(document_text, type: :document)
+source = facts.ingest(document_text, type: :document)
 
 # Extract facts
-extracted = facts.extract_facts(content.id, extractor: :llm)
+extracted = facts.extract_facts(source.id, extractor: :llm)
 ```
 
 ### Query Current State
@@ -45,7 +45,7 @@ historical = facts.facts_at(Date.parse("2023-06-15"), entity: paula.id)
 # Build complete timeline
 timeline = facts.timeline_for(paula.id)
 timeline.each do |fact|
-  puts "#{fact.valid_at}: #{fact.fact_text}"
+  puts "#{fact.valid_at}: #{fact.text}"
 end
 ```
 
@@ -60,5 +60,5 @@ entity = facts.resolve_entity("Paula Chen", type: :person)
 
 ```ruby
 # Process multiple documents
-results = facts.batch_extract(content_ids, parallel: true)
+results = facts.batch_extract(source_ids, parallel: true)
 ```

data/docs/examples/news-analysis.md

@@ -12,9 +12,9 @@ A news monitoring system that extracts facts from articles and tracks how inform
 require 'fact_db'
 
 FactDb.configure do |config|
-  config.database_url = ENV['DATABASE_URL']
-  config.llm_provider = :openai
-  config.llm_api_key = ENV['OPENAI_API_KEY']
+  config.database.url = ENV['DATABASE_URL']
+  config.llm.provider = :openai
+  config.llm.api_key = ENV['OPENAI_API_KEY']
 end
 
 facts = FactDb.new
@@ -109,7 +109,7 @@ end
 # List all extracted entities
 puts "\nExtracted Entities:"
 FactDb::Models::Entity.all.each do |entity|
-  puts "  #{entity.canonical_name} (#{entity.entity_type})"
+  puts "  #{entity.name} (#{entity.type})"
 end
 ```
 
@@ -119,13 +119,13 @@ end
 # CEO-related facts
 puts "\nCEO Facts:"
 facts.query_facts(topic: "CEO").each do |fact|
-  puts "  #{fact.valid_at.to_date}: #{fact.fact_text}"
+  puts "  #{fact.valid_at.to_date}: #{fact.text}"
 end
 
 # Acquisition facts
 puts "\nAcquisition Facts:"
 facts.query_facts(topic: "acquisition").each do |fact|
-  puts "  #{fact.valid_at.to_date}: #{fact.fact_text}"
+  puts "  #{fact.valid_at.to_date}: #{fact.text}"
 end
 ```
 
@@ -138,8 +138,8 @@ techcorp = facts.resolve_entity("TechCorp", type: :organization)
 # Timeline of TechCorp facts
 puts "\nTechCorp Timeline:"
 facts.timeline_for(techcorp.id).each do |fact|
-  source = fact.fact_sources.first&.content&.title || "Unknown"
-  puts "  #{fact.valid_at.to_date}: #{fact.fact_text}"
+  source = fact.fact_sources.first&.source&.title || "Unknown"
+  puts "  #{fact.valid_at.to_date}: #{fact.text}"
   puts "    Source: #{source}"
 end
 ```
@@ -164,8 +164,8 @@ if acquisition_fact
   )
 
   puts "\nAcquisition status updated:"
-  puts "  Original: #{acquisition_fact.reload.fact_text} (#{acquisition_fact.status})"
-  puts "  Updated: #{acquisition_fact.superseded_by.fact_text}"
+  puts "  Original: #{acquisition_fact.reload.text} (#{acquisition_fact.status})"
+  puts "  Updated: #{acquisition_fact.superseded_by.text}"
 end
 ```
 
@@ -197,14 +197,14 @@ def company_report(facts, company_name)
   current_facts = facts.current_facts_for(company.id)
 
   {
-    company: company.canonical_name,
-    current_facts: current_facts.map(&:fact_text),
+    company: company.name,
+    current_facts: current_facts.map(&:text),
     leadership: extract_leadership(current_facts),
     timeline: facts.timeline_for(company.id).map { |f|
       {
         date: f.valid_at,
-        fact: f.fact_text,
-        source: f.fact_sources.first&.content&.title
+        fact: f.text,
+        source: f.fact_sources.first&.source&.title
       }
     }
   }
@@ -213,8 +213,8 @@ end
 def extract_leadership(facts)
   leadership = {}
   facts.each do |fact|
-    if fact.fact_text =~ /CEO/
-      leadership[:ceo] = fact.entity_mentions.find { |m| m.mention_role == "subject" }&.entity&.canonical_name
+    if fact.text =~ /CEO/
+      leadership[:ceo] = fact.entity_mentions.find { |m| m.mention_role == "subject" }&.entity&.name
     end
   end
   leadership
@@ -228,19 +228,19 @@ puts JSON.pretty_generate(report)
 
 ```ruby
 def process_news_feed(facts, articles)
-  content_ids = articles.map do |article|
-    content = facts.ingest(
+  source_ids = articles.map do |article|
+    source = facts.ingest(
       article[:text],
       type: :article,
       title: article[:title],
       source_uri: article[:url],
       captured_at: article[:published_at]
     )
-    content.id
+    source.id
   end
 
   # Parallel extraction
-  results = facts.batch_extract(content_ids, extractor: :llm)
+  results = facts.batch_extract(source_ids, extractor: :llm)
 
   {
     processed: results.count,
@@ -273,10 +273,10 @@ def monitor_topic(facts, topic, since: 1.week.ago)
     new_facts: matching.count,
     facts: matching.map { |f|
       {
-        text: f.fact_text,
+        text: f.text,
         date: f.valid_at,
-        source: f.fact_sources.first&.content&.title,
-        entities: f.entity_mentions.map { |m| m.entity.canonical_name }
+        source: f.fact_sources.first&.source&.title,
+        entities: f.entity_mentions.map { |m| m.entity.name }
       }
     }
   }