Metadata-Version: 2.4
Name: xfingine
Version: 0.1.1
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Office/Business :: Financial
License-File: LICENSE
Summary: Pure computation engines for personal finance planning - inflation-adjusted EMI schedules and more
Home-Page: https://github.com/xfina-dev/xfingine
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/xfina-dev/xfingine
Project-URL: Repository, https://github.com/xfina-dev/xfingine

# xfingine

Python bindings for [**Xfingine**](https://github.com/xfina-dev/xfingine) —
pure computation engines for personal finance planning.

Data in, arithmetic, data out. No UI, no network, no clock — the same input
always produces the same output.

```bash
pip install xfingine
```

## Usage

```python
import xfingine

result = xfingine.compute_emi({
    "mode": "emi",            # "emi" | "tenure" | "loanAmount"
    "loanAmount": 5_000_000,
    "months": 240,
    "interestRate": 9,        # percent per year
    "inflationRate": 6,       # percent per year
    "start": "2026-01",       # optional, enables dates + per-year breakdown
})

result["emi"]                    # 44986    — the monthly payment
result["totals"]["nominalPaid"]  # 10796818 — rupees actually debited
result["totals"]["realPaid"]     # 6391327  — the same, in 2026 rupees
len(result["schedule"])          # 240 rows, month by month
len(result["years"])             # 20 rows, one per calendar year
```

Straight into a DataFrame:

```python
import pandas as pd

df = pd.DataFrame(result["schedule"])
df[["year", "month", "emi", "principal", "interest", "realEmi"]].head()
```

There is a `_json` twin of every function for string in / string out:

```python
xfingine.compute_emi_json('{"mode":"emi","loanAmount":5000000,"months":240,"interestRate":9}')
```

Invalid input raises `ValueError` with a readable message:

```python
xfingine.compute_emi({"mode": "tenure", "loanAmount": 5_000_000,
                      "emi": 1000, "interestRate": 12})
# ValueError: monthly payment of 1000.00 does not cover the first month's
#             interest of 50000.00; the loan would never be repaid
```

## Conventions

- Money comes back as whole rupees (`int`).
- Rates are percentages, not fractions: `9` means 9%.
- All keys are `camelCase`.
- Omit `start` and the engine reads no calendar — schedule rows carry no dates
  and `years` is empty.

Full documentation: [github.com/xfina-dev/xfingine](https://github.com/xfina-dev/xfingine)

## License

Apache-2.0

