# Referencia da API

Documentacao detalhada de todas as funcoes e modulos do assistente.

## Indice

- [agent.py](#agentpy)
- [tools/dynamo.py](#toolsdynamopy)
- [tools/secrets.py](#toolssecretspy)

---

## agent.py

Modulo principal que contem a logica do agente de IA.

### agent_call(event, context)

Funcao principal que processa perguntas do usuario e retorna respostas do assistente.

**Parametros:**

| Parametro | Tipo | Obrigatorio | Descricao |
|-----------|------|-------------|-----------|
| `event` | dict | Sim | Evento contendo dados da requisicao |
| `context` | object | Nao | Contexto do Lambda (pode ser None) |

**Estrutura do `event`:**

```python
{
    "username": str,        # Identificador do usuario
    "email": str,           # Email do usuario
    "language": str,        # Idioma desejado (ex: "Portuguese", "English")
    "message": list,        # Lista de mensagens no formato LangChain
    "chat_history": list,   # Historico de chat ([] para nova conversa)
    "origem": str           # (Opcional) Canal de origem da pergunta
}
```

**Formato das mensagens:**

```python
# Mensagem do usuario
{"role": "user", "content": "Texto da pergunta"}

# Mensagem do assistente
{"role": "assistant", "content": "Texto da resposta"}
```

**Retorno:**

```python
{
    "json": str,              # Resposta do assistente
    "dynamo_response": dict,  # Resposta da operacao DynamoDB
    "chat_history": list      # Historico atualizado
}
```

**Exemplo de Uso:**

```python
from agent import agent_call

# Nova conversa
event = {
    "username": "joao.silva",
    "email": "joao@empresa.com",
    "language": "Portuguese",
    "message": [{"role": "user", "content": "O que e o Comm.Pix?"}],
    "chat_history": [],
    "origem": "web"
}

response = agent_call(event, None)
print(response["json"])  # Resposta do assistente
```

**Codigos de Erro:**

| Erro | Causa | Solucao |
|------|-------|---------|
| KeyError | Campo obrigatorio ausente no event | Verificar estrutura do event |
| BedrockException | Erro na API do Bedrock | Verificar credenciais AWS |
| DynamoDBException | Erro ao acessar DynamoDB | Verificar permissoes IAM |

---

### out_of_scope_and_dont_know_answer()

Tool do LangChain para respostas padrao quando o agente nao encontra a resposta.

**Parametros:** Nenhum

**Retorno:** `str` - Mensagem padrao orientando o usuario a abrir ticket de suporte

**Comportamento:**
- Registra um score "Miss" no Langfuse
- Retorna mensagem com link para portal de suporte

**Quando e Chamada:**
- Perguntas fora do escopo do Comm.Pix
- Perguntas dentro do escopo mas sem resposta nos documentos

---

## tools/dynamo.py

Modulo para operacoes de memoria no DynamoDB.

### write_memory(user, timestamp, role, content)

Armazena uma mensagem da conversa no DynamoDB.

**Parametros:**

| Parametro | Tipo | Obrigatorio | Descricao |
|-----------|------|-------------|-----------|
| `user` | str | Sim | Identificador do usuario (UserId) |
| `timestamp` | int | Sim | Timestamp Unix da mensagem |
| `role` | str | Sim | Papel da mensagem ("user" ou "assistant") |
| `content` | str | Sim | Conteudo da mensagem |

**Retorno:** `None`

**Exemplo:**

```python
from tools import dynamo
import time

dynamo.write_memory(
    user="joao.silva",
    timestamp=int(time.time()),
    role="user",
    content="Como funciona o Finance Batch?"
)
```

**Estrutura no DynamoDB:**

```json
{
    "UserId": "joao.silva",
    "Timestamp": 1704067200,
    "role": "user",
    "content": "Como funciona o Finance Batch?"
}
```

---

### read_memory(userid)

Recupera as ultimas 30 mensagens de um usuario.

**Parametros:**

| Parametro | Tipo | Obrigatorio | Descricao |
|-----------|------|-------------|-----------|
| `userid` | str | Sim | Identificador do usuario |

**Retorno:** `list` - Lista de mensagens ordenadas por timestamp (mais recentes primeiro)

**Exemplo:**

```python
from tools import dynamo

history = dynamo.read_memory("joao.silva")
for msg in history:
    print(f"{msg['role']}: {msg['content']}")
```

**Retorno Exemplo:**

```python
[
    {"UserId": "joao.silva", "Timestamp": 1704067300, "role": "assistant", "content": "..."},
    {"UserId": "joao.silva", "Timestamp": 1704067200, "role": "user", "content": "..."},
    # ... ate 30 mensagens
]
```

---

## tools/secrets.py

Modulo para recuperacao de segredos do AWS Secrets Manager.

### get_secret()

Recupera as credenciais armazenadas no Secrets Manager.

**Parametros:** Nenhum

**Retorno:** `str` - String JSON contendo os segredos

**Exemplo:**

```python
from tools import secrets
import json

secret_string = secrets.get_secret()
secrets_data = json.loads(secret_string)

langfuse_public = secrets_data['api-langfuse-public']
langfuse_secret = secrets_data['api-langfuse-secret']
```

**Estrutura do Segredo:**

```json
{
    "api-langfuse-public": "pk-lf-xxxxxxxx",
    "api-langfuse-secret": "sk-lf-xxxxxxxx"
}
```

**Erros Possiveis:**

| Erro | Causa | Solucao |
|------|-------|---------|
| `ResourceNotFoundException` | Segredo nao encontrado | Verificar nome do segredo |
| `AccessDeniedException` | Sem permissao | Verificar politica IAM |
| `DecryptionFailure` | Erro de descriptografia | Verificar chave KMS |

---

## Fluxo Completo de Execucao

```
1. agent_call() recebe o evento
   │
2. Inicializa Langfuse handler
   │
3. Configura ChatBedrock (Claude Sonnet 4)
   │
4. Configura Knowledge Base Retriever
   │
5. Carrega historico
   │   ├── Se chat_history vazio: dynamo.read_memory('frente')
   │   └── Se nao: usa chat_history do evento
   │
6. Cria agente ReAct com tools:
   │   ├── retriever.as_tool() - Busca documentos
   │   └── out_of_scope_and_dont_know_answer - Resposta padrao
   │
7. Executa agente com streaming
   │   ├── Registra scores no Langfuse (Origem, Email)
   │   └── Processa cada step do agente
   │
8. Salva mensagem no DynamoDB
   │
9. Retorna resposta
```

---

## Variaveis de Configuracao

| Variavel | Local | Valor Padrao | Descricao |
|----------|-------|--------------|-----------|
| `model_id` | agent.py | `us.anthropic.claude-sonnet-4-20250514-v1:0` | Modelo Claude |
| `region_name` | agent.py | `us-east-1` | Regiao AWS |
| `knowledge_base_id` | agent.py | `PETAZDUOFZ` | ID da Knowledge Base |
| `temperature` | agent.py | `0.1` | Temperatura do modelo |
| `max_tokens` | agent.py | `2000` | Maximo de tokens |
| `numberOfResults` | agent.py | `4` | Documentos retornados |
| `table_name` | dynamo.py | `assistente-produtos-servicos-memoria` | Tabela DynamoDB |
| `secret_name` | secrets.py | `assistente-produtos-servicos` | Nome do segredo |