Deploy

.gitignore

@@ -0,0 +1,58 @@
+# Arquivos de upload (PDFs e outros documentos)
+uploaded_data/
+temp/
+
+# Cache Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Ambientes virtuais
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+logs/
+
+# Arquivos temporários do sistema
+.DS_Store
+Thumbs.db
+
+# Arquivos de configuração local
+config.local.py
+settings.local.py
+
+# Arquivos de backup
+*.bak
+*.backup
+*~
+
+# Arquivos de teste
+test_files/
+*.test
+
+# Arquivos grandes ou binários
+*.pdf
+*.docx
+*.xlsx
+*.pptx
+*.zip
+*.tar.gz
+*.rar
+
+# Modelos salvos localmente
+models/
+checkpoints/

agents/__init__.py

@@ -0,0 +1 @@
+# Módulo de agentes do AgentPDF

agents/state.py

@@ -0,0 +1,108 @@
+"""
+Definições de estado para o AgentPDF usando LangGraph.
+
+Este módulo define as estruturas de estado que serão utilizadas
+pelos nós do grafo para compartilhar informações durante a execução.
+"""
+
+from typing import List, Optional, Dict, Any
+from typing_extensions import TypedDict
+from langchain_core.messages import BaseMessage
+from langgraph.graph.message import add_messages
+from typing import Annotated
+
+
+class PDFState(TypedDict):
+    """
+    Estado principal do AgentPDF.
+    
+    Contém todas as informações necessárias para o processamento
+    de PDFs e geração de respostas.
+    """
+    # Mensagens da conversa
+    messages: Annotated[List[BaseMessage], add_messages]
+    
+    # Informações do PDF
+    pdf_path: Optional[str]
+    pdf_text: Optional[str]
+    pdf_chunks: Optional[List[str]]
+    
+    # Vector store e embeddings
+    vector_store: Optional[Any]
+    embeddings_created: bool
+    
+    # Contexto recuperado
+    retrieved_context: Optional[List[str]]
+    
+    # Pergunta do usuário
+    user_question: Optional[str]
+    
+    # Resposta final
+    final_answer: Optional[str]
+    
+    # Status do processamento
+    processing_status: str
+    error_message: Optional[str]
+
+
+class ProcessingState(TypedDict):
+    """
+    Estado específico para processamento de documentos.
+    """
+    document_path: str
+    extracted_text: Optional[str]
+    text_chunks: Optional[List[str]]
+    chunk_size: int
+    chunk_overlap: int
+
+
+class RetrievalState(TypedDict):
+    """
+    Estado específico para recuperação de contexto.
+    """
+    query: str
+    retrieved_docs: Optional[List[str]]
+    similarity_scores: Optional[List[float]]
+    top_k: int
+
+
+class LLMState(TypedDict):
+    """
+    Estado específico para interação com o LLM.
+    """
+    system_prompt: str
+    user_query: str
+    context: Optional[str]
+    response: Optional[str]
+    model_name: str
+
+
+# Estados de entrada e saída para diferentes nós
+class InputState(TypedDict):
+    """Estado de entrada para o grafo."""
+    messages: Annotated[List[BaseMessage], add_messages]
+    pdf_path: Optional[str]
+
+
+class OutputState(TypedDict):
+    """Estado de saída do grafo."""
+    messages: Annotated[List[BaseMessage], add_messages]
+    final_answer: str
+
+
+# Configurações padrão
+DEFAULT_CHUNK_SIZE = 1000
+DEFAULT_CHUNK_OVERLAP = 200
+DEFAULT_TOP_K = 5
+DEFAULT_MODEL = "gpt-4o-mini"
+
+# Status de processamento
+class ProcessingStatus:
+    IDLE = "idle"
+    LOADING_PDF = "loading_pdf"
+    PROCESSING_TEXT = "processing_text"
+    CREATING_EMBEDDINGS = "creating_embeddings"
+    RETRIEVING_CONTEXT = "retrieving_context"
+    GENERATING_RESPONSE = "generating_response"
+    COMPLETED = "completed"
+    ERROR = "error"

app.py

@@ -0,0 +1,94 @@
+"""
+Aplicação principal do AgentPDF.
+
+Este é o ponto de entrada da aplicação que inicializa
+a interface Gradio e configura o ambiente.
+"""
+
+import os
+import sys
+import warnings
+from pathlib import Path
+
+# Adiciona o diretório raiz ao path
+root_dir = Path(__file__).parent
+sys.path.insert(0, str(root_dir))
+
+# Suprime warnings desnecessários
+warnings.filterwarnings("ignore", category=UserWarning)
+warnings.filterwarnings("ignore", category=FutureWarning)
+
+from interface.modern_interface import create_modern_gradio_app
+from utils.config import Config
+from utils.logger import main_logger, setup_logger
+
+
+def setup_environment():
+    """Configura o ambiente da aplicação."""
+    # Configura logging
+    setup_logger("AgentPDF", "INFO")
+    
+    # Verifica configurações
+    if not Config.validate_config():
+        main_logger.warning("⚠️  Configuração incompleta detectada!")
+        main_logger.warning("   Certifique-se de configurar OPENAI_API_KEY no arquivo .env")
+        main_logger.warning("   A aplicação pode não funcionar corretamente sem a chave da API.")
+    
+    # Cria diretórios necessários
+    os.makedirs(Config.UPLOAD_DIR, exist_ok=True)
+    os.makedirs(Config.TEMP_DIR, exist_ok=True)
+    
+    main_logger.info("🚀 Ambiente configurado com sucesso!")
+
+
+def main():
+    """Função principal da aplicação."""
+    try:
+        # Banner de inicialização
+        print("""
+╔══════════════════════════════════════════════════════════════╗
+║                        🤖 AgentPDF                          ║
+║                                                              ║
+║           Chat Inteligente com Documentos PDF               ║
+║                                                              ║
+║    Powered by LangChain + LangGraph + GPT-4o-mini          ║
+╚══════════════════════════════════════════════════════════════╝
+        """)
+        
+        # Configura ambiente
+        setup_environment()
+        
+        # Informações de inicialização
+        main_logger.info("🔧 Inicializando AgentPDF...")
+        main_logger.info(f"📁 Diretório de upload: {Config.UPLOAD_DIR}")
+        main_logger.info(f"🌐 Porta: {Config.GRADIO_PORT}")
+        main_logger.info(f"🔑 OpenAI API configurada: {'✅' if Config.OPENAI_API_KEY else '❌'}")
+        
+        # Cria e executa a aplicação Gradio
+        main_logger.info("🎨 Criando interface Gradio moderna...")
+        app = create_modern_gradio_app()
+        
+        main_logger.info("🚀 Iniciando servidor...")
+        main_logger.info(f"🌍 Acesse: http://localhost:{Config.GRADIO_PORT}")
+        
+        # Executa a aplicação
+        app.launch(
+            server_name="0.0.0.0",
+            server_port=Config.GRADIO_PORT,
+            share=Config.GRADIO_SHARE,
+            show_error=True,
+            quiet=False
+        )
+        
+    except KeyboardInterrupt:
+        main_logger.info("👋 Aplicação interrompida pelo usuário")
+        sys.exit(0)
+        
+    except Exception as e:
+        main_logger.error(f"❌ Erro fatal na aplicação: {e}")
+        main_logger.exception("Detalhes do erro:")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

interface/__init__.py

@@ -0,0 +1 @@
+# Módulo da interface Gradio

interface/modern_interface.py

@@ -0,0 +1,255 @@
+"""
+Interface Gradio moderna para o AgentPDF com tema escuro.
+
+Esta interface replica o design moderno da imagem fornecida.
+"""
+
+import os
+import shutil
+import gradio as gr
+from typing import List, Tuple, Optional
+
+from main_graph import get_agent_graph, process_pdf_file, ask_pdf_question
+from utils.config import Config
+from utils.logger import main_logger
+
+
+class ModernAgentPDFInterface:
+    """Interface moderna para o AgentPDF."""
+    
+    def __init__(self):
+        """Inicializa a interface."""
+        self.current_state = None
+        self.chat_history = []
+        self.pdf_processed = False
+        self.current_pdf_name = None
+        
+    def upload_pdf(self, file) -> Tuple[str, str, List[List[str]]]:
+        """Processa o upload de um arquivo PDF."""
+        try:
+            if file is None:
+                return "❌ Erro: Nenhum arquivo selecionado", "Selecione um arquivo PDF", []
+            
+            if not file.name.lower().endswith('.pdf'):
+                return "❌ Erro: Formato inválido", "Apenas arquivos PDF são aceitos", []
+            
+            # Processa o arquivo
+            upload_dir = Config.UPLOAD_DIR
+            os.makedirs(upload_dir, exist_ok=True)
+            
+            filename = f"uploaded_{os.path.basename(file.name)}"
+            pdf_path = os.path.join(upload_dir, filename)
+            shutil.copy2(file.name, pdf_path)
+            
+            # Processa o PDF
+            result = process_pdf_file(pdf_path)
+            
+            if result["success"]:
+                self.current_state = result["result"]
+                self.pdf_processed = True
+                self.current_pdf_name = os.path.basename(file.name)
+                self.chat_history = []
+                
+                welcome_message = [
+                    ["Sistema", f"✅ PDF '{self.current_pdf_name}' processado com sucesso!"]
+                ]
+                
+                return (
+                    "✅ Documento processado",
+                    f"PDF: {self.current_pdf_name}\nStatus: Pronto para perguntas",
+                    welcome_message
+                )
+            else:
+                self.pdf_processed = False
+                return "❌ Erro no processamento", f"Erro: {result['error']}", []
+                
+        except Exception as e:
+            main_logger.error(f"Erro no upload: {e}")
+            return "❌ Erro inesperado", f"Erro: {str(e)}", []
+    
+    def chat_with_pdf(self, message: str, history: List[List[str]]) -> Tuple[List[List[str]], str]:
+        """Processa uma mensagem do chat."""
+        try:
+            if not self.pdf_processed or not self.current_state:
+                error_msg = "❌ Faça upload de um PDF primeiro"
+                history.append([message, error_msg])
+                return history, ""
+            
+            if not message.strip():
+                return history, ""
+            
+            # Processa a pergunta
+            result = ask_pdf_question(message, self.current_state)
+            
+            if result["success"]:
+                answer = result["answer"]
+                if result.get("result"):
+                    self.current_state = result["result"]
+            else:
+                answer = f"❌ Erro: {result['error']}"
+            
+            history.append([message, answer])
+            return history, ""
+            
+        except Exception as e:
+            main_logger.error(f"Erro no chat: {e}")
+            error_msg = f"❌ Erro inesperado: {str(e)}"
+            history.append([message, error_msg])
+            return history, ""
+    
+    def clear_chat(self) -> Tuple[List, str]:
+        """Limpa o histórico do chat."""
+        self.chat_history = []
+        return [], ""
+    
+    def get_pdf_info(self) -> str:
+        """Retorna informações sobre o PDF atual."""
+        if not self.pdf_processed or not self.current_pdf_name:
+            return "Nenhum documento carregado"
+        
+        info = f"📄 {self.current_pdf_name}\n"
+        info += f"✅ Processado e indexado\n"
+        
+        if self.current_state:
+            chunks = self.current_state.get("pdf_chunks", [])
+            if chunks:
+                info += f"📊 {len(chunks)} seções"
+        
+        return info
+    
+    def create_interface(self) -> gr.Blocks:
+        """Cria a interface moderna usando templates nativos do Gradio."""
+
+        # CSS simples e limpo
+        css = """
+        .gradio-container {
+            max-width: 100% !important;
+            padding: 20px !important;
+        }
+
+        .chat-container {
+            height: 70vh !important;
+        }
+
+        .send-button {
+            height: 56px !important;
+            min-height: 56px !important;
+        }
+
+        .sidebar-config {
+            max-width: 320px !important;
+            min-width: 320px !important;
+            width: 320px !important;
+        }
+        """
+
+        with gr.Blocks(
+            title="AgentPDF",
+            theme=gr.themes.Soft(
+                primary_hue="blue",
+                secondary_hue="slate",
+                neutral_hue="slate"
+            ),
+            css=css
+        ) as interface:
+
+            gr.Markdown("# 🤖 AgentPDF - Chat com Documentos")
+
+            with gr.Row():
+                # SIDEBAR - Configurações
+                with gr.Column(scale=1, elem_classes=["sidebar-config"]):
+                    gr.Markdown("## ⚙️ Configurações")
+
+                    with gr.Group():
+                        file_upload = gr.File(
+                            label="Selecione um PDF",
+                            file_types=[".pdf"],
+                            type="filepath"
+                        )
+
+                        upload_btn = gr.Button(
+                            "🚀 Processar PDF",
+                            variant="primary",
+                            size="lg"
+                        )
+
+                    with gr.Group():
+                        upload_status = gr.Textbox(
+                            label="📊 Status",
+                            interactive=False,
+                            placeholder="Aguardando upload...",
+                            lines=1
+                        )
+
+                        pdf_info = gr.Textbox(
+                            label="📄 Informações",
+                            interactive=False,
+                            value="Nenhum documento carregado",
+                            lines=2
+                        )
+
+
+                # ÁREA PRINCIPAL - Chat
+                with gr.Column(scale=3):
+                    gr.Markdown("## 💬 Conversa")
+
+                    chatbot = gr.Chatbot(
+                        elem_classes=["chat-container"],
+                        show_copy_button=True,
+                        bubble_full_width=False
+                    )
+
+                    with gr.Row():
+                        msg_input = gr.Textbox(
+                            placeholder="Digite sua pergunta sobre o PDF...",
+                            show_label=False,
+                            scale=5,
+                            lines=1
+                        )
+
+                        send_btn = gr.Button(
+                            "📤",
+                            variant="primary",
+                            scale=1,
+                            elem_classes=["send-button"]
+                        )
+
+            # Eventos da interface
+            upload_btn.click(
+                fn=self.upload_pdf,
+                inputs=[file_upload],
+                outputs=[upload_status, pdf_info, chatbot],
+                show_progress=True
+            )
+
+            send_btn.click(
+                fn=self.chat_with_pdf,
+                inputs=[msg_input, chatbot],
+                outputs=[chatbot, msg_input],
+                show_progress=True
+            )
+
+            msg_input.submit(
+                fn=self.chat_with_pdf,
+                inputs=[msg_input, chatbot],
+                outputs=[chatbot, msg_input],
+                show_progress=True
+            )
+
+        return interface
+
+
+def create_modern_gradio_app() -> gr.Blocks:
+    """Cria a aplicação Gradio moderna."""
+    interface = ModernAgentPDFInterface()
+    return interface.create_interface()
+
+
+if __name__ == "__main__":
+    app = create_modern_gradio_app()
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=Config.GRADIO_PORT,
+        share=Config.GRADIO_SHARE,
+        show_error=True
+    )

main_graph.py

@@ -0,0 +1,332 @@
+"""
+Grafo principal do AgentPDF usando LangGraph.
+
+Este módulo define o grafo principal que orquestra todos os nós
+para processar PDFs e responder perguntas usando LLM.
+"""
+
+from typing import Literal
+from langgraph.graph import StateGraph, START, END
+from langgraph.graph.message import add_messages
+from langchain_core.messages import HumanMessage
+
+from agents.state import PDFState, ProcessingStatus
+from nodes.pdf_loader import load_pdf_node
+from nodes.text_processor import text_processing_node
+from nodes.embeddings_creator import embeddings_creation_node
+from nodes.context_retriever import context_retrieval_node
+from nodes.llm_agent import llm_agent_node
+from utils.logger import log_graph_execution, main_logger
+from utils.config import Config
+
+
+class AgentPDFGraph:
+    """
+    Classe principal do grafo AgentPDF.
+    
+    Gerencia o fluxo de processamento de PDFs e geração de respostas
+    usando a arquitetura de nós do LangGraph.
+    """
+    
+    def __init__(self):
+        """Inicializa o grafo AgentPDF."""
+        self.graph = None
+        self._build_graph()
+        log_graph_execution("INIT", "Grafo AgentPDF inicializado")
+    
+    def _build_graph(self):
+        """Constrói o grafo com todos os nós e conexões."""
+        # Cria o StateGraph
+        graph_builder = StateGraph(PDFState)
+        
+        # Adiciona todos os nós
+        self._add_nodes(graph_builder)
+        
+        # Define as conexões entre nós
+        self._add_edges(graph_builder)
+        
+        # Compila o grafo
+        self.graph = graph_builder.compile()
+        
+        log_graph_execution("BUILD", "Grafo construído e compilado com sucesso")
+    
+    def _add_nodes(self, builder: StateGraph):
+        """
+        Adiciona todos os nós ao grafo.
+        
+        Args:
+            builder: Builder do StateGraph
+        """
+        # Nó de carregamento de PDF
+        builder.add_node("load_pdf", load_pdf_node)
+        
+        # Nó de processamento de texto
+        builder.add_node("process_text", text_processing_node)
+        
+        # Nó de criação de embeddings
+        builder.add_node("create_embeddings", embeddings_creation_node)
+        
+        # Nó de recuperação de contexto
+        builder.add_node("retrieve_context", context_retrieval_node)
+        
+        # Nó do agente LLM
+        builder.add_node("llm_agent", llm_agent_node)
+        
+        log_graph_execution("NODES", "Todos os nós adicionados ao grafo")
+    
+    def _add_edges(self, builder: StateGraph):
+        """
+        Define as conexões entre os nós.
+        
+        Args:
+            builder: Builder do StateGraph
+        """
+        # Ponto de entrada condicional
+        builder.add_conditional_edges(
+            START,
+            self._route_start,
+            {
+                "process_pdf": "load_pdf",
+                "answer_question": "retrieve_context"
+            }
+        )
+        
+        # Fluxo de processamento de PDF
+        builder.add_edge("load_pdf", "process_text")
+        builder.add_edge("process_text", "create_embeddings")
+        
+        # Após criar embeddings, vai para o fim (PDF processado)
+        builder.add_edge("create_embeddings", END)
+        
+        # Fluxo de resposta a perguntas
+        builder.add_edge("retrieve_context", "llm_agent")
+        builder.add_edge("llm_agent", END)
+        
+        log_graph_execution("EDGES", "Todas as conexões definidas")
+    
+    def _route_start(self, state: PDFState) -> Literal["process_pdf", "answer_question"]:
+        """
+        Determina o ponto de entrada baseado no estado.
+        
+        Args:
+            state: Estado atual do grafo
+        
+        Returns:
+            str: Próximo nó a ser executado
+        """
+        # Se há um PDF para processar e ainda não foi processado
+        if state.get("pdf_path") and not state.get("embeddings_created", False):
+            log_graph_execution("ROUTE", "Direcionando para processamento de PDF")
+            return "process_pdf"
+        
+        # Se há uma pergunta e o PDF já foi processado
+        if state.get("messages") and state.get("embeddings_created", False):
+            log_graph_execution("ROUTE", "Direcionando para resposta de pergunta")
+            return "answer_question"
+        
+        # Fallback: processar PDF
+        log_graph_execution("ROUTE", "Fallback: direcionando para processamento de PDF")
+        return "process_pdf"
+    
+    def process_pdf(self, pdf_path: str) -> dict:
+        """
+        Processa um arquivo PDF.
+        
+        Args:
+            pdf_path: Caminho para o arquivo PDF
+        
+        Returns:
+            dict: Resultado do processamento
+        """
+        log_graph_execution("PROCESS_PDF", f"Iniciando processamento: {pdf_path}")
+        
+        try:
+            # Estado inicial para processamento
+            initial_state = {
+                "pdf_path": pdf_path,
+                "messages": [],
+                "embeddings_created": False,
+                "processing_status": ProcessingStatus.LOADING_PDF
+            }
+            
+            # Executa o grafo
+            result = self.graph.invoke(initial_state)
+            
+            # Verifica se o processamento foi bem-sucedido
+            if result.get("processing_status") == ProcessingStatus.ERROR:
+                error_msg = result.get("error_message", "Erro desconhecido")
+                log_graph_execution("PROCESS_PDF", f"ERRO: {error_msg}")
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "result": result
+                }
+            
+            log_graph_execution("PROCESS_PDF", "PDF processado com sucesso")
+            return {
+                "success": True,
+                "message": "PDF processado e indexado com sucesso!",
+                "result": result
+            }
+            
+        except Exception as e:
+            error_msg = f"Erro no processamento do PDF: {str(e)}"
+            log_graph_execution("PROCESS_PDF", f"ERRO: {error_msg}")
+            main_logger.exception("Erro detalhado no processamento:")
+            
+            return {
+                "success": False,
+                "error": error_msg,
+                "result": None
+            }
+    
+    def ask_question(self, question: str, current_state: dict = None) -> dict:
+        """
+        Faz uma pergunta sobre o PDF processado.
+        
+        Args:
+            question: Pergunta do usuário
+            current_state: Estado atual (opcional)
+        
+        Returns:
+            dict: Resposta gerada
+        """
+        log_graph_execution("ASK_QUESTION", f"Pergunta: {question[:100]}...")
+        
+        try:
+            # Verifica se há estado atual ou cria um novo
+            if current_state is None:
+                log_graph_execution("ASK_QUESTION", "ERRO: Nenhum estado fornecido")
+                return {
+                    "success": False,
+                    "error": "PDF não foi processado. Faça upload de um PDF primeiro.",
+                    "answer": None
+                }
+            
+            # Verifica se o PDF foi processado
+            if not current_state.get("embeddings_created", False):
+                return {
+                    "success": False,
+                    "error": "PDF não foi processado completamente. Tente novamente.",
+                    "answer": None
+                }
+            
+            # Adiciona a pergunta às mensagens
+            human_message = HumanMessage(content=question)
+            messages = current_state.get("messages", [])
+            messages.append(human_message)
+            
+            # Estado para a pergunta
+            question_state = {
+                **current_state,
+                "messages": messages,
+                "user_question": question,
+                "processing_status": ProcessingStatus.RETRIEVING_CONTEXT
+            }
+            
+            # Executa o grafo
+            result = self.graph.invoke(question_state)
+            
+            # Verifica se houve erro
+            if result.get("processing_status") == ProcessingStatus.ERROR:
+                error_msg = result.get("error_message", "Erro desconhecido")
+                log_graph_execution("ASK_QUESTION", f"ERRO: {error_msg}")
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "answer": None
+                }
+            
+            # Extrai a resposta
+            answer = result.get("final_answer", "Não foi possível gerar uma resposta.")
+            
+            log_graph_execution("ASK_QUESTION", f"Resposta gerada: {len(answer)} caracteres")
+            
+            return {
+                "success": True,
+                "answer": answer,
+                "result": result
+            }
+            
+        except Exception as e:
+            error_msg = f"Erro ao processar pergunta: {str(e)}"
+            log_graph_execution("ASK_QUESTION", f"ERRO: {error_msg}")
+            main_logger.exception("Erro detalhado na pergunta:")
+            
+            return {
+                "success": False,
+                "error": error_msg,
+                "answer": None
+            }
+    
+    def get_graph_visualization(self) -> str:
+        """
+        Retorna uma representação visual do grafo.
+        
+        Returns:
+            str: Representação do grafo
+        """
+        try:
+            # Tenta gerar visualização se disponível
+            if hasattr(self.graph, 'get_graph'):
+                return str(self.graph.get_graph())
+            else:
+                return "Visualização não disponível"
+        except Exception as e:
+            main_logger.warning(f"Erro ao gerar visualização: {e}")
+            return "Erro na visualização do grafo"
+    
+    def get_status(self) -> dict:
+        """
+        Retorna o status atual do grafo.
+        
+        Returns:
+            dict: Status do grafo
+        """
+        return {
+            "graph_compiled": self.graph is not None,
+            "config_valid": Config.validate_config(),
+            "nodes_count": 5,  # Número de nós no grafo
+            "ready": self.graph is not None and Config.validate_config()
+        }
+
+
+# Instância global do grafo
+agent_pdf_graph = AgentPDFGraph()
+
+
+def get_agent_graph() -> AgentPDFGraph:
+    """
+    Retorna a instância global do grafo.
+    
+    Returns:
+        AgentPDFGraph: Instância do grafo
+    """
+    return agent_pdf_graph
+
+
+def process_pdf_file(pdf_path: str) -> dict:
+    """
+    Função de conveniência para processar um PDF.
+    
+    Args:
+        pdf_path: Caminho para o arquivo PDF
+    
+    Returns:
+        dict: Resultado do processamento
+    """
+    return agent_pdf_graph.process_pdf(pdf_path)
+
+
+def ask_pdf_question(question: str, state: dict = None) -> dict:
+    """
+    Função de conveniência para fazer perguntas.
+    
+    Args:
+        question: Pergunta do usuário
+        state: Estado atual do processamento
+    
+    Returns:
+        dict: Resposta gerada
+    """
+    return agent_pdf_graph.ask_question(question, state)

nodes/__init__.py

@@ -0,0 +1 @@
+# Módulo de nós do LangGraph

nodes/context_retriever.py

@@ -0,0 +1,333 @@
+"""
+Nó de recuperação de contexto para o AgentPDF.
+
+Este nó é responsável por buscar documentos relevantes no vector store
+baseado na pergunta do usuário para fornecer contexto ao LLM.
+"""
+
+from typing import Dict, Any, List, Tuple
+from langchain_community.vectorstores import FAISS
+from langchain_core.runnables import RunnableConfig
+from langchain_core.documents import Document
+from langchain_core.messages import HumanMessage
+
+from agents.state import PDFState, ProcessingStatus
+from utils.config import Config
+from utils.logger import log_node_execution, main_logger
+
+
+def context_retrieval_node(state: PDFState, config: RunnableConfig) -> Dict[str, Any]:
+    """
+    Nó responsável por recuperar contexto relevante para a pergunta.
+    
+    Este nó:
+    1. Extrai a pergunta do usuário das mensagens
+    2. Busca documentos relevantes no vector store
+    3. Seleciona e otimiza o contexto
+    4. Atualiza o estado com o contexto recuperado
+    
+    Args:
+        state: Estado atual do grafo
+        config: Configuração do LangGraph
+    
+    Returns:
+        Dict[str, Any]: Atualizações para o estado
+    """
+    log_node_execution("CONTEXT_RETRIEVER", "START", "Iniciando recuperação de contexto")
+    
+    try:
+        # Verifica se o vector store existe
+        vector_store = state.get("vector_store")
+        if not vector_store:
+            error_msg = "Vector store não encontrado. Execute o processamento do PDF primeiro."
+            log_node_execution("CONTEXT_RETRIEVER", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        # Extrai a pergunta do usuário
+        user_question = extract_user_question(state)
+        if not user_question:
+            error_msg = "Nenhuma pergunta encontrada nas mensagens"
+            log_node_execution("CONTEXT_RETRIEVER", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        log_node_execution(
+            "CONTEXT_RETRIEVER", 
+            "PROCESSING", 
+            f"Buscando contexto para: '{user_question[:100]}...'"
+        )
+        
+        # Busca documentos relevantes
+        relevant_docs = retrieve_relevant_documents(vector_store, user_question)
+        
+        if not relevant_docs:
+            log_node_execution(
+                "CONTEXT_RETRIEVER", 
+                "SUCCESS", 
+                "Nenhum contexto específico encontrado, usando busca ampla"
+            )
+            # Tenta uma busca mais ampla
+            relevant_docs = retrieve_relevant_documents(
+                vector_store, 
+                user_question, 
+                k=10, 
+                use_broad_search=True
+            )
+        
+        # Processa e otimiza o contexto
+        context_text = process_retrieved_context(relevant_docs, user_question)
+        
+        log_node_execution(
+            "CONTEXT_RETRIEVER", 
+            "SUCCESS", 
+            f"Contexto recuperado: {len(relevant_docs)} documentos, {len(context_text)} caracteres"
+        )
+        
+        return {
+            "retrieved_context": [doc.page_content for doc in relevant_docs],
+            "user_question": user_question,
+            "processing_status": ProcessingStatus.GENERATING_RESPONSE,
+            "error_message": None
+        }
+        
+    except Exception as e:
+        error_msg = f"Erro na recuperação de contexto: {str(e)}"
+        log_node_execution("CONTEXT_RETRIEVER", "ERROR", error_msg)
+        main_logger.exception("Erro detalhado na recuperação de contexto:")
+        
+        return {
+            "processing_status": ProcessingStatus.ERROR,
+            "error_message": error_msg
+        }
+
+
+def extract_user_question(state: PDFState) -> str:
+    """
+    Extrai a pergunta do usuário das mensagens.
+    
+    Args:
+        state: Estado atual contendo as mensagens
+    
+    Returns:
+        str: Pergunta do usuário
+    """
+    messages = state.get("messages", [])
+    
+    # Procura pela última mensagem humana
+    for message in reversed(messages):
+        if isinstance(message, HumanMessage):
+            return message.content.strip()
+    
+    # Fallback: verifica se há pergunta direta no estado
+    user_question = state.get("user_question")
+    if user_question:
+        return user_question.strip()
+    
+    return ""
+
+
+def retrieve_relevant_documents(
+    vector_store: FAISS, 
+    query: str, 
+    k: int = None, 
+    use_broad_search: bool = False
+) -> List[Document]:
+    """
+    Busca documentos relevantes no vector store.
+    
+    Args:
+        vector_store: Vector store FAISS
+        query: Pergunta do usuário
+        k: Número de documentos para retornar
+        use_broad_search: Se deve usar busca mais ampla
+    
+    Returns:
+        List[Document]: Lista de documentos relevantes
+    """
+    try:
+        # Configurações de busca
+        config = Config.get_retrieval_config()
+        search_k = k or config["k"]
+        
+        if use_broad_search:
+            search_k = min(search_k * 2, 15)  # Busca mais ampla
+        
+        # Busca com scores de similaridade
+        docs_with_scores = vector_store.similarity_search_with_score(
+            query, 
+            k=search_k
+        )
+        
+        # Filtra por threshold de similaridade se não for busca ampla
+        if not use_broad_search:
+            threshold = config["score_threshold"]
+            filtered_docs = [
+                doc for doc, score in docs_with_scores 
+                if score <= threshold  # FAISS usa distância (menor = mais similar)
+            ]
+        else:
+            # Na busca ampla, aceita mais documentos
+            filtered_docs = [doc for doc, score in docs_with_scores]
+        
+        # Log da busca
+        main_logger.debug(f"Busca retornou {len(docs_with_scores)} documentos")
+        main_logger.debug(f"Após filtragem: {len(filtered_docs)} documentos")
+        
+        if docs_with_scores:
+            best_score = docs_with_scores[0][1]
+            main_logger.debug(f"Melhor score de similaridade: {best_score:.4f}")
+        
+        return filtered_docs
+        
+    except Exception as e:
+        main_logger.error(f"Erro na busca de documentos: {e}")
+        return []
+
+
+def process_retrieved_context(documents: List[Document], query: str) -> str:
+    """
+    Processa e otimiza o contexto recuperado.
+    
+    Args:
+        documents: Lista de documentos recuperados
+        query: Pergunta original do usuário
+    
+    Returns:
+        str: Contexto processado e otimizado
+    """
+    if not documents:
+        return ""
+    
+    # Ordena documentos por relevância (se tiver scores)
+    sorted_docs = rank_documents_by_relevance(documents, query)
+    
+    # Combina o contexto
+    context_parts = []
+    total_length = 0
+    max_context_length = 4000  # Limite para não sobrecarregar o LLM
+    
+    for i, doc in enumerate(sorted_docs):
+        content = doc.page_content.strip()
+        
+        # Verifica se ainda cabe no limite
+        if total_length + len(content) > max_context_length:
+            # Tenta adicionar uma versão truncada
+            remaining_space = max_context_length - total_length
+            if remaining_space > 200:  # Só adiciona se sobrar espaço significativo
+                truncated_content = content[:remaining_space-50] + "..."
+                context_parts.append(f"[Documento {i+1}]\n{truncated_content}")
+            break
+        
+        context_parts.append(f"[Documento {i+1}]\n{content}")
+        total_length += len(content)
+    
+    # Junta o contexto
+    final_context = "\n\n".join(context_parts)
+    
+    main_logger.debug(f"Contexto final: {len(final_context)} caracteres de {len(documents)} documentos")
+    
+    return final_context
+
+
+def rank_documents_by_relevance(documents: List[Document], query: str) -> List[Document]:
+    """
+    Ordena documentos por relevância à pergunta.
+    
+    Args:
+        documents: Lista de documentos
+        query: Pergunta do usuário
+    
+    Returns:
+        List[Document]: Documentos ordenados por relevância
+    """
+    # Para uma implementação simples, vamos usar a ordem original
+    # Em uma versão mais avançada, poderíamos implementar re-ranking
+    
+    # Calcula scores simples baseados em palavras-chave
+    query_words = set(query.lower().split())
+    
+    def calculate_relevance_score(doc: Document) -> float:
+        content_words = set(doc.page_content.lower().split())
+        
+        # Conta palavras em comum
+        common_words = query_words.intersection(content_words)
+        
+        # Score baseado na proporção de palavras em comum
+        if len(query_words) == 0:
+            return 0.0
+        
+        return len(common_words) / len(query_words)
+    
+    # Ordena por score de relevância (decrescente)
+    scored_docs = [(doc, calculate_relevance_score(doc)) for doc in documents]
+    scored_docs.sort(key=lambda x: x[1], reverse=True)
+    
+    # Log dos scores para debug
+    for i, (doc, score) in enumerate(scored_docs[:3]):
+        main_logger.debug(f"Doc {i+1} relevance score: {score:.3f}")
+    
+    return [doc for doc, score in scored_docs]
+
+
+def enhance_query_for_retrieval(query: str) -> str:
+    """
+    Melhora a query para melhor recuperação.
+    
+    Args:
+        query: Query original
+    
+    Returns:
+        str: Query melhorada
+    """
+    # Remove palavras muito comuns que podem atrapalhar a busca
+    stop_words = {
+        'o', 'a', 'os', 'as', 'um', 'uma', 'uns', 'umas',
+        'de', 'do', 'da', 'dos', 'das', 'em', 'no', 'na',
+        'nos', 'nas', 'por', 'para', 'com', 'sem', 'sobre',
+        'que', 'qual', 'quais', 'como', 'quando', 'onde',
+        'é', 'são', 'foi', 'foram', 'ser', 'estar'
+    }
+    
+    # Mantém apenas palavras significativas
+    words = query.lower().split()
+    meaningful_words = [word for word in words if word not in stop_words and len(word) > 2]
+    
+    enhanced_query = ' '.join(meaningful_words)
+    
+    if enhanced_query != query.lower():
+        main_logger.debug(f"Query melhorada: '{query}' -> '{enhanced_query}'")
+    
+    return enhanced_query if enhanced_query else query
+
+
+def get_retrieval_statistics(documents: List[Document]) -> Dict[str, Any]:
+    """
+    Calcula estatísticas da recuperação.
+    
+    Args:
+        documents: Documentos recuperados
+    
+    Returns:
+        Dict[str, Any]: Estatísticas da recuperação
+    """
+    if not documents:
+        return {
+            "total_documents": 0,
+            "total_characters": 0,
+            "average_length": 0
+        }
+    
+    lengths = [len(doc.page_content) for doc in documents]
+    
+    return {
+        "total_documents": len(documents),
+        "total_characters": sum(lengths),
+        "average_length": sum(lengths) / len(lengths),
+        "min_length": min(lengths),
+        "max_length": max(lengths)
+    }

nodes/embeddings_creator.py

@@ -0,0 +1,303 @@
+"""
+Nó de criação de embeddings e vector store para o AgentPDF.
+
+Este nó é responsável por gerar embeddings dos chunks de texto
+e criar um vector store FAISS para recuperação eficiente.
+"""
+
+from typing import Dict, Any, List
+from langchain_openai import OpenAIEmbeddings
+from langchain_community.vectorstores import FAISS
+from langchain_core.runnables import RunnableConfig
+from langchain_core.documents import Document
+
+from agents.state import PDFState, ProcessingStatus
+from utils.config import Config, get_openai_api_key
+from utils.logger import log_node_execution, main_logger
+
+
+def embeddings_creation_node(state: PDFState, config: RunnableConfig) -> Dict[str, Any]:
+    """
+    Nó responsável por criar embeddings e vector store.
+    
+    Este nó:
+    1. Recebe os chunks de texto processados
+    2. Gera embeddings usando OpenAI
+    3. Cria um vector store FAISS
+    4. Atualiza o estado com o vector store
+    
+    Args:
+        state: Estado atual do grafo contendo os chunks
+        config: Configuração do LangGraph
+    
+    Returns:
+        Dict[str, Any]: Atualizações para o estado
+    """
+    log_node_execution("EMBEDDINGS_CREATOR", "START", "Iniciando criação de embeddings")
+    
+    try:
+        # Verifica se há chunks para processar
+        pdf_chunks = state.get("pdf_chunks")
+        if not pdf_chunks:
+            error_msg = "Nenhum chunk encontrado para criar embeddings"
+            log_node_execution("EMBEDDINGS_CREATOR", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        # Verifica se a API key está configurada
+        api_key = get_openai_api_key()
+        if not api_key:
+            error_msg = "Chave da API OpenAI não configurada"
+            log_node_execution("EMBEDDINGS_CREATOR", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        log_node_execution(
+            "EMBEDDINGS_CREATOR", 
+            "PROCESSING", 
+            f"Criando embeddings para {len(pdf_chunks)} chunks"
+        )
+        
+        # Cria o modelo de embeddings
+        embeddings_model = create_embeddings_model()
+        
+        # Converte chunks em documentos
+        documents = create_documents_from_chunks(pdf_chunks)
+        
+        # Cria o vector store
+        vector_store = create_vector_store(documents, embeddings_model)
+        
+        log_node_execution(
+            "EMBEDDINGS_CREATOR", 
+            "SUCCESS", 
+            f"Vector store criado com {len(documents)} documentos"
+        )
+        
+        return {
+            "vector_store": vector_store,
+            "embeddings_created": True,
+            "processing_status": ProcessingStatus.IDLE,  # Pronto para perguntas
+            "error_message": None
+        }
+        
+    except Exception as e:
+        error_msg = f"Erro ao criar embeddings: {str(e)}"
+        log_node_execution("EMBEDDINGS_CREATOR", "ERROR", error_msg)
+        main_logger.exception("Erro detalhado na criação de embeddings:")
+        
+        return {
+            "processing_status": ProcessingStatus.ERROR,
+            "error_message": error_msg,
+            "embeddings_created": False
+        }
+
+
+def create_embeddings_model() -> OpenAIEmbeddings:
+    """
+    Cria e configura o modelo de embeddings OpenAI.
+    
+    Returns:
+        OpenAIEmbeddings: Modelo de embeddings configurado
+    """
+    try:
+        embeddings = OpenAIEmbeddings(
+            openai_api_key=get_openai_api_key(),
+            model="text-embedding-3-small",  # Modelo mais eficiente
+            chunk_size=1000,  # Tamanho do chunk para embeddings
+            max_retries=3,
+            timeout=30
+        )
+        
+        main_logger.debug("Modelo de embeddings OpenAI criado com sucesso")
+        return embeddings
+        
+    except Exception as e:
+        main_logger.error(f"Erro ao criar modelo de embeddings: {e}")
+        raise
+
+
+def create_documents_from_chunks(chunks: List[str]) -> List[Document]:
+    """
+    Converte chunks de texto em objetos Document do LangChain.
+    
+    Args:
+        chunks: Lista de chunks de texto
+    
+    Returns:
+        List[Document]: Lista de documentos LangChain
+    """
+    documents = []
+    
+    for i, chunk in enumerate(chunks):
+        # Cria metadados para cada documento
+        metadata = {
+            "chunk_id": i,
+            "chunk_size": len(chunk),
+            "source": "pdf_upload",
+            "chunk_index": i
+        }
+        
+        # Cria o documento
+        doc = Document(
+            page_content=chunk,
+            metadata=metadata
+        )
+        
+        documents.append(doc)
+    
+    main_logger.debug(f"Criados {len(documents)} documentos a partir dos chunks")
+    return documents
+
+
+def create_vector_store(documents: List[Document], embeddings_model: OpenAIEmbeddings) -> FAISS:
+    """
+    Cria um vector store FAISS a partir dos documentos.
+    
+    Args:
+        documents: Lista de documentos
+        embeddings_model: Modelo de embeddings
+    
+    Returns:
+        FAISS: Vector store criado
+    """
+    try:
+        main_logger.info("Criando vector store FAISS...")
+        
+        # Cria o vector store
+        vector_store = FAISS.from_documents(
+            documents=documents,
+            embedding=embeddings_model
+        )
+        
+        main_logger.info(f"Vector store FAISS criado com {len(documents)} documentos")
+        
+        # Log estatísticas
+        log_vector_store_stats(vector_store, documents)
+        
+        return vector_store
+        
+    except Exception as e:
+        main_logger.error(f"Erro ao criar vector store FAISS: {e}")
+        raise
+
+
+def log_vector_store_stats(vector_store: FAISS, documents: List[Document]):
+    """
+    Registra estatísticas do vector store criado.
+    
+    Args:
+        vector_store: Vector store FAISS
+        documents: Lista de documentos
+    """
+    try:
+        # Estatísticas básicas
+        total_docs = len(documents)
+        total_chars = sum(len(doc.page_content) for doc in documents)
+        avg_doc_size = total_chars / total_docs if total_docs > 0 else 0
+        
+        main_logger.info(f"📊 Estatísticas do Vector Store:")
+        main_logger.info(f"   • Total de documentos: {total_docs}")
+        main_logger.info(f"   • Total de caracteres: {total_chars:,}")
+        main_logger.info(f"   • Tamanho médio por documento: {avg_doc_size:.0f} caracteres")
+        
+        # Testa uma busca simples para verificar funcionamento
+        test_results = vector_store.similarity_search("teste", k=1)
+        main_logger.debug(f"Teste de busca retornou {len(test_results)} resultado(s)")
+        
+    except Exception as e:
+        main_logger.warning(f"Erro ao calcular estatísticas do vector store: {e}")
+
+
+def test_vector_store(vector_store: FAISS, test_query: str = "informação") -> bool:
+    """
+    Testa o funcionamento do vector store.
+    
+    Args:
+        vector_store: Vector store para testar
+        test_query: Query de teste
+    
+    Returns:
+        bool: True se o teste passou
+    """
+    try:
+        # Testa busca por similaridade
+        results = vector_store.similarity_search(test_query, k=3)
+        
+        if not results:
+            main_logger.warning("Vector store não retornou resultados para query de teste")
+            return False
+        
+        # Testa busca com score
+        results_with_score = vector_store.similarity_search_with_score(test_query, k=3)
+        
+        if not results_with_score:
+            main_logger.warning("Vector store não retornou scores para query de teste")
+            return False
+        
+        main_logger.debug(f"Teste do vector store passou: {len(results)} resultados encontrados")
+        return True
+        
+    except Exception as e:
+        main_logger.error(f"Erro no teste do vector store: {e}")
+        return False
+
+
+def optimize_vector_store(vector_store: FAISS) -> FAISS:
+    """
+    Otimiza o vector store para melhor performance.
+    
+    Args:
+        vector_store: Vector store original
+    
+    Returns:
+        FAISS: Vector store otimizado
+    """
+    try:
+        # Para FAISS, podemos otimizar o índice
+        # Isso é especialmente útil para grandes volumes de dados
+        
+        main_logger.debug("Otimizando vector store FAISS...")
+        
+        # O FAISS já é otimizado por padrão para volumes pequenos/médios
+        # Para volumes maiores, poderíamos usar índices mais sofisticados
+        
+        return vector_store
+        
+    except Exception as e:
+        main_logger.warning(f"Erro na otimização do vector store: {e}")
+        return vector_store  # Retorna o original se a otimização falhar
+
+
+def get_vector_store_info(vector_store: FAISS) -> Dict[str, Any]:
+    """
+    Obtém informações sobre o vector store.
+    
+    Args:
+        vector_store: Vector store FAISS
+    
+    Returns:
+        Dict[str, Any]: Informações do vector store
+    """
+    try:
+        # Informações básicas do FAISS
+        index = vector_store.index
+        
+        return {
+            "total_vectors": index.ntotal,
+            "vector_dimension": index.d,
+            "index_type": type(index).__name__,
+            "is_trained": index.is_trained if hasattr(index, 'is_trained') else True
+        }
+        
+    except Exception as e:
+        main_logger.warning(f"Erro ao obter informações do vector store: {e}")
+        return {
+            "total_vectors": 0,
+            "vector_dimension": 0,
+            "index_type": "unknown",
+            "is_trained": False
+        }

nodes/llm_agent.py

@@ -0,0 +1,322 @@
+"""
+Nó do agente LLM para o AgentPDF.
+
+Este nó é responsável por gerar respostas inteligentes usando GPT-4o-mini
+baseadas no contexto recuperado do PDF e na pergunta do usuário.
+"""
+
+from typing import Dict, Any
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import AIMessage, SystemMessage, HumanMessage
+from langchain_core.runnables import RunnableConfig
+from langchain_core.prompts import ChatPromptTemplate
+
+from agents.state import PDFState, ProcessingStatus
+from utils.config import Config, get_openai_api_key
+from utils.logger import log_node_execution, main_logger
+
+
+def llm_agent_node(state: PDFState, config: RunnableConfig) -> Dict[str, Any]:
+    """
+    Nó responsável por gerar respostas usando o LLM.
+    
+    Este nó:
+    1. Recebe a pergunta e o contexto recuperado
+    2. Constrói um prompt otimizado
+    3. Chama o GPT-4o-mini para gerar a resposta
+    4. Processa e valida a resposta
+    5. Atualiza o estado com a resposta final
+    
+    Args:
+        state: Estado atual do grafo
+        config: Configuração do LangGraph
+    
+    Returns:
+        Dict[str, Any]: Atualizações para o estado
+    """
+    log_node_execution("LLM_AGENT", "START", "Iniciando geração de resposta")
+    
+    try:
+        # Verifica se há pergunta e contexto
+        user_question = state.get("user_question")
+        retrieved_context = state.get("retrieved_context", [])
+        
+        if not user_question:
+            error_msg = "Pergunta do usuário não encontrada"
+            log_node_execution("LLM_AGENT", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        # Verifica API key
+        api_key = get_openai_api_key()
+        if not api_key:
+            error_msg = "Chave da API OpenAI não configurada"
+            log_node_execution("LLM_AGENT", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        log_node_execution(
+            "LLM_AGENT", 
+            "PROCESSING", 
+            f"Gerando resposta para: '{user_question[:100]}...'"
+        )
+        
+        # Cria o modelo LLM
+        llm = create_llm_model()
+        
+        # Constrói o prompt
+        prompt = build_prompt(user_question, retrieved_context)
+        
+        # Gera a resposta
+        response = generate_response(llm, prompt)
+        
+        # Processa a resposta
+        final_answer = process_response(response, user_question)
+        
+        # Cria mensagem de resposta
+        ai_message = AIMessage(content=final_answer)
+        
+        log_node_execution(
+            "LLM_AGENT", 
+            "SUCCESS", 
+            f"Resposta gerada: {len(final_answer)} caracteres"
+        )
+        
+        return {
+            "final_answer": final_answer,
+            "messages": [ai_message],
+            "processing_status": ProcessingStatus.COMPLETED,
+            "error_message": None
+        }
+        
+    except Exception as e:
+        error_msg = f"Erro na geração de resposta: {str(e)}"
+        log_node_execution("LLM_AGENT", "ERROR", error_msg)
+        main_logger.exception("Erro detalhado na geração de resposta:")
+        
+        return {
+            "processing_status": ProcessingStatus.ERROR,
+            "error_message": error_msg
+        }
+
+
+def create_llm_model() -> ChatOpenAI:
+    """
+    Cria e configura o modelo LLM GPT-4o-mini.
+    
+    Returns:
+        ChatOpenAI: Modelo LLM configurado
+    """
+    model_config = Config.get_model_config()
+    
+    llm = ChatOpenAI(
+        openai_api_key=get_openai_api_key(),
+        model_name=model_config["model"],
+        temperature=model_config["temperature"],
+        max_tokens=model_config["max_tokens"],
+        timeout=60,
+        max_retries=3
+    )
+    
+    main_logger.debug(f"Modelo LLM criado: {model_config['model']}")
+    return llm
+
+
+def build_prompt(question: str, context_chunks: list) -> ChatPromptTemplate:
+    """
+    Constrói um prompt otimizado para o LLM.
+    
+    Args:
+        question: Pergunta do usuário
+        context_chunks: Lista de chunks de contexto
+    
+    Returns:
+        ChatPromptTemplate: Prompt construído
+    """
+    # Combina o contexto
+    context_text = "\n\n".join(context_chunks) if context_chunks else ""
+    
+    # Sistema de prompt em português
+    system_prompt = """Você é um assistente especializado em análise de documentos PDF. Sua função é responder perguntas baseadas exclusivamente no conteúdo fornecido.
+
+INSTRUÇÕES IMPORTANTES:
+1. Use APENAS as informações do contexto fornecido para responder
+2. Se a informação não estiver no contexto, diga claramente que não encontrou a informação no documento
+3. Seja preciso, claro e objetivo em suas respostas
+4. Cite trechos relevantes do documento quando apropriado
+5. Mantenha um tom profissional e educativo
+6. Se a pergunta for ambígua, peça esclarecimentos
+7. Organize sua resposta de forma estruturada quando necessário
+
+FORMATO DA RESPOSTA:
+- Responda diretamente à pergunta
+- Use parágrafos para organizar ideias complexas
+- Inclua citações do documento quando relevante
+- Termine com um resumo se a resposta for longa"""
+
+    # Template do prompt
+    prompt_template = ChatPromptTemplate.from_messages([
+        ("system", system_prompt),
+        ("human", """CONTEXTO DO DOCUMENTO:
+{context}
+
+PERGUNTA DO USUÁRIO:
+{question}
+
+Por favor, responda à pergunta baseando-se exclusivamente no contexto fornecido.""")
+    ])
+    
+    return prompt_template.partial(context=context_text, question=question)
+
+
+def generate_response(llm: ChatOpenAI, prompt: ChatPromptTemplate) -> str:
+    """
+    Gera a resposta usando o LLM.
+    
+    Args:
+        llm: Modelo LLM
+        prompt: Prompt construído
+    
+    Returns:
+        str: Resposta gerada
+    """
+    try:
+        # Cria a chain
+        chain = prompt | llm
+        
+        # Gera a resposta
+        response = chain.invoke({})
+        
+        # Extrai o conteúdo da resposta
+        if hasattr(response, 'content'):
+            return response.content
+        else:
+            return str(response)
+            
+    except Exception as e:
+        main_logger.error(f"Erro na geração da resposta: {e}")
+        raise
+
+
+def process_response(response: str, original_question: str) -> str:
+    """
+    Processa e valida a resposta gerada.
+    
+    Args:
+        response: Resposta bruta do LLM
+        original_question: Pergunta original do usuário
+    
+    Returns:
+        str: Resposta processada e validada
+    """
+    if not response or not response.strip():
+        return "Desculpe, não consegui gerar uma resposta adequada para sua pergunta."
+    
+    # Limpa a resposta
+    cleaned_response = response.strip()
+    
+    # Valida se a resposta é adequada
+    if len(cleaned_response) < 20:
+        return f"Resposta muito curta gerada. Pergunta original: {original_question}\n\nResposta: {cleaned_response}"
+    
+    # Adiciona informações contextuais se necessário
+    if "não encontrei" in cleaned_response.lower() or "não há informação" in cleaned_response.lower():
+        cleaned_response += "\n\n💡 **Dica**: Tente reformular sua pergunta ou verificar se o PDF contém a informação desejada."
+    
+    return cleaned_response
+
+
+def create_fallback_response(question: str, error_msg: str = None) -> str:
+    """
+    Cria uma resposta de fallback quando há erro.
+    
+    Args:
+        question: Pergunta original
+        error_msg: Mensagem de erro opcional
+    
+    Returns:
+        str: Resposta de fallback
+    """
+    base_response = f"""Desculpe, encontrei dificuldades para processar sua pergunta: "{question}"
+
+Isso pode ter acontecido por alguns motivos:
+1. O documento PDF pode não conter informações relacionadas à sua pergunta
+2. Pode haver um problema temporário com o processamento
+3. A pergunta pode precisar ser mais específica
+
+**Sugestões:**
+- Tente reformular sua pergunta de forma mais específica
+- Verifique se o PDF foi carregado corretamente
+- Certifique-se de que o documento contém a informação desejada"""
+
+    if error_msg:
+        base_response += f"\n\n**Detalhes técnicos:** {error_msg}"
+    
+    return base_response
+
+
+def validate_response_quality(response: str, question: str) -> tuple[bool, str]:
+    """
+    Valida a qualidade da resposta gerada.
+    
+    Args:
+        response: Resposta gerada
+        question: Pergunta original
+    
+    Returns:
+        tuple[bool, str]: (é_válida, motivo_se_inválida)
+    """
+    if not response or len(response.strip()) < 10:
+        return False, "Resposta muito curta ou vazia"
+    
+    # Verifica se a resposta é apenas uma repetição da pergunta
+    if question.lower() in response.lower() and len(response) < len(question) * 2:
+        return False, "Resposta parece ser apenas repetição da pergunta"
+    
+    # Verifica se há conteúdo substantivo
+    words = response.split()
+    if len(words) < 5:
+        return False, "Resposta com muito poucas palavras"
+    
+    # Verifica padrões de resposta inadequada
+    inadequate_patterns = [
+        "não posso responder",
+        "não tenho informação",
+        "desculpe, mas não",
+        "não é possível"
+    ]
+    
+    response_lower = response.lower()
+    inadequate_count = sum(1 for pattern in inadequate_patterns if pattern in response_lower)
+    
+    if inadequate_count > 1:
+        return False, "Resposta contém muitos padrões de inadequação"
+    
+    return True, "Resposta válida"
+
+
+def enhance_response_with_metadata(response: str, context_used: bool, num_sources: int) -> str:
+    """
+    Melhora a resposta adicionando metadados úteis.
+    
+    Args:
+        response: Resposta original
+        context_used: Se contexto foi usado
+        num_sources: Número de fontes consultadas
+    
+    Returns:
+        str: Resposta melhorada
+    """
+    enhanced_response = response
+    
+    # Adiciona informação sobre as fontes
+    if context_used and num_sources > 0:
+        enhanced_response += f"\n\n---\n📚 *Resposta baseada em {num_sources} seção(ões) do documento.*"
+    elif not context_used:
+        enhanced_response += "\n\n---\n⚠️ *Resposta gerada sem contexto específico do documento.*"
+    
+    return enhanced_response

nodes/pdf_loader.py

@@ -0,0 +1,199 @@
+"""
+Nó de carregamento de PDF para o AgentPDF.
+
+Este nó é responsável por carregar e extrair texto de arquivos PDF
+usando PyPDF2 e preparar o conteúdo para processamento posterior.
+"""
+
+import os
+from typing import Dict, Any
+from PyPDF2 import PdfReader
+from langchain_core.runnables import RunnableConfig
+
+from agents.state import PDFState, ProcessingStatus
+from utils.logger import log_node_execution, main_logger
+
+
+def load_pdf_node(state: PDFState, config: RunnableConfig) -> Dict[str, Any]:
+    """
+    Nó responsável por carregar e extrair texto de arquivos PDF.
+    
+    Este nó:
+    1. Verifica se o caminho do PDF é válido
+    2. Carrega o PDF usando PyPDF2
+    3. Extrai todo o texto do documento
+    4. Atualiza o estado com o texto extraído
+    
+    Args:
+        state: Estado atual do grafo contendo informações do PDF
+        config: Configuração do LangGraph
+    
+    Returns:
+        Dict[str, Any]: Atualizações para o estado
+    """
+    log_node_execution("PDF_LOADER", "START", "Iniciando carregamento do PDF")
+    
+    try:
+        # Verifica se o caminho do PDF foi fornecido
+        pdf_path = state.get("pdf_path")
+        if not pdf_path:
+            error_msg = "Caminho do PDF não fornecido"
+            log_node_execution("PDF_LOADER", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        # Verifica se o arquivo existe
+        if not os.path.exists(pdf_path):
+            error_msg = f"Arquivo PDF não encontrado: {pdf_path}"
+            log_node_execution("PDF_LOADER", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        # Atualiza status para carregamento
+        log_node_execution("PDF_LOADER", "PROCESSING", f"Carregando PDF: {pdf_path}")
+        
+        # Carrega e extrai texto do PDF
+        extracted_text = extract_text_from_pdf(pdf_path)
+        
+        if not extracted_text.strip():
+            error_msg = "Nenhum texto foi extraído do PDF"
+            log_node_execution("PDF_LOADER", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        # Sucesso - retorna texto extraído
+        log_node_execution(
+            "PDF_LOADER", 
+            "SUCCESS", 
+            f"Texto extraído com sucesso. Tamanho: {len(extracted_text)} caracteres"
+        )
+        
+        return {
+            "pdf_text": extracted_text,
+            "processing_status": ProcessingStatus.PROCESSING_TEXT,
+            "error_message": None
+        }
+        
+    except Exception as e:
+        error_msg = f"Erro ao carregar PDF: {str(e)}"
+        log_node_execution("PDF_LOADER", "ERROR", error_msg)
+        main_logger.exception("Erro detalhado no carregamento do PDF:")
+        
+        return {
+            "processing_status": ProcessingStatus.ERROR,
+            "error_message": error_msg
+        }
+
+
+def extract_text_from_pdf(pdf_path: str) -> str:
+    """
+    Extrai texto de um arquivo PDF usando PyPDF2.
+    
+    Args:
+        pdf_path: Caminho para o arquivo PDF
+    
+    Returns:
+        str: Texto extraído do PDF
+    
+    Raises:
+        Exception: Se houver erro na leitura do PDF
+    """
+    try:
+        text_content = []
+        
+        # Abre e lê o PDF
+        with open(pdf_path, 'rb') as file:
+            pdf_reader = PdfReader(file)
+            
+            # Extrai texto de cada página
+            for page_num, page in enumerate(pdf_reader.pages):
+                try:
+                    page_text = page.extract_text()
+                    if page_text.strip():  # Só adiciona se a página tem texto
+                        text_content.append(page_text)
+                        main_logger.debug(f"Texto extraído da página {page_num + 1}")
+                except Exception as e:
+                    main_logger.warning(f"Erro ao extrair texto da página {page_num + 1}: {e}")
+                    continue
+        
+        # Junta todo o texto
+        full_text = "\n\n".join(text_content)
+        
+        # Limpa o texto (remove espaços extras, quebras de linha desnecessárias)
+        cleaned_text = clean_extracted_text(full_text)
+        
+        main_logger.info(f"PDF processado: {len(pdf_reader.pages)} páginas, {len(cleaned_text)} caracteres")
+        
+        return cleaned_text
+        
+    except Exception as e:
+        main_logger.error(f"Erro ao extrair texto do PDF {pdf_path}: {e}")
+        raise
+
+
+def clean_extracted_text(text: str) -> str:
+    """
+    Limpa e normaliza o texto extraído do PDF.
+    
+    Args:
+        text: Texto bruto extraído do PDF
+    
+    Returns:
+        str: Texto limpo e normalizado
+    """
+    if not text:
+        return ""
+    
+    # Remove quebras de linha excessivas
+    text = text.replace('\n\n\n', '\n\n')
+    
+    # Remove espaços extras
+    lines = []
+    for line in text.split('\n'):
+        cleaned_line = ' '.join(line.split())  # Remove espaços extras
+        if cleaned_line:  # Só adiciona linhas não vazias
+            lines.append(cleaned_line)
+    
+    # Junta as linhas limpas
+    cleaned_text = '\n'.join(lines)
+    
+    return cleaned_text
+
+
+def validate_pdf_file(pdf_path: str) -> tuple[bool, str]:
+    """
+    Valida se um arquivo PDF é válido e pode ser processado.
+    
+    Args:
+        pdf_path: Caminho para o arquivo PDF
+    
+    Returns:
+        tuple[bool, str]: (é_válido, mensagem_de_erro)
+    """
+    try:
+        # Verifica se o arquivo existe
+        if not os.path.exists(pdf_path):
+            return False, f"Arquivo não encontrado: {pdf_path}"
+        
+        # Verifica se é um arquivo PDF
+        if not pdf_path.lower().endswith('.pdf'):
+            return False, "Arquivo deve ter extensão .pdf"
+        
+        # Tenta abrir o PDF para verificar se é válido
+        with open(pdf_path, 'rb') as file:
+            pdf_reader = PdfReader(file)
+            
+            # Verifica se tem pelo menos uma página
+            if len(pdf_reader.pages) == 0:
+                return False, "PDF não contém páginas"
+        
+        return True, "PDF válido"
+        
+    except Exception as e:
+        return False, f"Erro ao validar PDF: {str(e)}"

nodes/text_processor.py

@@ -0,0 +1,304 @@
+"""
+Nó de processamento de texto para o AgentPDF.
+
+Este nó é responsável por dividir o texto extraído do PDF em chunks
+menores usando RecursiveCharacterTextSplitter para otimizar a recuperação.
+"""
+
+from typing import Dict, Any, List
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_core.runnables import RunnableConfig
+
+from agents.state import PDFState, ProcessingStatus
+from utils.config import Config
+from utils.logger import log_node_execution, main_logger
+
+
+def text_processing_node(state: PDFState, config: RunnableConfig) -> Dict[str, Any]:
+    """
+    Nó responsável por processar e dividir o texto em chunks.
+    
+    Este nó:
+    1. Recebe o texto extraído do PDF
+    2. Divide o texto em chunks usando RecursiveCharacterTextSplitter
+    3. Otimiza os chunks para melhor recuperação
+    4. Atualiza o estado com os chunks processados
+    
+    Args:
+        state: Estado atual do grafo contendo o texto do PDF
+        config: Configuração do LangGraph
+    
+    Returns:
+        Dict[str, Any]: Atualizações para o estado
+    """
+    log_node_execution("TEXT_PROCESSOR", "START", "Iniciando processamento de texto")
+    
+    try:
+        # Verifica se há texto para processar
+        pdf_text = state.get("pdf_text")
+        if not pdf_text:
+            error_msg = "Nenhum texto encontrado para processar"
+            log_node_execution("TEXT_PROCESSOR", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        log_node_execution(
+            "TEXT_PROCESSOR", 
+            "PROCESSING", 
+            f"Processando texto de {len(pdf_text)} caracteres"
+        )
+        
+        # Configura o text splitter
+        text_splitter = create_text_splitter()
+        
+        # Divide o texto em chunks
+        chunks = text_splitter.split_text(pdf_text)
+        
+        if not chunks:
+            error_msg = "Nenhum chunk foi gerado do texto"
+            log_node_execution("TEXT_PROCESSOR", "ERROR", error_msg)
+            return {
+                "processing_status": ProcessingStatus.ERROR,
+                "error_message": error_msg
+            }
+        
+        # Processa e otimiza os chunks
+        processed_chunks = process_chunks(chunks)
+        
+        log_node_execution(
+            "TEXT_PROCESSOR", 
+            "SUCCESS", 
+            f"Texto dividido em {len(processed_chunks)} chunks"
+        )
+        
+        return {
+            "pdf_chunks": processed_chunks,
+            "processing_status": ProcessingStatus.CREATING_EMBEDDINGS,
+            "error_message": None
+        }
+        
+    except Exception as e:
+        error_msg = f"Erro ao processar texto: {str(e)}"
+        log_node_execution("TEXT_PROCESSOR", "ERROR", error_msg)
+        main_logger.exception("Erro detalhado no processamento de texto:")
+        
+        return {
+            "processing_status": ProcessingStatus.ERROR,
+            "error_message": error_msg
+        }
+
+
+def create_text_splitter() -> RecursiveCharacterTextSplitter:
+    """
+    Cria e configura o RecursiveCharacterTextSplitter.
+    
+    Returns:
+        RecursiveCharacterTextSplitter: Splitter configurado
+    """
+    # Obtém configurações
+    config = Config.get_text_splitter_config()
+    
+    # Separadores hierárquicos para melhor divisão
+    separators = [
+        "\n\n",  # Parágrafos
+        "\n",    # Quebras de linha
+        ". ",    # Frases
+        "! ",    # Exclamações
+        "? ",    # Perguntas
+        "; ",    # Ponto e vírgula
+        ", ",    # Vírgulas
+        " ",     # Espaços
+        ""       # Caracteres individuais
+    ]
+    
+    text_splitter = RecursiveCharacterTextSplitter(
+        chunk_size=config["chunk_size"],
+        chunk_overlap=config["chunk_overlap"],
+        separators=separators,
+        length_function=len,
+        is_separator_regex=False,
+    )
+    
+    main_logger.debug(f"Text splitter configurado: chunk_size={config['chunk_size']}, overlap={config['chunk_overlap']}")
+    
+    return text_splitter
+
+
+def process_chunks(chunks: List[str]) -> List[str]:
+    """
+    Processa e otimiza os chunks de texto.
+    
+    Args:
+        chunks: Lista de chunks brutos
+    
+    Returns:
+        List[str]: Lista de chunks processados e otimizados
+    """
+    processed_chunks = []
+    
+    for i, chunk in enumerate(chunks):
+        # Limpa o chunk
+        cleaned_chunk = clean_chunk(chunk)
+        
+        # Só adiciona chunks com conteúdo significativo
+        if is_meaningful_chunk(cleaned_chunk):
+            processed_chunks.append(cleaned_chunk)
+            main_logger.debug(f"Chunk {i+1} processado: {len(cleaned_chunk)} caracteres")
+        else:
+            main_logger.debug(f"Chunk {i+1} descartado por falta de conteúdo significativo")
+    
+    # Log estatísticas
+    main_logger.info(f"Chunks processados: {len(processed_chunks)} de {len(chunks)} originais")
+    
+    if processed_chunks:
+        avg_length = sum(len(chunk) for chunk in processed_chunks) / len(processed_chunks)
+        main_logger.info(f"Tamanho médio dos chunks: {avg_length:.0f} caracteres")
+    
+    return processed_chunks
+
+
+def clean_chunk(chunk: str) -> str:
+    """
+    Limpa e normaliza um chunk de texto.
+    
+    Args:
+        chunk: Chunk bruto
+    
+    Returns:
+        str: Chunk limpo
+    """
+    if not chunk:
+        return ""
+    
+    # Remove espaços extras no início e fim
+    chunk = chunk.strip()
+    
+    # Normaliza quebras de linha
+    chunk = chunk.replace('\r\n', '\n').replace('\r', '\n')
+    
+    # Remove quebras de linha excessivas
+    while '\n\n\n' in chunk:
+        chunk = chunk.replace('\n\n\n', '\n\n')
+    
+    # Remove espaços extras entre palavras
+    lines = []
+    for line in chunk.split('\n'):
+        cleaned_line = ' '.join(line.split())
+        if cleaned_line:
+            lines.append(cleaned_line)
+    
+    return '\n'.join(lines)
+
+
+def is_meaningful_chunk(chunk: str) -> bool:
+    """
+    Verifica se um chunk contém conteúdo significativo.
+    
+    Args:
+        chunk: Chunk para verificar
+    
+    Returns:
+        bool: True se o chunk é significativo
+    """
+    if not chunk or len(chunk.strip()) < 50:  # Muito pequeno
+        return False
+    
+    # Conta palavras
+    words = chunk.split()
+    if len(words) < 10:  # Muito poucas palavras
+        return False
+    
+    # Verifica se não é só números ou caracteres especiais
+    alpha_chars = sum(1 for c in chunk if c.isalpha())
+    if alpha_chars < len(chunk) * 0.5:  # Menos de 50% são letras
+        return False
+    
+    return True
+
+
+def get_chunk_statistics(chunks: List[str]) -> Dict[str, Any]:
+    """
+    Calcula estatísticas dos chunks processados.
+    
+    Args:
+        chunks: Lista de chunks
+    
+    Returns:
+        Dict[str, Any]: Estatísticas dos chunks
+    """
+    if not chunks:
+        return {
+            "total_chunks": 0,
+            "total_characters": 0,
+            "average_length": 0,
+            "min_length": 0,
+            "max_length": 0
+        }
+    
+    lengths = [len(chunk) for chunk in chunks]
+    
+    return {
+        "total_chunks": len(chunks),
+        "total_characters": sum(lengths),
+        "average_length": sum(lengths) / len(lengths),
+        "min_length": min(lengths),
+        "max_length": max(lengths)
+    }
+
+
+def optimize_chunks_for_retrieval(chunks: List[str]) -> List[str]:
+    """
+    Otimiza chunks para melhor performance na recuperação.
+    
+    Args:
+        chunks: Lista de chunks originais
+    
+    Returns:
+        List[str]: Lista de chunks otimizados
+    """
+    optimized = []
+    
+    for chunk in chunks:
+        # Adiciona contexto se necessário
+        if len(chunk) < 200:  # Chunks muito pequenos
+            # Tenta combinar com o próximo chunk se possível
+            continue
+        
+        # Garante que chunks importantes sejam preservados
+        if contains_important_content(chunk):
+            optimized.append(chunk)
+    
+    return optimized if optimized else chunks  # Fallback para chunks originais
+
+
+def contains_important_content(chunk: str) -> bool:
+    """
+    Verifica se um chunk contém conteúdo importante.
+    
+    Args:
+        chunk: Chunk para verificar
+    
+    Returns:
+        bool: True se contém conteúdo importante
+    """
+    # Palavras-chave que indicam conteúdo importante
+    important_keywords = [
+        'definição', 'conceito', 'importante', 'fundamental',
+        'princípio', 'regra', 'lei', 'teoria', 'método',
+        'processo', 'procedimento', 'resultado', 'conclusão'
+    ]
+    
+    chunk_lower = chunk.lower()
+    
+    # Verifica presença de palavras-chave importantes
+    for keyword in important_keywords:
+        if keyword in chunk_lower:
+            return True
+    
+    # Verifica se contém listas ou enumerações
+    if any(marker in chunk for marker in ['1.', '2.', '•', '-', 'a)', 'b)']):
+        return True
+    
+    return True  # Por padrão, considera importante

requirements.txt

@@ -0,0 +1,12 @@
+langchain==0.3.12
+langchain-community==0.3.12
+langchain-core==0.3.26
+langchain-openai==0.2.14
+langgraph==0.2.60
+gradio==5.9.1
+pypdf2==3.0.1
+faiss-cpu==1.9.0
+python-dotenv==1.0.1
+pydantic==2.10.4
+typing-extensions==4.12.2
+openai==1.58.1

tests/test_basic.py

@@ -0,0 +1,129 @@
+"""
+Testes básicos para o AgentPDF.
+
+Este módulo contém testes unitários básicos para verificar
+o funcionamento dos componentes principais.
+"""
+
+import unittest
+import os
+import sys
+from pathlib import Path
+
+# Adiciona o diretório raiz ao path
+root_dir = Path(__file__).parent.parent
+sys.path.insert(0, str(root_dir))
+
+from utils.config import Config
+from utils.logger import setup_logger
+from agents.state import PDFState, ProcessingStatus
+
+
+class TestConfig(unittest.TestCase):
+    """Testes para a configuração."""
+    
+    def test_config_attributes(self):
+        """Testa se os atributos de configuração existem."""
+        self.assertTrue(hasattr(Config, 'DEFAULT_MODEL'))
+        self.assertTrue(hasattr(Config, 'CHUNK_SIZE'))
+        self.assertTrue(hasattr(Config, 'TOP_K_DOCUMENTS'))
+        
+    def test_model_config(self):
+        """Testa a configuração do modelo."""
+        model_config = Config.get_model_config()
+        self.assertIn('model', model_config)
+        self.assertIn('temperature', model_config)
+        self.assertIn('max_tokens', model_config)
+        
+    def test_text_splitter_config(self):
+        """Testa a configuração do text splitter."""
+        splitter_config = Config.get_text_splitter_config()
+        self.assertIn('chunk_size', splitter_config)
+        self.assertIn('chunk_overlap', splitter_config)
+
+
+class TestState(unittest.TestCase):
+    """Testes para as estruturas de estado."""
+    
+    def test_processing_status(self):
+        """Testa os status de processamento."""
+        self.assertEqual(ProcessingStatus.IDLE, "idle")
+        self.assertEqual(ProcessingStatus.LOADING_PDF, "loading_pdf")
+        self.assertEqual(ProcessingStatus.ERROR, "error")
+        
+    def test_pdf_state_structure(self):
+        """Testa a estrutura do PDFState."""
+        # Verifica se PDFState é um TypedDict válido
+        self.assertTrue(hasattr(PDFState, '__annotations__'))
+        
+        # Verifica se tem os campos essenciais
+        annotations = PDFState.__annotations__
+        self.assertIn('messages', annotations)
+        self.assertIn('pdf_path', annotations)
+        self.assertIn('processing_status', annotations)
+
+
+class TestLogger(unittest.TestCase):
+    """Testes para o sistema de logging."""
+    
+    def test_logger_creation(self):
+        """Testa a criação do logger."""
+        logger = setup_logger("test", "INFO")
+        self.assertIsNotNone(logger)
+        self.assertEqual(logger.name, "test")
+
+
+class TestDirectories(unittest.TestCase):
+    """Testes para estrutura de diretórios."""
+    
+    def test_required_directories_exist(self):
+        """Testa se os diretórios necessários existem."""
+        required_dirs = [
+            'agents',
+            'nodes', 
+            'utils',
+            'gradio',
+            'uploaded_data'
+        ]
+        
+        for dir_name in required_dirs:
+            self.assertTrue(
+                os.path.exists(dir_name), 
+                f"Diretório {dir_name} não encontrado"
+            )
+
+
+class TestImports(unittest.TestCase):
+    """Testa se todos os módulos podem ser importados."""
+    
+    def test_import_config(self):
+        """Testa importação do módulo config."""
+        try:
+            from utils.config import Config
+            self.assertTrue(True)
+        except ImportError as e:
+            self.fail(f"Erro ao importar config: {e}")
+    
+    def test_import_state(self):
+        """Testa importação do módulo state."""
+        try:
+            from agents.state import PDFState
+            self.assertTrue(True)
+        except ImportError as e:
+            self.fail(f"Erro ao importar state: {e}")
+    
+    def test_import_main_graph(self):
+        """Testa importação do grafo principal."""
+        try:
+            from main_graph import AgentPDFGraph
+            self.assertTrue(True)
+        except ImportError as e:
+            self.fail(f"Erro ao importar main_graph: {e}")
+
+
+if __name__ == '__main__':
+    # Configura logging para testes
+    setup_logger("AgentPDF.Tests", "WARNING")
+    
+    # Executa os testes
+    unittest.main(verbosity=2)

utils/__init__.py

@@ -0,0 +1 @@
+# Módulo de utilitários

utils/config.py

@@ -0,0 +1,120 @@
+"""
+Configurações e utilitários para o AgentPDF.
+
+Este módulo contém configurações globais, carregamento de variáveis
+de ambiente e funções utilitárias para o projeto.
+"""
+
+import os
+from dotenv import load_dotenv
+from typing import Optional
+
+# Carrega variáveis de ambiente
+load_dotenv()
+
+
+class Config:
+    """Classe de configuração centralizada."""
+    
+    # API Keys
+    OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "")
+    LANGCHAIN_API_KEY: str = os.getenv("LANGCHAIN_API_KEY", "")
+    
+    # Configurações do LangChain
+    LANGCHAIN_TRACING_V2: bool = os.getenv("LANGCHAIN_TRACING_V2", "false").lower() == "true"
+    LANGCHAIN_PROJECT: str = os.getenv("LANGCHAIN_PROJECT", "agentpdf")
+    
+    # Configurações do modelo
+    DEFAULT_MODEL: str = "gpt-4o-mini"
+    DEFAULT_TEMPERATURE: float = 0.1
+    MAX_TOKENS: int = 2000
+    
+    # Configurações de processamento de texto
+    CHUNK_SIZE: int = 1000
+    CHUNK_OVERLAP: int = 200
+    
+    # Configurações de recuperação
+    TOP_K_DOCUMENTS: int = 5
+    SIMILARITY_THRESHOLD: float = 0.7
+    
+    # Configurações da interface
+    GRADIO_PORT: int = 7860
+    GRADIO_SHARE: bool = False
+    
+    # Diretórios
+    UPLOAD_DIR: str = "uploaded_data"
+    TEMP_DIR: str = "temp"
+    
+    @classmethod
+    def validate_config(cls) -> bool:
+        """
+        Valida se as configurações essenciais estão presentes.
+        
+        Returns:
+            bool: True se a configuração é válida, False caso contrário.
+        """
+        if not cls.OPENAI_API_KEY:
+            print("⚠️  AVISO: OPENAI_API_KEY não configurada!")
+            return False
+        return True
+    
+    @classmethod
+    def get_model_config(cls) -> dict:
+        """
+        Retorna configurações do modelo LLM.
+        
+        Returns:
+            dict: Configurações do modelo.
+        """
+        return {
+            "model": cls.DEFAULT_MODEL,
+            "temperature": cls.DEFAULT_TEMPERATURE,
+            "max_tokens": cls.MAX_TOKENS,
+        }
+    
+    @classmethod
+    def get_text_splitter_config(cls) -> dict:
+        """
+        Retorna configurações do divisor de texto.
+        
+        Returns:
+            dict: Configurações do text splitter.
+        """
+        return {
+            "chunk_size": cls.CHUNK_SIZE,
+            "chunk_overlap": cls.CHUNK_OVERLAP,
+        }
+    
+    @classmethod
+    def get_retrieval_config(cls) -> dict:
+        """
+        Retorna configurações de recuperação.
+        
+        Returns:
+            dict: Configurações de recuperação.
+        """
+        return {
+            "k": cls.TOP_K_DOCUMENTS,
+            "score_threshold": cls.SIMILARITY_THRESHOLD,
+        }
+
+
+def ensure_directories():
+    """Garante que os diretórios necessários existam."""
+    directories = [Config.UPLOAD_DIR, Config.TEMP_DIR]
+    for directory in directories:
+        os.makedirs(directory, exist_ok=True)
+
+
+def get_openai_api_key() -> Optional[str]:
+    """
+    Retorna a chave da API OpenAI.
+    
+    Returns:
+        Optional[str]: Chave da API ou None se não configurada.
+    """
+    return Config.OPENAI_API_KEY if Config.OPENAI_API_KEY else None
+
+
+# Inicialização
+ensure_directories()

utils/logger.py

@@ -0,0 +1,125 @@
+"""
+Sistema de logging para o AgentPDF.
+
+Fornece logging estruturado e colorido para melhor debugging
+e monitoramento do sistema.
+"""
+
+import logging
+import sys
+from datetime import datetime
+from typing import Optional
+
+
+class ColoredFormatter(logging.Formatter):
+    """Formatter personalizado com cores para diferentes níveis de log."""
+    
+    # Códigos de cores ANSI
+    COLORS = {
+        'DEBUG': '\033[36m',    # Ciano
+        'INFO': '\033[32m',     # Verde
+        'WARNING': '\033[33m',  # Amarelo
+        'ERROR': '\033[31m',    # Vermelho
+        'CRITICAL': '\033[35m', # Magenta
+        'RESET': '\033[0m'      # Reset
+    }
+    
+    def format(self, record):
+        # Adiciona cor baseada no nível
+        color = self.COLORS.get(record.levelname, self.COLORS['RESET'])
+        reset = self.COLORS['RESET']
+        
+        # Formato personalizado
+        record.levelname = f"{color}{record.levelname}{reset}"
+        
+        return super().format(record)
+
+
+def setup_logger(name: str = "AgentPDF", level: str = "INFO") -> logging.Logger:
+    """
+    Configura e retorna um logger personalizado.
+    
+    Args:
+        name: Nome do logger
+        level: Nível de logging (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+    
+    Returns:
+        logging.Logger: Logger configurado
+    """
+    logger = logging.getLogger(name)
+    
+    # Evita duplicação de handlers
+    if logger.handlers:
+        return logger
+    
+    # Configura nível
+    numeric_level = getattr(logging, level.upper(), logging.INFO)
+    logger.setLevel(numeric_level)
+    
+    # Handler para console
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(numeric_level)
+    
+    # Formatter com cores
+    formatter = ColoredFormatter(
+        '%(asctime)s | %(levelname)s | %(name)s | %(message)s',
+        datefmt='%H:%M:%S'
+    )
+    console_handler.setFormatter(formatter)
+    
+    logger.addHandler(console_handler)
+    
+    return logger
+
+
+def log_node_execution(node_name: str, status: str, details: Optional[str] = None):
+    """
+    Log específico para execução de nós do LangGraph.
+    
+    Args:
+        node_name: Nome do nó
+        status: Status da execução (START, SUCCESS, ERROR)
+        details: Detalhes adicionais
+    """
+    logger = logging.getLogger("AgentPDF.Nodes")
+    
+    emoji_map = {
+        "START": "🚀",
+        "SUCCESS": "✅",
+        "ERROR": "❌",
+        "PROCESSING": "⚙️"
+    }
+    
+    emoji = emoji_map.get(status, "📝")
+    message = f"{emoji} {node_name} - {status}"
+    
+    if details:
+        message += f" | {details}"
+    
+    if status == "ERROR":
+        logger.error(message)
+    elif status == "START" or status == "PROCESSING":
+        logger.info(message)
+    else:
+        logger.info(message)
+
+
+def log_graph_execution(action: str, details: Optional[str] = None):
+    """
+    Log específico para execução do grafo principal.
+    
+    Args:
+        action: Ação sendo executada
+        details: Detalhes adicionais
+    """
+    logger = logging.getLogger("AgentPDF.Graph")
+    
+    message = f"🔄 {action}"
+    if details:
+        message += f" | {details}"
+    
+    logger.info(message)
+
+
+# Logger principal do sistema
+main_logger = setup_logger("AgentPDF", "INFO")