legion-apollo 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c8e724eefe292faefec05ca4fc589ed935f4734bc5c4726b7c5d70ed3b69dbb
-  data.tar.gz: 3fc0246858d50305bd2d956e87c9ec844c71a769c4f81955f43d2640159a175c
+  metadata.gz: 56d4a2af4184bafd3474940f42a2b4e918490470b8faa3e5334f96bf27baff02
+  data.tar.gz: 6b4e4b7fcf9b93331de7e32214bee5415b0d6a47b20d4624894247c8350cc62c
 SHA512:
-  metadata.gz: eb2815139791a2ed4abd5f09f6ed2b5cf27b89c399ed00276fc58e8ebfaceede00eb1b0cc02f43371ce5099d12467398e7ce92e58352cc854bb4b5eecc4a2c1c
-  data.tar.gz: 763ff525cdf09284bc3a7c3337407bfcaa8a750f5dddaeb66e1a1b082742a9e158b813a39a0d606c4c1740ba26137c6b565c6152688bd6f007b601ed98dd6fd1
+  metadata.gz: 05a8fc891f57c4e9d71619c993c343753cc7674984847224957aa7f5621faa240b9d9017bdf9bd277a17ed1ef39d626229ac9058e66da55d7a477a47aa8b5c51
+  data.tar.gz: d80855fc0f2026c2035fd2b411a2d6daaa3684125455fa46ab161dbae0e9831d00437be0faa171718cbf811d5834a1ddd138e491891c96ad87d428ae4ce2f15d

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [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/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.3'
   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
@@ -307,6 +309,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.3
 platform: ruby
 authors:
 - Esity
@@ -86,6 +86,7 @@ files:
 - 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