irpf-bridge

irpf-bridge helps you work from your saved IRPF declaration instead of retyping everything in the official desktop program. It reads saved declaration files (.dec, .BKP, .xml, .conf), generates a review bundle from structured JSON inputs prepared from your supporting records, and writes back the declaration sections it currently supports so you can reopen the result in PGD and review it before filing.

Today the project targets IRPF 2026 artifacts and technically comfortable users on Linux. The official PGD desktop app remains the final review and acceptance step.

What it can help with today

Tax-return area	Current help
Company income for the main filer (_21)	Reads and writes supported PJ taxable income entries.
Dependents (_25)	Can add dependents through the supported registration path.
Payments and deductions (_26)	Supports codes 01 and 26.
Accounts, investments, and crypto (_27)	Supports deposit-like items plus structured asset positions for non-crypto, self-custody crypto, and exchange-custody crypto.
Company income for dependents (_32)	Supports dependent PJ taxable income when a compatible dependent record already exists.
Domestic debts (_55)	Can update existing code 12 entries; it does not create new debt entries.

What it does not do

• It is not a filing or transmission client.
• It does not ingest arbitrary PDFs, scans, OCR, or free text yet.
• It does not cover the full IRPF declaration.
• You still review the result in the official PGD desktop app before using it.

Quick start

1. Set up the project

make setup

2. Run the built-in smoke example

make smoke

This writes a run directory under var/smoke-runs/run-*/ with:

• review-bundle.json
• review-summary.txt
• trace.jsonl

3. Run a checked-in supported example

make run SCENARIO=fixtures/scenarios/informe-rendimentos-pj-supported/manifest.json
make fixture-check SCENARIO=fixtures/scenarios/informe-rendimentos-pj-supported/manifest.json

make run writes the review bundle for that example under var/runs/run-*/. make fixture-check reruns the same scenario and compares the output against the committed golden files.

Using your own declaration files

When you want to work with your own saved declaration and local notes, start with a directory that contains your declaration files (.dec, .BKP, .xml, or .conf), any local notes, and the structured JSON inputs for the supported area you want to update.

make local-harness-stage creates .local/local-harness/manifest.json to inventory those staged files. The writeback step still expects a prepared scenario manifest such as .local/local-harness/noncrypto/manifest.json; use a checked-in example like fixtures/scenarios/informe-rendimentos-pj-supported/manifest.json as the reference shape.

Then run:

make local-harness-stage \
  LOCAL_HARNESS_STAGED_ROOT=/absolute/path/to/staged-inputs
make local-harness-inspect
.venv/bin/python -m irpf_bridge local-harness writeback \
  --scenario .local/local-harness/noncrypto/manifest.json \
  --output-root var/local-harness/writeback

This keeps your local inputs out of git and writes updated .xml, .BKP, and .conf artifacts plus machine-readable review outputs for the prepared supported scenario.

Learn more

• fixtures/scenarios/ - checked-in example scenarios you can run today.
• docs/workflows/local-harness.md - workflow for staging your own local declaration files.
• docs/README.md - documentation guide and repository map.

License

This repository is licensed under GPL-3.0-only.