SPB Git

spb/air Public MIT

AIR — The Language of Accounting.

languageaccountingcompiler
Python 100%
2.5 KB
View source Raw Blame History

# Contributing to AIR

Thank you for considering a contribution! AIR has a few non-negotiable rules that CI enforces — read them before opening a PR.

# The rules (enforced)

  1. Author header on every file. Every source/doc/config file starts with the project header (see any file for the format). python scripts/check_headers.py must pass — CI fails otherwise.
  2. No floats for money — ever. Amounts, quantities, rates are Decimal in code and strings in JSON/YAML. Floats are rejected at every boundary.
  3. No tax rate, threshold, or rounding mode in code. All fiscal and policy parameters live in versioned ALSL policy sets with a mandatory source citation. The loader rejects uncited rates.
  4. Research before rules. Anything touching tax law, accounting standards, external APIs, or data formats needs a cited report in docs/research/ (official sources, consultation dates). Never from memory.
  5. The compiler stays deterministic. No LLM, network, or clock inside AIC. Same document + same policies = byte-identical journal.
  6. The invariant is sacred. Assets = Liabilities + Equity is verified after every compiler pass. New passes must keep entries balanced.
  7. Append-only history. Corrections are reversal entries; nothing posted is ever edited or deleted.

# Workflow

bash
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest tests/ -q --ignore=tests/test_llm_live.py   # offline suite
python3 scripts/check_headers.py
  • Write tests with the code: golden cases for accounting behavior (tests/golden/cases/*.yaml), property tests for invariants, unit tests for mechanics.
  • New event types need: posting rules, golden cases, and a spec update.
  • New backends implement backends/base.py (capabilities/compile/post/reverse) and must be fully testable offline (mock transport pattern — see backends/quickbooks/).
  • Architecture decisions get an ADR in docs/adr/.

# What makes a good first contribution

  • A new ALSL policy set for another jurisdiction (with cited research)
  • The beancount/hledger export backend (near-free per the research)
  • Reference-first matching (EndToEndId) in reconciliation
  • A Xero or Odoo backend with an offline mock transport

Author: Simon-Pierre Boucher — contact@spboucher.ai