Atualizando da branch de RAG para facilitar merge posterior

.github/workflows/ci.yml

@@ -31,6 +31,14 @@ jobs:
           pip install -r requirements.txt
           pip install -e .
 
+      - name: Ensure that the data folder exists
+        run: mkdir -p data
+
+      - name: Download the relase database for test
+        run: gh release download dados-teste -p "olist_relational.db" -D data/
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Run deterministic test layers
         run: |
           pytest \

.gitignore

@@ -48,6 +48,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+results/
 
 # Translations
 *.mo

ARQUITETURA.md

@@ -137,7 +137,8 @@ Arquivo: `text_to_insight/state.py`
 
 Campos obrigatorios:
 
-- `pergunta_usuario`
+- `pergunta_original`
+- `pergunta_atual`
 - `db_path`
 
 Campos principais do fluxo:
@@ -147,6 +148,13 @@ Campos principais do fluxo:
 - `status`, `tentativas_loop`, `historico_conversa`, `espera_humana`, `pergunta_ao_usuario`
 - telemetria: `tokens_input`, `tokens_output`, `tokens_total`
 
+## HITL e perguntas
+
+- `pergunta_original` e a pergunta inicial da thread (imutavel apos o primeiro set).
+- `pergunta_atual` e a pergunta corrente e fonte de verdade para todo o fluxo.
+- Em HITL, se a resposta do usuario for classificada como "nova pergunta",
+  o sistema atualiza `pergunta_atual` e reinicia o ciclo (sem alterar a original).
+
 ## Status operacionais
 
 No runtime/engine podem aparecer:

DESENVOLVIMENTO.md

@@ -52,6 +52,13 @@ Criterios minimos:
 - retomada por `thread_id`;
 - gravacao de metricas em CSV.
 
+## Contrato HITL (perguntas)
+
+- `pergunta_original`: pergunta inicial da thread, imutavel apos o primeiro set.
+- `pergunta_atual`: pergunta corrente e fonte de verdade para o fluxo.
+- Em HITL, se a resposta do usuario for classificada como "nova pergunta",
+  o sistema atualiza `pergunta_atual` e reinicia o ciclo, sem alterar a original.
+
 ## Execucao
 
 ```bash

README.md

@@ -13,6 +13,13 @@ O runtime padrao garante:
 - retomada por `thread_id`;
 - persistencia de metricas em `data/metricas_execucao.csv`.
 
+## Contrato HITL (perguntas)
+
+- `pergunta_original`: pergunta inicial da thread, imutavel apos o primeiro set.
+- `pergunta_atual`: pergunta corrente e fonte de verdade para o fluxo.
+- Em HITL, se a resposta do usuario for classificada como "nova pergunta",
+  o sistema atualiza `pergunta_atual` e reinicia o ciclo, sem alterar a original.
+
 ## Instalacao
 
 ```bash