"""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