lex-llm-bedrock 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e65f38c28a0411727577216ea5bc01057520cd14e110fdb88d02da6248125aad
-  data.tar.gz: d93dfe83c8e3acf0944518c1e964ddcccda59301a6a83460bff4618a883f34d8
+  metadata.gz: 61bd89194ee181746dc54c6b898bf31b4b8d599a01121bcec9a0dbd8b80d3b5c
+  data.tar.gz: 97ab9f39bec79114152b42d8fdf8f996a50b4b1ac94dcb1a230049ccd8d08398
 SHA512:
-  metadata.gz: 772d8484c70e24d732e74d751fed2264c253cdbc245d91d39c5aa0e642f0c3828fe144da025fd5237c33e694bb8ab7e9fa5dd009092ea40e75009eca34250b53
-  data.tar.gz: a00538ee0875ea03b3c25b163eecf791107b6a8ed8ec48a705b9cb9a0f7af32a4abcc5c1c968031eb43b736249acfe55bfefe08f6b8647a5476b775c67318336
+  metadata.gz: 441194151664025152b62567db2f84d9b406779502f560c9f8b0a41c891ec8f487624a8fd5bf3d6a7c86172b15a5f218bfa38c9f847d7a7bdec5db49e678ccca
+  data.tar.gz: 7676dff0e80cc6a3a0589a01acc723b7920c3d59193936c2f5a8bc89444957f1f43e9cf8b003ab19badd21720a74a26d8b3046d7e673c1333a1fca458b12af43

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.5 - 2026-04-30
+
+- Audit logging, rescue blocks, and README for full observability.
+- Add `include Legion::Logging::Helper` to Provider, RegistryPublisher, and RegistryEventBuilder.
+- Replace all bare rescue blocks with `handle_exception(e, level:, handled:, operation:)` calls.
+- Add `log.info` for key actions: chat, stream, embed, health, discovery, list_models.
+- Remove custom `log_publish_failure` method in favor of standard `handle_exception`.
+- Update README with architecture, file map, dependency table, and development guide.
+
 ## 0.1.4 - 2026-04-30
 
 - Add headers: parameter to complete method signature matching base provider contract

data/README.md

@@ -4,6 +4,48 @@ Amazon Bedrock provider extension for `Legion::Extensions::Llm`.
 
 This gem adds a hosted Bedrock provider surface for Legion LLM routing without depending on the old `legion-llm` gem. It uses the official AWS SDK for Ruby and keeps discovery offline by default, so loading the extension or running tests does not require live AWS credentials. It requires `lex-llm >= 0.1.5` for the shared model offering, alias, readiness, and fleet lane contract.
 
+## Architecture
+
+```
+Legion::Extensions::Llm::Bedrock
+├── Provider               # Bedrock implementation of the lex-llm Provider contract
+│   ├── Capabilities       # Capability predicates inferred from model IDs
+│   ├── chat / stream      # Converse / ConverseStream API calls
+│   ├── embed              # Titan InvokeModel embedding
+│   ├── count_tokens       # CountTokens API call
+│   ├── discover_offerings # Static catalog + live ListFoundationModels
+│   ├── health / readiness # Provider health checks with live AWS verification
+│   └── list_models        # Live model enumeration
+├── RegistryEventBuilder   # Builds sanitized lex-llm registry envelopes
+├── RegistryPublisher      # Best-effort async publisher for registry events
+└── Transport
+    ├── Exchanges::LlmRegistry    # Topic exchange for llm.registry events
+    └── Messages::RegistryEvent   # AMQP message for registry event publishing
+```
+
+## Dependencies
+
+| Gem | Required | Purpose |
+|-----|----------|---------|
+| `aws-sdk-bedrock` | Yes | Bedrock management client (ListFoundationModels) |
+| `aws-sdk-bedrockruntime` | Yes | Bedrock runtime client (Converse, InvokeModel) |
+| `legion-json` (>= 1.2.1) | Yes | JSON serialization |
+| `legion-logging` (>= 1.3.2) | Yes | Structured logging via Helper |
+| `legion-settings` (>= 1.3.14) | Yes | Configuration |
+| `lex-llm` (>= 0.1.5) | Yes | Shared provider contract, model offerings, routing |
+
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/extensions/llm/bedrock.rb` | Entry point: namespace, default settings, provider registration |
+| `lib/legion/extensions/llm/bedrock/provider.rb` | Full Bedrock provider implementation |
+| `lib/legion/extensions/llm/bedrock/registry_event_builder.rb` | Builds lex-llm registry event envelopes |
+| `lib/legion/extensions/llm/bedrock/registry_publisher.rb` | Best-effort async registry event publishing |
+| `lib/legion/extensions/llm/bedrock/transport/exchanges/llm_registry.rb` | AMQP topic exchange definition |
+| `lib/legion/extensions/llm/bedrock/transport/messages/registry_event.rb` | AMQP message class for registry events |
+| `lib/legion/extensions/llm/bedrock/version.rb` | `VERSION` constant |
+
 ## Install
 
 ```ruby
@@ -31,6 +73,8 @@ If explicit keys are not configured, the AWS SDK default credential provider cha
 Legion::Extensions::Llm::Bedrock.default_settings
 ```
 
+Configuration options: `bedrock_region`, `bedrock_endpoint`, `bedrock_access_key_id`, `bedrock_secret_access_key`, `bedrock_session_token`, `bedrock_profile`, `bedrock_stub_responses`.
+
 ## Provider Surface
 
 ```ruby
@@ -58,6 +102,8 @@ Every offering uses:
 
 Known aliases are intentionally small and conservative. For example, `claude-3-haiku` resolves to `anthropic.claude-3-haiku-20240307-v1:0`, while the preserved Bedrock model ID remains the routing model.
 
+Static models: `claude-3-haiku`, `titan-text-express`, `titan-embed-text-v2`, `llama-3.2-11b-instruct`, `mistral-large-3`.
+
 ## API Contract
 
 The implementation is intentionally limited to Bedrock operations documented by AWS:
@@ -70,10 +116,31 @@ The implementation is intentionally limited to Bedrock operations documented by
 
 Provider-specific request bodies are not guessed. Non-Titan embedding models raise until their documented body shape is added explicitly.
 
-AWS references:
+## Observability
+
+All classes include `Legion::Logging::Helper` for structured logging:
+
+- **Info-level**: provider connections, API calls (chat, stream, embed), model listing, health checks
+- **Debug-level**: offline health checks, readiness probes, token counting, registry event scheduling
+- **Rescue blocks**: every rescue calls `handle_exception(e, level:, handled:, operation:)` with dot-separated operation names (e.g., `bedrock.provider.health`, `bedrock.registry_publisher.publish_event`)
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec --format progress  # all pass
+bundle exec rubocop -A               # auto-fix
+bundle exec rubocop                  # lint check (0 offenses expected)
+```
+
+## AWS References
 
 - [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html)
 - [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)
 - [CountTokens](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_CountTokens.html)
 - [ListFoundationModels](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_ListFoundationModels.html)
 - [Foundation model information](https://docs.aws.amazon.com/bedrock/latest/userguide/foundation-models-reference.html)
+
+## License
+
+MIT

data/lib/legion/extensions/llm/bedrock/provider.rb

@@ -12,6 +12,8 @@ module Legion
       module Bedrock
         # Amazon Bedrock provider implementation for the Legion::Extensions::Llm contract.
         class Provider < Legion::Extensions::Llm::Provider # rubocop:disable Metrics/ClassLength
+          include Legion::Logging::Helper
+
           DEFAULT_REGION = 'us-east-1'
 
           STATIC_MODELS = [
@@ -85,10 +87,15 @@ module Legion
           end
 
           def discover_offerings(live: false, **filters)
-            return static_offerings(**filters) unless live
+            unless live
+              log.debug { 'bedrock.provider.discover_offerings: returning static catalog' }
+              return static_offerings(**filters)
+            end
 
+            log.info { "bedrock.provider.discover_offerings: listing foundation models (region=#{region})" }
             response = bedrock_client.list_foundation_models(**filters)
             Array(value(response, :model_summaries)).map { |summary| offering_from_summary(summary) }.tap do |offerings|
+              log.info { "bedrock.provider.discover_offerings: found #{offerings.size} models" }
               self.class.registry_publisher.publish_offerings_async(offerings, readiness: readiness(live: false))
             end
           end
@@ -114,15 +121,22 @@ module Legion
               live: live,
               credentials: credential_source
             }
-            return baseline.merge(checked: false) unless live
+            unless live
+              log.debug { "bedrock.provider.health: offline check (region=#{region})" }
+              return baseline.merge(checked: false)
+            end
 
+            log.info { "bedrock.provider.health: live check (region=#{region})" }
             bedrock_client.list_foundation_models
+            log.info { 'bedrock.provider.health: live check passed' }
             baseline.merge(checked: true)
           rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'bedrock.provider.health')
             baseline.merge(checked: true, ready: false, error: e.class.name, message: e.message)
           end
 
           def readiness(live: false)
+            log.debug { "bedrock.provider.readiness: checking (live=#{live})" }
             health(live: live).merge(local: false, remote: true, api_base: api_base,
                                      endpoints: endpoint_manifest).tap do |metadata|
               self.class.registry_publisher.publish_readiness_async(metadata) if live
@@ -130,6 +144,7 @@ module Legion
           end
 
           def list_models
+            log.info { 'bedrock.provider.list_models: fetching live model list' }
             discover_offerings(live: true).map do |offering|
               Legion::Extensions::Llm::Model::Info.new(
                 id: offering.model,
@@ -143,6 +158,7 @@ module Legion
           end
 
           def chat(messages, model:, temperature: nil, max_tokens: nil, tools: {}, tool_prefs: nil, params: {})
+            log.info { "bedrock.provider.chat: model=#{model_id(model)} messages=#{messages.size}" }
             request = Utils.deep_merge(
               converse_request(messages, model:, temperature:, max_tokens:, tools:, tool_prefs:),
               params
@@ -152,6 +168,7 @@ module Legion
 
           def stream(messages, model:, temperature: nil, max_tokens: nil, tools: {}, tool_prefs: nil, params: {},
                      &)
+            log.info { "bedrock.provider.stream: model=#{model_id(model)} messages=#{messages.size}" }
             request = Utils.deep_merge(
               converse_request(messages, model:, temperature:, max_tokens:, tools:, tool_prefs:),
               params
@@ -160,6 +177,7 @@ module Legion
           end
 
           def count_tokens(messages, model:, system: nil, params: {})
+            log.debug { "bedrock.provider.count_tokens: model=#{model_id(model)}" }
             request = Utils.deep_merge(
               {
                 model_id: model_id(model),
@@ -172,20 +190,21 @@ module Legion
           end
 
           def embed(text, model:, dimensions: nil)
-            model_id = model_id(model)
-            unless titan_embed?(model_id)
+            mid = model_id(model)
+            unless titan_embed?(mid)
               raise NotImplementedError,
-                    "Bedrock embedding payload for #{model_id} is not standardized"
+                    "Bedrock embedding payload for #{mid} is not standardized"
             end
 
+            log.info { "bedrock.provider.embed: model=#{mid}" }
             body = { inputText: text, dimensions: dimensions }.compact
             response = runtime_client.invoke_model(
-              model_id: model_id,
+              model_id: mid,
               content_type: 'application/json',
               accept: 'application/json',
               body: Legion::JSON.generate(body)
             )
-            parse_embedding_response(response, model: model_id)
+            parse_embedding_response(response, model: mid)
           end
 
           def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, thinking: nil, # rubocop:disable Lint/UnusedMethodArgument

data/lib/legion/extensions/llm/bedrock/registry_event_builder.rb

@@ -6,6 +6,8 @@ module Legion
       module Bedrock
         # Builds sanitized lex-llm registry envelopes for Bedrock provider state.
         class RegistryEventBuilder
+          include Legion::Logging::Helper
+
           def readiness(readiness)
             registry_event_class.public_send(
               readiness[:ready] ? :available : :unavailable,

data/lib/legion/extensions/llm/bedrock/registry_publisher.rb

@@ -6,6 +6,8 @@ module Legion
       module Bedrock
         # Best-effort publisher for Bedrock provider availability events.
         class RegistryPublisher
+          include Legion::Logging::Helper
+
           APP_ID = 'lex-llm-bedrock'
 
           def initialize(builder: RegistryEventBuilder.new)
@@ -13,10 +15,14 @@ module Legion
           end
 
           def publish_readiness_async(readiness)
+            log.debug { 'bedrock.registry_publisher.publish_readiness_async: scheduling readiness event' }
             schedule { publish_event(@builder.readiness(readiness)) }
           end
 
           def publish_offerings_async(offerings, readiness:)
+            log.debug do
+              "bedrock.registry_publisher.publish_offerings_async: scheduling #{Array(offerings).size} offerings"
+            end
             schedule do
               Array(offerings).each do |offering|
                 publish_event(@builder.offering_available(offering, readiness:))
@@ -33,10 +39,10 @@ module Legion
               Thread.current.abort_on_exception = false
               yield
             rescue StandardError => e
-              log_publish_failure(e, level: :debug)
+              handle_exception(e, level: :debug, handled: true, operation: 'bedrock.registry_publisher.schedule')
             end
           rescue StandardError => e
-            log_publish_failure(e, level: :debug)
+            handle_exception(e, level: :debug, handled: true, operation: 'bedrock.registry_publisher.schedule')
             false
           end
 
@@ -45,7 +51,7 @@ module Legion
 
             message_class.new(event:, app_id: APP_ID).publish(spool: false)
           rescue StandardError => e
-            log_publish_failure(e)
+            handle_exception(e, level: :warn, handled: true, operation: 'bedrock.registry_publisher.publish_event')
             false
           end
 
@@ -56,7 +62,9 @@ module Legion
             return true unless ::Legion::Transport::Connection.respond_to?(:session_open?)
 
             ::Legion::Transport::Connection.session_open?
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'bedrock.registry_publisher.publishing_available?')
             false
           end
 
@@ -70,7 +78,9 @@ module Legion
 
             require 'legion/extensions/llm/bedrock/transport/messages/registry_event'
             message_class_defined?
-          rescue LoadError
+          rescue LoadError => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'bedrock.registry_publisher.transport_message_available?')
             false
           end
 
@@ -81,18 +91,6 @@ module Legion
           def message_class
             ::Legion::Extensions::Llm::Bedrock::Transport::Messages::RegistryEvent
           end
-
-          def log_publish_failure(error, level: :warn)
-            message = "[lex-llm-bedrock] llm.registry publish failed: #{error.class}: #{error.message}"
-            logger = ::Legion::Extensions::Llm.logger if defined?(::Legion::Extensions::Llm)
-            if logger.respond_to?(level)
-              logger.public_send(level, message)
-            elsif logger.respond_to?(:debug)
-              logger.debug(message)
-            end
-          rescue StandardError
-            nil
-          end
         end
       end
     end

data/lib/legion/extensions/llm/bedrock/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Bedrock
-        VERSION = '0.1.4'
+        VERSION = '0.1.5'
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-bedrock
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - LegionIO