COLA — Cost of Living Affordability Assistant

A submission to the AI for Social Good Initiative (May 2026)

COLA is an AI-powered cost-of-living assistant for U.S. households. It forecasts regional rent trends with calibrated uncertainty, scores affordability for a given household profile with a transparent per-component breakdown, and flags metros where rent growth is outpacing local wages.

The project's most important contribution is a built-in fairness audit that publicly reports where ZIP-code-based recommendations correlate with demographic patterns — surfacing rather than hiding the residual signal of historical segregation.

---

Quickstart

pip install -r requirements.txt

python -m src.data.build_features         # builds the feature store
python -m src.models.forecasting           # generates rent forecasts
python -m src.models.displacement          # generates displacement signals
python -m src.evaluation.backtest          # writes reports/backtest_results.csv
python -m src.evaluation.fairness_audit    # writes reports/fairness_audit.csv
pytest tests/                              # 10 tests, all passing

streamlit run src/app/main.py              # launches the demo at localhost:8501

Key results

• Forecast accuracy: ensemble beats seasonal-naive baseline by 62% MAPE.
• Displacement detection: correctly classifies the 2022 rent boom as severe in Austin, Atlanta, LA, NYC.
• Fairness audit: honestly reports failure of the 0.05 disparity target — surfacing redlining's residual signal rather than hiding it.

Documentation

The 9-phase development trail required by the AI for Social Good Initiative master prompt:

Phase	Document	Status
1. Problem Discovery & Research	docs/phase_1_problem_discovery.md	✅
2. Ideation & System Design	docs/phase_2_ideation_and_design.md	✅
3. Technical Planning	docs/phase_3_technical_planning.md	✅
4–7. Data, Models, UX, Evaluation	docs/phases_4_7_execution_log.md	✅
8. Social Impact Analysis	docs/phase_8_social_impact.md	✅
9. Final Deliverables	docs/phase_9_final_report.md	✅

The required AI transparency log: ai_logs/ai_usage_log.md. Submission answers (50/100/100-word): docs/submission_answers.md. Demo video script: docs/video_script.md.

Repository layout

cola/
├── README.md
├── requirements.txt
├── config/msas.yaml
├── docs/                      # phase-by-phase documentation
├── src/
│   ├── data/build_features.py # feature store builder
│   ├── models/                # forecasting, affordability, displacement
│   ├── evaluation/            # backtest + fairness audit
│   └── app/main.py            # Streamlit UI
├── data/processed/            # parquet feature store
├── tests/                     # pytest suite
├── reports/                   # backtest + fairness audit outputs
└── ai_logs/                   # required AI usage log

Honest limitations

This is a 1-day vertical-slice prototype, not a production system. Specifically:

• 5 reference MSAs with synthetic data calibrated to published figures (live-API loaders are written but not used in the demo).
• The affordability scorer is rule-based, not deep ML. We judge transparency to be more important than a marginal accuracy gain.
• The fairness audit fails the 0.05 disparity target. This is the right finding for the audit to surface; it tells us that ZIP code carries demographic signal even with race excluded as a feature.
• No formal WCAG accessibility audit. No NL/chat interface.

A longer-running follow-up would expand MSA coverage, swap in live API loaders, add the LightGBM affordability refinement, and put guardrails in the recommendation layer to address the fairness findings.

Data sources

All free and public. Cited in docs/phase_1_problem_discovery.md §1.7:

• HUD Fair Market Rents API
• Zillow Observed Rent Index (ZORI)
• U.S. Bureau of Labor Statistics (QCEW, CPI, ECI, Real Earnings)
• U.S. Census Bureau (ACS 5-year)
• USDA Thrifty Food Plan
• U.S. Energy Information Administration (electricity prices)

License

MIT. The project is a research prototype and is intentionally non-commercial.