agent_contas/docs/PENTE_FINO_PARIDADE_TOOLS_CONTAS.md

Pente-fino de paridade — Contas original x Contas migrado

Escopo

Comparação funcional e arquitetural das 18 capabilities solicitadas, tomando como fonte de verdade o projeto Contas original e preservando, no migrado, as responsabilidades genéricas do agent_framework_oci (roteamento, confirmação, pause/resume, RAG, memória, observabilidade e política de tools).

Tools/capabilities avaliadas:

consultar_faturas, consultar_plano, invoice_explanation, buscar_informacao, consultar_vas, consultar_historico_vas, cancelar_vas_avulso, tratar_vas_estrategico, validar_contestacao, contestar_cobranca, finalizar_atendimento, consultar_status_solicitacao, enviar_sms, recuperar_fatura_pdf, pro_rata, termino_desconto, valor_divergente, retomar_workflow.

Resultado executivo

Depois das correções deste pente-fino, as 18 capabilities estão expostas no MCP e habilitadas no registry do agente. Os workflows conversacionais principais foram preservados do original. Os YAMLs buscar_fatura, buscar_informacao, cancelamento_vas_avulso, finalizar_atendimento, invoice_explanation, pro_rata, termino_desconto, valor_divergente e vas_estrategico permanecem equivalentes ao original. contestacao_tool contém uma diferença intencional de segurança: se a validação financeira falhar, o fluxo termina antes de SMS/contrato/SR.

A suíte completa do projeto após as mudanças executa 715 testes com sucesso.

Paridade por capability

Capability	Fonte/semântica no original	Situação após pente-fino	Ação tomada
consultar_faturas	complete_invoices + prefetch de bill_pdf + resumo semântico	Corrigida	Mantida a API de Complete Invoices e restaurados invoice_amount, invoice_amount_open, período e emissão a partir do PDF, sem inventar campo no backend.
consultar_plano	Evidência da própria fatura/billing analysis	OK	Extração determinística de seções Plano/Planos; não usa RAG nem inferência livre da LLM.
invoice_explanation	Workflow v2 + evidência da fatura + capability LLM de reescrita + pause	Corrigida	invoice_detail e resumo semântico agora chegam ao workflow; composição volta a ser da LLM do framework; await_user_input=True restaurado.
buscar_informacao	Tool RAG ativa (queries e query legado)	Corrigida arquiteturalmente	Reexposta como façade MCP compatível. Não duplica RAG no domínio: retorna requires_rag e delega ao RagService do framework. Suporta queries[] e query.
consultar_vas	Consulta de VAS ativos	OK	Mantida integração direta e resolução de domínio para os fluxos que precisam classificar item.
consultar_historico_vas	Histórico de VAS/serviços	OK	Mantido contrato da integração e normalização usada pelo cancelamento.
cancelar_vas_avulso	Tool ativa, somente avulso, confirmação, cancelamento + contestação automática	OK	Confirmação permanece no framework; preflight resolve nome/classe contra a fatura; workflow composto preserva cancelamento + contestação e protocolos.
tratar_vas_estrategico	vas_estrategico, bundle/estratégico	OK	Alias semântico migrado para tratar_vas_estrategico; workflow v3 preservado; redirecionamento automático evita cancelar estratégico como avulso.
validar_contestacao	Não existia como tool pública; regras CVAL existiam na execução	Corrigida	A pré-validação agora usa a mesma validate_contestation_items da execução financeira; deixa de aprovar algo que seria bloqueado depois. Usa o valor pedido pelo cliente, não o resolved_value da fatura.
contestar_cobranca	Workflow/ações de contestação e Conta Certa	OK + hardening	Workflow preservado e CVAL fail-closed. Adicionado edge de segurança para não continuar com SMS/contrato/SR após falha financeira.
finalizar_atendimento	Tool ativa; status obrigatório e regras estritas de finalização	Corrigida	status voltou a ser requisito explícito e é extraído genericamente pelo framework com enum semântico; erro_falha_sistema continua reservado ao sistema.
consultar_status_solicitacao	Integração de status SR usada internamente	Corrigida	Removido mapeamento incorreto interaction_key -> protocol (interaction_key é identidade da interação/mensagem, não protocolo). Protocolo é extraído da fala ou recuperado de aliases do contexto de workflow.
enviar_sms	Ação de integração usada pelos workflows	OK	Mantida integração TIM; continua sem regra de negócio dentro do framework.
recuperar_fatura_pdf	SecurePDF/invoice recover no original	Corrigida	Agora participa do InvoiceContextService para obter customer_id antes do SecurePDF quando não vier explicitamente.
pro_rata	Workflow v3; regra explícita de exatamente 2 planos e has_plano_controle	Corrigida	O MCP deriva os planos da evidência do Bill PDF/billing analysis, deduplica repetição DANFE/linha e falha fechado se não houver exatamente dois planos. has_plano_controle é determinístico.
termino_desconto	Capability/backend existente; mensagem específica sobre fim de fidelidade	Corrigida	Restaurada a semântica/mensagem original, incluindo plano, final da linha, fim do período promocional e retorno ao preço original.
valor_divergente	Capability/backend existente	Corrigida	Restaurada a semântica original de alteração no valor do plano por linha, em vez de texto genérico sobre billing analysis.
retomar_workflow	Resume era interno ao runtime/executor original	OK arquiteturalmente	Exposto como façade genérica do WorkflowRuntime.aresume; não replica estado conversacional dentro do domínio Contas.

Correções relevantes encontradas

1. Contexto de fatura

O original não obtinha o valor total diretamente de complete_invoices. Ele construía um contexto enriquecido a partir do PDF parseado. A migração já possuía parser e InvoiceContextService, mas faltava publicar integralmente o resumo semântico. Foi restaurada a cadeia:

Complete Invoices -> invoice/customer id -> Bill PDF -> parser -> total_geral -> invoice_amount/invoice_amount_open.

2. invoice_explanation

O YAML migrado preservava o pause, mas a action migrada não retornava await_user_input=True, ao contrário do original. Isso tornava a condição de pause falsa. Também havia sido eliminada a etapa de composição LLM específica. Agora a action retorna o gate de pause e uma diretiva requires_llm_composition, mantendo a LLM no framework, não no domínio.

3. buscar_informacao

A route ainda referenciava buscar_informacao, mas a tool estava enabled: false e nem era exposta pelo MCP. Isso criava uma discrepância entre o contrato original e a configuração migrada. A façade foi restaurada sem reintroduzir RAG customizado no Contas.

4. pro_rata

O schema/descrição original exigia exatamente dois planos. A migração aceitava planos=[] e podia afirmar pró-rata mesmo sem evidência. Agora os planos são derivados da fatura e a operação retorna NOT_APPLICABLE quando a evidência não comprova exatamente dois planos.

5. Pré-validação de contestação

validar_contestacao apenas resolvia o item e retornava eligible=true; a validação CVAL real só acontecia depois, já no workflow transacional. Agora a pré-validação e a execução usam a mesma regra financeira, evitando confirmação para uma operação que será inevitavelmente bloqueada.

6. Status de solicitação

O mapper usava interaction_key como protocol. Isso é semanticamente incorreto: interaction_key identifica a interação do framework. O protocolo agora vem da mensagem ou de campos de protocolo existentes no contexto transacional (protocol_number, protocolo_id, contestacao_protocol, cancelamento_vas_protocol).

Arquivos principais alterados

• contas_mcp/servers/contas_mcp_server/main.py
• app/domain/contas/service.py
• app/domain/contas/workflow_actions.py
• app/domain/contas/invoice_context.py (correção anterior da Opção A, mantida)
• config/tools.yaml
• config/mcp_parameter_mapping.yaml
• workflows/contestacao_tool.v2.yaml (hardening já presente)
• tests/migration/test_requested_tools_parity_pente_fino.py
• testes de invoice context previamente adicionados/mantidos

Testes de regressão adicionados

O novo arquivo tests/migration/test_requested_tools_parity_pente_fino.py verifica, entre outros pontos:

• exposição e habilitação das 18 tools;
• façade framework-native de RAG;
• consulta determinística de plano;
• propagação de invoice_detail e resumo semântico;
• composição LLM + pause de invoice_explanation;
• regra de exatamente dois planos em pró-rata;
• CVAL na pré-validação e rejeição de valor acima da cobrança;
• semântica de término de desconto e valor divergente;
• contratos diretos de VAS, histórico, status, SMS e PDF;
• ausência do mapeamento incorreto interaction_key -> protocol;
• obrigatoriedade/classificação de status na finalização.

Resultado dos testes

715 passed

A suíte completa disponível no pacote foi executada, não apenas os testes novos.