File size: 6,026 Bytes
68e8c03
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
"""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