Metadata-Version: 2.5
Name: australian-tax-calculators
Version: 0.1.8
Summary: Bounded Australian tax calculation worksheets with explicit scope and sources.
Project-URL: Repository, https://github.com/ryanduguid/australian-accounting/tree/main/packages/australian-tax-calculators
Author: Ryan Duguid
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build==1.6.1; extra == 'dev'
Requires-Dist: coverage==7.16.0; extra == 'dev'
Requires-Dist: hatchling==1.32.3; extra == 'dev'
Requires-Dist: mypy==2.3.1; extra == 'dev'
Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Requires-Dist: ruff==0.16.6; extra == 'dev'
Description-Content-Type: text/markdown

# Australian tax calculators

Ryan Duguid is not a registered tax agent or BAS agent. Project support is limited to software issues reproduced with fabricated data. Do not send taxpayer information or request advice, return preparation, tax-treatment confirmation, or lodgement.

[![tests](https://github.com/ryanduguid/australian-accounting/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanduguid/australian-accounting/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/australian-tax-calculators.svg?color=5C2D91&labelColor=04001F)](https://pypi.org/project/australian-tax-calculators/)
[![License: MIT](https://img.shields.io/badge/License-MIT-4F485E.svg?labelColor=04001F)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-5C2D91.svg?logo=python&logoColor=white&labelColor=04001F)](https://www.python.org/downloads/)

Distribution `australian-tax-calculators`, import package `austaxcalc`. Library
only: this component ships no command.

Ten calculation worksheets for established facts: ordinary GST, resident basic income
tax, CGT losses and discount, ordinary employer FBT, first-year depreciation,
quarterly super guarantee, Schedule 1 PAYG withholding, super contribution caps,
account-based pension minimums and study and training loan repayments. These are experimental
review aids, not advice or return preparation. Callers must establish every scope condition before calculating.

The Python functions in `austaxcalc.calculations` accept `Decimal` amounts and an
explicit period. Results include amounts, scope exclusions, official source URLs,
the source-check date and engine version. They perform no network calls or writes.
Amounts must be non-negative, finite, at most 2 decimal places and no more than
AUD 1 trillion. Rounding uses half-up to cents at output; individual worksheets
state additional conventions.

## Install

Python 3.10 or later. No runtime dependencies.

```bash
pip install australian-tax-calculators
```

## Use

Every worksheet takes `Decimal` amounts, an explicit period, and a
`scope_confirmed` flag the caller sets only once it has established the scope
conditions the worksheet states. Splitting $1,100.00 GST-inclusive into its
exclusive amount and its GST:

```python
from decimal import Decimal

from austaxcalc.calculations import gst

result = gst(Decimal("1100.00"), gst_inclusive=True, scope_confirmed=True, year="2025-26")
print(result["amounts"], result["source_checked"])
```

```
{'gst': '100.00', 'exclusive': '1000.00', 'inclusive': '1100.00'} 2026-09-10
```

Amounts come back as quoted decimal strings rather than numbers, so an amount
that leaves a worksheet cannot arrive at a JSON reader as a float.

The full result also carries `scope`, the official `sources` the figures came
from, the engine version and the warnings that travel with every worksheet:

```python
>>> result["scope"]
'One ordinary taxable supply at 10%, already classified by the operator. Excludes mixed supplies, exemptions, margin schemes, adjustments, tax invoice rounding across line items, input-credit entitlement and BAS preparation.'
>>> result["warnings"]
['Operator-confirmed facts and scope; eligibility is not independently verified.', 'Worksheet only, not advice, an assessment or a lodgment. Obtain human review.']
```

Full boundary statement: [DISCLAIMER.md](DISCLAIMER.md).

## Supported periods

| Worksheet | Period and boundary |
| --- | --- |
| GST | 2025-26, one ordinary taxable supply at 10%; no classification or BAS |
| Resident tax | 2024-25, 2025-26 and 2026-27; full-year resident ordinary income, before offsets and levies |
| CGT | 2025-26, resident individual's established gains and losses; losses before the 50% discount |
| FBT | Year ended 31 March 2026; established type 1 and type 2 taxable values, ordinary employer |
| Depreciation | 2025-26, first year of an ordinary tangible Division 40 asset; established life and use |
| SG | Complete quarters of 2025-26; established OTE, eligibility and qualifying contributions |
| Contribution caps | 2024-25 to 2026-27; one individual's classified contributions, no bring-forward period started in the 2 previous years |
| Pension minimum | 2024-25 to 2026-27; one account-based pension paying under SISR Schedule 7 |
| Study loan repayment | 2025-26 and 2026-27; one individual's established repayment income at the marginal rates; the formula amount before the loan-balance limit |

Unsupported periods fail. The SG worksheet does not implement post-June 2026
Payday entitlement rules. The separate Payday engine reviews timing on a supplied
liability. SMSF fund tax, Division 293 and 296 tax, the transfer balance cap, trusts, payroll
tax and Medicare calculations remain outside these worksheets.

## PAYG withholding

`payg_withholding` applies the Schedule 1 (NAT 1004) formulas to one regular
weekly, fortnightly or monthly pay made from 1 July 2026, on scale 1, 2, 3, 5
or 6 as the operator established from the payee's declarations. Earnings
include allowances subject to withholding. The result gives the weekly
earnings used, the weekly amount and the amount for the pay period, with the
coefficients applied. Scale 4, tax offsets, Medicare levy adjustments, study
and training support loans, extra amounts for 53 or 27 pays, quarterly pays
and the other schedules are outside it. The tests reproduce every amount in
the ATO's published sample data; see
[calculation evidence](docs/calculation-evidence.md#payg-withholding).
This worksheet is published in the 0.1.5 wheel.

## Super contribution caps and pension minimums

`contribution_caps` tests one year's classified contributions against the caps.
Unused concessional cap carries forward only when the total super balance at the
previous 30 June is below $500,000. The non-concessional cap is 4 times the
concessional cap, nil at or above the general transfer balance cap, and otherwise
1, 2 or 3 times the annual cap by the balance bands in ITAA 1997 s 292-85. Bring-forward
needs the person to be under 75 at any time in the year. The result gives room and
excess under each cap, the multiple of the annual cap available and the
bring-forward period the contributions started. A period started in an earlier
year is outside the worksheet.

`pension_minimum` applies SISR Schedule 7 to one account-based pension: the age
factor on the balance at 1 July, pro-rated by days in the first year, nil when the
pension starts on or after 1 June, and rounded to the nearest $10 with an exact $5
rounding up. The tests check every band boundary against the ATO's published
tables; see [calculation evidence](docs/calculation-evidence.md#contribution-caps).
These worksheets are published in the 0.1.6 wheel.

## Study and training loan repayment

`study_loan_repayment` applies the marginal repayment rates that apply from
2025-26 to one individual's established whole-dollar repayment income: nil at or
below the minimum repayment income, 15% of the excess up to the top of the first
band, then the 15% band in full plus 17% of the excess, and 10% of the whole
repayment income once that is the smaller amount. The result gives the marginal
amount, 10% of income, the compulsory repayment and the rate that applied, with
the thresholds. Repayment income (taxable income excluding assessable FHSS
released amounts, plus reportable fringe benefits, total net investment loss,
reportable super contributions and exempt foreign employment income) is the
operator's established fact. The formula amount is not limited to the loan
balance, and whether a debt exists, voluntary repayments, the overseas levy,
allocation between loan types, indexation and the Schedule 8 withholding
component are outside it. The tests hold the worksheet to the ATO's worked
examples, the Gazette that notified the 2026-27 thresholds and every band
boundary; see [calculation evidence](docs/calculation-evidence.md#study-loan-repayment).
This worksheet is on `main` and not yet in a published wheel.

## Worksheet discovery

`austaxcalc.calculations.worksheet_catalogue()`, published from the 0.1.4 wheel,
returns supported periods with inclusive dates, required inputs and units,
available methods, scope exclusions and a fabricated example for each worksheet.
Money in the catalogue uses decimal strings. Python callers convert these to
`Decimal`; MCP clients can send `example.facts` to `calculate_tax_worksheet`.

The engine owns the supported periods for both discovery and calculation.
Returned dictionaries can be edited without changing later calls or engine rules.

## Calculation evidence

[Calculation evidence](docs/calculation-evidence.md) records Library paragraphs,
document review dates, independent arithmetic and the limits of each example.
`example_evidence` in the catalogue points to these records. It requires no local
Library installation or network access at runtime.

Source URLs and exact exclusions remain in `austaxcalc/calculations.py` and every
result. The existing 10 September 2026 source-check baseline is now stored per
worksheet. A later check of one worksheet cannot refresh another's date. The
15 September Library example check does not extend that baseline to other periods
or establish a taxpayer's circumstances.
