payslip-ingest/tests/fixtures/meta_uk_2024_03_bonus_sacrificed.txt

Facebook UK Limited                                                                        Payslip

Employee:  Viktor Barzin                  NI Number:  AA123456A               Pay Date:      27/03/2024
Employee No:  254680                      Tax Code:   1257L                   Pay Period:    12
Department:  Engineering                                                      Period Start:  01/03/2024
                                                                              Period End:    31/03/2024


Payments                Units      Rate         Amount    Deductions                 Amount    Year to Date              Amount
Salary                                       9,500.00     Tax paid                   800.00    Salary                114,000.00
Perform Bonus                                    0.00     Employee NIC               280.00    Transportation            820.50
AE Pension EE                               -6,200.00     Student Loans               90.00


                                            ---------                         ---------
Total Payment:                               3,300.00     Total Deduction :    1,170.00        Net Pay:                2,130.00


This Period                                   Amount     Year To Date                Amount
Total Gross:                               3,300.00      Total Gross:            210,000.00
Taxable Pay:                               3,300.00      Taxable Pay:            185,000.00
Tax Paid:                                    800.00      Tax Paid:                42,000.00
EEs NI:                                      280.00      EEs NI:                   9,100.00
EEs Pension:                              -6,200.00      EEs Pension:            -52,000.00
v2: regex parser for Meta UK template + accurate RSU tax attribution ## Context v1 shipped a Claude Haiku-based extractor that validated only 10/71 backfilled rows. Haiku fumbles the arithmetic on pension salary-sacrifice, conflates RSU vest with regular earnings, and occasionally misreads YTD vs this-period columns — so 86% of rows land with validated=false and the downstream dashboards under-report take-home. Meta UK uses a stable two-variant template (pre/post 2022-01-31 boundary), so a regex parser is both faster (ms vs. 30-90s + $0.01-0.05/call) and more accurate. v2 introduces that parser as the primary path, keeps Claude as the fallback for non-Meta payslips, and surfaces new fields the dashboard needs to attribute PAYE between cash salary and RSU vests correctly. ## This change ### Parser (new) `payslip_ingest/parsers/meta_uk.py` detects the layout variant by header presence: - Variant A (pre-2022): vertical Description/This Period/This Year. `AE Pension EE` is a positive deduction against a pre-sacrifice gross — maps to `pension_employee` for the existing validation formula to hold. - Variant B (post-2022): side-by-side Payments \| Deductions \| Year to Date. `AE Pension EE` is NEGATIVE in Payments (salary sacrifice) — maps to `pension_sacrifice` and is already netted into Total Payment. `rsu_vest = RSU Tax Offset + RSU Excs Refund` (Meta's template inflates Taxable Pay without using a matching offset deduction). Column boundaries come from the header row's anchor positions; each data row slices into 3 cells and the last numeric token per cell is the amount. Anchor misses raise ParserError so the caller falls back to Claude rather than silently returning bad data. ### New fields Schema + DB + Claude prompt gain: - `salary`, `bonus`, `pension_sacrifice` — earnings decomposition for the dashboard's bonus-sacrifice visibility and earnings-breakdown chart - `taxable_pay`, `ytd_tax_paid`, `ytd_taxable_pay`, `ytd_gross` — powers the YTD-effective-rate method of attributing cash tax vs RSU tax, which is the only method that's accurate month-to-month All new columns default to 0 / null so v1 rows continue to round-trip. ### Orchestration processor.py tries `parse_meta_uk(pdftotext(pdf))` first. On success the result goes straight to the DB — zero Claude tokens spent, extraction in milliseconds. On ParserError it falls through to ClaudeExtractor as before. ProcessResult gains an `extractor` field ("meta_uk_regex" \| "claude") so backfill logs show the hit rate. ## Tests - `test_meta_uk_parser.py` — 11 tests covering variant A, variant B (standard + bonus month + bonus-sacrificed month), malformed inputs, and end-to-end totals validation for all 4 golden fixtures. - `test_processor.py` — 2 new tests proving the regex-first short-circuit and the Claude fallback on non-Meta inputs. Fixtures under `tests/fixtures/` are hand-crafted `pdftotext -layout` emulations — real Meta numbers from the plan's sample payslips for variant B, synthesized realistic variant A and bonus-sacrificed samples. 0001_initial.py reformat is yapf cleanup touched during the session's format pass; not a behavior change. ## Test Plan ### Automated ``` $ poetry run pytest ============================= test session starts ============================== collected 53 items tests/test_extractor.py ..... [ 9%] tests/test_meta_uk_parser.py ........... [ 30%] tests/test_paperless.py ...... [ 41%] tests/test_processor.py .............. [ 67%] tests/test_schema.py .... [ 75%] tests/test_tax_year.py ........ [ 90%] tests/test_webhook.py ..... [100%] ============================== 53 passed in 1.66s ============================== $ poetry run ruff check . All checks passed! $ poetry run mypy . Success: no issues found in 24 source files $ poetry run yapf --style pyproject.toml --diff --recursive payslip_ingest tests (no output — all files are yapf-clean) ``` ### Manual Verification Smoke-test the parser against a real Meta payslip PDF on the deploy host: ``` # After 0003 migration applied to prod DB $ poetry run python -c " from payslip_ingest.parsers import parse_meta_uk import subprocess text = subprocess.check_output(['pdftotext', '-layout', '/path/to/real.pdf', '-']).decode() p = parse_meta_uk(text) print(p.model_dump_json(indent=2)) " ``` Expected: JSON with salary/bonus/rsu_vest/pension_sacrifice populated and `validate_totals(p)` returning True. ## Reproduce locally 1. `cd payslip-ingest && poetry install` 2. `poetry run pytest tests/test_meta_uk_parser.py -v` 3. Expected: 11 tests pass, each fixture validates totals within 2p. Closes: code-un1 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> 2026-04-19 10:53:52 +00:00			`Facebook UK Limited Payslip`

			`Employee: Viktor Barzin NI Number: AA123456A Pay Date: 27/03/2024`
			`Employee No: 254680 Tax Code: 1257L Pay Period: 12`
			`Department: Engineering Period Start: 01/03/2024`
			`Period End: 31/03/2024`


			`Payments Units Rate Amount Deductions Amount Year to Date Amount`
			`Salary 9,500.00 Tax paid 800.00 Salary 114,000.00`
			`Perform Bonus 0.00 Employee NIC 280.00 Transportation 820.50`
			`AE Pension EE -6,200.00 Student Loans 90.00`


			`--------- ---------`
			`Total Payment: 3,300.00 Total Deduction : 1,170.00 Net Pay: 2,130.00`


			`This Period Amount Year To Date Amount`
			`Total Gross: 3,300.00 Total Gross: 210,000.00`
			`Taxable Pay: 3,300.00 Taxable Pay: 185,000.00`
			`Tax Paid: 800.00 Tax Paid: 42,000.00`
			`EEs NI: 280.00 EEs NI: 9,100.00`
			`EEs Pension: -6,200.00 EEs Pension: -52,000.00`