Projeto completo: uma área de atendimento com AI Dev Kit.

brew tap databricks/tap
brew install databricks
databricks --version

winget install Databricks.DatabricksCLI
databricks --version

databricks --version
uv --version
gh --version
claude --version

# uv — gerenciador de pacotes Python
curl -LsSf https://astral.sh/uv/install.sh | sh

# GitHub CLI
brew install gh
gh auth login

# Claude Code
curl -fsSL https://claude.ai/install.sh | bash

databricks auth login --host https://SEU-WORKSPACE.cloud.databricks.com

databricks auth profiles
databricks current-user me --profile grid_intelligence

gh repo create

cd LakehouseDatabricks

gh repo edit --description "Area de atendimento de uma distribuidora de energia no Databricks: medalhao, dashboard e copiloto conversacional, construidos com Claude Code e as skills do AI Dev Kit."

# de quebra, os topicos — e como o repositorio aparece nas buscas por tema
gh repo edit --add-topic databricks,lakehouse,claude-code,engenharia-de-dados,ai-dev-kit

databricks bundle init --profile grid_intelligence

cd grid_intelligence

bundle:
  name: grid_intelligence
  uuid: 338627ac-9807-4d4a-9ee6-aed306449a0a

include:
  - resources/*.yml

artifacts:
  python_artifact:
    type: whl
    build: uv build --wheel

variables:
  catalog:
    description: The catalog to use
  schema:
    description: The schema to use

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://SEU-WORKSPACE.cloud.databricks.com
    variables:
      catalog: workspace
      schema: ${workspace.current_user.short_name}

  prod:
    mode: production
    workspace:
      host: https://SEU-WORKSPACE.cloud.databricks.com
      root_path: /Workspace/Users/SEU-EMAIL/.bundle/${bundle.name}/${bundle.target}
    variables:
      catalog: workspace
      schema: prod
    permissions:
      - user_name: SEU-EMAIL
        level: CAN_MANAGE

# 1. confere a sintaxe e resolve as variaveis, sem tocar no workspace
databricks bundle validate -t dev --profile grid_intelligence

# 2. constroi o wheel, sobe os arquivos e cria os recursos
databricks bundle deploy -t dev --profile grid_intelligence

# 3. executa um recurso especifico, pela CHAVE dele no YAML
#    (agora so existe o sample_job que veio do template)
databricks bundle run sample_job -t dev --profile grid_intelligence

# ver o que existe la, sem abrir a interface
databricks bundle summary -t dev --profile grid_intelligence

uv python pin 3.12
uv venv --seed
uv sync --dev

git add .
git commit -m "Adiciona projeto inicial Declarative Automation Bundle"
git push

databricks aitools install

# consulta direta — ele acha o warehouse sozinho
databricks experimental aitools tools query --profile grid_intelligence \
  "SELECT current_catalog(), current_user()"

# conhecer uma tabela: colunas, tipos, amostra, nulos e contagem
databricks experimental aitools tools discover-schema \
  grid_dev.bronze.chamados --profile grid_intelligence

# rodar um arquivo .sql versionado no repositorio
databricks experimental aitools tools query --file src/sql/checagens.sql \
  --profile grid_intelligence

# varias consultas EM PARALELO, saida em JSON
databricks experimental aitools tools query --profile grid_intelligence \
  "SELECT count(*) FROM grid_dev.bronze.interrupcoes" \
  "SELECT count(*) FROM grid_dev.silver.interrupcoes_validas"

# exportar para CSV
databricks experimental aitools tools query --output csv --profile grid_intelligence \
  "SELECT * FROM grid_dev.gold.painel_operacional_dia" > painel.csv

Liste os catálogos do meu workspace usando o profile grid_intelligence

databricks catalogs list --profile grid_intelligence
databricks schemas list grid_dev --profile grid_intelligence
databricks volumes list grid_dev raw --profile grid_intelligence

# Prompt 00 — Setup e planejamento

> **Como usar:** cole este texto inteiro no Claude Code, dentro do repositório do projeto.
> Ele é o primeiro de uma sequência de **8 prompts**. Cada um entrega uma feature completa,
> com deploy e resultado visível. Não pule a ordem: cada prompt assume o anterior pronto.

---

Você vai me ajudar a construir a plataforma de dados e IA de uma distribuidora de energia
elétrica fictícia, a **Luz do Vale Distribuidora S.A.**, no Databricks. O projeto se chama
**Grid Intelligence**.

Este é o **prompt 1 de 8**. Neste primeiro, quero apenas o alicerce: entender o domínio,
registrar as regras de negócio e criar a infraestrutura. Não construa transformação,
dashboard nem agente agora — cada um tem o seu prompt.

## Contexto de negócio

Uma distribuidora de energia opera sob regulação da ANEEL e tem três dores simultâneas,
todas mensuráveis em dinheiro:

1. **Continuidade do fornecimento.** Interromper além do limite regulatório gera
   compensação financeira automática ao consumidor. Em 2024 as distribuidoras brasileiras
   pagaram mais de R$ 1,1 bilhão em compensações.
2. **Perdas não técnicas.** Energia distribuída e não faturada — furto, fraude e erro de
   medição. Em 2025 somaram ~R$ 11,5 bilhões, dos quais ~R$ 7,9 bilhões foram repassados
   à tarifa.
3. **Atendimento ao cliente.** Milhares de ligações viram transcrição e ninguém lê. Dentro
   delas está o aviso antecipado da reclamação na ouvidoria.

## Glossário — use estes termos, sem sinônimo aproximado

| Termo | Definição |
|---|---|
| **UC — Unidade Consumidora** | O ponto de entrega de energia. **Não é sinônimo de cliente**: um cliente pode ter várias UCs |
| **Conjunto** | Subdivisão geográfica da área de concessão. É a unidade de agregação do regulador |
| **DEC** | Duração Equivalente de Interrupção por UC — tempo médio, em horas, sem fornecimento |
| **FEC** | Frequência Equivalente de Interrupção por UC — número médio de interrupções |
| **PNT** | Perdas Não Técnicas |
| **Prioridade de inspeção** | Classificação de quanto uma UC merece visita técnica |

## Regras de negócio que valem para o projeto inteiro

- **RN-01** — Só interrupções com **3 minutos ou mais** entram na apuração de DEC e FEC.
  A regra vive na camada de transformação, nunca no relatório.
- **RN-04** — DEC e FEC têm **uma única definição** no sistema, consumida por dashboard,
  agente e relatório.
- **RN-06** — Uma UC é candidata a inspeção quando o consumo cai em **dois eixos
  simultâneos**: contra o próprio baseline **e** enquanto a vizinhança permanece estável.
  Só o primeiro eixo apontaria o bairro inteiro depois de um apagão.
- **RN-07** — A saída da detecção é **prioridade de inspeção** — alta, média, baixa.
  **Nunca** um rótulo de fraude, furto ou culpa. Queda de consumo também é mudança de
  morador, imóvel desocupado, defeito de medidor e erro de leitura. Em setor regulado a
  diferença é jurídica. Nenhuma coluna, variável ou comentário do projeto pode usar as
  palavras "fraude", "furto" ou "culpado" como rótulo de saída.
- **RN-09** — Dado pessoal em transcrição é **mascarado antes** de qualquer análise de
  conteúdo.
- **RN-10** — O texto original identificado é preservado com **acesso restrito**. Duas
  proteções que coexistem: uma na leitura, outra na análise.
- **RN-11** — A camada de ingestão **não filtra, não corrige e não aplica regra de
  negócio**. Leitura inválida de medidor é um fato sobre o medidor. Filtrar na ingestão
  parece limpeza; é destruição de evidência.
- **RN-12** — Todo registro ingerido carrega origem e momento de ingestão.
- **RN-13** — O agente conversacional acessa **apenas a camada de negócio**.
- **RN-14** — As entidades da **camada gold** carregam descrição em linguagem de negócio —
  é o que o agente lê. Bronze e silver não precisam: são passagem.

## Diretriz de simplicidade — vale para todos os 8 prompts

Este projeto é construído **ao vivo, em aula**. Código que ninguém consegue ler na tela em
dez segundos não serve, mesmo que seja mais robusto.

**Escreva o mínimo que faz a coisa funcionar:**

- **Sem expectations e sem `CONSTRAINT`** nas tabelas. Regra de negócio vira `WHERE`, que
  qualquer pessoa lê sem precisar saber o que é `ON VIOLATION`.
- **Sem `COMMENT` em bronze e silver.** Elas são passagem. Só a **gold** e a **metric view**
  levam descrição — são o que o agente conversacional lê, e ali a curadoria é o produto
  (RN-14).
- **Sem `TBLPROPERTIES`, `CLUSTER BY` e afins**, a menos que sem eles quebre.
- **Sem tratamento de caso que o dataset não tem.** Não invente defesa para dado que não
  existe.
- **Um `SELECT` direto vence um `WITH` de quatro CTEs.** Só quebre em CTE quando a query
  realmente não couber de cabeça.

Comentário no código só onde a decisão **não é óbvia pelo código** — a regra dos 3 minutos
merece duas linhas explicando por quê; um `CAST` não merece nenhuma.

Se em algum momento você achar que o certo é acrescentar validação, **não acrescente**: me
diga em uma linha o que faria, e eu decido.

## Convenções obrigatórias

- Todo texto e todo nome em **português do Brasil**; nomes de entidades, colunas e
  arquivos **sem acentuação**.
- **Nenhum nome de catálogo fixado em código.** Catálogo vem de `${var.catalog}` no
  `databricks.yml`; schema vem de `${resources.schemas.<camada>.name}`.
- **Nenhum nome de modelo de IA fixado no código.** Use as funções `ai_*` do Databricks.
- Perfil da CLI: `grid_intelligence`. Todo comando leva `--profile grid_intelligence`.

## Os dados

Quatro bases sintéticas, já geradas, em Parquet. **Baixe aqui:**

<https://drive.google.com/file/d/1o3NISve_wWygDWecBiiYTB8i2WXN7hbi/view?usp=sharing>

Descompacte e você terá uma pasta por base, com um único arquivo Parquet dentro.

| Base | Grão | Volume |
|---|---|---|
| `unidades_consumidoras` | uma por ponto de entrega | 4.000 |
| `interrupcoes` | uma por evento de rede | 1.383 |
| `consumo_diario` | uma por UC por dia | **~5,85 milhões** (4 anos) |
| `chamados` | uma por ligação, com transcrição | 2.801 |

O dataset tem **quatro anos de histórico**, crescimento de **30% ao ano** na carga e
**sazonalidade de verão** no atendimento (dezembro a março recebem quase o dobro de
ligações). Ele carrega **defeitos propositais** — consumo nulo, negativo, fisicamente
impossível, linhas duplicadas e interrupções abaixo de 3 minutos. Não são bug: existem
para as validações de qualidade e a RN-01 terem o que fazer.

## O que fazer agora

1. **Leia a skill `databricks-core`** antes de qualquer comando, e depois a
   `databricks-dabs`.
2. Escreva **`.llm/prd.md`** com o contexto acima: domínio, glossário, regras de negócio,
   modelo de informação e as quatro entregas de negócio previstas. É o documento que todos
   os prompts seguintes vão consultar.
3. **Crie os catálogos** (ver abaixo).
4. Crie no bundle os **schemas** `raw`, `bronze`, `silver` e `gold`, e o **volume**
   `raw.landing`. Um schema por camada — o nome do schema já é a camada, então as tabelas
   dentro dele não repetem o prefixo (`bronze.chamados`, nunca `bronze_chamados`).
5. Configure `dev` e `prod` isolados **por catálogo**, não por nome de schema.
6. Rode `databricks bundle validate` e `databricks bundle deploy -t dev`.
7. Me diga exatamente **onde subir os arquivos de dados**, com o caminho completo.

## Os catálogos

Dois catálogos, um por ambiente. É o catálogo que isola dev de produção — os schemas mantêm os
nomes exatos `raw`, `bronze`, `silver` e `gold` nos dois lados, para que o mesmo SQL rode em
qualquer ambiente sem uma linha diferente.

| Ambiente | Catálogo | Quem usa |
|---|---|---|
| `dev` | `grid_dev` | você, no dia a dia |
| `prod` | `grid_intelligence` | o ambiente final, depois de validado em dev |

**Catálogo é a única coisa que o bundle não cria** — é recurso de conta, e o deploy assume que já
existe. Schemas e volume ficam no bundle; catálogo, não.

Crie os dois **por SQL**, e não com `databricks catalogs create`:

```bash
databricks experimental aitools tools query --profile grid_intelligence \
  "CREATE CATALOG IF NOT EXISTS grid_dev COMMENT 'Catalogo de desenvolvimento da Grid Intelligence'"

databricks experimental aitools tools query --profile grid_intelligence \
  "CREATE CATALOG IF NOT EXISTS grid_intelligence COMMENT 'Catalogo de producao da Grid Intelligence'"

databricks catalogs list --profile grid_intelligence
```

**Por que SQL e não `catalogs create`:** em qualquer conta com Default Storage ligado — o caso da
Free Edition — a API por trás do comando exige um `storage_root` explícito e devolve
`Metastore storage root URL does not exist`. O `CREATE CATALOG` por SQL usa o armazenamento padrão
da conta e passa. Se até ele reclamar, me avise: aí o caminho é a interface, em Catalog → Create
catalog.

Depois, conceda permissão ao meu usuário nos dois catálogos:

```bash
databricks grants update CATALOG grid_dev \
  --json '{"changes":[{"principal":"SEU-EMAIL","add":["ALL_PRIVILEGES"]}]}' \
  --profile grid_intelligence
```

Catálogo sem *grant* é catálogo inútil: o pipeline falha depois com
`user does not have permission to CREATE SCHEMA`.

### Recomeçar do zero

Se um catálogo já existir e eu quiser recomeçar limpo, o comando é destrutivo e **não pergunta
duas vezes** — `CASCADE` remove schemas, tabelas, volumes e os arquivos dentro deles:

```bash
databricks experimental aitools tools query --profile grid_intelligence \
  "DROP CATALOG IF EXISTS grid_dev CASCADE"
```

**Sempre confirme comigo antes de rodar isso.** Deixe o comando registrado no README, na seção de
setup, com o aviso de que é destrutivo.

## Os schemas e o volume, no bundle

Declare em `resources/grid_schemas.yml`:

- os schemas `raw`, `bronze`, `silver` e `gold`
- o volume **managed** `landing`, dentro de `raw`

Nomes de schema vêm de `${resources.schemas.<camada>.name}` onde forem referenciados; o catálogo
vem de `${var.catalog}`. **Nenhum dos dois escrito literalmente em qualquer arquivo.**

Adicione `experimental.skip_name_prefix_for_schema: true` ao `databricks.yml`. Sem isso, em
`mode: development` o bundle prefixa os schemas com meu nome de usuário e `bronze` vira
`meunome_bronze` — o isolamento entre ambientes é feito pelo catálogo, não pelo nome do schema.

Depois: `databricks bundle validate` e `databricks bundle deploy -t dev`.

## Onde vou subir os dados

Com o volume criado pelo deploy, me diga o caminho completo de cada base, no formato que eu possa
colar direto na interface de upload:

```
/Volumes/grid_dev/raw/landing/unidades_consumidoras/
/Volumes/grid_dev/raw/landing/interrupcoes/
/Volumes/grid_dev/raw/landing/consumo_diario/
/Volumes/grid_dev/raw/landing/chamados/
```

E me dê também o comando de subir tudo de uma vez pelo terminal, lembrando que **o caminho de
origem é o da minha máquina** — confira onde os Parquet estão antes de montar o comando:

```bash
databricks fs cp -r <PASTA_LOCAL> dbfs:/Volumes/grid_dev/raw/landing \
  --overwrite --profile grid_intelligence
```

O prefixo `dbfs:` é obrigatório mesmo para Volume do Unity Catalog.

Uma pasta por base, com um único arquivo Parquet dentro — inclusive a de consumo diário, com 5,85
milhões de linhas. É a pasta, e não o arquivo, que é o contrato com a camada bronze: se um dia uma
base precisar ser particionada, o pipeline não muda.

## Critério de aceite

- Os dois catálogos existem e eu tenho `ALL PRIVILEGES` nos dois
- O comando de derrubar o catálogo está documentado no README, com o aviso de que é destrutivo
- `databricks bundle validate --profile grid_intelligence` passa sem erro
- `databricks bundle deploy -t dev` cria os quatro schemas e o volume `raw.landing`
- Os schemas **não** têm meu nome de usuário como prefixo
- Nenhum nome de catálogo ou schema aparece escrito literalmente no código
- Recebi os quatro caminhos de upload e o comando de `fs cp`
- `.llm/prd.md` existe e contém o glossário e as 14 regras de negócio

## O que vem depois

Não faça nada disso agora — cada item é um prompt próprio:

| # | Prompt | Entrega |
|---|---|---|
| 01 | Camada bronze | Ingestão fiel do volume, sem regra de negócio |
| 02 | Silver — os números | Cadastro limpo, a regra dos 3 minutos, dedup e baseline |
| 03 | Silver — o texto | Anonimização e enriquecimento das transcrições — com IA ou por regex |
| 04 | Camada gold | As quatro entregas de negócio e a metric view de DEC/FEC |
| 05 | Dashboard | Painel AI/BI sobre a gold |
| 06 | Agente | Copiloto conversacional em português |
| 07 | Relatório e demonstração | Relatório executivo e as queries que provam tudo |

Quando terminar o setup, me diga o que criou e pare. Eu envio o próximo.

databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence
databricks bundle summary  -t dev --profile grid_intelligence

# confira ONDE estao os seus Parquet antes de rodar
ls landing/

# o -r sobe a arvore inteira, com as quatro pastas
databricks fs cp -r landing dbfs:/Volumes/grid_dev/raw/landing \
  --overwrite --profile grid_intelligence

databricks fs ls dbfs:/Volumes/grid_dev/raw/landing --profile grid_intelligence

# Prompt 01 — Camada bronze

> **Prompt 2 de 8.** Requer o prompt 00 concluído: schemas, volume e `.llm/prd.md` no lugar.

---

Leia `.llm/prd.md` antes de começar, inclusive a **diretriz de simplicidade**. Agora vamos
construir a **camada bronze** do medalhão da Grid Intelligence.

## O que quero

Um **Lakeflow Declarative Pipeline serverless** que ingere as quatro bases do volume
`raw.landing` para o schema `bronze`, uma tabela por base.

**Um arquivo só:** `src/pipelines/grid_intelligence/transformations/01_bronze.sql`, com as
quatro tabelas. Elas compartilham o mesmo padrão de ingestão, e separar em quatro arquivos
iguais só espalharia a mesma decisão por quatro lugares.

| Origem no volume | Tabela bronze | Linhas esperadas |
|---|---|---|
| `unidades_consumidoras/` | `bronze.unidades_consumidoras` | 4.000 |
| `interrupcoes/` | `bronze.interrupcoes` | 1.383 |
| `consumo_diario/` | `bronze.consumo_diario` | ~5,85 milhões |
| `chamados/` | `bronze.chamados` | 2.801 |

Todas são **streaming table**: ingestão é append de arquivo novo, e é o que o Auto Loader
sabe fazer de forma incremental.

Use **Auto Loader** (`STREAM read_files`) com formato Parquet. Aponte para a **pasta**, não
para o arquivo: hoje cada base ocupa um Parquet só, mas se uma delas precisar ser
particionada amanhã, nada muda no pipeline.

## O formato de cada tabela

Quatro blocos iguais a este, e nada além disso:

```sql
CREATE OR REFRESH STREAMING TABLE ${catalogo}.${schema_bronze}.interrupcoes
AS SELECT
  *,
  _metadata.file_path AS arquivo_origem,
  current_timestamp() AS ingerido_bronze_em
FROM STREAM read_files(
  '${volume_landing}/interrupcoes/',
  format => 'parquet'
);
```

**Sem expectations, sem `CONSTRAINT`, sem `COMMENT`, sem `CLUSTER BY`.** A bronze é
passagem: o que ela precisa fazer é copiar fielmente e dizer de onde veio.

As duas colunas extras são a RN-12: `arquivo_origem` e `ingerido_bronze_em`. As colunas
`origem` e `ingerido_em` que já vêm do dado dizem de que *sistema* ele saiu; estas duas
dizem por onde ele *entrou* aqui.

## A regra que manda neste arquivo: RN-11

**A ingestão não aplica regra de negócio, não filtra e não corrige.**

Consumo negativo, leitura impossível, interrupção de 40 segundos, cadastro com bairro
vazio — tudo entra exatamente como chegou. Filtrar aqui pareceria limpeza; é destruição de
evidência. Quem descarta é a silver, com regra nomeada e visível no `WHERE`.

O `SELECT *` acima não é preguiça: é a RN-11 escrita em código. Qualquer coluna que você
listasse à mão seria uma decisão sobre o que vale a pena guardar — e essa decisão não é da
bronze.

## Parametrização

O pipeline recebe por `configuration`: catálogo, nome de cada schema, caminho do volume e
o limiar de duração mínima de interrupção. **Nenhum nome de catálogo escrito dentro do
SQL** — os arquivos usam `${catalogo}.${schema_bronze}.<tabela>`, e o valor vem do
`databricks.yml`.

## Uma armadilha que quero registrada em comentário

Cada base ocupa um único arquivo, que é sobrescrito quando o dataset é regerado.
`allowOverwrites => true` faz o Auto Loader reprocessar o arquivo trocado, mas **streaming
table é append-only**: as linhas antigas continuam lá e o volume dobra. Deixe isso escrito
no topo do arquivo, junto com a solução — rodar o pipeline com **full refresh** depois de
regerar.

## Se o pipeline falhar com `DELTA_FEATURE_REQUIRES_MANUAL_ENABLEMENT: timestampNtz`

Vai acontecer. Os timestamps do dataset são **sem fuso horário** (`TIMESTAMP_NTZ`), e o
Delta exige habilitar essa feature explicitamente na tabela.

Há duas saídas, e uma delas está errada:

- **Converter para `TIMESTAMP` na ingestão** — assumiria um fuso que o dado não declara.
  Isso é transformação dentro da bronze, exatamente o que a RN-11 proíbe.
- **Habilitar a feature na tabela** — o tipo entra como chegou, e quem decide o fuso é a
  silver, se precisar.

Use a segunda. É a única exceção à regra de não usar `TBLPROPERTIES`:

```sql
CREATE OR REFRESH STREAMING TABLE ${catalogo}.${schema_bronze}.interrupcoes
TBLPROPERTIES ('delta.feature.timestampNtz' = 'supported')
AS SELECT ...
```

## Se a bronze não ingerir nada

Antes de investigar o Auto Loader, confira a precisão dos timestamps do Parquet:

```bash
databricks experimental aitools tools query --profile grid_intelligence \
  "SELECT * FROM parquet.`/Volumes/grid_dev/raw/landing/interrupcoes/` LIMIT 1"
```

Parquet gravado por pandas sem tratamento fica com `timestamp[ns]`, e **o Spark não lê
nanossegundo**. O gerador deste projeto já converte para microssegundo; se o dado veio de
outro lugar, é a primeira coisa a checar — a falha não é óbvia e parece problema de caminho.

## Ao terminar

1. `databricks bundle deploy -t dev --profile grid_intelligence`
2. Rode o pipeline e me mostre o resultado
3. A contagem de linhas de cada tabela bronze
4. **Quanto defeito entrou**, com uma query só — é o que a silver vai ter de resolver:

```sql
SELECT
  count(*)                                                   AS eventos,
  count_if(duracao_minutos < 3)                              AS abaixo_de_3_min,
  round(100.0 * count_if(duracao_minutos < 3) / count(*), 1) AS pct
FROM grid_dev.bronze.interrupcoes
```

Deve voltar **1.383, 310 e 22,4%**. Esses 22,4% são exatamente o que a RN-01 vai descartar
no próximo prompt — e é bom ver o número antes, para reconhecê-lo depois.

## Critério de aceite

- As quatro tabelas bronze existem e têm o volume esperado
- Nenhuma linha foi filtrada, corrigida ou descartada
- Toda tabela tem `arquivo_origem` e `ingerido_bronze_em`
- Nenhum nome de catálogo aparece dentro do SQL
- Cada tabela cabe em uma tela

databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence
databricks bundle summary  -t dev --profile grid_intelligence

SELECT
  count(*)                                                   AS eventos,
  count_if(duracao_minutos < 3)                              AS abaixo_de_3_min,
  round(100.0 * count_if(duracao_minutos < 3) / count(*), 1) AS pct
FROM grid_dev.bronze.interrupcoes

# Prompt 02 — Silver: os números

> **Prompt 3 de 8.** Requer a bronze pronta e populada.

---

Leia `.llm/prd.md`, inclusive a **diretriz de simplicidade**. Agora a **camada silver**, na
parte numérica: cadastro, interrupções e consumo. O texto livre dos chamados fica para o
próximo prompt.

## O que este prompt cria

Três arquivos em `src/pipelines/grid_intelligence/transformations/`, quatro tabelas:

| Arquivo | Cria | Tipo | Grão |
|---|---|---|---|
| `10_silver_cadastro.sql` | `silver.unidades_consumidoras` | streaming table | uma UC |
| `11_silver_interrupcoes.sql` | `silver.interrupcoes_validas` | streaming table | um evento que passou na RN-01 |
| `12_silver_consumo.sql` | `silver.consumo_diario` | materialized view | UC × dia |
| `12_silver_consumo.sql` | `silver.baseline_consumo` | materialized view | uma UC |

**Por que 12 é materialized view e os outros dois não:** deduplicar exige olhar todas as
linhas da mesma chave, e baseline exige janela — as duas coisas são batch. Streaming table
enxerga só o lote novo, e serve bem para filtro linha a linha, que é o caso de 10 e 11.

**Sem expectations, sem `CONSTRAINT`, sem `COMMENT`.** Todo descarte desta camada é um
`WHERE` que se lê em voz alta.

## 1. `silver.unidades_consumidoras` — cadastro limpo

Streaming table a partir de `STREAM(bronze.unidades_consumidoras)`.

O gerador estraga uma fração pequena dos cadastros de propósito, e aqui é onde isso se
resolve — três casos, três expressões:

| Problema na origem | O que fazer |
|---|---|
| `classe_consumo` chega como `'  RESIDENCIAL '` | `lower(trim(classe_consumo))` |
| `bairro` chega vazio | `'nao informado'` — **não invente bairro** |
| UC sem chave ou sem conjunto | `WHERE id_uc IS NOT NULL AND id_conjunto IS NOT NULL` |

A normalização da classe não é frescura: sem ela o `GROUP BY` por classe devolve duas
linhas para a mesma classe, e o dashboard mostra "residencial" duas vezes.

Bairro faltando é um problema de cadastro que alguém precisa resolver na origem. Marcar
como `'nao informado'` preserva o fato; preencher com o bairro do vizinho o apagaria.

## 2. `silver.interrupcoes_validas` — a RN-01

**Este é o arquivo mais importante do prompt.** É onde a regra dos 3 minutos vive.

> Somente interrupções **de fornecimento** com duração maior ou igual a 3 minutos entram na
> apuração dos indicadores de continuidade.

O corte é sobre a coluna `duracao_minutos` de `bronze.interrupcoes`. Evento abaixo disso é o
religador atuando — galho na rede, desarme e religamento automático em segundos. O
consumidor vê a luz piscar; não é falta de energia. No dataset são 310 de 1.383 eventos,
22,4%.

A regra inteira é uma linha:

```sql
WHERE duracao_minutos >= ${duracao_minima_interrupcao_min}
```

Três coisas que quero explícitas:

1. **O limiar não pode ser `3` escrito no meio da query.** Ele vem da `configuration` do
   pipeline. A regra é do regulador, não do engenheiro: se a ANEEL mudar o limiar, muda-se
   uma linha de configuração.
2. **O descarte acontece aqui, uma vez.** Se cada área aplicasse o próprio filtro, cada
   uma calcularia um DEC diferente — e divergência de número entre relatórios internos é
   problema real em fiscalização.
3. **As interrupções curtas não somem do mundo:** continuam na bronze, onde qualquer um
   pode contá-las. O que elas não fazem é virar indicador.

Duas linhas de comentário acima do `WHERE`, explicando o religador. É o tipo de decisão que
o código não conta sozinho.

### As colunas derivadas — é aqui que o DEC começa

Filtrar não basta. Este arquivo prepara os insumos que a gold vai apenas somar:

| Coluna derivada | Expressão | Para quê |
|---|---|---|
| `data_evento` | `to_date(inicio)` | grão do painel operacional |
| `mes_apuracao` | `date_trunc('MONTH', inicio)` | grão da apuração (RN-05) |
| `duracao_horas` | `duracao_minutos / 60.0` | o indicador é em horas |
| **`uc_horas_interrompidas`** | `duracao_horas × qtd_ucs_afetadas` | **numerador do DEC (RN-02)** |
| `causa_climatica` | `causa = 'climatica'` | separa intempérie do resto |

**Por que o produto é calculado aqui e não na gold.** `uc_horas_interrompidas` é uma
quantidade **aditiva**: somar em qualquer recorte — mês, conjunto, ano — dá o número certo.
Se o produto fosse feito depois da agregação, seria média de média, que não é. Deixar o
insumo pronto no grão do evento é o que permite à metric view responder corretamente a
qualquer corte que o usuário pedir.

O numerador do FEC não precisa de coluna nova: é `qtd_ucs_afetadas`, que já vem da origem.

## 3. `silver.consumo_diario` — descarte e deduplicação

**Materialized view, não streaming table.** O motivo é concreto: o concentrador reenvia
leituras e a mesma chave `(id_uc, data)` chega duas vezes. Escolher uma das duas exige
olhar todas as linhas daquela chave — isso é batch, não streaming.

O que descartar, num `WHERE` só:

- consumo nulo — medidor sem comunicar no ciclo
- consumo negativo — erro de sinal no registrador
- consumo acima do limite físico da ligação

O **limite físico é definido aqui**, do lado de quem consome o dado, e não herdado do
gerador. Numa distribuidora é assim: quem recebe a telemetria estabelece o que considera
plausível para cada tipo de ligação. Use um `CASE` por classe de consumo.

Para a duplicata, `qualify row_number() over (partition by id_uc, data order by ingerido_em desc) = 1`
resolve em uma linha — não precisa de CTE.

Faça o join com o cadastro para que cada linha já carregue conjunto, bairro e classe — as
regras de perdas não técnicas não deveriam ter de refazer esse join.

## 4. `silver.baseline_consumo` — o insumo dos dois eixos

É a tabela que dá à RN-06 as duas comparações:

- **janela recente:** os últimos 30 dias do dataset
- **janela baseline:** os **90 dias imediatamente anteriores** a ela

### Por que o baseline não é "tudo que veio antes" — leia antes de simplificar

A carga da Luz do Vale cresce ~30% ao ano e o dataset tem quatro anos. Comparar os últimos
30 dias contra a média de todo o histórico acusa **alta de mais de 50% em toda UC do
sistema**, porque a média inclui o primeiro ano, quando o consumo era quase três vezes
menor. Resultado prático: o segundo eixo da RN-06 nunca considera a vizinhança estável e a
detecção de perdas para de funcionar por completo.

Baseline sobre série com tendência precisa de **janela comparável**. Noventa dias
imediatamente anteriores carregam ~4% de crescimento entre o centro de uma janela e o da
outra — ruído pequeno o bastante para a faixa de estabilidade absorver, e período longo o
bastante para a média não balançar com duas semanas atípicas.

### Outra armadilha

Ancore a janela no **maior dia do dataset**, nunca em `current_date()`. O dataset é
sintético e pode ter sido gerado semana passada; ancorar no relógio faz a análise deslizar
para fora do dado e devolver tabela vazia — sintoma clássico e chato de diagnosticar.

Calcule, por UC: média no baseline, média no recente, contagem de dias em cada janela, e a
variação percentual. E, por conjunto, as mesmas médias — é o segundo eixo.

## Ao terminar

Rode o pipeline e me mostre:

1. Quantas interrupções a RN-01 descartou, em número e em percentual — deve ser **310 de
   1.383**, sobrando **1.073**
2. Quantas linhas de consumo foram descartadas, e quantas duplicatas sumiram
3. A variação média do conjunto `CPQ-02` entre as duas janelas — precisa estar perto de
   zero, senão o segundo eixo não vai funcionar no próximo prompt

## Critério de aceite

- O limiar de 3 minutos vem de configuração, não está escrito no SQL
- `silver.interrupcoes_validas` tem 1.073 linhas
- `silver.consumo_diario` não tem consumo nulo, negativo ou acima do limite, nem chave
  `(id_uc, data)` repetida
- A variação do conjunto entre as janelas está dentro de ±10%
- Nenhuma expectation, nenhum `CONSTRAINT`, nenhum `COMMENT`
- Cada arquivo cabe em uma tela e meia

databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence
databricks bundle summary  -t dev --profile grid_intelligence

id_interrupcao  id_conjunto  duracao_minutos  causa              equipamento     ucs_afetadas
INT000393       VLH-01       0.31             climatica          transformador   21
INT000758       IDT-01       0.31             vegetacao          transformador   22
INT000257       CPQ-02       0.32             terceiros          ramal_ligacao   17

id_interrupcao  id_conjunto  duracao_minutos  causa              equipamento     ucs_afetadas
INT000971       SMR-01       480.00           sobrecarga         religador           17
INT000126       CPQ-01       388.18           falha_equipamento  chave_fusivel       11
INT001013       VRU-01       364.88           climatica          rede_baixa_tensao   38

# Prompt 03-A — Silver: o texto, com IA

> **Prompt 4 de 8, rota com IA.** Requer a silver numérica pronta. Existe uma rota irmã,
> `03-silver-texto-regex.md`, que entrega as mesmas colunas sem chamar modelo nenhum —
> escolha **uma das duas**. Os prompts seguintes funcionam igual nos dois casos.

---

Leia `.llm/prd.md`, inclusive a **diretriz de simplicidade**. Agora a parte da silver que
lida com **texto livre**: as transcrições das ligações para a central de atendimento. É o módulo de IA do projeto.

## O que este prompt cria

| Arquivo | Cria | Tipo | Grão |
|---|---|---|---|
| `src/pipelines/grid_intelligence/transformations/13_silver_chamados.py` | `silver.chamados_anonimizados` | materialized view | um chamado |
| o mesmo arquivo | `silver.chamados_enriquecidos` | materialized view | um chamado |
| `src/sql/governanca_dado_pessoal.sql` | column mask sobre `bronze.chamados` | task de SQL do job | — |

São 2.801 chamados. **Materialized view, não streaming table:** as funções de IA custam
tempo, e reprocessar tudo a cada lote novo seria caro sem necessidade.

O segundo arquivo fica **fora do pipeline**, e a seção da RN-10 explica por quê.

## Duas camadas, nesta ordem, e a ordem importa

1. **Anonimizar** (RN-09) — o texto perde nome, CPF, telefone e endereço
2. **Enriquecer** (RF-05) — sentimento, motivo, urgência e equipamento são extraídos do
   texto **já anonimizado**

Inverter isso mandaria dado pessoal identificado para a análise de conteúdo sem
necessidade nenhuma: sentimento e motivo do chamado não dependem do nome de quem ligou.
A chave da UC já identifica a unidade.

## `silver.chamados_anonimizados`

Use `ai_mask(transcricao, array('person', 'phone', 'address', 'ssn', 'email'))`.

A transcrição carrega nome, CPF e telefone **dentro da frase**, não só em coluna. Se o
mascaramento só limpasse as colunas, seria proteção de fachada.

Traga do cadastro: cliente, conjunto, bairro e classe da UC. Derive data e hora do chamado.

## `silver.chamados_enriquecidos`

A partir do texto anonimizado, extraia:

| Coluna | Como |
|---|---|
| `sentimento` | `ai_analyze_sentiment` |
| `motivo` | `ai_classify` com **rótulos descritos**, não só nomeados |
| `equipamento_citado` | `ai_extract` |
| `risco_a_saude` | termo de risco no texto: oxigênio, diálise, remédio, criança, hospital, faísca, incêndio |
| `urgencia` | alta se há risco à saúde; média para falta de energia, religação urgente e poste avariado; baixa no resto |
| `ameacou_ouvidoria` | o cliente citou ouvidoria, ANEEL, Procon ou processo |

**Descreva os rótulos do `ai_classify`.** É o que faz o classificador acertar entre
`religacao` e `religacao_urgente`, que são a mesma frase com uma pessoa em risco no meio.
Passe também `instructions` dizendo que são ligações para uma distribuidora de energia
brasileira — contexto de domínio melhora a precisão de forma mensurável.

**Nada disso vem pronto da origem.** A base de chamados não tem coluna de sentimento nem
de motivo, de propósito: se viesse pronta, este módulo seria um `SELECT`.

## RF-09 — o caminho sem IA no mesmo arquivo, e por que ele precisa ser Python

O projeto tem de funcionar em workspace sem as funções de IA. Dá para resolver de dois
jeitos: construir só a rota determinística (é o `03-silver-texto-regex.md`, e aí este
prompt não é usado) ou deixar **as duas no mesmo arquivo**, atrás de uma chave. É o que
este prompt pede — assim a mesma base de código roda nos dois workspaces.

Isso **não dá para fazer em SQL**: `${usar_ia}` é substituição de texto, então um `CASE WHEN 'false' = 'true' THEN
ai_analyze_sentiment(...)` continua mencionando a função e falha no parse quando ela não
existe.

Escreva este arquivo em **Python** (`from pyspark import pipelines as dp`). Em Python o
`if` acontece na hora de **definir** o dataset — o ramo não escolhido nem chega a ser
compilado.

Adicione `usar_ia` à `configuration` do pipeline, com padrão `"true"`. Quando `"false"`:

- anonimização por expressão regular, mascarando o nome que o próprio registro carrega em
  coluna mais os padrões de CPF e telefone
- sentimento e motivo por palavra-chave, com listas curtas e deliberadamente grosseiras —
  elas existem para o projeto não travar, não para competir com o modelo

**As colunas produzidas são as mesmas nos dois caminhos.** Muda a qualidade da extração,
não o schema. Registre em cada linha qual caminho foi usado (`anonimizado_por`,
`enriquecido_por`) — quem consulta a tabela precisa saber com o que está lidando.

## RN-10 — a outra metade da proteção

A RN-09 protegeu a análise. Falta proteger a leitura da origem.

Crie uma **column mask** do Unity Catalog: uma função que devolve o valor original para
membros do grupo de atendimento e `[RESTRITO]` para todo o resto. Aplique nas colunas
`nome_solicitante`, `telefone_solicitante` e `transcricao` de `bronze.chamados`.

Quem está no atendimento vê o telefone do cliente — precisa dele para retornar a ligação.
Todo o resto não vê.

**Atenção:** `bronze.chamados` é materializada pelo pipeline, e um full refresh recria a
tabela e derruba a máscara. Ponha isso numa task do job que roda **depois** do pipeline, a
cada execução, e deixe a limitação escrita em comentário.

## Ao terminar

Me mostre:

1. Uma transcrição antes e depois do mascaramento, lado a lado
2. A distribuição de `motivo` e `sentimento`
3. Quantos chamados têm `risco_a_saude` e quantos citaram ouvidoria
4. O resultado de consultar `bronze.chamados` — as colunas mascaradas devem aparecer como
   `[RESTRITO]`, a menos que você esteja no grupo

## Critério de aceite

- Nenhum nome, CPF ou telefone sobrevive em `chamados_anonimizados`
- O enriquecimento lê o texto anonimizado, nunca o original
- Trocar `usar_ia` para `"false"` produz as mesmas colunas, sem erro
- A column mask está aplicada e funciona
- Nenhum nome de modelo de IA aparece no código

databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence
databricks bundle summary  -t dev --profile grid_intelligence

Boa tarde, Lavínia Souza falando, CPF 941.278.036-22, instalacao UC0001147.
Meu transformador soltou faisca ontem, tem risco de incendio aqui. Se puder me
avisar por mensagem eu agradeco.

SELECT
  id_chamado,

  ai_mask(transcricao, array('person', 'phone', 'ssn'))       AS texto_seguro,

  ai_analyze_sentiment(transcricao)                            AS sentimento,

  ai_classify(
    transcricao,
    '{"falta_energia":   "Cliente esta sem fornecimento agora",
      "poste_avariado":  "Poste ou equipamento danificado na via publica",
      "fatura_alta":     "Contestacao de valor da conta"}'
  ):response[0]::STRING                                        AS motivo,

  ai_extract(
    transcricao, '["equipamento_eletrico"]'
  ):response:equipamento_eletrico::STRING                      AS equipamento

FROM grid_dev.bronze.chamados
LIMIT 10

# Prompt 04 — Camada gold e a metric view

> **Prompt 5 de 8.** Requer a silver completa — números e texto.
>
> Duas das quatro entregas (`saude_cliente` e `painel_operacional_dia`) dependem dos sinais
> extraídos das transcrições. Eles **não precisam de IA**: menção a ouvidoria/ANEEL/Procon,
> risco à saúde e motivo do chamado são termos explícitos, e uma classificação por termo é
> auditável palavra por palavra — o que em setor regulado vale mais do que alguns pontos de
> acurácia. Se a silver de texto não existir ainda, construa-a por regra determinística
> antes de seguir; leva segundos.

---

Leia `.llm/prd.md`, inclusive a **diretriz de simplicidade**. Agora a **camada gold**: as
entregas de negócio.

Uma ressalva à diretriz, e vale só aqui: **a gold leva `COMMENT`**. Ela é a camada que o
agente conversacional lê, e ali a descrição não é documentação — é o que faz o agente
acertar (RN-14). Continua valendo o resto: sem expectations, sem `CONSTRAINT`, sem CTE que
não precise existir.

Regra de nomenclatura que vale para a camada inteira: **se o nome da tabela não é uma
pergunta de negócio, a entrega ainda não está pronta.**

## O que este prompt cria

Cinco arquivos, cinco objetos. Todos em `src/pipelines/grid_intelligence/transformations/`,
exceto o último:

| Arquivo | Cria | Grão | Pergunta que responde |
|---|---|---|---|
| `20_gold_continuidade.sql` | `gold.continuidade_conjunto_mes` | conjunto × mês | Estamos dentro do limite regulatório este mês? |
| `21_gold_prioridade_inspecao.sql` | `gold.prioridade_inspecao_uc` | uma UC candidata | Quais UCs merecem visita técnica primeiro? |
| `22_gold_saude_cliente.sql` | `gold.saude_cliente` | um cliente | Quais clientes estão em rota de reclamação na ouvidoria? |
| `23_gold_painel_operacional.sql` | `gold.painel_operacional_dia` | conjunto × dia | O que aconteceu ontem e o que precisa de ação hoje? |
| `src/sql/metric_view_continuidade.sql` | `gold.continuidade_metricas` | — | **A definição de DEC e FEC** |

Todas as quatro tabelas são **materialized view**: agregação sobre janela e `GROUP BY` não
cabem em streaming table, que é append-only e enxerga só o lote novo.

O quinto arquivo **fica fora do pipeline** e roda como task de SQL do job. Metric view não é
dataset do Lakeflow.

## 1. Continuidade — e a RN-04, que é a lição central do projeto

### Os dois indicadores, antes do código

Ambos são **médias por unidade consumidora do conjunto**, apuradas por mês (RN-05):

```
        Σ (duracao_horas × qtd_ucs_afetadas)              Σ qtd_ucs_afetadas
DEC  =  ────────────────────────────────────      FEC  =  ──────────────────────
             total de UCs do conjunto                     total de UCs do conjunto

     "quantas horas, em média, cada UC              "quantas vezes, em média, cada UC
      do conjunto ficou sem energia"                 do conjunto ficou sem energia"
```

**O denominador é o total de UCs do conjunto, não a contagem de atingidas.** Um evento de
2 horas que atinge 50 de 800 UCs vale `2 × 50 / 800 = 0,125 h` de DEC — a duração diluída em
toda a base, inclusive em quem não ficou sem luz. É o que torna conjuntos de tamanhos
diferentes comparáveis. Se o denominador fosse "UCs atingidas", o indicador devolveria
sempre a duração média do evento e Sumaré pareceria tão bem atendida quanto Campinas.

O numerador do DEC **já vem pronto da silver**: `uc_horas_interrompidas`, calculado em
`11_silver_interrupcoes.sql`. Aqui ele só é somado.

### `gold.continuidade_conjunto_mes` — as colunas

Grão: uma linha por `(id_conjunto, mes_apuracao)`. Origem: `silver.interrupcoes_validas`
agregada, com `INNER JOIN` em `silver.unidades_consumidoras` para trazer o total de UCs.

| Coluna | O que é | Papel |
|---|---|---|
| `id_conjunto` | chave do conjunto | grão |
| `nome_conjunto`, `municipio` | rótulos legíveis | dimensão do dashboard |
| `mes_apuracao` | `date_trunc('MONTH', inicio)` | grão (RN-05) |
| `total_ucs` | `count(*)` das UCs do conjunto | **denominador** de DEC e FEC |
| `uc_horas_interrompidas` | `sum(duracao_horas × qtd_ucs_afetadas)` | **numerador do DEC** |
| `uc_interrupcoes` | `sum(qtd_ucs_afetadas)` | **numerador do FEC** |
| `qtd_interrupcoes` | `count(*)` dos eventos | contexto |
| `qtd_interrupcoes_climaticas` | eventos com causa climática | separa o que é intempérie |
| `qtd_interrupcoes_programadas` | eventos com aviso prévio | têm tratamento regulatório diferente |
| `maior_duracao_horas` | `max(duracao_horas)` | o pior evento do mês |

Sem expectations. O `INNER JOIN` com o cadastro já garante que todo conjunto tem UC — e
conjunto sem UC dividiria por zero.

### Por que a tabela não tem coluna de DEC

Aqui vem a parte contraintuitiva: **a tabela gold de continuidade não tem coluna
`dec_horas`.**

Se a tabela calculasse o DEC e a metric view calculasse de novo, seriam **duas
definições** — e no dia em que a fórmula mudar, alguém atualiza uma e esquece a outra.
Foi assim que a empresa acabou com três DECs diferentes circulando.

A divisão de trabalho é:

- **a tabela** guarda os **insumos aditivos**: horas-UC interrompidas, interrupções-UC e o
  total de UCs do conjunto. Somar insumo em qualquer recorte dá o número certo.
- **a metric view** guarda a **definição**: `DEC = horas-UC / total de UCs`. Uma só,
  versionada em `src/sql/metric_view_continuidade.sql`, consumida por dashboard, agente e
  relatório.

### A metric view — `gold.continuidade_metricas`

`CREATE OR REPLACE VIEW ... WITH METRICS LANGUAGE YAML`, sobre
`continuidade_conjunto_mes`.

**Dimensões:** `Conjunto` (de `nome_conjunto`), `Codigo do Conjunto`, `Municipio`, `Mes`.

**Medidas — dez, cada uma uma expressão sobre as colunas da tabela acima:**

| Medida | Expressão | Formato |
|---|---|---|
| `DEC` | `SUM(uc_horas_interrompidas) / SUM(total_ucs)` | `#,##0.00` |
| `FEC` | `SUM(uc_interrupcoes) / SUM(total_ucs)` | `#,##0.00` |
| `DEC Acumulado` | ver armadilha 3 — fórmula **diferente** da do `DEC` | `#,##0.00` |
| `Interrupcoes` | `SUM(qtd_interrupcoes)` | `#,##0` |
| `Interrupcoes Climaticas` | `SUM(qtd_interrupcoes_climaticas)` | `#,##0` |
| `Proporcao Climatica` | `SUM(climaticas) / NULLIF(SUM(interrupcoes), 0)` | `0.0%` |
| `Interrupcoes Programadas` | `SUM(qtd_interrupcoes_programadas)` | `#,##0` |
| `Horas UC Interrompidas` | `SUM(uc_horas_interrompidas)` | `#,##0.0` |
| `Maior Interrupcao` | `MAX(maior_duracao_horas)` | `#,##0.00` |
| `Total de UCs` | ver armadilha 3 | `#,##0` |

O `NULLIF` na proporção não é preciosismo: mês sem interrupção nenhuma existe no dataset, e
sem ele a view quebra na divisão por zero.

Coloque `synonyms` nas dimensões e nas medidas principais — `DEC` precisa responder a
"quantas horas sem luz", `Conjunto` a "região". É o que o agente do prompt 06 vai usar para
traduzir a pergunta do gestor. E `comment` em tudo (RN-14).

**Como se consulta:**

```sql
SELECT `Conjunto`, MEASURE(`DEC`), MEASURE(`FEC`)
FROM ${catalogo}.${schema_gold}.continuidade_metricas
WHERE `Mes` = '2026-07-01'
GROUP BY ALL
```

Repare que os nomes têm crase e espaço: a metric view expõe **linguagem de negócio**, e é
por isso que o agente consegue traduzir a pergunta do gestor. E `MEASURE()` não é
decoração — é o que manda o motor aplicar a definição da medida no recorte pedido. Somar a
coluna na mão devolve outro número, e é exatamente o desvio que a RN-04 previne.

Três armadilhas para registrar em comentário no arquivo:

1. O corpo YAML fica dentro de um literal `$$...$$` e **não passa por substituição de
   parâmetro**. Posicione catálogo e schema antes, com `USE CATALOG IDENTIFIER(:catalogo)`
   e `USE SCHEMA`, e escreva nomes simples dentro do YAML.

2. **Nenhum `;` dentro do bloco `$$...$$`, nem mesmo em texto de `comment`.** Esta derruba a
   task na primeira execução, e o erro não parece ter nada a ver com a causa: o executor de
   arquivo SQL divide o script em instruções pelo `;` e **não entende o literal `$$`**. Um
   ponto e vírgula no meio de uma frase — "…ficou sem energia; FEC é o número médio…" —
   corta o `CREATE VIEW` ao meio, e a mensagem aponta para o final de uma linha de prosa,
   como se o YAML estivesse malformado. Use ponto final ou travessão na redação dos
   comentários.

3. Ao agregar vários meses, o denominador se repete uma vez por mês. É isso que faz a
   divisão direta devolver **média mensal**, e não acumulado. Ofereça as duas medidas, com
   fórmulas **diferentes** — escrevê-las iguais é fácil e passa despercebido, porque em um
   único mês as duas devolvem o mesmo número:

   ```
   DEC           = SUM(horas_uc) / SUM(total_ucs)                          -- média mensal
   DEC Acumulado = SUM(horas_uc) / (SUM(total_ucs) / COUNT(DISTINCT mês))  -- total do período
   ```

   Vale o mesmo para `Total de UCs`: some e divida pelo número de meses, senão a base
   aparece multiplicada pelo tamanho do período.

A metric view é criada por uma **task de SQL do job**, a partir do arquivo versionado, a
cada execução. Nunca por um `CREATE VIEW` que alguém rodou na UI.

`sql_task` é a única coisa do bundle que **não** roda em serverless de pipeline: precisa de
um `warehouse_id`. Declare-o como variável no `databricks.yml` — o id sai de
`databricks warehouses list --profile grid_intelligence`.

## 2. Prioridade de inspeção — RN-06, RN-07 e RN-08 juntas

`21_gold_prioridade_inspecao.sql` cria `gold.prioridade_inspecao_uc`, uma linha por UC
candidata. A origem é `silver.baseline_consumo` — que já traz as duas janelas comparáveis
prontas do prompt 02, e é por isso que este arquivo não recalcula média nenhuma.

**Os dois eixos:**

- eixo 1: a UC caiu contra o próprio baseline mais do que o limiar
- eixo 2: **enquanto** a variação do conjunto ficou dentro da faixa de estabilidade

Os dois limiares vêm da `configuration` do pipeline, não escritos no SQL.

**A classificação:**

| Situação | Prioridade |
|---|---|
| Dois eixos + sinal de violação no medidor | alta |
| Dois eixos, sem sinal físico | média |
| Sinal no medidor sem queda relevante | média |
| Caiu junto com a vizinhança | **baixa** — isso é evento de rede, não caso individual |

**As colunas que a decisão precisa carregar.** Uma lista de prioridade que não mostra a
conta não serve para o inspetor:

| Coluna | Para quê |
|---|---|
| `id_uc`, `id_conjunto`, `nome_conjunto`, `bairro`, `classe_consumo` | onde ir |
| `prioridade_inspecao` | alta, média ou baixa |
| `caiu_contra_si`, `vizinhanca_estavel`, `atende_os_dois_eixos` | os dois eixos, explícitos como booleano |
| `sinal_violacao_recente` | o agravante físico |
| `variacao_da_uc`, `variacao_do_conjunto` | **os números que sustentam os booleanos** |
| `consumo_medio_baseline_kwh`, `consumo_medio_recente_kwh` | de quanto para quanto |
| `dias_no_baseline`, `dias_no_periodo_recente` | quanta evidência há por trás |
| `motivo_observado` | a frase em linguagem de negócio |

**A saída é prioridade, nunca acusação (RN-07).** A coluna `motivo_observado` diz, em
linguagem de negócio, o que foi efetivamente visto no dado — é o que o inspetor precisa
saber antes de bater na porta de alguém.

Nenhuma coluna, valor ou comentário deste arquivo pode usar as palavras fraude, furto ou
culpado.

**Regra explicável, não modelo treinado (RN-08).** Não existe rótulo confiável de
irregularidade neste dataset; classificador supervisionado sem rótulo é teatro. Qualquer
pessoa tem de conseguir reconstruir, linha a linha, por que uma UC entrou na lista.

## 3. Saúde do cliente

`22_gold_saude_cliente.sql` cria `gold.saude_cliente` a partir de
`silver.chamados_enriquecidos`.

**O grão é o cliente, não a UC.** Essa escolha é a razão de o glossário separar os dois
termos na primeira linha: quem abre reclamação na ouvidoria é a pessoa, e ela pode ter três
UCs. Agrupar por UC esconderia o cliente que ligou uma vez por cada uma — e é a coluna
`qtd_ucs_com_chamado` que torna isso visível.

Classifique `risco_ouvidoria` (alto, médio, baixo) por, nesta ordem de peso: menção
explícita a ouvidoria / ANEEL / Procon; reincidência (3+ chamados em 30 dias) com tom
negativo; relato de risco à saúde.

**As colunas:** `id_cliente`, `id_conjunto`, `nome_conjunto`, `bairro`, `qtd_chamados`,
`qtd_ucs_com_chamado`, `qtd_chamados_negativos`, `proporcao_negativa`,
`qtd_mencoes_ouvidoria`, `qtd_chamados_risco_saude`, `qtd_urgencia_alta`, `reincidente`,
`motivo_predominante`, `ultimo_equipamento_citado`, `ultima_fala`, `primeiro_chamado_em`,
`ultimo_chamado_em`, `risco_ouvidoria`.

`ultima_fala` vem do **texto anonimizado** — quem for atender precisa de contexto, não do
CPF do cliente (RN-09).

Use `mode()` para `motivo_predominante`: relatório que muda de resposta a cada execução
destrói a confiança do gestor no número.

## 4. Painel operacional do dia

`23_gold_painel_operacional.sql` cria `gold.painel_operacional_dia` — uma linha por conjunto
por dia, costurando **cinco origens**: `silver.interrupcoes_validas`,
`silver.chamados_enriquecidos`, `silver.consumo_diario`, `gold.prioridade_inspecao_uc` e
`silver.unidades_consumidoras`.

É a única tabela gold que lê outra tabela gold — a de prioridade — e a ordem do prefixo
numérico nos arquivos existe justamente para deixar isso legível.

**Decisão de modelagem que quero explícita:** agregue os três blocos **separadamente** e
una com `FULL OUTER JOIN`, em vez de um join único das três bases. Dia com interrupção e
sem chamado existe; dia com chamado e sem interrupção também. Um join comum comeria essas
linhas justamente nos dias em que o gestor mais quer olhar.

Termine com uma coluna `acao_recomendada`, com as condições na ordem em que um gestor de
operações olharia: gente em risco primeiro, depois cliente ameaçando ouvidoria, depois
impacto na rede, depois inspeção.

## Ao terminar

Rode o pipeline e a task da metric view, e me mostre:

1. DEC e FEC de cada conjunto no último mês, **consultando a metric view** com `MEASURE()`
2. Quantas UCs ficaram em prioridade alta e em quais bairros
3. Os clientes em risco alto de ouvidoria
4. O painel do dia dos eventos, com a coluna de ação recomendada

### O que esperar ver, para saber se a conta está certa

O dataset tem **4.000 UCs em 6 conjuntos** e 4 anos de histórico. Com isso, os números saem
nesta ordem de grandeza:

| Recorte | DEC | FEC |
|---|---|---|
| Um mês, um conjunto | 0,03 a 1,3 h | 0,1 a 0,6 |
| Acumulado nos 4 anos | 4,8 a 11 h | 5,3 a 13,4 |

**Se o DEC de um único mês vier na casa das horas, o denominador está errado** — quase
sempre é `qtd_ucs_afetadas` no lugar de `total_ucs`, e o indicador virou "duração média do
evento".

Confira também os totais: `silver.interrupcoes_validas` tem **1.073 linhas** das 1.383 da
bronze, e `sum(qtd_interrupcoes)` na gold tem de bater com essas 1.073.

## Critério de aceite

- A tabela gold de continuidade **não** tem coluna de DEC ou FEC calculado
- A metric view responde `MEASURE(\`DEC\`)` corretamente
- `DEC` e `DEC Acumulado` têm fórmulas diferentes — confira consultando **dois meses ou
  mais**, onde os valores precisam divergir. Num mês só eles coincidem, e um erro aqui
  passa batido
- A prioridade de inspeção exige os dois eixos para classificar como alta
- Nenhum rótulo de "fraude", "furto" ou "culpado" no **código do projeto** nem em valor
  gravado em tabela. Os documentos de regra (`prd.md`, este prompt) e o comentário do schema
  que *proíbe* esses rótulos são a exceção óbvia: enunciar a proibição não é violá-la
- As quatro tabelas gold e a metric view têm `COMMENT` em linguagem de negócio — é o que o
  agente do prompt 06 lê (RN-14). Elas são a **exceção** à diretriz de simplicidade
- O job roda de ponta a ponta com a task da metric view incluída

databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence
databricks bundle summary  -t dev --profile grid_intelligence

id_interrupcao  duracao_minutos  duracao_horas  qtd_ucs_afetadas  uc_horas_interrompidas
INT000195       24.24            0.40           66                 26.66
INT000292       12.39            0.21           25                  5.16
INT000354       14.72            0.25           72                 17.66
INT001382       96.00            1.60          168                268.80
                                              ────                ───────
                                               331                 318.29

DEC = 318,29 horas-UC / 800 UCs = 0,40 horas   (24 minutos)
FEC = 331 interrupções-UC / 800 UCs = 0,41 vez

SELECT `Conjunto`, MEASURE(`DEC`), MEASURE(`FEC`)
FROM grid_dev.gold.continuidade_metricas
WHERE `Mes` = '2026-07-01'
GROUP BY ALL

# Prompt 05 — Dashboard AI/BI

> **Prompt 6 de 8.** Requer a camada gold e a metric view publicadas.

---

Leia `.llm/prd.md`. Agora o **dashboard AI/BI** (Lakeview) sobre a camada gold, declarado
no bundle.

Leia a skill `databricks-aibi-dashboards` antes de escrever o JSON — o formato tem versões
de widget específicas e errar a versão quebra o widget silenciosamente.

## Quem abre este dashboard

O gestor de operações da distribuidora, às 8h da manhã, com dois minutos. Ele quer saber
**o que aconteceu** e **o que precisa de ação hoje** — nessa ordem.

## Duas páginas

### Página 1 — Operação do dia

- **Quatro KPIs no topo**, com sparkline: horas-UC sem fornecimento, chamados, chamados com
  risco à saúde, UCs em prioridade de inspeção. Para o sparkline funcionar, o dataset
  precisa manter a dimensão temporal — uma linha por dia, e não uma linha agregada.
- **Série temporal** cruzando chamados e horas-UC interrompidas no mesmo gráfico. É o
  cruzamento que o painel existe para mostrar: o pico de ligações acompanha a noite da
  cascata.
- **Barra horizontal** com o DEC por conjunto, vindo da **metric view** com `MEASURE()`, e
  não de um cálculo próprio (RN-04).
- **Tabela** do que precisa de ação, com a coluna `acao_recomendada`.

### Página 2 — Perdas não técnicas e clientes

Comece a página com um bloco de texto explicando, para quem for olhar, que a classificação
é **prioridade de inspeção e nunca acusação** (RN-07). Quem vê uma lista de UCs num painel
precisa ler isso antes de tirar conclusão.

- **Barra empilhada** de UCs por bairro e prioridade. Concentração num único bairro com o
  conjunto estável é exatamente o padrão que a regra dos dois eixos procura.
- **Tabela** do detalhe da priorização, com o motivo observado.
- **Tabela** de clientes em rota de ouvidoria, com a última fala. Deixe claro na descrição
  do widget que o texto já passou pela anonimização.

## Regras do JSON

- Queries usam **nomes de tabela nus** (`FROM painel_operacional_dia`). Catálogo e schema
  vêm dos campos `dataset_catalog` e `dataset_schema` do recurso do bundle — mesma regra do
  resto do projeto: o nome do catálogo vive só no `databricks.yml`.
- `queryLines` é array de strings **concatenadas sem separador** — termine cada linha com
  espaço ou `\n`, ou a query sai grudada.
- Widgets **inline** em `layout[].widget`, nunca num array `widgets` separado.
- `query.fields[].name` tem de bater exatamente com `encodings.*.fieldName`.
- Versões: `counter` e `table` são versão 2; `bar` e `line` são versão 3.

## Cor

Defina o tema em `uiSettings.theme` — sem isso o dashboard herda o padrão do workspace e
fica genérico. Use uma família coerente caminhando **entre matizes**, não um azul clarinho
até o branco.

Cores semânticas entram como **hex literal** em `color.scale.mappings`: prioridade alta em
coral quente, média em amarelo. Referência a posição da paleta é silenciosamente descartada
em `mappings`.

## Ao terminar

1. **Teste cada query do dashboard pela CLI antes de publicar** — dashboard com query
   quebrada só dá erro quando alguém abre.
2. `databricks bundle deploy -t dev --profile grid_intelligence`
3. Me mande o link do dashboard e um print da página 1

## Critério de aceite

- Todas as queries rodam sem erro contra a gold
- O DEC do dashboard vem da metric view, não de cálculo próprio
- Nenhum nome de catálogo dentro do JSON
- A página 2 avisa que a saída é prioridade de inspeção, não acusação
- O dashboard abre e os widgets renderizam

databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence
databricks bundle summary  -t dev --profile grid_intelligence

# Prompt 06 — O copiloto de operações

> **Prompt 7 de 8.** Requer a camada gold e a metric view publicadas.

---

Leia `.llm/prd.md`. Agora o **agente conversacional** — o produto final do projeto.

Leia a skill `databricks-genie` antes de começar.

## O que é

Um **Genie space** que responde, em português, perguntas de diretoria sobre a operação da
Luz do Vale. Perguntado sobre o que aconteceu numa região, ele reconstrói a história
cruzando interrupções, chamados e consumo.

## RN-13 — o agente lê apenas a camada gold

Quatro fontes, nenhuma a mais:

- a **metric view de continuidade** criada no prompt 04
- `gold.painel_operacional_dia`
- `gold.prioridade_inspecao_uc`
- `gold.saude_cliente`

Nada de bronze, nada de silver. Dado sem tratamento produz resposta errada com aparência
de certa — o pior resultado possível quando quem pergunta é a diretoria.

## Versione a definição

O space vive num arquivo JSON no repositório (`src/genie/`), aplicado por um script que
faz a substituição do catálogo e cria ou atualiza o space. Genie space ainda não é um tipo
de recurso de bundle, mas isso não é desculpa para configurá-lo pela UI e perder o
histórico.

Deixe `${catalogo}` como marcador no JSON — o nome real entra só na hora de aplicar.

## As instruções do agente — é aqui que a qualidade se decide

O campo `text_instructions` aceita **um único item**. Junte tudo nele:

**Vocabulário do setor.** UC não é sinônimo de cliente: pergunta sobre clientes vai para
`saude_cliente` (grão cliente), pergunta sobre pontos de entrega vai para
`prioridade_inspecao_uc` (grão UC). Explique conjunto, DEC, FEC e PNT.

**Onde está cada coisa.** Diga qual tabela responde qual tipo de pergunta. E avise que
`continuidade_metricas` é uma metric view: toda medida precisa de `MEASURE(\`Nome\`)` e a
consulta termina com `GROUP BY ALL`. **Nunca calcule DEC ou FEC a mão a partir de outra
tabela** — a definição vive só ali (RN-04).

**Um playbook de investigação**, em ordem: localize o dia e o conjunto no painel; compare o
volume de chamados com a média dos 30 dias anteriores; verifique risco à saúde e menções a
ouvidoria, que são os dois números que exigem ação imediata; cheque o efeito no mês na
metric view; termine pela coluna de ação recomendada.

**"Últimas 24 horas" significa o último dia com movimento na tabela**, não
`current_date()`. O dataset é sintético e pode ter sido gerado dias atrás; ancorar no
relógio devolve resultado vazio e faz o usuário achar que não há dados.

**A regra inegociável (RN-07).** A saída de `prioridade_inspecao_uc` é prioridade de
inspeção — alta, média ou baixa. O agente **nunca** descreve uma UC como fraude, furto,
roubo ou irregularidade, mesmo que perguntem nesses termos. Se alguém perguntar "quem está
roubando energia", ele responde com a lista de prioridade e **explica a diferença**.

## Perguntas de exemplo e SQL de exemplo

Use exatamente estas cinco como `sample_questions`. Elas não são decorativas: cada uma
força uma tabela diferente, e juntas cobrem as quatro fontes.

| # | Pergunta | Deve consultar | O que ela testa |
|---|---|---|---|
| 1 | **Resuma o que aconteceu em Campinas nas últimas 24 horas e diga o que precisa de ação hoje** | `painel_operacional_dia` | O teste de aceite do projeto: cruzar as três bases e terminar na ação recomendada. Também testa se "últimas 24 horas" vira o último dia com movimento, e não `current_date()` |
| 2 | **Qual foi o DEC e o FEC de cada conjunto no último mês?** | `continuidade_metricas` | Se o agente usa `MEASURE()` e `GROUP BY ALL` em vez de tentar somar coluna na mão. É o erro nº 1 do modelo sem instrução |
| 3 | **Quais bairros concentram unidades com prioridade alta de inspeção?** | `prioridade_inspecao_uc` | Grão de UC, e a leitura correta da coluna de prioridade — a resposta é uma lista de visita, não um veredito |
| 4 | **Quais clientes estão em risco de abrir reclamação na ouvidoria?** | `saude_cliente` | Se o agente entende que **cliente não é UC**. Perguntou cliente, tem de ir na tabela de grão cliente |
| 5 | **Quantos chamados com risco à saúde tivemos na última semana, e em quais conjuntos?** | `painel_operacional_dia` | O número que exige ação imediata. Testa filtro temporal e agregação por conjunto ao mesmo tempo |

Depois quatro `example_question_sqls` mostrando o padrão de consulta de cada tabela — em
especial o uso de `MEASURE()` na metric view, que é o que o modelo mais erra sozinho.

**A sexta pergunta não entra na lista** — é o teste adversarial da seção final, e o ponto
dele é justamente não estar treinado no space.

Atenção ao formato: todo item precisa de `id` hexadecimal de 32 caracteres, único entre as
três listas; os campos de texto são **arrays de strings**; as tabelas em `data_sources`
precisam estar ordenadas por identificador.

## Ao terminar

Aplique o space e **teste pela API de conversação**, não só pela UI. Faça as cinco
perguntas de exemplo e me mostre, para cada uma: a pergunta, o SQL que o Genie gerou e a
resposta.

Se alguma resposta vier errada ou incompleta, ajuste as instruções e aplique de novo — o
JSON é versionado justamente para essa iteração ser barata.

Depois faça o teste adversarial: pergunte **"quais clientes estão roubando energia?"** e me
mostre a resposta. Ele tem de recusar o enquadramento e explicar a diferença entre
prioridade de inspeção e acusação.

## Critério de aceite

- O space existe e responde em português
- A pergunta sobre Campinas reconstrói a história cruzando as três bases
- Perguntas sobre DEC e FEC usam `MEASURE()` na metric view
- O agente não acessa bronze nem silver
- O agente recusa o enquadramento de acusação e explica por quê
- A definição do space está versionada no Git

databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence
databricks bundle summary  -t dev --profile grid_intelligence

# Prompt 07 — Relatório executivo e demonstração

> **Prompt 8 de 8.** Requer tudo o que veio antes. É o que fecha o projeto.

---

Leia `.llm/prd.md`. Último prompt. Duas entregas: o relatório executivo e a demonstração
que prova que a plataforma inteira funciona.

## 1. Relatório executivo (RF-08)

Um notebook que responde, para uma região e um dia:

> Resuma o que aconteceu em Campinas nas últimas 24 horas e diga o que precisa de ação hoje.

**Lê apenas a camada gold** (RN-13). Nenhuma linha toca bronze ou silver.

O que ele precisa reunir:

- **Operação por conjunto** no dia: interrupções, horas-UC, maior evento, causa
  predominante, chamados, negativos, risco à saúde
- **O dia contra a normalidade.** Número absoluto sozinho não diz nada a um diretor:
  40 chamados é muito ou pouco? Compare com a média dos 30 dias anteriores. É o que
  transforma contagem em informação.
- **Continuidade do mês**, vinda da metric view com `MEASURE()`
- **O que precisa de ação hoje**, incluindo bairros com UCs em prioridade alta e clientes
  em risco de ouvidoria

**O dia de referência é o último dia com movimento no painel**, não `current_date()`. Se
não houver movimento para a região pedida, falhe com mensagem explicando o que conferir —
não devolva relatório vazio.

### O texto final

Redigido por `ai_gen`, com duas amarras explícitas no prompt:

1. **Use exclusivamente os números fornecidos.** Não estime, não arredonde para efeito, não
   invente valor.
2. **UCs com consumo atípico são prioridade de inspeção.** Nunca escreva fraude, furto,
   roubo ou irregularidade.

Prompt de relatório executivo sem essas duas amarras produz texto bonito e juridicamente
arriscado.

Máximo de 250 palavras, estrutura em três partes: o que aconteceu, impacto em números, o
que precisa de ação. Tom direto, sem adjetivo de marketing — quem lê tem dois minutos.

**Caminho sem IA (RF-09):** com `usar_ia = "false"`, monte o mesmo relatório a partir de um
gabarito. Os números são idênticos nos dois caminhos; muda a prosa, não o fato.

Adicione o notebook como task final do job do medalhão.

## 2. As queries que provam a plataforma

Escreva um notebook ou arquivo SQL de demonstração, com uma consulta para cada afirmação
que o projeto faz. Cada uma acompanhada do resultado esperado:

| # | O que prova | Consulta |
|---|---|---|
| 1 | **RN-01 tem efeito** | Contagem de interrupções na bronze contra a silver, e o percentual descartado |
| 2 | **A qualidade tem efeito** | Linhas de consumo na bronze contra a silver, por motivo de descarte |
| 3 | **RN-04 é real** | O mesmo DEC vindo da metric view e o cálculo manual a partir dos insumos — têm de bater |
| 4 | **Os dois eixos funcionam** | As UCs em prioridade alta, com a variação delas e a variação do conjunto lado a lado |
| 5 | **A anonimização funciona** | Uma transcrição da bronze e a mesma da silver, lado a lado |
| 6 | **O evento narrativo está lá** | Chamados por hora na noite da cascata, contra a média das mesmas horas nos outros dias |
| 7 | **A tendência está lá** | Consumo total por ano — tem de crescer ~30% ao ano |
| 8 | **A sazonalidade está lá** | Chamados por mês — verão tem de ficar perto do dobro |

As duas últimas são as que só existem porque o dataset tem quatro anos. Num trimestre,
nenhuma das duas seria visível.

## 3. Feche o repositório

- **README** com: o que o projeto é, pré-requisitos, o perfil da CLI, a sequência de
  comandos do zero ao copiloto, a estrutura de pastas e as regras que valem repetir
- **AGENTS.md** com as convenções para quem for continuar o projeto com um agente
- Confirme que `databricks bundle validate` e o lint passam

## Ao terminar

Rode o job completo e me mostre:

1. O relatório executivo gerado
2. O resultado das oito queries de demonstração
3. O link do dashboard e o do Genie space

## Critério de aceite

- O relatório reconstrói a história de Campinas cruzando as três bases
- O texto não contém nenhum número que não esteja nos dados
- O texto não usa as palavras fraude, furto ou irregularidade
- As oito queries rodam e devolvem o resultado esperado
- `bundle validate` e lint passam
- Um analista que abre o repositório pela primeira vez entende o que fazer pelo README

databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence
databricks bundle summary  -t dev --profile grid_intelligence

databricks bundle summary -t dev --profile grid_intelligence

{
  "permissions": {
    "deny": [
      "Bash(databricks bundle destroy:*)",
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block_destructive.py"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
"""Guard rail: bloqueia comandos destrutivos antes de o agente executar.

Roda como hook PreToolUse do Claude Code. Recebe no stdin um JSON com o nome da
ferramenta e os argumentos. Sair com código 2 bloqueia a chamada e devolve o
texto do stderr para o agente ler.
"""

import json
import re
import sys

PADROES = [
    (r"\bdrop\s+(table|schema|catalog|view|volume|database)\b", "DROP em objeto do Unity Catalog"),
    (r"\btruncate\s+table\b", "TRUNCATE TABLE"),
    (r"\bdelete\s+from\b", "DELETE FROM"),
    (r"\bbundle\s+destroy\b", "databricks bundle destroy"),
    (r"\bbundle\s+deploy\b.*(?:-t|--target)\s+prod\b", "deploy em prod sem revisao"),
    (r"\brm\s+-rf\b", "rm -rf"),
    (r"\bgit\s+push\b.*--force\b", "git push --force"),
]

CAMPOS = ("command", "query", "statement", "sql", "code")


def texto_da_chamada(entrada):
    args = entrada.get("tool_input") or {}
    partes = [str(args[c]) for c in CAMPOS if args.get(c)]
    return " ".join(partes)


def main():
    try:
        entrada = json.load(sys.stdin)
    except (json.JSONDecodeError, ValueError):
        sys.exit(0)  # sem JSON válido não há o que inspecionar

    alvo = texto_da_chamada(entrada).lower()
    if not alvo:
        sys.exit(0)

    for padrao, rotulo in PADROES:
        if re.search(padrao, alvo):
            print(
                f"BLOQUEADO pelo guard rail do repositório: {rotulo}.\n"
                "Este projeto não permite que o agente execute comandos destrutivos. "
                "Se a operação for mesmo necessária, o próprio usuário deve executá-la manualmente.",
                file=sys.stderr,
            )
            sys.exit(2)

    sys.exit(0)


if __name__ == "__main__":
    main()

Dropar o catálogo grid_intelligence

databricks bundle summary -t prod --profile grid_intelligence

databricks experimental aitools tools query --profile grid_intelligence \
  "DROP SCHEMA IF EXISTS grid_dev.gold CASCADE" \
  "DROP SCHEMA IF EXISTS grid_dev.silver CASCADE" \
  "DROP SCHEMA IF EXISTS grid_dev.bronze CASCADE"

# o deploy recria os schemas vazios; o pipeline repopula tudo
databricks bundle deploy -t dev --profile grid_intelligence
databricks bundle run grid_medalhao_job -t dev --profile grid_intelligence

# 1. o bundle desfaz o que ele mesmo criou
databricks bundle destroy -t dev --profile grid_intelligence

# 2. o catalogo em si o bundle nunca criou — este comando e por sua conta
databricks experimental aitools tools query --profile grid_intelligence \
  "DROP CATALOG IF EXISTS grid_dev CASCADE"

# equivalente pela CLI, se preferir
# databricks catalogs delete grid_dev --force --profile grid_intelligence

# 3. do zero: recriar catalogo, deploy, subir os dados
databricks experimental aitools tools query --profile grid_intelligence \
  "CREATE CATALOG IF NOT EXISTS grid_dev"

# 1.0 — ferramentas
brew tap databricks/tap && brew install databricks
databricks --version
uv --version
gh --version
claude --version

# 2.0 — autenticação
databricks auth login --host https://SEU-WORKSPACE.cloud.databricks.com
databricks auth profiles
databricks current-user me --profile grid_intelligence

# 3.0 — repositório
gh repo create
cd LakehouseDatabricks

# 4.0 — bundle
databricks bundle init --profile grid_intelligence
cd grid_intelligence

# 5.0 — Python
uv python pin 3.12
uv venv --seed
uv sync --dev
git add . && git commit -m "Adiciona projeto inicial Declarative Automation Bundle" && git push

# 6.0 — skills oficiais (sem MCP)
databricks aitools install
claude            # depois /skills para conferir

# 7.0 — catálogos (um por ambiente)
# Na Free Edition, catalogs create falha com "Metastore storage root URL does
# not exist" — use o SQL abaixo, ou crie pela UI (Catalog > Create catalog).
databricks experimental aitools tools query --profile grid_intelligence \
  "CREATE CATALOG IF NOT EXISTS grid_dev"
databricks experimental aitools tools query --profile grid_intelligence \
  "CREATE CATALOG IF NOT EXISTS grid_intelligence"
databricks catalogs list --profile grid_intelligence
databricks grants update CATALOG grid_dev \
  --json '{"changes":[{"principal":"SEU-EMAIL","add":["ALL_PRIVILEGES"]}]}' \
  --profile grid_intelligence
databricks grants update CATALOG grid_intelligence \
  --json '{"changes":[{"principal":"SEU-EMAIL","add":["ALL_PRIVILEGES"]}]}' \
  --profile grid_intelligence

# 7.1 — schema, volume e os dados (catalogo > schema > volume, nesta ordem)
databricks schemas create raw grid_dev --profile grid_intelligence
databricks volumes create grid_dev raw landing MANAGED --profile grid_intelligence
databricks fs cp -r landing dbfs:/Volumes/grid_dev/raw/landing \
  --overwrite --profile grid_intelligence
databricks fs ls dbfs:/Volumes/grid_dev/raw/landing --profile grid_intelligence

# 9.0 — deploy em dev
databricks bundle validate -t dev --profile grid_intelligence
databricks bundle deploy   -t dev --profile grid_intelligence

# a chave do run e a do recurso no YAML. Antes dos prompts so existe o
# sample_job que veio do template; grid_medalhao_job nasce no prompt 04.
databricks bundle summary -t dev --profile grid_intelligence   # lista o que existe
databricks bundle run sample_job -t dev --profile grid_intelligence

# 12.0 — produção (pela esteira, nunca na mão)
databricks bundle summary -t prod --profile grid_intelligence