CLAUDE.md

Guidance for Claude Code working in this repo. Read this first.

What this is

A demo (not production) of a reversible PII de-identification round trip for HNCB: advisor query with a real name → tokenized before it leaves for the cloud → Amazon Bedrock AgentCore agent reasons on tokens only → identity restored on-prem before the advisor sees the answer. Everything runs in one AWS account; "on-prem" is a logical, tag-labelled zone standing in for the branch data centre. The demo proves data-flow behaviour, not physical residency.

Critical context

Fusion is a shared SaaS instance. DO NOT build, host, or Terraform it. It is configured in the Amplify AI Gateway console (see fusion/POLICY_SETUP.md). Because it is SaaS, anything it calls must be a public HTTPS endpoint with auth — it cannot reach private VPC resources or use local AWS creds.
This means the AWS side's job is to expose two endpoints Fusion will call: /tokenize (ingress) and /restore (egress), plus host the detector, vault, RAG tool, and agent. See the task backlog below.
Detection ≠ redaction. The detector returns typed findings; our code owns minting tokens, writing the vault, and restoring. Never redact-and-discard.
Tokens must be random per request and stored in the vault keyed by session.

Architecture (maps to the customer's 8 steps)

Advisor UI → Fusion SaaS → [/tokenize: detect (Presidio) + mint + vault-write] → AgentCore Runtime (Bedrock model) → tool call via AgentCore Gateway → RAG Lambda (resolve token → de-identified evidence) → agent talking points → Fusion SaaS → [/restore: vault lookup] → Advisor UI.

Repo map

terraform/       DynamoDB (vault + customers), RAG Lambda, IAM, Presidio hosting
lambda_rag/      RAG tool (real): token resolve -> evidence package
gateway_api/     TODO: /tokenize and /restore HTTPS endpoints Fusion calls  (T1, T2)
agent/           Strands agent for AgentCore Runtime + tool schema
presidio/        detector service (typed findings) + Dockerfile
seed/            fake customer (Wang Xiaoming) + seed script
ui/              advisor UI (restored-vs-tokenized split view)
scripts/         deploy.sh, agentcore_setup.sh, teardown.sh
fusion/          POLICY_SETUP.md (SaaS console config — human does this, not you)

Commands

Deploy core infra: bash scripts/deploy.sh (review first)
Seed data: VAULT_TABLE=... CUSTOMERS_TABLE=... python seed/seed.py --with-demo-token
AgentCore: bash scripts/agentcore_setup.sh (verify against agentcore --help)
Teardown (do this to stop spend): bash scripts/teardown.sh
Terraform: run all terraform commands with -chdir=terraform.

Conventions & guardrails

Region default us-east-1 (best Bedrock/AgentCore quotas). Keep it a variable.
Never commit AWS creds, tokens, or real PII. Seed data is synthetic only.
Python: standard library + boto3; keep handlers small and dependency-light.
Pin bedrock-agentcore / strands-agents versions before agentcore launch — these SDKs move fast; verify signatures against installed versions, don't assume.
Prefer Lambda Function URLs (with auth) or API Gateway for the public endpoints.
After any infra change, remind the human to teardown when done recording.

Task backlog (pick these up)

Each task: keep it demo-grade, add a note in the file, and update this list.

T1 — /tokenize endpoint (gateway_api/tokenize/). HTTPS endpoint Fusion calls with {query}. Steps: POST query to Presidio /analyze; for each finding mint a random token (CUST_<rand> for PERSON→customer, TW_<rand> for TW_ROC_ID); write vault items {token, type, value, session_id, expires_at}; splice tokens into the text. Return {deidentified_prompt, session_id}. Accept: real name in → tokenized text + session_id out; vault rows written; same input yields different tokens on repeat calls.
T2 — /restore endpoint (gateway_api/restore/). Input {session_id, text}. Look up this session's tokens in the vault, re-attach identity (envelope-level: prepend the real name; also swap any inline tokens). Return {final}. Accept: tokenized answer + session_id → answer with 王小明 restored.
T3 — reachability from SaaS. Make Presidio (or fold detection into T1 so only /tokenize + /restore are public) reachable from Fusion SaaS with auth. Accept: Fusion SaaS can call the endpoints over HTTPS; nothing else is public.
T4 — AgentCore Gateway target. Wire the RAG Lambda as the MCP tool; confirm the agent can call get_customer_activity_summary(CUST_000123) and get the package. Accept: a manual agentcore invoke returns the evidence package.
T5 — Agent runtime. Pin deps, agentcore launch, capture the Runtime ARN. Accept: invoking the runtime with a tokenized prompt returns talking points.
T6 — UI wiring. Point ui/index.html GATEWAY_URL at the Fusion SaaS entry (or /tokenize for a Fusion-less dry run); host on S3+CloudFront. Accept: the split view renders restored vs tokenized.
T7 — E2E rehearsal. Run the full script in README; confirm the Bedrock/ AgentCore trace shows only tokens. Then verify teardown.sh leaves nothing paid-for.

Known caveats (don't "fix" these silently)

zh-TW detection is demo-narrow (tuned to the scripted entities), not production recall.
The agentic token-resolution loop (T4) is custom orchestration by design.
If you touch fusion/, it's documentation for a human — do not try to automate SaaS config.

5.5 KiB Raw Blame History