lex-azure-ai 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d62cce58c74c7629813ee041e1170b89b8bf840290e4780df44c498842e74575
-  data.tar.gz: d7ec97c677ba8c83c3e13fcfacf5e5ac9f3fb34eae518b65d57f21d37e1314e6
+  metadata.gz: 0b999c09cc1e7d260fd320f576ffe0bac0c7404e6d74ef210f83e216ab42fdf4
+  data.tar.gz: 73e5d2ac265f6b70a96bfbcbb754b44e96eeb202f84021999ce3d80e8ecd90e3
 SHA512:
-  metadata.gz: 2658586dd660d0a5dfce414f12932ca82582a7d142ad4605ef7eaf649aaf30368ebb3fd31a48dc6459f3120539622c34c82fd017a68d961e15075a23ae896998
-  data.tar.gz: dde8723318bf4c19c9c7396d6f2df1f6e25abcbf59f9f24051f1f0fdd1a3f95cc26153955aba57bbf16db34cca825a2a7d0f1c65a556532a70565003b0ab7daf
+  metadata.gz: 94d33edca3f7af18a63c8ac353c0e7636715c6493ab2722e74e93c3cde068ccdf2e3bc9f6650deaf99bd18b452ccdb8fc9b815b864932c3319ac36fff2948726
+  data.tar.gz: 91886385ce36acaf98edada221dac55654ca58ae968b4869b7a3ab41ac67934c254a852db22400848ff57df56a5b0c9c36bda18b0fde062acf1af82552b1a7c4

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.1.6] - 2026-04-17
+
+### Added
+- Content Safety runner with `check_text` method for Azure AI Content Safety `text:analyze` API (#4)
+- `content_safety_client` factory method in `Helpers::Client` for Cognitive Services endpoint
+- Configurable severity threshold (default 2, range 0-6) with normalized blocked/reasons response
+
+## [0.1.5] - 2026-04-06
+
+### Added
+- Credential-only identity module for Phase 8 Broker integration (`Identity` module with `provide_token`)
+
 ## [0.1.4] - 2026-03-31
 
 ### Added

data/CLAUDE.md

@@ -6,53 +6,137 @@
 
 ## Purpose
 
-Legion Extension that connects LegionIO to Azure AI Services (Azure OpenAI). Provides runners for chat completions, embeddings, and model listing via the Azure OpenAI REST API.
+Legion Extension that connects LegionIO to Azure AI Services. Provides runners for chat completions, embeddings, model listing (via Azure OpenAI), and content safety moderation (via Azure AI Content Safety).
 
 **GitHub**: https://github.com/LegionIO/lex-azure-ai
 **License**: MIT
-**Version**: 0.1.2
-**Specs**: 22 examples
+**Version**: 0.1.6
+**Specs**: 45 examples (5 spec files)
 
 ## Architecture
 
 ```
 Legion::Extensions::AzureAi
 ├── Runners/
-│   ├── Chat           # create(deployment:, messages:, api_key:, endpoint:, api_version:, ...)
-│   ├── Embeddings     # create(deployment:, input:, api_key:, endpoint:, api_version:, ...)
-│   └── Models         # list(api_key:, endpoint:, api_version:, ...)
+│   ├── Chat             # create(deployment:, messages:, api_key:, endpoint:, api_version:, ...)
+│   ├── Embeddings       # create(deployment:, input:, api_key:, endpoint:, api_version:, ...)
+│   ├── Models           # list(api_key:, endpoint:, api_version:, ...)
+│   └── ContentSafety    # check_text(content:, endpoint:, api_key:, severity_threshold:, ...)
 ├── Helpers/
-│   └── Client         # Faraday-based Azure OpenAI client (module, factory method)
-└── Client             # Standalone client class (includes all runners, holds @config)
+│   └── Client           # Faraday-based client factory (two methods: client + content_safety_client)
+├── Client               # Standalone client class (includes all runners, holds @config)
+└── Identity             # Credential-only identity module for Broker integration
 ```
 
-`Helpers::Client` is a **module** with a `client(api_key:, endpoint:, ...)` factory method. It builds a Faraday connection to `https://#{endpoint}.openai.azure.com` and sets the `api-key` header. Runner modules `extend` it to gain `client(...)` as a module-level method.
+### Two Azure Services, Two Clients
 
-`Client` (class) provides a standalone instantiable wrapper. It holds `@config` and delegates through `Helpers::Client`.
+`Helpers::Client` is a **module** with two factory methods:
+
+| Factory Method | Base URL | Auth Header | Used By |
+|----------------|----------|-------------|---------|
+| `client(api_key:, endpoint:, ...)` | `https://#{endpoint}.openai.azure.com` | `api-key` | Chat, Embeddings, Models |
+| `content_safety_client(api_key:, endpoint:, ...)` | `https://#{endpoint}.cognitiveservices.azure.com` | `Ocp-Apim-Subscription-Key` | ContentSafety |
+
+Both build a Faraday connection with JSON request/response middleware. Runner modules `extend` `Helpers::Client` to gain these as module-level methods.
+
+`Client` (class) provides a standalone instantiable wrapper. It holds `@config` and delegates through `Helpers::Client`. It includes all four runner modules.
+
+## Runner Reference
+
+### Chat — `Runners::Chat`
+
+```ruby
+create(deployment:, messages:, api_key:, endpoint:, api_version: '2024-10-21', max_tokens: nil, temperature: nil, **)
+```
+
+- POST `/openai/deployments/#{deployment}/chat/completions?api-version=#{api_version}`
+- Returns `{ result: response.body, usage: { input_tokens:, output_tokens:, cache_read_tokens:, cache_write_tokens: } }`
+
+### Embeddings — `Runners::Embeddings`
+
+```ruby
+create(deployment:, input:, api_key:, endpoint:, api_version: '2024-10-21', **)
+```
+
+- POST `/openai/deployments/#{deployment}/embeddings?api-version=#{api_version}`
+- Returns `{ result: response.body, usage: { input_tokens:, output_tokens:, cache_read_tokens:, cache_write_tokens: } }`
+
+### Models — `Runners::Models`
+
+```ruby
+list(api_key:, endpoint:, api_version: '2024-10-21', **)
+```
+
+- GET `/openai/models?api-version=#{api_version}`
+- Returns `{ models: response.body }` (note: `models` key, not `result`)
+
+### ContentSafety — `Runners::ContentSafety`
+
+```ruby
+check_text(content:, endpoint:, api_key:, severity_threshold: 2, categories: nil, api_version: '2024-09-01', **)
+```
+
+- POST `/contentsafety/text:analyze?api-version=#{api_version}`
+- Request body: `{ text: content }` (plus `categories:` if provided)
+- Response parsing: reads `categoriesAnalysis` array, filters by `severity >= severity_threshold`
+- Returns `{ result: { blocked:, reasons:, categories:, raw: } }`
+- Categories: Hate, Violence, SelfHarm, Sexual — severity range 0–6
+- Default `api_version` is `'2024-09-01'` (differs from OpenAI runners which default to `'2024-10-21'`)
+- No `usage` key — Content Safety API doesn't return token counts
 
 ## Key Design Decisions
 
-- Authentication uses the `api-key` header (not `Authorization: Bearer`). This is specific to Azure OpenAI — differs from lex-openai which uses Bearer.
-- API base URL is constructed from the `endpoint` param: `https://#{endpoint}.openai.azure.com`. The endpoint is typically the Azure resource name (e.g., `my-resource`).
-- Default `api_version` is `'2024-10-21'`. All runner methods accept `api_version:` as an override keyword.
-- `Models#list` returns `{ models: response.body }` (not `{ result: ... }`). `Chat` and `Embeddings` return `{ result: response.body }`.
-- `include Legion::Extensions::Helpers::Lex` is guarded with `const_defined?` pattern.
+- **Azure OpenAI auth** uses the `api-key` header (not `Authorization: Bearer`). Differs from lex-openai which uses Bearer.
+- **Content Safety auth** uses `Ocp-Apim-Subscription-Key` header. Different Azure service, different auth mechanism.
+- **API base URLs** are constructed from the `endpoint` param. The endpoint is typically the Azure resource name (e.g., `my-resource`).
+- **Two default `api_version` values**: `'2024-10-21'` for OpenAI runners, `'2024-09-01'` for Content Safety. All runners accept `api_version:` as an override.
+- **Return key conventions**: Chat and Embeddings return `{ result: ... }`, Models returns `{ models: ... }`, ContentSafety returns `{ result: { blocked:, reasons:, categories:, raw: } }`.
+- `include Legion::Extensions::Helpers::Lex` is guarded with `const_defined?` pattern in all runner modules.
+- **Identity module** is credential-only (`provider_type: :credential`). Resolves API key from `Legion::Settings.dig(:llm, :providers, :azure, :api_key)`.
+
+## File Map
+
+```
+lib/legion/extensions/azure_ai.rb                        # Entry point, requires all modules
+lib/legion/extensions/azure_ai/version.rb                 # VERSION constant
+lib/legion/extensions/azure_ai/helpers/client.rb          # Faraday factory methods (client + content_safety_client)
+lib/legion/extensions/azure_ai/runners/chat.rb            # Chat completions runner
+lib/legion/extensions/azure_ai/runners/embeddings.rb      # Embeddings runner
+lib/legion/extensions/azure_ai/runners/models.rb          # Model listing runner
+lib/legion/extensions/azure_ai/runners/content_safety.rb  # Content Safety text analysis runner
+lib/legion/extensions/azure_ai/client.rb                  # Standalone Client class
+lib/legion/extensions/azure_ai/identity.rb                # Broker identity integration
+
+spec/legion/extensions/azure_ai/runners/chat_spec.rb             # 9 examples
+spec/legion/extensions/azure_ai/runners/embeddings_spec.rb       # 9 examples
+spec/legion/extensions/azure_ai/runners/models_spec.rb           # 4 examples
+spec/legion/extensions/azure_ai/runners/content_safety_spec.rb   # 10 examples
+spec/legion/extensions/azure_ai/identity_spec.rb                 # 8 examples
+spec/client_spec.rb                                              # 5 examples
+```
 
 ## Dependencies
 
 | Gem | Purpose |
 |-----|---------|
-| `faraday` >= 2.0 | HTTP client for Azure OpenAI API |
+| `faraday` >= 2.0 | HTTP client for Azure OpenAI and Content Safety APIs |
 | `multi_json` | JSON parser abstraction |
+| `legion-cache`, `legion-crypt`, `legion-data`, `legion-json`, `legion-logging`, `legion-settings`, `legion-transport` | LegionIO core |
 
 ## Testing
 
 ```bash
 bundle install
-bundle exec rspec        # 22 examples
-bundle exec rubocop
+bundle exec rspec        # 45 examples
+bundle exec rubocop      # 0 offenses expected
 ```
 
+All specs use Faraday instance doubles — no network calls. The test pattern is:
+1. Create an anonymous class that `extend`s the runner module
+2. Stub `Faraday.new` to return an instance double
+3. Assert on paths, request bodies, and parsed response structures
+
 ---
 
 **Maintained By**: Matthew Iverson (@Esity)
+**Last Updated**: 2026-04-17

data/README.md

@@ -1,10 +1,14 @@
 # lex-azure-ai
 
-Legion Extension that connects LegionIO to Azure AI Services (Azure OpenAI).
+[![Gem Version](https://img.shields.io/gem/v/lex-azure-ai.svg)](https://rubygems.org/gems/lex-azure-ai)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.4-red.svg)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Legion Extension that connects LegionIO to Azure AI Services — Azure OpenAI and Azure AI Content Safety.
 
 ## Purpose
 
-Wraps the Azure OpenAI REST API as named runners consumable by any LegionIO task chain. Provides chat completions, embeddings, and model listing. Use this extension when you need direct access to the Azure OpenAI API surface within the LEX runner/actor lifecycle. For simple chat/embed workflows, consider `legion-llm` instead.
+Wraps the Azure AI REST APIs as named runners consumable by any LegionIO task chain. Provides chat completions, embeddings, model listing, and content safety moderation. Use this extension when you need direct access to the Azure AI API surface within the LEX runner/actor lifecycle. For simple chat/embed workflows, consider `legion-llm` instead.
 
 ## Installation
 
@@ -14,62 +18,164 @@ Add to your Gemfile:
 gem 'lex-azure-ai'
 ```
 
-## Usage
+Then run:
 
-### Standalone Client
+```bash
+bundle install
+```
+
+## Quick Start
 
 ```ruby
 require 'legion/extensions/azure_ai'
 
 client = Legion::Extensions::AzureAi::Client.new(
-  api_key: 'your-azure-api-key',
-  endpoint: 'my-resource',
-  api_version: '2024-10-21'
+  api_key:  'your-azure-api-key',
+  endpoint: 'my-resource'
 )
 
-result = client.create(
+# Chat completion
+chat = client.create(
   deployment: 'gpt-4o',
-  messages: [{ role: 'user', content: 'Hello!' }]
+  messages:   [{ role: 'user', content: 'Hello!' }]
 )
+puts chat[:result]['choices'].first['message']['content']
+
+# Content safety check
+safety = client.check_text(
+  content:  'some user-generated text',
+  endpoint: 'my-content-safety-resource',
+  api_key:  'your-content-safety-key'
+)
+puts "Blocked: #{safety[:result][:blocked]}"
 ```
 
-### Runners Directly
+## API Coverage
+
+| Runner | Method | Azure API | Auth Header |
+|--------|--------|-----------|-------------|
+| `Chat` | `create` | Azure OpenAI — Chat Completions | `api-key` |
+| `Embeddings` | `create` | Azure OpenAI — Embeddings | `api-key` |
+| `Models` | `list` | Azure OpenAI — Models | `api-key` |
+| `ContentSafety` | `check_text` | Azure AI Content Safety — `text:analyze` | `Ocp-Apim-Subscription-Key` |
+
+## Usage
+
+### Chat Completions
 
 ```ruby
-Legion::Extensions::AzureAi::Runners::Chat.create(
-  deployment: 'gpt-4o',
-  messages: [{ role: 'user', content: 'Hello!' }],
-  api_key: 'your-key',
-  endpoint: 'my-resource'
+result = Legion::Extensions::AzureAi::Runners::Chat.create(
+  deployment:  'gpt-4o',
+  messages:    [{ role: 'user', content: 'Hello!' }],
+  api_key:     'your-key',
+  endpoint:    'my-resource',
+  temperature: 0.7,       # optional
+  max_tokens:  1000       # optional
 )
+# => { result: { 'choices' => [...], 'usage' => {...} },
+#      usage: { input_tokens: 10, output_tokens: 20, ... } }
+```
 
-Legion::Extensions::AzureAi::Runners::Embeddings.create(
+### Embeddings
+
+```ruby
+result = Legion::Extensions::AzureAi::Runners::Embeddings.create(
   deployment: 'text-embedding-ada-002',
-  input: 'Hello world',
-  api_key: 'your-key',
-  endpoint: 'my-resource'
+  input:      'Hello world',
+  api_key:    'your-key',
+  endpoint:   'my-resource'
 )
+# => { result: { 'data' => [{ 'embedding' => [...] }] },
+#      usage: { input_tokens: 2, output_tokens: 0, ... } }
+```
+
+### Models
 
-Legion::Extensions::AzureAi::Runners::Models.list(
-  api_key: 'your-key',
+```ruby
+result = Legion::Extensions::AzureAi::Runners::Models.list(
+  api_key:  'your-key',
   endpoint: 'my-resource'
 )
+# => { models: { 'data' => [{ 'id' => 'gpt-4o' }, ...] } }
 ```
 
-## API Coverage
+### Content Safety
+
+```ruby
+result = Legion::Extensions::AzureAi::Runners::ContentSafety.check_text(
+  content:            'text to analyze',
+  api_key:            'your-content-safety-key',
+  endpoint:           'my-content-safety-resource',
+  severity_threshold: 2,                    # default 2, range 0-6
+  categories:         %w[Hate Violence],    # optional filter; defaults to all four
+  api_version:        '2024-09-01'          # default
+)
+# => { result: {
+#        blocked:    false,
+#        reasons:    [],
+#        categories: [
+#          { 'category' => 'Hate',     'severity' => 0 },
+#          { 'category' => 'Violence', 'severity' => 0 }, ...
+#        ],
+#        raw: { ... }
+#      } }
+```
+
+**Categories:** Hate, Violence, SelfHarm, Sexual — severity range 0–6. Any category at or above `severity_threshold` triggers `blocked: true`.
+
+### Standalone Client
+
+The `Client` class includes all runners and stores credentials so you don't repeat them:
+
+```ruby
+client = Legion::Extensions::AzureAi::Client.new(
+  api_key:     'your-key',
+  endpoint:    'my-resource',
+  api_version: '2024-10-21'  # default
+)
+
+client.create(deployment: 'gpt-4o', messages: [...])
+client.list
+```
+
+> **Note:** `check_text` requires `endpoint:` and `api_key:` as explicit arguments because Content Safety uses a different Azure resource and auth mechanism than OpenAI.
 
-| Runner | Methods |
-|--------|---------|
-| `Chat` | `create` |
-| `Embeddings` | `create` |
-| `Models` | `list` |
+## Azure Service Endpoints
+
+This gem talks to two distinct Azure services with different base URLs and authentication:
+
+| Service | Base URL | Auth Header |
+|---------|----------|-------------|
+| Azure OpenAI | `https://{endpoint}.openai.azure.com` | `api-key` |
+| Azure AI Content Safety | `https://{endpoint}.cognitiveservices.azure.com` | `Ocp-Apim-Subscription-Key` |
+
+The `endpoint` parameter is typically the Azure resource name (e.g., `my-resource`).
+
+## Identity
+
+The `Identity` module provides credential-only integration with the LegionIO Broker identity system:
+
+```ruby
+Legion::Extensions::AzureAi::Identity.provide_token
+# => Legion::Identity::Lease (or nil if no key configured)
+```
+
+API keys are resolved from `Legion::Settings` at `:llm → :providers → :azure → :api_key`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # 45 examples, 5 spec files
+bundle exec rubocop      # 0 offenses expected
+```
 
 ## Related
 
-- `lex-foundry` — Azure AI Foundry management API (model catalog, deployments, connections)
-- `legion-llm` — High-level LLM interface across all providers including Azure OpenAI
-- `extensions-ai/CLAUDE.md` — Architecture patterns shared across all AI extensions
+- [`lex-foundry`](https://github.com/LegionIO/lex-foundry) — Azure AI Foundry management API (model catalog, deployments, connections)
+- [`legion-llm`](https://github.com/LegionIO/legion-llm) — High-level LLM interface across all providers including Azure OpenAI
+- [`extensions-ai/CLAUDE.md`](../CLAUDE.md) — Architecture patterns shared across all AI extensions
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE) for details.

data/lib/legion/extensions/azure_ai/client.rb

@@ -4,6 +4,7 @@ require 'legion/extensions/azure_ai/helpers/client'
 require 'legion/extensions/azure_ai/runners/chat'
 require 'legion/extensions/azure_ai/runners/embeddings'
 require 'legion/extensions/azure_ai/runners/models'
+require 'legion/extensions/azure_ai/runners/content_safety'
 
 module Legion
   module Extensions
@@ -12,6 +13,7 @@ module Legion
         include Legion::Extensions::AzureAi::Runners::Chat
         include Legion::Extensions::AzureAi::Runners::Embeddings
         include Legion::Extensions::AzureAi::Runners::Models
+        include Legion::Extensions::AzureAi::Runners::ContentSafety
 
         attr_reader :config
 

data/lib/legion/extensions/azure_ai/helpers/client.rb

@@ -18,6 +18,15 @@ module Legion
               conn.headers['Content-Type'] = 'application/json'
             end
           end
+
+          def content_safety_client(api_key:, endpoint:, **)
+            Faraday.new(url: "https://#{endpoint}.cognitiveservices.azure.com") do |conn|
+              conn.request :json
+              conn.response :json, content_type: /\bjson$/
+              conn.headers['Ocp-Apim-Subscription-Key'] = api_key
+              conn.headers['Content-Type'] = 'application/json'
+            end
+          end
         end
       end
     end

data/lib/legion/extensions/azure_ai/identity.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module AzureAi
+      module Identity
+        module_function
+
+        def provider_name  = :azure
+        def provider_type  = :credential
+        def facing         = nil
+        def capabilities   = %i[credentials]
+
+        def resolve(canonical_name: nil) # rubocop:disable Lint/UnusedMethodArgument
+          nil
+        end
+
+        def provide_token
+          api_key = resolve_api_key
+          return nil unless api_key
+
+          Legion::Identity::Lease.new(
+            provider:   :azure,
+            credential: api_key,
+            expires_at: nil,
+            renewable:  false,
+            issued_at:  Time.now,
+            metadata:   { credential_type: :api_key }
+          )
+        end
+
+        def resolve_api_key
+          return nil unless defined?(Legion::Settings)
+
+          value = Legion::Settings.dig(:llm, :providers, :azure, :api_key)
+          value = value.find { |v| v && !v.empty? } if value.is_a?(Array)
+          value unless value.nil? || (value.is_a?(String) && (value.empty? || value.start_with?('env://')))
+        end
+
+        private_class_method :resolve_api_key
+      end
+    end
+  end
+end

data/lib/legion/extensions/azure_ai/runners/content_safety.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/azure_ai/helpers/client'
+
+module Legion
+  module Extensions
+    module AzureAi
+      module Runners
+        module ContentSafety
+          extend Legion::Extensions::AzureAi::Helpers::Client
+
+          def check_text(content:, endpoint:, api_key:, severity_threshold: 2,
+                         categories: nil, api_version: '2024-09-01', **)
+            body = { text: content }
+            body[:categories] = categories if categories
+
+            path = "/contentsafety/text:analyze?api-version=#{api_version}"
+            response = content_safety_client(api_key: api_key, endpoint: endpoint).post(path, body)
+
+            categories_analysis = response.body['categoriesAnalysis'] || []
+            blocked_categories = categories_analysis.select { |c| c['severity'] >= severity_threshold }
+
+            {
+              result: {
+                blocked:    !blocked_categories.empty?,
+                reasons:    blocked_categories.map { |c| c['category'] },
+                categories: categories_analysis,
+                raw:        response.body
+              }
+            }
+          end
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex, false)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/azure_ai/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module AzureAi
-      VERSION = '0.1.4'
+      VERSION = '0.1.6'
     end
   end
 end

data/lib/legion/extensions/azure_ai.rb

@@ -5,7 +5,9 @@ require 'legion/extensions/azure_ai/helpers/client'
 require 'legion/extensions/azure_ai/runners/chat'
 require 'legion/extensions/azure_ai/runners/embeddings'
 require 'legion/extensions/azure_ai/runners/models'
+require 'legion/extensions/azure_ai/runners/content_safety'
 require 'legion/extensions/azure_ai/client'
+require 'legion/extensions/azure_ai/identity'
 
 module Legion
   module Extensions

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-azure-ai
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Esity
@@ -157,7 +157,9 @@ files:
 - lib/legion/extensions/azure_ai.rb
 - lib/legion/extensions/azure_ai/client.rb
 - lib/legion/extensions/azure_ai/helpers/client.rb
+- lib/legion/extensions/azure_ai/identity.rb
 - lib/legion/extensions/azure_ai/runners/chat.rb
+- lib/legion/extensions/azure_ai/runners/content_safety.rb
 - lib/legion/extensions/azure_ai/runners/embeddings.rb
 - lib/legion/extensions/azure_ai/runners/models.rb
 - lib/legion/extensions/azure_ai/version.rb