fact_db 0.0.1

data/lib/fact_db/extractors/manual_extractor.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Extractors
+    class ManualExtractor < Base
+      # Manual extraction passes through the text as a single fact
+      # This is used for API-driven fact creation where the user
+      # provides the fact text and metadata directly
+      def extract(text, context = {})
+        return [] if text.nil? || text.strip.empty?
+
+        valid_at = context[:valid_at] || context[:captured_at] || Time.current
+
+        [
+          build_fact(
+            text: text,
+            valid_at: valid_at,
+            invalid_at: context[:invalid_at],
+            mentions: context[:mentions] || [],
+            confidence: context[:confidence] || 1.0,
+            metadata: context[:metadata] || {}
+          )
+        ]
+      end
+
+      # Manual extraction expects entities to be provided explicitly
+      def extract_entities(text)
+        []
+      end
+
+      # Convenience method for creating a single fact with full control
+      def create_fact(text:, valid_at:, invalid_at: nil, mentions: [], confidence: 1.0, metadata: {})
+        extract(text, {
+          valid_at: valid_at,
+          invalid_at: invalid_at,
+          mentions: mentions,
+          confidence: confidence,
+          metadata: metadata
+        }).first
+      end
+
+      # Convenience method for creating an entity
+      def create_entity(name:, type:, aliases: [], attributes: {})
+        build_entity(
+          name: name,
+          type: type,
+          aliases: aliases,
+          attributes: attributes
+        )
+      end
+    end
+  end
+end

data/lib/fact_db/extractors/rule_based_extractor.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Extractors
+    class RuleBasedExtractor < Base
+      # Date patterns for temporal extraction
+      DATE_PATTERNS = [
+        # "on January 10, 2024"
+        /(?:on|since|from|as of|starting)\s+(\w+\s+\d{1,2},?\s+\d{4})/i,
+        # "on 2024-01-10"
+        /(?:on|since|from|as of|starting)\s+(\d{4}-\d{2}-\d{2})/i,
+        # "in January 2024"
+        /(?:in|during)\s+(\w+\s+\d{4})/i,
+        # "in 2024"
+        /(?:in|during)\s+(\d{4})\b/i
+      ].freeze
+
+      END_DATE_PATTERNS = [
+        # "until January 10, 2024"
+        /(?:until|through|to|ended|left)\s+(\w+\s+\d{1,2},?\s+\d{4})/i,
+        /(?:until|through|to|ended|left)\s+(\d{4}-\d{2}-\d{2})/i
+      ].freeze
+
+      # Employment patterns
+      EMPLOYMENT_PATTERNS = [
+        # "Paula works at Microsoft"
+        /(\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:works?|worked|is working)\s+(?:at|for)\s+(\b[A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+)*)/,
+        # "Paula joined Microsoft"
+        /(\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:joined|started at|was hired by)\s+(\b[A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+)*)/,
+        # "Paula left Microsoft"
+        /(\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:left|departed|resigned from|was fired from)\s+(\b[A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+)*)/,
+        # "Paula is a Principal Engineer at Microsoft"
+        /(\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:is|was|became)\s+(?:a\s+)?([A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+)*)\s+at\s+(\b[A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+)*)/
+      ].freeze
+
+      # Relationship patterns
+      RELATIONSHIP_PATTERNS = [
+        # "Paula is married to John"
+        /(\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:is|was)\s+(?:married to|engaged to|dating)\s+(\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)/,
+        # "Paula is the CEO of Microsoft"
+        /(\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:is|was)\s+(?:the\s+)?(\w+(?:\s+\w+)*)\s+of\s+(\b[A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+)*)/
+      ].freeze
+
+      # Location patterns
+      LOCATION_PATTERNS = [
+        # "Paula lives in Seattle"
+        /(\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:lives?|lived|is based|was based|relocated)\s+(?:in|to)\s+(\b[A-Z][A-Za-z]+(?:,?\s+[A-Z]{2})?)/,
+        # "Microsoft is headquartered in Redmond"
+        /(\b[A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+)*)\s+(?:is|was)\s+(?:headquartered|located|based)\s+in\s+(\b[A-Z][A-Za-z]+(?:,?\s+[A-Z]{2})?)/
+      ].freeze
+
+      def extract(text, context = {})
+        return [] if text.nil? || text.strip.empty?
+
+        facts = []
+
+        # Extract employment facts
+        facts.concat(extract_employment_facts(text, context))
+
+        # Extract relationship facts
+        facts.concat(extract_relationship_facts(text, context))
+
+        # Extract location facts
+        facts.concat(extract_location_facts(text, context))
+
+        facts.uniq { |f| f[:text] }
+      end
+
+      def extract_entities(text)
+        return [] if text.nil? || text.strip.empty?
+
+        entities = []
+
+        # Extract person names (simple capitalized word sequences)
+        text.scan(/\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)\b/).flatten.uniq.each do |name|
+          next if common_word?(name)
+
+          entities << build_entity(name: name, type: "person")
+        end
+
+        # Extract organization names (from employment patterns)
+        EMPLOYMENT_PATTERNS.each do |pattern|
+          text.scan(pattern).each do |match|
+            org_name = match.last
+            entities << build_entity(name: org_name, type: "organization") unless common_word?(org_name)
+          end
+        end
+
+        # Extract locations
+        LOCATION_PATTERNS.each do |pattern|
+          text.scan(pattern).each do |match|
+            location = match.last
+            entities << build_entity(name: location, type: "place") unless common_word?(location)
+          end
+        end
+
+        entities.uniq { |e| e[:name].downcase }
+      end
+
+      private
+
+      def extract_employment_facts(text, context)
+        facts = []
+        default_date = context[:captured_at] || Time.current
+
+        EMPLOYMENT_PATTERNS.each do |pattern|
+          text.scan(pattern).each do |match|
+            person, *rest = match
+            org = rest.last
+
+            # Determine if this is a "left" pattern
+            is_termination = text.match?(/#{Regexp.escape(person)}\s+(?:left|departed|resigned|was fired)/i)
+
+            fact_text = match.join(" ").gsub(/\s+/, " ")
+            valid_at = extract_start_date(text) || default_date
+            invalid_at = is_termination ? (extract_end_date(text) || default_date) : nil
+
+            mentions = [
+              build_mention(name: person, type: "person", role: "subject"),
+              build_mention(name: org, type: "organization", role: "object")
+            ]
+
+            # Add role if present
+            if rest.length > 1
+              mentions << build_mention(name: rest[0], type: "concept", role: "instrument")
+            end
+
+            facts << build_fact(
+              text: fact_text,
+              valid_at: valid_at,
+              invalid_at: invalid_at,
+              mentions: mentions,
+              confidence: 0.8
+            )
+          end
+        end
+
+        facts
+      end
+
+      def extract_relationship_facts(text, context)
+        facts = []
+        default_date = context[:captured_at] || Time.current
+
+        RELATIONSHIP_PATTERNS.each do |pattern|
+          text.scan(pattern).each do |match|
+            fact_text = match.join(" ").gsub(/\s+/, " ")
+
+            mentions = match.map.with_index do |name, i|
+              role = i.zero? ? "subject" : "object"
+              build_mention(name: name, type: "person", role: role)
+            end
+
+            facts << build_fact(
+              text: fact_text,
+              valid_at: extract_start_date(text) || default_date,
+              invalid_at: extract_end_date(text),
+              mentions: mentions,
+              confidence: 0.75
+            )
+          end
+        end
+
+        facts
+      end
+
+      def extract_location_facts(text, context)
+        facts = []
+        default_date = context[:captured_at] || Time.current
+
+        LOCATION_PATTERNS.each do |pattern|
+          text.scan(pattern).each do |match|
+            entity_name, location = match
+            fact_text = "#{entity_name} is located in #{location}"
+
+            # Determine entity type
+            entity_type = text.match?(/#{Regexp.escape(entity_name)}\s+(?:lives?|lived)/i) ? "person" : "organization"
+
+            mentions = [
+              build_mention(name: entity_name, type: entity_type, role: "subject"),
+              build_mention(name: location, type: "place", role: "location")
+            ]
+
+            facts << build_fact(
+              text: fact_text,
+              valid_at: extract_start_date(text) || default_date,
+              invalid_at: nil,
+              mentions: mentions,
+              confidence: 0.7
+            )
+          end
+        end
+
+        facts
+      end
+
+      def extract_start_date(text)
+        DATE_PATTERNS.each do |pattern|
+          if (match = text.match(pattern))
+            return parse_date(match[1])
+          end
+        end
+        nil
+      end
+
+      def extract_end_date(text)
+        END_DATE_PATTERNS.each do |pattern|
+          if (match = text.match(pattern))
+            return parse_date(match[1])
+          end
+        end
+        nil
+      end
+
+      def common_word?(word)
+        common_words = %w[
+          The A An And Or But Is Was Were Are Been
+          Has Have Had Will Would Could Should
+          This That These Those
+          January February March April May June July August September October November December
+          Monday Tuesday Wednesday Thursday Friday Saturday Sunday
+          Inc Corp Ltd LLC Company Corporation
+        ]
+        common_words.any? { |w| w.casecmp?(word) }
+      end
+    end
+  end
+end

data/lib/fact_db/llm/adapter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module FactDb
+  module LLM
+    # Adapter for ruby_llm gem
+    # Provides a unified interface for the LLM extractor
+    #
+    # @example Configure with OpenAI
+    #   FactDb.configure do |config|
+    #     config.llm_client = FactDb::LLM::Adapter.new(
+    #       provider: :openai,
+    #       api_key: ENV["OPENAI_API_KEY"],
+    #       model: "gpt-4o-mini"
+    #     )
+    #   end
+    #
+    # @example Configure with Anthropic
+    #   FactDb.configure do |config|
+    #     config.llm_client = FactDb::LLM::Adapter.new(
+    #       provider: :anthropic,
+    #       api_key: ENV["ANTHROPIC_API_KEY"],
+    #       model: "claude-sonnet-4-20250514"
+    #     )
+    #   end
+    #
+    # @example Configure via YAML (config/fact_db.yml)
+    #   # llm_provider: anthropic
+    #   # llm_model: claude-sonnet-4-20250514
+    #   # llm_api_key: <%= ENV["ANTHROPIC_API_KEY"] %>
+    #
+    # @example Configure via environment variables
+    #   # EVENT_CLOCK_LLM_PROVIDER=anthropic
+    #   # EVENT_CLOCK_LLM_MODEL=claude-sonnet-4-20250514
+    #   # EVENT_CLOCK_LLM_API_KEY=sk-...
+    #
+    class Adapter
+      attr_reader :model, :provider
+
+      PROVIDER_DEFAULTS = {
+        openai: "gpt-4o-mini",
+        anthropic: "claude-sonnet-4-20250514",
+        gemini: "gemini-2.0-flash",
+        ollama: "llama3.2",
+        bedrock: "claude-sonnet-4",
+        openrouter: "anthropic/claude-sonnet-4"
+      }.freeze
+
+      # Create an adapter for a specific LLM provider
+      #
+      # @param provider [Symbol] :openai, :anthropic, :gemini, :ollama, :bedrock, :openrouter
+      # @param model [String] Model name (optional, uses provider default)
+      # @param api_key [String] API key (optional if set via ENV)
+      # @param options [Hash] Additional options passed to RubyLLM
+      #
+      def initialize(provider:, model: nil, api_key: nil, **options)
+        @provider = provider.to_sym
+        @model = model || PROVIDER_DEFAULTS[@provider]
+        @options = options
+
+        configure_ruby_llm(api_key)
+      end
+
+      # Send a prompt to the LLM and return the response text
+      #
+      # @param prompt [String] The prompt to send
+      # @return [String] The response text
+      def chat(prompt)
+        chat_instance = RubyLLM.chat(model: model)
+        response = chat_instance.ask(prompt)
+        response.content
+      end
+
+      # Alias for compatibility with different client interfaces
+      alias call chat
+      alias complete chat
+
+      private
+
+      def configure_ruby_llm(api_key)
+        require "ruby_llm"
+
+        RubyLLM.configure do |config|
+          case provider
+          when :openai
+            config.openai_api_key = api_key || ENV.fetch("OPENAI_API_KEY", nil)
+          when :anthropic
+            config.anthropic_api_key = api_key || ENV.fetch("ANTHROPIC_API_KEY", nil)
+          when :gemini
+            config.gemini_api_key = api_key || ENV.fetch("GEMINI_API_KEY", nil)
+          when :ollama
+            config.ollama_api_base = @options[:api_base] || "http://localhost:11434"
+          when :bedrock
+            config.bedrock_region = @options[:region] || ENV.fetch("AWS_REGION", "us-east-1")
+            config.bedrock_api_key = api_key || ENV.fetch("AWS_ACCESS_KEY_ID", nil)
+            config.bedrock_secret_key = @options[:secret_key] || ENV.fetch("AWS_SECRET_ACCESS_KEY", nil)
+          when :openrouter
+            config.openrouter_api_key = api_key || ENV.fetch("OPENROUTER_API_KEY", nil)
+          else
+            raise ConfigurationError, "Unknown LLM provider: #{provider}. " \
+                                       "Supported: openai, anthropic, gemini, ollama, bedrock, openrouter"
+          end
+        end
+      rescue LoadError
+        raise ConfigurationError, "LLM adapter requires the 'ruby_llm' gem. Add it to your Gemfile:\n" \
+                                  "  gem 'ruby_llm'"
+      end
+    end
+  end
+end

data/lib/fact_db/models/content.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Models
+    class Content < ActiveRecord::Base
+      self.table_name = "fact_db_contents"
+
+      has_many :fact_sources, class_name: "FactDb::Models::FactSource",
+               foreign_key: :content_id, dependent: :destroy
+      has_many :facts, through: :fact_sources
+
+      validates :content_hash, presence: true, uniqueness: true
+      validates :content_type, presence: true
+      validates :raw_text, presence: true
+      validates :captured_at, presence: true
+
+      before_validation :generate_content_hash, on: :create
+
+      # Content types
+      TYPES = %w[email transcript document slack meeting_notes contract report].freeze
+
+      validates :content_type, inclusion: { in: TYPES }, allow_nil: false
+
+      scope :by_type, ->(type) { where(content_type: type) }
+      scope :captured_between, ->(from, to) { where(captured_at: from..to) }
+      scope :captured_after, ->(date) { where("captured_at >= ?", date) }
+      scope :captured_before, ->(date) { where("captured_at <= ?", date) }
+
+      # Full-text search
+      scope :search_text, lambda { |query|
+        where("to_tsvector('english', raw_text) @@ plainto_tsquery('english', ?)", query)
+      }
+
+      # Vector similarity search (requires neighbor gem configured)
+      def self.nearest_neighbors(embedding, limit: 10)
+        return none unless embedding
+
+        order(Arel.sql("embedding <=> '#{embedding}'")).limit(limit)
+      end
+
+      def immutable?
+        true
+      end
+
+      def word_count
+        raw_text.split.size
+      end
+
+      def preview(length: 200)
+        return raw_text if raw_text.length <= length
+
+        "#{raw_text[0, length]}..."
+      end
+
+      private
+
+      def generate_content_hash
+        self.content_hash = Digest::SHA256.hexdigest(raw_text) if raw_text.present?
+      end
+    end
+  end
+end

data/lib/fact_db/models/entity.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Models
+    class Entity < ActiveRecord::Base
+      self.table_name = "fact_db_entities"
+
+      has_many :aliases, class_name: "FactDb::Models::EntityAlias",
+               foreign_key: :entity_id, dependent: :destroy
+      has_many :entity_mentions, class_name: "FactDb::Models::EntityMention",
+               foreign_key: :entity_id, dependent: :destroy
+      has_many :facts, through: :entity_mentions
+
+      belongs_to :merged_into, class_name: "FactDb::Models::Entity",
+                 foreign_key: :merged_into_id, optional: true
+      has_many :merged_entities, class_name: "FactDb::Models::Entity",
+               foreign_key: :merged_into_id
+
+      validates :canonical_name, presence: true
+      validates :entity_type, presence: true
+      validates :resolution_status, presence: true
+
+      # Entity types
+      TYPES = %w[person organization place product event concept].freeze
+      STATUSES = %w[unresolved resolved merged split].freeze
+
+      validates :entity_type, inclusion: { in: TYPES }
+      validates :resolution_status, inclusion: { in: STATUSES }
+
+      scope :by_type, ->(type) { where(entity_type: type) }
+      scope :resolved, -> { where(resolution_status: "resolved") }
+      scope :unresolved, -> { where(resolution_status: "unresolved") }
+      scope :not_merged, -> { where.not(resolution_status: "merged") }
+      scope :people, -> { by_type("person") }
+      scope :organizations, -> { by_type("organization") }
+      scope :places, -> { by_type("place") }
+
+      def resolved?
+        resolution_status == "resolved"
+      end
+
+      def merged?
+        resolution_status == "merged"
+      end
+
+      def canonical_entity
+        merged? ? merged_into&.canonical_entity || merged_into : self
+      end
+
+      def all_aliases
+        aliases.pluck(:alias_text)
+      end
+
+      def add_alias(text, type: nil, confidence: 1.0)
+        aliases.find_or_create_by!(alias_text: text) do |a|
+          a.alias_type = type
+          a.confidence = confidence
+        end
+      end
+
+      def matches_name?(name)
+        return true if canonical_name.downcase == name.downcase
+
+        aliases.exists?(["LOWER(alias_text) = ?", name.downcase])
+      end
+
+      # Get all facts mentioning this entity
+      def current_facts
+        facts.currently_valid.canonical
+      end
+
+      def facts_at(date)
+        facts.valid_at(date).canonical
+      end
+
+      # Vector similarity search for entity matching
+      def self.nearest_neighbors(embedding, limit: 10)
+        return none unless embedding
+
+        order(Arel.sql("embedding <=> '#{embedding}'")).limit(limit)
+      end
+    end
+  end
+end

data/lib/fact_db/models/entity_alias.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Models
+    class EntityAlias < ActiveRecord::Base
+      self.table_name = "fact_db_entity_aliases"
+
+      belongs_to :entity, class_name: "FactDb::Models::Entity"
+
+      validates :alias_text, presence: true
+      validates :alias_text, uniqueness: { scope: :entity_id }
+
+      # Alias types
+      TYPES = %w[name nickname email handle abbreviation title].freeze
+
+      validates :alias_type, inclusion: { in: TYPES }, allow_nil: true
+
+      scope :by_type, ->(type) { where(alias_type: type) }
+      scope :high_confidence, -> { where("confidence >= ?", 0.9) }
+
+      def self.find_entity_by_alias(text)
+        find_by(["LOWER(alias_text) = ?", text.downcase])&.entity
+      end
+    end
+  end
+end

data/lib/fact_db/models/entity_mention.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Models
+    class EntityMention < ActiveRecord::Base
+      self.table_name = "fact_db_entity_mentions"
+
+      belongs_to :fact, class_name: "FactDb::Models::Fact"
+      belongs_to :entity, class_name: "FactDb::Models::Entity"
+
+      validates :mention_text, presence: true
+      validates :fact_id, uniqueness: { scope: [:entity_id, :mention_text] }
+
+      # Mention roles
+      ROLES = %w[subject object location temporal instrument beneficiary].freeze
+
+      validates :mention_role, inclusion: { in: ROLES }, allow_nil: true
+
+      scope :by_role, ->(role) { where(mention_role: role) }
+      scope :subjects, -> { by_role("subject") }
+      scope :objects, -> { by_role("object") }
+      scope :high_confidence, -> { where("confidence >= ?", 0.9) }
+
+      def subject?
+        mention_role == "subject"
+      end
+
+      def object?
+        mention_role == "object"
+      end
+    end
+  end
+end