legion-llm 0.12.14 → 0.14.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d61b50d6573478325baba59ea7b05a8e7a6bce2c66c453d15eec40b1380b891
-  data.tar.gz: e14038bcac7c816169e31bc2f8a08fb76331e0bc7b18766f029fe217c3b57d2d
+  metadata.gz: 8ab1822ba6aa5df945cd99b3bb2ee5e735080f97a517d4de694725e38f44bf71
+  data.tar.gz: 276fd55c3fabce052c0c27a3cd1e84e050b502446a4b047ff8ec88fe829c7f47
 SHA512:
-  metadata.gz: e1abe73f183b7b6e135db20bb2bc2b875b6bb40234630c5327a906d38892b6ef83f35c2c9f8a8b0ee193451d1609f1e30c1ebc4b0ebf28e844b3a9e8044ffefa
-  data.tar.gz: bf44ad26a524c018b042dda702b076c98ef7068aaf48e638305776532d809036778c86a0e4e385974c2d59bffbdf61da4a20067b89d09cbc85a2e5a6b34f5203
+  metadata.gz: f1a2ca486fe605683c14a8847ed209a6041c8a557d90b4e6e01676218d3bced83e776ae4352a6f19c09ab19e2f98e129cfb947dcd435a490a6df5c7b95240b31
+  data.tar.gz: aa8cbe3c10d72b28d9a31a3e8f3114faaa2e016860e4520532d5872ab01a38e53084184cb22dbb0b7943691819291c17770fb7292da392460200057ba980e638

data/.gitignore

@@ -24,3 +24,4 @@ docs/
 bin/apollo-setup-postreboot.sh
 bin/apollo-setup-prereboot.sh
 legionio-bootstrap-uhg-v3.json
+docs/

data/.rubocop.yml

@@ -1,8 +1,96 @@
+plugins:
+  - rubocop-legion
+
+# These rubocop-legion cops surface in the local-path 0.1.7 build but were not
+# in the published 0.1.7 gem the repo previously tracked. They flag broad
+# pre-existing patterns unrelated to the N×N enforcement pass; deferred to
+# their own cleanup task. NoUnderscorePrefixedKwargs / NoInlineSettingDefaults
+# / NoDirectDispatch / NoShapeDuckTyping (the B4 set Phase 6 adopts) remain
+# enabled.
+Legion/RescueLogging/NoCapture:
+  Enabled: false
+Legion/ConstantSafety/InheritParam:
+  Enabled: false
+
+# rubocop-legion 0.1.9 cops — enabled as of P0 but deferred enforcement:
+# these four cops flag broad pre-existing patterns in the codebase that
+# predate the SSOT refactor. They gate NEW code from P1 onward; existing
+# violations are cleaned up within each phase as the code they govern is
+# rewritten. Do not add new violations; do not suppress them with inline
+# rubocop:disable without a tracking comment.
+#
+# TODO(P1): enable Legion/Llm/TaxonomyEnum repo-wide after lane taxonomy
+#           is established and all :type/:tier/:circuit_state literals updated.
+# TODO(P1): enable Legion/Llm/RescueLogLevel repo-wide after back-compat
+#           :debug rescue handlers are audited and leveled up.
+# TODO(P1): enable Legion/Llm/NoLoopDo repo-wide after cache/drain loops
+#           are converted to bounded iteration.
+Legion/Llm/TaxonomyEnum:
+  Enabled: false
+Legion/Llm/RescueLogLevel:
+  Enabled: false
+Legion/Llm/NoLoopDo:
+  Enabled: false
+# SettingsAccessPath is enabled for lib/ only — specs legitimately write
+# settings via the loader path to set up test fixtures.
+Legion/Llm/SettingsAccessPath:
+  Exclude:
+    - 'spec/**/*'
+
 AllCops:
   TargetRubyVersion: 3.4
   NewCops: enable
   SuggestExtensions: false
 
+# N×N routing guard cops (Phase 6 enforcement; defaults from rubocop-legion config/default.yml).
+#
+# - NoUnderscorePrefixedKwargs / NoInlineSettingDefaults / NoDirectDispatch are
+#   enabled repo-wide.
+# - NoShapeDuckTyping is enabled on the canonical-only surface where the shape
+#   contract is fully established by translators. Code at the HTTP/wire ingress
+#   (client_translator parse_request, StreamAssembler chunk adapter, DebugFormats
+#   request envelope reader, Response.from_provider_message bridge) legitimately
+#   inspects shape because that's the layer responsible for normalising into
+#   canonical. The cop's scope expands here as the executor's canonical
+#   migration (Phase 4 follow-up) lands.
+Legion/Framework/NoShapeDuckTyping:
+  Enabled: true
+  Include:
+    - 'lib/legion/llm/api/**/*.rb'
+    - 'lib/legion/llm/inference/**/*.rb'
+  Exclude:
+    # Legacy tree deprecated this release (R11); deleted next minor.
+    - 'lib/legion/llm/api/translators/**/*.rb'
+    - 'lib/legion/llm/api/anthropic/**/*.rb'
+    - 'lib/legion/llm/api/openai/**/*.rb'
+    - 'lib/legion/llm/api/native/**/*.rb'
+    - 'lib/legion/llm/api/shared_helpers.rb'
+    # Boundary code that legitimately bridges wire ↔ canonical: parse_request
+    # at the HTTP ingress, the StreamAssembler chunk adapter (P5 explicitly
+    # accepts both Canonical::Chunk and the legacy StreamChunk shape during
+    # migration), DebugFormats (reads raw env / reflects request), and
+    # shared_extractors (normalises arbitrary thinking content shapes).
+    # Pre-canonical inference steps still navigate raw wire hashes; that
+    # scope tightens once the executor finishes the canonical migration
+    # (Phase 4 follow-up).
+    - 'lib/legion/llm/api/client_translators/anthropic_messages.rb'
+    - 'lib/legion/llm/api/client_translators/openai_chat.rb'
+    - 'lib/legion/llm/api/client_translators/openai_responses.rb'
+    - 'lib/legion/llm/api/client_translators/shared_extractors.rb'
+    - 'lib/legion/llm/api/stream_assembler.rb'
+    - 'lib/legion/llm/api/debug_formats.rb'
+    - 'lib/legion/llm/api/namespaces/**/*.rb'
+    - 'lib/legion/llm/inference/audit_publisher.rb'
+    - 'lib/legion/llm/inference/embed_pipeline.rb'
+    - 'lib/legion/llm/inference/enrichment_injector.rb'
+    - 'lib/legion/llm/inference/executor.rb'
+    - 'lib/legion/llm/inference/executor/**/*.rb'
+    - 'lib/legion/llm/inference/native_tool_loop.rb'
+    - 'lib/legion/llm/inference/profile.rb'
+    - 'lib/legion/llm/inference/response.rb'
+    - 'lib/legion/llm/inference/route_attempts.rb'
+    - 'lib/legion/llm/inference/steps/**/*.rb'
+
 Layout/LineLength:
   Max: 195
 Layout/SpaceAroundEqualsInParameterDefault:
@@ -43,6 +131,7 @@ Naming/PredicateMethod:
   Enabled: false
 Metrics/ParameterLists:
   Max: 9
+  CountKeywordArgs: false
 Style/RedundantConstantBase:
   Exclude:
     - 'spec/**/*'

data/AGENTS.md

@@ -1,46 +1,61 @@
-# legion-llm Agent Notes
+# legion-llm — Agent Notes (v0.13.0)
 
-## Scope
-
-`legion-llm` provides provider configuration, chat/embed/structured interfaces, dynamic routing, escalation, quality checks, and pipeline execution for Legion.
+`legion-llm` is a **universal translation proxy** for LLM traffic: N client dialects (OpenAI Chat,
+OpenAI Responses, Anthropic Messages) × N provider backends (Bedrock, Anthropic, OpenAI, vLLM,
+Ollama, fleet), any direction. Every request parses once into `Canonical::Request`, is
+routed/executed, then renders once back to the caller's dialect. See `CLAUDE.md` for the full
+invariant set; `README.md` for detailed reference.
 
 ## Fast Start
 
 ```bash
 bundle install
-bundle exec rspec
-bundle exec rubocop
+bundle exec rspec      # 0 failures required before commit
+bundle exec rubocop    # 0 offenses required
 ```
 
+**The in-process matrix harness (`spec/legion/llm/api/matrix/`) is the commit gate.** Touch
+`lib/legion/llm/api/`, the executor, or the canonical/translator boundary → it must pass before push.
+
 ## Primary Entry Points
 
-- `lib/legion/llm.rb`
-- `lib/legion/llm/providers.rb`
-- `lib/legion/llm/router/`
-- `lib/legion/llm/pipeline/`
-- `lib/legion/llm/structured_output.rb`
-- `lib/legion/llm/embeddings.rb`
-- `lib/legion/llm/fleet/`
+- `lib/legion/llm.rb` — facade (`start`, `chat`, `ask`, `embed`, `structured`)
+- `lib/legion/llm/inventory.rb` — **single source of truth** for the model catalog
+- `lib/legion/llm/router.rb` + `router/{candidates,availability,health_tracker,escalation/}` — routing
+- `lib/legion/llm/inference/executor.rb` + `executor/{routing,escalation}.rb` — pipeline
+- `lib/legion/llm/inference/steps/` — the 18 pipeline steps
+- `lib/legion/llm/api/{openai,anthropic,native}/` — client routes
+- `lib/legion/llm/api/client_translators/` — canonical ↔ client wire formats
+- `lib/legion/llm/context/curator.rb` — async conversation curation (context-cost control)
+- Provider behaviour (defaults, capabilities, model filtering) lives in `../extensions-ai/lex-llm-*`
 
 ## Guardrails
 
-- Keep typed error behavior and retry semantics stable (`ProviderDown`, `RateLimitError`, `EscalationExhausted`, etc.).
-- Routing and escalation must remain deterministic given the same inputs/settings.
-- Preserve pipeline feature-flag behavior; avoid forcing pipeline-only code paths.
-- Keep provider credentials resolved through settings secret resolution flow; never hardcode secrets.
-- Maintain compatibility with direct methods (`chat_direct`, `embed_direct`, `structured_direct`) and daemon-aware flows.
-- Health tracker and rule scoring are contract-sensitive; changes require spec updates.
+- **Always translate, never passthrough**; **no `provider == :x` branches** outside translators.
+- **Inventory is the only catalog**; `Discovery`/`Registry`/`HealthTracker` are feeders.
+- Never dispatch a triple absent from the live catalog or unhealthy; **fail over, don't hard-fail**.
+- **Model policy = compliance**: `model_whitelist`/`model_blacklist` honored at dispatch, fail-closed;
+  a policy-denied model is terminal (never escalated, never trips circuits).
+- Thinking never crosses providers; mid-stream failover must not kill an in-flight conversation.
+- Every pipeline exit emits ledger events (metering/audit) — no bypasses.
+- `Legion::JSON` only (symbol keys); every `rescue` re-raises or `handle_exception`s; no
+  `defined?(Legion::Settings)` guards; `log.*` not `puts`.
+- **No personal/company identifiers in VCS**; never force-push.
+- Routing/escalation deterministic for the same inputs/settings; health-tracker & rule scoring are
+  contract-sensitive — changes require spec updates.
 
 ## Validation
 
-- Run targeted specs for modified router/pipeline/provider code.
-- Before handoff, run full `bundle exec rspec` and `bundle exec rubocop`.
+Run targeted specs for modified router/pipeline/translator code, then full `rspec` + `rubocop` +
+the matrix harness before handoff.
 
 ---
 
 ## Client Request Headers Reference
 
-Verified from source code (Claude Code binary + Codex `codex-rs` Rust source).
+Verified from source (Claude Code binary + Codex `codex-rs`). Useful when working on `/v1/messages`
+and `/v1/responses` handlers. Routing/identity headers `X-Legion-{Provider,Model,Instance,Tier}` are
+honored as **rules** (hard constraints), not hints.
 
 ### Claude Code → `POST /v1/messages`
 
@@ -48,15 +63,10 @@ Verified from source code (Claude Code binary + Codex `codex-rs` Rust source).
 |---|---|---|
 | `X-Claude-Code-Session-Id` | Stable UUID for the CLI session | Yes |
 | `x-app` | `"cli"` (foreground) or `"cli-bg"` (background) | Yes |
-| `x-claude-remote-session-id` | Remote container session ID | Conditional |
-| `x-claude-remote-container-id` | Remote container ID | Conditional |
-| `x-claude-code-agent-id` | Agent UUID for multi-agent sessions | Conditional |
-| `x-claude-code-parent-agent-id` | Parent agent UUID (spawned subagent) | Conditional |
-| `x-client-app` | Additional client app identifier | Conditional |
-
-Conversation threading is **stateless** — full `messages[]` history sent in the body on every request. No conversation ID, turn ID, or `x-client-request-id` header is sent.
+| `x-claude-code-agent-id` / `x-claude-code-parent-agent-id` | Agent / parent-agent UUIDs | Conditional |
 
-In Rack/Sinatra env keys, headers arrive as `HTTP_X_CLAUDE_CODE_SESSION_ID`, `HTTP_X_APP`, etc.
+Threading is **stateless** — full `messages[]` history in the body every request; no conversation/turn
+ID header. In Rack env: `HTTP_X_CLAUDE_CODE_SESSION_ID`, `HTTP_X_APP`, etc.
 
 ### Codex → `POST /v1/responses`
 
@@ -66,34 +76,15 @@ In Rack/Sinatra env keys, headers arrive as `HTTP_X_CLAUDE_CODE_SESSION_ID`, `HT
 | `thread-id` | Stable UUID for the thread/conversation | Yes |
 | `x-client-request-id` | Same value as `thread-id` | Yes |
 | `x-codex-installation-id` | Installation-scoped UUID | Yes |
-| `x-codex-window-id` | `"{thread_id}:{window_generation}"` | Yes |
-| `x-codex-turn-state` | Sticky-routing token returned by server, replayed by client | After first response |
-| `x-codex-turn-metadata` | Per-turn observability metadata | Conditional |
-| `x-codex-parent-thread-id` | Parent thread UUID (sub-agents) | Conditional |
-| `x-openai-subagent` | Sub-agent type (`"review"`, `"compact"`, `"memory_consolidation"`, etc.) | Conditional |
-| `x-openai-memgen-request` | `"true"` for memory generation requests | Conditional |
-
-In Rack/Sinatra env keys: `HTTP_SESSION_ID`, `HTTP_THREAD_ID`, `HTTP_X_CLIENT_REQUEST_ID`, `HTTP_X_CODEX_INSTALLATION_ID`, etc.
-
-**`HTTP_THREAD_ID` is the stable Codex thread/conversation ID** — it is stable for the lifetime of a thread, not per-request. `HTTP_X_CLIENT_REQUEST_ID` equals `HTTP_THREAD_ID` (Codex sets them to the same value).
-
-Conversation threading over HTTP uses full input in body (stateless like Anthropic). Over WebSocket, `previous_response_id` is sent in the request body to enable delta-only input.
+| `x-codex-turn-state` | Sticky-routing token, replayed by client | After first response |
+| `x-openai-subagent` | Sub-agent type (`review`, `compact`, …) | Conditional |
 
-### Practical Usage in `/v1/messages` and `/v1/responses` Handlers
+`HTTP_THREAD_ID` is the stable thread/conversation ID (not per-request); `HTTP_X_CLIENT_REQUEST_ID`
+equals it. HTTP threading is stateless (full input in body); over WebSocket, `previous_response_id`
+enables delta-only input.
 
 ```ruby
-# Stable request ID (Claude Code sends X-Claude-Code-Session-Id; Codex sends x-client-request-id = thread-id)
-request_id = env['HTTP_X_CLIENT_REQUEST_ID'] || "req_#{SecureRandom.hex(12)}"
-
-# Stable conversation/thread ID
-# Claude Code: no header — generate per-request or use Legion conversation tracking
-# Codex: HTTP_THREAD_ID is stable for the thread lifetime
-conversation_id = env['HTTP_THREAD_ID'] ||
-                  env['HTTP_X_LEGION_CONVERSATION_ID'] ||
-                  body[:conversation_id] ||
-                  "conv_#{SecureRandom.hex(8)}"
-
-# Identify the calling client
-claude_code_session = env['HTTP_X_CLAUDE_CODE_SESSION_ID']  # present only for Claude Code
-codex_installation  = env['HTTP_X_CODEX_INSTALLATION_ID']   # present only for Codex
+request_id      = env['HTTP_X_CLIENT_REQUEST_ID'] || "req_#{SecureRandom.hex(12)}"
+conversation_id = env['HTTP_THREAD_ID'] || env['HTTP_X_LEGION_CONVERSATION_ID'] ||
+                  body[:conversation_id] || "conv_#{SecureRandom.hex(8)}"
 ```