Lucasmacedo/AI-Frente-Corretora-Assistente
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
442acd7d1df862112b93ae1606e002b73b6219ed
AI-Frente-Corretora-Assistente/docs/frontend-app.md

9.2 KiB
Raw 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:

  1. Exibe mensagem do usuário - Mostra a pergunta na interface imediatamente
  2. 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
  3. 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
  4. 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.

Reference in New Issue View Git Blame Copy Permalink