Lucasmacedo/AI-Frente-Corretora-Assistente

Files

DNXBrasil 442acd7d1d Adds final version of documentation

2026-01-28 14:09:59 -03:00

9.2 KiB

Raw Permalink Blame History

Documentação da Aplicação Frontend

Este documento descreve a aplicação web Streamlit localizada na pasta front/app, que fornece uma interface de chat conversacional para o assistente de produtos e serviços baseado em IA.

Estrutura de Diretórios

front/app/
├── front.py       # Aplicação principal Streamlit (74 linhas)
└──  st_auth.py     # Módulo de autenticação AWS Secrets Manager (28 linhas)

Visão Geral da Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                    Interface Web Streamlit                  │
│              (Executa na porta 8501 via Docker)             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  [Autenticação de Usuário via AWS Cognito OIDC]             │
│           (Token JWT no header x-amzn-oidc-data)            │
│                          ↓                                   │
│  [Seletor de Idioma] [Campo de Entrada do Chat]             │
│                          ↓                                   │
│  ┌──────────────────────────────────────────┐               │
│  │   Gerenciamento de Estado da Sessão      │               │
│  │  - user_prompt_history                   │               │
│  │  - chat_answer_history                   │               │
│  │  - chat_history (conversa completa)      │               │
│  └──────────────────────────────────────────┘               │
│                          ↓                                   │
│  ┌──────────────────────────────────────────┐               │
│  │    Manipulador de Requisições API        │               │
│  │  - Busca chave API do AWS Secrets Mgr    │               │
│  │  - POST para AWS API Gateway             │               │
│  │  - Inclui contexto do usuário e histórico│               │
│  └──────────────────────────────────────────┘               │
│                          ↓                                   │
├─────────────────────────────────────────────────────────────┤
│           Backend AWS (Serviço Externo)                     │
│  API Gateway → Lambda → Assistente IA                       │
│  (Retorna JSON com chat_history e mensagem)                 │
└─────────────────────────────────────────────────────────────┘

Descrição dos Arquivos

st_auth.py - Integração com AWS Secrets Manager

Propósito: Recupera chaves de API e segredos sensíveis do AWS Secrets Manager.

Função: `get_secret()`

Conecta ao AWS Secrets Manager e recupera os segredos da aplicação.

def get_secret() -> str:
    """
    Recupera o segredo 'assistente-produtos-servicos' do AWS Secrets Manager.

    Retorna:
        str: A string do segredo (formato JSON) contendo chaves de API e credenciais.

    Exceções:
        ClientError: Se o segredo não puder ser recuperado da AWS.
    """

Detalhes Importantes:

Conecta ao AWS Secrets Manager na região us-east-1
Recupera o segredo chamado "assistente-produtos-servicos"
Retorna o segredo como string (formato JSON esperado)
Usa sessão boto3 para operações do SDK AWS
Inclui tratamento de erros para exceções ClientError

Dependências:

boto3 - SDK AWS para Python
botocore.exceptions - Tratamento de erros para operações AWS

front.py - Aplicação Principal Streamlit

Propósito: Interface de chatbot interativa para assistência de produtos/serviços com autenticação AWS Cognito e respostas baseadas em IA.

Componentes

1. Autenticação e Contexto do Usuário (Linhas 1-27)

Extrai informações do usuário da autenticação AWS ALB OIDC:

Extrai token JWT do header x-amzn-oidc-data
Decodifica token JWT sem verificação de assinatura
Extrai identificação do usuário de múltiplos campos JWT:
- sub (Subject - campo JWT padrão)
- cognito:username (nome de usuário Cognito)
- username (campo alternativo de nome de usuário)
- user_id (campo customizado)
Recupera email do usuário do token decodificado

2. Elementos da Interface

Elemento	Descrição
Seletor de Idioma	Dropdown com opções English, Portuguese, Spanish
Cabeçalho Principal	"Assistente Produtos Servicos"
Entrada do Chat	Campo de texto com placeholder em português

3. Gerenciamento de Estado da Sessão

A aplicação mantém três variáveis de estado de sessão:

Variável	Tipo	Descrição
`user_prompt_history`	`List[str]`	Lista de perguntas do usuário
`chat_answer_history`	`List[str]`	Lista de respostas da IA
`chat_history`	`List[dict]`	Histórico completo da conversa com papéis

4. Fluxo Principal do Chat

Quando um usuário envia uma mensagem, a seguinte sequência ocorre:

Exibe mensagem do usuário - Mostra a pergunta na interface imediatamente
Faz requisição à API:
- Constrói payload com mensagem, histórico do chat, nome de usuário, email, origem, idioma
- Envia requisição POST para endpoint AWS API Gateway
- Inclui chave API nos headers obtida do AWS Secrets Manager
Processa resposta:
- Analisa resposta JSON
- Atualiza histórico do chat da resposta se fornecido
- Extrai conteúdo da mensagem da estrutura de resposta
- Trata erros de timeout com mensagem amigável ao usuário
Atualiza estado:
- Adiciona pergunta do usuário ao histórico
- Adiciona resposta da IA ao histórico
- Atualiza histórico do chat com registros de conversa baseados em papéis

Fluxo de Dados

1. Acesso do Usuário → AWS ALB injeta token JWT nos headers
         ↓
2. Autenticação → Extrai user_id e email do JWT
         ↓
3. Entrada do Usuário → Mensagem de chat com preferência de idioma
         ↓
4. Chamada API → POST para AWS Lambda via API Gateway com:
   - Conteúdo da mensagem
   - Histórico do chat
   - Metadados do usuário (username, email, origin, language)
         ↓
5. Processamento Backend → Assistente IA gera resposta
         ↓
6. Resposta → JSON com chat_history e conteúdo da mensagem
         ↓
7. Exibição → Atualiza interface e mantém estado da sessão

Comunicação com API

Endpoint

POST https://xexm2wsz07-vpce-05915540d0592b921.execute-api.us-east-1.amazonaws.com/dev

Payload da Requisição

{
  "message": "Pergunta ou mensagem do usuário",
  "chat_history": [
    {"role": "user", "content": "Mensagem anterior do usuário"},
    {"role": "assistant", "content": "Resposta anterior do assistente"}
  ],
  "username": "user_id_do_jwt",
  "email": "usuario@exemplo.com",
  "origin": "streamlit",
  "language": "Portuguese"
}

Headers da Requisição

x-api-key: <Chave API do AWS Secrets Manager>

Formato da Resposta

{
  "chat_history": [...],
  "message": {
    "content": "Texto de resposta do assistente"
  }
}

Dependências

Pacote	Versão	Propósito
`streamlit`	^1.49.1	Framework de interface web
`boto3`	^1.40.37	SDK AWS
`requests`	-	Cliente HTTP para chamadas API
`PyJWT`	-	Decodificação de tokens JWT
`pyyaml`	-	Parsing de YAML

Configuração

Ambiente

Porta: 8501 (porta padrão do Streamlit)
Região AWS: us-east-1
Nome do Segredo: assistente-produtos-servicos

Idiomas Suportados

English (Inglês)
Portuguese (Português)
Spanish (Espanhol)

Tratamento de Erros

Cenário	Comportamento
Timeout da API	Exibe: Mensagem padrão definada anteriormente para enviar a equipe
Erros gerais da API	Resposta pode não ser exibida corretamente

Comportamento da Sessão

Histórico do chat persiste dentro de uma única sessão do navegador
Histórico é limpo ao atualizar a página ou fechar a aba
Não há armazenamento persistente de conversas

Notas de Implantação

A aplicação foi projetada para executar atrás de um AWS Application Load Balancer (ALB) com autenticação Cognito configurada. O ALB injeta o header x-amzn-oidc-data contendo o token JWT para usuários autenticados.

Docker

A aplicação executa em um container Docker (veja front/Dockerfile) e expõe a porta 8501.

9.2 KiB Raw Permalink Blame History