legion-llm 0.12.3 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 733b0a06bf37557dfe7c661d6d63596e30ef5cde4b01c9ae12e801c5257b684e
-  data.tar.gz: f24cfe5b32ed137a47efaac7adf57f348d911cb1f511fbdfc5a769ce54d7c32a
+  metadata.gz: eaa596812e2320baa0d8ae31b44225c80e9ad9b54e62531b3cd1c7640ff09fe6
+  data.tar.gz: a98b90ae07c7040fcd8a13adccf1d07037f253cc845cdc4dc55b65f434805ce0
 SHA512:
-  metadata.gz: c006671e6a1dc02bff77b18e3c31dc4cb771ffd1ba5a6b773e2d7a62a9e886b76e95fb1e9780b0c1285e0165a218112f239fe088ceae9296da440918bd682648
-  data.tar.gz: 14eaff3d563eb80e058f699bca53c79308642f745710c1a546b7e00ecfde049129d90e91a52cea5e13a0e19c39afb1282daf1228640680b8f7b94db777676f81
+  metadata.gz: a7611f997b2163792aa4f29d8ca2e3b8c10ec11af08ff8d89fae578ab0b0a138fbd9ad4957a5c42b793c30e959ab4c17290f01972cd0d8de8128e7e79873e28c
+  data.tar.gz: 3b0acc643ffe9c06c6d07df9c5dce9a54d79351878354e30c1cc22fb5c5001debf9ac529ddeb873868ff713f455665c6e5fe992558d70ef376151f9b368b7086

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,60 +1,111 @@
+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
+
 AllCops:
   TargetRubyVersion: 3.4
   NewCops: enable
   SuggestExtensions: false
 
-Layout/LineLength:
-  Max: 160
+# 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:
   EnforcedStyle: space
-
 Layout/HashAlignment:
   EnforcedHashRocketStyle: table
   EnforcedColonStyle: table
-
 Metrics/MethodLength:
-  Max: 60
-
+  Max: 150
 Metrics/ClassLength:
   Max: 1500
-
 Metrics/ModuleLength:
   Max: 1500
-
 Metrics/BlockLength:
-  Max: 40
+  Max: 150
   Exclude:
     - 'spec/**/*'
 
 Metrics/AbcSize:
-  Max: 85
-
+  Max: 110
+Metrics/BlockNesting:
+  Max: 4
 Metrics/CyclomaticComplexity:
-  Max: 35
+  Max: 50
 
 Metrics/PerceivedComplexity:
-  Max: 35
-
+  Max: 50
 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
-
 Style/RedundantConstantBase:
   Exclude:
     - 'spec/**/*'

data/AGENTS.md

@@ -1,37 +1,90 @@
-# 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 (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`
+
+| Header | Value | Always? |
+|---|---|---|
+| `X-Claude-Code-Session-Id` | Stable UUID for the CLI session | Yes |
+| `x-app` | `"cli"` (foreground) or `"cli-bg"` (background) | Yes |
+| `x-claude-code-agent-id` / `x-claude-code-parent-agent-id` | Agent / parent-agent UUIDs | Conditional |
+
+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`
+
+| Header | Value | Always? |
+|---|---|---|
+| `session-id` | Stable UUID for the Codex session | Yes |
+| `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-turn-state` | Sticky-routing token, replayed by client | After first response |
+| `x-openai-subagent` | Sub-agent type (`review`, `compact`, …) | Conditional |
+
+`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
+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)}"
+```