fact_db 0.0.1

data/docs/assets/css/custom.css

@@ -0,0 +1,137 @@
+/* EventClock Documentation Custom Styles */
+
+/* Code blocks */
+.highlight pre {
+  border-radius: 6px;
+}
+
+/* Tables */
+.md-typeset table:not([class]) {
+  font-size: 0.85rem;
+}
+
+.md-typeset table:not([class]) th {
+  background-color: var(--md-primary-fg-color);
+  color: var(--md-primary-bg-color);
+}
+
+/* Admonitions */
+.md-typeset .admonition {
+  border-radius: 6px;
+}
+
+/* Method signatures */
+.md-typeset code {
+  border-radius: 4px;
+}
+
+/* Navigation */
+.md-nav__link {
+  font-size: 0.85rem;
+}
+
+/* Mermaid diagrams */
+.mermaid {
+  text-align: center;
+  margin: 1.5rem 0;
+}
+
+/* API reference styling */
+.md-typeset h3 code {
+  background: transparent;
+  padding: 0;
+}
+
+/* Parameters table */
+.md-typeset table:not([class]) td:first-child code {
+  white-space: nowrap;
+}
+
+/* Example blocks */
+.md-typeset .example {
+  background-color: var(--md-code-bg-color);
+  border-left: 4px solid var(--md-accent-fg-color);
+  padding: 1rem;
+  margin: 1rem 0;
+  border-radius: 0 6px 6px 0;
+}
+
+/* Cards grid (for index pages) */
+.grid.cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+  gap: 1rem;
+  margin: 1rem 0;
+}
+
+/* Method dividers */
+.md-typeset hr {
+  margin: 2rem 0;
+  border-top: 1px solid var(--md-default-fg-color--lightest);
+}
+
+/* Smaller font for long code blocks */
+.md-typeset pre > code {
+  font-size: 0.8rem;
+}
+
+/* Timeline styling */
+.timeline {
+  border-left: 2px solid var(--md-accent-fg-color);
+  padding-left: 1rem;
+  margin-left: 0.5rem;
+}
+
+.timeline-item {
+  position: relative;
+  padding-bottom: 1rem;
+}
+
+.timeline-item::before {
+  content: "";
+  position: absolute;
+  left: -1.4rem;
+  top: 0.5rem;
+  width: 10px;
+  height: 10px;
+  background: var(--md-accent-fg-color);
+  border-radius: 50%;
+}
+
+/* Status badges */
+.status-canonical {
+  background: #4caf50;
+  color: white;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 0.75rem;
+}
+
+.status-superseded {
+  background: #ff9800;
+  color: white;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 0.75rem;
+}
+
+.status-corroborated {
+  background: #2196f3;
+  color: white;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 0.75rem;
+}
+
+.status-synthesized {
+  background: #9c27b0;
+  color: white;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 0.75rem;
+}
+
+/* Dark mode adjustments */
+[data-md-color-scheme="slate"] .md-typeset table:not([class]) th {
+  background-color: var(--md-primary-fg-color--dark);
+}

data/docs/concepts.md

@@ -0,0 +1,183 @@
+# Core Concepts
+
+FactDb is built around several key concepts that work together to provide temporal fact tracking with full provenance.
+
+## The Three-Layer Model
+
+### Content Layer
+
+The content layer stores immutable source documents - emails, articles, reports, transcripts, or any text that contains facts. Content is:
+
+- **Immutable** - Once ingested, content never changes
+- **Deduplicated** - Identified by content hash to prevent duplicates
+- **Timestamped** - Records when the content was captured
+- **Searchable** - Supports full-text and semantic search via embeddings
+
+### Entity Layer
+
+Entities represent real-world things mentioned in content:
+
+| Type | Examples |
+|------|----------|
+| `person` | Paula Chen, John Smith |
+| `organization` | Microsoft, Acme Corp |
+| `place` | San Francisco, Building A |
+| `product` | Windows 11, iPhone |
+| `event` | Q4 2024 Earnings Call |
+
+Entities support:
+
+- **Canonical Names** - The authoritative name for the entity
+- **Aliases** - Alternative names and spellings
+- **Resolution** - Matching mentions to entities via exact match, aliases, or fuzzy matching
+- **Merging** - Combining duplicate entities when discovered
+
+### Fact Layer
+
+Facts are temporal assertions about entities:
+
+```ruby
+# A fact has:
+# - fact_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
+# - entity_mentions: Links to entities mentioned in the fact
+# - fact_sources: Links to source content
+```
+
+## Fact Lifecycle
+
+Facts move through different statuses as information evolves:
+
+```mermaid
+stateDiagram-v2
+    [*] --> canonical: New fact extracted
+    canonical --> corroborated: Multiple sources confirm
+    canonical --> superseded: New information replaces
+    canonical --> synthesized: Combined with other facts
+    superseded --> [*]: Archived
+    corroborated --> superseded: Later replaced
+
+    classDef blue fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
+    classDef green fill:#047857,stroke:#065F46,color:#FFFFFF
+    classDef red fill:#B91C1C,stroke:#991B1B,color:#FFFFFF
+    classDef yellow fill:#B45309,stroke:#92400E,color:#FFFFFF
+
+    class canonical blue
+    class corroborated green
+    class superseded red
+    class synthesized yellow
+```
+
+### Canonical
+
+A canonical fact is the current authoritative version:
+
+```ruby
+fact = facts.fact_service.create(
+  "Paula is a Principal Engineer",
+  valid_at: Date.parse("2024-01-10"),
+  mentions: [{ entity: paula, role: "subject" }]
+)
+# fact.status => "canonical"
+```
+
+### Superseded
+
+When information changes, the old fact is superseded:
+
+```ruby
+# Paula gets promoted
+new_fact = facts.fact_service.resolver.supersede(
+  fact.id,
+  "Paula is a Senior Principal Engineer",
+  valid_at: Date.parse("2024-06-01")
+)
+# old fact.status => "superseded"
+# old fact.invalid_at => "2024-06-01"
+# new_fact.status => "canonical"
+```
+
+### Corroborated
+
+Facts confirmed by multiple sources gain higher confidence:
+
+```ruby
+facts.fact_service.resolver.corroborate(fact.id, other_fact.id)
+# After 2+ corroborations: fact.status => "corroborated"
+```
+
+### Synthesized
+
+Derived facts combine information from multiple sources:
+
+```ruby
+synthesized = facts.fact_service.resolver.synthesize(
+  [fact1.id, fact2.id, fact3.id],
+  "Paula worked at Microsoft from Jan 2024, promoted to Senior in June 2024",
+  valid_at: Date.parse("2024-01-10")
+)
+# synthesized.status => "synthesized"
+# synthesized.derived_from_ids => [fact1.id, fact2.id, fact3.id]
+```
+
+## Temporal Queries
+
+The power of FactDb is querying facts across time:
+
+```ruby
+# What do we know now?
+current_facts = facts.query_facts(entity: paula.id)
+
+# What did we know on March 1st?
+march_facts = facts.facts_at(Date.parse("2024-03-01"), entity: paula.id)
+
+# What's the full timeline?
+timeline = facts.timeline_for(paula.id, from: "2024-01-01", to: "2024-12-31")
+```
+
+## Entity Resolution
+
+When extracting facts, mentions must be resolved to entities:
+
+```mermaid
+graph LR
+    M1["'Paula'"] --> R{Resolver}
+    M2["'P. Chen'"] --> R
+    M3["'Paula Chen'"] --> R
+    R --> E[Paula Chen Entity]
+
+    style M1 fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
+    style M2 fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
+    style M3 fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF
+    style R fill:#B45309,stroke:#92400E,color:#FFFFFF
+    style E fill:#047857,stroke:#065F46,color:#FFFFFF
+```
+
+Resolution strategies (in order):
+
+1. **Exact Match** - Direct canonical name match
+2. **Alias Match** - Match against registered aliases
+3. **Fuzzy Match** - Levenshtein distance for typos/variations
+4. **Create New** - If no match, optionally create new entity
+
+## Audit Trails
+
+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}"
+end
+```
+
+This enables:
+
+- Tracing facts back to original documents
+- Verifying information
+- Understanding confidence levels
+- Investigating contradictions

data/docs/examples/basic-usage.md

@@ -0,0 +1,235 @@
+# Basic Usage
+
+A simple introduction to FactDb's core functionality.
+
+## Setup
+
+```ruby
+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']
+end
+
+# Create facts instance
+facts = FactDb.new
+```
+
+## Ingest Content
+
+```ruby
+# Ingest an email
+email = facts.ingest(
+  <<~TEXT,
+    Hi team,
+
+    I'm excited to announce that Paula Chen has accepted our offer
+    to join Microsoft as Principal Engineer starting January 10, 2024.
+
+    She'll be part of the Platform team reporting to Sarah Johnson.
+
+    Best,
+    HR
+  TEXT
+  type: :email,
+  title: "New Hire Announcement - Paula Chen",
+  captured_at: Time.current
+)
+
+puts "Ingested content ID: #{email.id}"
+```
+
+## Create Entities
+
+```ruby
+# Create people
+paula = facts.entity_service.create(
+  "Paula Chen",
+  type: :person,
+  aliases: ["Paula"]
+)
+
+sarah = facts.entity_service.create(
+  "Sarah Johnson",
+  type: :person,
+  aliases: ["Sarah"]
+)
+
+# Create organization
+microsoft = facts.entity_service.create(
+  "Microsoft",
+  type: :organization,
+  aliases: ["MS", "MSFT"]
+)
+
+platform_team = facts.entity_service.create(
+  "Platform Team",
+  type: :organization
+)
+
+puts "Created entities: Paula, Sarah, Microsoft, Platform Team"
+```
+
+## Extract Facts Manually
+
+```ruby
+# Create facts with explicit links
+fact1 = facts.fact_service.create(
+  "Paula Chen joined Microsoft as Principal Engineer",
+  valid_at: Date.parse("2024-01-10"),
+  mentions: [
+    { entity: paula, role: "subject", text: "Paula Chen" },
+    { entity: microsoft, role: "organization", text: "Microsoft" }
+  ],
+  sources: [
+    { content: email, type: "primary" }
+  ]
+)
+
+fact2 = facts.fact_service.create(
+  "Paula Chen reports to Sarah Johnson",
+  valid_at: Date.parse("2024-01-10"),
+  mentions: [
+    { entity: paula, role: "subject", text: "Paula Chen" },
+    { entity: sarah, role: "object", text: "Sarah Johnson" }
+  ],
+  sources: [
+    { content: email, type: "primary" }
+  ]
+)
+
+fact3 = facts.fact_service.create(
+  "Paula Chen is on the Platform Team",
+  valid_at: Date.parse("2024-01-10"),
+  mentions: [
+    { entity: paula, role: "subject", text: "Paula Chen" },
+    { entity: platform_team, role: "organization", text: "Platform Team" }
+  ],
+  sources: [
+    { content: email, type: "primary" }
+  ]
+)
+
+puts "Created #{3} facts"
+```
+
+## Extract Facts with LLM
+
+```ruby
+# Alternative: let LLM extract facts
+extracted = facts.extract_facts(email.id, extractor: :llm)
+
+puts "LLM extracted #{extracted.count} facts:"
+extracted.each do |fact|
+  puts "  - #{fact.fact_text}"
+end
+```
+
+## Query Facts
+
+```ruby
+# Current facts about Paula
+puts "\nCurrent facts about Paula:"
+facts.current_facts_for(paula.id).each do |fact|
+  puts "  - #{fact.fact_text}"
+end
+
+# Facts about Microsoft
+puts "\nFacts about Microsoft:"
+facts.query_facts(entity: microsoft.id).each do |fact|
+  puts "  - #{fact.fact_text}"
+end
+```
+
+## Resolve Entity
+
+```ruby
+# Resolve a name
+resolved = facts.resolve_entity("Paula")
+puts "\n'Paula' resolves to: #{resolved&.canonical_name}"
+
+# Type-constrained resolution
+person = facts.resolve_entity("Paula", type: :person)
+puts "'Paula' as person: #{person&.canonical_name}"
+```
+
+## Update Facts (Supersession)
+
+```ruby
+# Paula gets promoted
+new_fact = facts.fact_service.resolver.supersede(
+  fact1.id,
+  "Paula Chen is Senior Principal Engineer at Microsoft",
+  valid_at: Date.parse("2024-06-01")
+)
+
+puts "\nSuperseded fact:"
+puts "  Old: #{fact1.reload.fact_text} (#{fact1.status})"
+puts "  New: #{new_fact.fact_text} (#{new_fact.status})"
+```
+
+## Timeline
+
+```ruby
+# Build timeline
+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}"
+end
+```
+
+## Historical Query
+
+```ruby
+# 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}"
+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}"
+end
+```
+
+## Complete Script
+
+```ruby
+#!/usr/bin/env ruby
+require 'fact_db'
+
+# Setup
+FactDb.configure do |config|
+  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)
+
+# Create entities
+paula = facts.entity_service.create("Paula", type: :person)
+microsoft = facts.entity_service.create("Microsoft", type: :organization)
+
+# Create fact
+fact = facts.fact_service.create(
+  "Paula joined Microsoft",
+  valid_at: Date.parse("2024-01-10"),
+  mentions: [
+    { entity: paula, role: "subject", text: "Paula" },
+    { entity: microsoft, role: "organization", text: "Microsoft" }
+  ],
+  sources: [{ content: content, type: "primary" }]
+)
+
+# Query
+puts "Current facts about Paula:"
+facts.current_facts_for(paula.id).each { |f| puts "  - #{f.fact_text}" }
+```