From 859ccd43afbc82a1ff9c4c247db5288bcf6dbd97 Mon Sep 17 00:00:00 2001
From: Cristiano Hoshikawa <hoshikawa@uol.com.br>
Date: Mon, 27 Apr 2026 07:27:09 -0300
Subject: [PATCH] Update README.md

---
 README.md | 314 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 312 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3e6ef5a..0cfb616 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,312 @@
-# nemo_guardrails_oci_generative_ai
-Nemo Guardrails in OCI Generative AI
+
+# Tutorial Avançado: Integração do NeMo Guardrails com OCI Generative AI via Proxy OpenAI-Compatible
+
+---
+
+## Introdução
+
+Este tutorial demonstra como utilizar o **OCI Generative AI** por meio de uma interface compatível com a API da OpenAI, permitindo integração com frameworks modernos como o NeMo Guardrails.
+
+A ideia principal não é apenas “usar um proxy”, mas sim:
+
+>**Nota:** **desacoplar o modelo de linguagem (LLM) da aplicação**, criando uma camada intermediária que permite:
+- trocar modelos facilmente
+- integrar diferentes provedores (OCI, OpenAI, modelos locais)
+- padronizar consumo via API OpenAI
+
+---
+
+## Ideia Central
+
+O proxy `oci_openai_proxy.py` atua como um **adaptador universal**:
+
+- Recebe requisições no padrão OpenAI (`/v1/chat/completions`)
+- Traduz para chamadas do OCI Generative AI
+- Retorna resposta no mesmo formato OpenAI
+
+>**Nota:** Isso permite que ferramentas como o NeMo Guardrails funcionem sem saber que estão usando OCI.
+
+>**Mais importante:**
+Esse modelo permite evoluir para:
+- múltiplos LLMs
+- fallback entre provedores
+- balanceamento
+- controle centralizado
+
+---
+
+## Conceitos Fundamentais (Explicação detalhada)
+
+### 1. Proxy OpenAI-Compatible
+
+Um proxy é uma aplicação intermediária que:
+
+- recebe requisições padronizadas
+- adapta para outro backend
+- retorna no mesmo formato
+
+Neste caso:
+
+Entrada:
+```
+/v1/chat/completions
+```
+
+Saída:
+```
+OCI Generative AI → resposta OpenAI-like
+```
+
+>**Nota:** Benefício:
+Você não precisa alterar aplicações ao trocar o modelo.
+
+---
+
+### 2. NeMo Guardrails
+
+O **entity["software","NVIDIA NeMo Guardrails","framework"]** é um framework que permite:
+
+- controlar comportamento do LLM
+- aplicar regras de segurança
+- garantir previsibilidade
+
+Ele atua como uma camada entre:
+
+```
+Usuário ↔ Guardrails ↔ LLM
+```
+
+---
+
+### 3. Guardrails (Rails)
+
+Guardrails são regras que atuam em pontos específicos:
+
+- antes da entrada (input)
+- durante o processamento
+- após a resposta (output)
+
+>**Nota:** Eles permitem:
+- bloquear conteúdo
+- validar respostas
+- controlar comportamento
+
+---
+
+### 4. Arquitetura Final
+
+```
+User
+ ↓
+NeMo Guardrails
+ ↓
+Proxy OpenAI (porta 8051)
+ ↓
+OCI Generative AI
+ ↓
+Resposta
+```
+
+---
+
+## Pré-requisitos
+
+- Python 3.10+
+- OCI configurado (`~/.oci/config`)
+- Dependências:
+
+```bash
+pip install nemoguardrails fastapi uvicorn
+```
+
+---
+
+## Subindo o Proxy OCI
+
+### Arquivo: oci_openai_proxy.py
+
+Este arquivo é responsável por:
+
+- expor endpoint OpenAI
+- traduzir requisições para OCI
+- formatar respostas
+
+### Execução
+
+```bash
+uvicorn oci_openai_proxy:app --host 0.0.0.0 --port 8051
+```
+
+>**Nota:** Endpoint disponível:
+
+```
+http://localhost:8051/v1/chat/completions
+```
+
+---
+
+## Configuração do NeMo Guardrails
+
+### Estrutura de arquivos
+
+```
+config/
+ ├── config.yml
+ ├── rails.co
+```
+
+---
+
+## Arquivo: config.yml (Explicação detalhada)
+
+Este é o arquivo principal de configuração.
+
+### models
+
+Define qual modelo será usado.
+
+```yaml
+models:
+  - type: main
+    engine: openai
+    model: gpt-4
+```
+
+>**Nota:** Importante:
+Mesmo usando OCI, usamos `engine: openai` porque o proxy simula essa API.
+
+---
+
+### parameters
+
+```yaml
+parameters:
+  base_url: http://localhost:8051/v1
+  api_key: dummy
+```
+
+- `base_url`: aponta para o proxy
+- `api_key`: não é usada, mas é exigida pela interface OpenAI
+
+---
+
+### rails
+
+```yaml
+rails:
+  input:
+    flows:
+      - self check input
+  output:
+    flows:
+      - self check output
+```
+
+>**Nota:** Define quais regras serão aplicadas.
+
+---
+
+## Arquivo: rails.co (Explicação detalhada)
+
+Este arquivo define os **fluxos de comportamento**.
+
+Ele usa a linguagem Colang.
+
+### Exemplo:
+
+```co
+define flow self check input
+  user input
+  bot respond "Input validado"
+```
+
+>**Nota:** Isso significa:
+Sempre que houver entrada do usuário, execute esse fluxo.
+
+---
+
+### Output flow
+
+```co
+define flow self check output
+  bot output
+  bot respond "Output validado"
+```
+
+>**Nota:** Intercepta a saída antes de retornar ao usuário.
+
+---
+
+## Executando o NeMo
+
+```bash
+nemoguardrails run --config config
+```
+
+>**Nota:** Isso inicia o servidor do guardrails.
+
+---
+
+## Testando
+
+```bash
+curl http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-4",
+    "messages": [{"role": "user", "content": "Olá"}]
+  }'
+```
+
+---
+
+## Resultados Esperados
+
+Você deverá observar:
+
+- request passa pelo guardrails
+- proxy é acionado
+- OCI responde
+- saída é filtrada
+
+Fluxo real:
+
+```
+User
+ ↓
+Input Rails
+ ↓
+LLM (via Proxy)
+ ↓
+Output Rails
+ ↓
+Resposta final
+```
+
+---
+
+## Observações Importantes
+
+- O proxy deve estar ativo antes do NeMo
+- Logs podem ser ativados para debug
+- O sistema é extensível para:
+  - múltiplos modelos
+  - fallback automático
+  - auditoria
+
+---
+
+## Conclusão
+
+Este modelo permite:
+
+- desacoplar LLM da aplicação
+- trocar backend sem impacto
+- aplicar governança com guardrails
+- evoluir para arquitetura multi-modelo
+
+---
+
+## Acknowledgments
+
+- **Author** - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)