First commit

2026-10-30 22:04:44 -03:00
commit 645ecdfb07
2794 changed files with 282545 additions and 0 deletions
--- a/specs/en/SPEC-008-Deployment.md
+++ b/specs/en/SPEC-008-Deployment.md
@@ -0,0 +1,233 @@
+# SPEC-008 — Deployment
+
+## Scope
+
+Deployment cobre empacotamento, CI/CD, Kubernetes/OKE, Docker, secrets, Authentication OCI, health checks, rollback and Operations of the Components.
+
+## Components Deployáveis
+
+| Componente | Artefato |
+|---|---|
+| Agent Gateway | Docker image + Kubernetes Deployment |
+| Channel Gateway | Docker image + Kubernetes Deployment |
+| AI Gateway | Docker image + Kubernetes Deployment |
+| MCP Gateway | Docker image + Kubernetes Deployment |
+| Agent Backend | Docker image + Kubernetes Deployment |
+| MCP Server | Docker image + Kubernetes Deployment |
+| Evaluator API | Docker image + Kubernetes Deployment |
+| Evaluator Batch | Kubernetes CronJob |
+| Frontend Demo | Docker image Optional |
+
+## Pipeline
+
+```mermaid
+flowchart LR
+    A[Commit] --> B[Lint]
+    B --> C[Type Check]
+    C --> D[Unit Tests]
+    D --> E[Contract Tests]
+    E --> F[Security Scan]
+    F --> G[Build Wheel]
+    G --> H[Build Images]
+    H --> I[Publish]
+    I --> J[Deploy Dev]
+    J --> K[Smoke Tests]
+    K --> L[Certification]
+    L --> M[Deploy HML/Prod]
+```
+
+## Stages
+
+```yaml
+stages:
+  - validate
+  - lint
+  - type_check
+  - unit_test
+  - contract_test
+  - security_scan
+  - build_package
+  - build_image
+  - publish
+  - deploy_dev
+  - smoke_test
+  - certification
+  - deploy_hml
+  - deploy_prod
+```
+
+## Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: agent-runtime
+  labels:
+    app: agent-runtime
+    component: runtime
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: agent-runtime
+  template:
+    metadata:
+      labels:
+        app: agent-runtime
+    spec:
+      serviceAccountName: agent-runtime-sa
+      containers:
+        - name: agent-runtime
+          image: registry/agent-runtime:1.0.0
+          ports:
+            - containerPort: 8000
+          envFrom:
+            - configMapRef:
+                name: agent-runtime-config
+            - secretRef:
+                name: agent-runtime-secrets
+          readinessProbe:
+            httpGet:
+              path: /ready
+              port: 8000
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 8000
+```
+
+## Service
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: agent-runtime
+spec:
+  selector:
+    app: agent-runtime
+  ports:
+    - port: 8000
+      targetPort: 8000
+```
+
+## OCI Authentication
+
+| Ambiente | Modo |
+|---|---|
+| Local | `config_file` |
+| Local with endpoint OpenAI-Compatible | API key |
+| OCI Compute | `instance_principal` |
+| OKE | `workload_identity` or `resource_principal` |
+| Tests | `mock` |
+
+## Variáveis
+
+```env
+LLM_PROVIDER=oci_sdk
+OCI_AUTH_MODE=workload_identity
+ENABLE_LANGFUSE=true
+ENABLE_OTEL=true
+SESSION_REPOSITORY_PROVIDER=autonomous
+MEMORY_REPOSITORY_PROVIDER=autonomous
+CHECKPOINT_REPOSITORY_PROVIDER=autonomous
+```
+
+## Secrets
+
+| Secret | Uso |
+|---|---|
+| `LANGFUSE_PUBLIC_KEY` | Langfuse |
+| `LANGFUSE_SECRET_KEY` | Langfuse |
+| `OCI_GENAI_API_KEY` | OCI OpenAI-Compatible |
+| `ADB_PASSWORD` | Autonomous Database |
+| `MCP_BACKEND_TOKEN` | Integrações MCP |
+| `OTEL_AUTH_TOKEN` | Exportador OTEL, if aplicável |
+
+## Health Checks
+
+| Endpoint | Uso |
+|---|---|
+| `/health` | Process vivo. |
+| `/ready` | ready for traffic. |
+| `/version` | Version of build. |
+| `/debug/env` | Ambiente without segredos, when enabled. |
+
+## Rollback
+
+Itens considerados:
+
+- tag of the imagem;
+- Version of the pacote Python;
+- Version of the schemas;
+- Version of the YAMLs;
+- migrations;
+- datasets of eval;
+- contracts;
+- dashboards.
+
+## Smoke Tests
+
+```bash
+curl -f http://agent-runtime:8000/health
+curl -f http://agent-gateway:9000/health
+curl -f http://mcp-gateway:8300/health
+curl -f http://ai-gateway:9100/health
+```
+
+## Certification Stage
+
+A pipeline executa:
+
+- health checks;
+- Contract GatewayRequest;
+- Routing;
+- MCP invoke;
+- LLM mock/real conforme ambiente;
+- guardrails;
+- judges;
+- Memory/checkpoint;
+- relatório JSON/HTML.
+
+
+## Requirements No Funcionais
+
+| Categoria | Requirement |
+|---|---|
+| Availability | Components deployáveis expõem `/health` and `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
+| Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
+| Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
+| Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
+| Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
+| Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
+
+
+## Acceptance criteria
+
+- [ ] each app possui Dockerfile.
+- [ ] each app possui manifest Kubernetes.
+- [ ] CI executa lint, type check and Tests.
+- [ ] Contract tests validam Main contracts.
+- [ ] Security scan executa before of the publish.
+- [ ] Secrets No are versionados.
+- [ ] Workload Identity is configured em OKE.
+- [ ] Health/readiness/liveness are ativos.
+- [ ] Smoke tests rodam após deploy.
+- [ ] Rollback is documentado.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
+| Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
+| Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
+| Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
+| Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
+| AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
+| MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
+| Evaluator | layer of Evaluation online/offline, regressão and Certification. |
+| Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |