Metadata-Version: 2.5
Name: australian-tax-calculators
Version: 0.2.0
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: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.14
Provides-Extra: dev
Requires-Dist: build==1.6.1; extra == 'dev'
Requires-Dist: coverage==7.16.2; extra == 'dev'
Requires-Dist: hatchling==1.32.4; extra == 'dev'
Requires-Dist: hypothesis==6.169.0; extra == 'dev'
Requires-Dist: mypy==2.4.0; extra == 'dev'
Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Requires-Dist: ruff==0.17.0; extra == 'dev'
Description-Content-Type: text/markdown

# Australian tax calculators

Release `australian-tax-calculators==0.2.0` contains fourteen worksheets,
including Schedule 8 withholding, annual Medicare levy, LITO and Division 293.
Earlier releases through 0.1.9 contain ten. The
[release handoff](../../apps/aus-accounting-mcp/docs/worksheet-release.md)
keeps the engine release and MCP integration separate.

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://img.shields.io/github/actions/workflow/status/ryanduguid/australian-accounting/ci.yml?branch=main&label=tests&labelColor=000000&style=flat-square)](https://github.com/ryanduguid/australian-accounting/actions/workflows/ci.yml)<br>
[![PyPI](https://img.shields.io/pypi/v/australian-tax-calculators.svg?color=66023C&labelColor=000000&style=flat-square)](https://pypi.org/project/australian-tax-calculators/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-66023C?labelColor=000000&style=flat-square)](https://www.apache.org/licenses/LICENSE-2.0)
[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-66023C?logo=python&logoColor=white&labelColor=000000&style=flat-square)](https://www.python.org/downloads/)

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

Fourteen 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, study and training loan repayments, Schedule 8 study
loan withholding, a single person's Medicare levy, the low income tax offset and
Division 293 tax. 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.14 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 |
| Study loan withholding | Regular weekly, fortnightly or monthly pays from 1 July 2026 on scale 1, 2, 3, 5 or 6; the Schedule 1 amount plus the Schedule 8 component |
| Medicare levy | 2024-25 and 2025-26; full-year resident single without SAPTO, spouse, dependants or exemption; the 2% rate and the low-income reduction |
| Low income tax offset | 2024-25, 2025-26 and 2026-27; resident individual's established taxable income; the offset amount, not applied against tax |
| Division 293 | 2024-25, 2025-26 and 2026-27; established Division 293 income and low tax contributions; no defined benefit interests |

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 296 tax, the transfer balance cap, trusts, payroll
tax, the Medicare levy surcharge and Medicare levy reductions other than the single
low-income reduction 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).

## Study loan withholding

`study_loan_withholding` adds the Schedule 8 (NAT 3539) study and training
support loan component to the Schedule 1 amount for one regular weekly,
fortnightly or monthly pay made from 1 July 2026 to a payee who declared a
study and training support loan debt. Scale 1 takes the component for a payee
who did not claim the tax-free threshold; scales 2, 3, 5 and 6 take the one for
a payee who claimed it or is a foreign resident. The result gives the Schedule
1 amount, the component and their total. The ATO also publishes combined
coefficients and accepts either method; the tests hold the worksheet within $1
of them for scales 1 and 2, and to the schedule's three worked examples. See
[calculation evidence](docs/calculation-evidence.md#study-loan-withholding).

## Medicare levy and low income tax offset

`medicare_levy` applies the 2% rate and the low-income reduction in s 7 of the
Medicare Levy Act 1986 to a full-year resident single who is not entitled to
the seniors and pensioners tax offset and has no exemption: nil at or below the
threshold amount, and no more than 10% of the excess up to the phase-in limit.
The caller states whether s 9A (lump sum payments in arrears) applies, and the
worksheet refuses when it does. It covers 2024-25 and 2025-26; 2026-27 is refused until its thresholds are
published. `low_income_tax_offset` gives the ITAA 1997 s 61-115 offset from
established taxable income for 2024-25 to 2026-27. Neither applies the result
against tax payable. See
[calculation evidence](docs/calculation-evidence.md#medicare-levy).

## Division 293

`division_293` applies ITAA 1997 s 293-20 to one individual's established
Division 293 income and low tax contributions: when their sum exceeds $250,000,
taxable contributions are the lesser of the contributions and the excess, taxed
at 15%. It covers 2024-25 to 2026-27 and holds the ATO's worked example. Working
out either input, defined benefit interests and deferred debt accounts are
outside it. See [calculation evidence](docs/calculation-evidence.md#division-293).

These four worksheets are included from release 0.2.0.

## 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.
