scout-ai 1.1.6 → 1.1.7

data/lib/scout/network/entity.rb

@@ -0,0 +1,206 @@
+require_relative 'paths'
+
+module Entity
+  module Adjacent
+    def path_to(adjacency, entities, threshold = nil, max_steps = nil)
+      if Array === self
+        self.collect{|entity| entity.path_to(adjacency, entities, threshold, max_steps)}
+      else
+        if adjacency.type == :flat
+          max_steps ||= threshold
+          Paths.dijkstra(adjacency, self, entities, max_steps)
+        else
+          Paths.weighted_dijkstra(adjacency, self, entities, threshold, max_steps)
+        end
+      end
+    end
+
+    def random_paths_to(adjacency, l, times, entities)
+      if Array === self
+        self.inject([]){|acc,entity| acc += entity.random_paths_to(adjacency, l, times, entities)}
+      else
+        paths = []
+        times.times do 
+          paths << Paths.random_weighted_dijkstra(adjacency, l, self, entities)
+        end
+        paths
+      end
+    end
+
+    # list of neighbours up to a given radius using unweighted adjacency
+    # adjacency: Hash[String => Array[String]] or TSV(:flat) treated as adjacency
+    # k: maximum number of steps
+    # Returns an Array of Arrays (one per entity when self is an array), each
+    # containing the reachable entities (as plain values) within k steps
+    def neighborhood(adjacency, k)
+      if Array === self
+        self.collect{|entity| entity.neighborhood(adjacency, k)}
+      else
+        adj_hash = adjacency.respond_to?(:include?) ? adjacency : adjacency.to_hash
+        Paths.neighborhood(adj_hash, self, k)
+      end
+    end
+  end
+end
+
+module AssociationItem
+
+  # Dijkstra over a list of AssociationItems, using an optional block to
+  # compute edge weights.
+  def self.dijkstra(associations, start_node, end_node = nil, threshold = nil, max_steps = nil, &block)
+    adjacency = {}
+
+    associations.each do |m|
+      s, t, _sep = m.split "~"
+      next if s.nil? || t.nil? || s.strip.empty? || t.strip.empty?
+      adjacency[s] ||= Set.new
+      adjacency[s] << t 
+      next unless m.undirected
+      adjacency[t] ||= Set.new
+      adjacency[t] << s  
+    end
+
+    return nil unless adjacency.include? start_node
+
+    active   = PriorityQueue.new         
+    distances = Hash.new { 1.0 / 0.0 } 
+    parents   = Hash.new                 
+
+    active[start_node] << 0
+    best   = 1.0 / 0.0
+    found  = false
+    node_dist_cache = {}
+
+    until active.empty?
+      u        = active.priorities.first
+      distance = active.shift
+      distances[u] = distance
+      path = Paths.extract_path(parents, start_node, u) if parents.key?(u)
+      next if max_steps && path && path.length > max_steps 
+      next unless adjacency.include?(u) && adjacency[u] && !adjacency[u].empty?
+      adjacency[u].each do |v|
+        node_dist = node_dist_cache[[u,v]] ||= (block_given? ? block.call(u,v) : 1)
+        next if node_dist.nil? || (threshold && node_dist > threshold)
+        d = distance + node_dist
+        next unless d < distances[v] && d < best # we can't relax this one
+        active[v] << d
+        distances[v] = d
+        parents[v] = u
+        if String === end_node ? (end_node == v) : (end_node && end_node.include?(v))
+          best = d 
+          found = true
+        end
+      end    
+    end
+
+    return nil unless found
+
+    if end_node
+      end_node = (end_node & parents.keys).first unless String === end_node
+      return nil unless parents.include? end_node
+      Paths.extract_path(parents, start_node, end_node)
+    else
+      parents
+    end
+  end
+
+  # Connected components from a list of AssociationItems.
+  # Returns an Array of Arrays of node identifiers.
+  def self.components(associations, undirected: true)
+    inc = associations.respond_to?(:incidence) ? associations.incidence : AssociationItem.incidence(associations)
+
+    adjacency = Hash.new { |h,k| h[k] = [] }
+    nodes     = Set.new
+    targets   = inc.fields
+
+    inc.each do |src, row|
+      Array(row).each_with_index do |val, i|
+        next if val.nil?
+        t = targets[i]
+        adjacency[src] << t
+        nodes << src << t
+        adjacency[t] << src if undirected
+      end
+    end
+
+    components = []
+    visited    = Set.new
+
+    nodes.each do |n|
+      next if visited.include?(n)
+      comp  = []
+      queue = [n]
+      visited << n
+      until queue.empty?
+        u = queue.shift
+        comp << u
+        adjacency[u].each do |v|
+          next if visited.include?(v)
+          visited << v
+          queue << v
+        end
+      end
+      components << comp
+    end
+
+    components
+  end
+
+  # Degree per node from an AssociationItem list.
+  # direction: :out, :in, :both
+  def self.degrees(associations, direction: :both)
+    inc = associations.respond_to?(:incidence) ? associations.incidence : AssociationItem.incidence(associations)
+    deg = Hash.new(0)
+    targets = inc.fields
+
+    inc.each do |src, row|
+      Array(row).each_with_index do |val, i|
+        next if val.nil?
+        t = targets[i]
+        case direction
+        when :out
+          deg[src] += 1
+        when :in
+          deg[t] += 1
+        when :both
+          deg[src] += 1
+          deg[t]   += 1
+        else
+          raise ArgumentError, "Unknown direction: #{direction.inspect}"
+        end
+      end
+    end
+
+    deg
+  end
+
+  # Induced subgraph: keep only edges whose endpoints are in the given node set.
+  def self.subset_by_nodes(associations, nodes)
+    node_set = nodes.to_set
+    associations.select do |m|
+      s = m.source rescue nil
+      t = m.target rescue nil
+      next false if s.nil? || t.nil?
+      node_set.include?(s) && node_set.include?(t)
+    end
+  end
+
+  # Neighborhood within k steps inside a fixed subgraph, using unweighted BFS
+  # over adjacency built from associations.
+  def self.neighborhood(associations, seeds, k)
+    inc = associations.respond_to?(:incidence) ? associations.incidence : AssociationItem.incidence(associations)
+    adjacency = Hash.new { |h,k| h[k] = [] }
+    targets   = inc.fields
+
+    inc.each do |src, row|
+      Array(row).each_with_index do |val, i|
+        next if val.nil?
+        t = targets[i]
+        adjacency[src] << t
+        adjacency[t] << src
+      end
+    end
+
+    Paths.neighborhood(adjacency, seeds, k)
+  end
+end

data/lib/scout/network/knowledge_base.rb

@@ -0,0 +1,142 @@
+require 'scout/knowledge_base'
+require 'set'
+
+class KnowledgeBase
+  # Outward k-hop expansion from seeds over a KB database
+  # db: database name (Symbol or String)
+  # seeds: Entity or Array of Entities/ids
+  # depth: Integer
+  # direction: :out, :in, :both
+  # filter: optional Proc taking an AssociationItem and returning true/false
+  #
+  # Returns [visited_nodes, edges], where:
+  # - visited_nodes is an Array of identifiers (as returned by AssociationItem.source/target)
+  # - edges is an Array of AssociationItems traversed during the expansion
+  def radial_expand(db, seeds, depth:, direction: :out, filter: nil)
+    current = Array(seeds).compact
+    return [[], []] if current.empty?
+
+    visited = Set.new(current)
+    edges   = []
+
+    1.upto(depth) do
+      next_front = []
+
+      current.each do |entity|
+        step_edges = case direction
+                     when :out
+                       children(db, entity)
+                     when :in
+                       parents(db, entity)
+                     when :both
+                       children(db, entity) + parents(db, entity)
+                     else
+                       raise ArgumentError, "Unknown direction: #{direction.inspect}"
+                     end
+
+        step_edges.each do |item|
+          next if filter && ! filter.call(item)
+
+          s = item.source
+          t = item.target
+
+          edges << item
+
+          targets = case direction
+                    when :out then [t]
+                    when :in  then [s]
+                    when :both then [s, t]
+                    end
+
+          targets.each do |node|
+            next if visited.include?(node)
+            visited << node
+            next_front << node
+          end
+        end
+      end
+
+      break if next_front.empty?
+      current = next_front
+    end
+
+    [visited.to_a, edges.uniq]
+  end
+
+  # Return radial layers around seeds as an array of arrays of nodes, plus edges.
+  # layers[0] are the seeds, layers[1] nodes at distance 1, ... up to depth or
+  # until no more nodes are reached.
+  def radial_layers(db, seeds, depth:, direction: :out, filter: nil)
+    current = Array(seeds).compact
+    return [[], []] if current.empty?
+
+    layers  = []
+    visited = Set.new(current)
+    edges   = []
+
+    layers << current.dup
+
+    1.upto(depth) do
+      next_front = []
+
+      current.each do |entity|
+        step_edges = case direction
+                     when :out
+                       children(db, entity)
+                     when :in
+                       parents(db, entity)
+                     when :both
+                       children(db, entity) + parents(db, entity)
+                     else
+                       raise ArgumentError, "Unknown direction: #{direction.inspect}"
+                     end
+
+        step_edges.each do |item|
+          next if filter && ! filter.call(item)
+
+          s = item.source
+          t = item.target
+
+          edges << item
+
+          targets = case direction
+                    when :out then [t]
+                    when :in  then [s]
+                    when :both then [s, t]
+                    end
+
+          targets.each do |node|
+            next if visited.include?(node)
+            visited << node
+            next_front << node
+          end
+        end
+      end
+
+      break if next_front.empty?
+      layers << next_front
+      current = next_front
+    end
+
+    [layers, edges.uniq]
+  end
+
+  # Directional convenience wrappers
+  def radial_expand_out(db, seeds, depth:, filter: nil)
+    radial_expand(db, seeds, depth: depth, direction: :out, filter: filter)
+  end
+
+  def radial_expand_in(db, seeds, depth:, filter: nil)
+    radial_expand(db, seeds, depth: depth, direction: :in, filter: filter)
+  end
+
+  def radial_expand_both(db, seeds, depth:, filter: nil)
+    radial_expand(db, seeds, depth: depth, direction: :both, filter: filter)
+  end
+
+  # Convenience: only return the edges in a k-hop subgraph around seeds
+  def subgraph_around(db, seeds, depth:, direction: :out, filter: nil)
+    _visited, edges = radial_expand(db, seeds, depth: depth, direction: direction, filter: filter)
+    edges
+  end
+end

data/lib/scout/network/paths.rb

@@ -0,0 +1,177 @@
+require 'fc'
+
+module Paths
+
+  def self.extract_path(parents, start_node, end_node)
+    path = [end_node]
+    while not path.last === start_node
+      path << parents[path.last]
+    end
+    path
+  end
+
+  def self.dijkstra(adjacency, start_node, end_node = nil, max_steps = nil)
+
+    return nil unless adjacency.include? start_node
+
+    case end_node
+    when String
+      return nil unless adjacency.values.flatten.include? end_node
+    when Array
+      return nil unless (adjacency.values.flatten & end_node).any?
+    end
+
+    active = FastContainers::PriorityQueue.new(:min)
+    distances = Hash.new { 1.0 / 0.0 } 
+    parents = Hash.new                 
+
+    active.push(start_node, 0)
+    best = 1.0 / 0.0
+    until active.empty?
+      u = active.top
+      distance = active.top_key
+      active.pop
+
+      distances[u] = distance
+      d = distance + 1
+      path = extract_path(parents, start_node, u)
+      next if path.length > max_steps if max_steps 
+      adjacency[u].each do |v|
+        next unless d < distances[v] and d < best # we can't relax this one
+        best = d if (String === end_node ? end_node == v : end_node.include?(v))
+        active.push(v,d) if adjacency.include? v
+        distances[v] = d
+
+
+        parents[v] = u
+      end    
+    end
+
+    if end_node
+      end_node = end_node.select{|n| parents.keys.include? n}.first unless String === end_node
+      return nil if not parents.include? end_node
+      extract_path(parents, start_node, end_node)
+    else
+      parents
+    end
+  end
+
+  def self.weighted_dijkstra(adjacency, start_node, end_node = nil, threshold = nil, max_steps = nil)
+    return nil unless adjacency.include? start_node
+
+    active = FastContainers::PriorityQueue.new(:min)
+    distances = Hash.new { 1.0 / 0.0 } 
+    parents = Hash.new                 
+
+    active.push(start_node, 0)
+    best = 1.0 / 0.0
+    found = false
+    until active.empty?
+      u = active.top
+      distance = active.top_key
+      active.pop
+      distances[u] = distance
+      path = extract_path(parents, start_node, u)
+      next if path.length > max_steps if max_steps 
+      next if not adjacency.include?(u) or (adjacency[u].nil? or adjacency[u].empty? )
+      NamedArray.zip_fields(adjacency[u]).each do |v,node_dist|
+        node_dist = node_dist.to_f
+        next if node_dist.nil? or (threshold and node_dist > threshold)
+        d = distance + node_dist
+        next unless d < distances[v] and d < best # we can't relax this one
+        active.push(v, d)
+        distances[v] = d
+        parents[v] = u
+        if (String === end_node ? end_node == v : end_node.include?(v))
+          best = d 
+          found = true
+        end
+      end    
+    end
+
+    return nil unless found
+
+    if end_node
+      end_node = (end_node & parents.keys).first unless String === end_node
+      return nil if not parents.include? end_node
+      extract_path(parents, start_node, end_node)
+    else
+      parents
+    end
+  end
+
+  def self.random_weighted_dijkstra(adjacency, l, start_node, end_node = nil)
+    return nil unless adjacency.include? start_node
+
+    active = PriorityQueue.new         
+    distances = Hash.new { 1.0 / 0.0 } 
+    parents = Hash.new                 
+
+    active[start_node] << 0
+    best = 1.0 / 0.0
+    until active.empty?
+      u = active.priorities.first
+      distance = active.shift
+      distances[u] = distance
+      next if not adjacency.include?(u) or adjacency[u].nil? or adjacency[u].empty?
+      NamedArray.zip_fields(adjacency[u]).each do |v,node_dist|
+        next if node_dist.nil?
+        d = distance + (node_dist * (l + rand))
+        next unless d < distances[v] and d < best # we can't relax this one
+        active[v] << distances[v] = d
+        parents[v] = u
+        best = d if (String === end_node ? end_node == v : end_node.include?(v))
+      end    
+    end
+
+    if end_node
+      end_node = (end_node & parents.keys).first unless String === end_node
+      return nil if not parents.include? end_node
+      path = [end_node]
+      while not path.last === start_node
+        path << parents[path.last]
+      end
+      path
+    else
+      parents
+    end
+  end
+
+  # New: breadth‑first exploration from one or many start nodes (unweighted)
+  # adjacency: Hash[String => Array[String]]
+  # sources: String or Array[String]
+  # max_steps: Integer or nil (no limit)
+  # Returns Hash[node => distance_from_any_source]
+  def self.breadth_first(adjacency, sources, max_steps = nil)
+    sources = [sources] unless Array === sources
+    distances = {}
+    queue = []
+
+    sources.each do |s|
+      next unless adjacency.include?(s)
+      distances[s] = 0
+      queue << s
+    end
+
+    until queue.empty?
+      u = queue.shift
+      d = distances[u]
+      next if max_steps && d >= max_steps
+      next unless adjacency.include?(u)
+      adjacency[u].each do |v|
+        next if distances.key?(v)
+        distances[v] = d + 1
+        queue << v
+      end
+    end
+
+    distances
+  end
+
+  # New: enumerate nodes within k steps of a set of sources (unweighted)
+  # Convenience wrapper over breadth_first
+  def self.neighborhood(adjacency, sources, k)
+    distances = breadth_first(adjacency, sources, k)
+    distances.keys
+  end
+end

data/scout-ai.gemspec

@@ -2,11 +2,11 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: scout-ai 1.1.6 ruby lib
+# stub: scout-ai 1.1.7 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "scout-ai".freeze
-  s.version = "1.1.6".freeze
+  s.version = "1.1.7".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -79,6 +79,9 @@ Gem::Specification.new do |s|
     "lib/scout/model/python/torch/load_and_save.rb",
     "lib/scout/model/util/run.rb",
     "lib/scout/model/util/save.rb",
+    "lib/scout/network/entity.rb",
+    "lib/scout/network/knowledge_base.rb",
+    "lib/scout/network/paths.rb",
     "python/scout_ai/__init__.py",
     "python/scout_ai/huggingface/data.py",
     "python/scout_ai/huggingface/eval.py",
@@ -135,11 +138,14 @@ Gem::Specification.new do |s|
     "test/scout/model/python/torch/test_helpers.rb",
     "test/scout/model/test_base.rb",
     "test/scout/model/util/test_save.rb",
+    "test/scout/network/test_entity.rb",
+    "test/scout/network/test_knowledge_base.rb",
+    "test/scout/network/test_paths.rb",
     "test/test_helper.rb"
   ]
   s.homepage = "http://github.com/mikisvaz/scout-ai".freeze
   s.licenses = ["MIT".freeze]
-  s.rubygems_version = "3.7.0.dev".freeze
+  s.rubygems_version = "3.7.2".freeze
   s.summary = "AI gear for scouts".freeze
 
   s.specification_version = 4

data/test/scout/llm/backends/test_bedrock.rb

@@ -19,7 +19,7 @@ Some text
     assert(Float === emb.first)
   end
 
-  def test_tool
+  def __test_tool
     prompt =<<-EOF
 What is the weather in London. Should I take my umbrella? Use the provided tool
     EOF

data/test/scout/llm/test_agent.rb

@@ -13,9 +13,25 @@ class TestLLMAgent < Test::Unit::TestCase
 
       agent = LLM::Agent.new knowledge_base: kb
 
-      sss 0
       ppp agent.ask "Who is Miguel's brother-in-law. Brother in law is your spouses sibling or your sibling's spouse"
     end
   end
+
+  def test_workflow_eval
+    agent = LLM::Agent.new
+    agent.workflow do
+      input :c_degrees, :float, "Degrees Celsius"
+
+      task :c_to_f => :float do |c_degrees|
+        (c_degrees * 9.0 / 5.0) + 32.0
+      end
+
+      export :c_to_f
+    end
+
+    agent.user "Convert 30 celsius into faranheit"
+    res = agent.json_format({conversion: {type: :number}})
+    assert_equal 86.0, res['conversion']
+  end
 end
 

data/test/scout/network/test_entity.rb

@@ -0,0 +1,47 @@
+require File.expand_path(__FILE__).sub(%r(/test/.*), '/test/test_helper.rb')
+require File.expand_path(__FILE__).sub(%r(.*/test/), '').sub(/test_(.*)\.rb/,'\\1')
+
+require 'scout/network/entity'
+require 'scout/knowledge_base'
+
+class TestNetworkEntityAssociationItem < Test::Unit::TestCase
+  def build_pairs
+    kb = KnowledgeBase.new tmpdir
+    kb.register :brothers, datafile_test(:person).brothers, undirected: true
+    kb.all(:brothers)
+  end
+
+  def test_components
+    pairs = build_pairs
+    comps = AssociationItem.components(pairs)
+    # All nodes from brothers should appear in the (single) component
+    flat = comps.flatten
+    %w[Miki Isa Clei Guille].each do |name|
+      assert_include flat, name
+    end
+    assert_equal 1, comps.length
+  end
+
+  def test_degrees
+    pairs = build_pairs
+    deg   = AssociationItem.degrees(pairs)
+    # In brothers example, Miki and Isa each connected to at least one
+    assert deg['Miki'] > 0
+    assert deg['Isa']  > 0
+  end
+
+  def test_subset_by_nodes
+    pairs = build_pairs
+    sub   = AssociationItem.subset_by_nodes(pairs, %w[Miki Isa])
+    assert sub.any? { |e| [e.source, e.target].sort == %w[Isa Miki].sort }
+    # Edges involving others should be filtered out
+    refute sub.any? { |e| (e.source == 'Clei') || (e.target == 'Clei') }
+  end
+
+  def test_neighborhood_inside_subgraph
+    pairs = build_pairs
+    neigh = AssociationItem.neighborhood(pairs, 'Miki', 1)
+    assert_include neigh, 'Miki'
+    assert_include neigh, 'Isa'
+  end
+end