# 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) └── __pycache__/ # Bytecode Python compilado ``` ## 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. ```python 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. Função Utilitária: `create_sources_string()` ```python def create_sources_string(source_urls: Set[str]) -> str: """ Formata fontes de citação para exibição. Args: source_urls: Conjunto de URLs de fontes únicas para formatar. Retorna: str: Lista numerada de fontes para exibição. """ ``` *Nota: Atualmente definida mas não utilizada ativamente no código.* ##### 5. 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 ```json { "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: ``` ### Formato da Resposta ```json { "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: "Desculpe, a busca pode ter demorado mais que o esperado. Por favor tente novamente." | | 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. ## Considerações Conhecidas 1. **Endpoint de API Hardcoded:** A URL do AWS API Gateway está hardcoded no código fonte 2. **Funcionalidades Não Utilizadas:** Dependências `streamlit-authenticator` e `sseclient` são importadas mas não utilizadas 3. **Sem Validação de Entrada:** Perguntas dos usuários e respostas da API não são validadas antes do uso 4. **Persistência Apenas na Sessão:** Conversas não persistem entre sessões