Delete ARCHITECTURE.md

ARCHITECTURE.md

@@ -1,418 +0,0 @@
-# 🏗️ AgentGraph - Arquitetura Técnica Detalhada
-
-## 🎯 Visão Geral
-
-O AgentGraph é uma **plataforma multi-agente** construída com LangGraph, implementando uma arquitetura modular e extensível baseada em nós especializados. O sistema suporta múltiplos provedores LLM (OpenAI, Anthropic, HuggingFace) com processamento assíncrono, gerenciamento inteligente de objetos não-serializáveis e sistema robusto de retry para rate limiting.
-
-### **Principais Inovações Arquiteturais**
-- 🔄 **Fluxo Otimizado**: Detecção → AgentSQL → Refinamento (sem LLM intermediária)
-- 🧠 **Multi-Provedor**: Suporte nativo a OpenAI, Anthropic e HuggingFace
-- 🛠️ **Tool-Calling**: Ferramentas SQL nativas with verbose ativo
-- 🎛️ **Object Manager**: Solução elegante para objetos não-serializáveis
-- ⚡ **Async/Await**: Processamento não-bloqueante em toda a stack
-- 🔍 **LangSmith Integration**: Observabilidade completa com rastreamento automático
-
-## 📁 Estrutura do Projeto
-
-```
-agentgraph/
-├── app.py                     # Entry point: Gradio + LangGraph
-├── graphs/
-│   └── main_graph.py          # StateGraph principal
-├── nodes/                     # Nós especializados
-│   ├── csv_processing_node.py # Processamento genérico de CSV
-│   ├── database_node.py       # Operações de banco de dados
-│   ├── query_node.py          # Processamento de consultas
-│   ├── refinement_node.py     # Refinamento de respostas
-│   ├── cache_node.py          # Gerenciamento de cache
-│   ├── agent_node.py          # Coordenação geral
-│   └── custom_nodes.py        # Nós especializados
-├── agents/
-│   ├── sql_agent.py           # Criação do agente SQL
-│   └── tools.py               # Ferramentas do agente
-├── utils/
-│   ├── database.py            # Funções de banco de dados
-│   ├── config.py              # Configurações
-│   └── object_manager.py      # Gerenciador de objetos não-serializáveis
-├── uploaded_data/             # Arquivos CSV enviados
-├── requirements.txt
-├── README.md
-├── ARCHITECTURE.md
-└── .env
-```
-
-## 🔄 Fluxo do LangGraph
-
-### Fluxo Principal de Consulta
-
-```mermaid
-graph TD
-    A[validate_input] --> B[check_cache]
-    B --> C{Cache Hit?}
-    C -->|Sim| H[update_history]
-    C -->|Não| D[prepare_context]
-    D --> E[get_db_sample]
-    E --> F[process_query]
-    F --> G{Modo Avançado?}
-    G -->|Sim| I[refine_response]
-    G -->|Não| J[cache_response]
-    I --> K[format_response]
-    K --> J
-    J --> H
-    H --> L[END]
-```
-
-### Nós Especializados
-
-#### 1. **csv_processing_node.py**
-- **Função**: Processamento genérico de CSV
-- **Características**:
-  - Detecção automática de separadores (`;`, `,`, `\t`, `|`)
-  - Identificação inteligente de tipos de dados
-  - Conversão robusta para SQL types
-  - Estatísticas de processamento
-
-#### 2. **database_node.py**
-- **Função**: Operações de banco de dados
-- **Características**:
-  - Criação de banco a partir de DataFrame processado
-  - Carregamento de banco existente
-  - Obtenção de amostras de dados
-  - Validação de integridade
-
-#### 3. **query_node.py**
-- **Função**: Processamento de consultas SQL
-- **Características**:
-  - Validação de entrada
-  - Preparação de contexto
-  - Execução via agente SQL
-  - Tratamento de erros
-
-#### 4. **refinement_node.py**
-- **Função**: Refinamento de respostas
-- **Características**:
-  - Modo avançado com LLM adicional
-  - Avaliação de qualidade
-  - Formatação final
-  - Adição de insights
-
-#### 5. **cache_node.py**
-- **Função**: Gerenciamento de cache e histórico
-- **Características**:
-  - Verificação de cache
-  - Armazenamento de respostas
-  - Atualização de histórico
-  - Estatísticas de uso
-
-## 🔍 Integração LangSmith
-
-### **Observabilidade Automática**
-O AgentGraph inclui integração completa com LangSmith para rastreamento e monitoramento:
-
-```python
-# Configuração automática via variáveis de ambiente
-LANGSMITH_TRACING=true
-LANGSMITH_API_KEY=lsv2_pt_...
-LANGSMITH_PROJECT=agentgraph-project
-
-# Rastreamento automático de todo o fluxo LangGraph
-workflow.invoke(state) # ← Automaticamente rastreado
-```
-
-### **Componentes Rastreados**
-- ✅ **Todos os nós LangGraph**: validate_input → process_query → cache_response
-- ✅ **Agentes SQL**: Chamadas LLM com inputs/outputs completos
-- ✅ **Modelos Multi-Provedor**: OpenAI, Anthropic, HuggingFace
-- ✅ **Operações de Dados**: CSV processing, database operations
-- ✅ **Geração de Gráficos**: Seleção e criação de visualizações
-
-### **Benefícios da Integração**
-- 🔍 **Debug Avançado**: Visualize fluxo completo de execução
-- 📊 **Métricas de Performance**: Latência por nó e operação
-- 💰 **Análise de Custos**: Uso de tokens por modelo
-- 🐛 **Troubleshooting**: Identifique gargalos e erros
-- 📈 **Dashboards**: Monitoramento em tempo real
-
-## 🧠 Gerenciador de Objetos
-
-### Problema Resolvido
-O LangGraph requer que o estado seja serializável, mas objetos como SQLAgentManager, Engine e CacheManager não são serializáveis.
-
-### Solução: ObjectManager
-```python
-# Armazena objetos não-serializáveis
-agent_id = object_manager.store_sql_agent(sql_agent)
-engine_id = object_manager.store_engine(engine)
-cache_id = object_manager.store_cache_manager(cache_manager)
-
-# Estado serializável
-state = {
-    "user_input": "query",
-    "agent_id": agent_id,
-    "engine_id": engine_id,
-    "cache_id": cache_id
-}
-
-# Recupera objetos quando necessário
-sql_agent = object_manager.get_sql_agent(agent_id)
-```
-
-## 📊 Processamento CSV Genérico
-
-### Detecção Automática de Tipos
-
-```python
-# Detecta automaticamente:
-- Datas: Tenta conversão com pd.to_datetime()
-- Números inteiros: Verifica padrões numéricos
-- Números decimais: Detecta pontos/vírgulas
-- Texto: Mantém como string
-
-# Regras de processamento:
-- parse_dates: Para colunas de data
-- convert_to_int: Para números inteiros
-- convert_to_float: Para números decimais
-- convert_text_to_int/float: Para texto numérico
-- keep_as_text: Para texto puro
-```
-
-### Separadores Suportados
-- `;` (ponto e vírgula)
-- `,` (vírgula)
-- `\t` (tab)
-- `|` (pipe)
-
-## 🔧 Configurações
-
-### Arquivo .env
-```env
-# API Keys
-HUGGINGFACE_API_KEY=your_key_here
-OPENAI_API_KEY=your_key_here
-ANTHROPIC_API_KEY=your_key_here
-
-# LangSmith - Observabilidade (OPCIONAL)
-LANGSMITH_API_KEY=lsv2_pt_your_key_here
-LANGSMITH_TRACING=true
-LANGSMITH_ENDPOINT=https://api.smith.langchain.com
-LANGSMITH_PROJECT=agentgraph-project
-
-# Database Configuration
-SQL_DB_PATH=data.db
-DEFAULT_CSV_PATH=tabela.csv
-UPLOAD_DIR=uploaded_data
-
-# Model Configuration
-DEFAULT_MODEL=GPT-4o-mini
-MAX_ITERATIONS=40
-TEMPERATURE=0
-
-# Gradio Configuration
-GRADIO_SHARE=False
-GRADIO_PORT=7860
-```
-
-## 🚀 Funcionalidades
-
-### ✅ Mantidas do Código Original
-- Múltiplos modelos LLM (LLaMA 70B, 8B, Qwen 32B)
-- Upload de CSV personalizado
-- Sistema de cache inteligente
-- Modo avançado com refinamento
-- Histórico de conversas
-- Interface Gradio moderna
-- Reset do sistema
-
-### ✅ Novas Funcionalidades
-- Processamento genérico de CSV
-- Arquitetura modular de nós
-- Gerenciamento de objetos não-serializáveis
-- Fluxo condicional otimizado
-- Validação automática de sistema
-- Detecção automática de portas
-- Logs estruturados
-- **Integração LangSmith**: Observabilidade completa e automática
-
-## 🧪 Testes
-
-### Arquivo de Teste
-```bash
-python test_new_architecture.py
-```
-
-Testa individualmente:
-- Processamento CSV
-- Criação de banco
-- Agente SQL
-- Gerenciador de objetos
-- Amostra de dados
-
-## 🔄 Deploy
-
-### Local
-```bash
-python app.py
-```
-
-### HuggingFace Spaces
-1. Configure as variáveis de ambiente
-2. Faça upload dos arquivos
-3. O sistema detectará automaticamente a porta disponível
-
-## 📈 Benefícios da Nova Arquitetura
-
-1. **Escalabilidade**: Fácil adição de novos nós
-2. **Manutenibilidade**: Código organizado e modular
-3. **Robustez**: Sem problemas de serialização
-4. **Flexibilidade**: Processamento genérico de dados
-5. **Performance**: Fluxo otimizado com cache
-6. **Debugging**: Logs detalhados por nó
-7. **Testabilidade**: Nós independentes testáveis
-
-## 🔍 Monitoramento
-
-### Logs Estruturados
-```
-[VALIDATION] - Validação de entrada
-[CACHE] - Operações de cache
-[CONTEXT] - Preparação de contexto
-[DATABASE] - Operações de banco
-[QUERY] - Processamento de consultas
-[REFINE] - Refinamento de respostas
-[HISTORY] - Atualização de histórico
-```
-
-### Estatísticas
-- Tempo de execução por nó
-- Taxa de acerto do cache
-- Estatísticas de processamento CSV
-- Validação de componentes
-
-## 🚀 Roadmap de Expansão
-
-### **🎯 Arquitetura Preparada para Múltiplos Agentes**
-
-A arquitetura atual está **perfeitamente preparada** para expansão com novos agentes especializados:
-
-#### **📄 Agente PDF (Curto Prazo)**
-```python
-# Implementação planejada:
-nodes/pdf_processing_node.py
-agents/pdf_agent.py
-
-# Funcionalidades:
-- Extração de texto (PyPDF2, pdfplumber)
-- OCR para documentos escaneados (Tesseract)
-- Análise de estrutura de documentos
-- Busca semântica em conteúdo
-- Integração com LangGraph existente
-```
-
-#### **🗄️ Agente MySQL (Médio Prazo)**
-```python
-# Implementação planejada:
-nodes/mysql_node.py
-agents/mysql_agent.py
-
-# Funcionalidades:
-- Conexões externas MySQL/PostgreSQL
-- Pool de conexões otimizado
-- Queries complexas com JOINs
-- Transações e rollbacks
-- Múltiplas bases de dados
-```
-
-#### **📊 Agente de Gráficos (Médio Prazo)**
-```python
-# Implementação planejada:
-nodes/chart_generation_node.py
-agents/chart_agent.py
-
-# Funcionalidades:
-- Matplotlib, Plotly, Seaborn
-- Gráficos baseados em consultas SQL
-- Análise automática de dados
-- Exporta��ão em múltiplos formatos
-- Dashboards interativos
-```
-
-#### **🤖 Agente de ML/Previsões (Longo Prazo)**
-```python
-# Implementação planejada:
-nodes/prediction_node.py
-agents/ml_agent.py
-
-# Funcionalidades:
-- Modelos de Machine Learning
-- Análise de séries temporais
-- Previsões automáticas
-- Integração com scikit-learn
-- AutoML capabilities
-```
-
-### **🔄 Sistema de Detecção Expandido**
-
-```python
-def detect_query_type(user_query: str) -> str:
-    """Função já preparada para expansão"""
-
-    query_lower = user_query.lower().strip()
-
-    # Detecção atual
-    if 'sql' in query_lower or 'tabela' in query_lower:
-        return 'sql_query'
-
-    # Expansões futuras (já estruturadas)
-    elif 'pdf' in query_lower or 'documento' in query_lower:
-        return 'pdf_processing'
-    elif 'mysql' in query_lower or 'banco mysql' in query_lower:
-        return 'mysql_query'
-    elif 'gráfico' in query_lower or 'chart' in query_lower:
-        return 'chart_generation'
-    elif 'prever' in query_lower or 'previsão' in query_lower:
-        return 'prediction'
-
-    return 'sql_query'  # Default
-```
-
-### **🎛️ Roteamento Condicional Preparado**
-
-```python
-# No main_graph.py - Estrutura já preparada
-def route_by_type(state: Dict[str, Any]) -> str:
-    query_type = state.get("query_type", "sql_query")
-
-    routing_map = {
-        "sql_query": "sql_processing",
-        "pdf_processing": "pdf_processing",      # FUTURO
-        "mysql_query": "mysql_processing",       # FUTURO
-        "chart_generation": "chart_generation",  # FUTURO
-        "prediction": "prediction_processing"    # FUTURO
-    }
-
-    return routing_map.get(query_type, "sql_processing")
-```
-
-### **📈 Facilidade de Implementação**
-
-**Por que é fácil expandir:**
-- ✅ **Estrutura modular** - Cada agente = novo nó
-- ✅ **ObjectManager flexível** - Gerencia qualquer objeto
-- ✅ **Sistema de detecção** - Já preparado para novos tipos
-- ✅ **Configurações centralizadas** - Fácil adicionar APIs
-- ✅ **Interface dinâmica** - Dropdown automático
-- ✅ **Async/await** - Performance mantida
-- ✅ **Logs estruturados** - Debugging facilitado
-
-### **🎯 Próximos Passos Recomendados**
-
-1. **Agente PDF** - Implementação mais simples e útil
-2. **Sistema de Templates** - Prompts especializados por agente
-3. **Métricas avançadas** - Performance por tipo de agente
-4. **API REST** - Exposição de funcionalidades
-5. **Agente MySQL** - Conexões externas
-6. **Sistema de Pipelines** - Combinação de agentes
-
----
-
-**🏆 Conclusão**: A arquitetura atual é **excepcional** e está perfeitamente preparada para se tornar uma **plataforma completa de agentes especializados**. A expansão será natural e incremental, mantendo a robustez e performance existentes.