Dev#14
Merged
Merged
Conversation
…o usuário em linguagem natural
…estes - Planner retorna um JSON com decisão e pergunta - Agora o schema sempre passa pelo Planner para que ele avalie se a pergunta é clara, ou não antes de chamar o code_agent - Na main, ao invés de usarmos um simples Invoke, adicionei memória para que a pergunta do usuário seja feita fora do Grafo, desse modo podemos adicionar mais interações posteriormente - Caso a pergunta seja absurda/não esta clara, o grafo é interrompido e é adicionada uma pergunta do agente ao estado, abrindo espaço para um input do usuário - Mudei os testes para que estivessem coerentes com essa nova estrutura, adicionei um teste novo e re-rodei os testes em vcr para capturar as mudanças do Planner
Feature/metricas
…o schema, agora ele consegue captar um contexto razóavel da base de dados e ajuda na avaliação crítica
- Novo módulo src/spider/ com data_loader, query_executor, metrics, csv_reporter - Script scripts/test_spider_eval.py para avaliar agente contra 1.034 exemplos - Rastreia cada tentativa individualmente em CSV (1 linha por tentativa) - Calcula similarity score, resultado match, feedback do crítico - Suporta filtrar por db_id, seed, sample-size, max-attempts - Gera resumo com estatísticas por pergunta - Atualiza documentação: DESENVOLVIMENTO.md e README.md
Resolve conflitos mantendo HITL, incorpora métricas de latência e tokens, e padroniza o planejador para manter consistência do estado para tomadas de decisões que não envolvem chamadas de LLMs => retorna 0 tokens gastos
Mudei a lógica do HITL para, ao invés de concatenar respostas, prover um hsitórico de conversa tanto para o planner quanto para o code_agent
Agora que possuimos histórico de conversa, dei acesso dele ao critic e possibilitei a seleção de openai ou google na hr de usar o modelo de API
…ight into feat/metricas-spider
…o feat/metricas-spider
O sistema agora suporta a desativação do HITL via linha de comando
- Introduz flag `--hitl {on,off}` via `argparse` (default: on).
- Altera `executar_consulta` para respeitar o estado de `hitl_ativado`.
- Registra `erro_execucao` e salva as métricas em CSV mesmo no encerramento por bloqueio.
- Exibe o estado atual do HITL no início da execução da main.
- Atualiza `DESENVOLVIMENTO.md` com tutorial e cenários de uso da flag.
- Adiciona `.gitattributes` para forçar padronização de quebra de linha (LF).
Adicionei a classe da biblioteca ainda sem mudar a lógica na main e sem atualizar os testes para ela; Além disso, mudei a lógica do toggle para remover completamente essa opção do planner quando o hitl não esta disponível
…sta natural - Alinha README e ARQUITETURA com o fluxo atual do grafo (7 nós, roteamento revisado e etapa de resposta natural após aprovação do crítico). - Documenta o caminho de Human-in-the-Loop (espera_humana), a interrupção controlada e o comportamento quando o modo HITL está desligado. - Atualiza a semântica do estado compartilhado com campos de conversa, resposta final e telemetria de tokens. - Registra os status operacionais usados em runtime (aguardando_input e bloqueado_hitl). - Corrige o guia de desenvolvimento com validação de import da classe Graph e com a estrutura real de módulos/pastas. - Atualiza o índice técnico do projeto (INDICE.py) com a arquitetura vigente, componentes atuais e métricas/observabilidade. - Sem alteração de lógica de código, apenas documentação
…pública Este commit transforma a base de código em uma biblioteca semântica e oficial, eliminando duplicidades e formalizando contratos de execução, além de preparar o pacote para distribuição. Principais alterações: - Namespace e Empacotamento: Código base movido de `src` para `text_to_insight`. O pyproject.toml foi configurado para varredura do namespace oficial e criação do entrypoint de console `text-to-insight`. - Unificação de Runtime: Lógica antes dividida entre main e InsightEngine foi centralizada em `runtime.py`, que agora cuida do estado, loop do grafo, métricas e controle central de HITL (ligado/desligado/pausado). - Engine e CLI: Criação de uma CLI oficial (`cli.py`) suportando thread-id e db-path. A `InsightEngine` orquestra a execução via runtime (com métodos `run` e `resume`). O arquivo `main.py` virou apenas um adaptador fino da CLI. - API Pública: Congelada no `__init__.py`, expondo apenas as três interfaces essenciais: InsightEngine, Graph e EstadoTextToInsight. - Qualidade e Testes: Imports e assinaturas ajustados. Adição de novos testes de integração da Engine (fim a fim, com e sem HITL). Adição de `test_real_api_smoke.py` com o novo marker `real_api` no pytest.ini para monitoramento de provider/model drift. - Documentação: README.md, DESENVOLVIMENTO.md e ARQUITETURA.md atualizados para refletir a nova estrutura de biblioteca, estratégias de teste, CI híbrida e contratos de HITL.
Feature/hitl
…ifiquei o prompt do crítico para ser menos crítico
…ova pergunta - adiciona `pergunta_original` (imutavel) e `pergunta_atual` (fonte de verdade) ao estado - inicializa ambas no estado inicial do runtime - cria classificador de resposta humana com JSON estrito + fallback heuristico - atualiza `registrar_resposta_humana` para sempre anexar historico e, quando for `nova_pergunta`, resetar `sql_gerada`, `feedback_critico`, `erro_execucao`, `tentativas_loop`, `saida_terminal` e `status` para reexecutar o grafo limpo - migra prompts dos nos (planner/code_agent/critic/response) para usar `pergunta_atual` - ajusta prompt da resposta final para "pergunta atual" - atualiza fakes e testes (componentes, nos, integracao) e adiciona VCR de HITL - documenta o novo contrato de perguntas (README/ARQUITETURA/DESENVOLVIMENTO) O motivo do reset: quando a resposta humana vira uma nova pergunta, o estado anterior (SQL, feedback, erros e tentativas) passa a ser obsoleto e pode contaminar a nova execucao. Por isso, os campos sao limpos e o `status` volta para `iniciado`, garantindo que o fluxo replaneje, gere SQL e critique a partir da nova pergunta, sem herdar contexto incorreto.
Co-authored-by: Copilot <copilot@github.com>
… feature/resut-dataframe
…_schema e tratamento mais robusto dos campos de pergunta no nó do retriever mas sem mudança de lógica, além de atualização de docstring do Nó Retriever que estava inconsistente
Merge into dev from feature/geracao-grafico
Steiner Tree foi adicionada na etapa de retrieve do grafo Removi a lógica de busca de FK para que seja implementada como SchemaCralwer Reformulei os testes para a estrutura atual e tornei-os mais robustos Corrigi o Critic que estava recebendo sempre o SCHEMA completo
- Adiciona extração via SchemaCrawler em schema.py com fallback para PRAGMA SQLITE - Renomeia arquivo erich_schema.py para enrich_schema.py - Atualiza detalhes gerais na documentação - Adiciona 2 novos testes em test_components.py focados no SchemaCrawler OBS: O SchemaCrawler exige Java 17+ e instalação local na máquina. Futuramente, criar make_setup.py para automatizar o ambiente de dev e configurar a instalação do SC no Dockerfile de produção.
- Novo relatório com métricas de custo/latência (percentis P75/P90/P95) - Detalhes de falhas com histórico de tentativas, CoT e contexto - Renomear mismatches → failures para consistência - Remover coluna de veredito do crítico (removido do pipeline) - Relatório empírico completo (análises do orientador) - Parâmetros de CoT/data-exploration comentados (requer feature branch)
…xto adicional Quando uma instância do dataset tem o campo external_knowledge preenchido (ex: 'patents_info.md'), o script agora carrega o conteúdo do markdown correspondente em resource/documents/ e o anexa à pergunta dentro de tags <additional_context>. Isso dá ao agente o mesmo contexto de domínio que o benchmark provê, sem alterações arquiteturais. 13 das 135 instâncias locais possuem external_knowledge.
Hotfix/spider eval
…hecimentos e correções do agente
Implementação focada em melhorar o suporte aos bancos do benchmark Spider 2, resolver limitações matemáticas do SQLite e corrigir loops infinitos no grafo. A nova lógica garante um mecanismo inteligente para inferir chaves, recuperar contextos complexos e blindar o sistema contra erros de roteamento e limitações de dialeto.
Detalhes das alterações:
### 1. Robustez no Reconhecimento de Schemas
- **Heurística de FKs Virtuais Poliglota** (`text_to_insight/nodes/schema.py`):
- Expandida para identificar sufixos `_id`, `_code` e `_no`, e suportar mapeamento para tabelas no plural (ex: `flights`, `tickets`) ou com sufixos analíticos (`_data`).
- **Match de tabelas com prefixo**: a heurística agora busca tabelas que terminam com o nome base após separador `_` (ex: `order_id` → `olist_orders`), resolvendo bancos com convenção de nomes prefixados como Brazilian E-Commerce.
- **Match por coluna homônima**: detecta colunas com nome idêntico entre tabelas onde o nome da coluna faz parte do nome da outra tabela (ex: `product_category_name` em `olist_products` → `product_category_name_translation`).
- **Limpeza do SchemaCrawler**: Removida a dependência do arquivo solto `schemacrawler.config.properties`. Os parâmetros `-schemacrawler.format.hide_weakassociations=false` foram acoplados nativamente na chamada via `subprocess.run` em `schema.py`.
### 2. RAG Adaptativo e Roteamento Condicional
- **Steiner Tree Resiliente** (`text_to_insight/retriever/graph_logic.py`): O grafo do RAG agora ignora tabelas "intrusas" e forma caminhos agrupados sem abortar a busca.
- **Expansão Dinâmica do Top-K** (`text_to_insight/retriever/engine.py`, `text_to_insight/nodes/retriever.py`): O parâmetro `top_k` agora cresce automaticamente (5, 9, 13) baseado nas falhas do Planejador (`tentativas_loop`).
- **Fluxo do Grafo**: Em caso de erros, o Planejador (`status: revisando_estrategia`) passou a rotear de volta para o Retriever para aproveitar o novo Top-K expandido.
### 3. Melhorias no Motor de Avaliação (Spider 2) e Dialetos
- **Injeção de Conhecimento Externo (`scripts/test_spider2_eval.py`)**: O script de avaliação agora extrai automaticamente regras de negócio e contextos matemáticos da coluna `external_knowledge` no JSONL e as anexa ao prompt dentro das tags `<additional_context>`.
- **Injeção de Funções Matemáticas no SQLite (`src/spider/query_executor.py`)**: A conexão local foi estendida via `.create_function()` com 19 funções trigonométricas e matemáticas (SIN, COS, SQRT, POWER, PI, LOG, etc.), permitindo que o LLM resolva perguntas que usam cálculo espacial sem esbarrar no "No such function" (ex: DB Airlines).
### 4. Correções de Bug (Bugfixes)
- **Quebra de Loops Infinitos no Grafo** (`text_to_insight/routers/edges.py`, `text_to_insight/nodes/retriever.py`, `text_to_insight/state.py`, `text_to_insight/graph.py`):
Corrigidos ciclos infinitos onde o Planejador decidia `"revisando_estrategia"`, o Roteador enviava ao Retriever, mas o Retriever devolvia `"schema_obtido"` sem mudanças efetivas, fazendo o Planejador reavaliar e decidir `"revisando_estrategia"` novamente, infinitamente.
Três proteções no Roteador do Planejador:
- **Schema pequeno** (<1500 chars): RAG não consegue filtrar, Retriever é bypassed e o fluxo segue direto para `agente_codigo`.
- **Limite de expansões RAG** (`MAX_TENTATIVAS_REVISAO=2`): para schemas grandes, o Retriever pode ser chamado até 2 vezes via novo campo `tentativas_revisao_retriever` no estado. Após esgotar, o roteador força `agente_codigo`.
- **Eliminação do auto-loop do Planejador**: o path default do roteador agora envia para `agente_codigo` em vez de reenviar para o próprio `planejador`, impedindo auto-loops por status não reconhecido.
- **Correção de Prompt JSON (`text_to_insight/nodes/planner.py`)**: Substituídas as chaves duplas `{{` e `}}` no template de diretrizes, que estavam induzindo o LLM a alucinar o formato do JSON e gerar erros no decoder.
Exemplo de erro no log:
[PLANEJADOR] Erro ao parsear JSON: {{
"decisao": "revisando_estrategia"
}}
- **Documentação Atualizada** (`README.md`, `DESENVOLVIMENTO.md`): documentação e tutoriais refletindo o uso programático e por CLI.
- Refatoração dos testes de novas features (FKs virtuais, injeção matemática e loop do roteador) transferidos para test_componentes.py - Regeneração dos arquivos de gravação (cassettes) do VCR para adaptar o test_integracao aos novos payloads do LLM - docs: Inclusão do teste test_biblioteca_integracao.py na documentação de desenvolvimento
GraphRAG+SchemaCrawler para Dev
# Conflicts: # scripts/test_spider2_eval.py # scripts/test_spider_eval.py # tests/test_biblioteca_integracao.py # text_to_insight/InsightEngine.py # text_to_insight/cli.py # text_to_insight/graph.py # text_to_insight/nodes/critic.py # text_to_insight/nodes/retriever.py # text_to_insight/runtime.py # text_to_insight/state.py
Implementa CoT, Data Exploration e toggles. Remove Crítico. Melhora Scripts de avaliação.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Merge dev into main (Conference release)