Metadata-Version: 2.1
Name: sar-narrative-gen
Version: 0.1.0
Summary: AI-powered SAR narrative generator for AML compliance teams
Author: Bhavesh Awalkar
License: MIT
Project-URL: Homepage, https://github.com/Bhavesh0205/sar-narrative-gen
Project-URL: Repository, https://github.com/Bhavesh0205/sar-narrative-gen
Project-URL: Issues, https://github.com/Bhavesh0205/sar-narrative-gen/issues
Keywords: aml,anti-money-laundering,sar,suspicious-activity-report,compliance,bsa,fincen,fintech,financial-crime
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Financial and Insurance Industry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: notebook
Requires-Dist: jupyter; extra == "notebook"
Requires-Dist: pandas; extra == "notebook"
Requires-Dist: ipywidgets; extra == "notebook"

# sar-narrative-gen

[![Tests](https://github.com/Bhavesh0205/sar-narrative-gen/actions/workflows/ci.yml/badge.svg)](https://github.com/Bhavesh0205/sar-narrative-gen/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/sar-narrative-gen.svg)](https://pypi.org/project/sar-narrative-gen/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**AI-powered SAR narrative generator for AML compliance teams** — turns flagged transaction data into FinCEN-ready Suspicious Activity Report draft narratives using Claude.

---

## Why this exists

Writing SAR narratives is one of the most time-consuming tasks in a BSA/AML program. A compliance analyst reviewing 800+ alerts a week spends a significant portion of their time translating transaction data into structured prose — describing the who, what, when, where, and why of each suspicious pattern, in language that meets FinCEN guidance.

This toolkit automates the first draft. Feed it flagged transactions and subject information; get back a structured SAR narrative that follows FinCEN best practices. Analysts review and refine rather than write from scratch.

---

## How it works

The generator takes flagged transaction data, subject information, and a detected typology (structuring, layering, smurfing, rapid fund movement, dormant account) and constructs a structured prompt grounded in FinCEN SAR narrative guidance. It calls the Anthropic Claude API and returns a formatted narrative draft with metadata — transaction count, total flagged amount, date range, and generation timestamp.

The system prompt encodes FinCEN narrative requirements: objective language, no conclusory statements, specific transaction references, typology identification, and the standard who/what/when/where/why structure.

---

## Quick start

```bash
pip install sar-narrative-gen
```

Set your Anthropic API key:

```bash
export ANTHROPIC_API_KEY=your_key_here
```

Generate a SAR narrative:

```python
from sar import generate_sar_narrative

transactions = [
    {"date": "2024-03-01", "amount": 9400.00, "type": "cash_deposit",
     "from_account": "CASH", "to_account": "CHK-004821"},
    {"date": "2024-03-04", "amount": 9200.00, "type": "cash_deposit",
     "from_account": "CASH", "to_account": "CHK-004821"},
    {"date": "2024-03-07", "amount": 8900.00, "type": "cash_deposit",
     "from_account": "CASH", "to_account": "CHK-004821"},
]

subject = {
    "name": "Meridian Auto Parts LLC",
    "account_number": "CHK-004821",
    "customer_since": "2021-06-15",
    "business_type": "Auto parts retailer",
}

result = generate_sar_narrative(
    transactions=transactions,
    subject_info=subject,
    typology="structuring",
    filing_institution="First National Community Bank",
    additional_context="Subject's reported annual revenue is $180,000.",
)

print(result["narrative"])
print(f"Total flagged: ${result['total_amount']:,.2f}")
print(f"Transactions: {result['transaction_count']}")
```

---

## Supported typologies

| Typology | Description | Reference |
|---|---|---|
| `structuring` | Breaking up transactions below CTR threshold | 31 U.S.C. 5324 |
| `layering` | Moving funds through multiple accounts to obscure origin | FATF Typologies 2006 |
| `smurfing` | Multiple individuals conducting sub-threshold transactions | FinCEN FIN-2014-A005 |
| `rapid_movement` | Funds moving through accounts within 24–48 hours | FATF Guidance 2012 |
| `dormant_account` | Sudden high-volume activity in previously inactive account | FinCEN FIN-2022-A001 |

---

## Batch processing

Generate narratives for multiple cases at once:

```python
from sar import batch_generate, get_all_demo_cases

cases = get_all_demo_cases()  # includes structuring, layering, dormant account
results = batch_generate(cases)

for r in results:
    print(f"\n--- {r['case_id']} ---")
    print(r["narrative"])
```

---

## Demo cases

The package ships with three synthetic SAR cases for testing and demos:

```python
from sar.synthetic import (
    generate_structuring_case,
    generate_layering_case,
    generate_dormant_account_case,
)

case = generate_structuring_case()
print(case["transactions"])
```

All synthetic data — no real individuals, accounts, or institutions.

---

## Works great with aml-analytics

`sar-narrative-gen` is designed to work alongside [aml-analytics](https://github.com/Bhavesh0205/aml-analytics). Detect suspicious patterns with aml-analytics, then feed the flagged output directly into this generator:

```python
from aml.graph import build_network, detect_structuring
from aml.synthetic import generate_transactions
from sar import generate_sar_narrative

# Detect with aml-analytics
txns = generate_transactions(n=1000)
G = build_network(txns)
flagged = detect_structuring(G, threshold=9000)

# Draft the SAR
result = generate_sar_narrative(
    transactions=flagged,
    subject_info={"name": "Subject LLC", "account_number": "CHK-001"},
    typology="structuring",
)
print(result["narrative"])
```

---

## Disclaimer

This toolkit is for educational and research purposes only. Generated narratives are AI-drafted first drafts and must be reviewed, verified, and approved by a qualified BSA/AML compliance officer before filing. It does not constitute legal or compliance advice. All demo data is entirely synthetic.

---

## Citation

```bibtex
@software{sar_narrative_gen,
  author  = {Bhavesh Awalkar},
  title   = {sar-narrative-gen: AI-powered SAR narrative generator for AML compliance},
  year    = {2024},
  url     = {https://github.com/Bhavesh0205/sar-narrative-gen},
  license = {MIT}
}
```

---

## License

MIT — see [LICENSE](LICENSE) for details.
