fix(rlm): point install guidance at official rlm package, not aragora[rlm] extra

[scarmani]

Source

Tier-2 source-correctness fix from the docs-extras sweep (PR #8548 handoff discoveredIssues[1]), plus the misc-1 scrutiny nonBlockingIssues docs item.

Problem

aragora/rlm/factory.py (and several sibling RLM modules) emitted user-facing log/error messages instructing pip install aragora[rlm]. But rlm is not a pyproject [project.optional-dependencies] extra. The authoritative extra set is: all, blockchain, connectors, dev, enterprise, experimental, gateway, test. The base install ships only the compression fallback (gated by HAS_OFFICIAL_RLM); real RLM comes from the official rlm PyPI distribution. The guidance therefore pointed users at a nonexistent extra.

docs/status/STATUS.md had the mirror inconsistency: it claims real RLM support but showed pip install aragora (which ships only the fallback).

Change

Primary change is string-only correctness. All install-guidance now instructs pip install rlm:

• aragora/rlm/factory.py — 4 messages (collapsed the redundant aragora[rlm] or pip install rlm)
• aragora/rlm/__init__.py — docstring install block simplified to the single official install
• aragora/rlm/adapter.py, aragora/knowledge/mound/api/rlm.py, aragora/debate/cognitive_limiter_rlm.py, aragora/memory/cross_debate_rlm.py — docstring/log guidance
• docs/status/STATUS.md — RLM install prose pip install aragora → pip install rlm
• tests/{rlm,debate}/test_cognitive_limiter_rlm.py — docstring guidance kept consistent

No factory logic or control-flow change. docs/status/STATUS.md is not a sync-docs.js source (verified: node scripts/sync-docs.js produces zero docs-site/ drift), so no mirror regen; docs/archive/** untouched.

Required-gate follow-on (commit 2)

The required CI typecheck check is an absolute changed-file gate (mypy --ignore-missing-imports --follow-imports=skip, no baseline) that fails on ANY error in touched files. Touching cognitive_limiter_rlm.py and knowledge/mound/api/rlm.py surfaces 5 pre-existing union-attr/no-redef errors (verified present on origin/main). Resolved behavior-preservingly (annotations/comment only, no runtime change):

• _aragora_rlm: Any | None → Any (collapse redundant union; the value is factory-produced Any)
• source: Any = getattr(...) on the two knowledge-item loops
• # type: ignore[no-redef] on the conditional aragora.rlm.bridge import (matches the file's existing conditional-import convention, e.g. knowledge/mound/api/rlm.py lines 45-48)

Validation

rg -n --fixed-strings 'aragora[rlm]' aragora/ tests/     # -> zero matches (exit 1)
mypy --ignore-missing-imports --follow-imports=skip <6 touched files>   # Success: no issues found
make lint                                                # All checks passed!
ruff format --check aragora/ tests/ scripts/             # all formatted
bash typecheck_differential.sh                           # PASS (new=62 <= env drift 66)
pytest tests/rlm tests/debate/test_cognitive_limiter_rlm.py \
       tests/knowledge/mound/adapters/test_rlm_adapter.py \
       tests/handlers/test_rlm.py tests/handlers/features/test_rlm.py   # 1475 passed
pytest tests/memory/test_cross_debate_rlm.py tests/rlm/test_factory_integration.py  # 77 passed
make test-smoke                                          # Smoke tests passed!
PYTEST_BIN="python3 -m pytest" bash scripts/test_tiers.sh smoke   # 138 passed

Risk

Minimal. Install-guidance/docstring edits plus behavior-preserving type annotations to satisfy the absolute changed-file typecheck gate. No behavioral change to the RLM factory/fallback flow. No test asserts on the old string.

[github-actions]

Aragora Code Review

Advisory-only review. Findings are surfaced for follow-up and do not fail this workflow.

Revised Review Findings (Round 2 – Skeptical Review)

Based on the critiques received, I have re‑evaluated every change in the diff through a skeptical lens, focusing on assumptions, edge cases, and the concrete evidence in the codebase.

Security

No issues found. The diff touches only documentation strings, type annotations, and a minor local‑variable refactor. No injection, authentication, secret handling, or deserialization patterns are introduced.

Performance

No issues found. The local variable caching (rlm = self._aragora_rlm) in cognitive_limiter_rlm.py is a negligible performance change. No N+1 queries, unbounded collections, or blocking I/O are added.

Code Quality

Issue 1: Globally incorrect installation instructions – medium severity (upgraded from LOW)

Location: Every docstring, log message, and comment that previously read pip install aragora[rlm] is now changed to pip install rlm. Affected files:

• aragora/debate/cognitive_limiter_rlm.py (lines 16, 44, 205)
• aragora/knowledge/mound/api/rlm.py (lines 14, 228, 260, 370)
• aragora/memory/cross_debate_rlm.py (line 27)
• aragora/rlm/__init__.py (line 20)
• aragora/rlm/adapter.py (line 852)
• aragora/rlm/factory.py (lines 231, 267, 271, 471)
• docs/status/STATUS.md (line 1968)
• tests/debate/test_cognitive_limiter_rlm.py (line 18)
• tests/rlm/test_cognitive_limiter_rlm.py (line 8)

Problem: The PR asserts that the official RLM library is distributed as a standalone rlm package on PyPI. However, the diff provides no evidence that such a package exists or that the packaging configuration has been updated:

• Evidence [EVID‑1] (Import paths unchanged): The code itself still imports from aragora.rlm (e.g., from aragora.rlm import get_rlm, get_compressor, HAS_OFFICIAL_RLM in cognitive_limiter_rlm.py lines 40–43). If the RLM functionality were truly separated into a standalone package, these imports would almost certainly change to from rlm import …. The fact they remain unchanged strongly suggests the code still lives inside the aragora namespace.
• Evidence [EVID‑2] (No packaging changes): The PR does not touch setup.py, pyproject.toml, or any other packaging configuration that would create a rlm package alias or transform aragora[rlm] into a separately installable unit. Without such changes, pip install rlm will resolve to nothing (or a completely different package) and will fail for every user who follows the new instructions.
• Evidence [EVID‑3] (Removal of fallback alternative): In aragora/rlm/factory.py line 231 the original message gave two options: "Install with: pip install aragora[rlm] or pip install rlm". The PR deletes the aragora[rlm] alternative entirely, leaving only pip install rlm. This removal of a known‑working path without any indication that the standalone package is actually available is a high‑risk change.

Impact: Users attempting to install RLM support will encounter a pip error (No matching distribution found for rlm) and will not be able to use the RLM features. This is a functional, not merely cosmetic, problem that will generate support tickets and confusion.

Suggestion:

1. If the split is truly intended: Immediately update the packaging configuration (pyproject.toml / setup.py) to register the rlm package on PyPI and update the import paths so that the code can actually be used as a standalone package. Only then should the installation instructions be changed.
2. If the split has not been implemented: Revert all instructions back to pip install aragora[rlm] (or use a hybrid message that clearly indicates the current, working installation method). Remove the standalone rlm instruction to avoid misleading users.
3. As a temporary safe guard: Until the packaging is confirmed, keep the alternative of both methods from factory.py line 231, and for other messages, use a form like “Install with: pip install aragora[rlm] (if using the aragora ecosystem) or pip install rlm (when available as a standalone package)” to preserve backward compatibility while allowing future migration.

Issue 2: Inconsistent error‑message formatting – low severity

Location: aragora/knowledge/mound/api/rlm.py line 230 (the log message was shortened from a multi‑line format to a single line). Similar inconsistencies appear in other files (e.g., cognitive_limiter_rlm.py lines 44, 205).

Problem: Some log and error messages in the codebase are written as multi‑line strings with line breaks, while others are collapsed into a single line. This inconsistency makes it harder to maintain and to grep for all occurrences when the installation instructions need to be updated again.

Suggestion: Once the correct installation method is determined (see Issue 1), standardise the format across all RLM‑related files. Either use a consistently short message or a consistently formatted multi‑line message, and apply that to every log/warning/error.

What I Changed and Why (Response to Critiques)

1. Severity upgrade (LOW → MEDIUM) for the installation instruction issue: The original critique correctly pointed out that my initial LOW rating underestimated the real‑world impact – a broken pip install instruction is a functional, not a cosmetic, problem. I have therefore raised the severity to MEDIUM and added concrete evidence chains ([EVID‑1], [EVID‑2], [EVID‑3]) that demonstrate the inconsistency between the documentation and the actual code layout.

2. Added [EVID‑2] (no packaging changes) and [EVID‑3] (removal of fallback alternative): These strengthen the argument by showing that the PR not only fails to create the standalone package but also actively removes the only known‑working installation path. This makes the risk of a merge significantly higher.

3. Retained the minor consistency issue (Issue 2): I agree with the critic’s observation that the error‑message formatting is inconsistent. I have kept it as a LOW‑severity quality item because it is a real, though minor, maintainability concern that should be addressed alongside the main installation instruction fix.

4. Did not add any further performance or security issues: I thoroughly reviewed the diff again and found no new attack surfaces, performance regressions, or edge‑case failures beyond those already noted.

Final Recommendation

Do not merge this PR until the packaging model is verified. If the intent is to promote a separate rlm package, that must be reflected in the packaging configuration and in the import paths before the documentation is changed. If the RLM remains part of aragora, all installation instructions should be reverted to the currently working pip install aragora[rlm] form. Applying the documentation changes in isolation will cause real user‑facing failures.

1 finding(s) across the diff

[CRITICAL] Finding

Finding

---

Generated by Aragora multi-agent code review

[scarmani]

Claude independent model review

Reviewer: claude (anthropic) — independent adversarial model review via the Aragora Claude reviewer, grounded on the exact PR head.
Head: 54e38a2 (54e38a2), committed 2026-06-24T10:38:00Z.
PR: #8593.
Model family: claude

Verdict: PASS

• [P3] docs/status/STATUS.md:1968 — the block is headed "Install with real RLM support" but the command changed from pip install aragora to pip install rlm, dropping aragora entirely. A reader following only this standalone snippet would install the external RLM lib but not aragora itself. Consider pip install aragora rlm (or two lines) to keep the snippet self-sufficient; the in-code docstrings are fine since they address users who already have aragora.

dogfood: yes

[scarmani]

Grok independent model review

Reviewer: grok (xai) — independent adversarial model review via Grok Build CLI harness, grounded on the exact PR head.
Head: 54e38a2 (54e38a2), committed 2026-06-24T10:38:00Z.
PR: #8593.
Model family: grok

Verdict: PASS

No findings.

dogfood: yes