Helpdesk Com IA Usando RAG E MCP

🤖 Helpdesk AI: RAG & Agentic Workflow

🎯 About the Project

This project implements a Retrieval-Augmented Generation (RAG) architecture focused on solving the hallucination problem in LLMs for corporate use.

The goal is to create a Helpdesk Assistant that consults internal manuals and responds technically and accurately. If the solution is not in the database, the system uses an agent stream to automatically open a ticket in Trello via n8n, ensuring that the user is never without support.

The infrastructure was developed via code (FastAPIto ensure full control over data flow, security and API costs.

💡 What he doesSearch

• Vetorial (pgvector): Perform semantic search in documents, finding the right context rather than just keywords.
• Groundedness filter: Prompt configuration to ensure that AI responds only to what is in official documents.
• Ticket Automation (n8n): If the AI doesn’t know the answer, it fires a webhook into the n8nwhich creates a card in Trello of the support team.
• Chat history: Frontend memory management to keep conversation flowing.

🛠️ Technology Stack

• Backend:

Python + FastAPI + SQLAlchemy

• Database: PostgreSQL with extension 'pgvector'
• Artificial Intelligence: Google Gemini API (Embeddings e LLM)
• Orchestration: n8n e Trello
• APIFrontend: Streamlit

🧠 Technical Choices and Architecture

The system was structured with a focus on performance and safety. Below are the main points:

1. Vector Performance (768 dimensions):\

I configured the output of the embeddings model to __768 Dimensions__ (instead of 3072). This reduces bank memory consumption and speeds up the search for similarity without losing accuracy in the context of helpdesk.

1. Strict Groundedness:

The prompt works in restricted mode. If the information does not exist in the manuals, the model informs the limit of your knowledge and suggests opening the ticket.

1. Automation Triggers:

When the AI does not find the answer, it inserts an invisible tag into the backend. The FastAPI intercepts this tag, clears the text for the user and fires a __Asynchronous Webhook__ para o n8n.

1. DevSecOps Security:

Management of credentials via .env files injected into containers and use of the native n8n vault.

1. Code Organization (Clean Architecture): Use of APIRouter to separate user, document and chat logic into independent modules.

🚀 How to Execute the Project

Prerequisites

• Docker e Docker Compose instalados.
• Google AI Studio API key.

Step by Step

1. Clone the repository:

   git clone https://github.com/adriano-allef/Helpdesk-com-IA-usando-RAG-e-MCP.gitcd Helpdesk-com-IA-usando-RAG-e-MCP

1. Configure the environment variables:

Create a file .env Raiz com:

   GEMINI_API_KEY=sua_chave_aqui
   POSTGRES_USER=admin
   POSTGRES_PASSWORD=senha_segura
   POSTGRES_DB=helpdesk_db

3. Upgrade the infrastructure:

   docker compose up --build -d

4. Inicie o Frontend:

   pip install -r requirements.txt
   streamlit run frontend.py

📡 Endpoints da API

📂 Pasta Structure

app/
├── database/
│   └── database.py      # Conexão e sessão do banco de dados
├── models/
│   └── models.py        # Tabelas SQLAlchemy (ORM)
├── routers/
│   ├── chat.py          # Lógica RAG e Prompts
│   ├── documents.py     # Lógica de Embeddings
│   └── users.py         # Lógica de Usuários
├── schemas/
│   └── schemas.py       # Validação de dados (Pydantic)
├── main.py              # Ponto de entrada da API FastAPI
├── docker-compose.yml   # Orquestração dos contêineres (Docker)
├── Dockerfile           # Imagem do Backend
├── frontend.py          # Interface do usuário com Streamlit
├── requirements.txt     # Dependências do projeto
└── README.md            # Documentação (Você está aqui!)

🔮 Roadmap Completed

• \[x\] Integration with vector bank (pgvector).
• \[x\] Conversational memory on the frontend.
• \[x\] Agentic Workflow: Disparo de Webhooks para n8n.
• \[x\] Trello Integration: Automatic card creation.
• \[x\] Visual Dashboard: Architecture timeline in Streamlit.