Copiloto do Parceiro 🛍️🤖

Um lojista de marketplace recebe centenas de avaliações por mês. Ele não tem tempo de ler todas — mas cada uma diz exatamente o que está fazendo ele perder venda.

O Copiloto do Parceiro lê as avaliações reais de clientes (37 mil, em português, do marketplace Olist), classifica sentimento e risco de atraso com modelos treinados e avaliados com rigor, descobre por que os clientes reclamam e entrega ao parceiro um plano de ação — com cada número e cada citação verificados automaticamente contra os dados.

Feito para o problema que todo marketplace (de produtos ou de comida) tem do lado do parceiro: transformar feedback bruto em ação, sem que a IA invente nada.

Exemplo de saída

# Copiloto do Parceiro · `4a3ca931`
Categoria: cama_mesa_banho · Período: 2017-01-08 a 2018-08-21 · Avaliações com texto: 820

## Como você está
- Nota média 3,56; 26,8% das avaliações são negativas (mediana da categoria: 23,1%).
- 14,4% dos pedidos chegaram depois do prazo prometido (mediana da categoria: 8,6%).
- Nos últimos 3 meses a taxa de negativas melhorou: 18,2% (antes: 27,9%).
- O modelo achou 15 avaliações com nota alta mas texto negativo: reclamações que a nota esconde.

## O que mais gera reclamação (nota até 3)
1. Pedido não recebido: 24,5% das reclamações (81 ocorrências).
   > “Foi cobrado frete e a mercadoria não chegou até minha casa. Tive que retirar nos correios.”
   - Ação: Acompanhar rastreio dos pedidos em aberto e acionar a transportadora antes do cliente reclamar.
...
modo: deterministico · fidelidade: OK (27 números, 3 citações verificados)

Related MCP server: Zomato MCP Server

Arquitetura

flowchart LR
    D[(37 mil avaliações reais<br/>Olist, PT-BR)] --> M[Classificadores<br/>sentimento + risco de atraso<br/>TF-IDF baseline · BERTimbau]
    D --> R[Motivos<br/>regras auditáveis]
    M --> T[Ferramentas analíticas<br/>perfil · motivos · exemplos<br/>comparação com a categoria]
    R --> T
    T --> A{Copiloto}
    A -->|offline| DT[Template determinístico]
    A -->|tool calling| L[LLM compatível com OpenAI<br/>Groq, Gemini, OpenRouter, Ollama]
    DT --> F[Verificador de fidelidade<br/>números e citações]
    L --> F
    F -->|ok| OUT[Plano de ação]
    F -->|alucinou| DT
    T -. exposto como .-> MCP[[Servidor MCP]]

Princípio: a IA interpreta, o código calcula. Todas as métricas saem de funções testadas (analytics.py). O LLM só escolhe ferramentas e redige. Antes de entregar, o faithfulness.py confere cada número e cada trecho citado contra as saídas das ferramentas; se o LLM inventar algo, o copiloto devolve o relatório determinístico.

Avaliação

python evals/run_evals.py --markdown (roda no CI a cada push):

O que esses números contam:

• Divisão temporal, não aleatória. O modelo é treinado no passado e testado no futuro, como em produção.

• Drift real. A taxa de atraso foi de 27,8% em mar/2018 (validação) para 6,2% no teste. O PR-AUC cai de 0,83 para 0,49 por isso — o ROC-AUC, que não depende da taxa base, fica estável. Em produção isso pede recalibrar o limiar.

• "Neutro" é a classe difícil (nota 3 = avaliações mistas), por isso o macro-F1 fica abaixo da acurácia.

• A regra de atraso discorda do dado em parte por um motivo real: muitos clientes avaliam antes de receber ("ainda não chegou") mesmo quando a entrega acaba saindo no prazo.

• Detecção de 98%: em 1 de 50 casos o número inventado coincidiu com um número verdadeiro do relatório.

Fine-tuning (BERTimbau → Hugging Face)

O baseline TF-IDF roda em segundos e serve de piso. O notebooks/finetune_colab.ipynb ajusta o BERTimbau com a mesma divisão temporal (GPU T4 gratuita, ~15 min) e publica o modelo com model card e métricas no Hugging Face Hub.

Como usar

git clone https://github.com/anapbatista/copiloto-parceiro && cd copiloto-parceiro
pip install -e ".[dev,mcp]"
python -m copiloto.data            # baixa ~50 MB de dados públicos e cria os rótulos
python -m copiloto.model           # treina o baseline (~15 s) e imprime as métricas
python -m copiloto parceiros       # lista parceiros
python -m copiloto relatorio 4a3ca9315b744ce9f8e9374361493884
pytest                             # 19 testes (usam uma amostra, sem rede)

# Com LLM (qualquer endpoint compatível com a API da OpenAI):
pip install -e ".[llm]"
export COPILOTO_LLM_MODEL=llama-3.3-70b-versatile COPILOTO_LLM_BASE_URL=https://api.groq.com/openai/v1 OPENAI_API_KEY=...
python -m copiloto relatorio <seller_id>

# Como servidor MCP (stdio):
python -m copiloto.mcp_server

Limitações e próximos passos

• Dados de e-commerce de 2016–2018; o mesmo pipeline vale para avaliações de restaurantes quando houver dados rotulados.

• Motivos por regras são auditáveis, mas têm cobertura limitada (64% das avaliações negativas recebem ao menos um motivo). Próximo passo: anotar uma amostra e treinar um classificador multirrótulo de motivos.

• Publicar o BERTimbau ajustado no Hugging Face e comparar com o baseline nesta tabela.

• Avaliar o modo LLM em escala (taxa de fallback por modelo e custo por relatório).

Dados e licença

Código sob MIT. Dados: Brazilian E-Commerce Public Dataset by Olist (CC BY-NC-SA 4.0, uso não comercial); a amostra em tests/fixtures/ é derivada desse dataset. Autoria: Ana Paula de Abreu Batista.