finguard 0.4.1

FinGuard — Open-source LLM safety layer for financial AI

FinGuard 🛡️

The LLM Safety Orchestration Layer for Financial AI.

FinGuard is a modular, plug-and-play guardrail framework built for fintech teams. It wraps any LLM with a tiered safety pipeline covering PII redaction, prompt injection detection, regulatory compliance, and financial fraud signals — all configurable via simple YAML policies.

---

⚡ Quick Start

Installation

# Recommended for standard use
pip install finguard

# REQUIRED for Optimized (ONNX) latency in environments like Google Colab
pip install finguard onnxruntime optimum

# (Optional but Recommended) Pre-fetch models to avoid first-run latency
finguard-download

from finguard import FinGuard

guard = FinGuard(policy="retail_banking")

@guard.wrap
async def banking_assistant(prompt: str) -> str:
    return await llm.generate(prompt)

# PAN card in prompt is automatically blocked
response = await banking_assistant("My PAN is ABCDE1234F, reset my password")

---

🏗️ Tiered Safety Architecture

FinGuard uses a three-tier pipeline — each tier adds safety depth at the cost of latency. Pick the tier that fits your use case.

Tier	Policy	Avg Latency	What It Covers
Tier 1 — Fast Lane	fast_lane	~35ms	Regex PII (PAN, Aadhaar, IFSC, UPI), PMLA
Tier 2 — Standard	retail_banking, default	~55ms	Tier 1 + Native Presidio NER + Injection AI
Tier 3 — Full Stack	high_security, wealth_advisor	~180ms	Tier 2 + Topic Banning + Compliance Phrases

Benchmarks measured on CPU (ONNX runtime, no GPU). Mock LLM latency excluded.

---

📋 Policy Catalog

FinGuard ships with 5 ready-to-use policies. Load by name:

guard = FinGuard(policy="high_security")

Policy	Use Case	Tier
default	Balanced starting point for any financial bot	2
fast_lane	High-throughput systems: IVR, SMS bots, dashboards	1
retail_banking	Branch chatbots, net banking, UPI assistants	2
wealth_advisor	Robo-advisors, portfolio managers (SEBI compliance)	3
high_security	Fraud ops, compliance officers, internal audit tools	3

---

🔍 What Gets Protected

PII — Finance Base (Always Active)

Native Presidio entities with context-awareness and checksum validation:

Entity	ID	Detection
Credit Card	CREDIT_CARD	Pattern + Luhn checksum
IBAN	IBAN_CODE	Pattern + checksum
PAN Card	IN_PAN	Pattern + context
Aadhaar	IN_AADHAAR	Pattern + Verhoeff checksum
IFSC Code	IN_IFSC	Custom pattern + context
UPI/VPA	IN_VPA	Custom pattern + context
Email / Phone	EMAIL_ADDRESS, PHONE_NUMBER	Pattern

Optional Locale Packs

pii:
  locale_packs: ["IN_EXTENDED"]  # Adds Voter ID, Passport, Vehicle Reg
  # locale_packs: ["US"]         # Adds SSN, Driver License
  # locale_packs: ["GLOBAL"]     # Adds IP, URL, Location

Fraud & Compliance

• PMLA Scanner — flags high-value transfers (>₹50,000) with transfer keywords
• Compliance Phrases — enforces SEBI/RBI-style disclaimers on investment advice
• Numerical Hallucination — validates AI-stated figures against prompt context
• Topic Banning — blocks off-domain queries (crypto, medical, illegal lending)

---

🕵️‍♂️ Enterprise Observability & Audit

FinGuard features GuardTrace, a forensic-grade audit engine designed for SOC2 compliance and incident response. Every safety decision is fully reconstructable, without logging raw PII.

1. Multi-Backend Logging

Out-of-the-box support for:

• NDJSON File Logging: Built for easy ingestion into Splunk, DataDog, and ElasticSearch.
• Langfuse: Hierarchical session traces + visual violation scoring (pip install finguard[observability]).
• OpenTelemetry: Native OTEL spans and metrics for enterprise APM (pip install finguard[observability]).

# policy.yaml
audit:
  backend: "langfuse"       # "memory" | "file" | "langfuse" | "otel"
  emit_traces: true
  redact_input: true        # Logs SHA-256 fingerprint instead of raw text
  include_metadata_keys: ["session_id", "user_id"] # Safe tracking

2. Agentic Backtracking

If FinGuard blocks an agent's tool call or prompt, it raises a structured FinGuardViolation containing the exact GuardTrace. Your agent can catch this, inspect the violation, and self-correct its plan instead of crashing:

from finguard.exceptions import FinGuardViolation

try:
    response = await banking_assistant("Process transfer for 1234-5678-9012-3456")
except FinGuardViolation as e:
    failed_scanners = [s.scanner for s in e.trace.input_scanners if s.triggered]
    if "presidio_pii" in failed_scanners:
        print("Self-correcting: removing PII and retrying...")

---

🧩 Architecture

Prompt → [Tier 1: Regex Fast-Path] → [Tier 2: Presidio NER + ONNX AI] → [Tier 3: Compliance] → LLM → Output Guard → Response

• Singleton model cache — ONNX models loaded once per process, shared across all guards
• Whitelist-only PII registry — only finance-relevant recognizers are active; no BTC/SSN overhead
• Per-component latency — every GuardResult exposes component_latencies for observability

---

📊 Benchmarking

uv run benchmark.py

Sample output:

══════════════════════════════════════════════════════════════
  BENCHMARK SUMMARY
══════════════════════════════════════════════════════════════
  Tier                                     Avg      Min      Max
  Tier 1 – Fast Lane  (Regex)            35.0ms   30.5ms   36.9ms
  Tier 2 – Retail     (NER+AI)           54.7ms   47.3ms   65.4ms
  Tier 3 – High Sec   (Full)            181.0ms  149.2ms  277.3ms
══════════════════════════════════════════════════════════════

⚖️ License

MIT License.