# Assistente Projeto Produto - Documentacao

Esta documentacao cobre o sistema de assistente de IA construido com LangChain/LangGraph para suporte ao Comm.Pix.

## Indice

- [Visao Geral](#visao-geral)
- [Arquitetura](#arquitetura)
- [Componentes](#componentes)
- [Configuracao](#configuracaAh esqueci disso perdão usahushuao)
- [Uso](#uso)
- [Documentacao Adicional](#documentacao-adicional)

## Visao Geral

O Assistente e um agente RAG (Retrieval-Augmented Generation) que fornece suporte tecnico para usuarios da plataforma Comm.Pix. Ele utiliza:

- **Claude Sonnet 4** via Amazon Bedrock para capacidades de LLM
- **Amazon Knowledge Bases** para recuperacao de documentos
- **DynamoDB** para persistencia de memoria de conversas
- **Langfuse** para observabilidade e scoring
- **LangGraph** para orquestracao do agente

## Arquitetura

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Entrada User   │────▶│   agent_call()   │────▶│  Claude Sonnet  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │                         │
                               │                         ▼
                        ┌──────┴──────┐          ┌─────────────────┐
                        │             │          │ Knowledge Base  │
                        ▼             ▼          │   Retriever     │
                 ┌──────────┐  ┌──────────┐      └─────────────────┘
                 │ DynamoDB │  │ Langfuse │
                 │  Memoria │  │ Tracking │
                 └──────────┘  └──────────┘
```

## Componentes

### agent.py

Modulo principal de orquestracao do agente contendo:

- `agent_call(event, context)` - Ponto de entrada principal para a funcao Lambda
- `out_of_scope_and_dont_know_answer()` - Ferramenta para lidar com perguntas desconhecidas

**Estrutura do Evento de Entrada:**
```json
{
  "username": "usuario123",
  "email": "usuario@exemplo.com",
  "language": "Portuguese",
  "message": [{"role": "user", "content": "Pergunta aqui"}],
  "chat_history": [],
  "origem": "web"
}
```

**Estrutura da Resposta:**
```json
{
  "json": "Texto da resposta do assistente",
  "dynamo_response": {...},
  "chat_history": [...]
}
```

### tools/dynamo.py

Operacoes DynamoDB para memoria de conversas:

- `write_memory(user, timestamp, role, content)` - Armazena mensagens da conversa
- `read_memory(userid)` - Recupera as ultimas 30 mensagens de um usuario

### tools/secrets.py

Integracao com AWS Secrets Manager:

- `get_secret()` - Recupera chaves de API do Langfuse do AWS Secrets Manager

## Configuracao

### Recursos AWS Necessarios

1. **Tabela DynamoDB**: `assistente-produtos-servicos-memoria`
   - Partition Key: `UserId` (String)
   - Sort Key: `Timestamp` (Number)

2. **Secret no AWS Secrets Manager**: `assistente-produtos-servicos`
   - Chaves: `api-langfuse-public`, `api-langfuse-secret`

3. **Amazon Knowledge Base**: ID `PETAZDUOFZ`

### Requisitos de Ambiente

- Credenciais AWS configuradas (via IAM role ou variaveis de ambiente)
- Python 3.9+
- Pacotes necessarios no `requirements.txt`

## Uso

### Uso Basico

```python
from agent import agent_call

event = {
    "username": "usuario123",
    "email": "usuario@exemplo.com",
    "language": "Portuguese",
    "message": [{"role": "user", "content": "Como funciona o Pix?"}],
    "chat_history": [],
    "origem": "web"
}

response = agent_call(event, None)
print(response["json"])
```

### Como AWS Lambda

A funcao `agent_call` foi projetada para ser usada como handler de AWS Lambda.

## Documentacao Adicional

- [Guia de Integracao Langfuse](./langfuse-guide.md) - Como usar Langfuse para scoring e observabilidade
- [Guia do Bedrock Knowledge Base](./bedrock-knowledge-base-guide.md) - Como adicionar documentos a Knowledge Base
- [Referencia da API](./api-reference.md) - Documentacao detalhada da API