Repository navigation
Expand file tree
/
Copy pathINDICE.py
More file actions
157 lines (130 loc) · 8.94 KB
/
Copy pathINDICE.py
File metadata and controls
157 lines (130 loc) · 8.94 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
"""
Índice de Estrutura do Projeto Text-to-Insight
╔════════════════════════════════════════════════════════════════════════════╗
║ PROJETO TEXT-TO-INSIGHT ║
║ Supervisor/Hierarchical Agent com LangGraph + HITL + Métricas ║
║ Autor: Jonas Melo | Versão: 0.2.0 Alpha | Status: Fluxo Ativo ║
╚════════════════════════════════════════════════════════════════════════════╝
ESTRUTURA DE DIRETÓRIOS:
═══════════════════════
TextToInsight/ (Raiz do projeto)
│
├── 📄 README.md ⭐ COMECE AQUI - Documentação Principal
├── 📄 ARQUITETURA.md Detalhamento técnico da arquitetura
├── 📄 DESENVOLVIMENTO.md Guia de setup e desenvolvimento local
│
├── 🔧 pyproject.toml Metadados e dependências do projeto
├── 📋 requirements.txt Dependências pip
├── .gitignore Padrões ignorados pelo git
│
├── 🚀 main.py Script de execução principal
│
├── 📁 text_to_insight/ Código-fonte principal (pacote)
│ ├── __init__.py Package root
│ ├── state.py ⭐ TypedDict EstadoTextToInsight
│ ├── graph.py ⭐ Grafo compilado (entry point)
│ ├── InsightEngine.py API pública da biblioteca
│ ├── model_selection.py Seleção de modelo/provedor LLM
│ ├── runtime.py Runtime compartilhado
│ ├── utils.py Telemetria de tokens e latência
│ │
│ ├── 📁 nodes/ Nós do grafo
│ │ ├── __init__.py
│ │ ├── planner.py 🧠 Nó: Planejador (Supervisor)
│ │ ├── schema.py 📊 Nó: Extrator de Schema
│ │ ├── 📁 code_agent/
│ │ │ ├── code_agent.py 💻 Nó: Gerador de SQL
│ │ │ └── code_sql.py 🔐 Validação + Execução SQL segura
│ │ ├── sandbox.py 🏖️ Nó: Executor Seguro
│ │ ├── critic.py 🎯 Nó: Avaliador de Qualidade
│ │ ├── csv_saver.py 🧾 Nó: Salvar CSV
│ │ ├── graph_generator.py 📈 Nó: Gerador de Gráficos
│ │ └── response.py 💬 Nó: Resposta Natural Final
│ │
│ └── 📁 routers/ Roteadores Condicionais
│ ├── __init__.py
│ └── edges.py ➡️ Funções de roteamento
│
├── 📁 src/ Módulos de benchmark Spider
│ └── 📁 spider/
│ ├── data_loader.py Loader do Spider 1.0
│ ├── query_executor.py Executor SQL
│ ├── metrics.py Métricas (similarity/match/F1)
│ ├── csv_reporter.py Relatórios CSV
│ └── analise_empirica.py Pós-processamento e gráficos
│
├── 📁 scripts/ Orquestração de benchmarks
│ ├── test_spider_eval.py Benchmark Spider 1.0
│ └── test_spider2_eval.py Benchmark Spider 2.0 Lite
│
├── 📁 results/ Resultados CSV das execuções
└── 📁 graphs/ Gráficos gerados
═══════════════════════════════════════════════════════════════════════════════
GUIA DE LEITURA RECOMENDADO:
════════════════════════════
1️⃣ Iniciante?
└─► Leia: README.md → DESENVOLVIMENTO.md → main.py
2️⃣ Desenvolvedor?
└─► Leia: ARQUITETURA.md → text_to_insight/state.py → text_to_insight/graph.py
3️⃣ Operacional?
└─► Leia: DESENVOLVIMENTO.md → main.py → execute!
4️⃣ Estudo Profundo?
└─► text_to_insight/state.py → text_to_insight/nodes/* → text_to_insight/routers/edges.py → text_to_insight/graph.py
═══════════════════════════════════════════════════════════════════════════════
O QUE FOI CRIADO:
═════════════════
✅ ESTRUTURA: Projeto modular com text_to_insight/ + src/spider + suíte de testes em 3 camadas
✅ ESTADO: TypedDict EstadoTextToInsight com campos de SQL, HITL, resposta e telemetria
✅ 9 NÓS: Planejador, EsperaHumana, Schema, AgenteCódigo, Sandbox, Crítico, SalvarCSV, GeradorGráfico, Resposta
✅ 4 ROTEADORES: Sandbox, Planejador, Gráfico e Crítico
✅ GRAFO COMPILADO: StateGraph + MemorySaver + interrupt_before para HITL
✅ DOCUMENTAÇÃO: 3 guias: README, ARQUITETURA, DESENVOLVIMENTO
✅ TELEMETRIA: Tokens (input/output/total), tentativas e latência em CSV
✅ GRÁFICOS: Geração automática com matplotlib quando aplicável
✅ BENCHMARKS: Spider 1.0 e Spider 2.0 Lite (scripts/ + src/spider)
✅ TODA EM PT-BR: Código, variáveis, docstrings, comentários
═══════════════════════════════════════════════════════════════════════════════
ESTATÍSTICAS:
═════════════
📊 Linhas de Código: ~1.400+ (incluindo nós, roteadores e utilitários)
📚 Arquivos Python: 15+ (text_to_insight/ + src/spider + scripts + testes)
📖 Documentação: 3 guias principais
🔄 Fluxos de Grafo: 4+ cenários (normal, retry, HITL, bloqueado_hitl)
🧠 Tentativas max: 3 por padrão (configurável)
⏱️ Status possíveis: 10 tipados + operacionais (aguardando_input, bloqueado_hitl)
═══════════════════════════════════════════════════════════════════════════════
PRÓXIMOS PASSOS (NÃO IMPLEMENTADOS AGORA):
═══════════════════════════════════════════
❌ Novos provedores LLM (Anthropic, etc)
❌ Banco de dados real (PostgreSQL, MySQL, etc)
❌ Docker/Containerização
❌ Cache de schemas
❌ Métricas de produção
❌ Observabilidade (LangSmith, DataDog, etc)
❌ Autenticação/Autorização
❌ Testes unitários (estrutura preparada)
═══════════════════════════════════════════════════════════════════════════════
PARA COMEÇAR:
═════════════
1. Ler README.md para entender o conceito
2. Executar: python main.py "Sua pergunta"
3. Rastrear logs nos outputs dos nós
4. Estudar ARQUITETURA.md para entender fluxos
5. Testar o modo HITL: --hitl on e --hitl off
═══════════════════════════════════════════════════════════════════════════════
QUALIDADE DO CÓDIGO:
════════════════════
✓ Type hints completos (TypedDict, Literal, etc)
✓ Docstrings nas principais funções
✓ Comentários explicativos em código crítico
✓ Imports organizados
✓ Nomes descritivos em português
✓ Separação clara de responsabilidades
✓ Estrutura pronta para testes
✓ Métricas registradas por execução (tokens + latência)
═══════════════════════════════════════════════════════════════════════════════
Desenvolvido com LangGraph 0.2.0+ 🚀
"""
# Este é um arquivo de índice/documentação puro
if __name__ == "__main__":
print(__doc__)