Metadata-Version: 2.4
Name: elizabeth-anne-alexander
Version: 0.2.4
Summary: A fixed-policy, synthetic-data review boundary for AI-assisted Xero trial-balance analysis
Author: Ryan Duguid
License-Expression: MIT
Project-URL: Homepage, https://github.com/ryanduguid/accounting-review-pipeline/tree/main/packages/elizabeth-anne-alexander
Project-URL: Documentation, https://github.com/ryanduguid/accounting-review-pipeline/tree/elizabeth-anne-alexander/v0.2.4/packages/elizabeth-anne-alexander
Project-URL: Repository, https://github.com/ryanduguid/accounting-review-pipeline.git
Project-URL: Issues, https://github.com/ryanduguid/accounting-review-pipeline/issues
Keywords: xero,ai-agents,accounting,privacy,controls
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff==0.16.7; extra == "dev"
Requires-Dist: mypy==2.3.1; extra == "dev"
Requires-Dist: pytest==9.1.1; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: coverage==7.16.0; extra == "dev"
Requires-Dist: build>=1.6.1; extra == "dev"
Dynamic: license-file

# Xero Ledger Review Gate

| Install distribution | Python import | Command |
| --- | --- | --- |
| `elizabeth-anne-alexander` | `elizabeth_anne_alexander` | `elizabeth-anne-alexander` |

Compatibility: install `elizabeth-anne-alexander`, import `elizabeth_anne_alexander`, and run `elizabeth-anne-alexander`. These remain the supported names; no migration is required.

## Scope and assurance boundary

This is a **synthetic-only** design demonstration. It accepts synthetic
Xero-shaped trial-balance fixtures, not client exports or evidence from Xero.
`receipt.json` is an adjacent, unkeyed local SHA-256 checksum binding. Anyone
who can replace the artefacts can replace the receipt. It does not prove
authorship, source system, origin, time, or immutability.

```
+----------------------------------------------------------------------+
|                       Xero Ledger Review Gate                        |
+----------------------------------------------------------------------+
|           Synthetic fixed-policy zero-network review gateway         |
+----------------------------------+-----------------------------------+
| DR  what it gives you            | CR  what it needs                 |
+----------------------------------+-----------------------------------+
| redacted variance review         | synthetic Xero-shaped TB fixture  |
| local review display data        | a review policy JSON file         |
| local checksum binding           | a human decision JSON file        |
+----------------------------------+-----------------------------------+
```

[![tests](https://github.com/ryanduguid/accounting-review-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanduguid/accounting-review-pipeline/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/elizabeth-anne-alexander.svg?color=5C2D91&labelColor=04001F)](https://pypi.org/project/elizabeth-anne-alexander/)
[![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/)
[![License: MIT](https://img.shields.io/badge/License-MIT-4F485E.svg?labelColor=04001F)](LICENSE)
[![No network client](https://img.shields.io/badge/Network-No%20Client-5C2D91.svg?labelColor=04001F)](DATA-FLOW.md)

A **fixed-policy, zero-network ledger-review boundary for AI**, not an AI that operates Xero.

The maintained source is under
[`packages/elizabeth-anne-alexander`](https://github.com/ryanduguid/accounting-review-pipeline/tree/main/packages/elizabeth-anne-alexander)
in the Accounting Review Pipeline. The `elizabeth-anne-alexander`
distribution and command, and `elizabeth_anne_alexander` import, remain
compatibility identifiers.

Xero Ledger Review Gate consumes synthetic Xero-shaped trial-balance fixtures and produces a bounded, redacted variance-review result alongside separate local review evidence. It deliberately features **no network calls, no cloud telemetry, no LLM API clients, and zero accounting-system write operations**.

---

## Zero-network architecture

```mermaid
%%{init: {"themeVariables": {"lineColor": "#B1AFAD"}}}%%
flowchart TD
    subgraph ClientPerimeter ["Local Client Perimeter (Zero-Network)"]
        Raw["Synthetic Xero-Shaped Trial Balance Fixture"] --> Validate["Context & Hash Integrity Gate"]
        Validate --> Engine["Decimal Variance Review Engine<br/><i>(Fixed Policy v1)</i>"]
    end

    subgraph ArtifactSplit ["Deterministic Artefact Generation"]
        Engine --> Split{"Split Boundary"}
        Split --> Model["model-result.json<br/><i>(Redacted Bounded Values for AI)</i>"]
        Split --> Evidence["reviewer-evidence.json<br/><i>(Local Review Display Data)</i>"]
        Split --> Receipt["receipt.json<br/><i>(Local SHA-256 Checksum Binding)</i>"]
    end

    subgraph Governance ["Human-in-the-Loop Review"]
        Model --> LLM["AI Advisory Assessment"]
        Evidence & Receipt & LLM --> Reviewer["Human Accountant Review Gate"]
        Reviewer --> Decision{"Decision Status"}
        Decision -->|ACKNOWLEDGED| Done["Recorded Review Decision"]
        Decision -->|NEEDS_EVIDENCE / ESCALATED| Action["Further Investigation"]
    end

    style ClientPerimeter fill:#140E24,stroke:#4F485E,stroke-width:2px,color:#FFFFFF
    style ArtifactSplit fill:#1E1236,stroke:#5C2D91,stroke-width:2px,color:#FFFFFF
    style Governance fill:#2D184E,stroke:#8A4AC7,stroke-width:2px,color:#FFFFFF
```

---

## Quick Demo

```bash
# Install package in editable development mode
pip install -e ".[dev]"

# Run deterministic evaluation
elizabeth-anne-alexander evaluate \
  --context samples/contexts/sample-monthly-variance.context.json \
  --request samples/requests/sample-revenue-variance.request.json \
  --policy policy/demo-policy-v1.json \
  --out build/demo
```

### Validate a recorded human review decision
```bash
elizabeth-anne-alexander validate-review \
  --evidence build/demo/reviewer-evidence.json \
  --receipt build/demo/receipt.json \
  --decision samples/decisions/sample-review-decision.json
```

---

## Control boundary

- The canonical source contract has exactly 10 columns: `ReportDate,Tenant,Section,AccountID,AccountName,AccountCode,Debit,Credit,YTDDebit,YTDCredit`.
- The root `contracts/xero-trial-balance-v1/` directory is the exporter-owned, fabricated
  `xero-tb-csv.v1` corpus. Its `SHA256SUMS` file and every consumer's tests verify the same bytes
  locally, with no runtime network dependency.
- CSV schema, duplicate account IDs, reporting dates, balance pairs, source hashes, entity, basis, currency, tracking filters, and draft setting are all checked before review.
- Monetary values use `Decimal`, never binary floating point. Evaluation runs under its own fixed 28-digit context, and a CSV whose totals would round in it is refused instead of compared inexactly.
- `percent_change` in the model result is expressed in per cent and quantized to 4 decimal places (`"18.3333"` means 18.3333%). It is `null` when there is no prior balance to compare against.
- The model result states its own `currency` and `sign_convention`. Amounts are debit-positive (`ytd_net = YTDDebit - YTDCredit`), so a revenue, liability, or equity balance is negative and a revenue increase shows as a negative `delta`.
- Current and prior reports must sit in the same Australian financial year, or be the same day and month in different years. YTD columns reset on 1 July, so a comparison across the reset would report a whole prior-year balance as a movement.
- Current/prior trial balances are joined by stable `AccountID`, not account display name or code.
- An account changing section between periods fails closed instead of disappearing from, or being silently reclassified within, a section-scoped comparison.
- The model result never contains a tenant name, account name, account code, source file path, token, raw error, or free text copied from source data.
- Artefact timestamps (`export.generated_at`, `reviewed_at`) are accepted as `YYYY-MM-DD`, then `T`, `t`, or a space, then `HH:MM` with optional `:SS` and optional `.` plus one to 6 fractional digits, then `Z`, `z`, or `+/-HH:MM` with optional `:SS`. The gateway fixes that grammar itself rather than inheriting `datetime.fromisoformat`, whose accepted forms widened in Python 3.11: a bare `+10` offset, a week date, a basic-format `20260809T000000+0000`, and a fraction longer than 6 digits are refused on every interpreter, as is a separator character other than `T`, `t`, or a space.
- The 3 run artefacts are staged beside their destinations and moved into place only once all 3 are written, receipt last. The moves are not one atomic step, so an interrupted run can still leave one new file beside 2 old ones; `validate-review` refuses that pack because the receipt checksum binds the reviewer evidence and model result sitting beside it. This detects mismatched local files, but the adjacent unkeyed receipt provides no independent trust anchor.
- The package contains no network imports or mutation adapter. A future live connection must remain an authorised, read-only export handoff rather than an AI-controlled broad Xero tool set.

## Scope and limitation

Every source manifest, review context, model result, reviewer evidence, and receipt is marked `mode: synthetic`. The policy, request, and human-decision files carry no `mode` key: each is validated against an exact key set, so adding one is rejected. The `validate-review` output carries no `mode` key either; it reports the decision status for a run whose artefacts were already checked. It is a local design demonstration, not a client-data processor, production security system, accounting service, or professional opinion. The reviewer evidence/model-result file split demonstrates disclosure minimisation only; it is not an access-control mechanism by itself.

## Documentation and governance

- [`DATA-FLOW.md`](./DATA-FLOW.md) - Formal data-flow and zero-network security specification.
- [`CITATION.cff`](./CITATION.cff) - Academic and industry citation metadata.
- [`LICENSE`](./LICENSE) - MIT License.
