legion-apollo 0.3.2 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c8e724eefe292faefec05ca4fc589ed935f4734bc5c4726b7c5d70ed3b69dbb
-  data.tar.gz: 3fc0246858d50305bd2d956e87c9ec844c71a769c4f81955f43d2640159a175c
+  metadata.gz: 1b3c0668c2af6ecd24eec20affa9da56b2418d4c37ffde60529f15072712213e
+  data.tar.gz: faac4c926f2db4c77533ed589042020e521686866334b4cb0fadf6fc9f69f71f
 SHA512:
-  metadata.gz: eb2815139791a2ed4abd5f09f6ed2b5cf27b89c399ed00276fc58e8ebfaceede00eb1b0cc02f43371ce5099d12467398e7ce92e58352cc854bb4b5eecc4a2c1c
-  data.tar.gz: 763ff525cdf09284bc3a7c3337407bfcaa8a750f5dddaeb66e1a1b082742a9e158b813a39a0d606c4c1740ba26137c6b565c6152688bd6f007b601ed98dd6fd1
+  metadata.gz: efe1e40e94d96b16dfe997386fd4f55c2e62bb994e9bd701c0466ce630470d9f0c723d141ec52565f151d0a869c7c47beae074a5f60b4b05d57fe2fcae261ad4
+  data.tar.gz: a5e2d49ec89a148cfec6678fc3099839f82095904eb84e2c828aeb1dfdc424fd8dee236d23434c5e3a4ef407c7ebf49350705410e82f6f873c70e4c19dd2dec2

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [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
+- `Legion::Apollo::Routes` Sinatra extension module (`lib/legion/apollo/routes.rb`): all `/api/apollo/*` route definitions extracted from `LegionIO/lib/legion/api/apollo.rb`. Self-registers with `Legion::API.register_library_routes('apollo', Legion::Apollo::Routes)` during `Legion::Apollo.start`, immediately after `@started` is set (before `Local.start` / `seed_self_knowledge`).
+- `register_routes` private method on `Legion::Apollo` module.
+
+### Changed
+- `Legion::Apollo.start` now calls `register_routes` after setting `@started = true`.
+
 ## [0.3.2] - 2026-03-26
 
 ### Added

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
@@ -84,6 +85,10 @@ module Legion
           query(text: text, limit: limit, **)
         end
 
+        def graph
+          Legion::Apollo::Local::Graph
+        end
+
         def reset!
           @started = false
           @seeded = false
@@ -190,7 +195,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 +261,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?
 

data/lib/legion/apollo/routes.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative 'helpers/tag_normalizer'
+
+# Self-registering route module for legion-apollo.
+# All routes previously defined in LegionIO/lib/legion/api/apollo.rb now live here
+# and are mounted via Legion::API.register_library_routes when legion-apollo boots.
+#
+# LegionIO/lib/legion/api/apollo.rb is preserved for backward compatibility but guards
+# its registration with defined?(Legion::Apollo::Routes) so double-registration is avoided.
+
+module Legion
+  module Apollo
+    # Sinatra route module for Apollo API endpoints. Self-registers at boot.
+    module Routes # rubocop:disable Metrics/ModuleLength
+      def self.registered(app)
+        app.helpers ApolloHelpers
+        register_status_route(app)
+        register_stats_route(app)
+        register_query_route(app)
+        register_ingest_route(app)
+        register_related_route(app)
+        register_maintenance_route(app)
+        register_graph_route(app)
+        register_expertise_route(app)
+      end
+
+      def self.register_status_route(app)
+        app.get '/api/apollo/status' do
+          available      = apollo_runner_available?
+          data_connected = apollo_data_connected?
+          status_code    = available && data_connected ? 200 : 503
+
+          json_response({ available: available, data_connected: data_connected },
+                        status_code: status_code)
+        end
+      end
+
+      def self.register_stats_route(app)
+        app.get '/api/apollo/stats' do
+          halt 503, json_error('apollo_unavailable', 'apollo is not available', status_code: 503) unless apollo_loaded?
+
+          stats = apollo_stats
+          if stats[:error]
+            halt 503, json_error('apollo_stats_unavailable', stats[:error], status_code: 503)
+          else
+            json_response(stats)
+          end
+        end
+      end
+
+      def self.register_query_route(app) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        app.post '/api/apollo/query' do
+          halt 503, json_error('apollo_unavailable', 'apollo is not available', status_code: 503) unless apollo_loaded?
+
+          body = parse_request_body
+          default_limit = defined?(Legion::Settings) ? (Legion::Settings[:apollo]&.dig(:default_limit) || 5) : 5
+          result = apollo_runner.handle_query(
+            query:          body[:query],
+            limit:          body[:limit] || default_limit,
+            min_confidence: body[:min_confidence] || 0.3,
+            status:         body[:status] || [:confirmed],
+            tags:           body[:tags],
+            domain:         body[:domain],
+            agent_id:       body[:agent_id] || 'api'
+          )
+          json_response(result)
+        end
+      end
+
+      def self.register_ingest_route(app) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        app.post '/api/apollo/ingest' do
+          halt 503, json_error('apollo_unavailable', 'apollo is not available', status_code: 503) unless apollo_loaded?
+
+          body = parse_request_body
+          max_tags = defined?(Legion::Settings) ? (Legion::Settings[:apollo]&.dig(:max_tags) || 20) : 20
+          # TagNormalizer hard-caps to MAX_TAGS=20 internally; clamp here to make that limit explicit.
+          effective_max_tags = [max_tags, Legion::Apollo::Helpers::TagNormalizer::MAX_TAGS].min
+          tags = Legion::Apollo::Helpers::TagNormalizer.normalize(Array(body[:tags])).first(effective_max_tags)
+          result = apollo_runner.handle_ingest(
+            content:          body[:content],
+            content_type:     body[:content_type] || :observation,
+            tags:             tags,
+            source_agent:     body[:source_agent] || 'api',
+            source_provider:  body[:source_provider],
+            source_channel:   body[:source_channel] || 'rest_api',
+            knowledge_domain: body[:knowledge_domain],
+            context:          body[:context] || {}
+          )
+          json_response(result, status_code: 201)
+        end
+      end
+
+      def self.register_related_route(app)
+        app.get '/api/apollo/entries/:id/related' do
+          halt 503, json_error('apollo_unavailable', 'apollo is not available', status_code: 503) unless apollo_loaded?
+
+          result = apollo_runner.related_entries(
+            entry_id:       params[:id].to_i,
+            relation_types: params[:relation_types]&.split(','),
+            depth:          (params[:depth] || 2).to_i
+          )
+          json_response(result)
+        end
+      end
+
+      def self.register_maintenance_route(app) # rubocop:disable Metrics/MethodLength
+        app.post '/api/apollo/maintenance' do
+          halt 503, json_error('apollo_unavailable', 'apollo is not available', status_code: 503) unless apollo_loaded?
+
+          body = parse_request_body
+          action_str = body[:action]
+          unless %w[
+            decay_cycle corroboration
+          ].include?(action_str)
+            halt 400,
+                 json_error('invalid_action', 'action must be decay_cycle or corroboration', status_code: 400)
+          end
+
+          action = action_str.to_sym
+
+          result = run_maintenance(action)
+          json_response(result)
+        end
+      end
+
+      def self.register_graph_route(app)
+        app.get '/api/apollo/graph' do
+          halt 503, json_error('apollo_unavailable', 'apollo is not available', status_code: 503) unless apollo_loaded?
+
+          json_response(apollo_graph_topology)
+        end
+      end
+
+      def self.register_expertise_route(app)
+        app.get '/api/apollo/expertise' do
+          halt 503, json_error('apollo_unavailable', 'apollo is not available', status_code: 503) unless apollo_loaded?
+
+          json_response(apollo_expertise_map)
+        end
+      end
+
+      class << self
+        private :register_status_route, :register_stats_route, :register_query_route,
+                :register_ingest_route, :register_related_route, :register_maintenance_route,
+                :register_graph_route, :register_expertise_route
+      end
+
+      # Helper methods mixed into the Sinatra app context
+      module ApolloHelpers
+        def apollo_runner_available?
+          return false unless defined?(Legion::Extensions::Apollo::Runners::Knowledge)
+
+          required = %i[handle_query handle_ingest related_entries]
+          required.all? { |m| Legion::Extensions::Apollo::Runners::Knowledge.respond_to?(m) }
+        rescue StandardError => e
+          if defined?(Legion::Logging)
+            Legion::Logging.debug("Apollo#apollo_runner_available? check failed: #{e.message}")
+          end
+          false
+        end
+
+        def apollo_loaded?
+          apollo_runner_available? && apollo_data_connected?
+        end
+
+        def apollo_data_connected?
+          defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && !Legion::Data.connection.nil?
+        rescue StandardError => e
+          Legion::Logging.debug("Apollo#apollo_data_connected? check failed: #{e.message}") if defined?(Legion::Logging)
+          false
+        end
+
+        def apollo_runner
+          Legion::Extensions::Apollo::Runners::Knowledge
+        end
+
+        def apollo_maintenance_runner # rubocop:disable Metrics/MethodLength
+          @apollo_maintenance_runner ||= begin
+            unless defined?(Legion::Extensions::Apollo::Runners::Maintenance)
+              halt 503, json_error('maintenance_unavailable', 'Apollo maintenance runner is not loaded')
+            end
+
+            runner = Object.new.extend(Legion::Extensions::Apollo::Runners::Maintenance)
+            required = %i[run_decay_cycle check_corroboration]
+            unless required.all? { |m| runner.respond_to?(m) }
+              halt 503, json_error('maintenance_unavailable', 'Apollo maintenance runner is missing required actions')
+            end
+
+            runner
+          end
+        end
+
+        def run_maintenance(action)
+          case action
+          when :decay_cycle
+            apollo_maintenance_runner.run_decay_cycle
+          when :corroboration
+            apollo_maintenance_runner.check_corroboration
+          end
+        end
+
+        def apollo_graph_topology
+          return { error: 'Apollo runner unavailable' } unless apollo_runner_available?
+          unless apollo_runner.respond_to?(:graph_topology)
+            return { error: 'Apollo graph_topology not supported by runner' }
+          end
+
+          apollo_runner.graph_topology
+        rescue StandardError => e
+          Legion::Logging.debug("Apollo#apollo_graph_topology failed: #{e.message}") if defined?(Legion::Logging)
+          { error: 'apollo_graph_topology unavailable' }
+        end
+
+        def apollo_expertise_map
+          return { error: 'Apollo runner unavailable' } unless apollo_runner_available?
+          unless apollo_runner.respond_to?(:expertise_map)
+            return { error: 'Apollo expertise_map not supported by runner' }
+          end
+
+          apollo_runner.expertise_map
+        rescue StandardError => e
+          Legion::Logging.debug("Apollo#apollo_expertise_map failed: #{e.message}") if defined?(Legion::Logging)
+          { error: 'apollo_expertise_map unavailable' }
+        end
+
+        def apollo_stats
+          return { total_entries: 0, error: 'Apollo runner unavailable' } unless apollo_runner_available?
+          unless apollo_runner.respond_to?(:stats)
+            return { total_entries: 0,
+                     error:         'Apollo stats not supported by runner' }
+          end
+
+          apollo_runner.stats
+        rescue StandardError => e
+          Legion::Logging.debug("Apollo#apollo_stats failed: #{e.message}") if defined?(Legion::Logging)
+          { total_entries: 0, error: 'apollo_stats unavailable' }
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Apollo
-    VERSION = '0.3.2'
+    VERSION = '0.3.5'
   end
 end

data/lib/legion/apollo.rb

@@ -5,6 +5,7 @@ require_relative 'apollo/version'
 require_relative 'apollo/settings'
 require_relative 'apollo/local'
 require_relative 'apollo/runners'
+require_relative 'apollo/routes'
 
 module Legion
   # Apollo client library — query, ingest, and retrieve with smart routing.
@@ -23,6 +24,7 @@ module Legion
         @started = true
         Legion::Logging.info 'Legion::Apollo started' if defined?(Legion::Logging)
 
+        register_routes
         Legion::Apollo::Local.start
         seed_self_knowledge
       end
@@ -87,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
@@ -307,6 +331,15 @@ module Legion
       def not_started_error
         { success: false, error: :not_started }
       end
+
+      def register_routes
+        return unless defined?(Legion::API) && Legion::API.respond_to?(:register_library_routes)
+
+        Legion::API.register_library_routes('apollo', Legion::Apollo::Routes)
+        Legion::Logging.debug 'Legion::Apollo routes registered with API' if defined?(Legion::Logging)
+      rescue StandardError => e
+        Legion::Logging.warn "Legion::Apollo route registration failed: #{e.message}" if defined?(Legion::Logging)
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-apollo
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.5
 platform: ruby
 authors:
 - Esity
@@ -81,11 +81,14 @@ files:
 - 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
 - lib/legion/apollo/messages/writeback.rb
+- lib/legion/apollo/routes.rb
 - lib/legion/apollo/runners.rb
 - lib/legion/apollo/runners/request.rb
 - lib/legion/apollo/settings.rb