DocuMindAI_RAG_Application / src /rag_pipeline.py
AdryanAzul's picture
feat: deploy DocuMind AI (RAG + BYOK + local embeddings)
68e8c03 verified
Raw History Blame Contribute Delete
6.03 kB
"""Orquestração do pipeline RAG: indexação, recuperação e geração BYOK."""
from dataclasses import dataclass
from pathlib import Path
from typing import BinaryIO, Protocol
from src.document_loader import load_pdf
from src.embeddings import EmbeddingModel
from src.llm import LLMConfigError, LLMResult
from src.retriever import Retriever
from src.text_splitter import split_documents
from src.vector_store import StoredDocument, VectorStore
class LLMProtocol(Protocol):
"""Interface mínima esperada para o componente de geração de respostas."""
def generate_answer(self, question: str, contexts: list[StoredDocument]) -> str: ...
@dataclass(frozen=True)
class SourceCitation:
"""Referência de documento e página utilizada para compor a resposta."""
source: str
page: int
excerpt: str
@dataclass(frozen=True)
class RAGResponse:
"""Resultado completo de uma consulta ao pipeline RAG."""
answer: str
sources: list[SourceCitation]
provider_used: str = "none"
used_fallback: bool = False
class RAGPipeline:
"""Coordena carregamento de PDFs, chunking, embeddings locais, busca vetorial e LLM."""
def __init__(
self,
persist_directory: str | Path = "data/chroma_db",
collection_name: str = "documind_documents",
embedding_model: EmbeddingModel | None = None,
vector_store: VectorStore | None = None,
llm: LLMProtocol | None = None,
chunk_size: int = 800,
chunk_overlap: int = 150,
) -> None:
self.chunk_size = chunk_size
self.chunk_overlap = chunk_overlap
self.embedding_model = embedding_model or EmbeddingModel()
self.vector_store = vector_store or VectorStore(
persist_directory=persist_directory,
collection_name=collection_name,
)
self.retriever = Retriever(
embedding_model=self.embedding_model,
vector_store=self.vector_store,
)
self._llm = llm
def set_llm(self, llm: LLMProtocol | None) -> None:
"""Atualiza ou limpa o cliente LLM da sessão."""
self._llm = llm
def _get_llm(self) -> LLMProtocol:
if self._llm is None:
raise LLMConfigError(
"Credenciais não configuradas para esta sessão. "
"Informe sua chave de API na barra lateral para fazer perguntas."
)
return self._llm
def index_pdf(self, file_source: str | Path | BinaryIO, filename: str | None = None) -> int:
"""Extrai texto de um PDF, divide em chunks e armazena no ChromaDB."""
pages = load_pdf(file_source=file_source, filename=filename)
chunks = split_documents(
pages=pages,
chunk_size=self.chunk_size,
chunk_overlap=self.chunk_overlap,
)
embeddings = self.embedding_model.embed_documents([chunk.text for chunk in chunks])
if pages:
# Remove chunks antigos do mesmo arquivo para evitar órfãos em reenvios
self.vector_store.delete_by_source(pages[0].source)
return self.vector_store.add_chunks(chunks=chunks, embeddings=embeddings)
def ask(self, question: str, top_k: int = 4) -> RAGResponse:
"""Executa recuperação semântica e geração de resposta com fontes."""
if self.vector_store.count() == 0:
return RAGResponse(
answer="Nenhum documento foi indexado ainda. Envie um ou mais PDFs na barra lateral para começar.",
sources=[],
)
retrieved_docs = self.retriever.retrieve(query=question, top_k=top_k)
if not retrieved_docs:
return RAGResponse(
answer="Não encontrei informações suficientes nos documentos enviados para responder a essa pergunta.",
sources=[],
)
llm = self._get_llm()
if hasattr(llm, "generate_result"):
result: LLMResult = llm.generate_result(question=question, contexts=retrieved_docs) # type: ignore[attr-defined]
answer = result.text
provider_used = result.provider
used_fallback = result.used_fallback
else:
answer = llm.generate_answer(question=question, contexts=retrieved_docs)
provider_used = "custom"
used_fallback = False
if answer.startswith("Não encontrei informações suficientes"):
return RAGResponse(
answer=answer,
sources=[],
provider_used=provider_used,
used_fallback=used_fallback,
)
citations = self._build_citations(retrieved_docs)
return RAGResponse(
answer=answer,
sources=citations,
provider_used=provider_used,
used_fallback=used_fallback,
)
def list_indexed_sources(self) -> list[str]:
"""Retorna os nomes dos documentos atualmente armazenados no banco vetorial."""
return self.vector_store.list_sources()
def clear_index(self) -> None:
"""Remove todos os documentos indexados do banco vetorial."""
self.vector_store.clear()
def cleanup_session(self) -> None:
"""Limpa credenciais da memória e remove o armazenamento temporário da sessão."""
self._llm = None
self.vector_store.destroy_storage()
@staticmethod
def _build_citations(docs: list[StoredDocument]) -> list[SourceCitation]:
"""Agrupa citações preservando a ordem de relevância e evitando duplicatas exatas."""
seen: set[tuple[str, int]] = set()
citations: list[SourceCitation] = []
for doc in docs:
key = (doc.source, doc.page)
if key not in seen:
seen.add(key)
excerpt = doc.text[:220].rstrip() + ("..." if len(doc.text) > 220 else "")
citations.append(SourceCitation(source=doc.source, page=doc.page, excerpt=excerpt))
return citations