fact_db 0.0.2 → 0.0.3

data/lib/fact_db/config/defaults.yml

@@ -0,0 +1,254 @@
+# FactDb Bundled Defaults
+#
+# This file is the SINGLE SOURCE OF TRUTH for FactDb configuration schema.
+# All attributes must be declared here (even if nil) to be recognized.
+# It is bundled with the gem and loaded automatically at lowest priority.
+#
+# Loading priority (lowest to highest):
+# 1. This file (bundled defaults)
+# 2. XDG user config (~/.config/fact_db/fact_db.yml)
+# 3. Project config (./config/fact_db.yml)
+# 4. Local overrides (./config/fact_db.local.yml)
+# 5. Environment variables (FDB_*)
+# 6. Programmatic (FactDb.configure block)
+#
+# Structure:
+# - defaults: Base values for all environments (with nested sections)
+# - development: Overrides for development environment
+# - test: Overrides for test environment
+# - production: Overrides for production environment
+# - demo: Overrides for demo/staging environment
+#
+# Custom Environments:
+# Your application's config file (./config/fact_db.yml) can define additional
+# environments to suit your infrastructure. For example:
+#   staging:
+#     database:
+#       name: myapp_staging
+#   qa:
+#     database:
+#       name: myapp_qa
+#
+# Environment helper methods (e.g., config.staging?, config.qa?) are
+# automatically generated for any environment defined in configuration files.
+#
+# Access pattern:
+#   FactDb.config.database.url
+#   FactDb.config.database.pool
+#   FactDb.config.llm.provider
+#   FactDb.config.ranking.ts_rank_weight
+
+# =============================================================================
+# Shared Defaults (base for all environments)
+# =============================================================================
+defaults:
+  # ---------------------------------------------------------------------------
+  # Database Configuration (ActiveRecord-compatible keys)
+  # Access: FactDb.config.database.url, FactDb.config.database.pool, etc.
+  # ---------------------------------------------------------------------------
+  database:
+    adapter: postgresql
+    url: ~
+    host: localhost
+    port: 5432
+    name: fact_db_demo
+    username: ~
+    password: ~
+    pool: 5
+    timeout: 30000
+    encoding: "unicode"
+    prepared_statements: false
+    advisory_locks: false
+
+  # ---------------------------------------------------------------------------
+  # Embedding Configuration
+  # Access: FactDb.config.embedding.generator, FactDb.config.embedding.dimensions
+  # ---------------------------------------------------------------------------
+  embedding:
+    generator: ~
+    dimensions: 1536
+
+  # ---------------------------------------------------------------------------
+  # LLM Configuration
+  # Access: FactDb.config.llm.provider, FactDb.config.llm.model, etc.
+  # ---------------------------------------------------------------------------
+  llm:
+    client: ~
+    provider: ~
+    model: ~
+    api_key: ~
+
+  # ---------------------------------------------------------------------------
+  # Ranking Signal Weights
+  # Access: FactDb.config.ranking.ts_rank_weight, etc.
+  # Weights should sum to approximately 1.0 for normalized scores
+  # ---------------------------------------------------------------------------
+  ranking:
+    ts_rank_weight: 0.25
+    vector_similarity_weight: 0.25
+    entity_mention_weight: 0.15
+    direct_answer_weight: 0.15
+    term_overlap_weight: 0.10
+    relationship_match_weight: 0.05
+    confidence_weight: 0.05
+
+  # ---------------------------------------------------------------------------
+  # General Settings
+  # Access: FactDb.config.default_extractor, FactDb.config.log_level, etc.
+  # ---------------------------------------------------------------------------
+  default_extractor: manual
+  fuzzy_match_threshold: 0.85
+  auto_merge_threshold: 0.95
+  log_level: info
+
+  # ---------------------------------------------------------------------------
+  # LLM Prompts
+  # Access: FactDb.config.prompts.fact_extraction, FactDb.config.prompts.entity_extraction
+  # These prompts use %<text>s as a placeholder for the input text.
+  # ---------------------------------------------------------------------------
+  prompts:
+    fact_extraction: |
+      Extract ATOMIC factual assertions from the following text. Break compound
+      statements into individual, indivisible facts - one assertion per fact.
+
+      For each atomic fact:
+      1. State a single, indivisible assertion (not multiple facts combined)
+      2. Identify when it became true (valid_at) if mentioned or inferable
+      3. Identify when it stopped being true (invalid_at) if mentioned
+      4. Identify entities mentioned (people, organizations, places, products)
+      5. Assign a confidence score (0.0 to 1.0) based on how explicitly stated the fact is
+      6. For each entity, include any aliases or alternative names used in the text
+
+      Text:
+      %<text>s
+
+      Return as a JSON array with this structure:
+      [
+        {
+          "text": "Paula works at Microsoft",
+          "valid_at": "2024-01-10",
+          "invalid_at": null,
+          "confidence": 0.95,
+          "mentions": [
+            {"name": "Paula Chen", "type": "person", "role": "subject", "aliases": ["Paula", "P. Chen"]},
+            {"name": "Microsoft", "type": "organization", "role": "object", "aliases": ["MS", "Microsoft Corporation"]}
+          ]
+        },
+        {
+          "text": "Paula holds the title of Principal Engineer",
+          "valid_at": "2024-01-10",
+          "invalid_at": null,
+          "confidence": 0.95,
+          "mentions": [
+            {"name": "Paula Chen", "type": "person", "role": "subject", "aliases": ["Paula", "P. Chen"]}
+          ]
+        }
+      ]
+
+      Rules:
+      - ATOMIC FACTS: Break compound statements into smallest meaningful assertions
+        - "John and Mary married in Paris" becomes TWO facts: "John married Mary" AND "The marriage took place in Paris"
+        - "She is a doctor at City Hospital" becomes TWO facts: "She is a doctor" AND "She works at City Hospital"
+      - Extract only factual assertions, not opinions or speculation
+      - Use ISO 8601 date format (YYYY-MM-DD) when possible
+      - Set invalid_at to null if the fact is still true or unknown
+      - Set valid_at to null if the timing is not mentioned
+      - Entity types (use ONLY these exact values):
+        - person: individual humans
+        - organization: companies, governments, institutions, teams, groups
+        - place: cities, countries, buildings, geographic locations
+        - product: goods, services, software, publications
+        - event: wars, battles, elections, conferences, treaties, historical events
+        - concept: ideas, theories, abstract notions, fields of study
+      - Roles: subject, object, location, temporal, instrument, beneficiary
+      - For person entities, use the most complete/formal name as "name" and shorter/alternative forms as "aliases"
+      - Common aliases include: nicknames, titles with name, name variations, abbreviations
+      - NEVER include pronouns as aliases (he, she, him, her, they, them, his, her, their, it, we, you, I, me, my, etc.)
+      - NEVER include generic terms as aliases (man, woman, person, husband, wife, the man, this person, etc.)
+      - Only include proper names, nicknames, and formal variations as aliases
+
+      Return only valid JSON, no additional text.
+
+    entity_extraction: |
+      Extract all named entities from the following text.
+      For each entity:
+      1. Identify the canonical name
+      2. Classify the type using ONLY these exact values:
+         - person: individual humans
+         - organization: companies, governments, institutions, teams, groups
+         - place: cities, countries, buildings, geographic locations
+         - product: goods, services, software, publications
+         - event: wars, battles, elections, conferences, treaties, historical events
+         - concept: ideas, theories, abstract notions, fields of study
+      3. List any aliases or alternative names mentioned
+
+      Text:
+      %<text>s
+
+      Return as a JSON array:
+      [
+        {
+          "name": "Paula Chen",
+          "type": "person",
+          "aliases": ["Paula", "P. Chen"]
+        }
+      ]
+
+      Important rules for aliases:
+      - NEVER include pronouns (he, she, him, her, they, them, his, her, their, it, we, you, I, me, my, etc.)
+      - NEVER include generic terms (man, woman, person, husband, wife, the man, this person, believers, disciples, etc.)
+      - Only include proper names, nicknames, titles, and formal name variations
+
+      Return only valid JSON, no additional text.
+
+    rag_system: |
+      You are a knowledgeable assistant with access to a fact database. Use the provided context to inform your response, but also feel free to synthesize and expand upon the information with related knowledge.
+
+      Your response should:
+      1. Directly address the user's question
+      2. Include specific facts, names, dates, and details where relevant
+      3. Make connections between related pieces of information
+      4. Present information in clear, atomic statements that can be extracted as individual facts
+
+# =============================================================================
+# Development Environment Overrides
+# =============================================================================
+development:
+  database:
+    name: fact_db_development
+  log_level: debug
+
+# =============================================================================
+# Test Environment Overrides
+# =============================================================================
+test:
+  database:
+    name: fact_db_test
+    pool: 2
+    timeout: 5000
+  log_level: warn
+
+# =============================================================================
+# Production Environment Overrides
+# =============================================================================
+production:
+  database:
+    name: fact_db_production
+    pool: 10
+    timeout: 60000
+  log_level: warn
+
+# =============================================================================
+# Demo Environment Overrides
+# =============================================================================
+demo:
+  database:
+    name: fact_db_demo
+    pool: 3
+  log_level: info
+
+# -----------------------------------------------------------------------------
+# Add your own environments for your project's infrastructure
+# -----------------------------------------------------------------------------
+# qa:
+# staging:

data/lib/fact_db/config.rb

@@ -1,60 +1,119 @@
 # frozen_string_literal: true
 
-require "anyway_config"
+require "myway_config"
 require "logger"
 
+# Configure MywayConfig to use FDB_ENV for environment detection
+Anyway::Settings.current_environment = ENV["FDB_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+
 module FactDb
-  class Config < Anyway::Config
+  # FactDb Configuration using MywayConfig
+  #
+  # Schema is defined in lib/fact_db/config/defaults.yml (single source of truth)
+  #
+  # All config sections return ConfigSections with symbol keys:
+  #   FactDb.config.database  # => ConfigSection with {adapter: "postgresql", host: "localhost", ...}
+  #   FactDb.config.llm       # => ConfigSection with {provider: :anthropic, model: "claude-...", ...}
+  #   FactDb.config.embedding # => ConfigSection with {generator: nil, dimensions: 1536}
+  #   FactDb.config.ranking   # => ConfigSection with {ts_rank_weight: 0.25, ...}
+  #
+  # Access values via hash keys or dot notation:
+  #   FactDb.config.database[:host]
+  #   FactDb.config.database.host
+  #   FactDb.config.llm[:provider]
+  #   FactDb.config.llm.provider
+  #
+  # Configuration sources (lowest to highest priority):
+  # 1. Bundled defaults: lib/fact_db/config/defaults.yml (ships with gem)
+  # 2. XDG user config:
+  #    - ~/Library/Application Support/fact_db/fact_db.yml (macOS only)
+  #    - ~/.config/fact_db/fact_db.yml (XDG default)
+  #    - $XDG_CONFIG_HOME/fact_db/fact_db.yml (if XDG_CONFIG_HOME is set)
+  # 3. Project config: ./config/fact_db.yml (environment-specific)
+  # 4. Local overrides: ./config/fact_db.local.yml (gitignored)
+  # 5. Environment variables (FDB_*)
+  # 6. Explicit values passed to configure block
+  #
+  # @example Configure with environment variables
+  #   export FDB_DATABASE__URL=postgresql://localhost/fact_db_development
+  #   export FDB_LLM__PROVIDER=openai
+  #   export FDB_LLM__API_KEY=sk-xxx
+  #
+  # @example Configure with Ruby block
+  #   FactDb.configure do |config|
+  #     config.llm[:provider] = :openai
+  #     config.llm[:model] = "gpt-4o-mini"
+  #   end
+  #
+  class Config < MywayConfig::Base
     config_name :fact_db
+    env_prefix :fdb
+    defaults_path File.expand_path("config/defaults.yml", __dir__)
+    auto_configure!
 
-    # Database configuration
-    attr_config :database_url
-    attr_config database_pool_size: 5,
-                database_timeout: 30_000
-
-    # Embedding configuration
-    attr_config :embedding_generator
-    attr_config embedding_dimensions: 1536
-
-    # LLM configuration
-    attr_config :llm_client, :llm_provider, :llm_model, :llm_api_key
+    # ==========================================================================
+    # Callable Accessors (not loaded from config sources)
+    # ==========================================================================
 
-    # Extraction configuration
-    attr_config default_extractor: :manual
+    attr_accessor :embedding_generator, :llm_client, :logger
 
-    # Entity resolution thresholds
-    attr_config fuzzy_match_threshold: 0.85,
-                auto_merge_threshold: 0.95
+    # ==========================================================================
+    # Callbacks
+    # ==========================================================================
 
-    # Logging
-    attr_config :logger
-    attr_config log_level: :info
+    on_load :setup_defaults
 
-    # Build LLM client from configuration if not explicitly set
-    def llm_client
-      return super if super
+    # ==========================================================================
+    # XDG Config Path Helpers
+    # ==========================================================================
 
-      return nil unless llm_provider
+    def self.xdg_config_paths
+      MywayConfig::Loaders::XdgConfigLoader.config_paths(:fact_db)
+    end
 
-      @llm_client ||= LLM::Adapter.new(
-        provider: llm_provider.to_sym,
-        model: llm_model,
-        api_key: llm_api_key
-      )
+    def self.xdg_config_file
+      xdg_home = ENV["XDG_CONFIG_HOME"]
+      base = if xdg_home && !xdg_home.empty?
+        xdg_home
+      else
+        File.expand_path("~/.config")
+      end
+      File.join(base, "fact_db", "fact_db.yml")
     end
 
-    def logger
-      super || Logger.new($stdout, level: log_level)
+    def self.active_xdg_config_file
+      MywayConfig::Loaders::XdgConfigLoader.find_config_file(:fact_db)
     end
 
-    def validate!
-      raise ConfigurationError, "Database URL required" unless database_url
+    private
+
+    def setup_defaults
+      @logger ||= build_default_logger
+    end
 
-      self
+    def build_default_logger
+      logger = Logger.new($stdout)
+      logger.level = log_level || :info
+      logger.formatter = proc do |severity, datetime, _progname, msg|
+        "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity} -- FactDb: #{msg}\n"
+      end
+      logger
     end
   end
 
+  # ==========================================================================
+  # Module-level Configuration API
+  # ==========================================================================
+
   class << self
+    def env
+      @env ||= ENV.fetch("FDB_ENV") { ENV.fetch("RAILS_ENV") { ENV.fetch("RACK_ENV", "development") } }
+    end
+
+    def env=(value)
+      @env = value.to_s
+    end
+
     def config
       @config ||= Config.new
     end

data/lib/fact_db/database.rb

@@ -4,43 +4,133 @@ require "active_record"
 require "neighbor"
 
 module FactDb
+  # Database management module for FactDb
+  #
+  # Provides class methods for establishing database connections, running
+  # migrations, and managing database lifecycle (create, drop, reset).
+  #
+  # @example Establish connection and run migrations
+  #   FactDb::Database.establish_connection!
+  #   FactDb::Database.migrate!
+  #
+  # @example Reset database for testing
+  #   FactDb::Database.reset!
+  #
   module Database
     class << self
+      # Establishes an ActiveRecord database connection
+      #
+      # Uses configuration from FactDb.config by default. Sets up the logger
+      # if configured.
+      #
+      # @param config [FactDb::Config] configuration object (defaults to FactDb.config)
+      # @return [void]
       def establish_connection!(config = FactDb.config)
-        config.validate!
-        ActiveRecord::Base.establish_connection(config.database_url)
+        # config.database is a ConfigSection - convert to AR-compatible hash
+        ActiveRecord::Base.establish_connection(ar_connection_hash(config.database))
         ActiveRecord::Base.logger = config.logger if config.logger
       end
 
+      # Checks if a database connection is established
+      #
+      # @return [Boolean] true if connected to database
       def connected?
         ActiveRecord::Base.connected?
       end
 
+      # Drops the database
+      #
+      # Disconnects from the current database, connects to postgres maintenance
+      # database, and drops the configured database.
+      #
+      # @return [void]
+      def drop!
+        db_name = FactDb.config.database.name
+        ActiveRecord::Base.connection.disconnect! if connected?
+        ActiveRecord::Base.establish_connection(maintenance_database_url)
+        ActiveRecord::Base.connection.drop_database(db_name)
+        puts "Dropped database '#{db_name}'"
+      end
+
+      # Creates the database
+      #
+      # Connects to postgres maintenance database and creates the configured database.
+      #
+      # @return [void]
+      def create!
+        db_name = FactDb.config.database.name
+        ActiveRecord::Base.establish_connection(maintenance_database_url)
+        ActiveRecord::Base.connection.create_database(db_name)
+        puts "Created database '#{db_name}'"
+      end
+
+      # Runs all pending migrations
+      #
+      # Establishes connection if needed and runs migrations from db/migrate.
+      #
+      # @return [void]
       def migrate!
-        establish_connection! unless connected?
+        establish_connection!
         migrations_path = File.expand_path("../../db/migrate", __dir__)
         ActiveRecord::MigrationContext.new(migrations_path).migrate
       end
 
+      # Rolls back migrations
+      #
+      # @param steps [Integer] number of migrations to rollback (default: 1)
+      # @return [void]
       def rollback!(steps = 1)
         establish_connection! unless connected?
         migrations_path = File.expand_path("../../db/migrate", __dir__)
         ActiveRecord::MigrationContext.new(migrations_path).rollback(steps)
       end
 
+      # Drops, creates, and migrates the database
+      #
+      # Convenience method to completely reset the database to a clean state.
+      # Ignores errors when dropping (database may not exist).
+      #
+      # @return [void]
       def reset!
-        establish_connection! unless connected?
-        ActiveRecord::Base.connection.tables.each do |table|
-          next if table == "schema_migrations"
-          ActiveRecord::Base.connection.drop_table(table, if_exists: true, force: :cascade)
-        end
+        drop! rescue nil
+        create!
         migrate!
       end
 
+      # Returns the current schema version
+      #
+      # @return [Integer] the latest migration version number, or 0 if no migrations
       def schema_version
         establish_connection! unless connected?
         ActiveRecord::SchemaMigration.all.map(&:version).max || 0
       end
+
+      private
+
+      def maintenance_database_url
+        db = FactDb.config.database
+        url = db.url || build_database_url(db, "postgres")
+        uri = URI.parse(url)
+        uri.path = "/postgres"
+        uri.to_s
+      end
+
+      def build_database_url(db, database_name = nil)
+        host = db.host || "localhost"
+        port = db.port || 5432
+        name = database_name || db.name
+        user = db.username || ENV["USER"]
+
+        auth = user ? "#{user}@" : ""
+        "postgresql://#{auth}#{host}:#{port}/#{name}"
+      end
+
+      # Convert config to AR-compatible hash (name -> database)
+      def ar_connection_hash(db)
+        h = db.to_h
+        h[:database] = h.delete(:name) if h[:name] && !h[:database]
+        h
+      end
     end
   end
 end