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-005-Guardrails.md
+++ b/specs/en/SPEC-005-Guardrails.md
@@ -0,0 +1,194 @@
+# SPEC-005 — Guardrails
+
+## Scope
+
+Guardrails are Policies executadas sobre Input, Output, tool calls, RAG and responses finais. The platform suporta guardrails global, por Agent, por canal and por fase.
+
+## Fases
+
+| Fase | Input | Output |
+|---|---|---|
+| Input | `user_text`, `context` | `sanitized_input`, `GuardrailResult` |
+| Tool | `ToolInvocation` | tool allowed/bloqueada |
+| RAG | query/Context recuperado | Context aprovado/filtrado |
+| Output | `response_text` | Response aprovada/sanitizada/bloqueada |
+| Review | Response + evidências | Decision final |
+
+## GuardrailResult
+
+```json
+{
+  "code": "PINJ",
+  "phase": "input",
+  "status": "blocked",
+  "severity": "high",
+  "score": 0.98,
+  "message": "Entrada bloqueada por política.",
+  "details": {
+    "matched_policy": "prompt_injection"
+  }
+}
+```
+
+## Configuration Global
+
+```yaml
+input:
+  - code: MSK
+    enabled: true
+    mode: enforce
+  - code: VLOOP
+    enabled: true
+    mode: enforce
+  - code: PINJ
+    enabled: true
+    mode: enforce
+
+output:
+  - code: REVPREC
+    enabled: true
+    mode: enforce
+  - code: DLEX_OUT
+    enabled: true
+    mode: enforce
+  - code: PINJ
+    enabled: true
+    mode: observe
+```
+
+## Configuration por Agent
+
+```yaml
+agents:
+  telecom_contas:
+    input:
+      - code: BILLING_INPUT_POLICY
+        enabled: true
+        mode: observe
+    output:
+      - code: BILLING_COMPLIANCE
+        enabled: true
+        mode: enforce
+```
+
+## Modos
+
+| Modo | Comportamento |
+|---|---|
+| `enforce` | applies Block, máscara or alteração. |
+| `observe` | Registra without bloquear. |
+| `fail_open` | Em Error técnico, prossegue and emite NOC. |
+| `fail_closed` | Em Error técnico, bloqueia. |
+
+## Tipos
+
+| Tipo | Implementation |
+|---|---|
+| Determinístico | Regex, listas, tamanho, structure, Rules. |
+| LLM | Classificação semântica por profile. |
+| Híbrido | Determinístico + LLM em casos ambíguos. |
+
+## Profiles LLM
+
+```yaml
+profiles:
+  guardrail:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 600
+
+  grl:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 700
+```
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[Input] --> B[Deterministic Guardrails]
+    B --> C{Blocked?}
+    C -- yes --> D[Safe Response]
+    C -- no --> E[LLM Guardrails]
+    E --> F{Approved?}
+    F -- no --> D
+    F -- yes --> G[Runtime]
+```
+
+## Events
+
+| Evento | Description |
+|---|---|
+| `guardrail.started` | Execution iniciada. |
+| `guardrail.completed` | Execution concluída. |
+| `guardrail.blocked` | Conteúdo bloqueado. |
+| `guardrail.masked` | Conteúdo mascarado. |
+| `guardrail.failed` | Failure técnica. |
+| `guardrail.observe` | Policy observacional registrada. |
+
+## Códigos Base
+
+| Código | Fase | Uso |
+|---|---|---|
+| `MSK` | input/output | Mascaramento. |
+| `VLOOP` | input | Detecção of loop. |
+| `PINJ` | input/output | Prompt injection. |
+| `REVPREC` | output | Review of precisão. |
+| `DLEX_OUT` | output | control of Data and linguagem na Output. |
+| `RAGSEC` | rag/output | Security of Context recuperado. |
+
+## Tests
+
+| Test | objective |
+|---|---|
+| Unitário | validate guardrail isolado. |
+| Config | validate YAML and schema. |
+| integration | validate Execution no workflow. |
+| Observability | validate Events and traces. |
+| Negativo | validate Block. |
+| Observe-only | validate No Block. |
+
+
+## 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
+
+- [ ] Guardrails global are carregados por YAML.
+- [ ] Guardrails por Agent sobrescrevem or complementam global.
+- [ ] GuardrailResult is gerado for each Execution.
+- [ ] Modo enforce bloqueia when aplicável.
+- [ ] Modo observe No bloqueia.
+- [ ] Failures técnicas seguem Policy configured.
+- [ ] Guardrails LLM usam profile dedicado.
+- [ ] Events and Metrics are emitidos.
+- [ ] Tests cobrem casos positivos and negativos.
+- [ ] Output guardrails executam before of the Response final.
+
+
+## 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. |