Reframe for shared SaaS Fusion; add /tokenize+/restore, CLAUDE.md pointer

README.md

@@ -1,34 +1,45 @@
 # hncb-fusion-deid-demo
 
-All-AWS demo of the HNCB use case: a **reversible PII de-identification round trip**
+Demo of the HNCB use case: a **reversible PII de-identification round trip**
 through **Axway Amplify AI Gateway (Fusion)**, with the reasoning done by an
 **Amazon Bedrock AgentCore** agent. The advisor types a query containing a real
-name; the cloud only ever sees a token; the real identity is restored on-prem
+name; the cloud only ever sees a token; the real identity is restored before the
-before the answer is shown.
+answer is shown.
 
-> **Status: unrun scaffold.** This was authored, not executed. Review everything,
+> **Working with Claude Code? Read `CLAUDE.md` first** — it has the context,
-> pin dependency versions, and expect to adjust AgentCore/Fusion specifics to the
+> commands, and task backlog.
-> current CLI/console. Demo-grade, not production-grade.
+
+> **Status: unrun scaffold.** Authored, not executed. Review everything, pin
+> dependency versions, and adjust AgentCore specifics to the current CLI.
+> Demo-grade, not production-grade.
+
+## Fusion is shared SaaS
+Fusion is **not deployed by this repo** — it's a shared Amplify AI Gateway SaaS
+instance, configured in its console (`fusion/POLICY_SETUP.md`). Because it's SaaS,
+anything it calls must be a **public HTTPS endpoint with auth**. So the AWS side's
+job is to expose two endpoints Fusion calls — **`/tokenize`** (ingress) and
+**`/restore`** (egress) — plus host the detector, vault, RAG tool, and agent.
+Those two endpoints are the main remaining build (tasks T1/T2 in `CLAUDE.md`).
 
 ## What it demonstrates
 Raw PII (a Chinese name + a Taiwan ROC ID) is detected on ingress, replaced with a
 **random, format-safe token**, and only the tokenized prompt goes to the cloud
-agent. The agent calls a tool back "on-prem" with the token, gets a de-identified
+agent. The agent tool-calls back "on-prem" with the token, gets a de-identified
 evidence package, and writes talking points. Fusion restores the identity on the
 way out. **The money shot:** show the Bedrock request / AgentCore trace live — the
 cloud only ever saw `CUST_000123`, never `王小明`.
 
 ## Trust zones are logical
-Everything is one AWS account. The "on-prem" zone is a set of tag-labelled
+Everything is one AWS account. The "on-prem" zone is tag-labelled resources
-resources (`Zone = on-prem-VPC-A`) standing in for HNCB's branch data centre. This
+(`Zone = on-prem-VPC-A`) standing in for HNCB's branch data centre. Proves
-demo proves **behaviour and data-flow**, not physical data residency — say so on
+data-flow behaviour, not physical residency — say so on camera.
-camera: *"in production this zone is the branch DC; here a VPC stands in for it."*
 
 ## Component → service map (their 8 steps)
 | Step | Component | Service in this repo |
 |---|---|---|
 | 1, 8 | Advisor UI | `ui/index.html` on S3+CloudFront (or local) |
-| 2, 3-route, 8 | **Fusion AI Gateway** (the product) | ECS Fargate — `terraform/ecs.tf`, config in `fusion/POLICY_SETUP.md` |
+| 2, 3-route, 8 | **Fusion AI Gateway** (the product) | **shared SaaS** — configured via `fusion/POLICY_SETUP.md` (not deployed) |
+| 2 (ingress), 8 (egress) | `/tokenize` + `/restore` endpoints Fusion calls | **TODO** `gateway_api/` (tasks T1/T2) |
 | 2 | PII **detector** (typed findings, not redaction) | Presidio on Fargate — `presidio/` |
 | 2, 4, 8 | Token **vault** (reversible map) | DynamoDB — `terraform/main.tf` |
 | 3, 7 | Cloud **agent** + model | AgentCore Runtime + Bedrock — `agent/` |
@@ -38,36 +49,38 @@ camera: *"in production this zone is the branch DC; here a VPC stands in for it.
 
 ## Repo layout
 ```
-terraform/           core infra (DynamoDB, RAG Lambda, IAM) + ECS hosting
+CLAUDE.md            start here if using Claude Code (context + task backlog)
+terraform/           DynamoDB (vault + customers), RAG Lambda, IAM, Presidio hosting
 lambda_rag/          RAG tool: token resolve -> de-identified evidence package
+gateway_api/         TODO: /tokenize + /restore endpoints Fusion SaaS calls (T1/T2)
 agent/               Strands agent for AgentCore Runtime + tool schema
-presidio/            PII detector service (returns typed findings) + Dockerfile
+presidio/            PII detector service (typed findings) + Dockerfile
 seed/                fake customer (Wang Xiaoming) + seed script
-ui/                  advisor UI with restored-vs-tokenized split view
+ui/                  advisor UI (restored-vs-tokenized split view)
 scripts/             deploy.sh, agentcore_setup.sh, teardown.sh
-fusion/              POLICY_SETUP.md  (the console/flow config — the manual part)
+fusion/              POLICY_SETUP.md (SaaS console config — the manual part)
 ```
 
 ## Prerequisites
 `aws-cli` configured (creds + region), `terraform >= 1.5`, `docker`, `python3`,
 the AgentCore CLI (`npm i -g @aws/agentcore`), Bedrock model access enabled for
-`bedrock_model_id`, and an Axway Amplify AI Gateway (Fusion) container image you
+`bedrock_model_id`, and access to the shared **Fusion SaaS** instance.
-supply (`fusion_image_uri`).
 
 ## Deploy
 ```bash
 bash scripts/deploy.sh          # infra -> presidio image -> ECS -> seed -> AgentCore
-# then: configure Fusion policy (fusion/POLICY_SETUP.md)
+# then: build /tokenize + /restore (gateway_api/, tasks T1/T2)
-# then: point ui/index.html GATEWAY_URL at the Fusion host and open it
+# then: configure the shared Fusion SaaS instance (fusion/POLICY_SETUP.md)
+# then: point ui/index.html GATEWAY_URL at the Fusion SaaS entrypoint and open it
 ```
 
 ## Demo script (maps to the 8 steps)
 1. Advisor UI: submit *"請幫我整理王小明最近三個月的理財往來，並給我下次拜訪話術。"*
-2. Fusion detects `王小明` + `A123456789`, tokenizes, logs tokens only.
+2. Fusion (via `/tokenize`) detects `王小明` + `A123456789`, tokenizes, logs tokens only.
 3. Show the Bedrock/AgentCore trace — the prompt the cloud saw contains `CUST_000123`.
 4-6. Agent tool-calls back on-prem; RAG resolves the token, returns a summary.
 7. Agent writes talking points (no PII).
-8. Fusion restores `王小明`; the UI shows the restored answer beside the tokenized view.
+8. Fusion (via `/restore`) restores `王小明`; the UI shows restored beside tokenized.
 
 ## Teardown
 ```bash
@@ -75,11 +88,9 @@ bash scripts/teardown.sh        # stop paying for Fargate / AgentCore
 ```
 
 ## Honest caveats
-- **zh-TW detection is demo-narrow.** Presidio here is tuned to the scripted
+- **zh-TW detection is demo-narrow** — tuned to the scripted entities, not
-  entities; a smooth run is **not** evidence of production zh-TW recall — that
+  production recall. That remains the real-engagement risk.
-  remains the real-engagement risk.
+- **Per-request randomization** lives in the `/tokenize` mint step; confirm it
-- **Per-request randomization** ("different each time") lives in the Fusion mint
+  satisfies HNCB's "different each time" requirement.
-  step (`fusion/POLICY_SETUP.md`); confirm it satisfies HNCB's requirement.
 - **The agentic token-resolution loop** (agent tool call → on-prem RAG resolves the
-  token) is custom orchestration — it is not turnkey on any gateway, which is
+  token) is custom orchestration by design — where Fusion's depth is the argument.
-  exactly where Fusion's orchestration depth is the argument.