fact_db 0.0.2 → 0.0.3

data/docs/api/models/entity.md

@@ -6,8 +6,8 @@ Stores resolved identities (people, organizations, places, etc.).
 
 ```ruby
 entity = FactDb::Models::Entity.new(
-  canonical_name: "Paula Chen",
-  entity_type: "person"
+  name: "Paula Chen",
+  kind: "person"
 )
 ```
 
@@ -16,15 +16,15 @@ entity = FactDb::Models::Entity.new(
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `id` | Integer | Primary key |
-| `canonical_name` | String | Authoritative name |
-| `entity_type` | String | Type (person, organization, place, etc.) |
+| `name` | String | Authoritative name |
+| `kind` | String | Kind (person, organization, place, etc.) |
 | `resolution_status` | String | Status (unresolved, resolved, merged) |
-| `merged_into_id` | Integer | Points to canonical entity if merged |
+| `canonical_id` | Integer | Points to canonical entity if merged |
 | `metadata` | Hash | Additional attributes (JSONB) |
 | `embedding` | Vector | Semantic search vector |
 | `created_at` | DateTime | Record creation time |
 
-## Entity Types
+## Entity Kinds
 
 - `person` - Individual people
 - `organization` - Companies, teams, groups
@@ -52,7 +52,7 @@ belongs_to :merged_into, class_name: 'Entity', optional: true
 ### add_alias
 
 ```ruby
-def add_alias(text, type: nil, confidence: 1.0)
+def add_alias(text, kind: nil, confidence: 1.0)
 ```
 
 Add an alias to the entity.
@@ -60,7 +60,7 @@ Add an alias to the entity.
 **Example:**
 
 ```ruby
-entity.add_alias("Paula", type: "nickname", confidence: 0.95)
+entity.add_alias("Paula", kind: "nickname", confidence: 0.95)
 ```
 
 ### merged?
@@ -88,16 +88,16 @@ canonical = entity.canonical  # Returns the canonical entity
 
 ## Scopes
 
-### by_type
+### by_kind
 
 ```ruby
-scope :by_type, ->(type) { where(entity_type: type) }
+scope :by_kind, ->(k) { where(kind: k) }
 ```
 
-Filter by entity type.
+Filter by entity kind.
 
 ```ruby
-Entity.by_type('person')
+Entity.by_kind('person')
 ```
 
 ### active
@@ -124,7 +124,7 @@ Only resolved entities.
 
 ```ruby
 scope :search_name, ->(query) {
-  where("canonical_name ILIKE ?", "%#{query}%")
+  where("name ILIKE ?", "%#{query}%")
 }
 ```
 
@@ -140,8 +140,8 @@ Entity.search_name("paula")
 
 ```ruby
 entity = Entity.create!(
-  canonical_name: "Paula Chen",
-  entity_type: "person",
+  name: "Paula Chen",
+  kind: "person",
   metadata: {
     department: "Engineering",
     employee_id: "E12345"
@@ -153,15 +153,15 @@ entity = Entity.create!(
 
 ```ruby
 entity.add_alias("Paula")
-entity.add_alias("P. Chen", type: "abbreviation")
-entity.add_alias("Chen, Paula", type: "formal")
+entity.add_alias("P. Chen", kind: "abbreviation")
+entity.add_alias("Chen, Paula", kind: "formal")
 ```
 
 ### Check Aliases
 
 ```ruby
 entity.entity_aliases.each do |a|
-  puts "#{a.alias_text} (#{a.alias_type})"
+  puts "#{a.name} (#{a.kind})"
 end
 ```
 
@@ -169,7 +169,7 @@ end
 
 ```ruby
 entity.facts.each do |fact|
-  puts "#{fact.valid_at}: #{fact.fact_text}"
+  puts "#{fact.valid_at}: #{fact.text}"
 end
 ```
 
@@ -192,11 +192,11 @@ similar = Entity
 # entity2 will be merged into entity1
 entity2.update!(
   resolution_status: 'merged',
-  merged_into_id: entity1.id
+  canonical_id: entity1.id
 )
 
 # Copy aliases
 entity2.entity_aliases.each do |a|
-  entity1.add_alias(a.alias_text, type: a.alias_type)
+  entity1.add_alias(a.name, kind: a.kind)
 end
 ```

data/docs/api/models/fact.md

@@ -6,7 +6,7 @@ Stores temporal assertions about entities.
 
 ```ruby
 fact = FactDb::Models::Fact.new(
-  fact_text: "Paula Chen is Principal Engineer",
+  text: "Paula Chen is Principal Engineer",
   valid_at: Date.parse("2024-01-10"),
   status: "canonical"
 )
@@ -17,8 +17,8 @@ fact = FactDb::Models::Fact.new(
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `id` | Integer | Primary key |
-| `fact_text` | Text | The assertion |
-| `fact_hash` | String | Hash for deduplication |
+| `text` | Text | The assertion |
+| `digest` | String | SHA256 digest for deduplication |
 | `valid_at` | DateTime | When fact became true |
 | `invalid_at` | DateTime | When fact stopped being true (nil if current) |
 | `status` | String | Status (canonical, superseded, corroborated, synthesized) |
@@ -72,7 +72,7 @@ fact.add_mention(
 ### add_source
 
 ```ruby
-def add_source(content:, type: "primary", excerpt: nil, confidence: 1.0)
+def add_source(source:, kind: "primary", excerpt: nil, confidence: 1.0)
 ```
 
 Add a source content link.
@@ -81,8 +81,8 @@ Add a source content link.
 
 ```ruby
 fact.add_source(
-  content: email,
-  type: "primary",
+  source: email,
+  kind: "primary",
   excerpt: "...accepted the offer..."
 )
 ```
@@ -169,7 +169,7 @@ Fact.mentioning_entity(paula.id)
 
 ```ruby
 scope :search_text, ->(query) {
-  where("fact_text @@ plainto_tsquery(?)", query)
+  where("text @@ plainto_tsquery(?)", query)
 }
 ```
 
@@ -207,7 +207,7 @@ High confidence facts only.
 
 ```ruby
 fact = Fact.create!(
-  fact_text: "Paula Chen joined Microsoft as Principal Engineer",
+  text: "Paula Chen joined Microsoft as Principal Engineer",
   valid_at: Date.parse("2024-01-10"),
   status: "canonical",
   extraction_method: "manual",
@@ -219,7 +219,7 @@ fact.add_mention(entity: paula, text: "Paula Chen", role: "subject")
 fact.add_mention(entity: microsoft, text: "Microsoft", role: "organization")
 
 # Add source
-fact.add_source(content: announcement, type: "primary")
+fact.add_source(source: announcement, kind: "primary")
 ```
 
 ### Query Facts
@@ -239,7 +239,7 @@ Fact.search_text("promoted")
 
 ```ruby
 new_fact = Fact.create!(
-  fact_text: "Paula Chen is Senior Principal Engineer",
+  text: "Paula Chen is Senior Principal Engineer",
   valid_at: Date.parse("2024-06-01"),
   status: "canonical"
 )
@@ -254,10 +254,10 @@ old_fact.update!(
 ### Get Sources
 
 ```ruby
-fact.fact_sources.each do |source|
-  puts "Source: #{source.content.title}"
-  puts "Type: #{source.source_type}"
-  puts "Excerpt: #{source.excerpt}"
+fact.fact_sources.each do |fact_source|
+  puts "Source: #{fact_source.source.title}"
+  puts "Kind: #{fact_source.kind}"
+  puts "Excerpt: #{fact_source.excerpt}"
 end
 ```
 
@@ -265,6 +265,6 @@ end
 
 ```ruby
 fact.entity_mentions.each do |mention|
-  puts "#{mention.entity.canonical_name} (#{mention.mention_role})"
+  puts "#{mention.entity.name} (#{mention.mention_role})"
 end
 ```

data/docs/api/models/index.md

@@ -4,7 +4,7 @@ FactDb uses ActiveRecord models for data persistence.
 
 ## Core Models
 
-- [Content](content.md) - Immutable source documents
+- [Source](source.md) - Immutable source content
 - [Entity](entity.md) - Resolved identities with aliases
 - [Fact](fact.md) - Temporal assertions
 
@@ -23,8 +23,8 @@ end
 | Column | Type | Description |
 |--------|------|-------------|
 | entity_id | bigint | Parent entity |
-| alias_text | string | Alternative name |
-| alias_type | string | Type (nickname, abbreviation, etc.) |
+| name | string | Alternative name |
+| type | string | Type (nickname, abbreviation, etc.) |
 | confidence | float | Match confidence |
 
 ### EntityMention
@@ -53,15 +53,15 @@ Links facts to source content.
 ```ruby
 class FactSource < ActiveRecord::Base
   belongs_to :fact
-  belongs_to :content
+  belongs_to :source
 end
 ```
 
 | Column | Type | Description |
 |--------|------|-------------|
 | fact_id | bigint | Parent fact |
-| content_id | bigint | Source content |
-| source_type | string | Type (primary, supporting, contradicting) |
+| source_id | bigint | Source content |
+| kind | string | Kind (primary, supporting, corroborating) |
 | excerpt | text | Relevant text excerpt |
 | confidence | float | Source confidence |
 
@@ -69,7 +69,7 @@ end
 
 ```mermaid
 erDiagram
-    Content ||--o{ FactSource : "sourced by"
+    Source ||--o{ FactSource : "sourced by"
     Entity ||--o{ EntityAlias : "has"
     Entity ||--o{ EntityMention : "mentioned in"
     Fact ||--o{ EntityMention : "mentions"

data/docs/api/models/{content.md → source.md}

@@ -1,13 +1,13 @@
-# Content Model
+# Source Model
 
-Stores immutable source documents.
+Stores immutable source content from which facts are extracted.
 
-## Class: `FactDb::Models::Content`
+## Class: `FactDb::Models::Source`
 
 ```ruby
-content = FactDb::Models::Content.new(
-  raw_text: "Document content...",
-  content_type: "email",
+source = FactDb::Models::Source.new(
+  content: "Document content...",
+  kind: "email",
   captured_at: Time.current
 )
 ```
@@ -18,11 +18,11 @@ content = FactDb::Models::Content.new(
 |-----------|------|-------------|
 | `id` | Integer | Primary key |
 | `content_hash` | String | SHA256 hash for deduplication |
-| `content_type` | String | Type (email, document, etc.) |
-| `raw_text` | Text | Original content |
+| `kind` | String | Kind (email, document, etc.) |
+| `content` | Text | Original unmodified text content |
 | `title` | String | Optional title |
 | `source_uri` | String | Original location |
-| `source_metadata` | Hash | Additional metadata (JSONB) |
+| `metadata` | Hash | Additional metadata (JSONB) |
 | `embedding` | Vector | Semantic search vector |
 | `captured_at` | DateTime | When content was captured |
 | `created_at` | DateTime | Record creation time |
@@ -49,7 +49,7 @@ before_create :generate_embedding
 def compute_hash
 ```
 
-Computes SHA256 hash of raw_text for deduplication.
+Computes SHA256 hash of content for deduplication.
 
 ### generate_embedding
 
@@ -67,30 +67,30 @@ Generates embedding vector using configured generator.
 def self.find_or_create_by_text(text, **attributes)
 ```
 
-Find existing content by hash or create new.
+Find existing source by hash or create new.
 
 **Example:**
 
 ```ruby
-content = Content.find_or_create_by_text(
+source = Source.find_or_create_by_text(
   "Document text",
-  content_type: "document",
+  kind: "document",
   captured_at: Time.current
 )
 ```
 
 ## Scopes
 
-### by_type
+### by_kind
 
 ```ruby
-scope :by_type, ->(type) { where(content_type: type) }
+scope :by_kind, ->(kind) { where(kind: kind) }
 ```
 
-Filter by content type.
+Filter by content kind.
 
 ```ruby
-Content.by_type('email')
+Source.by_kind('email')
 ```
 
 ### captured_between
@@ -104,35 +104,35 @@ scope :captured_between, ->(from, to) {
 Filter by capture date range.
 
 ```ruby
-Content.captured_between(1.week.ago, Time.current)
+Source.captured_between(1.week.ago, Time.current)
 ```
 
 ### search_text
 
 ```ruby
 scope :search_text, ->(query) {
-  where("raw_text @@ plainto_tsquery(?)", query)
+  where("content @@ plainto_tsquery(?)", query)
 }
 ```
 
 Full-text search.
 
 ```ruby
-Content.search_text("quarterly earnings")
+Source.search_text("quarterly earnings")
 ```
 
 ## Usage Examples
 
-### Create Content
+### Create Source
 
 ```ruby
-content = Content.create!(
-  raw_text: "Important document...",
-  content_type: "document",
+source = Source.create!(
+  content: "Important document...",
+  kind: "document",
   title: "Q4 Report",
   source_uri: "https://example.com/report.pdf",
   captured_at: Time.current,
-  source_metadata: {
+  metadata: {
     author: "Jane Smith",
     department: "Finance"
   }
@@ -143,14 +143,14 @@ content = Content.create!(
 
 ```ruby
 hash = Digest::SHA256.hexdigest("Document text")
-content = Content.find_by(content_hash: hash)
+source = Source.find_by(content_hash: hash)
 ```
 
 ### Get Related Facts
 
 ```ruby
-content.facts.each do |fact|
-  puts fact.fact_text
+source.facts.each do |fact|
+  puts fact.text
 end
 ```
 
@@ -158,7 +158,7 @@ end
 
 ```ruby
 # Requires embedding
-similar = Content
+similar = Source
   .where.not(embedding: nil)
   .order(Arel.sql("embedding <=> '#{query_embedding}'"))
   .limit(10)

data/docs/api/pipeline/extraction.md

@@ -13,14 +13,14 @@ pipeline = FactDb::Pipeline::ExtractionPipeline.new(config)
 ### process
 
 ```ruby
-def process(contents, extractor: config.default_extractor)
+def process(sources, extractor: config.default_extractor)
 ```
 
-Process content items sequentially.
+Process source items sequentially.
 
 **Parameters:**
 
-- `contents` (Array<Content>) - Content records
+- `sources` (Array<Source>) - Source records
 - `extractor` (Symbol) - Extraction method
 
 **Returns:** `Array<Hash>`
@@ -28,8 +28,8 @@ Process content items sequentially.
 **Example:**
 
 ```ruby
-contents = Models::Content.where(id: [1, 2, 3])
-results = pipeline.process(contents, extractor: :llm)
+sources = Models::Source.where(id: [1, 2, 3])
+results = pipeline.process(sources, extractor: :llm)
 ```
 
 ---
@@ -37,14 +37,14 @@ results = pipeline.process(contents, extractor: :llm)
 ### process_parallel
 
 ```ruby
-def process_parallel(contents, extractor: config.default_extractor)
+def process_parallel(sources, extractor: config.default_extractor)
 ```
 
-Process content items concurrently.
+Process source items concurrently.
 
 **Parameters:**
 
-- `contents` (Array<Content>) - Content records
+- `sources` (Array<Source>) - Source records
 - `extractor` (Symbol) - Extraction method
 
 **Returns:** `Array<Hash>`
@@ -52,10 +52,10 @@ Process content items concurrently.
 **Example:**
 
 ```ruby
-results = pipeline.process_parallel(contents, extractor: :llm)
+results = pipeline.process_parallel(sources, extractor: :llm)
 
 results.each do |result|
-  puts "Content #{result[:content_id]}:"
+  puts "Source #{result[:source_id]}:"
   puts "  Facts: #{result[:facts].count}"
   puts "  Error: #{result[:error]}" if result[:error]
 end
@@ -67,7 +67,7 @@ end
 
 ```mermaid
 graph LR
-    A[Content] --> B[Validate]
+    A[Source] --> B[Validate]
     B --> C[Extract]
     C --> D[Validate Facts]
     D --> E[Results]
@@ -79,7 +79,7 @@ graph LR
     style E fill:#B91C1C,stroke:#991B1B,color:#FFFFFF
 ```
 
-1. **Validate** - Check content is not empty
+1. **Validate** - Check source is not empty
 2. **Extract** - Run extractor
 3. **Validate Facts** - Filter valid facts
 4. **Results** - Return extracted facts
@@ -89,9 +89,9 @@ graph LR
 ```mermaid
 graph TB
     subgraph Parallel
-        A1[Content 1] --> E1[Extract 1]
-        A2[Content 2] --> E2[Extract 2]
-        A3[Content 3] --> E3[Extract 3]
+        A1[Source 1] --> E1[Extract 1]
+        A2[Source 2] --> E2[Extract 2]
+        A3[Source 3] --> E3[Extract 3]
     end
     E1 --> Aggregate
     E2 --> Aggregate
@@ -110,22 +110,22 @@ graph TB
 
 ```ruby
 {
-  content_id: 123,
+  source_id: 123,
   facts: [<Fact>, <Fact>, ...],  # Extracted facts
   error: nil                      # Error message if failed
 }
 ```
 
-## Usage via Facts
+## Usage via FactDb
 
 ```ruby
 facts = FactDb.new
 
 # Sequential
-results = facts.batch_extract(content_ids, parallel: false)
+results = facts.batch_extract(source_ids, parallel: false)
 
 # Parallel (default)
-results = facts.batch_extract(content_ids, parallel: true)
+results = facts.batch_extract(source_ids, parallel: true)
 ```
 
 ## Error Handling
@@ -133,13 +133,13 @@ results = facts.batch_extract(content_ids, parallel: true)
 The pipeline catches errors per-item:
 
 ```ruby
-results = pipeline.process_parallel(contents)
+results = pipeline.process_parallel(sources)
 
 results.each do |result|
   if result[:error]
-    logger.error "Content #{result[:content_id]}: #{result[:error]}"
+    logger.error "Source #{result[:source_id]}: #{result[:error]}"
   else
-    logger.info "Content #{result[:content_id]}: #{result[:facts].count} facts"
+    logger.info "Source #{result[:source_id]}: #{result[:facts].count} facts"
   end
 end
 ```
@@ -151,12 +151,12 @@ end
 Optimal batch size depends on:
 
 - Extractor type (LLM has rate limits)
-- Content length
+- Source length
 - System resources
 
 ```ruby
 # Process in optimal batches
-contents.each_slice(25) do |batch|
+sources.each_slice(25) do |batch|
   results = pipeline.process_parallel(batch)
   process_results(results)
 end
@@ -167,7 +167,7 @@ end
 For large batches, process and discard:
 
 ```ruby
-contents.each_slice(50) do |batch|
+sources.each_slice(50) do |batch|
   results = pipeline.process_parallel(batch)
   save_facts(results.flat_map { |r| r[:facts] })
   # Results discarded after each batch

data/docs/api/pipeline/index.md

@@ -50,7 +50,7 @@ Pipeline results follow a consistent format:
 
 ```ruby
 {
-  content_id: 123,          # Item identifier
+  source_id: 123,           # Item identifier
   facts: [<Fact>, ...],     # Extracted/resolved items
   error: nil                # Error message if failed
 }

data/docs/api/pipeline/resolution.md

@@ -33,7 +33,7 @@ results = pipeline.resolve_entities(names)
 
 results.each do |result|
   puts "#{result[:name]}: #{result[:status]}"
-  puts "  Entity: #{result[:entity]&.canonical_name}"
+  puts "  Entity: #{result[:entity]&.name}"
 end
 ```
 
@@ -61,7 +61,7 @@ results = pipeline.detect_conflicts([paula.id, john.id])
 results.each do |result|
   puts "Entity #{result[:entity_id]}: #{result[:conflict_count]} conflicts"
   result[:conflicts].each do |c|
-    puts "  - #{c[:fact1].fact_text} vs #{c[:fact2].fact_text}"
+    puts "  - #{c[:fact1].text} vs #{c[:fact2].text}"
   end
 end
 ```
@@ -153,7 +153,7 @@ results = facts.detect_fact_conflicts([entity1.id, entity2.id])
 
 The pipeline uses the EntityResolver which tries:
 
-1. **Exact match** on canonical name
+1. **Exact match** on name
 2. **Alias match** on registered aliases
 3. **Fuzzy match** using Levenshtein distance
 
@@ -202,7 +202,7 @@ end
 
 ```ruby
 # Load entities into memory first
-Entity.where(entity_type: 'person').to_a
+Entity.where(type: 'person').to_a
 
 # Then resolve
 results = pipeline.resolve_entities(person_names, type: :person)