loan-analyzer 0.1.1

A comprehensive loan data validation and metrics engine using DuckDB.

Loan Analyzer

A lightweight, SQL-powered engine for validating loan data and computing analytical metrics using DuckDB. It is designed to transform raw CSV loan data into auditable, time-series financial states.

Project Structure

The project follows the src layout for better packaging and isolation:

loan_analyzer/
├── src/
│   └── loan_analyzer/
│       ├── loan_system/       # Core Python logic
│       ├── sql/               # SQL transformations (CTEs, etc.)
│       └── tests/             # SQL-based validation tests
├── docs/                      # Documentation
├── pyproject.toml             # Build configuration
└── README.md

Installation

You can install the package directly from GitHub:

pip install git+https://github.com/zakiahmed1234/loan_analyzer.git

---

Core API Reference

The API is modularized into specialized classes within the loan_analyzer package.

1. DataLoader

Handles data ingestion from CSVs into an in-memory DuckDB instance.

__init__(directory_path, connection=None)

• directory_path: Directory containing the required CSV files.
• connection: (Optional) An existing DuckDB connection. If omitted, a new in-memory connection is created.
• Behavior: Automatically loads all .csv files in the directory as tables.

from loan_analyzer import DataLoader
loader = DataLoader("./data/my_loan_batch")

---

2. DataValidation

Runs a suite of SQL-based invariant tests to ensure data integrity.

__init__(loader: DataLoader)

Initializes with a populated DataLoader.

validate_all()

Runs all tests in src/loan_analyzer/tests/data_validation/.

• Returns: A pandas DataFrame containing the results (check name, pass/fail, details).

from loan_analyzer import DataValidation
validator = DataValidation(loader)
report = validator.validate_all()
print(report)

---

3. LoanCalculation

The execution engine for financial business logic.

__init__(validator: DataValidation)

Initializes the runner with a DataValidation instance. It ensures validation has been run before executing calculations.

run_loan_state()

Executes the Recursive Balance Engine. This calculates monthly snapshots for every loan, tracking interest accrual, payments, and principal amortization.

from loan_analyzer import LoanCalculation
calculator = LoanCalculation(validator)
calculator.run_loan_state()

run_delinquency()

Calculates the Delinquency Waterfall (DPD and status classification).

calculator.run_delinquency()

---

4. LoanAudit

The Forensic Audit Tool. Provides a line-item reconciliation of a loan's principal change.

audit_loan(loan_id, as_of_date)

Returns a detailed text report reconciling Opening - Closing == Amortization + Write-offs.

from loan_analyzer import LoanAudit
auditor = LoanAudit(calculator)
print(auditor.audit_loan("L-001", "2024-05-15"))

---

Advanced Usage Example

from loan_analyzer import DataLoader, DataValidation, LoanCalculation, LoanAudit

# 1. Setup Data Environment (Auto-loads CSVs)
loader = DataLoader("FakeData/1/")

# 2. Perform Health Check
validator = DataValidation(loader)
report = validator.validate_all()
if not report.passed.all():
    print("Data issues found!")
    print(report[report.passed == False])

# 3. Generate Financial Models
calculator = LoanCalculation(validator)
calculator.run_all() # Runs both state and delinquency

# 4. Forensic Investigation
auditor = LoanAudit(calculator)
print(auditor.audit_loan("3c60c443-a997-4a9c-8948-33fd5301208e", "2023-12-01"))

SQL Resources

The core logic is modularized in src/loan_analyzer/sql/. You can find the recursive CTEs for balance tracking and the cumulative window functions for delinquency there.

License

MIT