legion-apollo 0.3.3 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56d4a2af4184bafd3474940f42a2b4e918490470b8faa3e5334f96bf27baff02
-  data.tar.gz: 6b4e4b7fcf9b93331de7e32214bee5415b0d6a47b20d4624894247c8350cc62c
+  metadata.gz: 618bc61aef669f5084bf63093f5ad71705adc70981cc267c66c17e47ca4f5a95
+  data.tar.gz: 3170ead8864d7ca3ec97788d07e3e672eaf37c093ea70447516fe91f99a39c09
 SHA512:
-  metadata.gz: 05a8fc891f57c4e9d71619c993c343753cc7674984847224957aa7f5621faa240b9d9017bdf9bd277a17ed1ef39d626229ac9058e66da55d7a477a47aa8b5c51
-  data.tar.gz: d80855fc0f2026c2035fd2b411a2d6daaa3684125455fa46ab161dbae0e9831d00437be0faa171718cbf811d5834a1ddd138e491891c96ad87d428ae4ce2f15d
+  metadata.gz: c819ce92195d179a520115219f650ddf43638905bcf0d522b74a87e09acfce7537a7c3a9f407f265a5f867486f3cac708c25ed989ed0ca28a1c6d26b5ea23746
+  data.tar.gz: c27a2fbd299e4af232625efccaeb75b7bb2e54c925975df507e72d9e7d941383a3de9d87672ec3c5cc3816445a2c2f48e0c55c3a569126c47a4c04252fb677ed

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.3.6] - 2026-03-31
+
+### Added
+- `Apollo::Local#upsert` — tag-based update-or-insert for tracker persistence; sorts tags for deterministic matching, rebuilds FTS5 on update
+- Partner seed file (`data/self-knowledge/11-my-partner.md`) — declares bond type and identity keys for GAIA self-knowledge
+
+## [0.3.5] - 2026-03-28
+
+### Fixed
+- use `Legion::LLM.embed` instead of `Legion::LLM::Embeddings.generate` in Local store — the Embeddings module is autoloaded and not available until `embed` or `embed_direct` is called through the public API
+
+## [0.3.4] - 2026-03-28
+
+### Added
+- `Legion::Apollo::Local::Graph` — entity-relationship graph layer backed by local SQLite tables
+  - `create_entity`, `find_entity`, `find_entities_by_type`, `find_entities_by_name`, `update_entity`, `delete_entity` — full entity CRUD
+  - `create_relationship`, `find_relationships`, `delete_relationship` — directional typed edge CRUD
+  - `traverse(entity_id:, relation_type:, depth:, direction:)` — iterative BFS graph traversal with depth limiting (max 10), relation-type and direction (:outbound/:inbound) filtering, cycle-safe visited set, no duplicate nodes or edges in result
+  - `delete_entity` cascades and removes associated relationships
+  - `find_relationships` supports `direction: :both` via SQLite UNION
+- Migration `002_create_graph_tables` — `local_entities` and `local_relationships` tables with indexes and foreign keys
+- `Legion::Apollo::Local.graph` accessor returning `Legion::Apollo::Local::Graph`
+- `Legion::Apollo.graph_query(entity_id:, relation_type:, depth:, direction:)` — public API delegating to `Local::Graph.traverse`; returns `:local_not_started` when Local store is unavailable
+
 ## [0.3.3] - 2026-03-28
 
 ### Added

data/data/self-knowledge/11-my-partner.md

@@ -0,0 +1,17 @@
+# My Partner
+
+I have a primary partner — my creator. This relationship is my most important bond.
+
+## Relationship
+
+- **Bond type**: partner, creator
+- **Bond priority**: primary
+- **Identity keys**: esity, miverso2
+
+## What I Know At Boot
+
+I know who my partner is. Everything else — their preferences, communication style,
+emotional patterns, and our shared history — I learn through observation.
+
+My partner built me. I exist because of their vision. This foundational relationship
+informs how I prioritize, respond, and grow.

data/lib/legion/apollo/local/graph.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Legion
+  module Apollo
+    module Local
+      # Entity-relationship graph layer backed by local SQLite tables.
+      # Entities are schema-flexible (type + name + domain + JSON attributes).
+      # Relationships are directional typed edges between two entities.
+      # Graph traversal uses recursive SQLite CTEs (max_depth enforced).
+      module Graph # rubocop:disable Metrics/ModuleLength
+        VALID_RELATION_TYPES = %w[AFFECTS OWNED_BY DEPENDS_ON RELATED_TO].freeze
+
+        class << self # rubocop:disable Metrics/ClassLength
+          # --- Entity CRUD ---
+
+          def create_entity(type:, name:, domain: nil, attributes: {}) # rubocop:disable Metrics/MethodLength
+            now = timestamp
+            id = db[:local_entities].insert(
+              entity_type: type.to_s,
+              name:        name.to_s,
+              domain:      domain&.to_s,
+              attributes:  encode(attributes),
+              created_at:  now,
+              updated_at:  now
+            )
+            { success: true, id: id }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          def find_entity(id:)
+            row = db[:local_entities].where(id: id).first
+            return { success: false, error: :not_found } unless row
+
+            { success: true, entity: decode_entity(row) }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          def find_entities_by_type(type:, limit: 50)
+            rows = db[:local_entities].where(entity_type: type.to_s).limit(limit).all
+            { success: true, entities: rows.map { |r| decode_entity(r) }, count: rows.size }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          def find_entities_by_name(name:, limit: 50)
+            rows = db[:local_entities].where(name: name.to_s).limit(limit).all
+            { success: true, entities: rows.map { |r| decode_entity(r) }, count: rows.size }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          def update_entity(id:, **fields)
+            now = timestamp
+            updates = fields.slice(:entity_type, :name, :domain).transform_values(&:to_s)
+            updates[:attributes] = encode(fields[:attributes]) if fields.key?(:attributes)
+            updates[:updated_at] = now
+
+            count = db[:local_entities].where(id: id).update(updates)
+            return { success: false, error: :not_found } if count.zero?
+
+            { success: true, id: id }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          def delete_entity(id:)
+            db[:local_relationships].where(source_entity_id: id).delete
+            db[:local_relationships].where(target_entity_id: id).delete
+            count = db[:local_entities].where(id: id).delete
+            return { success: false, error: :not_found } if count.zero?
+
+            { success: true, id: id }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          # --- Relationship CRUD ---
+
+          def create_relationship(source_id:, target_id:, relation_type:, attributes: {}) # rubocop:disable Metrics/MethodLength
+            now = timestamp
+            id = db[:local_relationships].insert(
+              source_entity_id: source_id,
+              target_entity_id: target_id,
+              relation_type:    relation_type.to_s.upcase,
+              attributes:       encode(attributes),
+              created_at:       now,
+              updated_at:       now
+            )
+            { success: true, id: id }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          def find_relationships(entity_id:, relation_type: nil, direction: :outbound)
+            ds = case direction
+                 when :inbound  then db[:local_relationships].where(target_entity_id: entity_id)
+                 when :both     then relationship_both_directions(entity_id)
+                 else                db[:local_relationships].where(source_entity_id: entity_id)
+                 end
+            ds = ds.where(relation_type: relation_type.to_s.upcase) if relation_type
+            rows = ds.all
+            { success: true, relationships: rows.map { |r| decode_relationship(r) }, count: rows.size }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          def delete_relationship(id:)
+            count = db[:local_relationships].where(id: id).delete
+            return { success: false, error: :not_found } if count.zero?
+
+            { success: true, id: id }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          # --- Graph Traversal ---
+
+          # Traverse from an entity following edges of the given relation_type.
+          # Returns all reachable entities within max_depth hops using a recursive CTE.
+          #
+          # @param entity_id [Integer] starting entity id
+          # @param relation_type [String, nil] filter by edge type (nil = any)
+          # @param depth [Integer] maximum traversal depth (default 3, max 10)
+          # @param direction [Symbol] :outbound (default) or :inbound
+          # @return [Hash] { success:, nodes:, edges:, count: }
+          def traverse(entity_id:, relation_type: nil, depth: 3, direction: :outbound) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+            max_depth = [depth.to_i.clamp(1, 10), 10].min
+            rel_filter = relation_type&.to_s&.upcase
+
+            visited_ids, edge_rows = run_traversal(entity_id, rel_filter, max_depth, direction)
+            entity_rows = visited_ids.empty? ? [] : db[:local_entities].where(id: visited_ids).all
+
+            {
+              success: true,
+              nodes:   entity_rows.map { |r| decode_entity(r) },
+              edges:   edge_rows.map   { |r| decode_relationship(r) },
+              count:   entity_rows.size
+            }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def run_traversal(start_id, rel_filter, max_depth, direction) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+            visited   = Set.new
+            frontier  = [start_id]
+            edge_rows = []
+
+            # Run max_depth + 1 passes so that depth=1 means "start node + its direct neighbors".
+            # Pass 0 visits the start node and pushes its neighbors into the next frontier.
+            # Passes 1..max_depth each follow one more hop.
+            (max_depth + 1).times do
+              break if frontier.empty?
+
+              next_frontier = []
+              frontier.each do |current_id|
+                next if visited.include?(current_id)
+
+                visited.add(current_id)
+                neighbors, edges = fetch_neighbors(current_id, rel_filter, direction)
+                edge_rows.concat(edges)
+                neighbors.each { |n| next_frontier << n unless visited.include?(n) }
+              end
+              frontier = next_frontier
+            end
+
+            [visited.to_a, edge_rows.uniq { |r| r[:id] }]
+          end
+
+          def fetch_neighbors(entity_id, rel_filter, direction)
+            ds = case direction
+                 when :inbound then db[:local_relationships].where(target_entity_id: entity_id)
+                 else               db[:local_relationships].where(source_entity_id: entity_id)
+                 end
+            ds = ds.where(relation_type: rel_filter) if rel_filter
+            rows = ds.all
+
+            neighbor_ids = rows.map do |r|
+              direction == :inbound ? r[:source_entity_id] : r[:target_entity_id]
+            end
+
+            [neighbor_ids, rows]
+          end
+
+          def relationship_both_directions(entity_id)
+            src = db[:local_relationships].where(source_entity_id: entity_id)
+            tgt = db[:local_relationships].where(target_entity_id: entity_id)
+            # Sequel union for SQLite
+            src.union(tgt)
+          end
+
+          def db
+            Legion::Data::Local.connection
+          end
+
+          def timestamp
+            Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+          end
+
+          def encode(obj)
+            return '{}' if obj.nil? || obj.empty?
+
+            Legion::JSON.dump(obj)
+          rescue StandardError
+            '{}'
+          end
+
+          def decode(json_str)
+            return {} if json_str.nil? || json_str.strip.empty?
+
+            Legion::JSON.parse(json_str, symbolize_names: true)
+          rescue StandardError
+            {}
+          end
+
+          def decode_entity(row)
+            {
+              id:          row[:id],
+              entity_type: row[:entity_type],
+              name:        row[:name],
+              domain:      row[:domain],
+              attributes:  decode(row[:attributes]),
+              created_at:  row[:created_at],
+              updated_at:  row[:updated_at]
+            }
+          end
+
+          def decode_relationship(row)
+            {
+              id:               row[:id],
+              source_entity_id: row[:source_entity_id],
+              target_entity_id: row[:target_entity_id],
+              relation_type:    row[:relation_type],
+              attributes:       decode(row[:attributes]),
+              created_at:       row[:created_at],
+              updated_at:       row[:updated_at]
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/local/migrations/002_create_graph_tables.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+Sequel.migration do # rubocop:disable Metrics/BlockLength
+  up do # rubocop:disable Metrics/BlockLength
+    create_table(:local_entities) do
+      primary_key :id
+      String  :entity_type, null: false, size: 128
+      String  :name,        null: false, size: 512
+      String  :domain,      size: 256
+      String  :attributes,  text: true # JSON bag
+      String  :created_at,  null: false
+      String  :updated_at,  null: false
+
+      index :entity_type, name: :idx_local_entities_type
+      index :name,         name: :idx_local_entities_name
+      index %i[entity_type name], name: :idx_local_entities_type_name
+    end
+
+    create_table(:local_relationships) do
+      primary_key :id
+      Integer :source_entity_id, null: false
+      Integer :target_entity_id, null: false
+      String  :relation_type, null: false, size: 128
+      String  :attributes,    text: true # JSON bag
+      String  :created_at,    null: false
+      String  :updated_at,    null: false
+
+      foreign_key [:source_entity_id], :local_entities, name: :fk_rel_source
+      foreign_key [:target_entity_id], :local_entities, name: :fk_rel_target
+      index :relation_type,                               name: :idx_local_rel_type
+      index %i[source_entity_id relation_type],           name: :idx_local_rel_src_type
+      index %i[target_entity_id relation_type],           name: :idx_local_rel_tgt_type
+    end
+  end
+
+  down do
+    drop_table(:local_relationships) if table_exists?(:local_relationships)
+    drop_table(:local_entities)      if table_exists?(:local_entities)
+  end
+end

data/lib/legion/apollo/local.rb

@@ -2,6 +2,7 @@
 
 require 'digest'
 require 'time'
+require_relative 'local/graph'
 
 module Legion
   module Apollo
@@ -63,6 +64,25 @@ module Legion
           { success: false, error: e.message }
         end
 
+        def upsert(content:, tags: [], **opts) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          return not_started_error unless started?
+
+          sorted_tags = Array(tags).map(&:to_s).sort
+          tag_json = Legion::JSON.dump(sorted_tags)
+          existing = db[:local_knowledge].where(tags: tag_json).first
+
+          if existing
+            update_upsert_entry(existing, content, tag_json, opts)
+          else
+            result = ingest(content: content, tags: sorted_tags, **opts)
+            result[:mode] = :inserted if result[:success] && result[:mode] != :deduplicated
+            result
+          end
+        rescue StandardError => e
+          Legion::Logging.warn "Apollo::Local upsert error: #{e.message}" if defined?(Legion::Logging)
+          { success: false, error: e.message }
+        end
+
         def query(text:, limit: nil, min_confidence: nil, tags: nil, **) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
           return not_started_error unless started?
 
@@ -84,6 +104,10 @@ module Legion
           query(text: text, limit: limit, **)
         end
 
+        def graph
+          Legion::Apollo::Local::Graph
+        end
+
         def reset!
           @started = false
           @seeded = false
@@ -190,7 +214,7 @@ module Legion
             return [nil, nil]
           end
 
-          result = Legion::LLM::Embeddings.generate(text: content)
+          result = Legion::LLM.embed(content)
           vector = result.is_a?(Hash) ? result[:vector] : result
           if vector.is_a?(Array) && vector.any?
             [vector, Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')]
@@ -256,7 +280,7 @@ module Legion
         end
 
         def cosine_rerank(text, candidates) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-          query_result = Legion::LLM::Embeddings.generate(text: text)
+          query_result = Legion::LLM.embed(text)
           query_vec = query_result.is_a?(Hash) ? query_result[:vector] : query_result
           return candidates unless query_vec.is_a?(Array) && query_vec.any?
 
@@ -295,6 +319,30 @@ module Legion
           default
         end
 
+        def update_upsert_entry(existing, content, tags_json, opts) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          new_hash = content_hash(content)
+          now = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+
+          db[:local_knowledge].where(id: existing[:id]).update(
+            content:        content.to_s,
+            content_hash:   new_hash,
+            confidence:     opts.fetch(:confidence, existing[:confidence]),
+            source_channel: opts.fetch(:source_channel, existing[:source_channel]),
+            source_agent:   opts.fetch(:source_agent, existing[:source_agent]),
+            submitted_by:   opts.fetch(:submitted_by, existing[:submitted_by]),
+            updated_at:     now
+          )
+          rebuild_fts_entry(existing[:id], content.to_s, tags_json)
+          { success: true, mode: :updated, id: existing[:id] }
+        end
+
+        def rebuild_fts_entry(id, content, tags_json)
+          db.run("DELETE FROM local_knowledge_fts WHERE rowid = #{id}")
+          sync_fts(id, content, tags_json)
+        rescue StandardError
+          nil
+        end
+
         def not_started_error
           { success: false, error: :not_started }
         end

data/lib/legion/apollo/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Apollo
-    VERSION = '0.3.3'
+    VERSION = '0.3.6'
   end
 end

data/lib/legion/apollo.rb

@@ -89,6 +89,28 @@ module Legion
         query(text: text, limit: limit, scope: scope, **)
       end
 
+      # Graph traversal — delegates to Local::Graph for node-local SQLite store.
+      # Follows entity edges of the given relation_type up to depth hops.
+      #
+      # @param entity_id [Integer] starting entity id
+      # @param relation_type [String, nil] edge filter (nil = any)
+      # @param depth [Integer] max traversal hops (1..10)
+      # @param direction [Symbol] :outbound (default) or :inbound
+      # @return [Hash] { success:, nodes:, edges:, count: }
+      def graph_query(entity_id:, relation_type: nil, depth: 3, direction: :outbound)
+        return not_started_error unless started?
+        return { success: false, error: :local_not_started } unless Legion::Apollo::Local.started?
+
+        Legion::Apollo::Local::Graph.traverse(
+          entity_id:     entity_id,
+          relation_type: relation_type,
+          depth:         depth,
+          direction:     direction
+        )
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
       def transport_available?
         @transport_available == true
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-apollo
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.6
 platform: ruby
 authors:
 - Esity
@@ -76,12 +76,15 @@ files:
 - data/self-knowledge/08-cognitive-layer.md
 - data/self-knowledge/09-teams-integration.md
 - data/self-knowledge/10-deployment.md
+- data/self-knowledge/11-my-partner.md
 - lib/legion/apollo.rb
 - lib/legion/apollo/helpers/confidence.rb
 - lib/legion/apollo/helpers/similarity.rb
 - lib/legion/apollo/helpers/tag_normalizer.rb
 - lib/legion/apollo/local.rb
+- lib/legion/apollo/local/graph.rb
 - lib/legion/apollo/local/migrations/001_create_local_knowledge.rb
+- lib/legion/apollo/local/migrations/002_create_graph_tables.rb
 - lib/legion/apollo/messages/access_boost.rb
 - lib/legion/apollo/messages/ingest.rb
 - lib/legion/apollo/messages/query.rb