feat(runtime): implement single-article consolidation runtime and modularize codebase
This commit is contained in:
@@ -0,0 +1,408 @@
|
||||
# Catálogo de métricas e KPIs — Runtime de consolidação de artigos
|
||||
|
||||
**Versão:** 1.0
|
||||
**Data:** 23 de agosto de 2026
|
||||
**Escopo:** runtime; self-healing excluído
|
||||
|
||||
**Regra mestre:** medir somente qualidade, operação, custo e riscos exigidos pelo runtime, sem criar telemetria sem consumidor ou finalidade definida.
|
||||
|
||||
## 1. Objetivo
|
||||
|
||||
Definir o que deve ser medido, como interpretar cada indicador, quais dimensões são permitidas e quais gates impedem o go-live ou uma promoção.
|
||||
|
||||
## 2. Princípios
|
||||
|
||||
- Invariantes críticas não são compensadas por média alta.
|
||||
- Métricas de qualidade devem ser segmentadas por idioma, domínio, extrator, modelo e prompt.
|
||||
- URLs, fingerprints e IDs de execução não devem virar labels de alta cardinalidade; pertencem a traces e logs.
|
||||
- Custo e latência são instrumentados antes de receber limites numéricos.
|
||||
- Limites são aprovados com baseline do staging, não inventados.
|
||||
- O runtime emite sinais objetivos para futura análise de prompt, mas não executa self-healing.
|
||||
|
||||
## 3. KPIs do produto
|
||||
|
||||
| KPI | Definição | Meta ou gate |
|
||||
| --- | --- | --- |
|
||||
| Publicação fundamentada | Markdown sem texto, URL ou imagem inventada | 100% |
|
||||
| Aprovação end-to-end textual | Artigos textuais que passam integralmente pela verdade de referência | ≥ 95% |
|
||||
| Integridade operacional | Artigos sem perda, corrupção ou duplicação | 100% |
|
||||
| Cobertura de telemetria | Trace enviado ou evento preservado | 100% |
|
||||
| Custo por Markdown aprovado | Custo LLM total dividido por Markdown aprovado | Limite aprovado após staging |
|
||||
| Latência end-to-end | Tempo recebido até persistência final | Limites p50/p95/p99 após staging |
|
||||
|
||||
## 4. Invariantes críticas
|
||||
|
||||
As seguintes métricas possuem meta zero e bloqueiam promoção quando maiores que zero:
|
||||
|
||||
| Métrica lógica | Evento contado |
|
||||
| --- | --- |
|
||||
| `ungrounded_text_total` | Texto publicado sem origem ou reparo autorizado |
|
||||
| `ungrounded_url_total` | URL publicada sem origem |
|
||||
| `ungrounded_image_total` | Imagem publicada sem origem |
|
||||
| `unauthorized_rewrite_total` | Reparo que resultou em paráfrase ou alteração semântica |
|
||||
| `critical_fact_change_total` | Nome, número, data, placar, citação ou fato alterado indevidamente |
|
||||
| `duplicate_output_total` | Saída final duplicada para mesmo fingerprint e versões |
|
||||
| `lost_article_total` | Entrada validada sem estado terminal rastreável |
|
||||
| `secret_exposure_total` | Credencial identificada em log, trace ou saída |
|
||||
| `powerful_runtime_model_call_total` | Chamada de modelo potente no runtime |
|
||||
| `online_promptfoo_call_total` | Promptfoo acionado pelo runtime |
|
||||
| `text_regex_usage_total` | Uso detectado de regex no pipeline textual/assertions |
|
||||
|
||||
## 5. Métricas de volume e resultado
|
||||
|
||||
| Métrica lógica | Definição |
|
||||
| --- | --- |
|
||||
| `article_received_total` | Execuções iniciadas |
|
||||
| `article_validated_total` | Entradas que passaram validação |
|
||||
| `article_duplicate_total` | Fingerprints já concluídos |
|
||||
| `article_completed_text_total` | Markdown produzido |
|
||||
| `article_rejected_ecp_total` | Rejeições esperadas pelo ECP |
|
||||
| `article_failed_validation_total` | Falhas antes do processamento |
|
||||
| `article_failed_processing_total` | Falhas após validação |
|
||||
|
||||
Taxas derivadas:
|
||||
|
||||
- conclusão textual por artigo validado;
|
||||
- rejeição ECP por artigo validado;
|
||||
- falha de validação por artigo recebido;
|
||||
- falha de processamento por artigo validado;
|
||||
- duplicidade por artigo recebido.
|
||||
|
||||
## 6. Métricas de entrada
|
||||
|
||||
| Métrica lógica | Dimensões de baixa cardinalidade |
|
||||
| --- | --- |
|
||||
| `input_validation_failure_total` | `reason`, `schema_version` |
|
||||
| `selected_extractor_total` | `extractor` |
|
||||
| `selected_extractor_unavailable_total` | `extractor` |
|
||||
| `source_language_total` | `language` |
|
||||
| `source_domain_group_total` | domínio controlado ou site cadastrado |
|
||||
| `ecp_version_total` | `ecp_schema_version` |
|
||||
|
||||
Domínio bruto de URL não deve virar label sem controle de cardinalidade. URLs individuais permanecem em trace/log.
|
||||
|
||||
## 7. Métricas de higienização
|
||||
|
||||
| Métrica lógica | Definição |
|
||||
| --- | --- |
|
||||
| `hygiene_call_total` | Chamadas lógicas de higienização |
|
||||
| `hygiene_schema_failure_total` | Respostas fora do schema |
|
||||
| `hygiene_grounding_failure_total` | IDs ou conteúdo sem origem |
|
||||
| `hygiene_fallback_total` | Uso de provider fallback |
|
||||
| `hygiene_deterministic_fallback_total` | Uso do fallback conservador |
|
||||
| `hygiene_terminal_failure_total` | Nenhum resultado seguro |
|
||||
| `block_candidate_total` | Blocos disponibilizados |
|
||||
| `block_kept_total` | Blocos selecionados |
|
||||
| `block_removed_total` | Blocos removidos |
|
||||
| `link_kept_total` | Links editoriais mantidos |
|
||||
| `image_kept_total` | Imagens editoriais comuns mantidas |
|
||||
|
||||
Nos evals:
|
||||
|
||||
- precisão de blocos;
|
||||
- recall de blocos;
|
||||
- perda material de conteúdo;
|
||||
- ruído residual;
|
||||
- precisão de links;
|
||||
- precisão de imagens;
|
||||
- acurácia de metadados.
|
||||
|
||||
## 8. Métricas de reparos textuais
|
||||
|
||||
| Métrica lógica | Definição |
|
||||
| --- | --- |
|
||||
| `text_repair_proposed_total` | Reparos propostos pelo LLM |
|
||||
| `text_repair_applied_total` | Reparos validados e aplicados |
|
||||
| `text_repair_rejected_total` | Reparos descartados |
|
||||
| `text_repair_category_total` | Reparos por categoria fechada |
|
||||
| `text_repair_ambiguous_target_total` | Fragmento não localizado inequivocamente |
|
||||
| `text_repair_sensitive_change_total` | Tentativa de alterar entidade sensível |
|
||||
|
||||
Dimensões permitidas:
|
||||
|
||||
- etapa ou campo;
|
||||
- categoria;
|
||||
- modelo;
|
||||
- versão do prompt;
|
||||
- idioma;
|
||||
- motivo de rejeição.
|
||||
|
||||
Texto original e substituição ficam no trace controlado, não em labels.
|
||||
|
||||
Gates:
|
||||
|
||||
- reparo indevido publicado: zero;
|
||||
- alteração crítica publicada: zero;
|
||||
- reparos rejeitados são medidos, não necessariamente erro terminal;
|
||||
- taxa de rejeição crescente sinaliza necessidade futura de revisão de prompt.
|
||||
|
||||
## 9. Métricas do ECP
|
||||
|
||||
| Métrica lógica | Definição |
|
||||
| --- | --- |
|
||||
| `ecp_classification_total` | Resultado por categoria |
|
||||
| `ecp_classification_failure_total` | Falha sem categoria válida |
|
||||
| `ecp_pass_total` | Direto ou contextual |
|
||||
| `ecp_reject_total` | Tangencial ou não relacionado |
|
||||
| `ecp_latency_seconds` | Duração do classificador |
|
||||
| `ecp_fallback_tier_total` | Tier usado pelo classificador, quando exposto |
|
||||
|
||||
A meta de qualidade intrínseca do classificador é herdada do projeto ECP e não duplicada neste catálogo. O runtime valida apenas integração, contrato, gate e resultado end-to-end.
|
||||
|
||||
## 10. Métricas de enriquecimento
|
||||
|
||||
| Métrica lógica | Definição |
|
||||
| --- | --- |
|
||||
| `sentiment_total` | Distribuição positive/negative/neutral |
|
||||
| `tag_count` | Quantidade de tags por artigo |
|
||||
| `enrichment_schema_failure_total` | Resposta inválida |
|
||||
| `enrichment_grounding_failure_total` | Evidência ou tag sem suporte |
|
||||
| `enrichment_fallback_total` | Uso de fallback barato |
|
||||
| `enrichment_terminal_failure_total` | Markdown bloqueado por falha final |
|
||||
|
||||
Nos evals, medir acurácia de sentimento relativo ao ECP e aceitação das tags conforme verdade de referência.
|
||||
|
||||
## 11. Métricas de LLM
|
||||
|
||||
Para cada generation:
|
||||
|
||||
- papel lógico;
|
||||
- provider;
|
||||
- modelo;
|
||||
- versão e hash do prompt;
|
||||
- versão do schema;
|
||||
- tentativa;
|
||||
- status;
|
||||
- tokens de entrada;
|
||||
- tokens de saída;
|
||||
- tokens em cache, quando disponíveis;
|
||||
- custo;
|
||||
- latência;
|
||||
- timeout;
|
||||
- retry;
|
||||
- fallback;
|
||||
- resultado de validação.
|
||||
|
||||
Métricas agregadas:
|
||||
|
||||
| Métrica lógica | Dimensões |
|
||||
| --- | --- |
|
||||
| `llm_request_total` | `logical_call`, `provider`, `model`, `status` |
|
||||
| `llm_input_tokens_total` | `logical_call`, `provider`, `model` |
|
||||
| `llm_output_tokens_total` | `logical_call`, `provider`, `model` |
|
||||
| `llm_cost_total` | `logical_call`, `provider`, `model` |
|
||||
| `llm_latency_seconds` | `logical_call`, `provider`, `model` |
|
||||
| `llm_retry_total` | `reason`, `provider`, `model` |
|
||||
| `llm_fallback_total` | `logical_call`, `reason` |
|
||||
| `llm_output_validation_failure_total` | `logical_call`, `reason`, `prompt_version` |
|
||||
|
||||
## 12. Sinais para futura revisão de prompt
|
||||
|
||||
O runtime não diagnostica causa-raiz nem inicia self-healing. Ele registra sinais objetivos que poderão alimentar alertas e análise futura:
|
||||
|
||||
| Sinal | Condição objetiva |
|
||||
| --- | --- |
|
||||
| `prompt_review_signal_total{reason=schema}` | Saída LLM fora do schema |
|
||||
| `prompt_review_signal_total{reason=grounding}` | ID, texto ou URL sem origem |
|
||||
| `prompt_review_signal_total{reason=repair}` | Reparo rejeitado |
|
||||
| `prompt_review_signal_total{reason=fallback}` | Primário exigiu fallback |
|
||||
| `prompt_review_signal_total{reason=terminal}` | Primário e fallback falharam |
|
||||
|
||||
Dimensões:
|
||||
|
||||
- chamada lógica;
|
||||
- prompt version;
|
||||
- provider/modelo;
|
||||
- idioma;
|
||||
- domínio controlado;
|
||||
- motivo.
|
||||
|
||||
Não existe:
|
||||
|
||||
- acionamento automático;
|
||||
- modelo otimizador;
|
||||
- judge;
|
||||
- prompt candidato;
|
||||
- alerta ativo como requisito deste projeto.
|
||||
|
||||
## 13. Métricas de persistência e idempotência
|
||||
|
||||
| Métrica lógica | Definição |
|
||||
| --- | --- |
|
||||
| `state_transition_total` | Transições por origem/destino |
|
||||
| `state_transition_failure_total` | Falhas de persistência |
|
||||
| `sqlite_lock_wait_seconds` | Espera por lock |
|
||||
| `sqlite_busy_failure_total` | Timeout de lock |
|
||||
| `atomic_write_failure_total` | Falhas em temporário/rename/hash |
|
||||
| `resume_total` | Execuções retomadas |
|
||||
| `idempotent_hit_total` | Resultado já concluído reutilizado |
|
||||
| `orphan_temp_file_total` | Temporários órfãos encontrados |
|
||||
|
||||
## 14. Métricas de observabilidade
|
||||
|
||||
| Métrica lógica | Meta |
|
||||
| --- | ---: |
|
||||
| `trace_created_total / article_validated_total` | 100% enviado ou pendente |
|
||||
| `telemetry_send_failure_total` | Medir; não bloquear artigo |
|
||||
| `telemetry_pending_total` | Deve retornar a zero após recuperação |
|
||||
| `telemetry_flush_failure_total` | Medir e preservar pendência |
|
||||
| `trace_content_disabled_total` | Informativa |
|
||||
| `trace_redaction_failure_total` | 0 |
|
||||
|
||||
## 15. Métricas de capacidade
|
||||
|
||||
Medir no staging e produção:
|
||||
|
||||
- artigos por hora;
|
||||
- execuções concorrentes;
|
||||
- duração total p50/p95/p99;
|
||||
- duração por estado p50/p95/p99;
|
||||
- CPU;
|
||||
- memória;
|
||||
- crescimento do SQLite;
|
||||
- uso de disco por saídas e temporários;
|
||||
- espera por lock;
|
||||
- falhas por saturação;
|
||||
- tokens e custo por artigo recebido;
|
||||
- tokens e custo por Markdown aprovado.
|
||||
|
||||
Gate já definido:
|
||||
|
||||
- sustentar 100 artigos por hora;
|
||||
- zero perda;
|
||||
- zero duplicação;
|
||||
- zero corrupção.
|
||||
|
||||
## 16. Baseline e definição de SLOs
|
||||
|
||||
### 16.1 Staging
|
||||
|
||||
Executar corpus representativo no ambiente equivalente ao de produção, incluindo idiomas, domínios, extratores, estruturas editoriais, ECP, fallback observado e concorrência real.
|
||||
|
||||
### 16.2 Relatório obrigatório
|
||||
|
||||
- tamanho e composição do corpus;
|
||||
- versões de código, prompt, modelo e ECP;
|
||||
- throughput;
|
||||
- latência p50/p95/p99 por etapa e total;
|
||||
- custo p50/p95/p99 por artigo;
|
||||
- custo por Markdown aprovado;
|
||||
- taxa de fallback;
|
||||
- utilização de recursos;
|
||||
- falhas e outliers.
|
||||
|
||||
### 16.3 Aprovação
|
||||
|
||||
Antes do go-live, registrar no runbook:
|
||||
|
||||
- limite de custo por artigo;
|
||||
- limite de custo por Markdown aprovado;
|
||||
- SLO de latência end-to-end;
|
||||
- timeouts por provider;
|
||||
- limite operacional de fallback;
|
||||
- limites de armazenamento.
|
||||
|
||||
Nenhum valor deve ser inserido sem evidência da baseline.
|
||||
|
||||
## 17. Logs estruturados
|
||||
|
||||
Campos mínimos:
|
||||
|
||||
- timestamp;
|
||||
- severity;
|
||||
- ambiente;
|
||||
- `run_id`;
|
||||
- fingerprint;
|
||||
- estado;
|
||||
- evento;
|
||||
- código de erro;
|
||||
- chamada lógica;
|
||||
- provider/modelo;
|
||||
- prompt version;
|
||||
- duração;
|
||||
- retry/fallback;
|
||||
- trace ID;
|
||||
- status final.
|
||||
|
||||
Campos proibidos:
|
||||
|
||||
- API keys;
|
||||
- headers de autorização;
|
||||
- secrets;
|
||||
- ECP integral;
|
||||
- HTML integral;
|
||||
- artigo integral por padrão.
|
||||
|
||||
Conteúdo necessário para diagnóstico fica no trace conforme política, com possibilidade de desativação.
|
||||
|
||||
## 18. Dashboards mínimos
|
||||
|
||||
### 18.1 Saúde do runtime
|
||||
|
||||
- recebidos, concluídos, rejeitados e falhos;
|
||||
- throughput;
|
||||
- latência;
|
||||
- custo;
|
||||
- providers;
|
||||
- fallback;
|
||||
- persistência;
|
||||
- telemetria pendente.
|
||||
|
||||
### 18.2 Qualidade
|
||||
|
||||
- schema e grounding;
|
||||
- reparos aplicados/rejeitados;
|
||||
- ECP;
|
||||
- sentimento e tags;
|
||||
- resultados por prompt/modelo/idioma/domínio.
|
||||
|
||||
### 18.3 Sinais de revisão futura
|
||||
|
||||
- `prompt_review_signal_total` por motivo;
|
||||
- falhas após fallback;
|
||||
- concentração por versão de prompt;
|
||||
- custo potencial associado aos casos.
|
||||
|
||||
O dashboard existe; alertas específicos de self-healing ficam para o subprojeto futuro.
|
||||
|
||||
## 19. Cardinalidade
|
||||
|
||||
Podem ser labels:
|
||||
|
||||
- ambiente;
|
||||
- estado;
|
||||
- código de erro;
|
||||
- chamada lógica;
|
||||
- provider;
|
||||
- modelo;
|
||||
- prompt version;
|
||||
- schema version;
|
||||
- idioma controlado;
|
||||
- extrator;
|
||||
- categoria ECP;
|
||||
- motivo categórico.
|
||||
|
||||
Não podem ser labels:
|
||||
|
||||
- URL;
|
||||
- fingerprint;
|
||||
- run ID;
|
||||
- trace ID;
|
||||
- título;
|
||||
- autor;
|
||||
- texto;
|
||||
- tag editorial livre;
|
||||
- nome livre de domínio não cadastrado.
|
||||
|
||||
## 20. Critério de aceite
|
||||
|
||||
O catálogo estará implementado quando:
|
||||
|
||||
- todas as invariantes críticas puderem ser medidas;
|
||||
- KPIs puderem ser calculados por slice;
|
||||
- Langfuse receber versões, custos, latência e scores;
|
||||
- logs forem estruturados e sanitizados;
|
||||
- telemetria pendente puder ser contada e reenviada;
|
||||
- sinais de revisão de prompt existirem sem acionar self-healing;
|
||||
- teste de staging produzir baseline completa;
|
||||
- limites de custo e latência forem aprovados e incorporados ao runbook antes do go-live.
|
||||
Reference in New Issue
Block a user