Initial commit

docs/langfuse-guide.md

@@ -0,0 +1,162 @@
+# Guia de Integração Langfuse
+
+Este guia descreve como o Langfuse está integrado ao assistente e como utilizar suas funcionalidades de observabilidade e rastreamento.
+
+## Índice
+
+- [O que é Langfuse](#o-que-e-langfuse)
+- [Como está integrado](#como-esta-integrado)
+- [Credenciais](#credenciais)
+- [Rastreamento automático via LangChain](#rastreamento-automatico-via-langchain)
+- [Tags por dashboard](#tags-por-dashboard)
+- [Adicionando scores customizados](#adicionando-scores-customizados)
+- [Visualizando traces](#visualizando-traces)
+
+---
+
+## O que é Langfuse
+
+Langfuse é uma plataforma de observabilidade para aplicações LLM que permite:
+
+- Rastrear automaticamente todas as chamadas ao modelo (tokens, latência, erros)
+- Inspecionar o histórico de mensagens e chamadas de tools
+- Adicionar scores e métricas customizadas por trace
+- Analisar performance e uso ao longo do tempo
+
+---
+
+## Como está integrado
+
+A integração é feita em dois módulos:
+
+### `dynamo.py` — inicialização do cliente
+
+O cliente `Langfuse` é instanciado na carga do módulo, usando credenciais obtidas do AWS Secrets Manager:
+
+```python
+from langfuse import Langfuse
+
+secrets = json.loads(get_secret())
+langfuse = Langfuse(
+    public_key=secrets["LANGFUSE-PUBLIC-KEY"],
+    secret_key=secrets["LANGFUSE-SECRET-KEY"],
+    host=os.environ["LANGFUSE_HOST"],
+)
+```
+
+O objeto `langfuse` é exportado e reutilizado pelo `orquestrador.py`.
+
+### `orquestrador.py` — rastreamento por execução
+
+A cada chamada ao agente, um `CallbackHandler` do LangChain é criado e passado na configuração do grafo LangGraph. Isso registra automaticamente no Langfuse todas as etapas da execução — chamadas ao modelo, chamadas de tools e mensagens trocadas.
+
+Ao final da execução, `langfuse.flush()` garante o envio dos dados pendentes.
+
+```python
+from langfuse.langchain import CallbackHandler
+from .dynamo import langfuse
+
+langfuse_handler = CallbackHandler()
+config = {"callbacks": [langfuse_handler], "tags": [base]}
+final_state = agent.invoke(initial_state, config=config)
+
+langfuse.flush()
+```
+
+---
+
+## Credenciais
+
+As chaves do Langfuse são armazenadas no AWS Secrets Manager, no secret definido pela variável de ambiente `SECRET_NAME`. O secret deve conter as seguintes chaves:
+
+| Chave no secret | Descrição |
+|-----------------|-----------|
+| `LANGFUSE-PUBLIC-KEY` | Chave pública do projeto Langfuse |
+| `LANGFUSE-SECRET-KEY` | Chave secreta do projeto Langfuse |
+
+O endpoint do servidor é configurado pela variável de ambiente `LANGFUSE_HOST`.
+
+---
+
+## Rastreamento automático via LangChain
+
+O `CallbackHandler` captura automaticamente, sem código adicional:
+
+- Cada chamada ao modelo Bedrock (input, output, tokens)
+- Chamadas às tools `get_monthly_report` e `get_consolidated_keys`
+- Sequência de passos do grafo LangGraph
+- Erros e exceções durante a execução
+
+Cada invocação de `orquestrador.main()` gera um trace independente no Langfuse.
+
+---
+
+## Tags por dashboard
+
+A tag `base` (nome do dashboard, ex: `bacio_transacional_loja_app`) é passada em cada execução:
+
+```python
+config = {"callbacks": [langfuse_handler], "tags": [base]}
+```
+
+Isso permite filtrar traces no Langfuse por cliente/dashboard.
+
+---
+
+## Adicionando scores customizados
+
+Para registrar métricas adicionais em um trace, use a API do cliente `langfuse` após a execução do agente. O trace ID pode ser obtido via `langfuse_handler.get_trace_id()`.
+
+### Tipos de score
+
+| Tipo | Uso |
+|------|-----|
+| `NUMERIC` | Valores numéricos (ex: satisfação 1–5, tempo de resposta) |
+| `CATEGORICAL` | Valores de categoria (ex: canal de origem, qualidade) |
+| `BOOLEAN` | Verdadeiro/falso |
+
+### Exemplo: score após execução
+
+```python
+from langfuse.langchain import CallbackHandler
+from .dynamo import langfuse
+
+langfuse_handler = CallbackHandler()
+config = {"callbacks": [langfuse_handler], "tags": [base]}
+final_state = agent.invoke(initial_state, config=config)
+
+trace_id = langfuse_handler.get_trace_id()
+if trace_id:
+    langfuse.score(
+        trace_id=trace_id,
+        name="canal_origem",
+        value="api",
+        data_type="CATEGORICAL",
+    )
+
+langfuse.flush()
+```
+
+> Sempre chame `langfuse.flush()` depois de registrar scores para garantir o envio.
+
+---
+
+## Visualizando traces
+
+Acesse a interface web do Langfuse no endereço configurado em `LANGFUSE_HOST`.
+
+### Navegação útil
+
+| O que ver | Onde ir |
+|-----------|---------|
+| Todas as execuções | Traces |
+| Execuções por dashboard | Traces → filtrar por tag |
+| Tokens por modelo | Dashboard → Usage |
+| Erros e falhas | Traces → filtrar por status `ERROR` |
+| Scores registrados | Trace individual → aba Scores |
+
+### Referências
+
+- [Documentação Oficial Langfuse](https://langfuse.com/docs)
+- [Integração LangChain/LangGraph](https://langfuse.com/docs/integrations/langchain)
+- [API de Scores](https://langfuse.com/docs/scores/custom)