Aferiq em 1 linha.

# 1. instalar
pip install aferiq-eval

# 2. .env (na raiz do projeto) — 1 env var (estilo Sentry):
AFERIQ_DSN=https://rg_pk_live_xxx@seu-deploy.com.br/api/v1/traces
# (gere em /dashboard/api-keys — clique "Baixar .env" pra ter o DSN pronto)

# 3. main.py — UMA linha, qualquer framework:
import openai          # ou anthropic — import ANTES do start() pro auto-patch
import aferiq
aferiq.start()         # lê AFERIQ_DSN, registra handler, auto-patcheia o SDK

# Pronto. A próxima chain.invoke / agent.run / chat.completions.create vira trace.

Depois de rodar seu app, abre /dashboard/traces e o primeiro trace aparece em ~30 segundos. Se não aparecer, vai em Troubleshooting abaixo.

Exemplo: LangChain RAG

import aferiq
aferiq.start()  # lê AFERIQ_DSN + redação PII BR

# Em CADA chain criada (RetrievalQA, ConversationalRetrievalChain, ou LCEL):
chain = RetrievalQA.from_chain_type(
    llm=llm,
    retriever=vectorstore.as_retriever(),
    callbacks=[aferiq.handler()],
)

from aferiq import redact_pii_br

# CPF/CNPJ/RG/CEP/email/telefone BR são redatados via regex.
# Idempotente, retorna a string redacted.
redact_pii_br("João, CPF 123.456.789-09")
# → "João, CPF [CPF]"

# Pra desativar redação (não recomendado em prod):
aferiq.start(redact=False)

Limites conhecidos: regex não cobre PII em prosa (nomes próprios, endereços), número de processo judicial, OAB, dados clínicos não-estruturados. Pra esses casos, redate antes de chamar chain.invoke() ou implemente handler custom — o source é todo público em aferiq-eval no PyPI.

• Coloquei aferiq.start() mas nada aparece em /dashboard/traces

  Verifica nessa ordem: (1) AFERIQ_DSN no .env não tá com placeholder <COLE_AQUI>; (2) python-dotenv carrega o .env (chamou load_dotenv() no entry point?); (3) start() retornou True — rode aferiq.start(verbose=True) e confira o probe (200 OK ou 405); (4) se você usa LangChain, anexou o handler? passou config={"callbacks": [aferiq.handler()]}? Em diagnóstico, faz POST manual: httpx.post(<url>, headers={"Authorization": f"Bearer <api_key>"}, json={"query":"x","context":["y"],"answer":"z"}) e confere o status code.

• AttributeError: module 'aferiq' has no attribute 'start'

  Você tá em uma versão < 0.2.2. aferiq.start() existe a partir de 0.2.2. Atualiza com `pip install --upgrade aferiq-eval` e confere `pip show aferiq-eval` que mostra 0.2.2+ (idealmente 0.2.5+ que tem auto-emit de traces standalone). Pra versões 0.2.0/0.2.1, use o pattern antigo: aferiq.init() + patch_openai() (do submódulo rageval.integrations.openai_patch).

• ImportError: rageval.integrations.langchain requires langchain-core

  Em versões < 0.2.3, `import aferiq` carregava langchain-core de forma eager — quebrava pra quem usava só OpenAI/Anthropic SDK puro. Resolvido em 0.2.3+: o handler do LangChain agora é importado lazy quando você chama aferiq.handler(). `pip install --upgrade aferiq-eval` resolve.

• Conflito de deps: openai==2.24.0 vs langchain-openai 0.2.x

  litellm (dep transitiva da SDK) puxa openai 2.x. Se seu projeto tá em langchain-openai 0.2.x, force openai<2.0 no requirements.txt do seu projeto. Em roadmap pra 0.3.0: split de litellm em extra opcional [eval].

• Estou enviando dados sensíveis e a redação default não cobre tudo

  Os patterns default cobrem CPF/CNPJ/RG/CEP/email/telefone. Pra adicionar (ex: OAB, número de processo, dados clínicos), use redact_pii_br() pra redatar antes do trace OU desative a redação default com aferiq.start(redact=False) e implemente seu próprio handler que faz o redact custom antes do POST.

• Trace aparece com query="" ou context=[]

  Em LCEL com retriever aninhado em RunnableParallel, on_retriever_end nem sempre dispara. Desde 0.1.1 o handler emite mesmo sem context (com lista vazia). Pra OpenAI SDK direto via auto-patch (0.2.5+), context é SEMPRE [] (não há retrieval visível no nível do patch). Se faltar query, é provável que o input do chain não tem chave "query"/"question"/"input". Verifica com handler.last_trace.

Não achou seu caso? hi@aferiq.com.br — resposta em horas, não dias.