legion-apollo 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 63a18f390ea4ed531450615fbff3877951d39b6a4d60bdf5fbee72a2572f3817
+  data.tar.gz: 9220f43c2c962e936d82257b8e944fb9b82fd7e1c306fbb8462a3323e6e37de6
+SHA512:
+  metadata.gz: '08e857932f343c0b7a5d8ec98abb1e2c2bbb4c4ba3953ef9ae33927b6a0f1861901f8646f900fba9fc233f99737805b355fa0f0176c11771fc664fe97ee54214'
+  data.tar.gz: 1d2bc1a4f9d9bf637731c48061bda8e442316feeb4a0eb29ccf0546d20ea1363be795c737079730706707659b1beef7cb81de63087ff4944084c25a9320e9eda

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.3.0] - 2026-03-25
+
+### Added
+- `Legion::Apollo::Local` — node-local knowledge store backed by SQLite + FTS5
+- Local settings defaults (retention_years, default_query_scope, fts_candidate_multiplier)
+- SQLite migration with FTS5 virtual table for full-text search
+- Ingest with content hash dedup, optional LLM embedding, configurable TTL (5-year default)
+- Query with FTS5 keyword search, tag filtering, confidence gating, cosine rerank
+- `embedded_at` column for future embedding backfill identification
+- `.local` accessor on `Legion::Apollo` module
+
+## [0.2.1] - 2026-03-25
+
+### Added
+- Initial gem scaffold: `Legion::Apollo` public API (`start`, `shutdown`, `query`, `ingest`, `retrieve`)
+- `Legion::Apollo::Settings` with default configuration values
+- Transport message envelope classes: `Ingest`, `Query`, `Writeback`, `AccessBoost`
+- Helper modules: `Confidence` constants, `Similarity` math, `TagNormalizer`
+- Smart routing: co-located lex-apollo service, RabbitMQ transport, graceful failure

data/LICENSE

@@ -0,0 +1,168 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and the Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal, or
+      written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of developing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combined work (in which such
+      Contribution(s) were submitted). If You institute patent litigation
+      against any entity (including a cross-claim or counterclaim in a
+      lawsuit) alleging that the Work or any of its copyright or other
+      intellectual property right is a patent claim is infringed by
+      the Work or any Contribution incorporated within the Work, a
+      patent license shall automatically terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, and to permit persons to whom the Contribution is
+      furnished to do so.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer, and
+      charge a fee for, acceptance of support, warranty, indemnity, or
+      other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions consistent with this terms of this License, and may not
+      impose any additional obligations.
+
+   END OF TERMS AND CONDITIONS

data/README.md

@@ -0,0 +1,18 @@
+# legion-apollo
+
+Apollo client library for the LegionIO framework.
+
+Provides `query`, `ingest`, and `retrieve` with smart routing: co-located lex-apollo service, RabbitMQ transport, or graceful failure.
+
+## Usage
+
+```ruby
+Legion::Apollo.start
+
+Legion::Apollo.ingest(content: 'Some knowledge', tags: %w[fact ruby])
+results = Legion::Apollo.query(text: 'tell me about ruby', limit: 5)
+```
+
+## License
+
+Apache-2.0

data/lib/legion/apollo/helpers/confidence.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    module Helpers
+      # Confidence constants and predicate helpers for Apollo knowledge entries.
+      # DB-dependent methods live in lex-apollo; only pure-function logic here.
+      module Confidence
+        INITIAL_CONFIDENCE     = 0.5
+        CORROBORATION_BOOST    = 0.15
+        CONTRADICTION_PENALTY  = 0.20
+        DECAY_RATE             = 0.005
+        WRITE_GATE_THRESHOLD   = 0.3
+        HIGH_CONFIDENCE        = 0.8
+        ARCHIVE_THRESHOLD      = 0.1
+
+        STATUSES = %i[pending confirmed disputed deprecated archived].freeze
+
+        CONTENT_TYPES = %i[
+          fact observation hypothesis procedure opinion
+          question answer summary analysis synthesis
+        ].freeze
+
+        module_function
+
+        def valid_status?(status)
+          STATUSES.include?(status&.to_sym)
+        end
+
+        def valid_content_type?(type)
+          CONTENT_TYPES.include?(type&.to_sym)
+        end
+
+        def above_write_gate?(confidence)
+          confidence.to_f >= WRITE_GATE_THRESHOLD
+        end
+
+        def high_confidence?(confidence)
+          confidence.to_f >= HIGH_CONFIDENCE
+        end
+
+        def apollo_setting(key, default)
+          return default unless defined?(Legion::Settings) && !Legion::Settings[:apollo].nil?
+
+          Legion::Settings[:apollo][key] || default
+        rescue StandardError
+          default
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/helpers/similarity.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    module Helpers
+      # Pure cosine similarity math and match classification for Apollo vectors.
+      module Similarity
+        EXACT_MATCH_THRESHOLD     = 0.95
+        HIGH_SIMILARITY_THRESHOLD = 0.85
+        CORROBORATION_THRESHOLD   = 0.75
+        RELATED_THRESHOLD         = 0.5
+
+        module_function
+
+        def cosine_similarity(vec_a, vec_b) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          return 0.0 if vec_a.nil? || vec_b.nil? || vec_a.empty? || vec_b.empty?
+          return 0.0 unless vec_a.size == vec_b.size
+
+          dot = 0.0
+          mag_a = 0.0
+          mag_b = 0.0
+
+          vec_a.size.times do |i|
+            a = vec_a[i].to_f
+            b = vec_b[i].to_f
+            dot   += a * b
+            mag_a += a * a
+            mag_b += b * b
+          end
+
+          denom = Math.sqrt(mag_a) * Math.sqrt(mag_b)
+          denom.zero? ? 0.0 : (dot / denom)
+        end
+
+        def classify_match(similarity)
+          case similarity
+          when EXACT_MATCH_THRESHOLD..1.0                          then :exact
+          when HIGH_SIMILARITY_THRESHOLD...EXACT_MATCH_THRESHOLD   then :high
+          when CORROBORATION_THRESHOLD...HIGH_SIMILARITY_THRESHOLD  then :corroboration
+          when RELATED_THRESHOLD...CORROBORATION_THRESHOLD          then :related
+          else :unrelated
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/helpers/tag_normalizer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    module Helpers
+      # Pure-function tag normalization: lowercase, strip invalid chars, dedup, truncate.
+      module TagNormalizer
+        MAX_TAG_LENGTH = 64
+        MAX_TAGS       = 20
+
+        module_function
+
+        def normalize(tags)
+          return [] unless tags.is_a?(Array)
+
+          tags
+            .map { |t| normalize_one(t) }
+            .compact
+            .uniq
+            .first(MAX_TAGS)
+        end
+
+        def normalize_one(tag)
+          return nil if tag.nil?
+
+          normalized = tag.to_s.strip.downcase.gsub(/[^a-z0-9_:-]/, '_').squeeze('_')
+          normalized = normalized[0, MAX_TAG_LENGTH] if normalized.length > MAX_TAG_LENGTH
+          normalized.empty? ? nil : normalized
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/local/migrations/001_create_local_knowledge.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+Sequel.migration do # rubocop:disable Metrics/BlockLength
+  up do
+    create_table(:local_knowledge) do
+      primary_key :id
+      String   :content,        null: false, text: true
+      String   :content_hash,   null: false, size: 32
+      String   :tags,           text: true
+      String   :embedding,      text: true
+      String   :embedded_at
+      String   :source_channel
+      String   :source_agent
+      String   :submitted_by
+      Float    :confidence,     default: 1.0
+      String   :expires_at,     null: false
+      String   :created_at,     null: false
+      String   :updated_at,     null: false
+
+      unique :content_hash, name: :idx_local_knowledge_hash
+      index :expires_at, name: :idx_local_knowledge_expires
+      index :embedded_at, name: :idx_local_knowledge_embedded
+    end
+
+    fts_sql = 'CREATE VIRTUAL TABLE IF NOT EXISTS local_knowledge_fts ' \
+              "USING fts5(content, tags, content='local_knowledge', content_rowid='id')"
+    run fts_sql
+  end
+
+  down do
+    run 'DROP TABLE IF EXISTS local_knowledge_fts'
+    drop_table(:local_knowledge) if table_exists?(:local_knowledge)
+  end
+end

data/lib/legion/apollo/local.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'time'
+
+module Legion
+  module Apollo
+    # Node-local knowledge store backed by SQLite + FTS5.
+    # Mirrors Legion::Apollo's public API but stores locally.
+    module Local # rubocop:disable Metrics/ModuleLength
+      MIGRATION_PATH = File.expand_path('local/migrations', __dir__).freeze
+
+      class << self # rubocop:disable Metrics/ClassLength
+        def start
+          return if @started
+          return unless local_enabled?
+          return unless data_local_available?
+
+          Legion::Data::Local.register_migrations(name: :apollo_local, path: MIGRATION_PATH)
+          @started = true
+          Legion::Logging.info 'Legion::Apollo::Local started' if defined?(Legion::Logging)
+        end
+
+        def shutdown
+          @started = false
+          Legion::Logging.info 'Legion::Apollo::Local shutdown' if defined?(Legion::Logging)
+        end
+
+        def started?
+          @started == true
+        end
+
+        def ingest(content:, tags: [], **opts) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          return not_started_error unless started?
+
+          hash = content_hash(content)
+          return { success: true, mode: :deduplicated } if duplicate?(hash)
+
+          embedding, embedded_at = generate_embedding(content)
+          now = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+          expires = compute_expires_at
+
+          row = {
+            content:        content,
+            content_hash:   hash,
+            tags:           Legion::JSON.dump(Array(tags).first(local_setting(:max_tags, 20))),
+            embedding:      embedding ? Legion::JSON.dump(embedding) : nil,
+            embedded_at:    embedded_at,
+            source_channel: opts[:source_channel],
+            source_agent:   opts[:source_agent],
+            submitted_by:   opts[:submitted_by],
+            confidence:     opts[:confidence] || 1.0,
+            expires_at:     expires,
+            created_at:     now,
+            updated_at:     now
+          }
+
+          id = db[:local_knowledge].insert(row)
+          sync_fts(id, content, row[:tags])
+
+          { success: true, mode: :local, id: id }
+        rescue StandardError => e
+          { 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?
+
+          limit ||= local_setting(:default_limit, 5)
+          min_confidence ||= local_setting(:min_confidence, 0.3)
+          multiplier = local_setting(:fts_candidate_multiplier, 3)
+
+          candidates = fts_search(text, limit: limit * multiplier)
+          candidates = filter_candidates(candidates, min_confidence: min_confidence, tags: tags)
+          candidates = cosine_rerank(text, candidates) if can_rerank?
+          results = candidates.first(limit)
+
+          { success: true, results: results, count: results.size, mode: :local }
+        rescue StandardError => e
+          { success: false, error: e.message }
+        end
+
+        def retrieve(text:, limit: 5, **)
+          query(text: text, limit: limit, **)
+        end
+
+        def reset!
+          @started = false
+        end
+
+        private
+
+        def local_enabled?
+          return false unless defined?(Legion::Settings)
+
+          settings = Legion::Settings[:apollo]
+          return true if settings.nil?
+
+          local = settings[:local]
+          return true if local.nil?
+
+          local[:enabled] != false
+        rescue StandardError
+          true
+        end
+
+        def data_local_available?
+          defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+        rescue StandardError
+          false
+        end
+
+        def db
+          Legion::Data::Local.connection
+        end
+
+        def content_hash(content)
+          normalized = content.to_s.strip.downcase.gsub(/\s+/, ' ')
+          Digest::MD5.hexdigest(normalized)
+        end
+
+        def duplicate?(hash)
+          db[:local_knowledge].where(content_hash: hash).any?
+        rescue StandardError
+          false
+        end
+
+        def generate_embedding(content) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          unless defined?(Legion::LLM) && Legion::LLM.respond_to?(:can_embed?) && Legion::LLM.can_embed?
+            return [nil, nil]
+          end
+
+          result = Legion::LLM::Embeddings.generate(text: 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')]
+          else
+            [nil, nil]
+          end
+        rescue StandardError
+          [nil, nil]
+        end
+
+        def compute_expires_at
+          years = local_setting(:retention_years, 5)
+          (Time.now.utc + (years * 365.25 * 24 * 3600)).strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+        end
+
+        def sync_fts(id, content, tags_json)
+          sql = 'INSERT INTO local_knowledge_fts(rowid, content, tags) ' \
+                "VALUES (#{id}, #{db.literal(content)}, #{db.literal(tags_json)})"
+          db.run(sql)
+        rescue StandardError => e
+          Legion::Logging.warn("FTS5 sync failed for id=#{id}: #{e.message}") if defined?(Legion::Logging)
+        end
+
+        def fts_search(text, limit:) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          escaped = text.to_s.gsub('"', '""')
+          now = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+          db.fetch(
+            'SELECT lk.* FROM local_knowledge lk ' \
+            'INNER JOIN local_knowledge_fts fts ON lk.id = fts.rowid ' \
+            'WHERE local_knowledge_fts MATCH ? AND lk.expires_at > ? ORDER BY fts.rank LIMIT ?',
+            escaped, now, limit
+          ).all
+        rescue StandardError
+          db[:local_knowledge]
+            .where(Sequel.lit('expires_at > ?', Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')))
+            .where(Sequel.ilike(:content, "%#{text}%"))
+            .limit(limit)
+            .all
+        end
+
+        def filter_candidates(candidates, min_confidence:, tags:)
+          candidates = candidates.select { |c| (c[:confidence] || 0) >= min_confidence }
+          if tags && !tags.empty?
+            tag_set = Array(tags).map(&:to_s)
+            candidates = candidates.select do |c|
+              entry_tags = parse_tags(c[:tags])
+              tag_set.intersect?(entry_tags)
+            end
+          end
+          candidates
+        end
+
+        def parse_tags(tags_json)
+          return [] if tags_json.nil? || tags_json.empty?
+
+          ::JSON.parse(tags_json)
+        rescue StandardError
+          []
+        end
+
+        def can_rerank?
+          defined?(Legion::LLM) && Legion::LLM.respond_to?(:can_embed?) && Legion::LLM.can_embed?
+        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_vec = query_result.is_a?(Hash) ? query_result[:vector] : query_result
+          return candidates unless query_vec.is_a?(Array) && query_vec.any?
+
+          scored = candidates.map do |c|
+            entry_vec = parse_embedding(c[:embedding])
+            score = if entry_vec
+                      Legion::Apollo::Helpers::Similarity.cosine_similarity(query_vec, entry_vec)
+                    else
+                      0.0
+                    end
+            c.merge(similarity: score)
+          end
+
+          scored.sort_by { |c| -(c[:similarity] || 0) }
+        rescue StandardError
+          candidates
+        end
+
+        def parse_embedding(embedding_json)
+          return nil if embedding_json.nil? || embedding_json.empty?
+
+          parsed = ::JSON.parse(embedding_json)
+          parsed.is_a?(Array) ? parsed.map(&:to_f) : nil
+        rescue StandardError
+          nil
+        end
+
+        def local_setting(key, default)
+          return default unless defined?(Legion::Settings) && !Legion::Settings[:apollo].nil?
+
+          local = Legion::Settings[:apollo][:local]
+          return default if local.nil?
+
+          local[key] || default
+        rescue StandardError
+          default
+        end
+
+        def not_started_error
+          { success: false, error: :not_started }
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/messages/access_boost.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    module Messages
+      # Envelope for publishing access-frequency boost events to the Apollo exchange.
+      class AccessBoost
+        ROUTING_KEY = 'apollo.access.boost'
+        EXCHANGE    = 'apollo'
+
+        def publish(payload)
+          return unless defined?(Legion::Transport)
+
+          exchange = Legion::Transport::Exchange.new(EXCHANGE, type: :topic, auto_delete: false)
+          exchange.publish(payload, routing_key: ROUTING_KEY)
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/messages/ingest.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    module Messages
+      # Envelope for publishing knowledge ingest requests to the Apollo exchange.
+      class Ingest
+        ROUTING_KEY = 'apollo.ingest'
+        EXCHANGE    = 'apollo'
+
+        def publish(payload)
+          return unless defined?(Legion::Transport)
+
+          exchange = Legion::Transport::Exchange.new(EXCHANGE, type: :topic, auto_delete: false)
+          exchange.publish(payload, routing_key: ROUTING_KEY)
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/messages/query.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    module Messages
+      # Envelope for publishing knowledge query requests to the Apollo exchange.
+      class Query
+        ROUTING_KEY = 'apollo.query'
+        EXCHANGE    = 'apollo'
+
+        def publish(payload)
+          return unless defined?(Legion::Transport)
+
+          exchange = Legion::Transport::Exchange.new(EXCHANGE, type: :topic, auto_delete: false)
+          exchange.publish(payload, routing_key: ROUTING_KEY)
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/messages/writeback.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    module Messages
+      # Envelope for publishing knowledge writeback events to the Apollo exchange.
+      class Writeback
+        ROUTING_KEY = 'apollo.writeback'
+        EXCHANGE    = 'apollo'
+
+        def publish(payload)
+          return unless defined?(Legion::Transport)
+
+          exchange = Legion::Transport::Exchange.new(EXCHANGE, type: :topic, auto_delete: false)
+          exchange.publish(payload, routing_key: ROUTING_KEY)
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/settings.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    # Default configuration values for the Apollo client.
+    module Settings
+      def self.default
+        {
+          enabled:        true,
+          transport_mode: :auto,
+          query_timeout:  5,
+          ingest_timeout: 10,
+          max_tags:       20,
+          default_limit:  5,
+          min_confidence: 0.3,
+          local:          local_defaults
+        }
+      end
+
+      def self.local_defaults
+        {
+          enabled:                  true,
+          retention_years:          5,
+          default_query_scope:      :all,
+          fts_candidate_multiplier: 3,
+          min_confidence:           0.3,
+          default_limit:            5
+        }
+      end
+    end
+  end
+end

data/lib/legion/apollo/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    VERSION = '0.3.0'
+  end
+end

data/lib/legion/apollo.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative 'apollo/version'
+require_relative 'apollo/settings'
+require_relative 'apollo/local'
+
+module Legion
+  # Apollo client library — query, ingest, and retrieve with smart routing.
+  # Routes to a co-located lex-apollo service when available, falls back to
+  # RabbitMQ transport, and degrades gracefully when neither is present.
+  module Apollo # rubocop:disable Metrics/ModuleLength
+    class << self # rubocop:disable Metrics/ClassLength
+      def start
+        return if @started
+
+        merge_settings
+        detect_transport
+        detect_data
+
+        @started = true
+        Legion::Logging.info 'Legion::Apollo started' if defined?(Legion::Logging)
+      end
+
+      def shutdown
+        @started = false
+        @transport_available = nil
+        @data_available = nil
+        Legion::Logging.info 'Legion::Apollo shutdown' if defined?(Legion::Logging)
+      end
+
+      def started?
+        @started == true
+      end
+
+      def local
+        Legion::Apollo::Local
+      end
+
+      def query(text:, limit: nil, min_confidence: nil, tags: nil, **opts) # rubocop:disable Metrics/MethodLength
+        return not_started_error unless started?
+
+        limit ||= apollo_setting(:default_limit, 5)
+        min_confidence ||= apollo_setting(:min_confidence, 0.3)
+
+        payload = { text: text, limit: limit, min_confidence: min_confidence, tags: tags, **opts }
+
+        if co_located_reader?
+          direct_query(payload)
+        elsif transport_available?
+          publish_query(payload)
+        else
+          { success: false, error: :no_path_available }
+        end
+      end
+
+      def ingest(content:, tags: [], **opts)
+        return not_started_error unless started?
+
+        payload = { content: content, tags: Array(tags).first(apollo_setting(:max_tags, 20)), **opts }
+
+        if co_located_writer?
+          direct_ingest(payload)
+        elsif transport_available?
+          publish_ingest(payload)
+        else
+          { success: false, error: :no_path_available }
+        end
+      end
+
+      def retrieve(text:, limit: 5, **)
+        query(text: text, limit: limit, **)
+      end
+
+      def transport_available?
+        @transport_available == true
+      end
+
+      def data_available?
+        @data_available == true
+      end
+
+      private
+
+      def merge_settings
+        return unless defined?(Legion::Settings)
+
+        defaults = Legion::Apollo::Settings.default
+        Legion::Settings[:apollo] = defaults.merge(Legion::Settings[:apollo] || {})
+      rescue StandardError => e
+        Legion::Logging.debug("Apollo settings merge failed: #{e.message}") if defined?(Legion::Logging)
+      end
+
+      def detect_transport
+        @transport_available = defined?(Legion::Transport) &&
+                               Legion::Settings[:transport][:connected] == true
+      rescue StandardError
+        @transport_available = false
+      end
+
+      def detect_data
+        @data_available = defined?(Legion::Data) &&
+                          Legion::Settings[:data][:connected] == true
+      rescue StandardError
+        @data_available = false
+      end
+
+      def co_located_reader?
+        return false unless data_available?
+
+        defined?(Legion::Extensions::Apollo::Runners::Knowledge) &&
+          Legion::Extensions::Apollo::Runners::Knowledge.respond_to?(:handle_query)
+      rescue StandardError
+        false
+      end
+
+      def co_located_writer?
+        return false unless data_available?
+
+        defined?(Legion::Extensions::Apollo::Runners::Knowledge) &&
+          Legion::Extensions::Apollo::Runners::Knowledge.respond_to?(:handle_ingest)
+      rescue StandardError
+        false
+      end
+
+      def direct_query(payload)
+        Legion::Extensions::Apollo::Runners::Knowledge.handle_query(**payload)
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
+      def direct_ingest(payload)
+        Legion::Extensions::Apollo::Runners::Knowledge.handle_ingest(**payload)
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
+      def publish_query(payload)
+        require_relative 'apollo/messages/query' unless defined?(Legion::Apollo::Messages::Query)
+        Legion::Apollo::Messages::Query.new.publish(Legion::JSON.dump(payload))
+        { success: true, mode: :async }
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
+      def publish_ingest(payload)
+        require_relative 'apollo/messages/ingest' unless defined?(Legion::Apollo::Messages::Ingest)
+        Legion::Apollo::Messages::Ingest.new.publish(Legion::JSON.dump(payload))
+        { success: true, mode: :async }
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
+      def apollo_setting(key, default)
+        return default unless defined?(Legion::Settings) && !Legion::Settings[:apollo].nil?
+
+        Legion::Settings[:apollo][key] || default
+      rescue StandardError
+        default
+      end
+
+      def not_started_error
+        { success: false, error: :not_started }
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: legion-apollo
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: legion-logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+- !ruby/object:Gem::Dependency
+  name: legion-settings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+description: Client-side Apollo knowledge store API for LegionIO. Provides query,
+  ingest, and retrieve with smart routing (co-located service, RabbitMQ, or graceful
+  failure).
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE
+- README.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/migrations/001_create_local_knowledge.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/settings.rb
+- lib/legion/apollo/version.rb
+homepage: https://github.com/LegionIO/legion-apollo
+licenses:
+- Apache-2.0
+metadata:
+  bug_tracker_uri: https://github.com/LegionIO/legion-apollo/issues
+  changelog_uri: https://github.com/LegionIO/legion-apollo/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/LegionIO/LegionIO
+  source_code_uri: https://github.com/LegionIO/legion-apollo
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Apollo client library for the LegionIO framework
+test_files: []