# 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)