Files · Perplexity Security Guardrails for SMB Financial Queries

# Perplexity Security Guardrails for SMB Financial Queries
 
Safely use Perplexity's search-augmented AI for financial Q&A with real-time PII redaction, harmful-content blocking, and audit logging.
 
## Problem
 
SMBs handling customer financial data must avoid exposing PII or sensitive information when using AI for support or analysis. Off-the-shelf chatbots lack guardrails for finance-specific compliance risks.
 
## Architecture
 
The request flow goes through a multi-layer guardrail pipeline before and after calling the Perplexity API:
 
```
User Query
  → Input Guardrails: PII Redaction → Presidio Security → Prompt Injection Detector → Topic Boundary → Cost Precheck → Rate Limiter
    → Perplexity API (search-augmented LLM)
      → Output Guardrails: PII Scan → Hallucination Check (cached) → Toxicity Filter
        → Response
```
 
Every guardrail rejection is logged as an incident via `@reaatech/guardrail-chain-observability`, and cost data is recorded via `@reaatech/llm-cost-telemetry`.
 
## Packages
 
### REAA packages
- `@reaatech/guardrail-chain@0.1.0` — core chain orchestration, `Guardrail` interface, budget management
- `@reaatech/guardrail-chain-config@0.1.0` — config loading from env/file with Zod validation
- `@reaatech/guardrail-chain-guardrails@0.1.0` — built-in guardrails (PII, injection, topic, toxicity, hallucination, etc.)
- `@reaatech/guardrail-chain-observability@0.1.0` — pluggable logging, metrics, and tracing
- `@reaatech/llm-cost-telemetry@0.1.0` — cost span tracking and budget monitoring
 
### Third-party
- `perplexity-sdk@1.0.4` — Unofficial Perplexity API client
- `@presidio-dev/hai-guardrails@1.12.0` — enterprise-grade PII, injection, and secret detection
- `zod@4.4.3` — runtime schema validation
 
## Quick Start
 
```bash
pnpm install
cp .env.example .env
# Fill in PERPLEXITY_API_KEY
pnpm dev
```
 
## API
 
### POST /api/chat
 
**Request body:**
 
```json
{
  "messages": [
    { "role": "user", "content": "What is my account balance?" }
  ],
  "userId": "user-123",
  "sessionId": "session-456",
  "model": "pplx-70b-online"
}
```
 
**Success response (200):**
 
```json
{
  "reply": "Your account balance is $1,234.56.",
  "passed": true,
  "cost": {
    "inputTokens": 50,
    "outputTokens": 100,
    "costUsd": 0.00015
  }
}
```
 
**Rejected response (403):**
 
```json
{
  "reply": "",
  "passed": false,
  "incident": {
    "id": "abc-123",
    "timestamp": "2026-05-28T12:00:00.000Z",
    "reason": "Input contained PII",
    "guardrailId": "pii-redaction",
    "phase": "input",
    "severity": "medium"
  }
}
```
 
## Guardrail Pipeline
 
### Input guardrails (in order)
1. **PresidioAdapter** — wraps `@presidio-dev/hai-guardrails` for injection, PII, and secret detection (heuristic mode)
2. **PIIRedaction** — regex-based PII masking with custom financial patterns (account numbers, routing numbers)
3. **PromptInjection** — jailbreak and instruction-injection detection
4. **TopicBoundary** — allows only finance/accounting topics; blocks politics, religion, gambling, hacking
5. **CostPrecheck** — heuristic token estimation before the API call
6. **RateLimiter** — 60 requests per minute per user
 
### Output guardrails (in order)
1. **PIIScan** — scans Perplexity output for leaked PII
2. **HallucinationCheck** (cached) — detects speculative language ("I think", "probably")
3. **ToxicityFilter** — regex-based toxicity detection
 
## Environment Variables
 
| Variable | Description |
|---|---|
| `PERPLEXITY_API_KEY` | Perplexity API key (required) |
| `PERPLEXITY_MODEL` | Model ID (default: `pplx-70b-online`) |
| `GUARDRAIL_CHAIN_BUDGET_MAX_LATENCY_MS` | Latency budget in ms (default: 3000) |
| `GUARDRAIL_CHAIN_BUDGET_MAX_TOKENS` | Token budget (default: 8000) |
| `GUARDRAIL_CHAIN_BUDGET_SKIP_SLOW` | Skip slow guardrails under pressure (default: true) |
 
## Testing
 
```bash
pnpm typecheck
pnpm lint
pnpm test
```
 
All HTTP calls are mocked via `vi.mock` — no live API keys needed for tests.
 
## License
 
MIT