Analyze FEC (Federal Election Commission) campaign finance filings. Use when working with FEC filing IDs, campaign finance data, contributions, disbursements, or political committee financial reports.
This skill enables analysis of Federal Election Commission campaign finance filings.
Dependencies are automatically installed when running the script with uv run.
The first time this skill is invoked in a session, verify that uv is installed by running:
uv --version
If this command fails or uv is not found, do not proceed. Instead, inform the user that uv is required but not installed, and direct them to the installation guide:
Always start by checking the filing size:
uv run scripts/fetch_filing.py <FILING_ID> --summary-only
Based on the summary, decide how to proceed—see Handling Large Filings below for filtering and streaming strategies. Small filings can be fetched directly; large filings require pre-filtering or streaming.
Fetching data:
uv run scripts/fetch_filing.py <FILING_ID> # Full filing (small filings only)
uv run scripts/fetch_filing.py <FILING_ID> --schedule A # Only contributions
uv run scripts/fetch_filing.py <FILING_ID> --schedule B # Only disbursements
uv run scripts/fetch_filing.py <FILING_ID> --schedules A,B # Multiple schedules
The fecfile library is installed automatically by uv.
IMPORTANT: Do not guess at field names. Before referencing any field names in responses:
references/FORMS.mdreferences/SCHEDULES.mdThese files contain the authoritative field mappings. If a field name isn't documented there, verify it exists in the actual JSON output before using it.
FEC filings vary enormously in size. Small filings (like state party monthly reports) may have only a few dozen itemizations and can be used directly. However, major committees like ActBlue, WinRed, and presidential campaigns can have hundreds of thousands of itemizations in a single filing. Do not dump large filing data directly into the context window.
Before pulling full schedules, use --summary-only to assess the filing:
uv run scripts/fetch_filing.py <ID> --summary-only
The summary includes financial totals that help gauge filing size without parsing itemizations:
| Field | Description |
|---|---|
col_a_individuals_itemized | Itemized individual contributions (this period) |
col_a_total_contributions | Total contributions (this period) |
col_a_total_disbursements | Total disbursements (this period) |
col_b_individuals_itemized | Itemized individual contributions (year-to-date) |
col_b_total_contributions | Total contributions (year-to-date) |
col_b_total_disbursements | Total disbursements (year-to-date) |
These are dollar totals, not item counts, but combined with the committee name they help you decide:
If you need to verify exact counts before processing, stream with an early cutoff:
uv run scripts/fetch_filing.py <ID> --stream --schedule A | python3 -c "
import sys
count = 0
limit = 256
for line in sys.stdin:
count += 1
if count >= limit:
print(f'Schedule A: {limit}+ items (stopped counting)')
sys.exit(0)
print(f'Schedule A: {count} items')
"
If itemization counts are in the hundreds or more, you must post-filter before presenting results. Even smaller filings may benefit from post-filtering to aggregate or focus the output.
Use CLI flags to filter before data is loaded into memory:
| Flag | Effect |
|---|---|
--summary-only | Only filing summary (no itemizations) |
--schedule A | Only Schedule A (contributions) |
--schedule B | Only Schedule B (disbursements) |
--schedule C | Only Schedule C (loans) |
--schedule D | Only Schedule D (debts) |
--schedule E | Only Schedule E (independent expenditures) |
--schedules A,B | Multiple schedules (comma-separated) |
Schedules you don't request are never parsed.
Use Python/pandas to aggregate, filter, and limit results:
cat > /tmp/analysis.py << 'EOF'
# /// script
# requires-python = ">=3.9"
# dependencies = ["pandas>=2.3.0"]
# ///
import json, sys
import pandas as pd
data = json.load(sys.stdin)
df = pd.DataFrame(data.get('itemizations', {}).get('Schedule A', []))
# Aggregate and limit output
print(df.groupby('contributor_state')['contribution_amount'].agg(['count', 'sum']).sort_values('sum', ascending=False).to_string())
EOF
uv run scripts/fetch_filing.py <ID> --schedule A 2>&1 | uv run /tmp/analysis.py
For truly massive filings where even a single schedule is too large to hold in memory, use --stream to output JSONL (one JSON object per line):
uv run scripts/fetch_filing.py <ID> --stream --schedule A
Each line has the format: {"data_type": "...", "data": {...}}
How streaming works:
The producer (fetch_filing.py) outputs one record at a time without loading the full filing. A consumer script reads one line at a time and aggregates incrementally. Neither side ever holds all records in memory.
Example streaming aggregation:
uv run scripts/fetch_filing.py <ID> --stream --schedule A | python3 -c "
import json, sys
from collections import defaultdict
totals = defaultdict(float)
counts = defaultdict(int)
for line in sys.stdin:
rec = json.loads(line)
if rec['data_type'] == 'itemization':
state = rec['data'].get('contributor_state', 'Unknown')
amt = float(rec['data'].get('contribution_amount', 0))
totals[state] += amt
counts[state] += 1
for state in sorted(totals, key=lambda s: -totals[s]):
print(f'{state}: {counts[state]} contributions, \${totals[state]:,.2f}')
"
This processes hundreds of thousands of records using constant memory.
--summary-only or --schedule X, then check size--stream with inline Python consumers for constant-memory processing.head(), .nlargest(), .nsmallest() to cap resultsFiling IDs can be found via:
When analyzing FEC filings:
See FORMS.md for detailed guidance on:
See SCHEDULES.md for detailed field mappings for:
Check the amendment_indicator field:
A = Standard AmendmentT = Termination AmendmentIf it's an amendment, look for previous_report_amendment_indicator for the original filing ID.
Use coverage_from_date and coverage_through_date fields.
For financial filings (F3, F3P, F3X):
col_a_total_receiptscol_a_total_disbursementscol_a_cash_on_hand_close_of_periodcol_a_debts_to and col_a_debts_byOnce you have filing data, you can answer questions like: