E-Commerce Assistant - RAG (Retrieval-Augmented Generation)

Este projeto é uma aplicação de assistente de compras inteligente para e-commerce, estruturado em FastAPI (Backend) e Vue.js + Vite (Frontend), integrado a um banco PostgreSQL (pgvector) para buscas semânticas, Redis para cache temporário do histórico de conversas e a API do Google Gemini (LLM e Embeddings).

Ele utiliza técnicas avançadas de RAG (Retrieval-Augmented Generation) para responder a perguntas de clientes, recomendando produtos reais da base com fotos, fretes e links de compra.

---

🧠 Conceitos de RAG & Arquitetura de Memória

1. Extração Paramétrica (NLU)

• O que é: O processo de analisar a mensagem natural do usuário para identificar intenções e extrair parâmetros estruturados (filtros).
• No projeto: O assistente recebe a mensagem do usuário (ex: "quero sabonetes até R$ 50") e, usando a API do Gemini com esquemas Pydantic (SearchFilters), extrai filtros limpos como category_name: "health_beauty" e max_price: 50.0. Ele também mapeia termos em português para as categorias em inglês do banco (ex: "perfume" $\rightarrow$ perfumery).

2. Embeddings Semânticos & pgvector

• O que é: Embeddings são representações vetoriais (listas de 768 decimais) que capturam o significado semântico do texto. Frases semanticamente equivalentes ficam próximas no espaço multidimensional.
• No projeto:
  • Usamos o modelo models/gemini-embedding-001 da Google.
  • Matryoshka Representation Learning (MRL): O modelo original gera vetores de 3072 dimensões. Para otimização de espaço e performance no banco, truncamos os vetores para 768 dimensões com mínima perda de qualidade.
  • pgvector: Extensão do PostgreSQL que armazena os vetores nativamente (vector(768)) e realiza busca por similaridade de cosseno usando o operador <=> direto nas queries SQL.

3. Busca Híbrida (Hybrid Search)

• Busca Vetorial (Semântica): Calcula a proximidade semântica entre a query do usuário e os produtos (ex: buscar "fragrância" e retornar "perfume").
• Busca Textual (Lexical Fallback): Caso a busca vetorial falhe ou o produto não tenha embedding, o sistema aplica busca via texto tradicional (ILIKE tokenizado com remoção de plurais e stopwords).

4. Histórico de Conversas e Sessão em Cache (Redis + LocalStorage)

• Cache no Redis: Em vez de inchar o banco PostgreSQL com logs de conversas, as mensagens de cada sessão de chat são persistidas de forma ultrarrápida no Redis (REDIS_URL) com expiração automática (TTL de 30 minutos).
• Metadados no LocalStorage: A barra lateral de conversas e os metadados (IDs das sessões, títulos dinâmicos e datas) são mantidos no navegador do usuário (localStorage). Ao trocar de aba no frontend, o Vue.js busca no Redis o histórico daquela sessão específica.
• Resiliência a Falhas: As perguntas do usuário e mensagens de erros (ex: estouro de cota do Gemini) são gravadas centralizadamente no Redis antes do término da requisição para manter o histórico de chat íntegro.

---

📂 Estrutura do Projeto

ecommerce-rag/
├── backend/                # API FastAPI, Banco e Scripts Python
│   ├── app/
│   │   ├── models/         # Modelos ORM do banco de dados (SQLAlchemy)
│   │   ├── repositories/   # Interfaces e consultas SQL/pgvector
│   │   ├── routers/        # Rotas FastAPI (Produtos e endpoints de Chat)
│   │   ├── schemas/        # Schemas Pydantic (Validação e serialização)
│   │   └── services/       # Regras de RAG, conexões Gemini e Redis
│   ├── scripts/
│   │   ├── ingest_data.py  # Ingestão de catálogo no banco e geração de buscas
│   │   └── generate_embeddings.py # Geração em lote de vetores semânticos
│   ├── docker-compose.yml  # PostgreSQL/pgvector e Redis no Docker
│   ├── requirements.txt    # Dependências do Python
│   └── run.py              # Script de inicialização do servidor Uvicorn
│
└── frontend/               # Cliente Vue.js (Vite)
    ├── src/
    │   ├── components/
    │   │   └── Chat.vue    # Componente de Chat (Apple Glass, Sessões, Markdown)
    │   ├── App.vue         # Wrapper da aplicação e animações do espaço (Estrelas/Planetas)
    │   └── style.css       # Design System Global (Variáveis e Resets)
    └── package.json        # Dependências NPM

---

🚀 Como Executar o Projeto

1. Requisitos Prévios

• Python 3.10 ou superior
• Node.js instalado
• Docker instalado e rodando

2. Configurar o Backend e Infraestrutura

Entre no diretório do backend:

cd backend

Crie um arquivo .env na pasta backend/ contendo as variáveis:

# Banco de dados
DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/shopping_assistant

# Chave da API do Gemini (Google AI Studio)
GEMINI_API_KEY=sua_chave_aqui

# Cache do Redis
REDIS_URL=redis://localhost:6379/0

Suba o container do PostgreSQL (pgvector) e Redis:

docker compose up -d

Crie o ambiente virtual Python, ative-o e instale as dependências:

python -m venv .venv
# No Windows:
.\.venv\Scripts\activate
# No Linux/Mac:
source .venv/bin/activate

pip install -r requirements.txt

3. Ingestão de Dados e Geração de Embeddings

Carregue os produtos reais da Amazon Brasil contidos em [sample_amazon_data.json] para o Postgres:

python scripts/ingest_data.py

Gere os embeddings vetoriais de busca para todos os produtos usando o modelo do Gemini:

python scripts/generate_embeddings.py --batch-size 15 --sleep 2.0

4. Rodar o Backend

Inicie o servidor FastAPI na porta 8000:

python run.py

---

5. Executar o Frontend

Abra outro terminal na raiz do projeto, entre no diretório do frontend:

cd frontend

Instale as dependências e inicie o servidor de desenvolvimento:

npm install
npm run dev

Abra a URL exibida no navegador (geralmente http://localhost:5173) e comece a conversar com o Grogu!

---

🧪 Funcionalidades de Destaque no Chat

• Abertura Segura: Todos os links externos e botões abrem em novas guias (target="_blank" rel="noopener noreferrer").
• Design Premium Apple macOS Glass: Efeito translúcido com desfoque de fundo (backdrop-filter) e naves, estrelas e planetas dinâmicos em CSS puro.
• Imagens Autolimitadas: Fotos de produtos exibidas em formato compacto premium (140px) com cantos arredondados e fundo branco.
• Botões de Compra Embutidos: Conversão de links de compra em botões com as cores oficiais e gradiente da Amazon.
• Animação de Mola (Elastic Bounce): Transições suaves nas bolhas de fala ao serem renderizadas ou enviadas.