pacioliscube 0.1.2__tar.gz

pacioliscube-0.1.2/.gitignore

@@ -0,0 +1,58 @@
+# Client and taxpayer data never belongs in this repository.
+# These patterns block the file names real ledgers and payroll exports arrive under.
+# Character classes are used on extensions because git only folds extension case
+# when core.ignorecase is set, which is not the case on every contributor's box.
+[pP][nN][lL]*.[cC][sS][vV]
+[tT][rR][iI][aA][lL]-[bB][aA][lL][aA][nN][cC][eE]*.[cC][sS][vV]
+[pP][aA][yY][rR][oO][lL][lL]*.[cC][sS][vV]
+client-data/
+clients/
+ledgers/
+exports/
+*.aba
+*.qbo
+*.ofx
+*.qif
+*.[xX][lL][sS]
+*.[xX][lL][sS][xX]
+*.[xX][lL][sS][mM]
+*.[pP][dD][fF]
+
+# The repository's own synthetic data is deliberately exempt.
+!examples/**
+!tests/fixtures/**
+
+# Credentials
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+token.json
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Agent scratch
+.superpowers/
+.claude/settings.local.json
+
+# Agent planning documents stay local: they carry paths from the box
+# they were written on and are of no use to a reader.
+docs/superpowers/

pacioliscube-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Issues and pull requests are welcome. A person reads every change before it
+lands, and a change that alters a calculated number needs to show its working.
+
+## Data boundary
+
+This repository must never carry real data. No client, taxpayer, employee or
+payroll records, no credentials, no tokens, no organisation names from a live
+engagement. Business data under `examples/` is invented. Statutory rates and
+thresholds use the dated primary sources in `docs/model-assumptions.md`.
+
+The `.gitignore` blocks the file names real ledgers and payroll exports arrive
+under. It is a safety net, not permission to try. If you need a new fixture,
+write one by hand.
+
+## Rates, thresholds and deadlines
+
+Every statutory figure lives in `examples/drivers.csv` as data. None of them is
+written into rule text, so changing a rate never means editing a rule.
+
+If you change a rate, a threshold or an effective date, cite the primary source
+in the pull request: the Australian Taxation Office page, the Revenue NSW page,
+or the legislation itself. Update the table in `docs/model-assumptions.md` in
+the same change, including the date you retrieved it. A secondary source, a blog
+or an accounting firm summary is not enough on its own.
+
+## Tests
+
+The suite asserts calculated numbers, not just that the model loads. A test that
+pins a figure must compute the expected value from first principles in the test
+body, so a reviewer can follow the arithmetic without trusting the engine.
+
+Run that test against the old code first. If it passes there too, it is not
+testing your change.
+
+```bash
+uv run --locked --extra dev ruff check pacioliscube tests
+uv run --locked --extra dev mypy pacioliscube
+uv run --locked --extra dev pytest -q
+```
+
+The same commands CI runs: ruff and mypy in the `lint` job, then the tests on
+Python 3.10, 3.12 and 3.13 (and 3.12 on Windows). Install the git hooks once
+with `uv tool install pre-commit && pre-commit install`; they run the pinned
+ruff check on staged files. The packaging job additionally builds the wheel,
+installs it into a clean environment and runs the real command line against the
+real model tree, because a wheel that cannot find its own model is a broken
+build artefact.
+
+The bounded mutmut pilot over `pacioliscube/evaluate.py`, with its survivor
+ledger and the decision to keep the pin, is recorded in
+[docs/mutation-baseline.md](docs/mutation-baseline.md). It is a test-design
+aid, not a CI gate.
+
+## Model changes
+
+The model source under `model/` follows the layout IBM's own Git integration
+writes: a `tm1project.json` manifest, `dimensions/`, `cubes/` with plain text
+`.rules` beside the JSON, and `processes/` with plain text `.ti` beside the JSON.
+
+Two rules hold for any change there:
+
+1. Every file in the tree must appear in the manifest, directly or through a
+   link from an object the manifest lists. The validator reports anything else,
+   because a deployment would leave it behind.
+2. Any cube with `SKIPCHECK` and rules needs a feeder pointing into it, from
+   that cube or from another. Unfed calculated cells are invisible in a real
+   database even though the rule is correct.
+
+Run `pacioliscube validate` before you open the pull request.
+
+## Pull requests
+
+Keep a pull request to one change. Describe what it does and, where it touches a
+number, show the command output rather than saying the tests pass.
+
+Prose in this repository is Australian English and carries no em dashes.
+
+## Security
+
+Report a vulnerability privately through the process in
+[SECURITY.md](SECURITY.md), not in a public issue.

pacioliscube-0.1.2/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ryan Duguid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

pacioliscube-0.1.2/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: pacioliscube
+Version: 0.1.2
+Summary: An open IBM Planning Analytics budgeting model with an offline engine that computes and tests it.
+Project-URL: Homepage, https://github.com/ryanduguid/planning-analytics-model
+Project-URL: Issues, https://github.com/ryanduguid/planning-analytics-model/issues
+Author: Ryan Duguid
+License-Expression: MIT
+License-File: LICENSE
+Keywords: australia,budgeting,fpa,planning-analytics,tm1
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+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: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.6.0; extra == 'dev'
+Requires-Dist: coverage==7.16.0; extra == 'dev'
+Requires-Dist: diff-cover==10.5.1; extra == 'dev'
+Requires-Dist: hypothesis==6.167.1; extra == 'dev'
+Requires-Dist: mutmut==3.7.0; extra == 'dev'
+Requires-Dist: mypy==2.3.1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.16.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# IBM Planning Analytics budget model with an offline rule evaluator
+
+```
++----------------------------------------------------------------------+
+|                       planning-analytics-model                       |
++----------------------------------------------------------------------+
+|            IBM Planning Analytics budget model as source             |
++----------------------------------+-----------------------------------+
+| DR  what it gives you            | CR  what it needs                 |
++----------------------------------+-----------------------------------+
+| runs TM1 rules with no server    | PA model files in Git format      |
+| validates model structure        | CSV data for cube loading         |
+| prints a P and L report          | -                                 |
++----------------------------------+-----------------------------------+
+```
+
+The PaciolisCube budget model. This repository was named PaciolisCube until September 2026; the old URL redirects.
+
+[![tests](https://github.com/ryanduguid/planning-analytics-model/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanduguid/planning-analytics-model/actions/workflows/ci.yml)
+[![licence: MIT](https://img.shields.io/badge/licence-MIT-5C2D91.svg?labelColor=04001F)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.10%2B-5C2D91.svg?labelColor=04001F)](https://www.python.org/)
+
+An IBM Planning Analytics budgeting model published as source, with an offline
+engine that computes it and a test suite that asserts the answers.
+
+**Package lifecycle:** source-only. Install from this repository; it is not
+published to PyPI.
+
+Planning Analytics models usually live inside a server. You can read a rule file
+on GitHub, but you cannot run it, and nothing tells you whether a change to it
+broke a number. This repository holds a complete driver based budget for a
+fictional Australian mining services group in the layout IBM's own Git
+integration writes, plus a Python engine that parses the rules and evaluates
+them with no TM1 server anywhere. Continuous integration recomputes the whole
+model on every push and fails if a figure moves.
+
+## What is here
+
+- `model/` is the model: a `tm1project.json` manifest, 13 dimensions, 5 cubes,
+  4 rule files and 8 TurboIntegrator processes. Rules are plain `.rules` text
+  beside the cube JSON, scripts are plain `.ti` text beside the process JSON,
+  which is what the Planning Analytics Git integration reads and writes.
+- `pacioliscube/` is the engine: a rule parser, a structural validator, a cell
+  store with weighted consolidation, a CSV loader and a command line.
+- `examples/` contains fictional entities, commercial rates and volumes, plus
+  dated statutory rates and thresholds cited in `docs/model-assumptions.md`.
+- `docs/model-assumptions.md` traces every statutory figure to its source, and
+  says for each one whether it was read from the legislation or confirmed
+  against the administering authority's own page.
+
+## Install
+
+```bash
+git clone https://github.com/ryanduguid/planning-analytics-model.git
+cd planning-analytics-model
+python -m pip install .
+```
+
+The runtime imports nothing outside the Python standard library. From a clone:
+
+```bash
+uv run --locked --extra dev pytest -q
+```
+
+## Use
+
+Check the model's structure:
+
+```bash
+pacioliscube validate model
+```
+
+```
+0 errors, 0 warnings
+```
+
+Print a profit and loss from the shipped data:
+
+```bash
+pacioliscube report model --data examples --year FY2026-27 --version Budget
+```
+
+```
+Profit and loss for FY2026-27, Budget
+PnL at FY, Group, All Cost Centres
+
+Revenue             52,764,000
+Direct Costs      (14,884,800)
+Gross Margin        37,879,200
+Employment Costs  (11,428,418)
+Overheads          (6,384,000)
+EBITDA              20,066,782
+Depreciation       (1,382,143)
+EBIT                18,684,640
+```
+
+Read one cell, consolidated or leaf:
+
+```bash
+pacioliscube calculate model --data examples --cell "PnL:FY2026-27,Budget,FY,Group,All Cost Centres,EBIT,Amount"
+```
+
+Each report line is rounded to whole dollars on its own, so a subtotal can sit a
+dollar away from the lines above it. `calculate` prints the unrounded figure.
+
+The offline CSV loader refuses conflicting values for the same cell and names
+both rows. Repeated rows with equal decimal values remain valid, including when
+element names differ only in case or surrounding whitespace.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Clean |
+| 1 | A usage or input error, including a report that does not fit the model |
+| 2 | The model does not load, or validation reports an error |
+| 3 | A calculation failed |
+
+## The model
+
+Two entities, CivilCo (civil earthworks) and HaulCo (haulage), roll up to a
+`Group`. The year ends 30 June, so `Period` runs July to June. FY2025-26 is held
+as `Actual` and FY2026-27 as `Budget`.
+
+Four cubes feed a fifth. `Drivers` holds statutory and planning rates and has no
+rules at all. `Workforce` turns headcount and pay rates into base pay,
+superannuation and payroll tax. `Revenue` turns billable hours and charge rates
+into revenue, and litres into fuel cost. `Capex` spreads fleet additions over
+each asset class life. All three feed `PnL`, which carries the statement from
+revenue down to EBIT.
+
+No rule file holds a statutory rate. Every one is read from the `Drivers` cube
+with `DB()`, so changing the superannuation guarantee percentage means editing a
+CSV, not a rule. A test fails the build if a number in any rule or script
+carries a value the driver file ships.
+
+## What the tests actually check
+
+The suite computes the model and asserts figures, rather than only checking that
+the source parses. Each expected number is written out longhand in the test, so
+a reviewer can follow the arithmetic without trusting the engine:
+
+- Monthly base pay is headcount times the annual rate over twelve.
+- Superannuation is capped at the maximum contribution base, and the cap is
+  proved to bite by asserting the gap from the uncapped figure.
+- Each year caps at its own base, so correcting one year cannot pass silently.
+- Payroll tax is levied on pay grossed up by superannuation, not on pay alone.
+- The payroll tax threshold credit reaches the designated group employer and no
+  other cost centre.
+- Depreciation is annual additions over the asset life in months, and an asset
+  class with no life set charges nothing rather than raising.
+- EBIT equals EBITDA less depreciation at the Group, across the full year.
+- The `PnL` wages line equals `Workforce` base pay summed over roles.
+
+Breaking any of those in the model source turns the suite red.
+
+[Native TM1 comparison](docs/native-comparison.md) defines eight synthetic cells,
+their independent expected values and the evidence to retain. Native comparison
+is pending because no TM1 server was available; passing offline tests does not
+establish agreement with a native server.
+
+## What it does not do
+
+- It is not tax advice, and it is not a payroll or lodgement engine. The
+  superannuation and payroll tax treatment here is a planning approximation.
+- It is not a maintained rate table. The statutory figures are sample data
+  pinned at the date in `docs/model-assumptions.md`, and they go stale.
+- It is not a full set of accounts. No balance sheet, no cash flow, no income
+  tax, no GST, no foreign currency, no intercompany elimination.
+- The engine covers the subset of the TM1 rules language this model uses. It is
+  not a Planning Analytics reimplementation, and it will not run an arbitrary
+  model.
+
+## Client data
+
+No real data belongs in this repository. The `.gitignore` blocks the file names
+ledgers and payroll exports arrive under. The examples combine invented business
+data with dated, sourced statutory figures. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Releases
+
+The repository's [GitHub Releases](https://github.com/ryanduguid/planning-analytics-model/releases) page is the canonical release history. A separate changelog is intentionally not maintained.
+
+## Author
+
+Written by Ryan Duguid, a provisional member of Chartered Accountants ANZ,
+independently, in his own time and on his own equipment. Nothing here is the
+work of any employer, and no client data was used to build or test it.
+
+Parts of this repository were written with AI assistance. Every statutory figure
+is traced to its source in `docs/model-assumptions.md`, which records what was
+read from the legislation, what was taken from the administering authority's own
+page, and who confirmed the figures that could not be fetched.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

pacioliscube-0.1.2/README.md

@@ -0,0 +1,197 @@
+# IBM Planning Analytics budget model with an offline rule evaluator
+
+```
++----------------------------------------------------------------------+
+|                       planning-analytics-model                       |
++----------------------------------------------------------------------+
+|            IBM Planning Analytics budget model as source             |
++----------------------------------+-----------------------------------+
+| DR  what it gives you            | CR  what it needs                 |
++----------------------------------+-----------------------------------+
+| runs TM1 rules with no server    | PA model files in Git format      |
+| validates model structure        | CSV data for cube loading         |
+| prints a P and L report          | -                                 |
++----------------------------------+-----------------------------------+
+```
+
+The PaciolisCube budget model. This repository was named PaciolisCube until September 2026; the old URL redirects.
+
+[![tests](https://github.com/ryanduguid/planning-analytics-model/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanduguid/planning-analytics-model/actions/workflows/ci.yml)
+[![licence: MIT](https://img.shields.io/badge/licence-MIT-5C2D91.svg?labelColor=04001F)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.10%2B-5C2D91.svg?labelColor=04001F)](https://www.python.org/)
+
+An IBM Planning Analytics budgeting model published as source, with an offline
+engine that computes it and a test suite that asserts the answers.
+
+**Package lifecycle:** source-only. Install from this repository; it is not
+published to PyPI.
+
+Planning Analytics models usually live inside a server. You can read a rule file
+on GitHub, but you cannot run it, and nothing tells you whether a change to it
+broke a number. This repository holds a complete driver based budget for a
+fictional Australian mining services group in the layout IBM's own Git
+integration writes, plus a Python engine that parses the rules and evaluates
+them with no TM1 server anywhere. Continuous integration recomputes the whole
+model on every push and fails if a figure moves.
+
+## What is here
+
+- `model/` is the model: a `tm1project.json` manifest, 13 dimensions, 5 cubes,
+  4 rule files and 8 TurboIntegrator processes. Rules are plain `.rules` text
+  beside the cube JSON, scripts are plain `.ti` text beside the process JSON,
+  which is what the Planning Analytics Git integration reads and writes.
+- `pacioliscube/` is the engine: a rule parser, a structural validator, a cell
+  store with weighted consolidation, a CSV loader and a command line.
+- `examples/` contains fictional entities, commercial rates and volumes, plus
+  dated statutory rates and thresholds cited in `docs/model-assumptions.md`.
+- `docs/model-assumptions.md` traces every statutory figure to its source, and
+  says for each one whether it was read from the legislation or confirmed
+  against the administering authority's own page.
+
+## Install
+
+```bash
+git clone https://github.com/ryanduguid/planning-analytics-model.git
+cd planning-analytics-model
+python -m pip install .
+```
+
+The runtime imports nothing outside the Python standard library. From a clone:
+
+```bash
+uv run --locked --extra dev pytest -q
+```
+
+## Use
+
+Check the model's structure:
+
+```bash
+pacioliscube validate model
+```
+
+```
+0 errors, 0 warnings
+```
+
+Print a profit and loss from the shipped data:
+
+```bash
+pacioliscube report model --data examples --year FY2026-27 --version Budget
+```
+
+```
+Profit and loss for FY2026-27, Budget
+PnL at FY, Group, All Cost Centres
+
+Revenue             52,764,000
+Direct Costs      (14,884,800)
+Gross Margin        37,879,200
+Employment Costs  (11,428,418)
+Overheads          (6,384,000)
+EBITDA              20,066,782
+Depreciation       (1,382,143)
+EBIT                18,684,640
+```
+
+Read one cell, consolidated or leaf:
+
+```bash
+pacioliscube calculate model --data examples --cell "PnL:FY2026-27,Budget,FY,Group,All Cost Centres,EBIT,Amount"
+```
+
+Each report line is rounded to whole dollars on its own, so a subtotal can sit a
+dollar away from the lines above it. `calculate` prints the unrounded figure.
+
+The offline CSV loader refuses conflicting values for the same cell and names
+both rows. Repeated rows with equal decimal values remain valid, including when
+element names differ only in case or surrounding whitespace.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Clean |
+| 1 | A usage or input error, including a report that does not fit the model |
+| 2 | The model does not load, or validation reports an error |
+| 3 | A calculation failed |
+
+## The model
+
+Two entities, CivilCo (civil earthworks) and HaulCo (haulage), roll up to a
+`Group`. The year ends 30 June, so `Period` runs July to June. FY2025-26 is held
+as `Actual` and FY2026-27 as `Budget`.
+
+Four cubes feed a fifth. `Drivers` holds statutory and planning rates and has no
+rules at all. `Workforce` turns headcount and pay rates into base pay,
+superannuation and payroll tax. `Revenue` turns billable hours and charge rates
+into revenue, and litres into fuel cost. `Capex` spreads fleet additions over
+each asset class life. All three feed `PnL`, which carries the statement from
+revenue down to EBIT.
+
+No rule file holds a statutory rate. Every one is read from the `Drivers` cube
+with `DB()`, so changing the superannuation guarantee percentage means editing a
+CSV, not a rule. A test fails the build if a number in any rule or script
+carries a value the driver file ships.
+
+## What the tests actually check
+
+The suite computes the model and asserts figures, rather than only checking that
+the source parses. Each expected number is written out longhand in the test, so
+a reviewer can follow the arithmetic without trusting the engine:
+
+- Monthly base pay is headcount times the annual rate over twelve.
+- Superannuation is capped at the maximum contribution base, and the cap is
+  proved to bite by asserting the gap from the uncapped figure.
+- Each year caps at its own base, so correcting one year cannot pass silently.
+- Payroll tax is levied on pay grossed up by superannuation, not on pay alone.
+- The payroll tax threshold credit reaches the designated group employer and no
+  other cost centre.
+- Depreciation is annual additions over the asset life in months, and an asset
+  class with no life set charges nothing rather than raising.
+- EBIT equals EBITDA less depreciation at the Group, across the full year.
+- The `PnL` wages line equals `Workforce` base pay summed over roles.
+
+Breaking any of those in the model source turns the suite red.
+
+[Native TM1 comparison](docs/native-comparison.md) defines eight synthetic cells,
+their independent expected values and the evidence to retain. Native comparison
+is pending because no TM1 server was available; passing offline tests does not
+establish agreement with a native server.
+
+## What it does not do
+
+- It is not tax advice, and it is not a payroll or lodgement engine. The
+  superannuation and payroll tax treatment here is a planning approximation.
+- It is not a maintained rate table. The statutory figures are sample data
+  pinned at the date in `docs/model-assumptions.md`, and they go stale.
+- It is not a full set of accounts. No balance sheet, no cash flow, no income
+  tax, no GST, no foreign currency, no intercompany elimination.
+- The engine covers the subset of the TM1 rules language this model uses. It is
+  not a Planning Analytics reimplementation, and it will not run an arbitrary
+  model.
+
+## Client data
+
+No real data belongs in this repository. The `.gitignore` blocks the file names
+ledgers and payroll exports arrive under. The examples combine invented business
+data with dated, sourced statutory figures. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Releases
+
+The repository's [GitHub Releases](https://github.com/ryanduguid/planning-analytics-model/releases) page is the canonical release history. A separate changelog is intentionally not maintained.
+
+## Author
+
+Written by Ryan Duguid, a provisional member of Chartered Accountants ANZ,
+independently, in his own time and on his own equipment. Nothing here is the
+work of any employer, and no client data was used to build or test it.
+
+Parts of this repository were written with AI assistance. Every statutory figure
+is traced to its source in `docs/model-assumptions.md`, which records what was
+read from the legislation, what was taken from the administering authority's own
+page, and who confirmed the figures that could not be fetched.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

pacioliscube-0.1.2/SECURITY.md

@@ -0,0 +1,28 @@
+# Security
+
+## Supported version
+
+The latest commit on the default branch. There is no backport branch.
+
+## Reporting a vulnerability
+
+Use GitHub's private vulnerability reporting on this repository. Do not open a
+public issue.
+
+Expect an acknowledgement within seven days. If the report is valid, the fix and
+a note of what was affected land on the default branch.
+
+## What this project does and does not do
+
+The runtime imports nothing outside the Python standard library. It makes no
+network calls, reads no credentials and writes no files unless you ask it to.
+It reads two things: the model source under `model/` and whatever CSV files you
+point it at.
+
+Model source is data, not code. The loader refuses a link that climbs out of the
+model root, so a manifest or an object file cannot reach an arbitrary path on
+the machine that loads it. Rule text is parsed, never executed.
+
+The TurboIntegrator processes under `model/processes/` are source for a Planning
+Analytics server to run. Nothing here executes them. Read them before you deploy
+them, the same as any script you did not write.