fact_db 0.0.1

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

@@ -0,0 +1,202 @@
+# EntityService
+
+Service for creating and resolving entities.
+
+## Class: `FactDb::Services::EntityService`
+
+```ruby
+service = FactDb::Services::EntityService.new(config)
+```
+
+## Methods
+
+### create
+
+```ruby
+def create(canonical_name, type:, aliases: [], metadata: {})
+```
+
+Create a new entity.
+
+**Parameters:**
+
+- `canonical_name` (String) - Authoritative name
+- `type` (Symbol) - Entity type
+- `aliases` (Array) - Alternative names
+- `metadata` (Hash) - Additional attributes
+
+**Returns:** `Models::Entity`
+
+**Example:**
+
+```ruby
+entity = service.create(
+  "Paula Chen",
+  type: :person,
+  aliases: ["Paula", "P. Chen"],
+  metadata: { department: "Engineering" }
+)
+```
+
+---
+
+### find
+
+```ruby
+def find(id)
+```
+
+Find entity by ID.
+
+**Returns:** `Models::Entity`
+
+---
+
+### resolve
+
+```ruby
+def resolve(name, type: nil)
+```
+
+Resolve a name to an entity using multiple strategies.
+
+**Parameters:**
+
+- `name` (String) - Name to resolve
+- `type` (Symbol) - Optional type filter
+
+**Returns:** `Models::Entity` or `nil`
+
+**Example:**
+
+```ruby
+entity = service.resolve("Paula Chen", type: :person)
+```
+
+---
+
+### add_alias
+
+```ruby
+def add_alias(entity_id, alias_text, type: nil, confidence: 1.0)
+```
+
+Add an alias to an entity.
+
+**Example:**
+
+```ruby
+service.add_alias(entity.id, "P. Chen", type: :abbreviation)
+```
+
+---
+
+### remove_alias
+
+```ruby
+def remove_alias(entity_id, alias_text)
+```
+
+Remove an alias from an entity.
+
+---
+
+### merge
+
+```ruby
+def merge(keep_id, merge_id)
+```
+
+Merge two entities (merge_id into keep_id).
+
+**Example:**
+
+```ruby
+service.merge(canonical_entity.id, duplicate_entity.id)
+```
+
+---
+
+### update
+
+```ruby
+def update(id, **attributes)
+```
+
+Update entity attributes.
+
+**Example:**
+
+```ruby
+service.update(
+  entity.id,
+  canonical_name: "Paula M. Chen",
+  metadata: { title: "Senior Engineer" }
+)
+```
+
+---
+
+### search
+
+```ruby
+def search(query, type: nil, limit: 20)
+```
+
+Search entities by name.
+
+**Parameters:**
+
+- `query` (String) - Search query
+- `type` (Symbol) - Optional type filter
+- `limit` (Integer) - Max results
+
+**Returns:** `Array<Models::Entity>`
+
+---
+
+### by_type
+
+```ruby
+def by_type(type)
+```
+
+Filter entities by type.
+
+**Returns:** `ActiveRecord::Relation`
+
+---
+
+### in_content
+
+```ruby
+def in_content(content_id)
+```
+
+Find entities mentioned in a content.
+
+**Returns:** `Array<Models::Entity>`
+
+---
+
+### related_to
+
+```ruby
+def related_to(entity_id)
+```
+
+Find entities that appear in facts with the given entity.
+
+**Returns:** `Array<Models::Entity>`
+
+---
+
+### semantic_search
+
+```ruby
+def semantic_search(query, type: nil, limit: 10)
+```
+
+Semantic similarity search using embeddings.
+
+**Returns:** `Array<Models::Entity>`

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

@@ -0,0 +1,223 @@
+# FactService
+
+Service for extracting and querying facts.
+
+## Class: `FactDb::Services::FactService`
+
+```ruby
+service = FactDb::Services::FactService.new(config)
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `resolver` | FactResolver | For fact resolution operations |
+
+## Methods
+
+### create
+
+```ruby
+def create(fact_text, valid_at:, invalid_at: nil, mentions: [], sources: [], confidence: 1.0, metadata: {})
+```
+
+Create a new fact.
+
+**Parameters:**
+
+- `fact_text` (String) - The assertion
+- `valid_at` (Date/Time) - When fact became true
+- `invalid_at` (Date/Time) - When fact stopped (optional)
+- `mentions` (Array) - Entity mentions
+- `sources` (Array) - Source content links
+- `confidence` (Float) - Extraction confidence
+- `metadata` (Hash) - Additional data
+
+**Returns:** `Models::Fact`
+
+**Example:**
+
+```ruby
+fact = service.create(
+  "Paula Chen is Principal Engineer",
+  valid_at: Date.parse("2024-01-10"),
+  mentions: [
+    { entity: paula, role: "subject", text: "Paula Chen" }
+  ],
+  sources: [
+    { content: email, type: "primary" }
+  ]
+)
+```
+
+---
+
+### find
+
+```ruby
+def find(id)
+```
+
+Find fact by ID.
+
+**Returns:** `Models::Fact`
+
+---
+
+### extract_from_content
+
+```ruby
+def extract_from_content(content_id, extractor: config.default_extractor)
+```
+
+Extract facts from content using specified extractor.
+
+**Parameters:**
+
+- `content_id` (Integer) - Content ID
+- `extractor` (Symbol) - Extractor type (:manual, :llm, :rule_based)
+
+**Returns:** `Array<Models::Fact>`
+
+**Example:**
+
+```ruby
+facts = service.extract_from_content(content.id, extractor: :llm)
+```
+
+---
+
+### query
+
+```ruby
+def query(topic: nil, at: nil, entity: nil, status: :canonical, from: nil, to: nil, limit: nil)
+```
+
+Query facts with filters.
+
+**Parameters:**
+
+- `topic` (String) - Text search
+- `at` (Date/Time) - Point in time
+- `entity` (Integer) - Entity ID
+- `status` (Symbol/Array) - Status filter
+- `from` (Date/Time) - Range start
+- `to` (Date/Time) - Range end
+- `limit` (Integer) - Max results
+
+**Returns:** `ActiveRecord::Relation`
+
+**Example:**
+
+```ruby
+# Current facts about Paula
+facts = service.query(entity: paula.id, status: :canonical)
+
+# Historical facts
+facts = service.query(entity: paula.id, at: Date.parse("2023-06-15"))
+
+# Facts in a range
+facts = service.query(
+  entity: paula.id,
+  from: Date.parse("2023-01-01"),
+  to: Date.parse("2023-12-31")
+)
+```
+
+---
+
+### timeline
+
+```ruby
+def timeline(entity_id:, from: nil, to: nil)
+```
+
+Build a timeline for an entity.
+
+**Returns:** `Array<Models::Fact>`
+
+**Example:**
+
+```ruby
+timeline = service.timeline(entity_id: paula.id)
+timeline.each do |fact|
+  puts "#{fact.valid_at}: #{fact.fact_text}"
+end
+```
+
+---
+
+### from_content
+
+```ruby
+def from_content(content_id)
+```
+
+Get facts sourced from specific content.
+
+**Returns:** `Array<Models::Fact>`
+
+---
+
+### semantic_search
+
+```ruby
+def semantic_search(query, entity: nil, limit: 10)
+```
+
+Semantic similarity search.
+
+**Returns:** `Array<Models::Fact>`
+
+## Resolver Methods
+
+Access via `service.resolver`:
+
+### supersede
+
+```ruby
+service.resolver.supersede(old_fact_id, new_text, valid_at: date)
+```
+
+Supersede an existing fact.
+
+### synthesize
+
+```ruby
+service.resolver.synthesize(source_ids, synthesized_text, valid_at: date)
+```
+
+Create synthesized fact from multiple sources.
+
+### corroborate
+
+```ruby
+service.resolver.corroborate(fact_id, corroborating_fact_id)
+```
+
+Mark fact as corroborated.
+
+### invalidate
+
+```ruby
+service.resolver.invalidate(fact_id, at: Time.current)
+```
+
+Invalidate a fact.
+
+### find_conflicts
+
+```ruby
+service.resolver.find_conflicts(entity_id: id, topic: text)
+```
+
+Find potentially conflicting facts.
+
+### resolve_conflict
+
+```ruby
+service.resolver.resolve_conflict(keep_id, supersede_ids, reason: text)
+```
+
+Resolve conflicts by keeping one fact.

data/docs/api/services/index.md

@@ -0,0 +1,55 @@
+# Services
+
+Services provide the business logic layer for FactDb operations.
+
+## Available Services
+
+- [ContentService](content-service.md) - Ingest and manage source content
+- [EntityService](entity-service.md) - Create and resolve entities
+- [FactService](fact-service.md) - Extract and query facts
+
+## Service Pattern
+
+All services follow a common pattern:
+
+```ruby
+class SomeService
+  attr_reader :config
+
+  def initialize(config = FactDb.config)
+    @config = config
+  end
+
+  # Business methods...
+end
+```
+
+## Accessing Services
+
+### Via Facts
+
+```ruby
+facts = FactDb.new
+
+facts.content_service.create(text, type: :document)
+facts.entity_service.create("Paula", type: :person)
+facts.fact_service.create("Fact text", valid_at: Date.today)
+```
+
+### Directly
+
+```ruby
+service = FactDb::Services::ContentService.new(config)
+content = service.create(text, type: :document)
+```
+
+## Common Methods
+
+All services provide these common methods:
+
+| Method | Description |
+|--------|-------------|
+| `find(id)` | Find record by ID |
+| `create(...)` | Create new record |
+| `update(id, ...)` | Update existing record |
+| `search(query)` | Search records |