fact_db 0.0.2 → 0.0.3

data/lib/fact_db/temporal/query.rb

@@ -2,13 +2,38 @@
 
 module FactDb
   module Temporal
+    # Executes temporal queries on facts with time-based filtering
+    #
+    # Provides methods for querying facts at specific points in time,
+    # comparing states between dates, and searching with temporal constraints.
+    #
+    # @example Query current facts about an entity
+    #   query = Query.new
+    #   facts = query.current_facts(entity_id: person.id)
+    #
+    # @example Compare facts at two points in time
+    #   diff = query.diff(entity_id: person.id, from_date: Date.parse("2023-01-01"), to_date: Date.today)
+    #   puts "Added: #{diff[:added].count}, Removed: #{diff[:removed].count}"
+    #
     class Query
+      # @return [ActiveRecord::Relation] the base scope for queries
       attr_reader :scope
 
+      # Initializes a new Query with an optional base scope
+      #
+      # @param scope [ActiveRecord::Relation] base fact scope (defaults to all facts)
       def initialize(scope = Models::Fact.all)
         @scope = scope
       end
 
+      # Executes a temporal query with multiple filters
+      #
+      # @param topic [String, nil] text to search for in fact content
+      # @param at [Date, Time, nil] point in time (nil for currently valid)
+      # @param entity_id [Integer, nil] filter by entity
+      # @param status [Symbol] fact status filter (:canonical, :superseded, :synthesized, :all)
+      # @param limit [Integer, nil] maximum number of results
+      # @return [ActiveRecord::Relation] matching facts ordered by valid_at desc
       def execute(topic: nil, at: nil, entity_id: nil, status: :canonical, limit: nil)
         result = @scope
 
@@ -33,31 +58,56 @@ module FactDb
         result
       end
 
-      # Currently valid facts about an entity
+      # Returns currently valid canonical facts about an entity
+      #
+      # @param entity_id [Integer] the entity to query
+      # @return [ActiveRecord::Relation] currently valid facts mentioning the entity
       def current_facts(entity_id:)
         execute(entity_id: entity_id, at: nil, status: :canonical)
       end
 
-      # Facts valid at a specific point in time
+      # Returns facts valid at a specific point in time
+      #
+      # @param date [Date, Time] the point in time to query
+      # @param entity_id [Integer, nil] optional entity filter
+      # @return [ActiveRecord::Relation] facts valid at the given date
       def facts_at(date, entity_id: nil)
         execute(at: date, entity_id: entity_id, status: :canonical)
       end
 
-      # Facts that became valid in a date range
+      # Returns facts that became valid within a date range
+      #
+      # @param from [Date, Time] start of range (inclusive)
+      # @param to [Date, Time] end of range (inclusive)
+      # @param entity_id [Integer, nil] optional entity filter
+      # @return [ActiveRecord::Relation] facts created in the range, ordered by valid_at asc
       def facts_created_between(from:, to:, entity_id: nil)
         result = @scope.canonical.became_valid_between(from, to)
         result = result.mentioning_entity(entity_id) if entity_id
         result.order(valid_at: :asc)
       end
 
-      # Facts that became invalid in a date range
+      # Returns facts that became invalid within a date range
+      #
+      # @param from [Date, Time] start of range (inclusive)
+      # @param to [Date, Time] end of range (inclusive)
+      # @param entity_id [Integer, nil] optional entity filter
+      # @return [ActiveRecord::Relation] facts invalidated in the range, ordered by invalid_at asc
       def facts_invalidated_between(from:, to:, entity_id: nil)
         result = @scope.became_invalid_between(from, to)
         result = result.mentioning_entity(entity_id) if entity_id
         result.order(invalid_at: :asc)
       end
 
-      # Semantic search with temporal filtering
+      # Searches facts by text with temporal filtering
+      #
+      # Uses PostgreSQL full-text search with optional point-in-time filtering.
+      #
+      # @param query [String] text to search for
+      # @param at [Date, Time, nil] point in time (nil for currently valid)
+      # @param entity_id [Integer, nil] optional entity filter
+      # @param limit [Integer] maximum number of results (default: 20)
+      # @return [ActiveRecord::Relation] matching facts
       def semantic_search(query:, at: nil, entity_id: nil, limit: 20)
         result = @scope.canonical.search_text(query)
         result = apply_temporal_filter(result, at)
@@ -65,14 +115,28 @@ module FactDb
         result.limit(limit)
       end
 
-      # Find facts where entity has a specific role
+      # Returns facts where an entity has a specific mention role
+      #
+      # @param entity_id [Integer] the entity to query
+      # @param role [String, Symbol] the mention role (e.g., :subject, :object)
+      # @param at [Date, Time, nil] point in time (nil for currently valid)
+      # @return [ActiveRecord::Relation] facts with the entity in the specified role
       def facts_with_entity_role(entity_id:, role:, at: nil)
         result = @scope.canonical.with_role(entity_id, role)
         result = apply_temporal_filter(result, at)
         result.order(valid_at: :desc)
       end
 
-      # Compare facts at two points in time
+      # Compares facts at two points in time to find changes
+      #
+      # @param entity_id [Integer] the entity to compare
+      # @param from_date [Date, Time] the earlier point in time
+      # @param to_date [Date, Time] the later point in time
+      # @return [Hash] hash with :added, :removed, and :unchanged arrays of facts
+      #
+      # @example
+      #   diff = query.diff(entity_id: 1, from_date: 1.year.ago, to_date: Date.today)
+      #   puts "#{diff[:added].count} new facts, #{diff[:removed].count} removed"
       def diff(entity_id:, from_date:, to_date:)
         facts_at_from = facts_at(from_date, entity_id: entity_id).to_a
         facts_at_to = facts_at(to_date, entity_id: entity_id).to_a

data/lib/fact_db/temporal/query_builder.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Temporal
+    # A scoped query builder for temporal queries.
+    # Allows chaining: facts.at("2024-01-15").query("Paula's role")
+    #
+    # @example Basic usage
+    #   facts.at("2024-01-15").query("Paula's role", format: :cypher)
+    #   facts.at("2024-01-15").facts_for(entity_id)
+    #   facts.at("2024-01-15").compare_to("2024-06-15")
+    #
+    class QueryBuilder
+      attr_reader :date
+
+      # Initialize with a Facts instance and date
+      #
+      # @param facts [FactDb::Facts] The Facts instance
+      # @param date [Date] The point in time
+      def initialize(facts, date)
+        @facts = facts
+        @date = date
+      end
+
+      # Execute a query at this point in time
+      #
+      # @param topic [String] The query topic
+      # @param format [Symbol] Output format (:json, :triples, :cypher, :text, :prolog)
+      # @return [Array, String, Hash] Results at this point in time
+      def query(topic, format: :json, **options)
+        @facts.query_facts(topic: topic, at: @date, format: format, **options)
+      end
+
+      # Get all facts valid at this date
+      #
+      # @param format [Symbol] Output format
+      # @return [Array, String, Hash] Results
+      def facts(format: :json, **options)
+        @facts.facts_at(@date, format: format, **options)
+      end
+
+      # Get facts for a specific entity at this date
+      #
+      # @param entity_id [Integer] Entity ID
+      # @param format [Symbol] Output format
+      # @return [Array, String, Hash] Results
+      def facts_for(entity_id, format: :json, **options)
+        @facts.facts_at(@date, entity: entity_id, format: format, **options)
+      end
+
+      # Compare this date to another
+      #
+      # @param other_date [Date, String] The date to compare to
+      # @param topic [String, nil] Optional topic to compare
+      # @return [Hash] Differences with :added, :removed, :unchanged keys
+      def compare_to(other_date, topic: nil)
+        @facts.diff(topic, from: @date, to: other_date)
+      end
+
+      # Get the timeline state at this date
+      #
+      # @param entity_id [Integer] Entity ID
+      # @return [Array] Facts valid at this date for the entity
+      def state_for(entity_id, format: :json)
+        @facts.facts_at(@date, entity: entity_id, format: format)
+      end
+    end
+  end
+end

data/lib/fact_db/temporal/timeline.rb

@@ -2,59 +2,106 @@
 
 module FactDb
   module Temporal
+    # Builds and analyzes temporal timelines of facts for an entity
+    #
+    # Provides methods to view an entity's history, group events by time periods,
+    # find overlapping facts, and compare states at different points in time.
+    # Includes Enumerable for easy iteration over timeline events.
+    #
+    # @example Build a timeline for an entity
+    #   timeline = Timeline.new.build(entity_id: person.id)
+    #   timeline.by_year.each { |year, events| puts "#{year}: #{events.count} events" }
+    #
+    # @example Find currently active facts
+    #   active_facts = timeline.active
+    #
     class Timeline
       include Enumerable
 
+      # @return [Array<TimelineEvent>] the timeline events
       attr_reader :events
 
+      # Initializes a new empty Timeline
       def initialize
         @events = []
       end
 
+      # Iterates over timeline event hashes
+      #
+      # @yield [Hash] each event as a hash
+      # @return [Enumerator] if no block given
       def each(&block)
         to_hash.each(&block)
       end
 
+      # Builds a timeline of facts for an entity
+      #
+      # @param entity_id [Integer] the entity to build timeline for
+      # @param from [Date, Time, nil] start of date range (optional)
+      # @param to [Date, Time, nil] end of date range (optional)
+      # @return [Timeline] self for method chaining
       def build(entity_id:, from: nil, to: nil)
         facts = fetch_facts(entity_id, from, to)
         @events = facts.map { |fact| TimelineEvent.new(fact) }
         self
       end
 
+      # Returns events sorted by valid_at date
+      #
+      # @return [Array<TimelineEvent>] sorted events
       def to_a
         @events.sort_by(&:valid_at)
       end
 
+      # Returns events as an array of hashes
+      #
+      # @return [Array<Hash>] events converted to hash format
       def to_hash
         to_a.map(&:to_hash)
       end
 
-      # Group events by year
+      # Groups events by year
+      #
+      # @return [Hash<Integer, Array<TimelineEvent>>] events grouped by year
       def by_year
         to_a.group_by { |event| event.valid_at.year }
       end
 
-      # Group events by month
+      # Groups events by month
+      #
+      # @return [Hash<String, Array<TimelineEvent>>] events grouped by "YYYY-MM" key
       def by_month
         to_a.group_by { |event| event.valid_at.strftime("%Y-%m") }
       end
 
-      # Get events in a specific date range
+      # Returns events in a specific date range
+      #
+      # @param from [Date, Time] start of range (inclusive)
+      # @param to [Date, Time] end of range (inclusive)
+      # @return [Array<TimelineEvent>] events within the range
       def between(from, to)
         to_a.select { |event| event.valid_at >= from && event.valid_at <= to }
       end
 
-      # Get currently active events
+      # Returns currently active (valid) events
+      #
+      # @return [Array<TimelineEvent>] events with no invalid_at date
       def active
         to_a.select(&:currently_valid?)
       end
 
-      # Get historical (no longer valid) events
+      # Returns historical (no longer valid) events
+      #
+      # @return [Array<TimelineEvent>] events that have been invalidated
       def historical
         to_a.reject(&:currently_valid?)
       end
 
-      # Find overlapping events
+      # Finds pairs of overlapping events
+      #
+      # Two events overlap if their validity periods intersect.
+      #
+      # @return [Array<Array<TimelineEvent, TimelineEvent>>] pairs of overlapping events
       def overlapping
         result = []
         sorted = to_a
@@ -68,12 +115,17 @@ module FactDb
         result
       end
 
-      # Get the state at a specific point in time
+      # Returns the state (valid events) at a specific point in time
+      #
+      # @param date [Date, Time] the point in time to query
+      # @return [Array<TimelineEvent>] events valid at the given date
       def state_at(date)
         to_a.select { |event| event.valid_at?(date) }
       end
 
-      # Generate a summary of changes
+      # Generates a summary of changes between consecutive events
+      #
+      # @return [Array<Hash>] array of hashes with :from, :to, and :gap_days keys
       def changes_summary
         sorted = to_a
 
@@ -103,29 +155,68 @@ module FactDb
       end
     end
 
+    # Wraps a Fact as a timeline event with convenience methods
+    #
+    # Provides a simplified interface for timeline operations,
+    # delegating most methods to the underlying fact.
+    #
     class TimelineEvent
+      # @return [FactDb::Models::Fact] the underlying fact
       attr_reader :fact
 
-      delegate :id, :fact_text, :valid_at, :invalid_at, :status,
+      # @!method id
+      #   @return [Integer] the fact ID
+      # @!method text
+      #   @return [String] the fact text
+      # @!method valid_at
+      #   @return [Time] when the fact became valid
+      # @!method invalid_at
+      #   @return [Time, nil] when the fact became invalid
+      # @!method status
+      #   @return [String] the fact status
+      # @!method currently_valid?
+      #   @return [Boolean] true if fact is currently valid
+      # @!method valid_at?(date)
+      #   @param date [Date, Time] the point in time
+      #   @return [Boolean] true if valid at the given date
+      # @!method duration
+      #   @return [ActiveSupport::Duration, nil] validity duration
+      # @!method duration_days
+      #   @return [Integer, nil] validity duration in days
+      # @!method entities
+      #   @return [Array<Entity>] mentioned entities
+      # @!method source_contents
+      #   @return [Array<Source>] source documents
+      delegate :id, :text, :valid_at, :invalid_at, :status,
                :currently_valid?, :valid_at?, :duration, :duration_days,
                :entities, :source_contents, to: :fact
 
+      # Initializes a new TimelineEvent
+      #
+      # @param fact [FactDb::Models::Fact] the fact to wrap
       def initialize(fact)
         @fact = fact
       end
 
+      # Converts the event to a hash representation
+      #
+      # @return [Hash] hash with :id, :text, :valid_at, :invalid_at, :status, :duration_days, :entities
       def to_hash
         {
           id: id,
-          fact_text: fact_text,
+          text: text,
           valid_at: valid_at,
           invalid_at: invalid_at,
           status: status,
           duration_days: duration_days,
-          entities: entities.map(&:canonical_name)
+          entities: entities.map(&:name)
         }
       end
 
+      # Compares events by valid_at date for sorting
+      #
+      # @param other [TimelineEvent] the event to compare with
+      # @return [Integer] -1, 0, or 1
       def <=>(other)
         valid_at <=> other.valid_at
       end

data/lib/fact_db/transformers/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Transformers
+    # Base transformer class providing common utilities.
+    # Subclasses implement specific output formats for LLM consumption.
+    class Base
+      # Transform query results to the target format.
+      #
+      # @param results [QueryResult] The query results
+      # @return [QueryResult] Transformed results (may modify in place)
+      def transform(results)
+        results
+      end
+
+      protected
+
+      # Safely get a value from hash or object
+      #
+      # @param obj [Hash, Object] Source object
+      # @param key [Symbol] Key to retrieve
+      # @return [Object, nil] The value
+      def get_value(obj, key)
+        if obj.is_a?(Hash)
+          obj[key] || obj[key.to_s]
+        elsif obj.respond_to?(key)
+          obj.send(key)
+        end
+      end
+
+      # Format dates consistently
+      #
+      # @param date [Date, Time, String, nil] Date to format
+      # @return [String, nil] Formatted date string
+      def format_date(date)
+        return nil if date.nil?
+
+        if date.respond_to?(:strftime)
+          date.strftime("%Y-%m-%d")
+        else
+          date.to_s
+        end
+      end
+
+      # Escape strings for output
+      #
+      # @param str [String] String to escape
+      # @return [String] Escaped string
+      def escape_string(str)
+        str.to_s.gsub('"', '\\"').gsub("\n", "\\n")
+      end
+
+      # Create a variable name from a string
+      #
+      # @param str [String] Source string
+      # @return [String] Valid variable name
+      def to_variable(str)
+        str.to_s
+           .downcase
+           .gsub(/[^a-z0-9]+/, "_")
+           .gsub(/^_|_$/, "")
+           .slice(0, 30)
+      end
+
+      # Truncate string to specified length
+      #
+      # @param str [String] String to truncate
+      # @param length [Integer] Maximum length
+      # @return [String] Truncated string
+      def truncate(str, length)
+        return str if str.to_s.length <= length
+
+        "#{str.to_s[0, length - 3]}..."
+      end
+    end
+  end
+end

data/lib/fact_db/transformers/cypher_transformer.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Transformers
+    # Transforms results into Cypher-like graph notation.
+    # This format is readable by both humans and LLMs, and encodes
+    # nodes, relationships, and properties explicitly.
+    #
+    # @example Output format
+    #   (paula:Person {name: "Paula Chen"})
+    #   (microsoft:Organization {name: "Microsoft"})
+    #   (paula)-[:WORKS_AT {since: "2024-01-10", role: "Principal Engineer"}]->(microsoft)
+    class CypherTransformer < Base
+      # Transform results to Cypher format.
+      #
+      # @param results [QueryResult] The query results
+      # @return [String] Cypher-like graph notation
+      def transform(results)
+        lines = []
+        defined_nodes = Set.new
+
+        # Define entity nodes
+        results.each_entity do |entity|
+          node_def = entity_to_cypher(entity)
+          if node_def && !defined_nodes.include?(node_def)
+            lines << node_def
+            defined_nodes << node_def
+          end
+        end
+
+        # Define relationships from facts
+        results.each_fact do |fact|
+          relationship = fact_to_cypher(fact, results.entities, defined_nodes, lines)
+          lines << relationship if relationship
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def entity_to_cypher(entity)
+        name = get_value(entity, :name)
+        return nil unless name
+
+        var = to_variable(name)
+        entity_kind = get_value(entity, :kind) || "Entity"
+        label = entity_kind.to_s.capitalize
+
+        props = { name: name }
+
+        # Add aliases if present
+        aliases = get_value(entity, :aliases)
+        if aliases && !aliases.empty?
+          alias_texts = aliases.map { |a| a.is_a?(Hash) ? a[:name] : a.to_s }
+          props[:aliases] = alias_texts
+        end
+
+        "(#{var}:#{label} #{format_props(props)})"
+      end
+
+      def fact_to_cypher(fact, entities, defined_nodes, lines)
+        text = get_value(fact, :text) || ""
+        return nil if text.empty?
+
+        mentions = get_value(fact, :entity_mentions) || []
+
+        # Find subject and object from mentions if available
+        subject_mention = mentions.find { |m| get_value(m, :mention_role) == "subject" }
+        object_mention = mentions.find { |m| get_value(m, :mention_role) != "subject" }
+
+        # Get subject - from mentions or parse from text
+        if subject_mention
+          subject_id = get_value(subject_mention, :entity_id)
+          subject_entity = entities[subject_id]
+          subject_name = subject_entity ? get_value(subject_entity, :name) : "Entity_#{subject_id}"
+        else
+          subject_name = extract_subject(text)
+        end
+
+        return nil if subject_name.nil? || subject_name.empty?
+
+        subject_var = to_variable(subject_name)
+
+        # Ensure subject node is defined
+        unless defined_nodes.any? { |n| n.include?("(#{subject_var}:") }
+          node_def = "(#{subject_var}:Entity {name: \"#{escape_string(subject_name)}\"})"
+          lines << node_def
+          defined_nodes << node_def
+        end
+
+        # Build relationship properties
+        rel_props = {}
+
+        valid_at = get_value(fact, :valid_at)
+        rel_props[:since] = format_date(valid_at) if valid_at
+
+        invalid_at = get_value(fact, :invalid_at)
+        rel_props[:until] = format_date(invalid_at) if invalid_at
+
+        status = get_value(fact, :status)
+        rel_props[:status] = status if status
+
+        confidence = get_value(fact, :confidence)
+        rel_props[:confidence] = confidence if confidence
+
+        # Extract relationship type from fact text
+        rel_type = extract_relationship_type(text)
+
+        if object_mention
+          # Relationship to another entity
+          object_id = get_value(object_mention, :entity_id)
+          object_entity = entities[object_id]
+          object_name = object_entity ? get_value(object_entity, :name) : "Entity_#{object_id}"
+          object_var = to_variable(object_name)
+
+          # Ensure object node is defined
+          unless defined_nodes.any? { |n| n.include?("(#{object_var}:") }
+            node_def = "(#{object_var}:Entity {name: \"#{escape_string(object_name)}\"})"
+            lines << node_def
+            defined_nodes << node_def
+          end
+
+          props_str = rel_props.empty? ? "" : " #{format_props(rel_props)}"
+          "(#{subject_var})-[:#{rel_type}#{props_str}]->(#{object_var})"
+        else
+          # Relationship to a literal value
+          object_value = extract_object_value(text, subject_name)
+          props_str = rel_props.empty? ? "" : " #{format_props(rel_props)}"
+          "(#{subject_var})-[:#{rel_type}#{props_str}]->(\"#{escape_string(object_value)}\")"
+        end
+      end
+
+      def extract_relationship_type(text)
+        if text.match?(/\bworks?\s+(at|for)\b/i)
+          "WORKS_AT"
+        elsif text.match?(/\bworked\s+(at|for)\b/i)
+          "WORKED_AT"
+        elsif text.match?(/\breports?\s+to\b/i)
+          "REPORTS_TO"
+        elsif text.match?(/\bis\s+(a|an|the)\b/i)
+          "IS_A"
+        elsif text.match?(/\bis\s+\w+/i)
+          "IS"
+        elsif text.match?(/\bhas\b/i)
+          "HAS"
+        elsif text.match?(/\bdecided\b/i)
+          "DECIDED"
+        elsif text.match?(/\bjoined\b/i)
+          "JOINED"
+        elsif text.match?(/\bleft\b/i)
+          "LEFT"
+        else
+          "RELATES_TO"
+        end
+      end
+
+      def extract_subject(text)
+        words = text.split(/\s+/)
+        words.take_while { |w| !w.match?(/^(is|are|was|were|has|have|works|worked|reports)$/i) }.join(" ")
+      end
+
+      def extract_object_value(text, subject)
+        remainder = text.sub(/^#{Regexp.escape(subject)}\s*/i, "")
+        remainder.sub(/^(is|are|was|were|has|have|works?|worked|reports?)\s+(at|for|to|a|an|the)?\s*/i, "")
+      end
+
+      def format_props(props)
+        return "{}" if props.empty?
+
+        pairs = props.map do |k, v|
+          value = case v
+                  when String then "\"#{escape_string(v)}\""
+                  when Array then "[#{v.map { |e| "\"#{escape_string(e)}\"" }.join(", ")}]"
+                  when nil then "null"
+                  else v.to_s
+                  end
+          "#{k}: #{value}"
+        end
+
+        "{#{pairs.join(", ")}}"
+      end
+    end
+  end
+end

data/lib/fact_db/transformers/json_transformer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FactDb
+  module Transformers
+    # JSON transformer - returns results as structured hash.
+    # This is the default pass-through format.
+    class JsonTransformer < Base
+      # Transform results to JSON-ready hash format.
+      #
+      # @param results [QueryResult] The query results
+      # @return [Hash] JSON-serializable hash
+      def transform(results)
+        results.to_h
+      end
+    end
+  end
+end