Skip to content

Quick Start

Get FactDb running in 5 minutes.

1. Configure

Create a configuration file or use environment variables:

export FDB_DATABASE__URL="postgresql://localhost/fact_db"
export FDB_LLM__PROVIDER="openai"
export FDB_LLM__API_KEY="sk-..."

# config/fact_db.yml
database:
  url: postgresql://localhost/fact_db

llm:
  provider: openai
  api_key: <%= ENV['OPENAI_API_KEY'] %>

FactDb.configure do |config|
  config.database.url = "postgresql://localhost/fact_db"
  config.llm.provider = :openai
  config.llm.api_key = ENV['OPENAI_API_KEY']
end

2. Set Up Database

Run the migrations:

require 'fact_db'

FactDb.configure do |config|
  config.database.url = ENV['DATABASE_URL']
end

# Run migrations
FactDb::Database.migrate!

3. Create Your First Facts Instance

require 'fact_db'

facts = FactDb.new

4. Ingest Content

# Ingest an email
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.",
  kind: :email,
  title: "New Hire Announcement",
  captured_at: Time.current
)

puts "Ingested source: #{source.id}"

5. Create Entities

# Create entities for people and organizations
paula = facts.entity_service.create(
  "Paula Chen",
  kind: :person,
  aliases: ["Paula", "P. Chen"]
)

sarah = facts.entity_service.create(
  "Sarah Johnson",
  kind: :person,
  aliases: ["Sarah"]
)

platform_team = facts.entity_service.create(
  "Platform Team",
  kind: :organization
)

6. Extract Facts

Manual Extraction

fact = facts.fact_service.create(
  "Paula Chen joined as Principal Engineer",
  valid_at: Date.parse("2024-01-10"),
  mentions: [
    { entity: paula, role: "subject", text: "Paula Chen" }
  ],
  sources: [
    { source: source, type: "primary" }
  ]
)

LLM Extraction

# Extract facts automatically using LLM
extracted = facts.extract_facts(source.id, extractor: :llm)

extracted.each do |fact|
  puts "Extracted: #{fact.text}"
  puts "  Valid from: #{fact.valid_at}"
end

7. Query Facts

# Get current facts about Paula
current = facts.current_facts_for(paula.id)
current.each { |f| puts f.text }

# Get facts valid at a specific date
historical = facts.facts_at(
  Date.parse("2023-12-01"),
  entity: paula.id
)

# Search by topic
team_facts = facts.query_facts(topic: "Platform Team")

8. Build Timelines

timeline = facts.timeline_for(paula.id)

timeline.each do |entry|
  puts "#{entry[:date]}: #{entry[:fact].text}"
end

Complete Example

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
source = facts.ingest(
  "Paula Chen joined Microsoft as Principal Engineer on January 10, 2024.",
  kind: :announcement,
  captured_at: Time.current
)

# Create entities
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(source.id, extractor: :llm)

# Query
puts "Current facts about Paula:"
facts.current_facts_for(paula.id).each do |fact|
  puts "  - #{fact.text}"
end

Next Steps