Metadata-Version: 2.4
Name: ifrs16kit
Version: 1.0.0
Summary: Interactive IFRS 16 auditor re-performance tool producing liquid Excel workbooks
Author: Ayce Makbule (Lena) Acar
License-Expression: MIT
Keywords: IFRS 16,lease accounting,audit,re-performance,ISA 540,excel,openpyxl,right-of-use asset,lease liability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Programming Language :: Python :: 3
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: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl>=3.1
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Dynamic: license-file

# LeaseAuditKit — Interactive IFRS 16 Re-performance Tool (LIQUID edition)

A standalone Python tool that re-performs a lessee's IFRS 16 lease accounting from first principles, independently of the client's own calculation, and delivers the result as a fully formula-driven ("liquid") Excel audit workbook. It is designed for the substantive re-performance of management's lease estimates under ISA 540 (accounting estimates), ISA 500 (audit evidence, including para A21 on re-performance), and ISA 230 (documentation).

Author: Ayce Makbule (Lena) Acar — MSc Business Analytics, Trinity College Dublin.

## Why "liquid"?

Every derived figure in the generated workbook is a live Excel formula, not a hard-coded value. Change any dark-red input cell — lease term, IBR, payment frequency, country, depreciation method — and the entire model (liability, ROU asset, 120-period schedule, annual summary, journals, deferred tax) recalculates instantly inside Excel. The Python script never bakes numbers into the calculation sheets; it only writes the inputs and the formula fabric around them. A separate, independent Python engine re-computes the same figures so the auditor can verify the Excel model against a second implementation (a "two-engine" control).

## Requirements

- Python 3.9+
- openpyxl (installed automatically as a dependency)
- Microsoft Excel (or LibreOffice) to fill the template and recalculate the output

Works from any environment: terminal, VS Code, Spyder, PyCharm.

## Installation

From the package root (the folder containing `pyproject.toml`):

```bash
pip install -e .
```

The editable (`-e`) install means edits to `src/ifrs16kit/core.py` take
effect immediately without reinstalling. Installation registers both the
importable package (`import ifrs16kit`) and a terminal command
(`ifrs16kit`), usable from any directory.

## Quick start

**Command line** (interactive flow):

```bash
# Guided flow — 3 questions, then a fillable template
ifrs16kit

# Instant demo — runs the CALISMA golden benchmark end-to-end
ifrs16kit --demo
```

**Spyder / notebook — interactive flow** (asks the questions, waits while you fill the template):

```python
import ifrs16kit as lease
lease.run()
# 1. answers 3 questions in the console
# 2. writes IFRS16_Input.xlsx and PAUSES — open it in Excel, fill the
#    dark-red cells, save, return to the console and press Enter
# 3. validates the template and writes IFRS16_Calculation.xlsx
```

**Spyder / notebook — non-interactive two-step** (no questions; you control each step):

```python
import ifrs16kit as lease

lease.demo()                       # instantly writes BOTH Excel files (golden case)

lease.create_input()               # step 1: writes IFRS16_Input.xlsx → fill in Excel
lease.create_calculation()         # step 2: reads it back → writes IFRS16_Calculation.xlsx
```

`create_input()` accepts `country=`, `advance=`, `freq=` and a custom path;
`create_calculation()` accepts custom template/output paths.

**Python API** (programmatic — no interview, no template round-trip):

```python
import ifrs16kit as lease

inp = lease.LeaseInputs(
    entity="Example Co. Limited", country="Ireland",
    commencement=__import__("datetime").date(2025, 1, 1),
    term_years=2, freq=12, payment=650.0,
    is_advance=True, ibr_annual=0.06, idc=600.0,
)

lease.cross_check(inp)                                     # dict of key figures
lease.build_calculation_workbook(inp, "IFRS16_Calc.xlsx")  # 10-sheet liquid workbook
lease.build_template({"country": "Ireland", "is_advance": True, "freq": 12},
                   "IFRS16_Input.xlsx")                  # blank input template
inp2 = lease.read_template("IFRS16_Input.xlsx")            # validated read-back
```

Public API: `LeaseInputs`, `cross_check`, `build_template`, `read_template`,
`build_calculation_workbook`, `print_summary`, plus the `COUNTRIES`,
`FREQUENCIES`, and `MAX_PERIODS` constants.

## Workflow

1. **Interview.** The script asks three questions: country/jurisdiction (Türkiye, Ireland, United Kingdom, UAE, Australia), payment timing (advance/arrears), and payment frequency (monthly, quarterly, semi-annual, annual).
2. **Template.** It generates `IFRS16_Input.xlsx` — a single-sheet LIQUID input template. Only the dark-red, thick-bordered cells are editable inputs; everything else (total term, N, periodic rate, capacity checks) auto-calculates with live formulas. Dropdowns constrain frequency, timing, depreciation method, and country.
3. **Fill and save.** Open the template in Excel, fill every dark-red cell, confirm the two green validation cells both say "OK", save, and return to the running script.
4. **Validation.** The script reads the template back and validates it: non-empty entity, valid date, positive term/payment/useful life, IBR entered as a decimal or percentage below 100%, a whole number of payment periods, and N ≤ 120 (template capacity). Errors are listed cell-by-cell so they can be fixed and re-read without restarting.
5. **Output.** It generates `IFRS16_Calculation.xlsx` — the full 10-sheet liquid workbook — and prints an independent Python cross-check of the key figures.

## The generated workbook (10 sheets)

| Sheet | Contents |
|---|---|
| **Inputs** | All lease inputs plus live-linked key outputs (liability, ROU, totals) and country-driven framework/audit-standard lookups from Setup. |
| **Initial Measurement** | PV of lease payments period-by-period (IFRS 16 ¶26) and the ROU asset build-up (¶24: liability + IDC + prepayments − incentives + restoration). |
| **Lease Schedule** | 120-period-capacity amortisation and depreciation schedule (¶36 effective interest; ¶31 depreciation), with year tags and a Final Payment status flag. Rows self-hide beyond N. |
| **Annual Summary** | P&L impact and year-end balances by reporting year, a front-loading memo vs a straight-line charge, and five automated reconciliation checks (closing liability = 0, closing ROU = 0, principal = initial liability, expense = payments + IDC, front-loading sums to nil). |
| **Journals** | Initial-recognition entry with debit/credit balance check, plus representative Period 1 entries (payment, interest unwind, depreciation). |
| **Tax_Reconciliation** | Illustrative year-1 accounting-vs-cash-rental P&L difference and deferred-tax computation at the jurisdiction's rate. |
| **Findings** | Findings-and-recommendations register wired to the reconciliation checks — flags "Y" and a recommendation automatically when a check fails. |
| **Audit_Procedures** | 20 substantive procedures (P-1 to P-20) mapped to assertions (existence, completeness, accuracy, cut-off, classification, presentation). |
| **PBC_List** | 18-item prepared-by-client request list with purpose, format, and due dates. |
| **Setup** | Country lookup table driving currency, reporting framework, lease standard (IFRS 16 / TFRS 16 / AASB 16), audit standards (ISA / ISA (Ireland) / ISA (UK) / BDS / ASA 540-500-230), and illustrative tax rate. |

## Colour and formatting conventions

- **Dark red fill, thick border, bold** — your input (client data / auditor assumptions)
- **Black** — formula / computed
- **Green font on light-green fill** — link to another sheet, or an automated check
- **Navy headers, Times New Roman throughout**

## Calculation conventions

- Periodic discount rate uses the effective (compound) conversion: `(1 + IBR)^(1/frequency) − 1`, not simple pro-rata.
- Advance payments: the first payment is undiscounted (discount exponent `p − 1`); interest accrues on the opening liability net of the period's payment. Arrears: exponent `p`; interest on the full opening liability.
- Depreciation: straight-line over the shorter of the lease term and useful life (no ownership transfer assumed), or reducing balance at `1 − (1 − annual rate)^(1/frequency)` per period with a final-period write-off of the remaining carrying amount.

## Verification

The tool ships with a golden benchmark (the CALISMA case: monthly advance, 24 periods, 6% IBR, 650/month, 600 IDC):

| Figure | Expected |
|---|---|
| Lease liability at commencement | 14,761.09 |
| ROU asset at commencement | 15,361.09 |
| Total interest over term | 838.91 |
| Total P&L charge | 16,200.00 |

Run `ifrs16kit --demo` and compare the console cross-check and `Inputs!B36:B42` of the generated workbook against these values. The five reconciliation checks on the Annual Summary sheet must all read "OK".

## Files

| File | Role |
|---|---|
| `pyproject.toml` | Package metadata, dependency, and the `ifrs16kit` CLI entry point |
| `src/ifrs16kit/core.py` | The engine, template builder, validator, and workbook builder |
| `src/ifrs16kit/__init__.py` | Public API exports |
| `IFRS16_Input.xlsx` | Generated input template (step 2) |
| `IFRS16_Calculation.xlsx` | Generated liquid calculation workbook (step 5) |
| `VIGNETTE.md` | Worked example mapped to IFRS 16 paragraphs and ISA requirements |

The tool also runs without installation: `python src/ifrs16kit/core.py --demo`.

## Limitations

Single lease, fixed payments, no mid-term modifications or remeasurements, no CPI-linked variable payments, template capacity of 120 payment periods. These are audit re-performance scoping choices, not engine defects: modifications and variable payments are covered qualitatively as procedures P-12 and P-13 on the Audit_Procedures sheet.
