fact_db 0.0.2 → 0.0.3

data/docs/getting-started/database-setup.md

@@ -24,7 +24,7 @@ FactDb provides migrations that create all necessary tables:
 require 'fact_db'
 
 FactDb.configure do |config|
-  config.database_url = "postgresql://localhost/fact_db"
+  config.database.url = "postgresql://localhost/fact_db"
 end
 
 FactDb::Database.migrate!
@@ -34,19 +34,19 @@ FactDb::Database.migrate!
 
 The migrations create six tables:
 
-### contents
+### sources
 
-Stores immutable source documents.
+Stores immutable source content.
 
 | Column | Type | Description |
 |--------|------|-------------|
 | id | bigint | Primary key |
 | content_hash | string | SHA256 hash for deduplication |
-| content_type | string | Type (email, document, article) |
-| raw_text | text | Original content |
+| type | string | Type (email, document, article) |
+| content | text | Original source content |
 | title | string | Optional title |
 | source_uri | string | Original location |
-| source_metadata | jsonb | Additional metadata |
+| metadata | jsonb | Additional metadata |
 | embedding | vector(1536) | Semantic search vector |
 | captured_at | timestamptz | When content was captured |
 
@@ -57,10 +57,10 @@ Stores resolved identities.
 | Column | Type | Description |
 |--------|------|-------------|
 | id | bigint | Primary key |
-| canonical_name | string | Authoritative name |
-| entity_type | string | person, organization, place, etc. |
+| name | string | Authoritative name |
+| type | string | person, organization, place, etc. |
 | resolution_status | string | unresolved, resolved, merged |
-| merged_into_id | bigint | Points to canonical entity if merged |
+| canonical_id | bigint | Points to canonical entity if merged |
 | metadata | jsonb | Additional attributes |
 | embedding | vector(1536) | Semantic search vector |
 
@@ -72,8 +72,8 @@ Stores alternative names for entities.
 |--------|------|-------------|
 | id | bigint | Primary key |
 | entity_id | bigint | Foreign key to entities |
-| alias_text | string | Alternative name |
-| alias_type | string | nickname, abbreviation, etc. |
+| name | string | Alternative name |
+| type | string | nickname, abbreviation, etc. |
 | confidence | float | Match confidence (0-1) |
 
 ### facts
@@ -83,8 +83,8 @@ Stores temporal assertions.
 | Column | Type | Description |
 |--------|------|-------------|
 | id | bigint | Primary key |
-| fact_text | text | The assertion |
-| fact_hash | string | For deduplication |
+| text | text | The assertion |
+| digest | string | SHA256 digest for deduplication |
 | valid_at | timestamptz | When fact became true |
 | invalid_at | timestamptz | When fact stopped being true |
 | status | string | canonical, superseded, corroborated, synthesized |
@@ -117,8 +117,8 @@ Links facts to source content.
 |--------|------|-------------|
 | id | bigint | Primary key |
 | fact_id | bigint | Foreign key to facts |
-| content_id | bigint | Foreign key to contents |
-| source_type | string | primary, supporting, contradicting |
+| source_id | bigint | Foreign key to sources |
+| kind | string | primary, supporting, corroborating |
 | excerpt | text | Relevant text excerpt |
 | confidence | float | Source confidence |
 
@@ -128,8 +128,8 @@ The migrations create indexes for:
 
 - Content hash (unique)
 - Content type
-- Full-text search on raw_text
-- Entity canonical name
+- Full-text search on content
+- Entity name
 - Entity type
 - Fact status
 - Temporal range queries (valid_at, invalid_at)
@@ -158,12 +158,20 @@ Configure the connection pool for your workload:
 
 ```ruby
 FactDb.configure do |config|
-  config.database_url = ENV['DATABASE_URL']
-  config.database_pool_size = 10  # Default: 5
-  config.database_timeout = 60_000  # Default: 30000ms
+  config.database.url = ENV['DATABASE_URL']
+  config.database.pool_size = 10  # Default: 5
+  config.database.timeout = 60_000  # Default: 30000ms
 end
 ```
 
+Or via environment variables:
+
+```bash
+export FDB_DATABASE__URL="postgresql://localhost/fact_db"
+export FDB_DATABASE__POOL_SIZE=10
+export FDB_DATABASE__TIMEOUT=60000
+```
+
 ## Next Steps
 
 - [Quick Start](quick-start.md) - Start using FactDb

data/docs/getting-started/index.md

@@ -55,17 +55,17 @@ require 'fact_db'
 
 # Configure
 FactDb.configure do |config|
-  config.database_url = ENV['DATABASE_URL']
+  config.database.url = ENV['DATABASE_URL']
 end
 
 # Create a facts instance
 facts = FactDb.new
 
 # Ingest content
-content = facts.ingest("Important information...", type: :document)
+source = facts.ingest("Important information...", type: :document)
 
 # Extract and query facts
-extracted = facts.extract_facts(content.id)
+extracted = facts.extract_facts(source.id)
 ```
 
 Continue to the [Installation Guide](installation.md) to begin.

data/docs/getting-started/quick-start.md

@@ -9,27 +9,30 @@ Create a configuration file or use environment variables:
 === "Environment Variables"
 
     ```bash
-    export EVENT_CLOCK_DATABASE_URL="postgresql://localhost/fact_db"
-    export EVENT_CLOCK_LLM_PROVIDER="openai"
-    export EVENT_CLOCK_LLM_API_KEY="sk-..."
+    export FDB_DATABASE__URL="postgresql://localhost/fact_db"
+    export FDB_LLM__PROVIDER="openai"
+    export FDB_LLM__API_KEY="sk-..."
     ```
 
 === "YAML Config"
 
     ```yaml
     # config/fact_db.yml
-    database_url: postgresql://localhost/fact_db
-    llm_provider: openai
-    llm_api_key: <%= ENV['OPENAI_API_KEY'] %>
+    database:
+      url: postgresql://localhost/fact_db
+
+    llm:
+      provider: openai
+      api_key: <%= ENV['OPENAI_API_KEY'] %>
     ```
 
 === "Ruby Block"
 
     ```ruby
     FactDb.configure do |config|
-      config.database_url = "postgresql://localhost/fact_db"
-      config.llm_provider = :openai
-      config.llm_api_key = ENV['OPENAI_API_KEY']
+      config.database.url = "postgresql://localhost/fact_db"
+      config.llm.provider = :openai
+      config.llm.api_key = ENV['OPENAI_API_KEY']
     end
     ```
 
@@ -41,7 +44,7 @@ Run the migrations:
 require 'fact_db'
 
 FactDb.configure do |config|
-  config.database_url = ENV['DATABASE_URL']
+  config.database.url = ENV['DATABASE_URL']
 end
 
 # Run migrations
@@ -60,14 +63,14 @@ facts = FactDb.new
 
 ```ruby
 # Ingest an email
-content = facts.ingest(
+source = facts.ingest(
   "Hi team, Paula Chen has accepted our offer and will join as Principal Engineer starting January 10, 2024. She'll be reporting to Sarah in the Platform team.",
-  type: :email,
+  kind: :email,
   title: "New Hire Announcement",
   captured_at: Time.current
 )
 
-puts "Ingested content: #{content.id}"
+puts "Ingested source: #{source.id}"
 ```
 
 ## 5. Create Entities
@@ -76,19 +79,19 @@ puts "Ingested content: #{content.id}"
 # Create entities for people and organizations
 paula = facts.entity_service.create(
   "Paula Chen",
-  type: :person,
+  kind: :person,
   aliases: ["Paula", "P. Chen"]
 )
 
 sarah = facts.entity_service.create(
   "Sarah Johnson",
-  type: :person,
+  kind: :person,
   aliases: ["Sarah"]
 )
 
 platform_team = facts.entity_service.create(
   "Platform Team",
-  type: :organization
+  kind: :organization
 )
 ```
 
@@ -104,7 +107,7 @@ fact = facts.fact_service.create(
     { entity: paula, role: "subject", text: "Paula Chen" }
   ],
   sources: [
-    { content: content, type: "primary" }
+    { source: source, type: "primary" }
   ]
 )
 ```
@@ -113,10 +116,10 @@ fact = facts.fact_service.create(
 
 ```ruby
 # Extract facts automatically using LLM
-extracted = facts.extract_facts(content.id, extractor: :llm)
+extracted = facts.extract_facts(source.id, extractor: :llm)
 
 extracted.each do |fact|
-  puts "Extracted: #{fact.fact_text}"
+  puts "Extracted: #{fact.text}"
   puts "  Valid from: #{fact.valid_at}"
 end
 ```
@@ -126,7 +129,7 @@ end
 ```ruby
 # Get current facts about Paula
 current = facts.current_facts_for(paula.id)
-current.each { |f| puts f.fact_text }
+current.each { |f| puts f.text }
 
 # Get facts valid at a specific date
 historical = facts.facts_at(
@@ -144,7 +147,7 @@ team_facts = facts.query_facts(topic: "Platform Team")
 timeline = facts.timeline_for(paula.id)
 
 timeline.each do |entry|
-  puts "#{entry[:date]}: #{entry[:fact].fact_text}"
+  puts "#{entry[:date]}: #{entry[:fact].text}"
 end
 ```
 
@@ -155,32 +158,32 @@ 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
 facts = FactDb.new
 
 # Ingest content
-content = facts.ingest(
+source = facts.ingest(
   "Paula Chen joined Microsoft as Principal Engineer on January 10, 2024.",
-  type: :announcement,
+  kind: :announcement,
   captured_at: Time.current
 )
 
 # Create entities
-paula = facts.entity_service.create("Paula Chen", type: :person)
-microsoft = facts.entity_service.create("Microsoft", type: :organization)
+paula = facts.entity_service.create("Paula Chen", kind: :person)
+microsoft = facts.entity_service.create("Microsoft", kind: :organization)
 
 # Extract facts via LLM
-extracted = facts.extract_facts(content.id, extractor: :llm)
+extracted = facts.extract_facts(source.id, extractor: :llm)
 
 # Query
 puts "Current facts about Paula:"
 facts.current_facts_for(paula.id).each do |fact|
-  puts "  - #{fact.fact_text}"
+  puts "  - #{fact.text}"
 end
 ```
 

data/docs/guides/batch-processing.md

@@ -20,10 +20,10 @@ Process content one at a time:
 ```ruby
 facts = FactDb.new
 
-content_ids = [content1.id, content2.id, content3.id]
+source_ids = [content1.id, content2.id, content3.id]
 
 results = facts.batch_extract(
-  content_ids,
+  source_ids,
   extractor: :llm,
   parallel: false
 )
@@ -35,13 +35,13 @@ Process content concurrently (default):
 
 ```ruby
 results = facts.batch_extract(
-  content_ids,
+  source_ids,
   extractor: :llm,
   parallel: true  # default
 )
 
 results.each do |result|
-  puts "Content #{result[:content_id]}:"
+  puts "Content #{result[:source_id]}:"
   puts "  Facts extracted: #{result[:facts].count}"
   puts "  Error: #{result[:error]}" if result[:error]
 end
@@ -51,7 +51,7 @@ end
 
 ```ruby
 result = {
-  content_id: 123,
+  source_id: 123,
   facts: [<Fact>, <Fact>, ...],  # Extracted facts
   error: nil                      # Error message if failed
 }
@@ -75,7 +75,7 @@ results = facts.batch_resolve_entities(names, type: nil)
 results.each do |result|
   case result[:status]
   when :resolved
-    puts "#{result[:name]} -> #{result[:entity].canonical_name}"
+    puts "#{result[:name]} -> #{result[:entity].name}"
   when :not_found
     puts "#{result[:name]} -> Not found"
   when :error
@@ -104,9 +104,9 @@ results.each do |result|
   if result[:conflict_count] > 0
     puts "Entity #{result[:entity_id]} has #{result[:conflict_count]} conflicts:"
     result[:conflicts].each do |conflict|
-      puts "  #{conflict[:fact1].fact_text}"
+      puts "  #{conflict[:fact1].text}"
       puts "  vs"
-      puts "  #{conflict[:fact2].fact_text}"
+      puts "  #{conflict[:fact2].text}"
       puts "  Similarity: #{conflict[:similarity]}"
     end
   end
@@ -153,7 +153,7 @@ pipeline = SimpleFlow::Pipeline.new do
   # Step 1: Validate
   step ->(result) {
     content = result.value
-    if content.raw_text.blank?
+    if source.content.blank?
       result.halt("Empty content")
     else
       result.continue(content)
@@ -182,7 +182,7 @@ result = pipeline.call(SimpleFlow::Result.new(content))
 ### Graceful Degradation
 
 ```ruby
-results = facts.batch_extract(content_ids, extractor: :llm)
+results = facts.batch_extract(source_ids, extractor: :llm)
 
 successful = results.select { |r| r[:error].nil? }
 failed = results.reject { |r| r[:error].nil? }
@@ -192,7 +192,7 @@ puts "Failed: #{failed.count}"
 
 # Retry failed items with different extractor
 if failed.any?
-  retry_ids = failed.map { |r| r[:content_id] }
+  retry_ids = failed.map { |r| r[:source_id] }
   retry_results = facts.batch_extract(retry_ids, extractor: :rule_based)
 end
 ```
@@ -204,7 +204,7 @@ results.each do |result|
   if result[:error]
     logger.error(
       "Extraction failed",
-      content_id: result[:content_id],
+      source_id: result[:source_id],
       error: result[:error]
     )
   end
@@ -217,7 +217,7 @@ end
 
 ```ruby
 # Process in batches of 10-50 for optimal performance
-content_ids.each_slice(25) do |batch|
+source_ids.each_slice(25) do |batch|
   results = facts.batch_extract(batch, parallel: true)
   process_results(results)
 end
@@ -228,7 +228,7 @@ end
 For LLM extraction, add delays between batches:
 
 ```ruby
-content_ids.each_slice(10) do |batch|
+source_ids.each_slice(10) do |batch|
   results = facts.batch_extract(batch, extractor: :llm)
   process_results(results)
   sleep(2)  # Rate limit
@@ -239,7 +239,7 @@ end
 
 ```ruby
 # Process results immediately to avoid memory buildup
-content_ids.each_slice(50) do |batch|
+source_ids.each_slice(50) do |batch|
   results = facts.batch_extract(batch)
 
   results.each do |result|
@@ -259,7 +259,7 @@ Track batch processing metrics:
 ```ruby
 start_time = Time.now
 
-results = facts.batch_extract(content_ids, parallel: true)
+results = facts.batch_extract(source_ids, parallel: true)
 
 duration = Time.now - start_time
 success_rate = results.count { |r| r[:error].nil? }.to_f / results.count
@@ -275,18 +275,18 @@ puts "Items/second: #{(results.count / duration).round(2)}"
 
 ```ruby
 # Sequential for small batches (< 5 items)
-if content_ids.count < 5
-  results = facts.batch_extract(content_ids, parallel: false)
+if source_ids.count < 5
+  results = facts.batch_extract(source_ids, parallel: false)
 else
-  results = facts.batch_extract(content_ids, parallel: true)
+  results = facts.batch_extract(source_ids, parallel: true)
 end
 ```
 
 ### 2. Handle Partial Failures
 
 ```ruby
-def process_batch(content_ids)
-  results = facts.batch_extract(content_ids)
+def process_batch(source_ids)
+  results = facts.batch_extract(source_ids)
 
   {
     successful: results.select { |r| r[:error].nil? },
@@ -294,17 +294,17 @@ def process_batch(content_ids)
   }
 end
 
-batch_result = process_batch(content_ids)
+batch_result = process_batch(source_ids)
 retry_failed(batch_result[:failed]) if batch_result[:failed].any?
 ```
 
 ### 3. Log Progress
 
 ```ruby
-total = content_ids.count
+total = source_ids.count
 processed = 0
 
-content_ids.each_slice(25) do |batch|
+source_ids.each_slice(25) do |batch|
   results = facts.batch_extract(batch)
   processed += batch.count
 
@@ -316,10 +316,10 @@ end
 
 ```ruby
 # LLM for complex documents
-complex_docs = contents.select { |c| c.raw_text.length > 1000 }
+complex_docs = sources.select { |s| s.content.length > 1000 }
 facts.batch_extract(complex_docs.map(&:id), extractor: :llm)
 
 # Rule-based for simple, structured content
-simple_docs = contents.select { |c| c.raw_text.length <= 1000 }
+simple_docs = sources.select { |s| s.content.length <= 1000 }
 facts.batch_extract(simple_docs.map(&:id), extractor: :rule_based)
 ```