irs-990-extract

Reusable section extractors for IRS Form 990, 990-EZ, and 990-PF XML filings.

This repo contains the extraction layer behind Harbor Commons: small, composable Python modules that turn IRS XML into structured outputs for downstream analysis.

What is here

• extract_part_vii.py — officer and compensation extraction
• extract_schedule_a.py through extract_schedule_r.py — schedule-level extraction modules
• extract_990ez_core.py — 990-EZ core extraction
• extract_narratives.py — narrative/text extraction support
• cli.py, run_extract.py, run_extract_v2.py — command-line entry points and orchestration
• utils.py — shared IRS namespace, hashing, and helper logic

Why this matters

Most nonprofit analysis starts with PDFs, flat exports, or manual review. This repo works one layer closer to the source: the XML itself. That makes extraction reproducible, diffable, and portable across fields.

Who this is for

• nonprofit researchers
• funders and intermediaries
• civic-tech builders
• anyone building a receipts-first nonprofit intelligence layer

Design choices

• Modular extractors instead of one monolithic parser
• Section-by-section evolution so individual schedules can improve independently
• Standard-library first where practical
• Public-record discipline so downstream consumers can trace claims back to filings

Relationship to Harbor Commons

This repo is the public extraction engine. harbor-commons is the public product layer built on top of methods like these.

Quick start

python run_extract.py /path/to/filing.xml
python cli.py /path/to/filing.xml --pretty

Documentation

See METHOD.md for the extraction philosophy, the evolution from flat crawl to targeted section extraction, and how to think about the older issue waves in context.