Repository navigation
feat(bird): support for bird benchmarl with multi-attempt logging and data inspection - #17
Open
LuizCorrei4 wants to merge 11 commits into
Open
LuizCorrei4 wants to merge 11 commits into
LuizCorrei4 wants to merge 11 commits into
Conversation
…tação de nós e corrigir loops de roteamento Implementação do pipeline completo de avaliação do benchmark BIRD (Big Bench for Large-scale Database Grounded Text-to-SQL Evaluation), com download, carregamento, execução segura em SQLite, métricas multiset (EX), relatórios e suíte de testes. Adicionalmente, alinha a documentação da arquitetura à realidade do grafo (remoção de referências defasadas ao nó Crítico) e corrige um ciclo infinito no roteamento do LangGraph quando o RAG está desativado. Detalhes das alterações: ### 1. Suíte de Avaliação do BIRD Benchmark (`src/bird/`, `scripts/`, `tests/`) - **Download e Setup de Dados (`scripts/setup_bird_data.py`)**: - Script sem dependências externas (apenas Standard Library) com suporte ao flag `--mini` (~800MB) ou dataset completo. - Normaliza arquivos de perguntas (`data/bird/dev.json`) e bancos SQLite em `data/bird/dev_databases/<db_id>/<db_id>.sqlite`. - **Loader e Parser do Dataset (`src/bird/data_loader.py`)**: - Carregador de dados com amostragem reprodutível via seed (`sample_examples`) e suporte a estratificação por dificuldade (`simple`, `moderate`, `challenging`). - Preparado para PR #15 com resolução de dialetos e URIs via variáveis de ambiente (`BIRD_MYSQL_URI`, `BIRD_POSTGRES_URI`). - Injeção opcional de dicas e regras de negócio via `Hint: {evidence}` controlada por flag `--use-evidence`. - **Executor Seguro em SQLite (`src/bird/query_executor.py`)**: - Execução isolada em modo somente leitura (`?mode=ro&uri=true`) com bloqueio de comandos mutantes (`DROP`, `INSERT`, `DELETE`). - Injeção de 19 funções matemáticas nativas do SQLite com captura segura de erros de domínio (ex: `SQRT(-1)`, `LOG(0)` retornam `NULL` sem crash). - Timeout determinístico com `threading.Timer` para impedir travamentos em queries cartesianas. - **Métricas e Execution Accuracy Multiset (`src/bird/metrics.py`)**: - Cálculo de `execution_match` (EX) comparando multiset de tuplas (`Counter`) com normalização de nulos e floats, garantindo independência de aliases e ordem de colunas. - Cálculo de similaridade sintática de texto SQL via `difflib.SequenceMatcher`. - Padronização em 16 colunas oficiais para diagnóstico detalhado por tentativa. - **Gerador de Relatórios e Submissão Oficial (`src/bird/csv_reporter.py`)**: - Criação automática de subpastas dedicadas por execução (`reports/bird/run_<timestamp>/`). - Geração sincronizada de 3 artefatos: log detalhado linha a linha (`.csv`), relatório executivo formatado com estratificação por dificuldade (`.md`) e arquivo canônico aceito pelo avaliador oficial da DAMO Academy (`.json` / `predict_dev.json`). - Métricas agregadas de `sandbox_success_rate` e `self_correction_rate`. - **Orquestrador CLI de Avaliação (`scripts/test_bird_eval.py`)**: - CLI completa com suporte a `--sample-size`, `--seed`, `--stratify`, `--db-filter`, `--difficulty`, `--rag on/off`, `--cot on/off`, `--use-evidence on/off` e `--dry-run` para testes locais com custo zero. - Cache de instâncias da engine por banco (`engine_cache`) com isolamento estrito de memória por thread (`MemorySaver`). - **Suíte de Testes Automatizados (`tests/test_bird_eval.py`)**: - 11 testes unitários cobrindo todos os módulos do harness com fixtures sintéticas temporárias em ~0.7s (sem consumo de API nem dependência de internet). - **Manual de Operação e Runbook (`src/bird/BENCHMARK.md`)**: - Documentação técnica e operacional completa, com dicionário de métricas e guia prático para análise de diagnósticos e decisões de engenharia. ### 2. Alinhamento Arquitetural: Remoção de Referências Legadas ao Nó Crítico - **Atualização da Documentação (`ARQUITETURA.md`, `README.md`, `DESENVOLVIMENTO.md`)**: - Grafo atualizado de 9 para 8 nós base após a remoção histórica do nó `critic.py` (commit `2501d197...`). - Documentação do loop real de auto-correção do sandbox: `Executor (Sandbox) --[exec_erro]--> Planejador -> Agente de Código`. - Remoção de `feedback_critico` e `roteador_critico` da documentação e alinhamento dos módulos BIRD com o campo `execution_status` e `error`. ### 3. Correções de Bug (Bugfix no Roteamento com RAG Desativado) - **Quebra de Loop Infinito (`text_to_insight/routers/edges.py`, `text_to_insight/nodes/retriever.py`)**: - Identificado ciclo infinito onde erros de execução em modo `--rag off` faziam o `planejador` decidir `"revisando_estrategia"`, e o `roteador_planejador` redirecionava para o `retriever` para expandir schema. - Com RAG desativado, o schema já é completo e o `retriever` não realizava mudanças, mantendo o status em loop infinito. - Correção: o `roteador_planejador` agora detecta RAG desativado e desvia diretamente para o `agente_codigo` para corrigir a query SQL sem passar pelo retriever. - O nó `retriever.py` agora reseta o status para `"schema_obtido"` e incrementa o contador de revisões mesmo com RAG desativado como salvaguarda. - Adicionado teste unitário `test_roteador_planejador_revisao_com_rag_desativado` em `tests/test_componentes.py` (36 testes passando).
…eporting - Implemented `format_result_rows_markdown_table` to render database result rows as GitHub-flavored Markdown tables. - Enhanced `BirdCSVReporter` to include methods for recording failure and self-correction cases. - Updated `rewrite_ordered_csv` to sort rows by `question_id` and `attempt_number`. - Modified `format_markdown_report` to include detailed sections for self-corrections and failure analyses in the generated Markdown report. - Added unit tests for the new table formatting and CSV reporting features.
Data exploration was not running when RAG was on and the topk of 5 was to low to help Pass@k 1
When the Schema was not presente and HITL was on, schema_router was pointing to retriever, which points to planner without schema, resulting in an infinite loop
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
2 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.
Summary:
Integrates full evaluation capabilities for the BIRD benchmark into TextToInsight. Adds automated data provisioning, safe read-only SQL execution with math functions and timeouts, multi-attempt trial tracking, and publication-ready Markdown inspection reports with top-10 dataset result previews.
Fix the GraphRAG to match the SOTA use of it in TextToSQL.
Key Changes:
src/bird/):data_loader.py: Question dataset loading, directory nesting normalization, database/difficulty filtering, and reproducible seeded sampling.query_executor.py: Safe read-only SQLite execution with math function extensions (SQRT,POW,LOG, etc. returningNULLon domain errors) and thread watchdog timeouts (conn.interrupt()).metrics.py: Execution Accuracy (EX via multiset Counter) and normalized SQL text similarity.csv_reporter.py: Logs trial progression into 16-column CSV files, exports officialpredict_dev.json, and renders Markdown reports with top-10 result inspection tables for errors and self-corrections.BENCHMARK.md: Technical and operational manual for benchmark execution.scripts/):setup_bird_data.py: Zero-dependency automated dataset download and extraction supporting--miniand--full.test_bird_eval.py: Evaluation CLI orchestrator supporting live runs, stratification, and cost-free--dry-run.text_to_insight/):retriever.pyandedges.pywhen RAG is disabled to prevent redundant retriever loops.ARQUITETURA.md,DESENVOLVIMENTO.md, andREADME.mdreflecting the sandbox retry (WITHOUT CRITIC NODE) loop and BIRD instructions.