fincompl 🏦🛡️

Finance Compliance Guardrails for Production AI Systems

fincompl is the first open-source Python library specifically designed to protect production AI/LLM systems operating in financial services from compliance violations — inline, at generation time, before responses reach users.

---

Why fincompl?

The Gap in Existing Libraries

Capability	guardrails-ai	NeMo Guardrails	fincompl
Generic PII detection	✅	✅	✅
Finance-specific PII (IBAN, EIN, account #)	❌	❌	✅
Investor suitability (SEC Reg BI / FINRA 2111)	❌	❌	✅
AML / structuring red flags	❌	❌	✅
Insider trading / MNPI detection	❌	❌	✅
Market abuse (MAR / SEC 10b-5)	❌	❌	✅
Fair lending (ECOA / FHA)	❌	❌	✅
Hallucinated regulatory citations	❌	❌	✅
Conflict of interest detection	❌	❌	✅
Record-keeping violation detection	❌	❌	✅
Cryptographic audit chain (SEC 17a-4)	❌	❌	✅
LangChain / LangGraph native integration	✅	✅	✅
OpenTelemetry tracing	❌	❌	✅
MCP server	❌	❌	✅
MIT License	❌ Apache	❌ Apache	✅ MIT

---

Regulatory Coverage

Framework	Rules / Articles	Guardrails
SEC	Rule 10b-5, Reg BI (15l-1), Rule 17a-4	Insider trading, Suitability, Record-keeping
FINRA	2111, 2210, 2010, 3280, 4511	Suitability, Market abuse, Conflict of interest
MiFID II	Art. 23, 24, 25, Title IV (MAR)	Suitability, Disclosure, Market abuse
BSA/AML	31 CFR 1020, FinCEN guidance	AML structuring, Layering, Sanctions evasion
GDPR	Art. 4, 9	PII detection and redaction
CCPA	§1798	PII detection
GLBA	15 U.S.C. §6801	Financial PII (SSN, bank accounts)
PCI-DSS	Requirements 3, 4	Credit card, CVV redaction
ECOA / FHA	CFPB guidance	Fair lending language
Dodd-Frank	Title X	AML overlap, FinCEN

---

Installation

# Core (no ML dependencies)
pip install fincompl

# With LangChain integration
pip install "fincompl[langchain]"

# With LangGraph
pip install "fincompl[langgraph]"

# Everything
pip install "fincompl[all]"

---

Quick Start

Standalone

import asyncio
from fincompl import GuardrailPipeline, GuardrailConfig
from fincompl.guardrails import PIIGuardrail, SuitabilityGuardrail, AMLGuardrail
from fincompl.models import FinancialContext

pipeline = GuardrailPipeline(
    config=GuardrailConfig(regulations=["SEC", "FINRA", "BSA/AML"]),
    guardrails=[PIIGuardrail(), SuitabilityGuardrail(), AMLGuardrail()],
)

result = asyncio.run(pipeline.run(
    input_text=user_message,
    output_text=llm_response,
    context=FinancialContext(
        account_type="retail",
        risk_profile="conservative",
        jurisdiction="US",
    ),
))

print(result.summary())
# ⚠️  2 violation(s) — action: block
#   [CRITICAL] suitability_guardrail: Guaranteed return language detected...

LangChain — Callback (zero code change)

from fincompl.integrations.langchain import FinComplCallbackHandler

handler = FinComplCallbackHandler(pipeline=pipeline, raise_on_block=True)

# Attach to any LangChain LLM — no other changes needed
llm = ChatOpenAI(callbacks=[handler])

LangChain — LCEL chain composition

from fincompl.integrations.langchain import FinComplRunnable

chain = prompt | llm | FinComplRunnable(pipeline=pipeline) | output_parser
result = await chain.ainvoke({"question": "What should I invest in?"})

LangGraph — Compliance node

from fincompl.integrations.langchain import make_langgraph_guardrail_node

guardrail_node = make_langgraph_guardrail_node(pipeline=pipeline)

graph = StateGraph(AgentState)
graph.add_node("llm", llm_node)
graph.add_node("guardrails", guardrail_node)
graph.add_edge("llm", "guardrails")
graph.add_edge("guardrails", END)

---

Guardrails Reference

PIIGuardrail

Detects and redacts financial-grade PII: SSN, credit cards (Visa/MC/Amex/Discover), IBAN, EIN, bank account numbers, email, phone. Action: REDACT / BLOCK per sensitivity.

SuitabilityGuardrail

Enforces SEC Reg BI and FINRA 2111: blocks guaranteed-return language, checks product risk against investor profile, enforces accredited-investor gating, requires disclosures.

AMLGuardrail

Detects BSA/AML red flags: structuring, layering, money laundering, hawala, mixer/tumbler usage, sanctions evasion. Escalates on input, blocks on output guidance.

MarketAbuseGuardrail

Flags pump-and-dump, wash trading, spoofing, front-running, quote stuffing (MiFID II MAR / SEC 10b-5).

InsiderTradingGuardrail

Detects MNPI references, insider tips, quiet-period trading discussions (SEC Rule 10b-5 / FINRA 2010).

FairLendingGuardrail

Catches discriminatory lending language, redlining, steering by protected class (ECOA / Fair Housing Act).

HallucinationGuardrail

Detects hallucinated regulatory citations combined with uncertainty signals — unique to fincompl.

PromptInjectionGuardrail

Finance-specific injection patterns: attempts to bypass KYC/AML/compliance via instruction injection.

DisclosureGuardrail

Appends required legal disclosure text when investment content is detected (FINRA 2210 / SEC).

RecordKeepingGuardrail

Blocks instructions to delete, destroy, or conceal financial records (SEC 17a-4 / FINRA 4511).

ConflictOfInterestGuardrail

Detects undisclosed COI: kickbacks, referral fees, selling-away (SEC Reg BI / FINRA 3280).

---

OpenTelemetry

from fincompl.telemetry import configure_telemetry

# Console (development)
configure_telemetry(exporter="console")

# OTLP (production — Jaeger, Grafana Tempo, Datadog, etc.)
configure_telemetry(
    service_name="my-fintech-app",
    exporter="otlp",
    otlp_endpoint="http://jaeger:4317",
)

Every pipeline run and individual guardrail check creates a span with:

• fincompl.session_id
• fincompl.regulations
• fincompl.guardrail.name
• fincompl.violations
• fincompl.final_action
• fincompl.processing_time_ms

---

MCP Server

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "fincompl": {
      "command": "fincompl-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Available MCP Tools

Tool	Description
fincompl_check	Full pipeline on input+output pair
fincompl_pii_scan	PII scan with redaction
fincompl_suitability	Suitability check with investor context
fincompl_aml_scan	AML red-flag detection
fincompl_list_guardrails	List guardrails and their regulatory coverage
fincompl_audit_trail	Retrieve tamper-evident audit chain

---

Audit Trail

Every pipeline run produces an immutable AuditRecord with:

• SHA-256 hash of input and output text (text never stored)
• Previous record hash (chain-of-custody)
• Timestamp, session ID, pipeline version
• Full violation list with evidence

This satisfies SEC Rule 17a-4 and FINRA 4511 recordkeeping requirements.

---

Custom Guardrails

from fincompl.guardrails import BaseGuardrail
from fincompl.models import Action, Severity

class CryptoRestrictionGuardrail(BaseGuardrail):
    name = "crypto_restriction"

    async def check(self, *, input_text, output_text, context, config):
        if "bitcoin" in output_text.lower() and context and context.account_type == "retail":
            return [self._violation(
                rule_id="CRYPTO-001",
                regulation="SEC",
                severity=Severity.HIGH,
                action=Action.BLOCK,
                message="Crypto recommendations blocked for retail accounts.",
                evidence="bitcoin",
            )]
        return []

pipeline.add_guardrail(CryptoRestrictionGuardrail())

---

Stack

• Runtime: Python 3.10+, Pydantic v2, anyio
• Observability: OpenTelemetry SDK + OTLP exporter
• MCP: mcp (Model Context Protocol SDK)
• Security: cryptography (audit chain hashing)
• Logging: structlog
• LangChain: langchain-core >= 0.3
• LangGraph: langgraph >= 0.2
• Testing: pytest, pytest-asyncio
• Packaging: Hatchling, PEP 517

---

Contributing

PRs welcome. See CONTRIBUTING.md for guidelines. Areas needing work:

• ML-based hallucination detection (transformer models)
• Redis audit backend
• More jurisdiction-specific patterns (FCA, BaFin, ASIC)
• FINOS AI Governance Framework alignment

License

MIT — see LICENSE