Files · Google Gemini Security Guardrails for SMB Healthcare PII Redaction

# Google Gemini Security Guardrails for SMB Healthcare PII Redaction
 
> Automatically detect and redact PHI from patient messages before they reach the LLM, helping small clinics stay HIPAA‑compliant.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Problem
 
Small healthcare providers using AI chatbots for patient intake risk exposing protected health information (PHI) to LLM APIs — a HIPAA violation that can result in severe fines and loss of trust.
 
## Solution
 
This recipe layers multiple guardrail strategies to ensure PHI never reaches the LLM:
 
1. **PII Detection** — `@presidio-dev/hai-guardrails` detects PHI (emails, SSNs, phone numbers) in incoming messages
2. **Guardrail Chain** — `@reaatech/guardrail-chain` with `@reaatech/guardrail-chain-guardrails` `PIIRedaction` redacts detected entities
3. **Entity Mapping** — Custom `EntityMapper` tracks original↔redacted token mappings for re-identification of responses
4. **LLM** — Redacted prompts are sent to Google Gemini via `@google/genai`
5. **Tool-Use Firewall** — `@reaatech/tool-use-firewall-core` inspects all tool calls and blocks those containing unredacted PHI
6. **Session Continuity** — `@reaatech/session-continuity` persists entity maps across multi-turn conversations
7. **Cost Tracking** — `@reaatech/llm-cost-telemetry` records cost per LLM call with Gemini 2.5 Flash pricing
 
## Architecture
 
```
User message
  → POST /api/chat
    → @presidio-dev/hai-guardrails PII detection
    → @reaatech/guardrail-chain redaction
    → Entity mapping (original ↔ [PHI-N])
    → @google/genai Gemini 2.5 Flash LLM
    → @reaatech/tool-use-firewall-core tool-call inspection
    → Response re-identification
    → @reaatech/session-continuity persistence
    → @reaatech/llm-cost-telemetry tracking
  → JSON response
```
 
## API Contract
 
### `POST /api/chat`
 
**Request:**
```json
{
  "message": "My email is john@example.com",
  "sessionId": "optional-existing-session-id",
  "userId": "optional-user-id"
}
```
 
**Response (200):**
```json
{
  "reply": "I see your email is john@example.com (re-identified)",
  "sessionId": "uuid",
  "redacted": true,
  "costUsd": 0.001
}
```
 
**Error responses:**
- `400` — Invalid request body (missing/empty `message` or malformed JSON)
- `403` — Tool call blocked (references unredacted PHI)
- `500` — Internal server error
 
## Getting Started
 
```bash
pnpm install
cp .env.example .env
# Edit .env: add your GEMINI_API_KEY
pnpm dev              # Start dev server at http://localhost:3000
pnpm test             # Run tests with coverage
pnpm typecheck        # TypeScript check
pnpm lint             # ESLint check
```
 
## Project Structure
 
```
app/api/chat/route.ts     Next.js App Router API route handler
src/types.ts              Shared types and Zod schemas
src/services/
  pii-detector.ts         @presidio-dev/hai-guardrails wrapper
  guardrail-chain-service.ts  @reaatech/guardrail-chain orchestration
  session-service.ts      @reaatech/session-continuity management
  entity-mapper.ts        PHI token mapping utilities
  firewall-service.ts     @reaatech/tool-use-firewall-core integration
  llm-client.ts           @google/genai Gemini client
  cost-tracker.ts         @reaatech/llm-cost-telemetry tracking
tests/                    Vitest test suite (59+ tests)
```
 
## Packages Used
 
| Package | Purpose |
|---|---|
| `@reaatech/guardrail-chain@0.1.0` | Guardrail chain orchestration |
| `@reaatech/guardrail-chain-guardrails@0.1.0` | PIIRedaction guardrail |
| `@reaatech/session-continuity@0.1.0` | Multi-turn session management |
| `@reaatech/tool-use-firewall-core@0.1.0` | Tool-call firewall |
| `@reaatech/llm-cost-telemetry@0.2.0` | LLM cost tracking |
| `@google/genai@2.8.0` | Google Gemini SDK |
| `@presidio-dev/hai-guardrails@1.12.0` | PII detection |
| `zod@4.4.3` | Schema validation |
 
## Environment Variables
 
| Variable | Description |
|---|---|
| `GEMINI_API_KEY` | Google Gemini API key (get from aistudio.google.com) |
| `SESSION_TTL_SECONDS` | Session time-to-live in seconds |
| `COST_BUDGET_DAILY_USD` | Daily cost budget |
| `OTEL_SERVICE_NAME` | OpenTelemetry service name |
 
## License
 
MIT — see [LICENSE](./LICENSE).