legion-llm 0.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a39a5fe8483ddcd715dafd4d65dfe1f4457b90e5a39e62cfa2a32b6c68c8e0c
+  data.tar.gz: 37ed9c3b024a1cb9cce7eed1e287512c91269ef99fbb7b54342de57ceae9a668
+SHA512:
+  metadata.gz: a19943d8d25665e16ae55dfe6c0e32bad0e834a3eed3c5e028c0c0db672d531ea21e6015e6137b1f7c0b57bb38e2677091cab7d48dc3a3169cf9273fe6e468e7
+  data.tar.gz: b9bd3d4586e64b9f1866d7e276ecdb3969e2204c8428b37e08fd262ddaef77846c5d28f192174b2ed5787d1576431aae4ebe29e2087499f06e2d0f9393e293ff

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,18 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/legion/.idea/
+/.idea/
+*.key
+# rspec failure tracking
+.rspec_status
+legionio.key
+# logs and OS artifacts
+legion.log
+.DS_Store

data/.rubocop.yml

@@ -0,0 +1,56 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Max: 9

data/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Legion LLM Changelog
+
+## [0.3.1] - 2026-03-16
+
+### Removed
+- `vault_path` provider setting (superseded by universal `vault://` resolver in legion-settings 1.3.0)
+- `resolve_credentials` and related methods from Providers module
+
+## [0.3.0] - 2026-03-16
+
+### Added
+- Model escalation on retry: automatic fallback to more capable models on hard or quality failures
+- `Router.resolve_chain` returns ordered `EscalationChain` of fallback resolutions
+- `QualityChecker` module with built-in heuristics (empty, too_short, repetition, json_parse) and pluggable checks
+- `EscalationHistory` mixin tracks attempts on response objects (`escalated?`, `escalation_history`, `final_resolution`)
+- `chat(escalate: true, message:)` retry loop with configurable `max_escalations:` and `quality_check:`
+- HealthTracker `:quality_failure` signal with half-weight failure counting (6 quality failures to trip circuit)
+- AMQP transport: `llm.escalation` exchange + `EscalationEvent` message for fleet-wide observability
+- Settings: `routing.escalation.enabled`, `max_attempts`, `quality_threshold`
+- Helper passthrough: `llm_chat` accepts `escalate:`, `max_escalations:`, `quality_check:`
+
+## [0.2.3]
+
+### Added
+- Timezone support for routing schedule windows via TZInfo
+- `within_schedule?` converts `now` to the schedule's IANA timezone before evaluating hours and days
+- `tzinfo` (>= 2.0) runtime dependency
+
+## [0.2.2]
+
+### Added
+- `Legion::LLM::Discovery::Ollama` module — queries Ollama `/api/tags` for pulled models with TTL cache
+- `Legion::LLM::Discovery::System` module — queries OS memory (macOS `vm_stat`/`sysctl`, Linux `/proc/meminfo`) with TTL cache
+- Router step 4.5: rejects Ollama rules where model is not pulled or exceeds available memory
+- Discovery settings: `enabled`, `refresh_seconds`, `memory_floor_mb` under `Legion::Settings[:llm][:discovery]`
+- Startup discovery: logs available Ollama models and system memory when Ollama provider is enabled
+
+### Changed
+- Added SimpleCov for test coverage reporting
+
+## [0.2.1]
+
+### Added
+- `Legion::LLM::Compressor` module for deterministic prompt compression
+- Three compression levels: light (articles/filler), moderate (+connectives), aggressive (+low-signal words, whitespace collapse)
+- Code block protection (fenced and inline code preserved)
+- `compress_level` field on `Router::Resolution` for routing-driven compression
+- `compress:` parameter on `llm_chat` helper for opt-in compression
+- Routing rules can specify `compress_level` in target to auto-compress for cost-sensitive tiers
+
+## [0.2.0]
+
+### Added
+- Dynamic weighted routing engine (`Legion::LLM::Router`)
+- Intent-based dispatch with privacy, capability, and cost dimensions
+- Priority-based rule matching with time-based schedule windows
+- Cost multipliers for economic routing (e.g., provider promotions)
+- HealthTracker with circuit breaker pattern and latency rolling window
+- Pluggable signal handlers for extensible health monitoring
+- `intent:` and `tier:` parameters on `chat`, `llm_chat`, and `llm_session`
+- Routing rules configurable via `Legion::Settings[:llm][:routing]`
+- Three-tier routing: local (Ollama), fleet (Transport/AMQP), cloud (API providers)
+
+## v0.1.0
+* Initial release
+* Core module with start/shutdown lifecycle
+* Provider configuration (Bedrock, Anthropic, OpenAI, Gemini, Ollama)
+* Vault credential resolution for all providers
+* Chat, embed, and agent convenience methods
+* Extension helper mixin for LEX extensions
+* Auto-detection of default model from enabled providers

data/CLAUDE.md

@@ -0,0 +1,388 @@
+# legion-llm
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Core LegionIO gem providing LLM capabilities to all extensions. Wraps ruby_llm to provide a consistent interface for chat, embeddings, tool use, and agents across multiple providers (Bedrock, Anthropic, OpenAI, Gemini, Ollama). Includes a dynamic weighted routing engine that dispatches requests across local, fleet, and cloud tiers based on caller intent, priority rules, time schedules, cost multipliers, and real-time provider health.
+
+**GitHub**: https://github.com/LegionIO/legion-llm
+**License**: Apache-2.0
+
+## Architecture
+
+### Startup Sequence
+
+```
+Legion::LLM.start
+  ├── 1. Read settings from Legion::Settings[:llm]
+  ├── 2. For each enabled provider:
+  │     ├── Resolve credentials from Vault (if vault_path set)
+  │     └── Configure RubyLLM provider
+  ├── 3. Run discovery (if Ollama enabled): warm model + system memory caches
+  ├── 4. Auto-detect default model from first enabled provider
+  └── 5. Ping provider (if default_model + default_provider set): send test request, log latency
+```
+
+### Module Structure
+
+```
+Legion::LLM (lib/legion/llm.rb)
+├── EscalationExhausted # Raised when all escalation attempts are exhausted
+├── Settings         # Default config, provider settings, routing defaults, discovery defaults
+├── Providers        # Provider configuration and Vault credential resolution
+├── Compressor       # Deterministic prompt compression (3 levels, code-block-aware)
+├── Discovery        # Runtime introspection for local model availability and system resources
+│   ├── Ollama       # Queries Ollama /api/tags for pulled models (TTL-cached)
+│   └── System       # Queries OS memory: macOS (vm_stat/sysctl), Linux (/proc/meminfo)
+├── QualityChecker   # Response quality heuristics (empty, too_short, repetition, json_parse, json_expected) + pluggable callable
+├── EscalationHistory # Mixin for response objects: escalation_history, escalated?, final_resolution, escalation_chain
+├── Router           # Dynamic weighted routing engine
+│   ├── Resolution   # Value object: tier, provider, model, rule name, metadata, compress_level
+│   ├── Rule         # Routing rule: intent matching, schedule windows, constraints
+│   ├── HealthTracker # Circuit breaker, latency rolling window, pluggable signal handlers
+│   └── EscalationChain # Ordered fallback resolution chain with max_attempts cap (pads last resolution if chain is short)
+└── Helpers::LLM     # Extension helper mixin (llm_chat, llm_embed, llm_session, compress:)
+```
+
+### Routing Architecture
+
+Three-tier dispatch model. Local-first avoids unnecessary network hops; fleet offloads to shared hardware via Transport; cloud is the fallback for frontier models.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              Legion::LLM Router (per-node)               │
+│                                                          │
+│  Tier 1: LOCAL  → Ollama on this machine (direct HTTP)   │
+│          Zero network overhead, no Transport              │
+│                                                          │
+│  Tier 2: FLEET  → Ollama on Mac Studios / GPU servers    │
+│          Via Legion::Transport (AMQP) when local can't   │
+│          serve the model (Phase 2, not yet built)        │
+│                                                          │
+│  Tier 3: CLOUD  → Bedrock / Anthropic / OpenAI / Gemini │
+│          Existing provider API calls                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Routing Resolution Flow
+
+```
+1. Caller passes intent: { privacy: :strict, capability: :basic }
+2. Router merges with default_intent (fills missing dimensions)
+3. Load rules from settings, filter by:
+   a. Intent match (all `when` conditions must match)
+   b. Schedule window (valid_from/valid_until, hours, days)
+   c. Constraints (e.g., never_cloud strips cloud-tier rules)
+   d. Discovery (Ollama model pulled? Model fits in available RAM?)
+   e. Tier availability (is Ollama running? is Transport loaded?)
+4. Score remaining candidates:
+   effective_priority = rule.priority
+                      + health_tracker.adjustment(provider)
+                      + (1.0 - cost_multiplier) * 10
+5. Return Resolution for highest-scoring candidate
+```
+
+### Integration with LegionIO
+
+- **Service**: `setup_llm` called between data and supervision in startup sequence
+- **Extensions**: `llm_required?` method on extension module, checked at load time
+- **Helpers**: `Legion::Extensions::Helpers::LLM` auto-loaded when gem is present
+- **Readiness**: Registers as `:llm` in `Legion::Readiness`
+- **Shutdown**: `Legion::LLM.shutdown` called during service shutdown
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `ruby_llm` (>= 1.0) | Multi-provider LLM client |
+| `tzinfo` (>= 2.0) | IANA timezone conversion for schedule windows |
+| `legion-logging` | Logging |
+| `legion-settings` | Configuration |
+
+## Key Interfaces
+
+```ruby
+# Core
+Legion::LLM.start                    # Configure providers, set defaults
+Legion::LLM.shutdown                 # Cleanup
+Legion::LLM.started?                 # -> Boolean
+Legion::LLM.settings                 # -> Hash
+
+# Chat (with optional routing)
+Legion::LLM.chat(model:, provider:)                         # Direct (no routing)
+Legion::LLM.chat(intent: { privacy: :strict })              # Intent-based routing
+Legion::LLM.chat(tier: :cloud, model: 'claude-sonnet-4-6')  # Explicit tier override
+Legion::LLM.embed(text, model:)                             # Embeddings (no routing)
+Legion::LLM.agent(AgentClass)                               # Agent instance
+
+# Compressor
+Legion::LLM::Compressor.compress(text, level: 1)                  # -> String (deterministic)
+Legion::LLM::Compressor.stopwords_for_level(2)                    # -> Array of words
+
+# Router
+Legion::LLM::Router.resolve(intent:, tier:, model:, provider:)  # -> Resolution or nil
+Legion::LLM::Router.health_tracker                               # -> HealthTracker
+Legion::LLM::Router.routing_enabled?                             # -> Boolean
+Legion::LLM::Router.reset!                                       # Clear cached state
+
+# HealthTracker
+tracker = Legion::LLM::Router.health_tracker
+tracker.report(provider: :anthropic, signal: :error, value: 1)   # Feed signal
+tracker.report(provider: :ollama, signal: :latency, value: 1200) # Feed latency
+tracker.adjustment(:anthropic)                                    # -> Integer (priority offset)
+tracker.circuit_state(:anthropic)                                 # -> :closed/:open/:half_open
+tracker.register_handler(:gpu_utilization) { |data| ... }         # Extend with new signals
+
+# Escalation
+Legion::LLM.chat(message:, escalate: true, max_escalations: 3, quality_check:) # Escalating chat — raises EscalationExhausted if all attempts fail
+Legion::LLM::EscalationExhausted                                                # raised when all escalation attempts are exhausted
+Legion::LLM::Router.resolve_chain(intent:, tier:, max_escalations:)            # -> EscalationChain
+Legion::LLM::QualityChecker.check(response, quality_threshold: 50, json_expected: false, quality_check: nil) # -> QualityResult
+```
+
+## Settings
+
+Settings read from `Legion::Settings[:llm]`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `enabled` | Boolean | `true` | Enable LLM support |
+| `connected` | Boolean | `false` | Set to true after successful start |
+| `default_model` | String | `nil` | Default model ID (auto-detected if nil) |
+| `default_provider` | Symbol | `nil` | Default provider (auto-detected if nil) |
+| `providers` | Hash | See below | Per-provider configuration |
+| `routing` | Hash | See below | Dynamic routing engine configuration |
+| `discovery` | Hash | See below | Ollama model discovery and system memory settings |
+
+### Provider Settings
+
+Each provider has: `enabled`, `api_key`, `vault_path`, plus provider-specific keys.
+
+Vault credential resolution: When `vault_path` is set and Legion::Crypt::Vault is connected, credentials are fetched from Vault at startup. Keys map to provider-specific fields automatically.
+
+Bedrock supports two auth modes:
+- **SigV4** (default): `api_key` + `secret_key` (+ optional `session_token`)
+- **Bearer token**: `bearer_token` for AWS Identity Center/SSO. When set, `bedrock_bearer_auth.rb` is required lazily to monkey-patch RubyLLM's Bedrock provider.
+
+### Auto-Detection Priority
+
+When no defaults are configured, the first enabled provider is used:
+
+1. Bedrock -> `us.anthropic.claude-sonnet-4-6-v1`
+2. Anthropic -> `claude-sonnet-4-6`
+3. OpenAI -> `gpt-4o`
+4. Gemini -> `gemini-2.0-flash`
+5. Ollama -> `llama3`
+
+### Routing Settings
+
+Nested under `Legion::Settings[:llm][:routing]`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `enabled` | Boolean | `false` | Enable routing (opt-in) |
+| `default_intent` | Hash | `{ privacy: 'normal', capability: 'moderate', cost: 'normal' }` | Defaults merged into every intent |
+| `tiers.local` | Hash | `{ provider: 'ollama' }` | Local tier config |
+| `tiers.fleet` | Hash | `{ queue: 'llm.inference', timeout_seconds: 30 }` | Fleet tier config |
+| `tiers.cloud` | Hash | `{ providers: ['bedrock', 'anthropic'] }` | Cloud tier config |
+| `health.window_seconds` | Integer | `300` | Rolling window for latency tracking |
+| `health.circuit_breaker.failure_threshold` | Integer | `3` | Consecutive failures before circuit opens |
+| `health.circuit_breaker.cooldown_seconds` | Integer | `60` | Seconds before circuit transitions to half_open |
+| `health.latency_penalty_threshold_ms` | Integer | `5000` | Latency above this triggers priority penalty |
+| `health.budget.daily_limit_usd` | Float | `nil` | Daily cloud spend limit (future) |
+| `health.budget.monthly_limit_usd` | Float | `nil` | Monthly cloud spend limit (future) |
+| `rules` | Array | `[]` | Routing rules (see below) |
+| `escalation.enabled` | Boolean | `false` | Enable model escalation on retry |
+| `escalation.max_attempts` | Integer | `3` | Max escalation attempts per call |
+| `escalation.quality_threshold` | Integer | `50` | Min response character length |
+
+### Routing Rules
+
+Each rule is a hash with:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | String | Yes | Unique rule identifier |
+| `when` | Hash | Yes | Intent conditions to match (`privacy`, `capability`, `cost`) |
+| `then` | Hash | No | Target: `{ tier:, provider:, model: }` |
+| `priority` | Integer | No (default 0) | Higher wins when multiple rules match |
+| `constraint` | String | No | Hard constraint (e.g., `never_cloud`) |
+| `fallback` | String | No | Fallback tier if primary is unavailable |
+| `cost_multiplier` | Float | No (default 1.0) | Lower = cheaper = routing bonus |
+| `schedule` | Hash | No | Time-based activation window |
+| `note` | String | No | Human-readable note |
+
+### Intent Dimensions
+
+| Dimension | Values | Default | Effect |
+|-----------|--------|---------|--------|
+| `privacy` | `:strict`, `:normal` | `:normal` | `:strict` -> never cloud (via `never_cloud` constraint rules) |
+| `capability` | `:basic`, `:moderate`, `:reasoning` | `:moderate` | Higher prefers larger/cloud models |
+| `cost` | `:minimize`, `:normal` | `:normal` | `:minimize` prefers local/fleet |
+
+### Schedule Windows
+
+Rules can include a `schedule` hash for time-based activation:
+
+| Field | Format | Example |
+|-------|--------|---------|
+| `valid_from` | ISO 8601 | `"2026-03-15T00:00:00"` |
+| `valid_until` | ISO 8601 | `"2026-03-29T23:59:59"` |
+| `hours` | Array of "HH:MM-HH:MM" | `["00:00-06:00", "18:00-23:59"]` |
+| `days` | Array of day names | `["monday", "tuesday"]` |
+| `timezone` | IANA timezone | `"America/Chicago"` (converts `now` via TZInfo before evaluating hours/days) |
+
+All fields optional. Omit any to mean "always active."
+
+### Discovery Settings
+
+Nested under `Legion::Settings[:llm][:discovery]`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `enabled` | Boolean | `true` | Master switch for discovery checks |
+| `refresh_seconds` | Integer | `60` | TTL for both discovery caches |
+| `memory_floor_mb` | Integer | `2048` | Minimum free MB to reserve for OS |
+
+Discovery is lazy TTL-cached: data refreshes on the next `Router.resolve` call after TTL expires. At startup, caches are warmed if Ollama is enabled. When disabled, all discovery checks are bypassed (permissive).
+
+### HealthTracker
+
+In-memory signal consumer with pluggable handlers. Adjusts effective priorities at runtime.
+
+**Built-in signals:** `:error` (circuit breaker), `:success` (circuit recovery), `:latency` (rolling window penalty), `:quality_failure` (half-weight circuit breaker, 6 failures to trip vs 3 for hard errors)
+
+**Circuit breaker states:**
+- `:closed` (normal, adjustment = 0)
+- `:open` (after `failure_threshold` consecutive errors, adjustment = -50)
+- `:half_open` (after `cooldown_seconds`, tries one request, adjustment = -25)
+
+**Latency penalty:** `-10` per multiple above `LATENCY_THRESHOLD_MS` (5000ms), capped at `-50`
+
+**Extensible:** Call `register_handler(:signal_name) { |data| ... }` to add new signal types. Signal providers (like lex-metering) call `report()` with `defined?(Legion::LLM::Router)` guard.
+
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/llm.rb` | Entry point: start, shutdown, chat (with routing), embed, agent |
+| `lib/legion/llm/settings.rb` | Default settings including routing_defaults, auto-merge into Legion::Settings |
+| `lib/legion/llm/providers.rb` | Provider config, Vault resolution, RubyLLM configuration |
+| `lib/legion/llm/bedrock_bearer_auth.rb` | Monkey-patch for Bedrock Bearer Token auth — required lazily |
+| `lib/legion/llm/compressor.rb` | Deterministic prompt compression: 3 levels, code-block-aware, stopword removal |
+| `lib/legion/llm/router.rb` | Router module: resolve, health_tracker, select_candidates pipeline |
+| `lib/legion/llm/router/resolution.rb` | Value object: tier, provider, model, rule, metadata, compress_level |
+| `lib/legion/llm/router/rule.rb` | Rule class: from_hash, matches_intent?, within_schedule?, to_resolution |
+| `lib/legion/llm/router/health_tracker.rb` | HealthTracker: circuit breaker, latency window, pluggable signal handlers |
+| `lib/legion/llm/discovery/ollama.rb` | Ollama /api/tags discovery with TTL cache |
+| `lib/legion/llm/discovery/system.rb` | OS memory introspection (macOS + Linux) with TTL cache |
+| `lib/legion/llm/version.rb` | Version constant (0.3.0) |
+| `lib/legion/llm/quality_checker.rb` | QualityChecker module with QualityResult struct |
+| `lib/legion/llm/escalation_history.rb` | EscalationHistory mixin: `escalation_history`, `escalated?`, `final_resolution`, `escalation_chain` |
+| `lib/legion/llm/router/escalation_chain.rb` | EscalationChain value object |
+| `lib/legion/llm/transport/exchanges/escalation.rb` | AMQP exchange for escalation events |
+| `lib/legion/llm/transport/messages/escalation_event.rb` | AMQP message for escalation events |
+| `lib/legion/llm/helpers/llm.rb` | Extension helper mixin: llm_chat (with compress:, escalate:, max_escalations:, quality_check:), llm_embed, llm_session |
+| `spec/legion/llm_spec.rb` | Tests: settings, lifecycle, providers, auto-config |
+| `spec/legion/llm/integration_spec.rb` | Tests: routing integration with chat() |
+| `spec/legion/llm/router_spec.rb` | Tests: Router.resolve, priority selection, constraints, health |
+| `spec/legion/llm/router/resolution_spec.rb` | Tests: Resolution value object |
+| `spec/legion/llm/router/rule_spec.rb` | Tests: Rule intent matching, from_hash, to_resolution |
+| `spec/legion/llm/router/rule_schedule_spec.rb` | Tests: Rule schedule evaluation |
+| `spec/legion/llm/router/health_tracker_spec.rb` | Tests: circuit breaker, latency, signal handlers |
+| `spec/legion/llm/router/settings_spec.rb` | Tests: routing defaults in settings |
+| `spec/legion/llm/compressor_spec.rb` | Tests: compression levels, code-block protection, determinism |
+| `spec/legion/llm/helpers/llm_spec.rb` | Tests: helper mixin with compress integration |
+| `spec/legion/llm/discovery/ollama_spec.rb` | Tests: Ollama model discovery, TTL, error handling |
+| `spec/legion/llm/discovery/system_spec.rb` | Tests: System memory introspection |
+| `spec/legion/llm/discovery/router_integration_spec.rb` | Tests: Router discovery filtering |
+| `spec/legion/llm/discovery/startup_spec.rb` | Tests: Startup discovery warmup |
+| `spec/legion/llm/discovery/settings_spec.rb` | Tests: Discovery settings defaults |
+| `spec/legion/llm/quality_checker_spec.rb` | QualityChecker tests |
+| `spec/legion/llm/escalation_history_spec.rb` | EscalationHistory tests |
+| `spec/legion/llm/escalation_integration_spec.rb` | chat() escalation loop tests |
+| `spec/legion/llm/router/escalation_chain_spec.rb` | EscalationChain tests |
+| `spec/legion/llm/router/resolve_chain_spec.rb` | Router.resolve_chain tests |
+| `spec/legion/llm/transport/escalation_spec.rb` | Transport tests |
+| `spec/spec_helper.rb` | Stubbed Legion::Logging and Legion::Settings for testing |
+
+## Extension Integration
+
+Extensions declare LLM dependency via `llm_required?`:
+
+```ruby
+module Legion::Extensions::MyLex
+  def self.llm_required?
+    true
+  end
+end
+```
+
+Helper methods available in runners when gem is loaded:
+
+```ruby
+# Direct (no routing)
+llm_chat(message, model:, provider:, tools:, instructions:)
+llm_embed(text, model:)
+llm_session(model:, provider:)
+
+# With routing
+llm_chat(message, intent: { privacy: :strict, capability: :basic })
+llm_chat(message, tier: :cloud, model: 'claude-sonnet-4-6')
+llm_session(intent: { capability: :reasoning })
+```
+
+## Vault Integration
+
+Provider credentials are resolved by the universal `Legion::Settings::Resolver` (in `legion-settings`), not by legion-llm itself. Use `vault://` and `env://` URI references directly in settings values:
+
+```json
+{
+  "llm": {
+    "providers": {
+      "bedrock": {
+        "enabled": true,
+        "bearer_token": ["vault://secret/data/llm/bedrock#bearer_token", "env://AWS_BEARER_TOKEN"],
+        "region": "us-east-2"
+      },
+      "anthropic": {
+        "enabled": true,
+        "api_key": "env://ANTHROPIC_API_KEY"
+      }
+    }
+  }
+}
+```
+
+By the time `Legion::LLM.start` runs, all `vault://` and `env://` references have already been resolved to plain strings by `Legion::Settings.resolve_secrets!` (called in the boot sequence after `Legion::Crypt.start`).
+
+The legacy `vault_path` per-provider setting was removed in v0.3.1.
+
+## Testing
+
+Tests run without the full LegionIO stack. `spec/spec_helper.rb` stubs `Legion::Logging` and `Legion::Settings` with in-memory implementations. Each test resets settings to defaults via `before(:each)`.
+
+```bash
+bundle exec rspec    # 269 examples, 0 failures
+bundle exec rubocop  # 31 files, 0 offenses
+```
+
+## Design Documents
+
+- `docs/plans/2026-03-14-llm-dynamic-routing-design.md` — Full design (approved)
+- `docs/plans/2026-03-14-llm-dynamic-routing-implementation.md` — Implementation plan
+- `docs/plans/2026-03-15-ollama-discovery-design.md` — Ollama discovery design (approved)
+- `docs/plans/2026-03-15-ollama-discovery-implementation.md` — Discovery implementation plan
+- `docs/plans/2026-03-16-llm-escalation-design.md` — Model escalation design (approved)
+- `docs/plans/2026-03-16-llm-escalation-implementation.md` — Escalation implementation plan
+
+## Future (Not Yet Built)
+
+- **Fleet tier (Phase 2)**: `lex-llm-fleet` extension — inference workers on Mac Studios / NVIDIA servers, dispatched via Legion::Transport AMQP queues
+- **Advanced signals (Phase 3)**: Budget tracking, lex-metering integration, GPU utilization monitoring
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop'
+  gem 'simplecov'
+  gem 'webmock'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   Copyright 2026 Esity / Matthew Iverson
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.