Python >=3.9 · PyPI Package v0.1.0 · CFSBR Computational Research

Deterministic Financial Math, Credit Risk Modeling & Quantitative Primitives for Python

FinEngine-Py brings audited actuarial math, integer-scaled sub-unit arithmetic (Poisha / Cents), strict type hints, and native Pandas DataFrame integration to Python quants, data scientists, and fintech developers. Maintained under the Centre for Fintech & Strategic Business Research (CFSBR).

            $
            pip install finengine

View on PyPI (v0.1.0) ↗ Run in Google Colab ↗ Full API Docs ↗ GitHub ↗

Project Status: Developer Preview & Research Prototype (v0.1.0 on PyPI)

finengine.math and finengine.core provide mathematically verified deterministic primitives (integer sub-unit arithmetic, reducing-balance amortization, international day-count conventions, and hybrid robust XIRR solvers). Higher-level machine learning and thin-file scoring modules (finengine.ai) represent baseline heuristic scaffolds under CFSBR research and are not an empirical substitute for regulated core banking or rating agency models.

Installation Options & Extras

FinEngine-Py is designed with a lightweight core and optional modular extras:

1. Pure Math Core (Zero-Dependency)

pip install finengine

100% pure Python with zero third-party dependencies. Ideal for lightweight microservices, AWS Lambda, and embedded runtimes.

2. With Pandas & NumPy Support

pip install "finengine[analysis]"

Adds structured to_dataframe() and batch portfolio amortization schedule support for data science workflows.

3. Full Suite with AI & Risk Engine

pip install "finengine[all]"

Includes Scikit-Learn based pre-calibrated credit risk scoring models for MFS (bKash/Nagad) and nano-loans.

Instant Cloud Tryout

Run Python SDK in Google Colab

Explore Pandas DataFrame schedules and credit risk models in 1-click on Google Colab.

Code Recipes

Executable Python Examples

Tested for Python 3.9+ with strict type hints, dataclasses, and Pandas compatibility.

1. Deterministic Loan Amortization (36-Month EMI)

example_amortize.py

Computes true reducing-balance installments with integer-rounded Poisha reconciliation.

from finengine import amortize, format_money

# Compute a 36-month loan amortization for BDT 5,00,000 at 13.5% p.a.
plan = amortize(principal=500000, annual_rate=13.5, months=36)

print(f"Monthly Payment: {format_money(plan.monthly_payment, 'BDT')}")
# → Monthly Payment: BDT 16,967.64

print(f"Total Interest:  {format_money(plan.total_interest, 'BDT')}")
# → Total Interest:  BDT 1,10,835.20

print(f"Final Balance:   {plan.schedule[-1].remaining_balance}")
# → Final Balance:   0.0 (Guaranteed Terminal Zero Closure)

2. Banking Day-Count & Moratorium (Grace Period) Schedule

example_daycount_moratorium.py

Supports international day-count conventions (Actual/365, Actual/360, 30/360), business day rolling rules, and interest-only grace periods.

from finengine import amortize, days_between, year_fraction

# Compute day-count fractions under banking conventions
days = days_between("2026-01-01", "2026-07-01", convention="Actual/365")  # → 181
fraction = year_fraction("2026-01-01", "2026-07-01", convention="30/360")   # → 0.50

# 36-month loan with 6 months grace period (interest-only moratorium)
plan = amortize(
    principal=500000,
    annual_rate=12.0,
    months=36,
    grace_period_months=6,
    grace_period_type="interest-only",
    day_count_convention="Actual/365"
)

print(f"Grace Month 1 Payment (Interest Only): {plan.schedule[0].payment}")
# → Grace Month 1 Payment: BDT 5,000.00
print(f"Active Month 7 Payment (Amortizing):    {plan.schedule[6].payment}")
# → Active Month 7 Payment: BDT 19,371.45

2. Tabular Pandas DataFrame Schedule Analysis

example_pandas.py

Direct conversion into a structured Pandas DataFrame for plotting, risk analysis, and Excel exports.

import pandas as pd
from finengine import amortize, to_dataframe

plan = amortize(principal=500000, annual_rate=13.5, months=36)

# Direct conversion into structured Pandas DataFrame
df = to_dataframe(plan)

print(df.head())
#    month   payment  principal_paid  interest  remaining_balance
# 0      1  16967.64        11342.64   5625.00          488657.36
# 1      2  16967.64        11470.25   5497.39          477187.11
# 2      3  16967.64        11599.29   5368.35          465587.82

# Export to spreadsheet format
df.to_csv("sme_amortization_schedule.csv", index=False)

3. Non-Periodic Cash Flow XIRR Solver

example_xirr.py

Constrained Newton-Raphson solver with bisection fallbacks for irregular cashflow internal rate of return.

from datetime import date
from finengine import xirr, CashFlow

cashflows = [
    CashFlow(amount=-100000, date=date(2026, 1, 1)),   # Initial investment
    CashFlow(amount=25000,  date=date(2026, 4, 1)),   # Q1 Dividend
    CashFlow(amount=30000,  date=date(2026, 8, 15)),  # Q2 Distribution
    CashFlow(amount=65000,  date=date(2026, 12, 31)), # Year-end liquidation
]

rate = xirr(cashflows)
print(f"Annualized Internal Rate of Return (XIRR): {rate * 100:.2f}%")
# → Annualized Internal Rate of Return (XIRR): 24.83%

4. Alternative Credit Risk & MFS Nano-Loan Scoring

example_credit_risk.py

Pre-calibrated risk models for informal, thin-file, and MFS (bKash/Nagad) wallet transactions.

from finengine.ai import MFSProfile, assess_credit_risk

profile = MFSProfile(
    monthly_inflows=75000.0,
    monthly_outflows=35000.0,
    avg_balance=18000.0,
    transaction_frequency=40,
    utility_bill_consistency=1.0,
    account_age_months=24,
    past_defaults=0,
)

assessment = assess_credit_risk(profile=profile, requested_amount=50000)

print(f"Credit Score:      {assessment.score} / 850")
print(f"Default Risk (PD): {assessment.default_probability * 100:.2f}%")
print(f"Risk Tier:         {assessment.risk_tier}")
print(f"Recommended Limit: BDT {assessment.recommended_credit_limit:,.2f}")

Research Note: finengine.ai provides a baseline heuristic feature-engineering interface under the CFSBR Lab computational research roadmap. Teams deploying in production should train and calibrate models on empirical institution-specific portfolio default datasets.

Full Python API Reference Specification

Function / Class	Signature	Return Type	Description
amortize()	(principal, annual_rate, months, round_to_integer=False)	AmortizationPlan	Computes full reducing-balance EMI schedule with Terminal Zero guarantee.
monthly_payment()	(principal, annual_rate, months, round_to_integer=False)	float	Returns exact monthly installment amount in standard currency units.
xirr()	(cashflows, guess=0.1, max_iter=100)	float	Solves annualized internal rate of return for irregular non-periodic cashflows.
create_money()	(amount, currency='BDT')	Money	Creates monetary instance with integer sub-unit scaling (Poisha).
format_money()	(amount, currency='BDT', locale='en-BD')	str	Formats currency strings with South Asian (Lakh/Crore) or Western notation.
to_dataframe()	(schedule_or_plan)	pandas.DataFrame	Converts plan or schedule rows into a structured Pandas DataFrame.
batch_amortize()	(portfolio)	pandas.DataFrame	Computes aggregated multi-loan portfolio amortization schedules.
simulate_loan()	(principal, annual_rate, months, prepayments=None, default_month=None)	dict	Simulates prepayment acceleration or borrower default stress scenarios.
assess_credit_risk()	(inflows=None, profile=None, requested_amount=0.0)	CreditAssessment	Evaluates borrower credit risk, score, and safe exposure limit.

Development & Testing Guide

Contribute to FinEngine-Py or run the test suite locally:

# 1. Clone repository
git clone https://github.com/gmrafi/FinEngine-Py.git
cd FinEngine-Py

# 2. Install in editable mode with development dependencies
pip install -e ".[dev,all]"

# 3. Run automated pytest test suite
pytest -v tests/

# 4. Strict type verification with mypy
mypy src/

# 5. Fast linting with ruff
ruff check src/ tests/