DEV Community: Cleber Lucas

En:Building a RAG Agent for SOPs

Cleber Lucas — Tue, 09 Jun 2026 16:53:55 +0000

How I built a RAG agent to eliminate operational interruptions at work

Open source project using Python, LangChain, ChromaDB, FastAPI and Discord — from a real problem to production deployment.

Every company has a silent cycle that drains time without anyone noticing.

An employee has a question about a procedure. They can't find the answer in the documentation. They interrupt a more experienced colleague. That person stops what they're doing, answers, and goes back to work — focus already broken. Multiply that by 10, 20, 50 times a week.

Watching that pattern is what led me to build POPS AI: a RAG (Retrieval-Augmented Generation) agent capable of answering questions about a company's Standard Operating Procedures, directly through Discord or via a REST API.

The problem that motivated the project

The company had dozens of SOPs documented in PDF format. The problem wasn't a lack of documentation — it was the friction in accessing it. Nobody opens a network folder, hunts for the right file, and reads 15 pages just to answer a quick question.

The question I asked myself was simple: what if the documentation could answer questions on its own?

The architecture in three stages

The system works in three distinct phases, each with a clear responsibility.

1. Extraction

The extrair_texto.py script reads PDFs from the pops_originais/ folder, extracts the full text using PyMuPDF, and saves it as .txt. Page images are also extracted for future use.

import fitz  # PyMuPDF

def extract_text_from_pdf(pdf_path):
    doc = fitz.open(pdf_path)
    full_text = ""
    for page in doc:
        full_text += page.get_text()
    return full_text

Simple, but important: extraction quality determines response quality. Scanned PDFs without OCR are enemy number one here.

2. Embedding generation

With the extracted texts, gerar_embeddings.py splits the content into chunks using LangChain's RecursiveCharacterTextSplitter, generates the vectors, and persists them in ChromaDB.

from langchain.text_splitter import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200
)
chunks = splitter.split_text(text)

The chunk_overlap=200 was a deliberate choice: it ensures context isn't cut off abruptly between chunks, which visibly improved response coherence.

The project supports two embedding models via config.py:

Gemini models/embedding-001 — high quality, requires API key, cost scales with volume
Local SBERT (paraphrase-multilingual-mpnet-base-v2) — runs offline, great for avoiding costs or rate limits

This flexibility was one of the design decisions that added the most value, especially for anyone who wants to experiment with the project at zero cost.

3. Query (RAG)

When a user asks a question, the system:

Converts the question into a vector using the same embedding model
Searches for the most semantically similar chunks in ChromaDB
Builds a prompt with the retrieved excerpts as context
Sends it to Gemini 2.0 Flash to generate the final answer

results = collection.query(
    query_embeddings=[question_embedding],
    n_results=5
)

context = "\n\n".join(results['documents'][0])

prompt = f"""You are an assistant specialized in the company's SOPs.
Use only the information below to answer.

Context:
{context}

Question: {question}
"""

The interfaces: Discord and API

The project exposes the knowledge base in two ways.

Discord bot with slash commands:

/pop <question> — queries the vector database and returns the answer
/addpop <file.txt> — lets admins add new SOPs in real time, without reprocessing the entire base

FastAPI REST API with a POST /ask endpoint, designed for integration with other internal systems:

// Request
{ "question": "How do I configure the scanner on the Samsung printer?" }

// Response
{
  "answer": "To configure the scanner, follow these steps:\n1. Turn on the printer...\n[Source: SOP-ScannerSetup.txt]"
}

The challenge nobody talks about: token costs

Building the RAG was the fun part. The real challenge came after: how do you control costs in production?

A few decisions that made a real difference:

Using SBERT for embeddings instead of the Gemini API brings indexing cost down to zero — the model runs locally. Cost only occurs at response generation, which is where the actual value is.

Limiting n_results=5 in the vector search avoids passing unnecessary context to the model. More context = more tokens = more cost, without necessarily improving the answer.

Gemini 2.0 Flash was chosen intentionally over Pro: for objective questions about procedures, the quality difference is minimal while the cost difference is significant.

Deployment: one container, two processes

One decision that cost me a few hours was running the Discord bot and the FastAPI server in the same Docker container. The solution was Supervisor, which manages both processes in a lightweight, self-recovering way.

# supervisord.conf
[program:api]
command=uvicorn api_bot:app --host 0.0.0.0 --port 8000

[program:discord]
command=python bot_discord.py

autostart=true
autorestart=true

The result is a single, lightweight container that starts both services in parallel and automatically restarts either one if it fails. On an entry-level VPS, this matters a lot.

What I learned that wasn't in the plan

Chunking is an art. Chunk size and overlap affect response quality more than the model itself. I spent more time tuning this than anything else.

Security from day one. The .gitignore had to be configured before the first public commit to ensure no confidential company PDFs ended up in the repository. A mistake here is hard to undo.

The real problem wasn't technical. The most complex part was understanding what kind of questions users would actually ask and how to structure the SOPs so the model could retrieve the right information. Garbage in, garbage out applies twice as hard in RAG.

The project is open source

POPS AI is available on GitHub with a full README, .env.example, configured Docker Compose, and step-by-step setup instructions for both local and container-based deployment.

You can clone it, adapt it to your own knowledge base, and use it with your own documents — whether for SOPs, internal wikis, product manuals, or any PDF-based documentation.

🔗 github.com/obelucca/POPS_AI

Stack

Python 3.10 LangChain ChromaDB FastAPI Discord.py Google Gemini 2.0 Flash SBERT Docker Supervisor PyMuPDF

If you made it this far and are curious about any architectural decision, token cost management in production, or how to adapt this to a different use case — drop a comment. Happy to discuss.

Do PDF ao Discord com RAG: Como construí um agente RAG para eliminar interrupções operacionais na empresa

Cleber Lucas — Tue, 09 Jun 2026 13:51:49 +0000

Como construí um agente RAG para eliminar interrupções operacionais na empresa

Projeto open source com Python, LangChain, ChromaDB, FastAPI e Discord — do problema real ao deploy em produção.

Toda empresa tem aquele ciclo silencioso que drena tempo sem que ninguém perceba.

Um funcionário tem uma dúvida sobre um procedimento. Não encontra a resposta nos documentos. Interrompe alguém mais experiente. Essa pessoa para o que estava fazendo, responde, e volta ao trabalho — já com o raciocínio quebrado. Multiplique isso por 10, 20, 50 vezes por semana.

Foi observando esse padrão que decidi construir o POPS AI: um agente de RAG (Retrieval-Augmented Generation) capaz de responder perguntas sobre os Procedimentos Operacionais Padrão de uma empresa, direto pelo Discord ou via API REST.

O problema que motivou o projeto

A empresa tinha dezenas de POPs documentados em PDF. O problema não era a falta de documentação — era o atrito para acessá-la. Ninguém abre uma pasta de rede, procura o arquivo certo e lê 15 páginas para responder uma dúvida pontual.

A pergunta que me fiz foi simples: e se a documentação pudesse responder sozinha?

A arquitetura em três etapas

O sistema funciona em três fases distintas, cada uma com responsabilidade clara.

1. Extração

O script extrair_texto.py lê os PDFs da pasta pops_originais/, extrai o texto completo com PyMuPDF e salva em .txt. Imagens das páginas também são extraídas para uso futuro.

import fitz  # PyMuPDF

def extrair_texto_pdf(caminho_pdf):
    doc = fitz.open(caminho_pdf)
    texto_completo = ""
    for pagina in doc:
        texto_completo += pagina.get_text()
    return texto_completo

Simples, mas importante: a qualidade da extração determina a qualidade das respostas. PDFs escaneados sem OCR são o inimigo número um aqui.

2. Geração de embeddings

Com os textos extraídos, o gerar_embeddings.py divide o conteúdo em chunks usando o RecursiveCharacterTextSplitter da LangChain, gera os vetores e persiste no ChromaDB.

from langchain.text_splitter import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200
)
chunks = splitter.split_text(texto)

O chunk_overlap=200 foi uma decisão deliberada: ele garante que o contexto não seja cortado abruptamente entre um chunk e o próximo, o que melhorou visivelmente a coerência das respostas.

O projeto suporta dois modelos de embedding via config.py:

Gemini models/embedding-001 — qualidade alta, requer API key e gera custo por volume
SBERT local (paraphrase-multilingual-mpnet-base-v2) — roda offline, ótimo para evitar custos ou limites de requisição

Essa flexibilidade foi uma das decisões de design que mais agregou valor, especialmente para quem quer experimentar o projeto sem gastar nada.

3. Consulta (RAG)

Quando o usuário faz uma pergunta, o sistema:

Converte a pergunta em vetor usando o mesmo modelo de embedding
Busca os chunks mais semanticamente similares no ChromaDB
Monta um prompt com os trechos recuperados como contexto
Envia para o Gemini 2.0 Flash gerar a resposta final

resultados = collection.query(
    query_embeddings=[embedding_pergunta],
    n_results=5
)

contexto = "\n\n".join(resultados['documents'][0])

prompt = f"""Você é um assistente especializado nos POPs da empresa.
Use apenas as informações abaixo para responder.

Contexto:
{contexto}

Pergunta: {pergunta}
"""

As interfaces: Discord e API

O projeto expõe a base de conhecimento de duas formas.

Bot do Discord com slash commands:

/pop <pergunta> — consulta a base vetorial e retorna a resposta
/addpop <arquivo.txt> — permite que administradores adicionem novos POPs em tempo real, sem precisar reprocessar toda a base

API FastAPI com endpoint POST /ask, pensada para integrar com outros sistemas internos:

// Request
{ "question": "Como configurar o scanner da impressora Samsung?" }

// Response
{
  "answer": "Para configurar o scanner, siga os passos:\n1. Ligue a impressora...\n[Fonte: POP-ConfiguraçãoScanner.txt]"
}

O desafio que ninguém menciona: custo de tokens

Construir o RAG foi a parte divertida. O desafio real veio depois: como controlar o custo em produção?

Algumas decisões que fizeram diferença:

Usar SBERT para embeddings em vez da API do Gemini reduz o custo de indexação para zero — o modelo roda localmente. O custo só existe na geração de resposta, que é onde o valor real está.

Limitar n_results=5 na busca vetorial evita passar contexto desnecessário para o modelo. Mais contexto = mais tokens = mais custo, sem necessariamente melhorar a resposta.

Gemini 2.0 Flash foi escolhido intencionalmente sobre o Pro: para perguntas objetivas sobre procedimentos, a diferença de qualidade é mínima e a diferença de custo é expressiva.

Deploy: um container, dois processos

Uma decisão que me custou algumas horas foi rodar o bot do Discord e a API FastAPI no mesmo container Docker. A solução foi o Supervisor, que gerencia ambos os processos de forma leve e auto-recuperável.

# supervisord.conf
[program:api]
command=uvicorn api_bot:app --host 0.0.0.0 --port 8000

[program:discord]
command=python bot_discord.py

autostart=true
autorestart=true

O resultado é um container único, leve, que sobe os dois serviços em paralelo e reinicia automaticamente qualquer um que falhe. Para uma VPS de entrada, isso faz toda a diferença.

O que aprendi que não estava no plano

Chunking é uma arte. O tamanho e o overlap dos chunks afetam mais a qualidade das respostas do que o modelo em si. Passei mais tempo ajustando isso do que qualquer outra coisa.

Segurança desde o início. O .gitignore precisou ser configurado antes do primeiro commit público para garantir que nenhum PDF com dados confidenciais da empresa fosse parar no repositório. Um erro aqui é difícil de reverter.

O problema real não era técnico. A parte mais complexa foi entender que tipo de pergunta os usuários fariam e como estruturar os POPs para que o modelo conseguisse recuperar as informações certas. Garbage in, garbage out vale dobrado em RAG.

O projeto é open source

O POPS AI está disponível no GitHub com README completo, .env.example, Docker Compose configurado e passo a passo de instalação tanto local quanto via container.

Você pode clonar, adaptar para sua própria base de conhecimento e usar com seus próprios documentos — seja para POPs, wikis internas, manuais de produto ou qualquer documentação em PDF.

🔗 github.com/obelucca/POPS_AI

Stack utilizada

Python 3.10 LangChain ChromaDB FastAPI Discord.py Google Gemini 2.0 Flash SBERT Docker Supervisor PyMuPDF

Se você chegou até aqui e tem curiosidade sobre alguma decisão de arquitetura, custo de tokens em produção ou como adaptar para um caso de uso diferente — deixa nos comentários. Bora trocar ideia.