new feature: Integration with kbdb Autonomous

docs/RAG_PROVIDER_KBDB.md

@@ -0,0 +1,94 @@
+# RAG alternativo: Standard x KBDB Enterprise
+
+O framework passa a suportar dois backends de retrieval pelo mesmo contrato `RagService`, sem alterar os agentes nem `_retrieve_rag_context()`.
+
+## Seleção
+
+```env
+RAG_PROVIDER=standard  # default: comportamento anterior
+# ou
+RAG_PROVIDER=kbdb      # KBDB enterprise
+```
+
+A seleção é exclusiva por processo. Os dois RAGs não executam juntos e não compartilham vector store, graph store ou ingestão.
+
+## `standard`
+
+Mantém integralmente o RAG já existente no `agent_framework_oci`: `VECTOR_STORE_PROVIDER`, `GRAPH_STORE_PROVIDER`, embedding, query rewrite, compression, retrieval guardrails e geração continuam válidos.
+
+## `kbdb`
+
+O framework integra somente a porta estável de serving do projeto KBDB:
+
+`PKG_KB_SERVING.SEARCH_KNOWLEDGE_BASE`
+
+O pipeline enterprise continua externo ao runtime do agente e preserva sua própria arquitetura RAW → SILVER → GOLD, HVI/hybrid search, property graph, publicação, lifecycle, auditoria e observabilidade.
+
+O envelope KBDB é adaptado para `RagResult`/`VectorDocument`; portanto os agentes existentes continuam chamando `_retrieve_rag_context()` e os retrieval guardrails do framework continuam depois do retrieval.
+
+### Configuração
+
+```env
+RAG_PROVIDER=kbdb
+RAG_TOP_K=5
+KBDB_DB_USER=KB_USER
+KBDB_DB_PASSWORD=...
+KBDB_DB_DSN=...
+KBDB_DB_WALLET_LOCATION=...
+KBDB_DB_WALLET_PASSWORD=...
+KBDB_SEARCH_TYPE=hybrid
+KBDB_NODE_EXPANSION=true
+KBDB_NODE_MAX_RELATED=8
+KBDB_GRAPH_CROSS_REF=false
+KBDB_MAX_CROSS_REF_HOPS=1
+KBDB_DOCUMENT_TYPE=customer_safe
+KBDB_METADATA_JSON=
+KBDB_MIN_SCORE=
+```
+
+Quando `RAG_PROVIDER=kbdb`, `KBDB_DB_USER`, `KBDB_DB_PASSWORD` e `KBDB_DB_DSN` são obrigatórios. O KBDB usa conexão isolada porque pode residir em outro Autonomous. `KBDB_DB_DSN` segue a mesma semântica de `ADB_DSN`: use o alias TNS existente no `tnsnames.ora` da wallet indicada por `KBDB_DB_WALLET_LOCATION`, e não uma URL `tcps://...`.
+
+## Isolamento e compatibilidade
+
+- `RAG_PROVIDER=standard` não importa nem conecta ao KBDB.
+- `RAG_PROVIDER=kbdb` não instancia vector/graph stores do RAG padrão.
+- Ingestão por `RagService.add_documents()` não é permitida no modo KBDB: deve passar pelo pipeline/publicação KBDB.
+- Query rewrite e context compression continuam opcionais e são aplicados pela camada comum do framework.
+- `AgentRuntimeMixin._retrieve_rag_context()` e os agentes permanecem inalterados.
+- Falhas do KBDB seguem a semântica existente do framework: retrieval é evidência auxiliar e a exceção é convertida em metadata técnica sem derrubar a jornada.
+
+
+## Resposta direta de tool e RAG
+
+O framework não considera mais que um resultado MCP estruturado é, por si só, uma resposta suficiente ao usuário.
+
+Uma política `response.renderer` define somente **como** apresentar o resultado. Ela não encerra o fluxo antes de RAG/LLM. Para uma tool deliberadamente produzir uma resposta final direta, a aplicação deve declarar explicitamente:
+
+```yaml
+response:
+  mode: renderer
+  renderer: meu.renderer
+  direct: true
+```
+
+Sem `direct: true`, o resultado da tool permanece como evidência MCP e o fluxo segue para `_retrieve_rag_context()` e composição LLM. Isso permite, por exemplo, que uma consulta operacional de plano seja combinada com conhecimento documental do KBDB quando a pergunta pedir regras, políticas ou explicações.
+
+O core do framework não possui fallback por nome de tool (`consultar_plano`, `consultar_pedido`, etc.). Regras de apresentação pertencem à aplicação/domínio.
+
+
+## Suficiência MCP e grounding
+
+Um resultado MCP bem-sucedido **não** faz o framework pular RAG automaticamente.
+O domínio só pode declarar suficiência documental explicitamente no payload com
+`rag_sufficient=true` ou `knowledge_sufficient=true`. Essa decisão é genérica e
+não depende do nome da tool nem de palavras-chave de telecom/retail.
+
+No provider `kbdb`, `KBDB_GROUNDED_ONLY=true` é o padrão. Quando a busca KBDB
+retorna vazia, bloqueada ou com erro, a composição LLM pode usar fatos comprovados
+por MCP/business context, mas não pode completar a parte documental com conhecimento
+paramétrico do modelo. Deve informar que não há evidência suficiente na base.
+
+Eventos do ProductAgent registram `IC.PRODUCT_RAG_CONTEXT_EVALUATED` em toda
+tentativa/decisão e `IC.PRODUCT_RAG_CONTEXT_RETRIEVED` somente quando há contexto
+recuperado. Os metadados incluem `provider`, `status`, `document_count`, `reason`,
+`error`, `query`, `namespace` e `latency_ms`.