feat(rag): implementa proposta pos-Recaman e metrica de diversidade (R457)

Author: MarceloClaro

VALIDATION_R457.md

@@ -0,0 +1,75 @@
+# Recibo local de validação — SPEC-935-R457
+
+## Escopo
+
+Implementação da **proposta pós-Recamán** documentada no manual técnico RAG
+(SPEC-935-R456): um conjunto de artefatos que diversificam de forma
+**determinística** e **estruturada** o ranking pós-ranqueado da arquitetura RAG,
+fechando a lacuna de métrica de diversidade do painel `EnhancedRAG.metrics()`.
+
+A implementação é **aditiva, de baixo acoplamento e não-invasiva**: cria o módulo
+`rag/recaman.py` e acrescenta um campo novo (`diversity`) ao dicionário de
+métricas, sem alterar o contrato dos campos existentes nem o comportamento dos
+ranqueadores atuais.
+
+## Artefatos implementados (GREEN)
+
+| Artefato | Descrição |
+|---|---|
+| `rag/recaman.py` | Novo módulo 100% stdlib, determinístico. |
+| `recaman_sequence(n)` | Gera os `n` primeiros termos de A005132 (oráculo OEIS). |
+| `ArtifactType` | Enum de classificação semântica (paper/regulation/judicial/clinical/generic). |
+| `AnchorResolver` | Deduplica por âncora canônica (identidade de fonte/âmago). |
+| `RecamanDiversifier` | Diversifica ranking via offsets `(1 + a_m) mod N` (Tabela 1 do manual). |
+| `CanonicalContextPacker` | Posiciona âncoras distintas de forma determinística (mitiga "lost in the middle"). |
+| `diversity(items)` | Métrica Div(S) ∈ [0,1] sobre âncoras canônicas (Eq. 6.1 do manual). |
+| `EnhancedRAG.metrics()` | Integração ADITIVA: novo campo `diversity`, sem remover/renomear os 4 existentes. |
+
+## Evidência observada
+
+```text
+25 passed in 0.34s   # tests/test_r457_recaman_diversifier.py (25 contratos GREEN)
+48 passed in 0.81s   # R457 + R456 + R455
+47 passed in 6.49s   # regressão R436 (enhanced_search_rag) + R99 (rag_evolved)
+```
+
+## Fidelidade matemática ao manual
+
+- **Oráculo OEIS A005132**: `[0,1,3,6,2,7,13,...]` — confirmado por teste.
+- **Tabela 1 (N=8)**: índices `(1 + a_m) mod 8 = [1,2,4,7,3,0]` — confirmado por teste.
+- **Seção 5.1**: relevância primária (top-1) nunca perdida — confirmado por teste
+  para vários `k`.
+- **Seção 6.1**: Div(S) ≈ 0 para itens idênticos; ≈ 1 para itens disjuntos —
+  confirmado por teste.
+- **Custo O(N)/O(M)**: implementação iterativa com conjunto visitado; sem
+  recursão, termina sempre — confirmado por teste para N até 512.
+
+## Distinção escopo (anti-overclaim)
+
+- A implementação **torna a capacidade e a métrica disponíveis**, mas **NÃO
+  promove o diversificador ao pipeline padrão**: a flag `_DIVERSIFIER_ENABLED`
+  permanece `False` e o fluxo principal fica configurável/desligado.
+- **NÃO** alega ganhos empíricos de qualidade (isso exige experimento de coorte
+  futuro, fora desta spec).
+- **NÃO** altera ranqueamento primário (BM25/denso) nem roteamento adaptativo.
+
+## Comandos executados
+
+```bash
+cd /home/marceloclaro/opencode-ecosystem-core
+python3 -m pytest tests/test_r457_recaman_diversifier.py -q
+python3 -m pytest tests/test_r457_recaman_diversifier.py tests/test_r456_manual_tecnico_rag.py tests/test_r455_readme_historico_operacional.py -q
+python3 -m pytest tests/test_r436_enhanced_search_rag.py tests/test_r99_rag_evolved.py -q
+python3 -m marceloclaro.cli doctor
+```
+
+## Limites conhecidos
+
+- O `diversity` é computado sobre âncoras canônicas (source/doc_id/title), que é
+  uma aproximação determinística de "âmago" sem embeddings — suficiente para a
+  métrica, que pode ser refinada em ciclo futuro.
+- Para `N` pequenos, offsets de Recamán repetem posições; o `diversify` pula
+  posições já usadas e completa por relevância, garantindo unicidade.
+- A sequência de Recamán legitimanmente revisita valores (A005132 não é injetora
+  para `n` grande) — os testes refletem a definição real, não uma premissa falsa
+  de termos todos distintos.

evolution/cycles.json

@@ -5042,6 +5042,25 @@
         "Tabelas em ABNT dentro de ambientes com recuo (quote) devem usar linewidth e colunas raggedright (L{}) para nao estourar as margens; e o comando marginpar colide com as margens ABNT estreitas, devendo ser desativado em favor de marcadores inline."
       ],
       "timestamp": 1788096506.2147543
+    },
+    {
+      "round_id": "R457",
+      "objective": "Implementacao da proposta pos-Recaman (SPEC-935-R456): diversificador estruturado deterministico + metrica de diversidade.",
+      "changes": [
+        "rag/recaman.py (novo, 100% stdlib): recaman_sequence (oraculo A005132), ArtifactType, AnchorResolver, RecamanDiversifier (offsets (1+a_m) mod N, Tabela 1), CanonicalContextPacker e metrica diversity() (Eq. 6.1 Div(S)).",
+        "rag/enhanced_search_rag.py: integracao ADITIVA de EnhancedRAG.metrics() com novo campo 'diversity' em [0,1], sem quebrar os 4 campos historicos; flag _DIVERSIFIER_ENABLED=False (pipeline padrao nao aciona).",
+        "specs/SPEC-935-R457-implementacao-proposta-recaman.md criada (status green com 13 criterios executaveis).",
+        "tests/test_r457_recaman_diversifier.py: 25 contratos GREEN (oraculo, tabela N=8, determinismo, relevancia primaria, orcamento, DEDUP por ancora, faixa/identicos/disjuntos Div, packer canonico, integracao aditiva).",
+        "VALIDATION_R457.md criado com escopo e limites anti-overclaim."
+      ],
+      "score": 9.0,
+      "lessons": [
+        "A sequencia de Recaman (A005132) NAO e injetora para n grande (revisita valores); testes que exigem 'todos termos distintos' sao incorretos e devem ser corrigidos para refletir a definicao real.",
+        "Implementacao 'da proposta do manual' deve preservar o espirito anti-overclaim: expor a capacidade e a metrica, deixar o pipeline padrao desligado (flag) e nao alegar ganho empirico sem experimento de coorte.",
+        "Integracao de metrica nova em API existente deve ser aditiva (append de chave) e tolerante (try/except), para nao quebrar contrato nem falhar se o modulo opcional estiver ausente.",
+        "Os offsets da Tabela 1 sao (1 + a_m) mod N, nao a_m mod N: a coluna 0 (relevancia max) e coberta no percurso e o topo nunca e perdido."
+      ],
+      "timestamp": 1788099545.03523
     }
   ]
 }

rag/enhanced_search_rag.py

@@ -31,6 +31,15 @@
     CitationGraph = object  # type: ignore
     RAGEvolved = object  # type: ignore
 
+# ── Diversificador proposto (SPEC-935-R457) ────────────────────────────────
+_DIVERSIFIER_ENABLED = False  # API exposta; pipeline padrão não a aciona ainda.
+try:
+    from rag.recaman import RecamanDiversifier as _RecamanDiversifier
+    from rag.recaman import diversity as _diversity
+except Exception:
+    _RecamanDiversifier = None  # type: ignore
+    _diversity = None  # type: ignore
+
 try:
     from research.searchers import PaperRecord, MultiSearcher
 except Exception:
@@ -542,9 +551,18 @@ def answer_grounded(self, query: str, top_k: int = 3) -> Dict[str, Any]:
         }
 
     def metrics(self, evidence: List[Any]) -> Dict[str, float]:
-        """Métricas de qualidade do retrieval."""
+        """Métricas de qualidade do retrieval (inclui diversidade — SPEC-935-R457).
+
+        Retorna os 4 campos históricos (groundedness, citation_coverage,
+        temporal_spread, avg_year) mais o novo campo ``diversity`` em [0,1]
+        (Div(S) sobre âncoras canônicas), de forma ADITIVA e sem quebrar
+        contrato existente.
+        """
         if not evidence:
-            return {"groundedness": 0.0, "citation_coverage": 0.0, "temporal_spread": 0.0, "avg_year": 0.0}
+            return {
+                "groundedness": 0.0, "citation_coverage": 0.0,
+                "temporal_spread": 0.0, "avg_year": 0.0, "diversity": 0.0,
+            }
         # groundedness = média dos final_score
         scores = [float(getattr(ev, "final_score", 0) or (ev.get("final_score", 0) if isinstance(ev, dict) else 0)) for ev in evidence]
         groundedness = sum(scores) / len(scores) if scores else 0.0
@@ -556,11 +574,16 @@ def metrics(self, evidence: List[Any]) -> Dict[str, float]:
         years = [y for y in years if isinstance(y, int)]
         temporal_spread = float(max(years) - min(years)) if len(years) >= 2 else 0.0
         avg_year = float(sum(years) / len(years)) if years else 0.0
+        # diversity (SPEC-935-R457) — Div(S) sobre âncoras canônicas.
+        div_value = 0.0
+        if _diversity is not None:
+            div_value = float(_diversity(evidence))
         return {
             "groundedness": round(groundedness, 4),
             "citation_coverage": round(citation_coverage, 4),
             "temporal_spread": temporal_spread,
             "avg_year": round(avg_year, 1),
+            "diversity": round(div_value, 4),
         }
 
     def status(self) -> Dict[str, Any]: