Forem: SKasagar

Extracting T4 Data from PDFs in Python — A Canadian Developer's Guide

SKasagar — Sat, 11 Apr 2026 01:46:00 +0000

Cross-posted from caseonix.ca

Every Canadian fintech team eventually hits this problem. Users upload their T4 slips. Your backend gets a PDF. Somewhere between that PDF and your database you need to pull out box 14, box 22, the SIN, the employer name — correctly, reliably, across documents from dozens of different payroll software vendors.

The obvious tools get recommended: AWS Textract, LlamaParse, pdfplumber, PyMuPDF. They're good at what they do. But none of them know what a T4 is. They don't know that box 14 is employment income, that box 22 is income tax deducted, that a nine-digit formatted number is a Social Insurance Number, or that CRA publishes an XML specification for this document every year. They hand you text. The domain knowledge you write yourself.

That ends up being more work than people expect. I've seen it written three or four different ways at different companies, none with tests, none with audit trails, all slightly wrong at the edges. This is the guide I wish existed before I started.

What's a T4? For non-Canadian readers: a T4 (Statement of Remuneration Paid) is the Canadian equivalent of a US W-2. Every employer issues one annually to report employment income, CPP contributions, EI premiums, and income tax withheld. It's one of the most common documents in Canadian fintech, mortgage underwriting, and tax software.

Why Regex Isn't Enough

The first instinct is regex. T4s are standardized CRA forms — surely field positions are consistent?

import re
import pdfplumber

with pdfplumber.open("t4_2024.pdf") as pdf:
    text = pdf.pages[0].extract_text()

box_14 = re.search(r"14\s+[\$]?([\d,]+\.?\d*)", text)
if box_14:
    income = float(box_14.group(1).replace(",", ""))

This works on the T4 you tested it on. It breaks on the next one because a different payroll vendor laid the PDF out differently, the box number is on a different line than the value, or the document is a scanned image with no text layer.

Regex extraction of financial documents is essentially a parser that only works on documents you've already seen. Every new employer format becomes a special case. The maintenance cost compounds.

Step 1 — Get Clean Text with Docling

Docling is IBM's open-source document intelligence toolkit. It handles PDF text extraction, layout analysis, table recognition, and OCR fallback. Runs entirely locally, no API keys, MIT licensed.

pip install docling

Then convert any PDF:

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("t4_2024.pdf")

# Clean markdown-formatted text, reading order preserved
text = result.document.export_to_markdown()
print(text)

What comes out is structured text with layout preserved. Docling understands the difference between a table cell and a paragraph. It handles scanned documents through an OCR pipeline and correctly orders multi-column layouts. For T4 PDFs — which vary significantly between payroll vendors — the output quality is consistent in a way raw pdfplumber isn't.

First-run note: Docling downloads its layout models from HuggingFace on first run (~500MB). This is expected — models are cached locally after that. For production, pre-pull them during your Docker build step.

Docling gives you clean text. It still doesn't know what box 14 means. That's the next layer.

Step 2 — Extract Fields with pydantic-ai

Once you have clean text, you need to pull out specific typed fields reliably. The right tool for this today is an LLM with structured output — you give it a Pydantic model and it fills it in. pydantic-ai handles this cleanly and is model-agnostic: Claude, OpenAI, and local Ollama all work behind the same interface.

pip install pydantic-ai

Define your T4 model and agent:

from pydantic import BaseModel
from pydantic_ai import Agent

class T4Fields(BaseModel):
    employer_name: str
    tax_year: int
    box_14_employment_income: float
    box_22_income_tax_deducted: float
    box_16_cpp_contributions: float | None = None
    box_18_ei_premiums: float | None = None
    box_52_pension_adjustment: float | None = None
    province_of_employment: str | None = None

agent = Agent(
    "anthropic:claude-sonnet-4-6",
    result_type=T4Fields,
    system_prompt="""
    You are extracting fields from a Canadian T4 Statement of Remuneration Paid.
    Return monetary values as plain floats (87500.0, not "$87,500.00").
    Return null for any field not present in the document.
    Province of employment should be a 2-letter code (ON, BC, QC, etc.).
    Do not hallucinate values — if a field is not visible, return null.
    """,
)

result = agent.run_sync(f"Extract T4 fields:\n\n{text}")
fields = result.output

print(fields.box_14_employment_income)   # → 87500.0
print(fields.box_22_income_tax_deducted) # → 21340.0
print(fields.province_of_employment)     # → "ON"

To run fully locally with no external API calls, swap the model string:

agent = Agent(
    "ollama:llama3.2",   # no ANTHROPIC_API_KEY needed
    result_type=T4Fields,
    system_prompt=...,
)

For environments with data residency requirements — most regulated Canadian financial services — that matters. The document never leaves your infrastructure.

Step 3 — The Part Most Implementations Skip

Docling plus pydantic-ai gets you surprisingly far. In testing on T4 PDFs from major Canadian payroll providers, field extraction accuracy sits above 90% on the primary income and tax boxes.

But two things are missing that matter for production use in regulated industries.

Confidence scoring and a review queue

The LLM will be more certain about box 14 (employment income, usually prominent and clearly labeled) than about box 52 (pension adjustment, often blank or formatted inconsistently). If you're pre-filling a tax form with extracted values, you need to know which fields are safe to pass through automatically and which ones need a human to confirm.

Without confidence scores, low-quality extractions silently enter production. That's how incorrect T4 data gets submitted to CRA.

PII handling and an audit trail

A T4 contains a Social Insurance Number. Before you send that document text to any external API, you should know what PII is in it. Canada's PIPEDA requires that organizations limit the collection, use, and disclosure of personal information to what's necessary for the identified purpose — sending a full T4 text to a US-based cloud LLM for extraction is hard to defend under that standard unless you've taken steps to identify and handle the PII.

⚠️ The SIN problem: A Canadian SIN in the format XXX-XXX-XXX is sensitive personal information under PIPEDA. Every T4 contains one. If you're sending raw T4 text to a US-based cloud API without detecting and handling this, you're creating a compliance exposure that most legal teams would not be comfortable with.

Putting It Together: Docling + pydantic-ai + Presidio

Microsoft Presidio is an open-source PII detection and anonymization library. It supports custom recognizers — you can teach it what a Canadian SIN looks like, what a CRA Business Number looks like, and what Canadian postal codes look like. None of these ship in Presidio's defaults.

pip install presidio-analyzer presidio-anonymizer
python -m spacy download en_core_web_lg

Then add the Canadian recognizers and scan:

from presidio_analyzer import AnalyzerEngine, PatternRecognizer, Pattern
from presidio_anonymizer import AnonymizerEngine
from presidio_anonymizer.entities import OperatorConfig

analyzer = AnalyzerEngine()

# Add Canadian SIN recognizer — not in Presidio defaults
sin_recognizer = PatternRecognizer(
    supported_entity="CA_SIN",
    patterns=[Pattern("CA_SIN", r"\b\d{3}-\d{3}-\d{3}\b", score=0.9)],
    context=["sin", "social insurance"],
)
analyzer.registry.add_recognizer(sin_recognizer)

# Scan before sending to LLM
results = analyzer.analyze(text=document_text, language="en")
pii_found = [{"entity_type": r.entity_type, "score": r.score} for r in results]

# Optionally redact before the LLM call
anonymizer = AnonymizerEngine()
redacted = anonymizer.anonymize(
    text=document_text,
    analyzer_results=results,
    operators={"CA_SIN": OperatorConfig("replace", {"new_value": "***-***-***"})},
)
# Send redacted.text to the LLM instead

Now you know what PII was in the document before extraction ran, you have a record of it, and you can choose whether to redact before the LLM call.

The Full Stack in One Place: FinLit

Wiring Docling, pydantic-ai, Presidio, confidence scoring, audit logging, and CRA-specific schemas together is the kind of plumbing every team building on Canadian documents ends up writing. I built FinLit — an open-source Python library that does exactly this, with pre-built YAML schemas for T4, T5, T4A, NR4, and Canadian bank statements.

pip install finlit
python -m spacy download en_core_web_lg

Then run the pipeline:

from finlit import DocumentPipeline, schemas

pipeline = DocumentPipeline(
    schema=schemas.CRA_T4,
    extractor="claude",      # or "openai" or "ollama"
    audit=True,
    pii_redact=False,        # set True to redact SINs in audit log output
    review_threshold=0.85,
)

result = pipeline.run("john_doe_t4_2024.pdf")

The result object has everything:

# Typed, validated fields — monetary values are always float
result.fields["box_14_employment_income"]      # → 87500.0
result.fields["box_22_income_tax_deducted"]    # → 21340.0
result.fields["province_of_employment"]        # → "ON"

# Per-field confidence — box 52 came back uncertain
result.confidence["box_52_pension_adjustment"] # → 0.71

# Fields below the 0.85 threshold go here instead of silently through
result.needs_review    # → True
result.review_fields
# [{"field": "box_52_pension_adjustment", "confidence": 0.71, "raw": "4,200.00"}]

# Trace any extracted value back to its page and location
result.source_ref["box_14_employment_income"]
# {"page": 1, "bbox": [120, 340, 280, 360], "doc": "john_doe_t4_2024.pdf"}

# Immutable audit log — every event from load to completion
result.audit_log
# [
#   {"event": "document_loaded",     "sha256": "abc...", "ts": "..."},
#   {"event": "pii_detected",        "count": 1, "entities": ["CA_SIN"], "ts": "..."},
#   {"event": "extraction_complete", "fields_returned": 13, "ts": "..."},
#   {"event": "review_flagged",      "count": 1, "ts": "..."},
#   {"event": "pipeline_complete",   "fields_extracted": 13, "ts": "..."}
# ]

# Raw PII detections on the source document (Presidio output)
result.pii_entities
# [{"entity_type": "CA_SIN", "score": 0.9, "start": 142, "end": 153}]

For batch processing — say, a payroll integrator running hundreds of T4s at year-end:

from finlit import BatchPipeline, schemas
from glob import glob

batch = BatchPipeline(schema=schemas.CRA_T4, extractor="ollama", workers=8)

for path in glob("uploads/*.pdf"):
    batch.add(path)

results = batch.run()
results.export_csv("extracted/t4s_2024.csv")

print(f"Processed:    {results.total}")
print(f"Needs review: {results.review_count}")

The extractor="ollama" configuration means no document leaves your infrastructure. The pipeline runs entirely on-premises, which removes the PIPEDA third-party disclosure question entirely.

Build vs Buy vs Open-Source

Approach	Time to first extraction	Canadian schemas	Audit trail	Data residency	Cost
Regex + pdfplumber	Hours	You write them	None	On-prem	Free
AWS Textract	Hours	None	Partial	US only	$1.50/1000 pages
LlamaParse	Minutes	None	None	US SaaS	$3–$10/1000 pages
Docling alone	Hours	You write them	None	On-prem	Free
FinLit	Minutes	T4, T5, T4A, NR4, bank statements	Built in	On-prem or cloud	Free + LLM costs

What the Schema YAML Looks Like

Every built-in schema in FinLit is a versioned YAML file. The T4 schema maps directly to CRA's published XML specification. Here's a simplified excerpt:

name: cra_t4
version: "2024"
document_type: "CRA T4 Statement of Remuneration Paid"

fields:
  - name: box_14_employment_income
    dtype: float
    required: true
    description: "Box 14: Total employment income before deductions"

  - name: employee_sin
    dtype: str
    required: true
    pii: true
    regex: '^\d{3}-\d{3}-\d{3}$'
    description: "Employee's Social Insurance Number"

  - name: province_of_employment
    dtype: str
    required: false
    description: "Province or territory of employment (2-letter code)"

The pii: true flag tells the pipeline this field is sensitive — it gets flagged in the audit log and can be redacted depending on your pii_redact configuration. The regex field enforces format validation after extraction, so a malformed SIN raises a validation error rather than silently passing through.

Adding a new schema for a document type that isn't in the registry yet takes about 20 minutes if you know the document. Schema contributions are the highest-value PRs the project gets.

Practical Notes from Building This

A few things that aren't obvious until you've processed a few thousand real T4s:

Scanned T4s are common. Many smaller employers still print and scan. Docling's OCR pipeline handles these, but accuracy drops — budget for a higher review threshold (0.90 vs 0.85) on scanned documents.
Box 52 (pension adjustment) is almost always uncertain. It's blank for most employees, optionally present for others, and formatted inconsistently across payroll vendors. Flag it for review at any confidence below 0.95 if your use case relies on it.
Quebec T4s have additional fields. RL-1 slips carry Quebec provincial tax information that a standard T4 schema doesn't cover. If you're processing documents from Quebec employees, you'll want a separate RL-1 schema.
CRA updates its XML specification annually. Field names and codes are stable, but new boxes get added. Pin your schema version and test against new documents at the start of each tax year.
Multi-page T4s exist. Most T4s are single-page, but amended T4s can span two pages. Docling handles this correctly; regex approaches often don't.

The Short Version

Use Docling for parsing, pydantic-ai for field extraction, Presidio for PII detection, and either wire it together yourself or use FinLit to skip the plumbing. Run it locally with Ollama if you can't send documents to a cloud API. Build an audit log from the start — retrofitting one later is painful.

Building PIPEDA-Compliant AI Tools on Cloudflare Workers — A Developer's Guide

SKasagar — Tue, 07 Apr 2026 20:02:00 +0000

Canada still runs on PIPEDA, Bill C-27 died on the Order Paper, and the CLOUD Act didn't go anywhere. Here's what that actually means if you're building AI tools for the Canadian market in 2026 — and how to ship them without a compliance incident.

The Regulatory Landscape: What Actually Applies in 2026

If you've been waiting for Ottawa to sort out AI regulation, you'll be waiting a while longer. Bill C-27 — which would have introduced the Consumer Privacy Protection Act (CPPA) and the Artificial Intelligence and Data Act (AIDA) — died when Parliament was prorogued in January 2025. A snap federal election in April 2025 pushed reform further down the road. As of April 2026, Canada has no federal AI-specific legislation.

I spent 25 years in financial services before starting to build AI tools for this market. The compliance landscape isn't new to me — but the gap between what AI vendors promise and what Canadian regulations actually require was wide enough to build a company in.

That doesn't mean you're operating in a vacuum. Three frameworks define your compliance obligations right now:

PIPEDA (federal) — Canada's Personal Information Protection and Electronic Documents Act, written in 2000 but still the law. It requires meaningful consent, accountability for data in the hands of third parties, and "comparable protection" for cross-border transfers.
Quebec's Law 25 (provincial) — Fully enforced since September 2024 and significantly stricter than PIPEDA. Requires explicit consent for automated decision-making, mandatory Privacy Impact Assessments for high-risk AI, and penalties up to C$25M or 4% of global revenue.
OSFI B-13 (sector-specific) — If you serve federally regulated financial institutions, OSFI's Technology and Cyber Security Risk Management guideline requires third-party risk management that extends to AI service providers.

Most builders now align with Quebec Law 25 as their baseline — it's the strictest Canadian framework, and if you comply with it, you effectively comply with PIPEDA too. If you serve financial institutions, layer OSFI B-13 on top.

The CLOUD Act Problem Nobody Wants to Talk About

Here's the uncomfortable truth about "Canadian data residency" in 2026: storing data in a Canadian data centre run by a US company does not protect it from US government access.

The US CLOUD Act (Clarifying Lawful Overseas Use of Data Act) gives American authorities the power to compel US-headquartered companies to hand over data regardless of where that data is physically stored. This means AWS Canada Central in Montreal, Azure Canada East in Quebec City, and Google Cloud's Montreal region are all subject to US legal orders — even though the bits never leave Canadian soil.

For most consumer applications, this is a theoretical risk. But for legal firms handling privileged documents, financial institutions under OSFI oversight, healthcare organizations subject to PHIPA, or government contractors — it's a real compliance problem that auditors are increasingly asking about.

What this means for your architecture

You have three tiers of Canadian data residency, and they offer very different levels of protection:

Tier	What It Means	CLOUD Act Exposure	Examples
1. Canadian-operated infrastructure	Data processed by a Canadian-incorporated company on Canadian servers	None	ThinkOn/Hypertec sovereign cloud, TELUS/OpenText sovereign cloud, Bell/SAP sovereign cloud
2. US hyperscaler, Canadian region	Data in Canada, but operator is US-incorporated	Yes — compellable by US legal order	AWS ca-central-1, Azure Canada East, GCP Montreal
3. US processing	Data leaves Canada entirely	Full exposure	ChatGPT, Copilot (most configurations), Gemini

For most regulated use cases, Tier 2 is the pragmatic minimum — it satisfies PIPEDA's "comparable protection" standard and is what most organizations document in their PIAs. Tier 1 is where you go when the threat model specifically includes foreign government access to data, which is increasingly the case in defence, government, and privileged legal work.

Five Design Principles for Compliance-First AI

After building LocalMind, a sovereign document intelligence platform for the Canadian market, I've arrived at five architectural principles that make compliance a design spec rather than an afterthought.

1. Pin computation to geography

Don't just store data in Canada — process it there too. Every API call to a US-hosted LLM is a cross-border transfer under PIPEDA. Cloudflare Workers run at the edge and can be pinned to Canadian data centres using Custom Regions (launched March 2026). Workers AI provides embedding models that execute on-region. For LLM inference, route through an AI Gateway with jurisdiction controls.

How I built LocalMind: All TLS termination, embedding generation, vector search, and document processing runs on Cloudflare's Canadian edge. LLM calls route through AI Gateway with Canadian jurisdiction pinning. The result: sub-5ms cold starts and zero US data exposure.

2. Detect and redact PII before it hits the model

The simplest way to reduce your compliance surface is to never send personal information to the LLM in the first place. Build a PII detection layer that runs before any AI processing:

Pattern matching for structured PII: SINs (Canadian Social Insurance Numbers), credit card numbers, health card IDs, phone numbers, email addresses
Named Entity Recognition for unstructured PII: names, addresses, dates of birth
Redaction options: replace with tokens ([PERSON_1]), mask partially (***-***-123), or strip entirely

This isn't just good compliance hygiene — it also reduces hallucination risk, because the model isn't distracted by personal details that are irrelevant to the analysis.

3. Log everything, explain everything

Quebec's Law 25, Section 12.1 requires you to explain automated decisions to affected individuals. PIPEDA's accountability principle (Principle 1) makes you responsible for data in the hands of third-party processors. Both of these demand audit trails.

At minimum, log:

What data was sent to which AI model, and when
What the model returned
What decision was made based on that output
What PII was detected and how it was handled
Which user or process initiated the request

Store these logs in the same jurisdiction as the data itself. If your compute is in Canada but your logs are in Datadog's US region, you've created a cross-border transfer that undermines the whole architecture.

4. Build for human-in-the-loop

Law 25 requires that individuals can request human review of automated decisions. PIPEDA's accuracy principle (Principle 6) means AI-generated conclusions need to be challengeable. Build this into the product from day one:

Every AI-generated finding should cite its source document and passage
Users should be able to override, dismiss, or escalate any automated assessment
Confidence scores should be visible, not hidden behind a clean UI
Critical decisions (compliance pass/fail, risk ratings) should require explicit human confirmation

5. Isolate tenants at the data layer

Multi-tenant AI systems need strict namespace isolation. When Organization A uploads a contract, Organization B's vector search must never surface it — even if the embeddings are mathematically similar. Use per-tenant namespaces in your vector database, per-tenant encryption keys if possible, and never co-mingle document chunks across organizational boundaries.

Canadian Infrastructure Options in 2026

The Canadian AI infrastructure landscape has expanded significantly. Here's what's actually available for builders:

Provider	Canadian AI Services	Sovereignty Level	Best For
Cloudflare	Workers AI (embeddings, inference), Vectorize, D1, R2, Custom Regions for Canada	US-incorporated, but Custom Regions pin processing to Canadian PoPs	Edge-first apps, document processing, low-latency AI
AWS Canada	Bedrock (foundation models), SageMaker, ca-central-1 and ca-west-1	Tier 2 (US-incorporated)	Enterprise workloads, teams already on AWS
Azure Canada	Azure OpenAI (Canada East), Azure ML, Copilot with in-country processing (2026)	Tier 2 (US-incorporated)	Microsoft shops, government (with caveats)
ThinkOn/Hypertec/Aptum	Sovereign government cloud (launched Oct 2025)	Tier 1 (Canadian-incorporated)	Federal/provincial government, defence
TELUS/OpenText	Sovereign cloud (launched Jul 2025)	Tier 1 (Canadian-incorporated)	Regulated industries, healthcare
Bell/SAP	Sovereign cloud (launched Feb 2026)	Tier 1 (Canadian-controlled)	Enterprise ERP with sovereign AI

A Compliance Checklist for Shipping

Before you launch an AI tool for the Canadian market, run through this:

[ ] Data residency documented: You can state exactly where data is stored and processed, and which jurisdictions apply to your providers.
[ ] PII detection in place: Personal information is identified and handled (redacted, masked, or consented) before AI processing.
[ ] Consent is meaningful: Users understand, in plain language, that AI will process their information and how.
[ ] Automated decisions are explainable: Every AI output cites its source, and users can request human review.
[ ] Audit trail exists: Every AI interaction is logged — input, output, model used, timestamp, user — and logs are stored in the same jurisdiction as the data.
[ ] Privacy Impact Assessment completed: Required by Law 25 for high-risk AI; good practice everywhere.
[ ] Cross-border transfers documented: If any data leaves Canada (including for LLM inference), you've documented the legal basis and safeguards.
[ ] Tenant isolation tested: Multi-tenant systems have been tested to confirm no cross-tenant data leakage in search, retrieval, or AI outputs.
[ ] Third-party risk assessed: You've evaluated your AI providers' CLOUD Act exposure and documented it in your risk register.
[ ] Breach response plan includes AI: Your incident response plan covers scenarios where AI-processed data is compromised.

I built LocalMind with compliance as a design constraint — the same way you'd treat latency or uptime. The regulatory landscape will catch up eventually. The question is whether your architecture is ready when it does.