Metadata-Version: 2.4
Name: finguard
Version: 0.4.1
Summary: FinGuard — Open-source LLM safety layer for financial AI
Author: FinGuard Authors
License: MIT
License-File: LICENSE
Requires-Python: <3.13,>=3.10
Requires-Dist: huggingface-hub[hf-xet]
Requires-Dist: llm-guard[onnxruntime]>=0.3.14
Requires-Dist: numpy<2.0.0
Requires-Dist: onnx
Requires-Dist: onnxruntime
Requires-Dist: optimum
Requires-Dist: pip
Requires-Dist: presidio-analyzer>=2.2.35
Requires-Dist: presidio-anonymizer>=2.2.35
Requires-Dist: pydantic
Requires-Dist: pyyaml>=6.0
Requires-Dist: torch>=2.4.0
Provides-Extra: all
Requires-Dist: langfuse>=4.0.0; extra == 'all'
Requires-Dist: opentelemetry-api>=1.40.0; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.40.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: observability
Requires-Dist: langfuse>=4.0.0; extra == 'observability'
Requires-Dist: opentelemetry-api>=1.40.0; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.40.0; extra == 'observability'
Description-Content-Type: text/markdown

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

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1-gtumX-iv2qUeAwr27ULvwI-_WEGgFMd#scrollTo=iNfXwkl8YbJG)

---

## ⚡ Quick Start

### Installation
```bash
# 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
```

```python
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:

```python
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](https://microsoft.github.io/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
```yaml
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]`).

```yaml
# 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:

```python
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

```bash
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.
