first commit

deploy/README.md

@@ -0,0 +1,125 @@
+# Deployment Kubernetes — Evaluator TIM
+
+O **evaluator continua sendo batch/CronJob-only**. O componente `evaluator-batch` não expõe HTTP nem gRPC.
+
+Para acompanhamento operacional existe um componente **separado e somente leitura**, `evaluator-monitor`, que consulta as tabelas do Autonomous Database e disponibiliza `/ui` e APIs de monitoramento. Essa separação mantém o processamento em batch e evita acoplar uma API HTTP ao evaluator.
+
+Recursos aplicados pelo Kustomize:
+
+```text
+Namespace
+ServiceAccount
+ConfigMap
+CronJob evaluator-batch
+Deployment evaluator-monitor
+Service evaluator-monitor (ClusterIP)
+```
+
+O CronJob executa diariamente às 02:00 em `America/Sao_Paulo`, com `suspend: false` e `concurrencyPolicy: Forbid`.
+
+## Preparação
+
+```bash
+cp deploy/env/evaluator.env.example deploy/env/evaluator.env
+```
+
+Configure ADB, OCI GenAI e GCS no env file. Copie `deploy/langfuse/langfuse_credentials.example.yaml` para `deploy/langfuse/langfuse_credentials.yaml` e declare ali quantos agentes/projetos Langfuse forem necessários. O script cria o Secret `evaluator-langfuse` dinamicamente a partir desse arquivo.
+
+Wallet Oracle:
+
+```text
+deploy/wallet/
+```
+
+Credencial GCP opcionalmente materializada pelo script:
+
+```text
+deploy/gcp/GCP_ACCESS_KEY.json
+```
+
+## Secrets
+
+```bash
+./deploy/scripts/create-secrets.sh dev
+./deploy/scripts/create-secrets.sh hml
+./deploy/scripts/create-secrets.sh prod
+```
+
+## Build
+
+```bash
+export REGISTRY=tim.azurecr.io
+export IMAGE_TAG=0.3.0
+./deploy/scripts/build-push.sh prod
+```
+
+## Deploy
+
+```bash
+export REGISTRY=tim.azurecr.io
+export IMAGE_TAG=0.3.0
+./deploy/scripts/deploy.sh prod
+```
+
+## Status
+
+```bash
+./deploy/scripts/status.sh prod
+```
+
+Ou:
+
+```bash
+kubectl -n agent-evaluator-prod get cronjob,jobs,pods,deploy,svc
+```
+
+## Execução imediata
+
+```bash
+./deploy/scripts/run-now.sh prod
+```
+
+Acompanhar logs do batch:
+
+```bash
+kubectl -n agent-evaluator-prod get jobs,pods
+kubectl -n agent-evaluator-prod logs -f job/<nome-do-job>
+```
+
+O comando `run-agents` também imprime o `RUN_ID` assim que cada execução é criada, permitindo:
+
+```bash
+python -m evaluator.cli progress <RUN_ID> --events 100
+```
+
+## Interface web
+
+O Service do monitor é `ClusterIP`, portanto não fica exposto externamente por default.
+
+Para acessar via sua máquina:
+
+```bash
+kubectl -n agent-evaluator-prod port-forward svc/evaluator-monitor 8080:8080
+```
+
+Abra:
+
+```text
+http://localhost:8080/ui
+```
+
+Endpoints read-only:
+
+```text
+GET /health
+GET /api/runs
+GET /api/runs/{run_id}
+GET /api/runs/{run_id}/results
+GET /ui
+```
+
+Não há endpoints para iniciar, cancelar, apagar ou alterar runs.
+
+## Configuração de storage
+
+Os buckets por ambiente ficam em `configs/judge/storage.yaml`. Para usar outro arquivo, configure `STORAGE_CONFIG_PATH`. `JUDGE_GCS_BUCKET` sobrescreve o mapping quando necessário.