# Form 990 XAI Risk: an interpretable review-prioritization framework for IRS nonprofit filings

> Form 990 XAI Risk is a research-grade Python framework that scores IRS Form 990 filings for human review prioritization, combining structured financial features, text analysis, and graph models with built-in explainability. pyproject.toml names the package 'esgx' for ESG reporting with no ML dependencies declared, a mismatch with the README's Form 990 compliance scope and deep learning architecture.

**jc2744-fintech/taxguard-xai** — Interpretable AI framework for compliance risk screening on IRS Form 990 filings — transformers, GNNs, and temporal models with built-in explainability.

- Repository: https://github.com/jc2744-fintech/taxguard-xai
- Stars: 1,001 · Forks: 18
- Language: Python
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/jc2744-fintech-taxguard-xai

## Prioritizing Form 990 filings for human review, not automating compliance findings

Form 990 XAI Risk targets audit teams and compliance researchers who work with IRS public data from nonprofit organizations. Scores and signals produced by the framework identify records that may deserve human verification, not findings of fraud, tax noncompliance, intent, or legal liability. Every consequential conclusion must be checked against the original filing and the relevant context.

A concept called governed outputs enforces this boundary. Facts, derived features, weak signals, model scores, explanation data, and reviewer decisions are kept as separate artifacts throughout the pipeline. Nothing merges them into a single verdict.

Intended users are research groups working with the IRS Tax Exempt Organizations Search dataset, known as TEOS, and with ProPublica Nonprofit Explorer data. A compliance officer who needs a ready-to-deploy screening service will find this insufficient. Leakage-aware evaluation using organization-grouped stacking and expanding-window tax-year backtesting is documented in the README, which points toward a research setting where evaluation methodology matters as much as the predictions themselves.

## A six-layer pipeline from IRS XML to a review bundle with three parallel model branches

Data flows from two input sources through normalization into three parallel branches, then into a fusion layer, and finally into a human-review bundle. IRS TEOS XML files and ProPublica Nonprofit Explorer API v2 are the two intake paths.

Normalization is version-tolerant, supporting XML aliases across different Form 990 schema versions, and covers filings, relations, officers, and a parser diagnostic report. A quality layer adds duplicate detection, reconciliation checks, missingness audits, history-gap detection, and coverage audits.

Three processing branches run in parallel after normalization. Structured processing builds financial, governance, reconciliation, and temporal features. Text processing runs a TF-IDF logistic model with signed token contributions, with an optional pretrained Transformer and token attribution as the research extension. Graph processing uses one-hop relation features from disclosed filing relationships and a derived peer graph, plus GATv2 with edge attention as an optional path. On temporal data, a separate branch adds annual ratios, changes, deficit runs, and history depth, with a dilated residual TCN with integrated gradients as the deep learning option.

All three streams feed into a fusion layer using grouped out-of-fold stacking and uncertainty routing. Output is a review bundle containing review_queue.csv, review_queue.jsonl, and review_queue.html, alongside anomaly scores, weak supervision signals, and run_summary.json.

## pip install -e '[dev]' and form990-xai real-sample run the 15-record smoke test

Setup follows a standard virtual environment flow:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e '.[dev]'

form990-xai real-sample --output-dir artifacts/real_sample
```

Running that command produces artifacts under artifacts/real_sample/. Directory contents include analytical_relations.csv, anomaly_model.joblib, anomaly_scores.csv, latest_organization_profiles.csv, model_frame.csv, a quality directory, and a review_bundle directory with review_queue.csv, review_queue.jsonl, and review_queue.html, alongside run_summary.json, weak_review_signals.csv, and weak_supervision_report.json.

A checked-in snapshot of 15 organization-year records for three Washington nonprofits drives this smoke test. Person names, addresses, individual compensation rows, and labels are all omitted. Provenance documentation lives at data/real_sample/README.md and docs/REAL_DATA_PROVENANCE.md.

Fetching a fresh cohort from ProPublica requires no API key for the documented Nonprofit Explorer API v2 endpoint:

```bash
form990-xai fetch-propublica \
  --ein 91-0564748 \
  --ein 91-1935159 \
  --ein 91-0565006 \
  --output-dir data/refresh \
  --build-graph
```

Raw JSON responses are cached before normalization, and each fetch writes a manifest recording URL, retrieval timestamp, SHA-256, byte count, and cache path.

## Three modeling modes: anomaly discovery, weak supervision, and optional deep learning

Without any labels, Isolation Forest runs on normalized features and produces anomaly percentile scores. A high percentile means unusual relative to the fitted reference data, not noncompliant. Explanation output uses empirical percentiles and `robust-z` reasons.

Running the anomaly mode:

```bash
form990-xai anomaly \
  --filings data/processed/filings.csv \
  --relations data/processed/relations.csv \
  --save-model artifacts/anomaly.joblib \
  --output artifacts/anomaly_scores.csv
```

A second mode relies on 11 auditable weak-label functions. Weak labels are generated programmatically from filing data, with abstentions and conflicts tracked separately so the review queue reflects genuine uncertainty rather than false precision. Expert-adjudicated labels are marked as the optional research extension, meaning the checked-in snapshot has no adjudicated labels and carries no predictive performance claims.

Deep learning extensions add three optional paths: a pretrained Transformer with token attribution on text, GATv2 with edge attention on the graph, and a dilated residual TCN with integrated gradients on temporal sequences. All three appear in the implemented capabilities table under the column labeled 'optional research branch,' separate from the laptop-friendly baseline.

## Disclosed and analytical graphs serve different purposes and must not be conflated

Form 990 XAI Risk separates two graph concepts that the architecture keeps distinct. Disclosed relationship graphs are extracted from Form 990 schedules: related organizations, officers, and service providers. Analytical comparison graphs are constructed by code, adding temporal-predecessor and nearest-peer edges for representation learning.

All analytical edges use derived_* relation types and carry metadata stating they assert no affiliation, common control, transactions, or shared personnel. That metadata boundary is what prevents a nearest-peer edge from being misread as a reported relationship.

Building the analytical graph:

```bash
form990-xai build-graph \
  --filings data/refresh/filings.csv \
  --neighbors 3 \
  --output data/refresh/relations.csv
```

--neighbors 3 controls the number of nearest-peer edges per node. No similarity metric for selecting those peers is documented, so that part of peer graph construction is not reproducible from the README alone.

## pyproject.toml names the package 'esgx' for ESG reporting and lists no ML dependencies

A close reading of the repository files reveals a significant inconsistency between the README and pyproject.toml. pyproject.toml sets name = "esgx" with the description "AI for ESG Reporting: extraction, validation, and taxonomy mapping." ESG reporting has nothing to do with IRS Form 990 filings or compliance risk screening.

Python version constraints compound this gap. README badges specify Python 3.10 to 3.12. pyproject.toml sets requires-python to >=3.9.

requirements.txt and pyproject.toml list only numpy, pandas, pydantic, typer, rich, PyYAML, jinja2, regex, and pytest. None of the ML or graph ML packages needed to run Isolation Forest, GATv2, TCN, or Transformer models appears in either file. CLI entry point form990-xai used throughout the README is absent from the pyproject.toml fragment in the repository.

In practice, the pyproject.toml and the README describe two different projects. Before installing anything, verify that your local copy of pyproject.toml defines both the [dev] extras group and the form990-xai entry point.

## FORM990_ENTITY_SALT creates pseudonymous IDs and salt-change behavior is undocumented

Full IRS dataset research runs three commands in sequence: discovering archive names from the official IRS page, downloading a bounded archive, and ingesting it:

```bash
export FORM990_ENTITY_SALT='replace-with-a-long-random-study-secret'
form990-xai ingest \
  --archive data/raw/irs/2026/2026_TEOS_XML_06A.zip \
  --dataset-name irs-2026-06A \
  --output-dir data/processed/irs-2026-06A
```

FORM990_ENTITY_SALT creates stable pseudonymous person IDs. No documentation addresses what happens to existing person IDs if the salt changes mid-study, or whether the value is validated before ingestion begins. For a longitudinal study where person ID stability matters, this gap needs resolution before data collection starts.

Ingestion writes normalized filing, relation, and officer tables, plus parser diagnostics, a data-quality audit, and a manifest containing raw source hashes and normalized table fingerprints.

No GitHub releases exist, the last push was on 2026-08-05, and all files carry an MIT license. Anyone building a pipeline on this project must track commits directly, since no stable version exists to pin.

## Conclusion

Form 990 XAI Risk suits researchers and compliance teams who want a well-documented, explanation-first starting point for prioritizing Form 990 reviews and can supply their own labeled data. Skip it if you need a production-ready scoring service: the repository has no GitHub releases, the last push was on 2026-08-05, and pyproject.toml names the package 'esgx' with no ML libraries in its dependency list. Before running pip install -e '[dev]', verify that your working copy of pyproject.toml defines the [dev] extras and the form990-xai CLI entry point.

## FAQ

### What is Form 990 XAI Risk?

Form 990 XAI Risk is a research-grade Python framework for prioritizing IRS Form 990 nonprofit filings for human review using interpretable AI. It combines structured financial features, text analysis, and graph modeling with built-in explanation outputs. Scores identify records that may warrant verification, not findings of noncompliance.

### How do I install Form 990 XAI Risk?

Set up a Python virtual environment and run pip install -e '[dev]' from the repository root. Running form990-xai real-sample --output-dir artifacts/real_sample runs a smoke test against 15 organization-year records from three Washington nonprofits.

### Does Form 990 XAI Risk require an API key for ProPublica data?

No API key is required for the documented Nonprofit Explorer API v2 endpoint.

### What graph model does Form 990 XAI Risk use?

Core graph processing uses one-hop relation features from the disclosed Form 990 filing relationships. GATv2 with edge attention is the optional research extension. A separate analytical comparison graph adds derived_* edges for representation learning and must not be confused with disclosed filing relationships.

### Is Form 990 XAI Risk production-ready?

It is positioned as a research-grade, audit-first framework. pyproject.toml lists no ML dependencies despite the README describing Transformer, GNN, and TCN models, and no stable version exists to pin.

## Sources

- [Issues](https://github.com/jc2744-fintech/taxguard-xai/issues)
- [jc2744-fintech/taxguard-xai on GitHub](https://github.com/jc2744-fintech/taxguard-xai)
- [License: MIT](https://github.com/jc2744-fintech/taxguard-xai/blob/main/LICENSE)
- [README](https://github.com/jc2744-fintech/taxguard-xai/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jc2744-fintech-taxguard-xai