# 🧠 GroundedOS Lab — Confidence Calibration Phase
## Implementação: Evidence-Based Confidence Calibration + Uncertainty-Aware RAG
Você está trabalhando no projeto GroundedOS Lab.
Objetivo:
Implementar um sistema real de calibração de confiança para respostas RAG, indo além de:
- score do modelo
- score do chunk
- score do embedding
A confiança final deve ser baseada em evidência recuperada, consistência entre fontes, cobertura da pergunta, ausência/presença de contradições, groundedness e estabilidade do pipeline.
Essa implementação deve tornar o GroundedOS Lab capaz de responder não apenas “qual é a resposta?”, mas também:
- quão confiável é essa resposta?
- por que essa confiança é alta ou baixa?
- quais evidências sustentam a resposta?
- onde há lacunas?
- há contradições?
- a confiança mudou após reranking?
- o retrieval foi suficiente?
====================================================
# CONTEXTO ATUAL
====================================================
O projeto já possui:
- RAG pipeline
- retrieval traces
- hybrid search
- reranking
- semantic cache
- query understanding
- evals
- observability
- Dev Mode
- groundedness checks
- faithfulness/relevance/recall scorers
- retrieval diagnostics planejado
- adaptive retrieval planejado
- GraphRAG planejado
- LLM-as-judge planejado
Hoje a confiança tende a ser inferida de:
- score de chunks
- score do modelo
- heurísticas simples
O objetivo agora é criar um sistema formal de Confidence Calibration.
====================================================
# OBJETIVO PRINCIPAL
====================================================
Criar uma camada de calibração de confiança baseada em múltiplos sinais:
- retrieval confidence
- answer confidence
- evidence coverage
- agreement entre chunks
- source diversity
- contradiction detection
- rerank stability
- groundedness
- citation support
- query ambiguity
- corpus coverage
- confidence degradation factors
====================================================
# FASE A — CONFIDENCE CALIBRATION ENGINE
====================================================
Objetivo:
Criar engine central de confiança.
====================================================
## Criar
- ConfidenceCalibrationEngine
- ConfidenceSignalCollector
- ConfidenceScore
- ConfidenceBreakdown
- ConfidenceFactor
- ConfidenceTrace
- ConfidencePolicy
- CalibrationProfile
====================================================
## A engine deve calcular
- overallConfidence
- retrievalConfidence
- evidenceConfidence
- answerConfidence
- citationConfidence
- contradictionRisk
- uncertaintyLevel
====================================================
## Exemplo de saída
{
"overallConfidence": 0.74,
"label": "moderate",
"breakdown": {
"retrievalConfidence": 0.81,
"evidenceCoverage": 0.68,
"chunkAgreement": 0.77,
"sourceDiversity": 0.62,
"contradictionRisk": 0.18,
"groundedness": 0.84,
"rerankStability": 0.71
},
"uncertaintyReasons": [
"A cobertura da pergunta é parcial",
"As fontes recuperadas são pouco diversas"
],
"recommendedAction": "answer_with_uncertainty"
}
====================================================
# FASE B — CONFIDENCE SIGNALS
====================================================
Objetivo:
Coletar sinais de confiança de várias etapas do pipeline.
====================================================
## Sinais mínimos
### 1. Retrieval score signals
- top chunk score
- average topK score
- score distribution
- score gap between top results
- score threshold margin
- retrieval saturation
====================================================
### 2. Evidence coverage signals
- quantas partes da pergunta foram cobertas
- quais subperguntas têm evidência
- quais entidades foram encontradas
- quais entidades ficaram sem evidência
- cobertura por fonte
====================================================
### 3. Chunk agreement signals
- chunks concordam entre si?
- múltiplos chunks sustentam a mesma afirmação?
- evidência é redundante ou complementar?
- há consenso entre evidências?
====================================================
### 4. Source diversity signals
- número de documentos distintos
- número de tipos de fonte
- diversidade temporal
- diversidade de autoria/origem
- concentração excessiva em uma única fonte
====================================================
### 5. Contradiction signals
- chunks contraditórios
- datas conflitantes
- versões conflitantes
- decisões antigas vs novas
- ADR substituído por outro
====================================================
### 6. Groundedness signals
- resposta suportada pelos chunks?
- existem claims sem evidência?
- citações sustentam a afirmação?
- answer spans mapeiam para evidence spans?
====================================================
### 7. Rerank stability signals
- ranking mudou muito após rerank?
- chunks relevantes foram promovidos?
- chunks relevantes foram rebaixados?
- top results são estáveis entre estratégias?
====================================================
### 8. Query risk signals
- query ambígua
- query crítica
- query multi-hop
- query exige precisão alta
- query exige resposta normativa
====================================================
# FASE C — EVIDENCE COVERAGE ESTIMATOR
====================================================
Objetivo:
Medir se a evidência recuperada cobre a pergunta.
====================================================
## Criar
- EvidenceCoverageEstimator
- QueryFacetExtractor
- FacetCoverageResult
- MissingEvidenceDetector
====================================================
## Fluxo
query
→ extrair facets/subperguntas
→ mapear chunks para facets
→ calcular cobertura
→ identificar lacunas
====================================================
## Exemplo
Query:
"Compare auth changes between phase 5 and phase 6"
Facets:
- auth in phase 5
- auth in phase 6
- changes/differences
- evidence from ADRs/docs
Coverage:
- phase 5: 0.9
- phase 6: 0.7
- differences: 0.6
- ADR evidence: 0.3
====================================================
# FASE D — AGREEMENT / CONSENSUS ENGINE
====================================================
Objetivo:
Detectar concordância entre evidências.
====================================================
## Criar
- EvidenceAgreementAnalyzer
- ClaimExtractor
- ClaimSupportMapper
- ConsensusScore
- EvidenceCluster
====================================================
## Fluxo
chunks
→ extrair claims
→ agrupar claims similares
→ mapear suporte
→ calcular agreement
====================================================
## Resultado
- claims supported by multiple chunks
- claims supported by single chunk
- claims unsupported
- weakly supported claims
- conflicting claims
====================================================
# FASE E — CONTRADICTION DETECTION
====================================================
Objetivo:
Detectar conflitos entre chunks/documentos.
====================================================
## Criar
- ContradictionDetector
- ConflictPair
- ConflictSeverity
- ConflictResolutionHint
====================================================
## Tipos de contradição
- value_conflict
- date_conflict
- version_conflict
- status_conflict
- decision_conflict
- source_conflict
- semantic_conflict
====================================================
## Exemplo
Documento antigo:
"Auth uses session tokens."
Documento novo:
"Auth uses JWT."
Diagnóstico:
- version_conflict
- possível substituição arquitetural
- confiança reduzida se não houver evidência de timeline
====================================================
# FASE F — SOURCE DIVERSITY SCORING
====================================================
Objetivo:
Medir diversidade e independência das fontes.
====================================================
## Criar
- SourceDiversityAnalyzer
- SourceIndependenceScore
- EvidenceProvenanceAnalyzer
====================================================
## Considerar
- documentos distintos
- chunks do mesmo documento
- autores/origens diferentes
- datas diferentes
- tipos diferentes: ADR, README, code, docs, eval artifacts
- fontes primárias vs derivadas
====================================================
## Penalizar
- evidência concentrada em um único chunk
- múltiplos chunks duplicados
- fontes antigas sem atualização
- fontes sem provenance
====================================================
# FASE G — RERANK STABILITY
====================================================
Objetivo:
Medir estabilidade do ranking.
====================================================
## Criar
- RerankStabilityAnalyzer
- RankingDelta
- RankCorrelationScore
- RetrievalStabilityReport
====================================================
## Medir
- diferença entre ranking inicial e reranked
- estabilidade entre runs
- estabilidade entre providers
- sensibilidade a query rewrite
- sensibilidade a topK
- impacto do reranker
====================================================
## Exemplo
Se a resposta depende de um chunk que só aparece após reranking agressivo:
- confiança moderada
- registrar dependência do reranker
- sugerir validação extra
====================================================
# FASE H — CONFIDENCE POLICIES
====================================================
Objetivo:
Definir como o sistema deve agir com base na confiança.
====================================================
## Criar
- ConfidencePolicyEngine
- ConfidenceAction
- ConfidenceThresholds
====================================================
## Ações possíveis
- answer_normally
- answer_with_uncertainty
- request_clarification
- run_additional_retrieval
- run_self_check
- run_contradiction_check
- refuse_due_to_insufficient_evidence
- cite_limitations
- escalate_to_deep_retrieval
====================================================
## Labels
- very_low
- low
- moderate
- high
- very_high
====================================================
# FASE I — UNCERTAINTY-AWARE ANSWER GENERATION
====================================================
Objetivo:
Fazer a resposta refletir corretamente a confiança.
====================================================
## Requisitos
Se confiança alta:
- responder diretamente
- citar evidências
Se confiança moderada:
- responder com ressalvas
- indicar lacunas
Se confiança baixa:
- não inventar
- dizer que evidência é insuficiente
- sugerir próxima ação
====================================================
## Exemplo
"Com base nas evidências recuperadas, a resposta mais provável é..."
"Não encontrei evidência suficiente para afirmar com segurança..."
"Há sinais conflitantes entre os documentos..."
====================================================
# FASE J — CONFIDENCE CALIBRATION DATASET
====================================================
Objetivo:
Criar dataset para calibrar confiança.
====================================================
## Criar amostras
- respostas corretas com alta evidência
- respostas corretas com evidência parcial
- respostas incorretas com score alto
- retrieval com semantic drift
- chunks contraditórios
- fontes duplicadas
- query ambígua
- resposta sem evidência
====================================================
## Cada item deve conter
- query
- retrievedChunks
- answer
- expectedConfidence
- expectedLabel
- knownFailureModes
- expectedAction
====================================================
# FASE K — EVALS / BENCHMARKS
====================================================
Objetivo:
Avaliar se a confiança está bem calibrada.
====================================================
## Métricas
- calibration error
- expected calibration error
- confidence vs correctness correlation
- overconfidence rate
- underconfidence rate
- Brier score
- abstention quality
- uncertainty usefulness
- contradiction detection accuracy
- coverage estimation accuracy
====================================================
## Comparações
- chunk score only vs calibrated confidence
- model score only vs calibrated confidence
- calibrated confidence before/after rerank
- dense retrieval vs hybrid retrieval
- with/without contradiction detection
====================================================
# FASE L — OBSERVABILITY / DEV MODE
====================================================
Todas as decisões de confiança DEVEM aparecer no Dev Mode.
====================================================
## Mostrar
- overall confidence
- confidence label
- breakdown por fator
- uncertainty reasons
- missing evidence
- contradictions
- source diversity
- agreement score
- rerank stability
- groundedness score
- policy action selected
====================================================
## Confidence Trace
Exemplo:
overall confidence: moderate 0.74
retrieval confidence: high
evidence coverage: partial
contradiction risk: low
source diversity: medium
policy action: answer_with_uncertainty
====================================================
# FASE M — FRONTEND / LAB
====================================================
Adicionar:
1. Confidence Dashboard
2. Confidence Breakdown Panel
3. Evidence Coverage Viewer
4. Agreement/Consensus Panel
5. Contradiction Viewer
6. Source Diversity Map
7. Rerank Stability Viewer
8. Calibration Benchmark Viewer
====================================================
## Visualizações
Mostrar:
- quais fatores aumentaram confiança
- quais fatores reduziram confiança
- quais evidências sustentam cada claim
- quais claims não têm suporte
- onde há conflito
- como reranking mudou a confiança
====================================================
# FASE N — API
====================================================
Criar ou evoluir endpoints:
POST /confidence/score
POST /confidence/calibrate
POST /confidence/evaluate
POST /confidence/explain
GET /confidence/policies
GET /confidence/runs
====================================================
## Payloads devem permitir
- query
- answer
- retrievedChunks
- citations
- retrievalTrace
- rerankTrace
- confidenceProfile
- includeContradictionCheck
- includeCoverageCheck
- includeAgreementCheck
- devMode
====================================================
# FASE O — TESTES
====================================================
Adicionar testes para:
- confidence score aggregation
- evidence coverage estimation
- agreement detection
- contradiction detection
- source diversity scoring
- rerank stability analysis
- confidence policy selection
- uncertainty-aware answer formatting
- calibration dataset validation
- benchmark calculations
====================================================
# OUTPUT ESPERADO
====================================================
Quero que você entregue:
1. Arquitetura proposta
2. Estrutura de pastas
3. Interfaces TypeScript principais
4. Confidence Calibration Engine
5. Estratégia de signal collection
6. Estratégia de evidence coverage
7. Estratégia de agreement entre chunks
8. Estratégia de source diversity
9. Estratégia de contradiction detection
10. Estratégia de rerank stability
11. Estratégia de confidence policies
12. Estratégia de uncertainty-aware generation
13. Dataset de calibração
14. Evals/benchmarks necessários
15. Integração com Dev Mode
16. Sugestões de UI
17. Trade-offs
18. Riscos técnicos
19. Estratégia incremental de implementação
20. Exemplos de payloads
21. Exemplo end-to-end de confidence calibration
22. Exemplo de Confidence Trace
23. Comparação entre score simples vs confiança calibrada
IMPORTANTE:
A implementação deve tratar confiança como um produto de evidência, cobertura, consenso e estabilidade, não como um número decorativo vindo do modelo ou do score do chunk.
