fact_db 0.0.2 → 0.0.3

data/docs/guides/ingesting-content.md

@@ -16,8 +16,8 @@ content = facts.ingest(
 ## Full Options
 
 ```ruby
-content = facts.ingest(
-  raw_text,
+source = facts.ingest(
+  text_content,
   type: :email,
   title: "RE: Offer Letter - Paula Chen",
   source_uri: "mailto:hr@company.com/msg/12345",
@@ -89,12 +89,12 @@ Content is automatically deduplicated by SHA256 hash:
 
 ```ruby
 # First ingestion - creates new record
-content1 = facts.ingest("Hello world", type: :note)
+source1 = facts.ingest("Hello world", type: :note)
 
 # Second ingestion - returns existing record
-content2 = facts.ingest("Hello world", type: :note)
+source2 = facts.ingest("Hello world", type: :note)
 
-content1.id == content2.id  # => true
+source1.id == source2.id  # => true
 ```
 
 ## Timestamps
@@ -132,29 +132,29 @@ contents = documents.map do |doc|
 end
 ```
 
-## Content Service
+## Source Service
 
-For advanced operations, use the content service directly:
+For advanced operations, use the source service directly:
 
 ```ruby
-# Create content
-content = facts.content_service.create(
-  raw_text,
+# Create source
+source = facts.source_service.create(
+  text_content,
   type: :document,
   title: "Annual Report"
 )
 
 # Find by ID
-content = facts.content_service.find(content_id)
+source = facts.source_service.find(source_id)
 
 # Find by hash
-content = facts.content_service.find_by_hash(sha256_hash)
+source = facts.source_service.find_by_hash(sha256_hash)
 
 # Search by text
-results = facts.content_service.search("quarterly earnings")
+results = facts.source_service.search("quarterly earnings")
 
 # Semantic search (requires embedding)
-results = facts.content_service.semantic_search(
+results = facts.source_service.semantic_search(
   "financial performance",
   limit: 10
 )

data/docs/guides/llm-integration.md

@@ -18,9 +18,9 @@ gem 'ruby_llm'
 
     ```ruby
     FactDb.configure do |config|
-      config.llm_provider = :openai
-      config.llm_model = "gpt-4o-mini"
-      config.llm_api_key = ENV['OPENAI_API_KEY']
+      config.llm.provider = :openai
+      config.llm.model = "gpt-4o-mini"
+      config.llm.api_key = ENV['OPENAI_API_KEY']
     end
     ```
 
@@ -28,9 +28,9 @@ gem 'ruby_llm'
 
     ```ruby
     FactDb.configure do |config|
-      config.llm_provider = :anthropic
-      config.llm_model = "claude-sonnet-4-20250514"
-      config.llm_api_key = ENV['ANTHROPIC_API_KEY']
+      config.llm.provider = :anthropic
+      config.llm.model = "claude-sonnet-4-20250514"
+      config.llm.api_key = ENV['ANTHROPIC_API_KEY']
     end
     ```
 
@@ -38,9 +38,9 @@ gem 'ruby_llm'
 
     ```ruby
     FactDb.configure do |config|
-      config.llm_provider = :gemini
-      config.llm_model = "gemini-2.0-flash"
-      config.llm_api_key = ENV['GEMINI_API_KEY']
+      config.llm.provider = :gemini
+      config.llm.model = "gemini-2.0-flash"
+      config.llm.api_key = ENV['GEMINI_API_KEY']
     end
     ```
 
@@ -48,11 +48,19 @@ gem 'ruby_llm'
 
     ```ruby
     FactDb.configure do |config|
-      config.llm_provider = :ollama
-      config.llm_model = "llama3.2"
+      config.llm.provider = :ollama
+      config.llm.model = "llama3.2"
     end
     ```
 
+=== "Environment Variables"
+
+    ```bash
+    export FDB_LLM__PROVIDER=openai
+    export FDB_LLM__MODEL=gpt-4o-mini
+    export FDB_LLM__API_KEY=sk-...
+    ```
+
 ## Supported Providers
 
 | Provider | Models | Config Key |
@@ -85,20 +93,20 @@ PROVIDER_DEFAULTS = {
 facts = FactDb.new
 
 # Ingest content
-content = facts.ingest(
+source = facts.ingest(
   "Paula Chen joined Microsoft as Principal Engineer on January 10, 2024. She previously worked at Google for 5 years.",
   type: :announcement
 )
 
 # Extract facts using LLM
-extracted = facts.extract_facts(content.id, extractor: :llm)
+extracted = facts.extract_facts(source.id, extractor: :llm)
 
 extracted.each do |fact|
-  puts "Fact: #{fact.fact_text}"
+  puts "Fact: #{fact.text}"
   puts "  Valid: #{fact.valid_at}"
   puts "  Confidence: #{fact.confidence}"
   fact.entity_mentions.each do |m|
-    puts "  Entity: #{m.entity.canonical_name} (#{m.mention_role})"
+    puts "  Entity: #{m.entity.name} (#{m.mention_role})"
   end
 end
 ```
@@ -122,7 +130,7 @@ Extract temporal facts from this content. For each fact:
 4. Assess confidence level
 
 Content:
-{content.raw_text}
+{source.content}
 
 Return JSON:
 {
@@ -174,12 +182,12 @@ puts response
 
 ```ruby
 begin
-  extracted = facts.extract_facts(content.id, extractor: :llm)
+  extracted = facts.extract_facts(source.id, extractor: :llm)
 rescue FactDb::ConfigurationError => e
   # LLM not configured or ruby_llm missing
   puts "LLM Error: #{e.message}"
   # Fall back to rule-based
-  extracted = facts.extract_facts(content.id, extractor: :rule_based)
+  extracted = facts.extract_facts(source.id, extractor: :rule_based)
 rescue StandardError => e
   # API error, rate limit, etc.
   puts "Extraction failed: #{e.message}"
@@ -191,16 +199,16 @@ end
 Process multiple documents efficiently:
 
 ```ruby
-content_ids = [content1.id, content2.id, content3.id]
+source_ids = [content1.id, content2.id, content3.id]
 
 # Parallel processing (uses simple_flow pipeline)
-results = facts.batch_extract(content_ids, extractor: :llm, parallel: true)
+results = facts.batch_extract(source_ids, extractor: :llm, parallel: true)
 
 results.each do |result|
   if result[:error]
-    puts "Error for #{result[:content_id]}: #{result[:error]}"
+    puts "Error for #{result[:source_id]}: #{result[:error]}"
   else
-    puts "Extracted #{result[:facts].count} facts from #{result[:content_id]}"
+    puts "Extracted #{result[:facts].count} facts from #{result[:source_id]}"
   end
 end
 ```
@@ -211,17 +219,17 @@ end
 
 ```ruby
 # For simple extractions, use smaller models
-config.llm_model = "gpt-4o-mini"  # Cheaper than gpt-4o
+config.llm.model = "gpt-4o-mini"  # Cheaper than gpt-4o
 
 # For complex documents, use larger models
-config.llm_model = "gpt-4o"
+config.llm.model = "gpt-4o"
 ```
 
 ### Batch Processing
 
 ```ruby
 # Process in batches to reduce API calls
-content_ids.each_slice(10) do |batch|
+source_ids.each_slice(10) do |batch|
   facts.batch_extract(batch, extractor: :llm)
   sleep(1)  # Rate limiting
 end
@@ -232,8 +240,8 @@ end
 ```ruby
 # Use Ollama for development/testing
 FactDb.configure do |config|
-  config.llm_provider = :ollama
-  config.llm_model = "llama3.2"
+  config.llm.provider = :ollama
+  config.llm.model = "llama3.2"
 end
 ```
 
@@ -259,7 +267,7 @@ end
 ### 1. Validate Extractions
 
 ```ruby
-extracted = facts.extract_facts(content.id, extractor: :llm)
+extracted = facts.extract_facts(source.id, extractor: :llm)
 
 extracted.each do |fact|
   # Flag low-confidence extractions
@@ -273,9 +281,9 @@ end
 
 ```ruby
 # Cache LLM responses for repeated content
-cache_key = "llm_extraction:#{content.content_hash}"
+cache_key = "llm_extraction:#{source.content_hash}"
 extracted = Rails.cache.fetch(cache_key) do
-  facts.extract_facts(content.id, extractor: :llm)
+  facts.extract_facts(source.id, extractor: :llm)
 end
 ```
 
@@ -285,7 +293,7 @@ end
 require 'retryable'
 
 Retryable.retryable(tries: 3, sleep: 5) do
-  facts.extract_facts(content.id, extractor: :llm)
+  facts.extract_facts(source.id, extractor: :llm)
 end
 ```
 
@@ -293,7 +301,7 @@ end
 
 ```ruby
 # Track extraction statistics
-extracted = facts.extract_facts(content.id, extractor: :llm)
+extracted = facts.extract_facts(source.id, extractor: :llm)
 StatsD.increment('fact_db.llm_extractions')
 StatsD.histogram('fact_db.facts_per_content', extracted.count)
 ```

data/docs/guides/temporal-queries.md

@@ -66,7 +66,7 @@ timeline = facts.timeline_for(paula.id)
 
 timeline.each do |fact|
   range = fact.invalid_at ? "#{fact.valid_at} - #{fact.invalid_at}" : "#{fact.valid_at} - present"
-  puts "#{range}: #{fact.fact_text}"
+  puts "#{range}: #{fact.text}"
 end
 
 # Timeline for specific period
@@ -196,7 +196,7 @@ similar_about_paula = facts.fact_service.semantic_search(
 ```ruby
 fact = facts.query_facts(entity: paula.id).first
 
-fact.fact_text        # The assertion text
+fact.text        # The assertion text
 fact.valid_at         # When it became true
 fact.invalid_at       # When it stopped (nil if current)
 fact.status           # canonical, superseded, etc.
@@ -210,26 +210,26 @@ fact.metadata         # Additional data
 ```ruby
 # Entity mentions
 fact.entity_mentions.each do |mention|
-  puts "#{mention.entity.canonical_name} (#{mention.mention_role})"
+  puts "#{mention.entity.name} (#{mention.mention_role})"
 end
 
 # Source content
-fact.fact_sources.each do |source|
-  puts "Source: #{source.content.title}"
-  puts "Excerpt: #{source.excerpt}"
+fact.fact_sources.each do |fact_source|
+  puts "Source: #{fact_source.source.title}"
+  puts "Excerpt: #{fact_source.excerpt}"
 end
 
 # Superseding fact
 if fact.superseded?
   new_fact = fact.superseded_by
-  puts "Superseded by: #{new_fact.fact_text}"
+  puts "Superseded by: #{new_fact.text}"
 end
 
 # Source facts (for synthesized)
 if fact.synthesized?
   fact.derived_from_ids.each do |id|
     source = FactDb::Models::Fact.find(id)
-    puts "Derived from: #{source.fact_text}"
+    puts "Derived from: #{source.text}"
   end
 end
 ```
@@ -295,7 +295,7 @@ all_facts = FactDb::Models::Fact
 
 all_facts.each do |fact|
   status_info = fact.superseded? ? "(superseded)" : "(current)"
-  puts "#{fact.valid_at}: #{fact.fact_text} #{status_info}"
+  puts "#{fact.valid_at}: #{fact.text} #{status_info}"
 end
 ```
 
@@ -309,7 +309,7 @@ recently_superseded = FactDb::Models::Fact
   .includes(:superseded_by)
 
 recently_superseded.each do |old_fact|
-  puts "Changed: #{old_fact.fact_text}"
-  puts "To: #{old_fact.superseded_by.fact_text}"
+  puts "Changed: #{old_fact.text}"
+  puts "To: #{old_fact.superseded_by.text}"
 end
 ```

data/docs/index.md

@@ -34,14 +34,14 @@ require 'fact_db'
 facts = FactDb.new
 
 # Ingest content
-content = facts.ingest(
+source = facts.ingest(
   "Paula Chen joined Microsoft as Principal Engineer on January 10, 2024.",
   type: :email,
   captured_at: Time.current
 )
 
 # Extract facts using LLM
-extracted = facts.extract_facts(content.id, extractor: :llm)
+extracted = facts.extract_facts(source.id, extractor: :llm)
 
 # Query current facts about Paula
 current_facts = facts.query_facts(entity: paula.id)
@@ -110,6 +110,10 @@ bundle install
 
 See the [Installation Guide](getting-started/installation.md) for detailed setup instructions.
 
+## API Documentation
+
+API documentation (YARD) is available at **[https://madbomber.github.io/fact_db/yard](https://madbomber.github.io/fact_db/yard)**
+
 ## Requirements
 
 - Ruby >= 3.0

data/examples/.envrc

@@ -0,0 +1,4 @@
+
+source_up
+
+export FDB_ENV=demo

data/examples/.gitignore

@@ -0,0 +1 @@
+*.log

data/examples/001_configuration.rb

@@ -0,0 +1,312 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Conventions? bah-humbug;  Configure everything!!
+#
+# Configuration Example for FactDb
+#
+# This example demonstrates all the ways to configure FactDb:
+# - Bundled defaults (shipped with the gem)
+# - Environment variables (FDB_*)
+# - XDG user config files (~/.config/fact_db/fact_db.yml)
+# - Project config files (./config/fact_db.yml)
+# - Local overrides (./config/fact_db.local.yml)
+# - Programmatic configuration blocks
+#
+# Configuration priority (lowest to highest):
+# 1. Bundled defaults
+# 2. XDG user config
+# 3. Project config
+# 4. Local overrides
+# 5. Environment variables
+# 6. Programmatic (FactDb.configure block)
+
+require_relative "utilities"
+
+demo_setup!("FactDb Configuration Demo")
+
+demo_section("Section 1: Current Environment")
+
+puts <<~ENV_DETECTION
+  Environment detection priority: FDB_ENV > RAILS_ENV > RACK_ENV > 'development'
+    FDB_ENV:   #{ENV['FDB_ENV'].inspect}
+    RAILS_ENV: #{ENV['RAILS_ENV'].inspect}
+    RACK_ENV:  #{ENV['RACK_ENV'].inspect}
+    Detected:  #{FactDb.env}
+ENV_DETECTION
+
+# Environment helper methods
+config = FactDb.config
+
+puts <<~ENV_HELPERS
+
+  Environment helpers:
+    config.environment:  #{config.environment}
+    config.production?:  #{config.production?}
+    config.development?: #{config.development?}
+    config.test?:        #{config.test?}
+    config.demo?:        #{config.demo?}
+ENV_HELPERS
+
+demo_section("Section 2: Configuration File Locations")
+
+defaults_path = File.expand_path("../lib/fact_db/config/defaults.yml", __dir__)
+
+puts <<~CONFIG_SOURCES
+  Configuration sources (lowest to highest priority):
+
+  1. Bundled defaults (ships with gem):
+     #{defaults_path}
+
+  2. XDG user config paths (checked in order):
+CONFIG_SOURCES
+
+FactDb::Config.xdg_config_paths.each_with_index do |path, i|
+  file_path = File.join(path, "fact_db.yml")
+  exists = File.exist?(file_path)
+  status = exists ? "(exists)" : "(not found)"
+  puts "     #{i + 1}. #{file_path} #{status}"
+end
+
+active_xdg = FactDb::Config.active_xdg_config_file
+
+puts <<~MORE_SOURCES
+
+     Active XDG config: #{active_xdg || '(none)'}
+
+  3. Project config:  ./config/fact_db.yml
+     Exists: #{File.exist?('./config/fact_db.yml')}
+
+  4. Local overrides: ./config/fact_db.local.yml (typically gitignored)
+     Exists: #{File.exist?('./config/fact_db.local.yml')}
+
+  5. Environment variables: FDB_* (see Section 4)
+
+  6. Programmatic: FactDb.configure { |c| ... } (see Section 5)
+MORE_SOURCES
+
+demo_section("Section 3: Accessing Configuration Values")
+
+puts <<~DATABASE_CONFIG
+  Database configuration (ConfigSection with dot notation):
+    config.database.adapter:  #{config.database.adapter.inspect}
+    config.database.url:      #{config.database.url.inspect}
+    config.database.host:     #{config.database.host.inspect}
+    config.database.port:     #{config.database.port.inspect}
+    config.database.name:     #{config.database.name.inspect}
+    config.database.username: #{config.database.username.inspect}
+    config.database.pool:     #{config.database.pool.inspect}
+    config.database.timeout:  #{config.database.timeout.inspect}
+
+  LLM configuration:
+    config.llm.provider: #{config.llm.provider.inspect}
+    config.llm.model:    #{config.llm.model.inspect}
+    config.llm.api_key:  #{config.llm.api_key ? '[REDACTED]' : 'nil'}
+
+  Embedding configuration:
+    config.embedding.generator:  #{config.embedding.generator.inspect}
+    config.embedding.dimensions: #{config.embedding.dimensions.inspect}
+
+  Ranking weights (for relevance scoring):
+    config.ranking.ts_rank_weight:            #{config.ranking.ts_rank_weight}
+    config.ranking.vector_similarity_weight:  #{config.ranking.vector_similarity_weight}
+    config.ranking.entity_mention_weight:     #{config.ranking.entity_mention_weight}
+    config.ranking.direct_answer_weight:      #{config.ranking.direct_answer_weight}
+    config.ranking.term_overlap_weight:       #{config.ranking.term_overlap_weight}
+    config.ranking.relationship_match_weight: #{config.ranking.relationship_match_weight}
+    config.ranking.confidence_weight:         #{config.ranking.confidence_weight}
+
+  General settings:
+    config.default_extractor:     #{config.default_extractor.inspect}
+    config.fuzzy_match_threshold: #{config.fuzzy_match_threshold}
+    config.auto_merge_threshold:  #{config.auto_merge_threshold}
+    config.log_level:             #{config.log_level.inspect}
+DATABASE_CONFIG
+
+demo_section("Section 4: Environment Variables")
+
+puts <<~ENV_VARS
+  Environment variables use the FDB_ prefix with double underscores for nesting.
+  They have the HIGHEST priority (except for programmatic config).
+
+  Examples:
+    # Environment selection
+    export FDB_ENV=production
+
+    # Database configuration
+    export FDB_DATABASE__URL=postgresql://user:pass@localhost:5432/fact_db
+    export FDB_DATABASE__NAME=my_fact_db
+    export FDB_DATABASE__HOST=db.example.com
+    export FDB_DATABASE__PORT=5432
+    export FDB_DATABASE__USERNAME=dbuser
+    export FDB_DATABASE__PASSWORD=secret
+    export FDB_DATABASE__POOL=10
+
+    # LLM configuration
+    export FDB_LLM__PROVIDER=anthropic
+    export FDB_LLM__MODEL=claude-sonnet-4-20250514
+    export FDB_LLM__API_KEY=sk-xxx
+
+    # Embedding configuration
+    export FDB_EMBEDDING__DIMENSIONS=1536
+
+    # Ranking weights
+    export FDB_RANKING__TS_RANK_WEIGHT=0.30
+    export FDB_RANKING__VECTOR_SIMILARITY_WEIGHT=0.25
+
+    # General settings
+    export FDB_DEFAULT_EXTRACTOR=llm
+    export FDB_FUZZY_MATCH_THRESHOLD=0.80
+    export FDB_LOG_LEVEL=debug
+
+  Currently set FDB_* environment variables:
+ENV_VARS
+
+fdb_vars = ENV.select { |k, _| k.start_with?("FDB_") }
+if fdb_vars.empty?
+  puts "    (none)"
+else
+  fdb_vars.each do |key, value|
+    display_value = key.include?("KEY") || key.include?("PASSWORD") ? "[REDACTED]" : value
+    puts "    #{key}=#{display_value}"
+  end
+end
+
+demo_section("Section 5: Programmatic Configuration")
+
+# Reset configuration to show before/after
+FactDb.reset_configuration!
+
+puts <<~PROGRAMMATIC_INTRO
+  Use FactDb.configure to set values programmatically.
+  This has the HIGHEST priority and overrides all other sources.
+
+  Before programmatic configuration:
+    log_level: #{FactDb.config.log_level.inspect}
+    fuzzy_match_threshold: #{FactDb.config.fuzzy_match_threshold}
+PROGRAMMATIC_INTRO
+
+# Apply programmatic configuration
+FactDb.configure do |c|
+  # Scalar values
+  c.log_level = :debug
+  c.fuzzy_match_threshold = 0.75
+  c.default_extractor = :llm
+
+  # Callable objects (not loaded from config files)
+  c.logger = Logger.new($stdout, level: Logger::WARN)
+
+  # Custom embedding generator (lambda or object responding to #call)
+  # c.embedding_generator = ->(text) { OpenAI.embed(text) }
+
+  # Custom LLM client
+  # c.llm_client = MyCustomLLMClient.new
+end
+
+puts <<~AFTER_PROGRAMMATIC
+
+  After programmatic configuration:
+    log_level: #{FactDb.config.log_level.inspect}
+    fuzzy_match_threshold: #{FactDb.config.fuzzy_match_threshold}
+    default_extractor: #{FactDb.config.default_extractor.inspect}
+    logger: #{FactDb.config.logger.class}
+AFTER_PROGRAMMATIC
+
+demo_section("Section 6: Config File Examples")
+
+puts <<~CONFIG_FILES
+  XDG User Config (~/.config/fact_db/fact_db.yml):
+    ---
+    # User-wide defaults (applies to all projects)
+    database:
+      host: localhost
+      username: myuser
+
+    llm:
+      provider: anthropic
+      api_key: sk-my-api-key  # Or use FDB_LLM__API_KEY env var
+
+    embedding:
+      dimensions: 1536
+
+  Project Config (./config/fact_db.yml):
+    ---
+    # Environment-specific configuration
+    development:
+      database:
+        name: myapp_development
+      log_level: debug
+
+    test:
+      database:
+        name: myapp_test
+        pool: 2
+      log_level: warn
+
+    production:
+      database:
+        name: myapp_production
+        pool: 25
+      log_level: info
+      fuzzy_match_threshold: 0.90
+
+  Local Overrides (./config/fact_db.local.yml):
+    ---
+    # Personal overrides (gitignored)
+    # Great for API keys and local database credentials
+    llm:
+      api_key: sk-my-personal-key
+
+    database:
+      password: my_local_password
+CONFIG_FILES
+
+demo_section("Section 7: Database Configuration")
+
+puts <<~DATABASE_INFO
+  Database configuration uses 'name' for the database name.
+  When passed to ActiveRecord, it's automatically mapped to 'database'.
+
+  Current database config:
+    Name: #{FactDb.config.database.name}
+    Host: #{FactDb.config.database.host}
+    Port: #{FactDb.config.database.port}
+    Pool: #{FactDb.config.database.pool}
+
+  Full config hash (for ActiveRecord):
+    #{FactDb.config.database.to_h.inspect}
+DATABASE_INFO
+
+demo_section("Section 8: Quick Reference")
+
+puts <<~REFERENCE
+  Environment Variables:
+    FDB_ENV                         - Set environment (development/test/production)
+    FDB_DATABASE__URL               - Full database connection URL
+    FDB_DATABASE__NAME              - Database name
+    FDB_LLM__PROVIDER               - LLM provider (anthropic/openai)
+    FDB_LLM__API_KEY                - API key for LLM
+
+  Config Files (in priority order):
+    lib/fact_db/config/defaults.yml - Bundled defaults (lowest)
+    ~/.config/fact_db/fact_db.yml   - XDG user config
+    ./config/fact_db.yml            - Project config
+    ./config/fact_db.local.yml      - Local overrides (gitignored)
+
+  Ruby API:
+    FactDb.env                      - Current environment name
+    FactDb.config                   - Configuration object
+    FactDb.configure { |c| ... }    - Programmatic configuration
+    FactDb.reset_configuration!     - Reload from all sources
+
+  Config Sections (ConfigSection with dot notation):
+    config.database                 - Database configuration
+    config.database.host            - Dot notation access
+    config.database[:host]          - Hash bracket access
+    config.database.to_h            - Convert to plain Hash
+    config.llm                      - LLM configuration
+    config.embedding                - Embedding configuration
+    config.ranking                  - Ranking weights
+REFERENCE
+
+demo_footer("Configuration Demo Complete!")