fact_db 0.0.2 → 0.0.3

data/docs/api/services/entity-service.md

@@ -13,15 +13,15 @@ service = FactDb::Services::EntityService.new(config)
 ### create
 
 ```ruby
-def create(canonical_name, type:, aliases: [], metadata: {})
+def create(name, kind:, aliases: [], metadata: {})
 ```
 
 Create a new entity.
 
 **Parameters:**
 
-- `canonical_name` (String) - Authoritative name
-- `type` (Symbol) - Entity type
+- `name` (String) - Authoritative name
+- `kind` (Symbol) - Entity kind
 - `aliases` (Array) - Alternative names
 - `metadata` (Hash) - Additional attributes
 
@@ -32,7 +32,7 @@ Create a new entity.
 ```ruby
 entity = service.create(
   "Paula Chen",
-  type: :person,
+  kind: :person,
   aliases: ["Paula", "P. Chen"],
   metadata: { department: "Engineering" }
 )
@@ -55,7 +55,7 @@ Find entity by ID.
 ### resolve
 
 ```ruby
-def resolve(name, type: nil)
+def resolve(name, kind: nil)
 ```
 
 Resolve a name to an entity using multiple strategies.
@@ -63,14 +63,14 @@ Resolve a name to an entity using multiple strategies.
 **Parameters:**
 
 - `name` (String) - Name to resolve
-- `type` (Symbol) - Optional type filter
+- `kind` (Symbol) - Optional kind filter
 
 **Returns:** `Models::Entity` or `nil`
 
 **Example:**
 
 ```ruby
-entity = service.resolve("Paula Chen", type: :person)
+entity = service.resolve("Paula Chen", kind: :person)
 ```
 
 ---
@@ -78,7 +78,7 @@ entity = service.resolve("Paula Chen", type: :person)
 ### add_alias
 
 ```ruby
-def add_alias(entity_id, alias_text, type: nil, confidence: 1.0)
+def add_alias(entity_id, alias_name, kind: nil, confidence: 1.0)
 ```
 
 Add an alias to an entity.
@@ -86,7 +86,7 @@ Add an alias to an entity.
 **Example:**
 
 ```ruby
-service.add_alias(entity.id, "P. Chen", type: :abbreviation)
+service.add_alias(entity.id, "P. Chen", kind: :abbreviation)
 ```
 
 ---
@@ -94,7 +94,7 @@ service.add_alias(entity.id, "P. Chen", type: :abbreviation)
 ### remove_alias
 
 ```ruby
-def remove_alias(entity_id, alias_text)
+def remove_alias(entity_id, alias_name)
 ```
 
 Remove an alias from an entity.
@@ -130,7 +130,7 @@ Update entity attributes.
 ```ruby
 service.update(
   entity.id,
-  canonical_name: "Paula M. Chen",
+  name: "Paula M. Chen",
   metadata: { title: "Senior Engineer" }
 )
 ```
@@ -140,7 +140,7 @@ service.update(
 ### search
 
 ```ruby
-def search(query, type: nil, limit: 20)
+def search(query, kind: nil, limit: 20)
 ```
 
 Search entities by name.
@@ -148,32 +148,32 @@ Search entities by name.
 **Parameters:**
 
 - `query` (String) - Search query
-- `type` (Symbol) - Optional type filter
+- `kind` (Symbol) - Optional kind filter
 - `limit` (Integer) - Max results
 
 **Returns:** `Array<Models::Entity>`
 
 ---
 
-### by_type
+### by_kind
 
 ```ruby
-def by_type(type)
+def by_kind(kind)
 ```
 
-Filter entities by type.
+Filter entities by kind.
 
 **Returns:** `ActiveRecord::Relation`
 
 ---
 
-### in_content
+### in_source
 
 ```ruby
-def in_content(content_id)
+def in_source(source_id)
 ```
 
-Find entities mentioned in a content.
+Find entities mentioned in a source.
 
 **Returns:** `Array<Models::Entity>`
 
@@ -194,7 +194,7 @@ Find entities that appear in facts with the given entity.
 ### semantic_search
 
 ```ruby
-def semantic_search(query, type: nil, limit: 10)
+def semantic_search(query, kind: nil, limit: 10)
 ```
 
 Semantic similarity search using embeddings.

data/docs/api/services/fact-service.md

@@ -19,14 +19,14 @@ service = FactDb::Services::FactService.new(config)
 ### create
 
 ```ruby
-def create(fact_text, valid_at:, invalid_at: nil, mentions: [], sources: [], confidence: 1.0, metadata: {})
+def create(text, valid_at:, invalid_at: nil, mentions: [], sources: [], confidence: 1.0, metadata: {})
 ```
 
 Create a new fact.
 
 **Parameters:**
 
-- `fact_text` (String) - The assertion
+- `text` (String) - The assertion
 - `valid_at` (Date/Time) - When fact became true
 - `invalid_at` (Date/Time) - When fact stopped (optional)
 - `mentions` (Array) - Entity mentions
@@ -46,7 +46,7 @@ fact = service.create(
     { entity: paula, role: "subject", text: "Paula Chen" }
   ],
   sources: [
-    { content: email, type: "primary" }
+    { source: email, type: "primary" }
   ]
 )
 ```
@@ -65,17 +65,17 @@ Find fact by ID.
 
 ---
 
-### extract_from_content
+### extract_from_source
 
 ```ruby
-def extract_from_content(content_id, extractor: config.default_extractor)
+def extract_from_source(source_id, extractor: config.default_extractor)
 ```
 
-Extract facts from content using specified extractor.
+Extract facts from source using specified extractor.
 
 **Parameters:**
 
-- `content_id` (Integer) - Content ID
+- `source_id` (Integer) - Source ID
 - `extractor` (Symbol) - Extractor type (:manual, :llm, :rule_based)
 
 **Returns:** `Array<Models::Fact>`
@@ -83,7 +83,7 @@ Extract facts from content using specified extractor.
 **Example:**
 
 ```ruby
-facts = service.extract_from_content(content.id, extractor: :llm)
+facts = service.extract_from_source(source.id, extractor: :llm)
 ```
 
 ---
@@ -142,19 +142,19 @@ Build a timeline for an entity.
 ```ruby
 timeline = service.timeline(entity_id: paula.id)
 timeline.each do |fact|
-  puts "#{fact.valid_at}: #{fact.fact_text}"
+  puts "#{fact.valid_at}: #{fact.text}"
 end
 ```
 
 ---
 
-### from_content
+### from_source
 
 ```ruby
-def from_content(content_id)
+def from_source(source_id)
 ```
 
-Get facts sourced from specific content.
+Get facts sourced from specific source.
 
 **Returns:** `Array<Models::Fact>`
 

data/docs/api/services/index.md

@@ -4,7 +4,7 @@ Services provide the business logic layer for FactDb operations.
 
 ## Available Services
 
-- [ContentService](content-service.md) - Ingest and manage source content
+- [SourceService](source-service.md) - Ingest and manage source content
 - [EntityService](entity-service.md) - Create and resolve entities
 - [FactService](fact-service.md) - Extract and query facts
 
@@ -26,12 +26,12 @@ end
 
 ## Accessing Services
 
-### Via Facts
+### Via FactDb
 
 ```ruby
 facts = FactDb.new
 
-facts.content_service.create(text, type: :document)
+facts.source_service.create(text, type: :document)
 facts.entity_service.create("Paula", type: :person)
 facts.fact_service.create("Fact text", valid_at: Date.today)
 ```
@@ -39,8 +39,8 @@ facts.fact_service.create("Fact text", valid_at: Date.today)
 ### Directly
 
 ```ruby
-service = FactDb::Services::ContentService.new(config)
-content = service.create(text, type: :document)
+service = FactDb::Services::SourceService.new(config)
+source = service.create(text, type: :document)
 ```
 
 ## Common Methods

data/docs/api/services/{content-service.md → source-service.md}

@@ -1,11 +1,11 @@
-# ContentService
+# SourceService
 
 Service for ingesting and managing source content.
 
-## Class: `FactDb::Services::ContentService`
+## Class: `FactDb::Services::SourceService`
 
 ```ruby
-service = FactDb::Services::ContentService.new(config)
+service = FactDb::Services::SourceService.new(config)
 ```
 
 ## Methods
@@ -13,28 +13,28 @@ service = FactDb::Services::ContentService.new(config)
 ### create
 
 ```ruby
-def create(raw_text, type:, captured_at: Time.current, metadata: {}, title: nil, source_uri: nil)
+def create(content, kind:, captured_at: Time.current, metadata: {}, title: nil, source_uri: nil)
 ```
 
-Create new content with automatic deduplication.
+Create new source with automatic deduplication.
 
 **Parameters:**
 
-- `raw_text` (String) - Content text
-- `type` (Symbol) - Content type
+- `content` (String) - Source text content
+- `kind` (Symbol) - Content kind
 - `captured_at` (Time) - Capture timestamp
 - `metadata` (Hash) - Additional metadata
 - `title` (String) - Optional title
 - `source_uri` (String) - Original location
 
-**Returns:** `Models::Content`
+**Returns:** `Models::Source`
 
 **Example:**
 
 ```ruby
-content = service.create(
+source = service.create(
   "Email body text...",
-  type: :email,
+  kind: :email,
   title: "RE: Important",
   metadata: { from: "sender@example.com" }
 )
@@ -48,9 +48,9 @@ content = service.create(
 def find(id)
 ```
 
-Find content by ID.
+Find source by ID.
 
-**Returns:** `Models::Content`
+**Returns:** `Models::Source`
 
 ---
 
@@ -60,15 +60,15 @@ Find content by ID.
 def find_by_hash(hash)
 ```
 
-Find content by SHA256 hash.
+Find source by SHA256 hash.
 
-**Returns:** `Models::Content` or `nil`
+**Returns:** `Models::Source` or `nil`
 
 **Example:**
 
 ```ruby
 hash = Digest::SHA256.hexdigest(text)
-content = service.find_by_hash(hash)
+source = service.find_by_hash(hash)
 ```
 
 ---
@@ -79,14 +79,14 @@ content = service.find_by_hash(hash)
 def search(query, limit: 20)
 ```
 
-Full-text search content.
+Full-text search sources.
 
 **Parameters:**
 
 - `query` (String) - Search query
 - `limit` (Integer) - Max results
 
-**Returns:** `Array<Models::Content>`
+**Returns:** `Array<Models::Source>`
 
 **Example:**
 
@@ -109,7 +109,7 @@ Semantic similarity search using embeddings.
 - `query` (String) - Search query
 - `limit` (Integer) - Max results
 
-**Returns:** `Array<Models::Content>`
+**Returns:** `Array<Models::Source>`
 
 **Example:**
 
@@ -119,20 +119,20 @@ results = service.semantic_search("financial performance")
 
 ---
 
-### by_type
+### by_kind
 
 ```ruby
-def by_type(type)
+def by_kind(kind)
 ```
 
-Filter content by type.
+Filter sources by kind.
 
 **Returns:** `ActiveRecord::Relation`
 
 **Example:**
 
 ```ruby
-emails = service.by_type(:email)
+emails = service.by_kind(:email)
 ```
 
 ---
@@ -143,9 +143,9 @@ emails = service.by_type(:email)
 def recent(limit: 20)
 ```
 
-Get recently captured content.
+Get recently captured sources.
 
-**Returns:** `Array<Models::Content>`
+**Returns:** `Array<Models::Source>`
 
 ---
 
@@ -155,12 +155,12 @@ Get recently captured content.
 def mentioning_entity(entity_id)
 ```
 
-Find content that mentions an entity (via facts).
+Find sources that mention an entity (via facts).
 
-**Returns:** `Array<Models::Content>`
+**Returns:** `Array<Models::Source>`
 
 **Example:**
 
 ```ruby
-paula_content = service.mentioning_entity(paula.id)
+paula_sources = service.mentioning_entity(paula.id)
 ```

data/docs/architecture/database-schema.md

@@ -6,21 +6,21 @@ FactDb uses PostgreSQL with the pgvector extension for semantic search capabilit
 
 ```mermaid
 erDiagram
-    contents ||--o{ fact_sources : "sourced by"
+    sources ||--o{ fact_sources : "sourced by"
     entities ||--o{ entity_aliases : "has"
     entities ||--o{ entity_mentions : "mentioned in"
     facts ||--o{ entity_mentions : "mentions"
     facts ||--o{ fact_sources : "sourced from"
     facts ||--o| facts : "superseded by"
 
-    contents {
+    sources {
         bigint id PK
         string content_hash UK
-        string content_type
-        text raw_text
+        string type
+        text content
         string title
         string source_uri
-        jsonb source_metadata
+        jsonb metadata
         vector embedding
         timestamptz captured_at
         timestamptz created_at
@@ -28,10 +28,10 @@ erDiagram
 
     entities {
         bigint id PK
-        string canonical_name
-        string entity_type
+        string name
+        string type
         string resolution_status
-        bigint merged_into_id FK
+        bigint canonical_id FK
         jsonb metadata
         vector embedding
         timestamptz created_at
@@ -40,15 +40,15 @@ erDiagram
     entity_aliases {
         bigint id PK
         bigint entity_id FK
-        string alias_text
-        string alias_type
+        string name
+        string type
         float confidence
     }
 
     facts {
         bigint id PK
-        text fact_text
-        string fact_hash
+        text text
+        string digest
         timestamptz valid_at
         timestamptz invalid_at
         string status
@@ -74,8 +74,8 @@ erDiagram
     fact_sources {
         bigint id PK
         bigint fact_id FK
-        bigint content_id FK
-        string source_type
+        bigint source_id FK
+        string kind
         text excerpt
         float confidence
     }
@@ -83,28 +83,28 @@ erDiagram
 
 ## Tables
 
-### contents
+### sources
 
-Stores immutable source documents.
+Stores immutable source content.
 
 ```sql
-CREATE TABLE contents (
+CREATE TABLE sources (
     id BIGSERIAL PRIMARY KEY,
     content_hash VARCHAR(64) NOT NULL UNIQUE,
-    content_type VARCHAR(50) NOT NULL,
-    raw_text TEXT NOT NULL,
+    type VARCHAR(50) NOT NULL,
+    content TEXT NOT NULL,
     title VARCHAR(255),
     source_uri TEXT,
-    source_metadata JSONB NOT NULL DEFAULT '{}',
+    metadata JSONB NOT NULL DEFAULT '{}',
     embedding VECTOR(1536),
     captured_at TIMESTAMPTZ NOT NULL,
     created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
-CREATE INDEX idx_contents_type ON contents(content_type);
-CREATE INDEX idx_contents_captured ON contents(captured_at);
-CREATE INDEX idx_contents_text ON contents USING gin(to_tsvector('english', raw_text));
-CREATE INDEX idx_contents_embedding ON contents USING hnsw(embedding vector_cosine_ops);
+CREATE INDEX idx_sources_type ON sources(type);
+CREATE INDEX idx_sources_captured ON sources(captured_at);
+CREATE INDEX idx_sources_text ON sources USING gin(to_tsvector('english', content));
+CREATE INDEX idx_sources_embedding ON sources USING hnsw(embedding vector_cosine_ops);
 ```
 
 ### entities
@@ -114,17 +114,17 @@ Stores resolved identities.
 ```sql
 CREATE TABLE entities (
     id BIGSERIAL PRIMARY KEY,
-    canonical_name VARCHAR(255) NOT NULL,
-    entity_type VARCHAR(50) NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    type VARCHAR(50) NOT NULL,
     resolution_status VARCHAR(20) NOT NULL DEFAULT 'unresolved',
-    merged_into_id BIGINT REFERENCES entities(id),
+    canonical_id BIGINT REFERENCES entities(id),
     metadata JSONB NOT NULL DEFAULT '{}',
     embedding VECTOR(1536),
     created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
-CREATE INDEX idx_entities_name ON entities(canonical_name);
-CREATE INDEX idx_entities_type ON entities(entity_type);
+CREATE INDEX idx_entities_name ON entities(name);
+CREATE INDEX idx_entities_type ON entities(type);
 CREATE INDEX idx_entities_status ON entities(resolution_status);
 CREATE INDEX idx_entities_embedding ON entities USING hnsw(embedding vector_cosine_ops);
 ```
@@ -137,14 +137,14 @@ Stores alternative names for entities.
 CREATE TABLE entity_aliases (
     id BIGSERIAL PRIMARY KEY,
     entity_id BIGINT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
-    alias_text VARCHAR(255) NOT NULL,
-    alias_type VARCHAR(50),
+    name VARCHAR(255) NOT NULL,
+    type VARCHAR(50),
     confidence FLOAT DEFAULT 1.0
 );
 
 CREATE INDEX idx_aliases_entity ON entity_aliases(entity_id);
-CREATE INDEX idx_aliases_text ON entity_aliases(alias_text);
-CREATE UNIQUE INDEX idx_aliases_unique ON entity_aliases(entity_id, alias_text);
+CREATE INDEX idx_aliases_text ON entity_aliases(name);
+CREATE UNIQUE INDEX idx_aliases_unique ON entity_aliases(entity_id, name);
 ```
 
 ### facts
@@ -154,8 +154,8 @@ Stores temporal assertions.
 ```sql
 CREATE TABLE facts (
     id BIGSERIAL PRIMARY KEY,
-    fact_text TEXT NOT NULL,
-    fact_hash VARCHAR(64) NOT NULL,
+    text TEXT NOT NULL,
+    digest VARCHAR(64) NOT NULL,
     valid_at TIMESTAMPTZ NOT NULL,
     invalid_at TIMESTAMPTZ,
     status VARCHAR(20) NOT NULL DEFAULT 'canonical',
@@ -174,7 +174,7 @@ CREATE INDEX idx_facts_valid ON facts(valid_at);
 CREATE INDEX idx_facts_invalid ON facts(invalid_at);
 CREATE INDEX idx_facts_temporal ON facts(valid_at, invalid_at);
 CREATE INDEX idx_facts_method ON facts(extraction_method);
-CREATE INDEX idx_facts_text ON facts USING gin(to_tsvector('english', fact_text));
+CREATE INDEX idx_facts_text ON facts USING gin(to_tsvector('english', text));
 CREATE INDEX idx_facts_embedding ON facts USING hnsw(embedding vector_cosine_ops);
 ```
 
@@ -205,15 +205,15 @@ Links facts to source content.
 CREATE TABLE fact_sources (
     id BIGSERIAL PRIMARY KEY,
     fact_id BIGINT NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
-    content_id BIGINT NOT NULL REFERENCES contents(id),
-    source_type VARCHAR(50) NOT NULL DEFAULT 'primary',
+    source_id BIGINT NOT NULL REFERENCES sources(id),
+    kind VARCHAR(50) NOT NULL DEFAULT 'primary',
     excerpt TEXT,
     confidence FLOAT DEFAULT 1.0
 );
 
-CREATE INDEX idx_sources_fact ON fact_sources(fact_id);
-CREATE INDEX idx_sources_content ON fact_sources(content_id);
-CREATE INDEX idx_sources_type ON fact_sources(source_type);
+CREATE INDEX idx_fact_sources_fact ON fact_sources(fact_id);
+CREATE INDEX idx_fact_sources_source ON fact_sources(source_id);
+CREATE INDEX idx_fact_sources_kind ON fact_sources(kind);
 ```
 
 ## Vector Indexes
@@ -221,8 +221,8 @@ CREATE INDEX idx_sources_type ON fact_sources(source_type);
 FactDb uses HNSW indexes for fast approximate nearest neighbor search:
 
 ```sql
--- Contents semantic search
-CREATE INDEX idx_contents_embedding ON contents
+-- Sources semantic search
+CREATE INDEX idx_sources_embedding ON sources
     USING hnsw(embedding vector_cosine_ops)
     WITH (m = 16, ef_construction = 64);
 
@@ -269,7 +269,7 @@ ORDER BY f.valid_at ASC;
 
 ```sql
 SELECT *, embedding <=> '[...]' AS distance
-FROM contents
+FROM sources
 ORDER BY embedding <=> '[...]'
 LIMIT 10;
 ```
@@ -279,7 +279,7 @@ LIMIT 10;
 ### Vacuum and Analyze
 
 ```sql
-VACUUM ANALYZE contents;
+VACUUM ANALYZE sources;
 VACUUM ANALYZE entities;
 VACUUM ANALYZE facts;
 ```
@@ -287,7 +287,7 @@ VACUUM ANALYZE facts;
 ### Reindex Vectors
 
 ```sql
-REINDEX INDEX idx_contents_embedding;
+REINDEX INDEX idx_sources_embedding;
 REINDEX INDEX idx_entities_embedding;
 REINDEX INDEX idx_facts_embedding;
 ```

data/docs/architecture/entity-resolution.md

@@ -33,7 +33,7 @@ Direct match against canonical names:
 ```ruby
 # Looking for "Microsoft"
 entity = facts.resolve_entity("Microsoft")
-# Matches: Entity(canonical_name: "Microsoft")
+# Matches: Entity(name: "Microsoft")
 ```
 
 ### 2. Alias Match
@@ -130,7 +130,7 @@ facts.entity_service.add_alias(
 
 ```ruby
 entity.entity_aliases.each do |alias_record|
-  puts "#{alias_record.alias_text} (#{alias_record.alias_type})"
+  puts "#{alias_record.name} (#{alias_record.type})"
 end
 ```
 
@@ -153,7 +153,7 @@ facts.entity_service.merge(
 
 # After merge:
 # - entity2.resolution_status => "merged"
-# - entity2.merged_into_id => entity1.id
+# - entity2.canonical_id => entity1.id
 # - All facts mentioning entity2 now also reference entity1
 ```
 
@@ -193,11 +193,11 @@ fact = facts.fact_service.create(
 The LLM extractor resolves mentions automatically:
 
 ```ruby
-extracted = facts.extract_facts(content.id, extractor: :llm)
+extracted = facts.extract_facts(source.id, extractor: :llm)
 
 extracted.each do |fact|
   fact.entity_mentions.each do |mention|
-    puts "Resolved '#{mention.mention_text}' to #{mention.entity.canonical_name}"
+    puts "Resolved '#{mention.mention_text}' to #{mention.entity.name}"
     puts "  Role: #{mention.mention_role}"
     puts "  Confidence: #{mention.confidence}"
   end
@@ -240,7 +240,7 @@ results = facts.batch_resolve_entities(names)
 
 results.each do |result|
   puts "#{result[:name]}: #{result[:status]}"
-  puts "  Entity: #{result[:entity]&.canonical_name}"
+  puts "  Entity: #{result[:entity]&.name}"
 end
 ```