Bem-vindo ao Catálogo Inteligente de Tintas Suvinil, uma API REST capaz de:
- Interpretar a intenção do usuário e acionar somente os agentes relevantes via um orquestrador inteligente com LangChain
- Buscar informações contextuais com RAG (Retrieval-Augmented Generation), utilizando embeddings armazenados no banco com suporte a vetores via pgvector
- Orquestrar múltiplos agentes especializados, incluindo:
- Agente de Intenção
- Agente de Ambientes (interno/externo)
- Agente de Resistência
- Agente de Uso (escolha ideal com base vetorial)
- Agente de Visualização (geração de imagem com DALL·E)
- Gerar simulações visuais realistas da aplicação da tinta com a OpenAI Image API (DALL·E), com prompts otimizados via técnicas de engenharia de prompt
- Manter o contexto da conversa através de sessões contínuas, permitindo múltiplas mensagens com consistência
- Testar e documentar toda a API via Swagger
- Interface visual completa integrada ao backend com React, seguindo a identidade da Suvinil
- Tecnologias
- Arquitetura
- Módulos Principais
- Pré-requisitos
- Configuração do Projeto
- Variáveis de Ambiente
- Orquestração com Docker Compose
- Executando a Aplicação
- Documentação Swagger / OpenAPI
- Endpoints de Demonstração
- Testagem
- Dicas de Uso
- Estrutura de Pastas
- Organização do Projeto
- Próximos Passos
- Autor
- Backend: NestJS (modular, DI, Clean Architecture)
- Linguagem: TypeScript
- Banco de Dados: PostgreSQL + pgvector
- ORM: Prisma (com extensão postgresqlExtensions)
- Infraestrutura: Docker Compose
- IA / LLM: OpenAI GPT-4 Turbo & GPT-3.5-Turbo
- Embeddings: text-embedding-3-small (1536 dims)
- Vector Search: SQL RAW com <-> e índice ivfflat
- LangChain: orchestration de prompts via LCEL
- TintasModule – CRUD de tintas com atributos (nome, cor, acabamento, features, linha…)
- EmbeddingModule – Geração e busca de embeddings (UsageAgent usa SQL RAW)
- AgentsModule – Agentes especializados:
- IntentAgent: classifica intenção (environment, resistance, visualization)
- EnvironmentAgent: sugere propriedades por ambiente
- ResistanceAgent: detalha requisitos técnicos (UV, anti-mofo…)
- UsageAgent: busca vetorial e sumarização
- VisualizationAgent: gera prompt + imagens via DALL·E
- OrchestratorModule – Orquestra agentes e compõe contexto
- ChatModule – Endpoint /chat com histórico e sessionId
- OpenaiModule – Acesso genérico à API OpenAI
Fluxo de /chat:
- Cliente envia { question, sessionId? }
- IntentAgent decide agentes
- Orchestrator chama Usage + Environment/Resistance
- VisualizationAgent gera imagem se solicitado
- ChatService retorna { reply, sessionId, imageUrls? }
- /tintas
- POST /tintas – Cria nova tinta
- GET /tintas – Lista tintas
- GET /tintas/:id – Detalha tinta
- PATCH /tintas/:id – Atualiza tinta
- DELETE /tintas/:id – Remove tinta
- /embeddings
- POST /embeddings/generate-all
- POST /embeddings/:id
- GET /embeddings/search?q=texto&k=5
- /chat
- POST /chat – Chat interativo com IA
- /openai
- POST /openai – Endpoint genérico OpenAI
- Node.js ≥ 16
- Docker & Docker Compose
- Git
- Clone o repositório:
git clone https://github.com/ArthurLuis/SuvinilBot.git
cd SuvinilBot
- Instale as dependências:
npm install
Crie um arquivo .env na raiz com:
DATABASE_URL=postgresql://USER:PASSWORD@localhost:5432/dbname
OPENAI_API_KEY=sk-YOUR_KEY
ENVIADO POR EMAIL
- Acesse a pasta backend:
cd backend
- Suba o banco com suporte a pgvector via Docker:
docker-compose up --build
💡 O banco vai rodar na porta 5432 com o nome tintas. A imagem já vem com o pgvector habilitado.
Se precisar popular o banco com os dados iniciais e gerar os embeddings:
- Rode o seed manualmente (popula as tintas):
docker exec suvinil_api npm run seed
- Gere os embeddings das tintas:
- Via terminal:
curl -X POST http://localhost:3001/embedding/generate-all
- Ou via botão no frontend (tem um botão que faz isso por você 👌)
- É possivel também usar o Swagger em http://localhost:3001/api
Dentro da pasta backend, inicie a API em modo dev:
npm install npm run start:dev
A API vai rodar em http://localhost:3001
- Acesse a pasta frontend:
cd ../frontend
- Instale as dependências e rode:
npm install npm run dev
O frontend estará disponível em http://localhost:3000
- Acesse http://localhost:3000 para ver a interface do chatbot.
- Faça uma pergunta como: “Quero pintar minha sala com uma cor aconchegante”.
- Se aparecer uma sugestão de tinta (ou até uma imagem gerada com a cor), tá rodando!
- Acesse: http://localhost:3001/api
- Explore todos os endpoints, modelos de request/response e exemplos interativos.
- Teste Chat
Envie { "question": "Qual tinta para área externa?" } em POST /chat. - Geração de Embeddings
- POST /embeddings/generate-all
- POST /embeddings/1
- Busca Vetorial
- GET /embeddings/search?q=externo&k=3
- CRUD de Tintas
- POST /tintas com JSON de CreateTintaDto
- GET /tintas
- ...
- Quarto fácil de limpar e sem cheiro forte
Requisição:
POST /chat
Content-Type: application/json
{
"question": "Quero pintar meu quarto, mas prefiro algo que seja fácil de limpar e sem cheiro forte. Tem alguma sugestão?"
}
- Fachada exposta ao sol e chuva
Requisição:
POST /chat
Content-Type: application/json
{
"question": "Preciso pintar a fachada da minha casa. Bate muito sol e chove bastante por aqui. Qual tinta você recomenda?"
}
- Tinta para madeira resistente ao calor
Requisição:
POST /chat
Content-Type: application/json
{
"question": "Você tem alguma tinta para madeira que seja resistente ao calor?"
}
- Simulação de cinza moderno no escritório
Requisição:
POST /chat
Content-Type: application/json
{
"question": "Quero pintar meu escritório com um tom de cinza moderno. Mostra como ficaria?"
}
-
Gere os embeddings antes de testar
Use o botão flutuante no canto inferior direito do frontend para rodar POST /embeddings/generate-all. -
Fluxo de orquestração
Quanto mais agentes forem acionados, maior o tempo de resposta. Comece com perguntas mais diretas e depois aumente a complexidade. -
Sessão e contexto
O frontend mantém o mesmo sessionId. Para reiniciar o chat sem contexto antigo, recarregue a página ou clique no ícone da Suvinil. -
Consistência do DALL·E
Os resultados podem variar conforme o tipo de tinta. Se a imagem sair estranha, tente reformular o prompt ou reenviar a requisição. -
Swagger para testes diretos
Você também pode testar todos os endpoints em http://localhost:3001/api sem precisar do frontend. -
Monitore os logs do backend
Observe os logs para ver como a orquestração dos agentes acontece em tempo real. Exemplo:
[Nest] 22212 - DEBUG [IntentService] Classificando intenção: "[…]"
[Nest] 22212 - LOG [IntentService] Agentes selecionados: environment, resistance
[Nest] 22212 - DEBUG [OrchestratorService] Buscando tintas similares…]
src/
├─ app.module.ts
├─ main.ts
├─ agents/
├─ embedding/
├─ prompts/
├─ tintas/
├─ chat/
├─ openai/
├─ orchestrator/
└─ prisma/
└─ schema.prisma
Para manter uma organização clara e facilitar o acompanhamento do desenvolvimento, utilizei o Notion como ferramenta de planejamento e documentação do projeto. Nele, você encontrará:
- Estrutura do projeto
- Planejamento de funcionalidades
- Relatorios diarios com daily escrita, decisões tecnicas, prints e dificuldades para cada dia de projeto
- Lista de tarefas divididas por dia
Acesse a página do projeto no Notion pelo link abaixo:
🔗 Loomi — Desafio Técnico SuvinilBot no Notion
- Adicionar mais agentes
- Testes unitarios
- Cadastro de usuario e gestão de conversas
Codado com ❤️ por Arthur Luis
Desenvolvedor de software | entusiasta de IA e arquitetura limpa