docs-cli 0.1.0__py3-none-any.whl

docs_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: docs-cli
+Version: 0.1.0
+Summary: Um toolkit para processamento e avaliação de documentação.
+Author-email: Paulo Guilherme Pilott <seuemail@example.com>
+License: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Documentation
+Classifier: Topic :: Utilities
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: google-generativeai
+Requires-Dist: python-dotenv
+Requires-Dist: numpy
+Requires-Dist: pandas
+
+# Toolkit de Análise e Cobertura de Documentação Técnica (`docs-cli`)
+
+Este toolkit fornece um conjunto de scripts Python para processar documentação técnica em formato Markdown, gerar embeddings semânticos, avaliar a cobertura da documentação em relação a um conjunto de perguntas e respostas, e gerar relatórios detalhados. O script principal `docs_tc.py` orquestra a execução dos scripts individuais.
+
+## Pré-requisitos
+
+1.  **Python 3.7+**: certifique-se de que o Python está instalado e configurado no seu PATH.
+2.  **Dependências Python**: instale as bibliotecas necessárias. É recomendado criar um ambiente virtual:
+    ```bash
+    python -m venv venv
+    source venv/bin/activate  # Linux/macOS
+    # venv\Scripts\activate    # Windows
+    pip install google-generativeai python-dotenv numpy pandas
+    ```
+    Você também pode criar um arquivo `requirements.txt` com o conteúdo acima e rodar `pip install -r requirements.txt`.
+3.  **Chave da API Google Gemini**:
+    * Crie um arquivo chamado `.env` na raiz do projeto.
+    * Dentro do `.env`, adicione sua chave da API:
+        ```
+        GOOGLE_API_KEY="SUA_CHAVE_API_AQUI"
+        ```
+    * **IMPORTANTE**: o arquivo `.env` contém informações sensíveis e **não deve ser versionado** no Git. Adicione `.env` ao seu arquivo `.gitignore`.
+
+## Estrutura de Arquivos Esperada (Antes da Execução)  
+
+```txt
+/seu-projeto-raiz/
+|-- docs_tc.py                   # Script orquestrador principal
+|-- merge_markdown.py            # Script para consolidar .md
+|-- extract_data_from_markdown.py  # Script para extrair dados do .md consolidado
+|-- generate_embeddings.py        # Script para gerar embeddings
+|-- limpa_csv.py                 # Script para limpar o CSV de Q&A
+|-- evaluate_coverage.py         # Script para avaliar a cobertura
+|-- generate_report.py           # Script para gerar relatório .md
+|-- generate_report_html.py      # Script para gerar relatório .html
+```
+## Arquivos Gerados (e não versionados por padrão):
+
+Os seguintes arquivos são gerados durante a execução dos scripts. É recomendado adicioná-los ao seu `.gitignore` se você não pretende versioná-los:
+
+- `corpus_consolidated.md`
+- `raw_docs.json`
+- `embedings.json` (ou o nome que você usar para o arquivo de embeddings)
+- `gartner_filtrado_processed.csv` (ou o nome do seu CSV de Q&A limpo)
+- `evaluation_results.json`
+- `coverage_report.md`
+- `coverage_report.html`
+
+### Configuração do `.gitignore`:
+
+#### Arquivos de Ambiente
+```gitignore	
+.env
+chaves/.env
+```
+#### Arquivos de Dados Gerados
+```gitignore
+# Ignorar arquivos gerados automaticamente 
+*.json
+*.csv
+*.md
+*.html
+```
+
+#### Exceto os arquivos que SÃO parte do toolkit/interface
+
+```bash
+# Mantenha estes arquivos versionados (exceções à regra global)
+!docs_tc.py
+!merge_markdown.py
+!extract_data_from_markdown.py
+!generate_embedings.py
+!limpa_csv.py
+!evaluate_coverage.py
+!generate_report.py
+!generate_report_html.py
+!assistente/index.html
+!assistente/about.html
+!assistente/mudanca.html
+!README.md
+!requirements.txt
+```
+
+#### Arquivos de Cache Python
+```gitignore	
+pycache/
+*.py[cod]
+*$py.class
+```
+#### Ambiente Virtual
+```gitignore
+venv/
+```
+
+- Ajuste o `.gitignore` acima para manter os arquivos `.md` e `.html` que são parte da sua documentação ou da ferramenta em si (como este `README.md` ou o `index.html` da interface).*
+- No exemplo acima, `*.json`, `*.csv`, `*.md`, `*.html` são ignorados globalmente, e depois exceções são adicionadas. Seus arquivos de documentação originais em `DocumentosMD/` e o CSV bruto em `DadosQA/` **não serão ignorados** por esta configuração, o que é o desejado.*
+
+## Utilização do `docs-cli`
+
+O `docs_tc.py` é o ponto de entrada principal para utilizar o toolkit. Abra um terminal na raiz do projeto.
+
+### 1. Ajuda Geral e de Comandos:
+
+```bash
+docs-cli -h
+docs-cli <comando> -h  # Ex: docs-cli merge -h
+```
+### 2. Execução de Comandos Individuais:
+
+Cada script pode ser chamado por um subcomando. Os nomes de arquivo padrão são usados se não especificados.
+
+#### Consolidar Documentos (`merge`):
+
+```bash
+docs-cli merge ./docs/ --output_file corpus_consolidated.md
+
+```
+
+- `./docs/`: Diretório contendo seus arquivos .md originais.
+- `-output_file`: (opcional) Nome do arquivo consolidado. Padrão: `corpus_consolidated.md`.
+
+#### Extrair Dados do Markdown Consolidado (`extract`):
+
+```bash
+docs-cli extract --input_file corpus_consolidated.md --output_file raw_docs.json
+```
+
+- `-input_file`: (Opcional) Arquivo .md consolidado. Padrão: `corpus_consolidated.md`.
+- `-output_file`: (Opcional) Arquivo JSON para os dados brutos. Padrão: `raw_docs.json`.
+
+#### Gerar Embeddings (`generate_embeddings`):
+
+```bash
+docs-cli generate_embeddings --input_file raw_docs.json --output_file embeddings.json
+```
+
+- `-input_file`: (Opcional) Arquivo JSON com os dados brutos. Padrão: `raw_docs.json`.
+- `-output_file`: (Opcional) Arquivo JSON para os embeddings. Padrão: `embeddings.json`.
+
+#### Limpar CSV de Q&A (`clean_csv`):
+
+```bash
+docs-cli clean_csv ./csv/qa_bruto.csv --output_file qa_processado.csv
+```
+
+- `./csv/qa_bruto.csv`: Caminho para o arquivo CSV de perguntas e respostas bruto.
+- `-output_file`: (Opcional) Nome do arquivo CSV processado. Padrão: `gartner_filtrado_processed.csv`.
+
+#### Avaliar Cobertura (`evaluate_coverage`):
+
+```bash
+docs-cli evaluate qa_processado.csv embeddings.json -k 5 -o evaluation_results.json
+```
+
+- `qa_processado.csv`: Caminho para o arquivo CSV de perguntas e respostas processado.
+- `embeddings.json`: Caminho para o arquivo JSON com os embeddings.
+- `-k`: (Opcional) Número de resultados a retornar. Padrão: 5.
+- `-o`: (Opcional) Nome do arquivo JSON para os resultados da avaliação. Padrão: `evaluation_results.json`.
+De forma geral, os parâmetros são:
+
+| Parâmetro                | Tipo    | Obrigatório | Descrição                                                                                       |
+|--------------------------|---------|-------------|-------------------------------------------------------------------------------------------------|
+| `qa_file`                | string  | Sim         | Caminho para o arquivo CSV com perguntas e respostas                                            |
+| `embeddings_file`        | string  | Sim         | Caminho para o arquivo JSON com os chunks processados e embeddings                              |
+| `-k`, `--top-k`          | inteiro | Não         | Número de chunks mais relevantes a considerar (padrão: `5`)                                       |
+| `-o`, `--output`         | string  | Não         | Caminho do arquivo de saída para os resultados (padrão: `evaluation_results.json`)              |
+
+#### Gerar Relatório Markdown (`generate_report`):
+
+```bash
+docs-cli generate_report evaluation_results.json --output_file coverage_report.md
+```
+
+- `evaluation_results.json`: Caminho para o arquivo JSON com os resultados da avaliação.
+- `-output_file`: (Opcional) Nome do arquivo Markdown para o relatório. Padrão: `coverage_report.md`.
+
+#### Gerar Relatório HTML (`generate_report_html`):
+
+```bash
+docs-cli generate_report_html evaluation_results.json --output_file coverage_report.html
+```
+
+- `evaluation_results.json`: Caminho para o arquivo JSON com os resultados da avaliação.
+- `-output_file`: (Opcional) Nome do arquivo HTML para o relatório. Padrão: `coverage_report.html`.
+
+## Executando o Toolkit Completo
+Para executar todo o fluxo de trabalho do toolkit, você pode usar o comando principal `docs_tc.py` com o subcomando `full_flow`. Este comando executa todos os passos necessários, desde a consolidação dos documentos até a geração dos relatórios.
+
+```bash
+docs-cli full_flow ./docs/ ./csv/qa_bruto.csv --eval_top_k 5 --embeddings_file embedings.json
+```
+
+## Manutenção e Versionamento
+
+- NÃO FAÇA COMMIT do seu arquivo `.env` contendo a `GOOGLE_API_KEY`.
+- NÃO FAÇA COMMIT dos arquivos de dados gerados automaticamente (como `corpus_consolidated.md`, `raw_docs.json`, `embedings.json`, `evaluation_results.json`, etc.), a menos que tenha um motivo específico para versionar um estado particular desses dados. Adicione-os ao seu `.gitignore`.
+- O arquivo CSV original com os dados de Q&A e os arquivos Markdown originais da sua documentação podem e devem ser versionados se fizerem parte da fonte do seu projeto.
+
+---
+
+Dê um alô :)
+paulo[at]paulogpd.com.br

docs_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+docs_tc.py,sha256=2SDRu3E4vuyHmtTT1KNVuvPSOLopRm6B4OahEDe9Zo8,15921
+evaluate_coverage.py,sha256=4dvQZGKqVtC6UoEXyYDyfW53t-MSDvhgsg82xofUkow,17177
+extract_data_from_markdown.py,sha256=kkGLlHrnEXFxuGDdpXKdQLu2gDqkX2e8TlOHQARwDiQ,5729
+generate_embeddings.py,sha256=8wWoVZ_pdu-hQ6iYNi8kS4LE-ZyoQav5NtHkeTApFkY,10687
+generate_report.py,sha256=twQICwbh_4G5BMIZw0sZLzU8RW67FMxgZuI23Xh7xao,4726
+generate_report_html.py,sha256=0Zf3O1NMqsY7pGBwmwkD3KvDH8_yR2mGTPPZIzD8cV4,10232
+limpa_csv.py,sha256=fOVv3ryh3LxQFF99WgrXuqocnExvHgzP46eVZT4zjWk,6096
+merge_markdown.py,sha256=TlACWE73mhRYOImb-YVezEu0QUxqh2pa8_cz3-K94Ws,3458
+docs_cli-0.1.0.dist-info/METADATA,sha256=DwLaaGh92xsFDJRc8MS33eq6BpafwbLjjEqbxlUOXIo,9366
+docs_cli-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+docs_cli-0.1.0.dist-info/entry_points.txt,sha256=QujFzE6D1LdLGX79v7Lk3rNQpiGQE6czUUwWfdiWTMY,417
+docs_cli-0.1.0.dist-info/top_level.txt,sha256=rYmdCpf_cAsmIgkzk_iA0SvgEQzGKPRE6UDwg6qO5ZQ,135
+docs_cli-0.1.0.dist-info/RECORD,,

docs_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

docs_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,9 @@
+[console_scripts]
+docs-cli = docs_tc:main
+docs-tc-clean-csv = limpa_csv:cli_main
+docs-tc-evaluate-coverage = evaluate_coverage:cli_main
+docs-tc-extract-data = extract_data_from_markdown:cli_main
+docs-tc-generate-embeddings = generate_embedings:cli_main
+docs-tc-generate-report-html = generate_report_html:cli_main
+docs-tc-generate-report-md = generate_report:cli_main
+docs-tc-merge-markdown = merge_markdown:cli_main

docs_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,8 @@
+docs_tc
+evaluate_coverage
+extract_data_from_markdown
+generate_embeddings
+generate_report
+generate_report_html
+limpa_csv
+merge_markdown

docs_tc.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import argparse
+import subprocess
+import sys
+import os
+
+# Nomes de arquivo padrão intermediários e finais
+DEFAULT_CORPUS_CONSOLIDATED = "corpus_consolidated.md"
+DEFAULT_RAW_DOCS = "raw_docs.json"
+DEFAULT_EMBEDDINGS = "embeddings.json" # Conforme sua solicitação
+DEFAULT_EVAL_RESULTS = "evaluation_results.json"
+DEFAULT_QA_PROCESSED = "gartner_filtrado_processed.csv" # Saída do limpa_csv e entrada do evaluate
+DEFAULT_MD_REPORT = "coverage_report.md"
+DEFAULT_HTML_REPORT = "coverage_report.html"
+
+def run_script(command_args):
+    """Executa um script (entry point) como um subprocesso."""
+    # Espera que command_args[0] seja um executável no PATH (ex: 'docs-tc-extract-data')
+    command = command_args
+    print(f"🚀 Executando: {' '.join(command)}")
+    try:
+        process = subprocess.run(command, capture_output=True, text=True, encoding=sys.stdout.encoding or 'latin-1', errors='replace')
+
+        if process.stdout:
+            print("Output:\n", process.stdout)
+        if process.stderr:
+            print("Errors:\n", process.stderr, file=sys.stderr)
+
+        if process.returncode != 0:
+            print(f"❌ Erro ao executar {' '.join(command)}. Código de saída: {process.returncode}", file=sys.stderr)
+            return None # Indica falha para as funções run_step_or_exit
+
+        print(f"✅ Script {' '.join(command_args)} concluído com sucesso.")
+        return process
+
+    except FileNotFoundError:
+        print(f"🚨 Erro: Comando '{command[0]}' não encontrado. Verifique se o docs-cli está instalado corretamente e se os scripts dos subcomandos (ex: {command[0]}.exe) foram criados na pasta Scripts do seu ambiente virtual e se o ambiente virtual está ativo.", file=sys.stderr)
+        sys.exit(1) # Falha crítica se o comando do script não for encontrado
+    except Exception as e:
+        print(f"🚨 Exceção ao executar o subprocesso {' '.join(command)}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Docs Toolkit CLI - Orquestrador de scripts de processamento de documentação.")
+    subparsers = parser.add_subparsers(dest="command", help="Comandos disponíveis", required=True)
+
+    # --- Subparser para merge_markdown.py ---
+    parser_merge = subparsers.add_parser("merge", help="Consolida arquivos Markdown de um diretório.")
+    parser_merge.add_argument("input_dir", help="Diretório de entrada contendo os arquivos .md.")
+    parser_merge.add_argument("--output_file", default=DEFAULT_CORPUS_CONSOLIDATED,
+                              help=f"Arquivo de saída para o Markdown consolidado (padrão: {DEFAULT_CORPUS_CONSOLIDATED}).")
+
+    # --- Subparser para extract_data_from_markdown.py ---
+    parser_extract = subparsers.add_parser("extract", help="Extrai dados estruturados do Markdown consolidado.")
+    parser_extract.add_argument("--input_file", default=DEFAULT_CORPUS_CONSOLIDATED,
+                                help=f"Arquivo Markdown consolidado de entrada (padrão: {DEFAULT_CORPUS_CONSOLIDATED}).")
+    parser_extract.add_argument("--output_file", default=DEFAULT_RAW_DOCS,
+                                help=f"Arquivo JSON de saída para os documentos brutos (padrão: {DEFAULT_RAW_DOCS}).")
+
+    # --- Subparser para generate_embedings.py ---
+    parser_generate = subparsers.add_parser("generate_embeddings", help="Gera embeddings para os documentos processados.")
+    parser_generate.add_argument("--input_file", default=DEFAULT_RAW_DOCS,
+                                 help=f"Arquivo JSON de entrada com os documentos brutos (padrão: {DEFAULT_RAW_DOCS}).")
+    parser_generate.add_argument("--output_file", default=DEFAULT_EMBEDDINGS,
+                                 help=f"Arquivo JSON de saída para os embeddings (padrão: {DEFAULT_EMBEDDINGS}).")
+
+    # --- Subparser para limpa_csv.py ---
+    parser_clean_csv = subparsers.add_parser("clean_csv", help="Limpa o arquivo CSV de Perguntas e Respostas.")
+    parser_clean_csv.add_argument("input_file", help="Arquivo CSV de entrada a ser limpo (ex: qa-data.csv).")
+    parser_clean_csv.add_argument("--output_file", default=DEFAULT_QA_PROCESSED,
+                                  help=f"Arquivo CSV de saída limpo (padrão: {DEFAULT_QA_PROCESSED}).")
+
+    # --- Subparser para evaluate_coverage.py ---
+    parser_evaluate = subparsers.add_parser("evaluate", help="Avalia a cobertura da documentação.")
+    parser_evaluate.add_argument("qa_file",
+                                 help="Caminho para o arquivo CSV limpo com perguntas e respostas.")
+    parser_evaluate.add_argument("embeddings_file",
+                                 help="Caminho para o arquivo JSON com chunks processados e embeddings.")
+    parser_evaluate.add_argument("-k", "--top_k", type=int, default=5,
+                                 help="Número de chunks mais relevantes a considerar (padrão: 5).")
+    parser_evaluate.add_argument("-o", "--output", default=DEFAULT_EVAL_RESULTS,
+                                 help=f"Arquivo de saída para os resultados da avaliação (padrão: {DEFAULT_EVAL_RESULTS}).")
+
+    # --- Subparser para generate_report.py (Markdown) ---
+    parser_report_md = subparsers.add_parser("report_md", help="Gera o relatório de cobertura em Markdown.")
+    parser_report_md.add_argument("--input_file", default=DEFAULT_EVAL_RESULTS,
+                                  help=f"Arquivo JSON de entrada com os resultados da avaliação (padrão: {DEFAULT_EVAL_RESULTS}).")
+    parser_report_md.add_argument("--output_file", default=DEFAULT_MD_REPORT,
+                                  help=f"Arquivo Markdown de saída para o relatório (padrão: {DEFAULT_MD_REPORT}).")
+    parser_report_md.add_argument("--top_k_chunks", type=int, default=5,
+                                  help="Valor de top_k_chunks usado na avaliação (para consistência do relatório, padrão: 5).")
+
+    # --- Subparser para generate_report_html.py (HTML) ---
+    parser_report_html = subparsers.add_parser("report_html", help="Gera o relatório de cobertura em HTML.")
+    parser_report_html.add_argument("--input_file", default=DEFAULT_EVAL_RESULTS,
+                                    help=f"Arquivo JSON de entrada com os resultados da avaliação (padrão: {DEFAULT_EVAL_RESULTS}).")
+    parser_report_html.add_argument("--output_file", default=DEFAULT_HTML_REPORT,
+                                    help=f"Arquivo HTML de saída para o relatório (padrão: {DEFAULT_HTML_REPORT}).")
+    parser_report_html.add_argument("--top_k_chunks", type=int, default=5,
+                                    help="Valor de top_k_chunks usado na avaliação (para consistência do relatório, padrão: 5).")
+
+    # --- Subparser para o fluxo completo ---
+    parser_full_flow = subparsers.add_parser("full_flow", help="Executa o fluxo completo de processamento e avaliação.")
+    parser_full_flow.add_argument("doc_input_dir", help="Diretório de entrada dos arquivos .md originais.")
+    parser_full_flow.add_argument("qa_input_file", help="Arquivo CSV de entrada original com Perguntas e Respostas (ex: qa-data.csv).")
+    parser_full_flow.add_argument("--eval_top_k", type=int, default=5, help="Top K para a etapa de avaliação (padrão: 5).")
+    parser_full_flow.add_argument("--corpus_file", default=DEFAULT_CORPUS_CONSOLIDATED)
+    parser_full_flow.add_argument("--raw_docs_file", default=DEFAULT_RAW_DOCS)
+    parser_full_flow.add_argument("--embeddings_file", default=DEFAULT_EMBEDDINGS)
+    parser_full_flow.add_argument("--cleaned_qa_file", default=DEFAULT_QA_PROCESSED)
+    parser_full_flow.add_argument("--eval_results_file", default=DEFAULT_EVAL_RESULTS)
+    parser_full_flow.add_argument("--md_report_file", default=DEFAULT_MD_REPORT)
+    parser_full_flow.add_argument("--html_report_file", default=DEFAULT_HTML_REPORT)
+
+
+    # --- Subparser para fluxo customizado ---
+    parser_custom_flow = subparsers.add_parser("custom_flow", help="Executa uma sequência customizada de scripts.")
+    parser_custom_flow.add_argument("steps", nargs='+', choices=['merge', 'extract', 'generate_embeddings', 'clean_csv', 'evaluate', 'report_md', 'report_html'],
+                                    help="Sequência de etapas a serem executadas (ex: merge extract generate_embeddings).")
+
+    args = parser.parse_args()
+
+    # Nomes dos entry points (conforme definido em setup.py)
+    SCRIPT_MAP = {
+        "merge": "docs-tc-merge-markdown",
+        "extract": "docs-tc-extract-data",
+        "generate_embeddings": "docs-tc-generate-embeddings", # Certifique-se que 'generate_embedings.py' (com typo) tem cli_main e o entry point no setup.py usa esse nome de módulo
+        "clean_csv": "docs-tc-clean-csv",
+        "evaluate": "docs-tc-evaluate-coverage",
+        "report_md": "docs-tc-generate-report-md",
+        "report_html": "docs-tc-generate-report-html"
+    }
+
+    if args.command == "merge":
+        run_script([SCRIPT_MAP["merge"], args.input_dir, args.output_file])
+    elif args.command == "extract":
+        run_script([SCRIPT_MAP["extract"], args.input_file, args.output_file])
+    elif args.command == "generate_embeddings":
+        run_script([SCRIPT_MAP["generate_embeddings"], args.input_file, args.output_file])
+    elif args.command == "clean_csv":
+        run_script([SCRIPT_MAP["clean_csv"], args.input_file, args.output_file])
+    elif args.command == "evaluate":
+        run_script([
+            SCRIPT_MAP["evaluate"],
+            args.qa_file,
+            args.embeddings_file,
+            "-k", str(args.top_k),
+            "-o", args.output
+        ])
+    elif args.command == "report_md":
+        run_script([
+            SCRIPT_MAP["report_md"],
+            args.input_file,
+            args.output_file,
+            str(args.top_k_chunks)
+        ])
+    elif args.command == "report_html":
+        run_script([
+            SCRIPT_MAP["report_html"],
+            args.input_file,
+            args.output_file,
+            str(args.top_k_chunks)
+        ])
+    elif args.command == "full_flow":
+        print("🚀 Iniciando fluxo completo...")
+        def run_step_or_exit(step_command_args):
+            if run_script(step_command_args) is None:
+                print(f"❌ Etapa {step_command_args[0]} falhou. Abortando fluxo completo.")
+                sys.exit(1)
+
+        run_step_or_exit([SCRIPT_MAP["merge"], args.doc_input_dir, args.corpus_file])
+        run_step_or_exit([SCRIPT_MAP["clean_csv"], args.qa_input_file, args.cleaned_qa_file])
+        run_step_or_exit([SCRIPT_MAP["extract"], args.corpus_file, args.raw_docs_file])
+        run_step_or_exit([SCRIPT_MAP["generate_embeddings"], args.raw_docs_file, args.embeddings_file])
+        run_step_or_exit([
+            SCRIPT_MAP["evaluate"],
+            args.cleaned_qa_file,
+            args.embeddings_file,
+            "-k", str(args.eval_top_k),
+            "-o", args.eval_results_file
+        ])
+        run_step_or_exit([
+            SCRIPT_MAP["report_md"],
+            args.eval_results_file,
+            args.md_report_file,
+            str(args.eval_top_k)
+        ])
+        run_step_or_exit([
+            SCRIPT_MAP["report_html"],
+            args.eval_results_file,
+            args.html_report_file,
+            str(args.eval_top_k)
+        ])
+        print("🎉 Fluxo completo concluído!")
+
+    elif args.command == "custom_flow":
+        print(f"▶️ Iniciando fluxo customizado: {' -> '.join(args.steps)}")
+        current_corpus_file = DEFAULT_CORPUS_CONSOLIDATED
+        current_raw_docs_file = DEFAULT_RAW_DOCS
+        current_embeddings_file = DEFAULT_EMBEDDINGS
+        current_cleaned_qa_file = DEFAULT_QA_PROCESSED
+        current_eval_results_file = DEFAULT_EVAL_RESULTS
+        default_eval_top_k = 5
+
+        def run_custom_step_or_exit(step_command_args):
+            if run_script(step_command_args) is None:
+                print(f"❌ Etapa {step_command_args[0]} falhou. Abortando fluxo customizado.")
+                sys.exit(1)
+
+        for step in args.steps:
+            print(f"\n--- Executando etapa: {step} ---")
+            if step == "merge":
+                doc_input_dir = input("Por favor, informe o diretório de entrada para 'merge' (pressione Enter para usar 'docs' como padrão): ") or "docs"
+                run_custom_step_or_exit([SCRIPT_MAP["merge"], doc_input_dir, current_corpus_file])
+            elif step == "extract":
+                 if not os.path.exists(current_corpus_file):
+                     current_corpus_file = input(f"Arquivo Corpus ({current_corpus_file}) não encontrado. Informe o caminho correto: ")
+                 run_custom_step_or_exit([SCRIPT_MAP["extract"], current_corpus_file, current_raw_docs_file])
+            elif step == "generate_embeddings":
+                if not os.path.exists(current_raw_docs_file):
+                     current_raw_docs_file = input(f"Arquivo Raw Docs ({current_raw_docs_file}) não encontrado. Informe o caminho correto: ")
+                run_custom_step_or_exit([SCRIPT_MAP["generate_embeddings"], current_raw_docs_file, current_embeddings_file])
+            elif step == "clean_csv":
+                qa_input_file = input("Por favor, informe o arquivo CSV de Q&A original para 'clean_csv' (pressione Enter para usar 'qa-data.csv'): ") or "qa-data.csv"
+                run_custom_step_or_exit([SCRIPT_MAP["clean_csv"], qa_input_file, current_cleaned_qa_file])
+            elif step == "evaluate":
+                if not os.path.exists(current_cleaned_qa_file):
+                     current_cleaned_qa_file = input(f"Arquivo QA limpo ({current_cleaned_qa_file}) não encontrado. Informe o caminho correto: ")
+                if not os.path.exists(current_embeddings_file):
+                     current_embeddings_file = input(f"Arquivo de Embeddings ({current_embeddings_file}) não encontrado. Informe o caminho correto: ")
+                eval_k_str = input(f"Informe o top_k para evaluate (pressione Enter para usar {default_eval_top_k}): ") or str(default_eval_top_k)
+                run_custom_step_or_exit([
+                    SCRIPT_MAP["evaluate"],
+                    current_cleaned_qa_file, current_embeddings_file,
+                    "-k", eval_k_str,
+                    "-o", current_eval_results_file
+                ])
+            elif step == "report_md":
+                 if not os.path.exists(current_eval_results_file):
+                     current_eval_results_file = input(f"Arquivo de Resultados da Avaliação ({current_eval_results_file}) não encontrado. Informe o caminho correto: ")
+                 report_k_str = input(f"Informe o top_k_chunks para report_md (pressione Enter para usar {default_eval_top_k}, deve coincidir com o usado na avaliação): ") or str(default_eval_top_k)
+                 run_custom_step_or_exit([
+                    SCRIPT_MAP["report_md"], current_eval_results_file, DEFAULT_MD_REPORT, report_k_str
+                ])
+            elif step == "report_html":
+                if not os.path.exists(current_eval_results_file):
+                     current_eval_results_file = input(f"Arquivo de Resultados da Avaliação ({current_eval_results_file}) não encontrado. Informe o caminho correto: ")
+                report_k_str = input(f"Informe o top_k_chunks para report_html (pressione Enter para usar {default_eval_top_k}, deve coincidir com o usado na avaliação): ") or str(default_eval_top_k)
+                run_custom_step_or_exit([
+                    SCRIPT_MAP["report_html"], current_eval_results_file, DEFAULT_HTML_REPORT, report_k_str
+                ])
+        print("⏹️ Fluxo customizado concluído.")
+
+if __name__ == "__main__":
+    main()