# 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.