# FinGuard Memory and Architectural Overview

## 1. Project Purpose & Scope
FinGuard is an LLM safety orchestration layer tailored for the financial sector. Unlike generic guardrails (e.g., standard NeMo or LlamaGuard) that look for toxicity or general prompt injection, FinGuard specifically targets domain risks such as unauthorized financial advice, hallucinated numerical claims (e.g., fake returns), and Indian PII (PAN, Aadhaar).

## 2. Core Architecture & Request Flow
The typical lifecycle of a request (`finguard/core.py`):
1. **Intercept (Input Pipeline):** The user's prompt passes through the `InputPipeline` (`finguard/pipeline.py`). It loads scanners defined in the active policy (e.g., `PromptInjection`, `BanTopics` via `llm-guard`).
2. **LLM Invocation:** If the prompt is deemed safe, the underlying `@guard.wrap` decorator invokes the internal LLM.
3. **Validation (Output Pipeline):** The LLM's response goes through the `OutputPipeline`. Financial-specific validators include:
   - `NumericalClaimValidator` (`finguard/validators/numerical.py`): Compares numerical values in the output against those in the prompt to catch ungrounded numerical claims (minimizing hallucinations).
   - `CompliancePhraseDetector` (`finguard/validators/compliance.py`): Checks for SEBI/RBI violating phrases (e.g., "risk-free", "guaranteed returns") using regex, and ensures required disclaimers are present.
4. **Audit Logging:** Interactions, latency, and violations are sent to `AuditLogger` (`finguard/audit.py`), allowing institutions to maintain PMLA audit records.

## 3. Configuration & Policies
FinGuard uses declarative YAML policies (`finguard/policies/` & `finguard/config.py`), parsed via Pydantic models (e.g., `PolicyConfig`, `PiiConfig`).
- **Built-in Policies:** 
  - `banking_support_chatbot_v1.yaml`: Fast, low-risk setup focusing on PII anonymization and banning off-topics.
  - `wealth_mgmt_assistant_v1.yaml`: Heavy validation, strict compliance checks, enabling numerical hallucination checks.
  - `fraud_ops_agent_v1.yaml`: Strong PII focus for agentic setups.

## 4. Key Design Choices & Nuances
- **Parallel Scanners (Async Architecture):** Input and Output scanners are architected to run concurrently. Most local heuristic engines (regex/presidio) execute extremely fast (<20ms). 
- **Dynamic Routing:** `finguard/router.py` dynamically aggregates the necessary scanner instances depending on the loaded YAML configuration, ensuring minimal overhead. 
- **Graceful Failure:** Depending on the `on_fail` parameter in the policy, violations can either block the pipeline completely, pass with a warning, or (planned) attempt self-correction.

## 5. Locating Key Logic
- **Decorator Framework:** `finguard/core.py` (`FinGuard.wrap`)
- **Pipeline Orchestration:** `finguard/pipeline.py`
- **Policy Models & Parser:** `finguard/config.py`
- **Dynamic Scanners Instance Manager:** `finguard/router.py`
- **Custom Native Validators:** `finguard/validators/`
- **Event Audit Stream:** `finguard/audit.py`

This framework effectively separates policy management from business logic.
