ADEX-CODEGEN (README)

O ADEX-CODEGEN é uma extensão avançada para Visual Studio Code desenvolvida para acelerar, automatizar e padronizar processos de GenAI, migração de código, engenharia de dados e desenvolvimento assistido dentro do ecossistema da Claro.

Baseado em pr

Nome do pacote (VS Code): adex-gpt Display name: ADEX-CODEGEN Atalhos e comandos: via Command Palette (Ctrl+Shift+P)

Visão geral

O ADEX-CODEGEN reúne, em uma única extensão:

• Migração PL/SQL → PySpark com pipeline multiagente (Parser → Mapper → Optimizer → Generator → Validator) e geração opcional de relatório.
• Chat técnico em WebView (assistente geral e assistentes especializados).
• Roteamento multi‑LLM (Azure OpenAI e/ou Hub GPU interno) com opções de fallback e modo ensemble + juiz.
• Observabilidade e governança: coleta de token usage, dashboards FinOps e LLM Governance, logs e métricas para pré‑prod.

Principais recursos

1) Migração PL/SQL → PySpark (multiagente)

Pipeline de migração com agentes especializados:

flowchart LR
  A[PL/SQL selecionado] --> B[ParserAgent]
  B --> C[MapperAgent]
  C --> D[OptimizerAgent]
  D --> E[GeneratorAgent]
  E --> F[ValidatorAgent]
  F --> G[Artefatos gerados]
  G --> H[migrated_pyspark.py]
  G --> I[analysis.json]
  G --> J[validation.json]
  G --> K[migration_report.md]

Como usar

1. Abra um arquivo PL/SQL e selecione um trecho.
2. Execute ADEX-GPT: Migrate PL/SQL to PySpark (adex-gpt.migrateCode) ou use o atalho.
3. Acompanhe o resultado no Migration Panel e nos artefatos gerados.

Atalho

• Windows/Linux: Ctrl + Alt + M
• macOS: Cmd + Alt + M

2) Roteamento multi‑LLM (Azure + Hub GPU + Juiz)

Você pode operar em três estratégias:

• azure-only: usa somente Azure OpenAI.
• hub-only: usa somente Hub GPU (ex.: gpt-oss-20b, gpt-oss-120b).
• ensemble-judge: executa gpt20 + gpt120 em paralelo e usa o Azure (ex.: gpt‑4o) como juiz para consolidar a resposta.

flowchart LR
  U[Prompt/solicitação] --> R[LLM Router]
  R -->|hub| M1[gpt-oss-20b]
  R -->|hub| M2[gpt-oss-120b]
  M1 --> J[Juiz (Azure)]
  M2 --> J
  J --> O[Resposta final + decisão]

3) Assistentes em WebView

• AI Chat: painel de chat genérico para troubleshooting, revisão e suporte.
• ADEX‑AIRFLOW Assistant: painel focado em autoria de DAGs, governança e padrões ADEX.
• Pré‑Prod Assistant (ADEX‑CODEGEN): painel com quick buttons e recursos FR‑00X, incluindo:
  • FR‑001: validar dicionário x script
  • FR‑005: sugestões PEP‑8
  • FR‑006: geração de registro de alterações (mudancas.md)
  • FR‑011: recomendações e geração de logs de execução
  • FR‑012: dashboard (modal) com métricas e séries temporais

4) Observabilidade, FinOps e Governança

• Token Usage: salva JSONs de execução em <outputDir>/token-usage/*.json.
• FinOps Dashboard: agrega token usage e mostra resumos por modelo e feature.
• LLM Governance Dashboard: visão consolidada de chamadas, roteamento e indicadores (baseado no token usage).
• Pré‑Prod logs: grava logs em docs/logs/preprod_execution_*.log.
• Pré‑Prod métricas (FR‑012): salva séries em docs/metrics/preprod_metrics_*.jsonl.

Requisitos

• VS Code ^1.105.0
• Node.js (para desenvolvimento da extensão)
• Permissão de leitura/escrita no workspace (para gerar artefatos e logs)

Instalação e uso rápido

1. Instale a extensão (VSIX interno ou marketplace privado).
2. Abra um workspace/pasta no VS Code.
3. Configure uma das opções abaixo:

Opção A — Azure OpenAI (mais simples)

Defina no settings.json:

{
  "adex-gpt.azureOpenAI.endpoint": "https://<seu-endpoint>.openai.azure.com/",
  "adex-gpt.azureOpenAI.deploymentName": "<deployment>",
  "adex-gpt.azureOpenAI.apiVersion": "2024-xx-xx",
  "adex-gpt.azureOpenAI.apiKey": "<sua-chave>"
}

Opção B — Hub GPU (gpt‑oss)

{
  "adex-gpt.hubGpu.enabled": true,
  "adex-gpt.hubGpu.gpt20.baseUrl": "https://<hub>/gpt20/v1",
  "adex-gpt.hubGpu.gpt20.model": "openai/gpt-oss-20b",
  "adex-gpt.hubGpu.gpt120.baseUrl": "https://<hub>/gpt120/v1",
  "adex-gpt.hubGpu.gpt120.model": "openai/gpt-oss-120b"
}

Opção C — Ensemble + Juiz (recomendado para confiabilidade)

{
  "adex-gpt.llmRouting.enabled": true,
  "adex-gpt.hubGpu.enabled": true,
  "adex-gpt.llmRouting.strategy": "ensemble-judge",
  "adex-gpt.llmRouting.timeoutMs": 300000,
  "adex-gpt.llmRouting.maxRetries": 2,
  "adex-gpt.llmRouting.temperature": 0
}

Comandos

Configurações (Settings)

| Setting | Tipo | Default | Descrição | | ----------------------------------------------- | --------: | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | adex-gpt.azureOpenAI.apiKey | string | | Azure OpenAI API Key (será lida da User/Workspace Settings; o comando 'ADEX-GPT: Enter API Key' salva no workspace). | | `adex-gpt.azureOpenAI.endpoint` | `string` | | Azure OpenAI Endpoint URL (ex.: https://.openai.azure.com) — sem barra no final. | | adex-gpt.azureOpenAI.deploymentName | string | | Nome do deployment do modelo no seu recurso (ex.: gpt-4o). | | `adex-gpt.azureOpenAI.apiVersion` | `string` | `2024-06-01` | API Version do Azure OpenAI (use uma versão suportada pelo seu recurso). | | `adex-gpt.features.enableOptimization` | `boolean` | `True` | Enable PySpark code optimization | | `adex-gpt.features.autoValidation` | `boolean` | `True` | Auto-validate migrated code | | `adex-gpt.features.generateDocumentation` | `boolean` | `True` | Generate migration documentation | | `adex-gpt.features.experimentalFeatures` | `boolean` | `False` | Enable experimental migration features (may be unstable). | | `adex-gpt.logging.level` | `string` | `info` | Logging level | | `adex-gpt.outputDir` | `string` | `.adex-gpt/migrations` | Pasta onde serão salvos os arquivos migrados. | | `adex-gpt.backupOnOverwrite` | `boolean` | `True` | Faz backup automaticamente antes de sobrescrever um arquivo existente. | | `adex-gpt.langfuse.enabled` | `boolean` | `False` | Habilita envio de telemetria de LLM para Langfuse. | | `adex-gpt.langfuse.host` | `string` | `https://cloud.langfuse.com` | URL da instância Langfuse. | | `adex-gpt.langfuse.publicKey` | `string` | | Public key da API Langfuse. | | adex-gpt.langfuse.secretKey | string | | Secret key da API Langfuse (NÃO comitar em Git). | | `adex-gpt.hubGpu.enabled` | `boolean` | `False` | Habilita uso de endpoints Hub GPUs (OpenAI compat /v1). | | `adex-gpt.hubGpu.apiKey` | `string` | | Opcional: Bearer token para o gateway Hub GPUs (se necessário). | | adex-gpt.hubGpu.gpt20.baseUrl | string | https://hub-gpus.claro.com.br/gpt20/v1 | Base URL do endpoint gpt20 (sem barra final). | | adex-gpt.hubGpu.gpt20.model | string | openai/gpt-oss-20b | Nome do modelo para gpt20 (campo 'model' no body). | | adex-gpt.hubGpu.gpt120.baseUrl | string | https://hub-gpus.claro.com.br/gpt120/v1 | Base URL do endpoint gpt120 (sem barra final). | | adex-gpt.hubGpu.gpt120.model | string | openai/gpt-oss-120b | Nome do modelo para gpt120 (campo 'model' no body). | | adex-gpt.llmRouting.enabled | boolean | False | Ativa o roteador de LLM (Azure + Hub GPUs). | | adex-gpt.llmRouting.strategy | string | azure-only | Estratégia: azure-only, hub-only, ou gpt20+gpt120 em paralelo com gpt-4o como juiz. | | adex-gpt.llmRouting.timeoutMs | number | 120000 | Timeout (ms) das chamadas aos modelos (Hub e Azure). | | adex-gpt.llmRouting.maxRetries | number | 2 | Retries para Hub GPUs (em erro/transiente). | | adex-gpt.llmRouting.temperature | number | 0.1 | Temperatura para Hub GPUs. | | adex-gpt.llmRouting.judgeMaxTokens | number | 2048 | Max tokens para a chamada do juiz (Azure/gpt-4o). | | adex-gpt.llmRouting.refineWhenSingleCandidate | boolean | False | Quando strategy=ensemble-judge e apenas 1 candidato (gpt20 ou gpt120) responder, chama o Azure/gpt-4o para refinamento final antes de responder ao usuário. | | adex-gpt.llmRouting.refineMaxTokens | number | 1024 | Max tokens para a chamada de refinamento (Azure/gpt-4o) quando refineWhenSingleCandidate=true. |

Configurações avançadas (opcionais via settings.json)

Além das settings expostas no contributes.configuration, o código também lê (se você declarar manualmente):

• adex-gpt.azureOpenAI.timeout
• adex-gpt.azureOpenAI.maxRetries
• adex-gpt.azureOpenAI.temperature

Estrutura de saída e artefatos

Por padrão, os artefatos são gravados em:

• adex-gpt.outputDir (default: .adex-gpt/migrations)

Exemplo típico:

.adex-gpt/migrations/
  20260203-12-34-56/
    migrated_pyspark.py
    analysis.json
    validation.json
    migration_report.md
  token-usage/
    <feature>-<timestamp>-<rand>.json
docs/
  token-usage/               # sincronizado pelo Orchestrator (quando aplicável)
  logs/
    preprod_execution_*.log  # FR-011
  metrics/
    preprod_metrics_*.jsonl  # FR-012

Dashboards

FinOps Dashboard

Use o comando: ADEX-CODEGEN: FinOps Dashboard (adex.finOpsDashboard)

LLM Governance Dashboard

Use o comando: ADEX-CODEGEN: LLM Governance Dashboard (adex.llmGovernanceDashboard)

Segurança e boas práticas

• Nunca commite chaves (apiKey, secretKey) no repositório.
• Para ambientes corporativos, prefira armazenar segredos em cofre/variáveis e injetar via policy.
• O assistente de Airflow inclui regras de governança e restrição de fontes/datasets no system prompt (DataSecOps).

Desenvolvimento

npm install
npm run compile
npm run lint
npm test

Gerar pacote VSIX:

npm run package

Known issues

• Workspaces sem permissão de escrita impedem geração de artefatos (migrations/logs/métricas).
• O modo ensemble-judge depende de conectividade Hub GPU + Azure.
• JSONs de token usage só são gerados quando a camada de telemetria está ativa na feature/fluxo executado.

Release notes

0.0.1

• Migração PL/SQL → PySpark (multiagente) e Migration Panel
• AI Chat / Airflow Assistant / Pré‑Prod Assistant
• Roteamento multi‑LLM (Azure / Hub / Juiz)
• Token usage + dashboards FinOps e LLM Governance
• Logs e métricas (FR‑011 / FR‑012)

Following extension guidelines

Para garantir qualidade e consistência, a extensão segue as diretrizes oficiais de extensões VS Code:

• Extension Guidelines

Working with Markdown

Você pode editar este README usando o Visual Studio Code. Algumas teclas úteis:

• Dividir editor:Ctrl + \
• Toggle Preview:Ctrl + Shift + V
• Sugestões de Markdown:Ctrl + Space

For more information

• Visual Studio Code's Markdown Support
• Markdown Syntax Reference

**Enjoy!

ISC