fact_db 0.0.2 → 0.0.3

data/lib/fact_db/pipeline/extraction_pipeline.rb

@@ -4,16 +4,16 @@ require "simple_flow"
 
 module FactDb
   module Pipeline
-    # Pipeline for extracting facts from content using SimpleFlow
-    # Supports parallel processing of multiple content items
+    # Pipeline for extracting facts from sources using SimpleFlow
+    # Supports parallel processing of multiple source items
     #
     # @example Sequential extraction
     #   pipeline = ExtractionPipeline.new(config)
-    #   results = pipeline.process([content1, content2], extractor: :llm)
+    #   results = pipeline.process([source1, source2], extractor: :llm)
     #
     # @example Parallel extraction
     #   pipeline = ExtractionPipeline.new(config)
-    #   results = pipeline.process_parallel([content1, content2, content3], extractor: :llm)
+    #   results = pipeline.process_parallel([source1, source2, source3], extractor: :llm)
     #
     class ExtractionPipeline
       attr_reader :config
@@ -22,40 +22,40 @@ module FactDb
         @config = config
       end
 
-      # Process multiple content items sequentially
+      # Process multiple source items sequentially
       #
-      # @param contents [Array<Models::Content>] Content records to process
+      # @param sources [Array<Models::Source>] Source records to process
       # @param extractor [Symbol] Extractor type (:manual, :llm, :rule_based)
-      # @return [Array<Hash>] Results with extracted facts per content
-      def process(contents, extractor: config.default_extractor)
+      # @return [Array<Hash>] Results with extracted facts per source
+      def process(sources, extractor: config.default_extractor)
         pipeline = build_extraction_pipeline(extractor)
 
-        contents.map do |content|
-          result = pipeline.call(SimpleFlow::Result.new(content))
+        sources.map do |source|
+          result = pipeline.call(SimpleFlow::Result.new(source))
           {
-            content_id: content.id,
+            source_id: source.id,
             facts: result.success? ? result.value : [],
             error: result.halted? ? result.error : nil
           }
         end
       end
 
-      # Process multiple content items in parallel
+      # Process multiple source items in parallel
       # Uses SimpleFlow's parallel execution capabilities
       #
-      # @param contents [Array<Models::Content>] Content records to process
+      # @param sources [Array<Models::Source>] Source records to process
       # @param extractor [Symbol] Extractor type (:manual, :llm, :rule_based)
-      # @return [Array<Hash>] Results with extracted facts per content
-      def process_parallel(contents, extractor: config.default_extractor)
-        pipeline = build_parallel_pipeline(contents, extractor)
-        initial_result = SimpleFlow::Result.new(contents: contents, results: {})
+      # @return [Array<Hash>] Results with extracted facts per source
+      def process_parallel(sources, extractor: config.default_extractor)
+        pipeline = build_parallel_pipeline(sources, extractor)
+        initial_result = SimpleFlow::Result.new(sources: sources, results: {})
 
         final_result = pipeline.call(initial_result)
 
-        contents.map do |content|
-          result = final_result.value[:results][content.id]
+        sources.map do |source|
+          result = final_result.value[:results][source.id]
           {
-            content_id: content.id,
+            source_id: source.id,
             facts: result&.dig(:facts) || [],
             error: result&.dig(:error)
           }
@@ -68,21 +68,21 @@ module FactDb
         extractor_instance = get_extractor(extractor)
 
         SimpleFlow::Pipeline.new do
-          # Step 1: Validate content
+          # Step 1: Validate source
           step ->(result) {
-            content = result.value
-            if content.nil? || content.raw_text.blank?
-              result.halt("Content is empty or missing")
+            source = result.value
+            if source.nil? || source.content.blank?
+              result.halt("Source content is empty or missing")
             else
-              result.continue(content)
+              result.continue(source)
             end
           }
 
           # Step 2: Extract facts
           step ->(result) {
-            content = result.value
+            source = result.value
             begin
-              facts = extractor_instance.extract(content)
+              facts = extractor_instance.extract(source)
               result.continue(facts)
             rescue StandardError => e
               result.halt("Extraction failed: #{e.message}")
@@ -98,24 +98,24 @@ module FactDb
         end
       end
 
-      def build_parallel_pipeline(contents, extractor)
+      def build_parallel_pipeline(sources, extractor)
         extractor_instance = get_extractor(extractor)
 
         SimpleFlow::Pipeline.new do
-          # Create a step for each content item
-          contents.each do |content|
-            step "extract_#{content.id}", depends_on: [] do |result|
+          # Create a step for each source item
+          sources.each do |source|
+            step "extract_#{source.id}", depends_on: [] do |result|
               begin
-                facts = extractor_instance.extract(content)
+                facts = extractor_instance.extract(source)
                 valid_facts = facts.select { |f| f.valid? }
 
                 new_results = result.value[:results].merge(
-                  content.id => { facts: valid_facts, error: nil }
+                  source.id => { facts: valid_facts, error: nil }
                 )
                 result.continue(result.value.merge(results: new_results))
               rescue StandardError => e
                 new_results = result.value[:results].merge(
-                  content.id => { facts: [], error: e.message }
+                  source.id => { facts: [], error: e.message }
                 )
                 result.continue(result.value.merge(results: new_results))
               end
@@ -123,7 +123,7 @@ module FactDb
           end
 
           # Aggregate results
-          step "aggregate", depends_on: contents.map { |c| "extract_#{c.id}" } do |result|
+          step "aggregate", depends_on: sources.map { |s| "extract_#{s.id}" } do |result|
             result.continue(result.value)
           end
         end

data/lib/fact_db/pipeline/resolution_pipeline.rb

@@ -23,10 +23,10 @@ module FactDb
       # Resolve multiple entity names in parallel
       #
       # @param names [Array<String>] Entity names to resolve
-      # @param type [Symbol, nil] Entity type filter
+      # @param kind [Symbol, nil] Entity kind filter
       # @return [Array<Hash>] Resolution results
-      def resolve_entities(names, type: nil)
-        pipeline = build_entity_resolution_pipeline(names, type)
+      def resolve_entities(names, kind: nil)
+        pipeline = build_entity_resolution_pipeline(names, kind)
         initial_result = SimpleFlow::Result.new(names: names, resolved: {})
 
         final_result = pipeline.call(initial_result)
@@ -64,7 +64,7 @@ module FactDb
 
       private
 
-      def build_entity_resolution_pipeline(names, type)
+      def build_entity_resolution_pipeline(names, kind)
         resolver = @entity_resolver
 
         SimpleFlow::Pipeline.new do
@@ -72,7 +72,7 @@ module FactDb
           names.each do |name|
             step "resolve_#{name.hash.abs}", depends_on: [] do |result|
               begin
-                entity = resolver.resolve(name, type: type)
+                entity = resolver.resolve(name, kind: kind)
                 status = entity ? :resolved : :not_found
 
                 new_resolved = result.value[:resolved].merge(

data/lib/fact_db/query_result.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module FactDb
+  # Holds the results of a query and provides a unified interface
+  # for transformers to work with.
+  #
+  # @example Basic usage
+  #   result = QueryResult.new(query: "Paula Chen")
+  #   result.add_facts(facts)
+  #   result.resolve_entities(entity_service)
+  #   triples = TripleTransformer.new.transform(result)
+  #
+  class QueryResult
+    attr_reader :query, :facts, :entities, :metadata, :raw_facts
+
+    def initialize(query:)
+      @query = query
+      @facts = []
+      @raw_facts = []
+      @entities = {}
+      @metadata = {
+        retrieved_at: Time.now,
+        stores_queried: [:fact_db]
+      }
+    end
+
+    # Add facts to the result set.
+    #
+    # @param facts [Array<Fact>, Array<Hash>] Facts to add
+    # @return [void]
+    def add_facts(facts)
+      return if facts.nil? || facts.empty?
+
+      @raw_facts += Array(facts)
+      @facts += normalize_facts(facts)
+    end
+
+    # Resolve and cache entities mentioned in facts.
+    #
+    # @param entity_service [EntityService] Service to resolve entities
+    # @return [void]
+    def resolve_entities(entity_service = nil)
+      entity_ids = collect_entity_ids
+      return if entity_ids.empty?
+
+      entity_ids.each do |id|
+        next if @entities[id]
+
+        entity = resolve_entity(entity_service, id)
+        @entities[id] = normalize_entity(entity) if entity
+      end
+    end
+
+    # Check if results are empty.
+    #
+    # @return [Boolean]
+    def empty?
+      @facts.empty?
+    end
+
+    # Get all items for comparison operations.
+    #
+    # @return [Array<Hash>] Normalized items
+    def items
+      @facts.map { |f| normalize_for_comparison(f) }
+    end
+
+    # Convert to hash for JSON serialization.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        query: @query,
+        facts: @facts,
+        entities: @entities,
+        metadata: @metadata
+      }
+    end
+
+    # Hash-like access for backward compatibility.
+    #
+    # @param key [Symbol, String] Key to access
+    # @return [Object] Value for the key
+    def [](key)
+      to_h[key.to_sym]
+    end
+
+    # Iterate over all facts.
+    #
+    # @yield [Hash] Each normalized fact
+    # @return [void]
+    def each_fact(&block)
+      @facts.each(&block)
+    end
+
+    # Iterate over all entities.
+    #
+    # @yield [Hash] Each normalized entity
+    # @return [void]
+    def each_entity(&block)
+      @entities.values.each(&block)
+    end
+
+    # Get count of facts.
+    #
+    # @return [Integer]
+    def fact_count
+      @facts.size
+    end
+
+    # Get count of entities.
+    #
+    # @return [Integer]
+    def entity_count
+      @entities.size
+    end
+
+    private
+
+    def normalize_facts(facts)
+      facts.map do |fact|
+        if fact.is_a?(Hash)
+          fact
+        elsif fact.respond_to?(:as_json)
+          fact.as_json.transform_keys(&:to_sym)
+        else
+          {
+            id: fact.id,
+            text: fact.text,
+            valid_at: fact.valid_at,
+            invalid_at: fact.invalid_at,
+            status: fact.status,
+            confidence: fact.respond_to?(:confidence) ? fact.confidence : nil,
+            entity_mentions: extract_mentions(fact)
+          }
+        end
+      end
+    end
+
+    def extract_mentions(fact)
+      return [] unless fact.respond_to?(:entity_mentions)
+
+      fact.entity_mentions.map do |mention|
+        if mention.is_a?(Hash)
+          mention
+        else
+          {
+            entity_id: mention.entity_id,
+            mention_role: mention.mention_role,
+            mention_text: mention.respond_to?(:mention_text) ? mention.mention_text : nil,
+            confidence: mention.respond_to?(:confidence) ? mention.confidence : nil
+          }
+        end
+      end
+    end
+
+    def normalize_entity(entity)
+      if entity.is_a?(Hash)
+        entity
+      elsif entity.respond_to?(:as_json)
+        entity.as_json.transform_keys(&:to_sym)
+      else
+        {
+          id: entity.id,
+          name: entity.name,
+          kind: entity.kind,
+          aliases: entity.respond_to?(:aliases) ? entity.aliases.map { |a| { name: a.name, kind: a.kind } } : [],
+          resolution_status: entity.respond_to?(:resolution_status) ? entity.resolution_status : nil
+        }
+      end
+    end
+
+    def collect_entity_ids
+      ids = Set.new
+
+      @facts.each do |fact|
+        mentions = fact[:entity_mentions] || []
+        mentions.each { |m| ids << m[:entity_id] }
+      end
+
+      ids.to_a.compact
+    end
+
+    def resolve_entity(entity_service, id)
+      return nil unless entity_service
+
+      if entity_service.respond_to?(:find)
+        entity_service.find(id)
+      end
+    rescue StandardError
+      nil
+    end
+
+    def normalize_for_comparison(item)
+      {
+        type: :fact,
+        text: item[:text],
+        valid_at: item[:valid_at]
+      }
+    end
+  end
+end