new feature: transaction evidence

Tuning-Performance/Transaction_Evidence/README.md

@@ -0,0 +1,172 @@
+# Transaction Evidence / Evidência Operacional de Transação
+
+Esta variante demonstra a funcionalidade **Transaction Evidence** do `agent_framework_oci`.
+Ela preserva o resultado estruturado de transações executadas no estado/checkpoint do
+LangGraph e o reutiliza, quando relevante, em turnos posteriores como evidência
+operacional para composição de resposta e groundedness.
+
+> Transaction Evidence **não é Long Term Memory**. É estado operacional associado à
+> sessão/workflow e aos recursos envolvidos na transação.
+
+## Problema que resolve
+
+Sem esta funcionalidade, uma transação pode ocorrer corretamente em um turno:
+
+```text
+quero cancelar pedido
+PED-1001
+sim
+→ protocolo CANCEL-2026-001
+```
+
+mas, no turno seguinte:
+
+```text
+quero meu pedido
+```
+
+o runtime pode consultar apenas `consultar_pedido`. Se a resposta mencionar o
+cancelamento/protocolo visto no turno anterior, o judge de groundedness pode tratar
+isso como informação não evidenciada.
+
+Com Transaction Evidence, o resultado transacional confirmado fica estruturado em
+`transaction_evidence` e pode aparecer como `relevant_transaction_evidence` quando
+correlacionado ao recurso atual.
+
+## Fluxo demonstrado
+
+```text
+cancelar_pedido(PED-1001)
+        ↓
+transação executada
+        ↓
+transaction_evidence
+  - tool_name
+  - arguments
+  - transaction_id
+  - status
+  - result/protocolo
+        ↓
+checkpoint da sessão
+        ↓
+novo turno: "quero meu pedido"
+        ↓
+consultar_pedido(PED-1001)
+        +
+relevant_transaction_evidence(PED-1001)
+        ↓
+resposta + groundedness com evidência operacional
+```
+
+## Regras de segurança e correlação
+
+A implementação do framework:
+
+- registra apenas resultados transacionais efetivamente executados;
+- mantém histórico bounded das evidências mais recentes;
+- correlaciona por identificadores de recurso, como `order_id`, `invoice_id`,
+  `asset_id`, `resource_key` e outros campos `*_id`;
+- evita reutilizar evidência de um recurso diferente;
+- disponibiliza somente a evidência relevante do turno em
+  `relevant_transaction_evidence`;
+- expõe a evidência relevante no metadata da resposta para diagnóstico;
+- inclui a evidência relevante no contexto usado pelos judges/groundedness.
+
+## Configuração
+
+Não existe uma variável obrigatória `ENABLE_TRANSACTION_EVIDENCE` nesta versão.
+A funcionalidade faz parte do runtime transacional do framework e depende da
+persistência de estado/checkpoint já usada pelo agente.
+
+Os principais pontos do exemplo são:
+
+- `app/state.py`: campos `transaction_evidence`, `last_transaction_evidence` e
+  `relevant_transaction_evidence`;
+- `app/workflows/agent_graph.py`: injeta evidência relevante no contexto dos judges;
+- `app/main.py`: publica `transaction_evidence` no metadata da resposta;
+- framework: `runtime/agent_runtime.py`: grava, correlaciona e materializa a evidência.
+
+## Executar
+
+```bash
+cd Tuning-Performance/Transaction_Evidence/agent_template_backend
+pip install -e ../../../libs/agent_framework
+pip install -r requirements.txt
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Use o frontend normalmente apontando para `http://localhost:8000`.
+
+## Cenário de teste recomendado
+
+Execute na mesma sessão:
+
+```text
+quero meu pedido
+quero cancelar pedido
+PED-1001
+sim
+quero meu pedido
+```
+
+Na última rodada, valide no JSON de resposta:
+
+```json
+{
+  "route": "orders_agent",
+  "intent": "retail_order_tracking",
+  "transaction_evidence": [
+    {
+      "tool_name": "cancelar_pedido",
+      "status": "COMPLETED"
+    }
+  ]
+}
+```
+
+A estrutura exata do `result` depende da tool transacional, mas o protocolo retornado
+pela transação deve estar presente na evidência relevante quando o recurso correlacionar.
+
+## Resultado esperado
+
+No último `quero meu pedido`:
+
+1. a intent deve ser `retail_order_tracking`;
+2. `consultar_pedido` deve ser executada normalmente;
+3. a evidência da transação anterior de `PED-1001` deve ser recuperada;
+4. a resposta pode mencionar o cancelamento/protocolo porque essa informação agora
+   está suportada por evidência operacional;
+5. o judge de groundedness deve receber essa mesma evidência.
+
+## Diferença para Long Term Memory
+
+| Transaction Evidence | Long Term Memory |
+|---|---|
+| Estado operacional | Memória semântica/pessoal |
+| Resultado de tools/transações | Preferências e fatos duráveis |
+| Correlacionado a recursos | Correlacionado ao sujeito |
+| Usado para grounding operacional | Usado para personalização/contexto |
+| Curto/médio prazo de workflow | Longo prazo entre conversas |
+
+---
+
+## English summary
+
+This variant demonstrates **Transaction Evidence**: executed transactional tool
+outcomes are persisted as structured operational evidence in LangGraph state/checkpoint.
+On later turns, the runtime correlates prior evidence with the current resource and
+exposes it as `relevant_transaction_evidence` to both response composition and
+judges/groundedness. It is operational workflow state, not Long Term Memory.
+
+Recommended test sequence:
+
+```text
+show my order
+cancel my order
+PED-1001
+yes
+show my order
+```
+
+On the last turn, verify that the response metadata contains relevant transaction
+evidence for the cancellation of `PED-1001`.