nmtc-application-builder 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. nmtc_application_builder-1.0.0/PKG-INFO +265 -0
  2. nmtc_application_builder-1.0.0/README.md +213 -0
  3. nmtc_application_builder-1.0.0/nmtc_application_builder.egg-info/PKG-INFO +265 -0
  4. nmtc_application_builder-1.0.0/nmtc_application_builder.egg-info/SOURCES.txt +67 -0
  5. nmtc_application_builder-1.0.0/nmtc_application_builder.egg-info/dependency_links.txt +1 -0
  6. nmtc_application_builder-1.0.0/nmtc_application_builder.egg-info/entry_points.txt +2 -0
  7. nmtc_application_builder-1.0.0/nmtc_application_builder.egg-info/requires.txt +35 -0
  8. nmtc_application_builder-1.0.0/nmtc_application_builder.egg-info/top_level.txt +1 -0
  9. nmtc_application_builder-1.0.0/nmtcapp/__init__.py +66 -0
  10. nmtc_application_builder-1.0.0/nmtcapp/cli.py +309 -0
  11. nmtc_application_builder-1.0.0/nmtcapp/core/__init__.py +5 -0
  12. nmtc_application_builder-1.0.0/nmtcapp/core/application.py +439 -0
  13. nmtc_application_builder-1.0.0/nmtcapp/core/cde.py +148 -0
  14. nmtc_application_builder-1.0.0/nmtcapp/core/pipeline.py +473 -0
  15. nmtc_application_builder-1.0.0/nmtcapp/data/__init__.py +29 -0
  16. nmtc_application_builder-1.0.0/nmtcapp/data/benchmark_thresholds.py +108 -0
  17. nmtc_application_builder-1.0.0/nmtcapp/data/historical_awards.py +275 -0
  18. nmtc_application_builder-1.0.0/nmtcapp/data/schema.py +140 -0
  19. nmtc_application_builder-1.0.0/nmtcapp/integrations/__init__.py +13 -0
  20. nmtc_application_builder-1.0.0/nmtcapp/integrations/cdfidata_adapter.py +97 -0
  21. nmtc_application_builder-1.0.0/nmtcapp/integrations/hmda_adapter.py +94 -0
  22. nmtc_application_builder-1.0.0/nmtcapp/integrations/impact_adapter.py +104 -0
  23. nmtc_application_builder-1.0.0/nmtcapp/integrations/nmtc_calc_adapter.py +128 -0
  24. nmtc_application_builder-1.0.0/nmtcapp/integrations/nmtc_mapper_adapter.py +122 -0
  25. nmtc_application_builder-1.0.0/nmtcapp/intelligence/__init__.py +26 -0
  26. nmtc_application_builder-1.0.0/nmtcapp/intelligence/benchmarks.py +326 -0
  27. nmtc_application_builder-1.0.0/nmtcapp/intelligence/distress_analysis.py +117 -0
  28. nmtc_application_builder-1.0.0/nmtcapp/intelligence/geographic_analysis.py +126 -0
  29. nmtc_application_builder-1.0.0/nmtcapp/intelligence/impact_aggregator.py +94 -0
  30. nmtc_application_builder-1.0.0/nmtcapp/intelligence/pattern_analysis.py +188 -0
  31. nmtc_application_builder-1.0.0/nmtcapp/intelligence/pipeline_analyzer.py +183 -0
  32. nmtc_application_builder-1.0.0/nmtcapp/intelligence/recommendations.py +517 -0
  33. nmtc_application_builder-1.0.0/nmtcapp/intelligence/sector_analysis.py +122 -0
  34. nmtc_application_builder-1.0.0/nmtcapp/intelligence/win_probability.py +293 -0
  35. nmtc_application_builder-1.0.0/nmtcapp/optimizer/__init__.py +8 -0
  36. nmtc_application_builder-1.0.0/nmtcapp/optimizer/candidate_pool.py +119 -0
  37. nmtc_application_builder-1.0.0/nmtcapp/optimizer/constraints.py +93 -0
  38. nmtc_application_builder-1.0.0/nmtcapp/optimizer/objectives.py +222 -0
  39. nmtc_application_builder-1.0.0/nmtcapp/optimizer/pipeline_optimizer.py +313 -0
  40. nmtc_application_builder-1.0.0/nmtcapp/renderers/__init__.py +24 -0
  41. nmtc_application_builder-1.0.0/nmtcapp/renderers/_word_helpers.py +207 -0
  42. nmtc_application_builder-1.0.0/nmtcapp/renderers/excel_builder.py +549 -0
  43. nmtc_application_builder-1.0.0/nmtcapp/renderers/markdown_builder.py +178 -0
  44. nmtc_application_builder-1.0.0/nmtcapp/renderers/pdf_builder.py +668 -0
  45. nmtc_application_builder-1.0.0/nmtcapp/renderers/styles.py +142 -0
  46. nmtc_application_builder-1.0.0/nmtcapp/renderers/word_builder.py +470 -0
  47. nmtc_application_builder-1.0.0/nmtcapp/sections/__init__.py +22 -0
  48. nmtc_application_builder-1.0.0/nmtcapp/sections/base.py +112 -0
  49. nmtc_application_builder-1.0.0/nmtcapp/sections/section_a_business.py +93 -0
  50. nmtc_application_builder-1.0.0/nmtcapp/sections/section_b_outcomes.py +93 -0
  51. nmtc_application_builder-1.0.0/nmtcapp/sections/section_c_management.py +82 -0
  52. nmtc_application_builder-1.0.0/nmtcapp/sections/section_d_capitalization.py +83 -0
  53. nmtc_application_builder-1.0.0/nmtcapp/sections/section_e_prior_awards.py +88 -0
  54. nmtc_application_builder-1.0.0/nmtcapp/tables/__init__.py +15 -0
  55. nmtc_application_builder-1.0.0/nmtcapp/tables/distress_table.py +108 -0
  56. nmtc_application_builder-1.0.0/nmtcapp/tables/geographic_table.py +75 -0
  57. nmtc_application_builder-1.0.0/nmtcapp/tables/impact_table.py +123 -0
  58. nmtc_application_builder-1.0.0/nmtcapp/tables/investor_table.py +131 -0
  59. nmtc_application_builder-1.0.0/nmtcapp/tables/pipeline_table.py +162 -0
  60. nmtc_application_builder-1.0.0/nmtcapp/tables/track_record_table.py +65 -0
  61. nmtc_application_builder-1.0.0/nmtcapp/validation/__init__.py +12 -0
  62. nmtc_application_builder-1.0.0/nmtcapp/validation/completeness_check.py +83 -0
  63. nmtc_application_builder-1.0.0/nmtcapp/validation/consistency_check.py +129 -0
  64. nmtc_application_builder-1.0.0/nmtcapp/validation/eligibility_check.py +77 -0
  65. nmtc_application_builder-1.0.0/nmtcapp/validation/readiness_score.py +309 -0
  66. nmtc_application_builder-1.0.0/nmtcapp/visualization/__init__.py +16 -0
  67. nmtc_application_builder-1.0.0/nmtcapp/visualization/maps.py +726 -0
  68. nmtc_application_builder-1.0.0/pyproject.toml +83 -0
  69. nmtc_application_builder-1.0.0/setup.cfg +4 -0
@@ -0,0 +1,265 @@
1
+ Metadata-Version: 2.4
2
+ Name: nmtc-application-builder
3
+ Version: 1.0.0
4
+ Summary: Flagship NMTC application intelligence platform — pipeline analysis, eligibility validation, readiness scoring, and visualization for CDEs
5
+ Author-email: Jay Patel <thejaypatel1511@gmail.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Jaypatel1511/nmtc-application-builder
8
+ Project-URL: Repository, https://github.com/Jaypatel1511/nmtc-application-builder
9
+ Project-URL: Documentation, https://github.com/Jaypatel1511/nmtc-application-builder#readme
10
+ Project-URL: Issue Tracker, https://github.com/Jaypatel1511/nmtc-application-builder/issues
11
+ Keywords: nmtc,cdfi,community-development,new-markets-tax-credit,pipeline
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Financial and Insurance Industry
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Office/Business :: Financial
20
+ Classifier: Topic :: Scientific/Engineering :: GIS
21
+ Requires-Python: >=3.9
22
+ Description-Content-Type: text/markdown
23
+ Requires-Dist: pandas>=1.3
24
+ Requires-Dist: numpy>=1.21
25
+ Requires-Dist: pyyaml>=6.0
26
+ Requires-Dist: nmtc-mapper>=0.3.0
27
+ Requires-Dist: nmtc-calc>=0.1.0
28
+ Requires-Dist: hmda-analyzer>=0.1.0
29
+ Requires-Dist: cdfidata>=0.1.7
30
+ Requires-Dist: impact-ledger>=0.2.0
31
+ Requires-Dist: cra-scraper>=0.1.0
32
+ Provides-Extra: word
33
+ Requires-Dist: python-docx>=1.1.0; extra == "word"
34
+ Provides-Extra: excel
35
+ Requires-Dist: openpyxl>=3.0.9; extra == "excel"
36
+ Provides-Extra: pdf
37
+ Requires-Dist: reportlab>=4.0.0; extra == "pdf"
38
+ Provides-Extra: viz
39
+ Requires-Dist: matplotlib>=3.7; extra == "viz"
40
+ Provides-Extra: output
41
+ Requires-Dist: python-docx>=1.1.0; extra == "output"
42
+ Requires-Dist: openpyxl>=3.0.9; extra == "output"
43
+ Requires-Dist: reportlab>=4.0.0; extra == "output"
44
+ Provides-Extra: dev
45
+ Requires-Dist: pytest>=7.0; extra == "dev"
46
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
47
+ Requires-Dist: jupyter>=1.0; extra == "dev"
48
+ Requires-Dist: python-docx>=1.1.0; extra == "dev"
49
+ Requires-Dist: openpyxl>=3.0.9; extra == "dev"
50
+ Requires-Dist: reportlab>=4.0.0; extra == "dev"
51
+ Requires-Dist: matplotlib>=3.7; extra == "dev"
52
+
53
+ # NMTC Application Builder
54
+
55
+ **The open-source intelligence platform for competitive CDFI Fund applications.**
56
+
57
+ [![PyPI version](https://img.shields.io/pypi/v/nmtc-application-builder.svg)](https://pypi.org/project/nmtc-application-builder/)
58
+ [![Python](https://img.shields.io/pypi/pyversions/nmtc-application-builder.svg)](https://pypi.org/project/nmtc-application-builder/)
59
+ [![Tests](https://img.shields.io/badge/tests-544%20passing-brightgreen.svg)](https://github.com/Jaypatel1511/nmtc-application-builder/actions)
60
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
61
+ [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://jaypatel1511.github.io/nmtc-application-builder/)
62
+
63
+ **[Documentation](https://jaypatel1511.github.io/nmtc-application-builder/) · [Streamlit Demo](https://nmtc-application-builder.streamlit.app) · [Examples](examples/) · [PyPI](https://pypi.org/project/nmtc-application-builder/)**
64
+
65
+ ---
66
+
67
+ CDEs spend months preparing NMTC allocation applications without knowing how their pipeline compares to historical winners. This library changes that — scoring your pipeline against five years of CDFI Fund award data in seconds, generating competition-ready document drafts automatically, and telling you exactly what to fix.
68
+
69
+ ```python
70
+ app = Application(cde=CDEProfile.sample(), requested_allocation=65_000_000)
71
+ app.add_pipeline(Pipeline.from_csv("pipeline.csv"))
72
+ score = app.score_win_probability()
73
+ print(f"Alignment: {score.composite_score:.0f}/100 [{score.competitive_tier}]")
74
+ # → Alignment: 66/100 [competitive]
75
+ paths = app.generate("./drafts/")
76
+ # → Word, Excel, PDF, and Markdown application package ready in ./drafts/
77
+ ```
78
+
79
+ ---
80
+
81
+ ## The Problem
82
+
83
+ CDE teams preparing NMTC allocation applications work blind. They spend weeks manually assembling pipeline data in Excel, draft narrative sections without knowing how their distress concentration or geographic diversity compares to past winners, and submit applications with no objective measure of competitiveness. The CDFI Fund receives 280–340 applications per round with a ~35% acceptance rate — yet most CDEs have no systematic way to benchmark their position before the deadline.
84
+
85
+ ## The Solution
86
+
87
+ `nmtc-application-builder` gives CDEs a programmatic intelligence layer built on five years of CDFI Fund public award data. Load your pipeline from CSV, run `analyze()`, and immediately see where you stand on every dimension the CDFI Fund scores: distress concentration, geographic diversity, sector mix, impact intensity, and pipeline quality. Get specific, numbered recommendations. Optimize your project subset automatically. Generate the Word, Excel, PDF, and Markdown drafts that go directly into your application package.
88
+
89
+ ---
90
+
91
+ ## Quickstart
92
+
93
+ ```bash
94
+ pip install nmtc-application-builder[output,viz]
95
+ ```
96
+
97
+ ```python
98
+ from nmtcapp import Application, CDEProfile, Pipeline
99
+ from nmtcapp.optimizer import OptimizationConstraints
100
+
101
+ # 1. Define your CDE
102
+ cde = CDEProfile.sample() # or CDEProfile.from_yaml("cde.yaml")
103
+
104
+ # 2. Load your pipeline
105
+ pipeline = Pipeline.from_csv("pipeline.csv") # or Pipeline.sample(n=20) for demo
106
+
107
+ # 3. Analyze
108
+ app = Application(cde=cde, requested_allocation=65_000_000)
109
+ app.add_pipeline(pipeline)
110
+ analysis = app.analyze()
111
+ analysis.summary()
112
+
113
+ # 4. Score alignment with historical winners
114
+ score = app.score_win_probability() # alignment score, not win probability
115
+ print(f"{score.composite_score:.0f}/100 [{score.competitive_tier}]")
116
+
117
+ # 5. Get quantified recommendations
118
+ recs = app.recommendations()
119
+ print(recs.summary())
120
+
121
+ # 6. Optimize your pipeline subset
122
+ result = app.optimize_pipeline(
123
+ constraints=OptimizationConstraints(max_total_qei=65_000_000, min_states=5)
124
+ )
125
+ print(f"Score: {result.alignment_score_before*100:.0f} → {result.alignment_score_after*100:.0f}")
126
+
127
+ # 7. Generate the full application package
128
+ paths = app.generate("./drafts/")
129
+ ```
130
+
131
+ Or bootstrap a starter project in 60 seconds:
132
+
133
+ ```bash
134
+ nmtcapp init my-application/
135
+ cd my-application/
136
+ jupyter notebook analysis.ipynb
137
+ ```
138
+
139
+ ---
140
+
141
+ ## What It Does
142
+
143
+ - **Pipeline ingestion** — Load from CSV or build programmatically; validates all required fields
144
+ - **NMTC eligibility enrichment** — Census tract lookup, distress level classification (deep / severe / LIC), opportunity zone and native area flags
145
+ - **Distress concentration analysis** — Deep/severe QEI percentage vs. CDFI Fund competitive thresholds (target: ≥75%)
146
+ - **Geographic diversity scoring** — State count, HHI concentration index, urban/rural split
147
+ - **Sector mix analysis** — Shannon entropy, dominant sector, high-priority sector alignment
148
+ - **Impact projection** — Jobs per $MM QEI benchmarked against historical winner distributions
149
+ - **Win alignment scoring** — 5-dimensional score (0–100) against CY2020–2024 winner patterns
150
+ - **Quantified recommendations** — Specific, numbered improvement actions per dimension with estimated score impact
151
+ - **Pipeline optimizer** — Greedy + local-search selects the best project subset for your target budget
152
+ - **Output generation** — Word, Excel, PDF, and Markdown application drafts in one call
153
+ - **Geographic visualizations** — Publication-quality pipeline maps, radar charts, and benchmark plots at 300 DPI
154
+ - **CLI** — `nmtcapp init` / `nmtcapp analyze` for quick command-line workflows
155
+
156
+ > **Methodology note:** Alignment scores measure similarity to historical winner patterns — they are not win probabilities. The CDFI Fund does not publish rejected application data, so a true probability model cannot be built from public information alone.
157
+
158
+ ---
159
+
160
+ ## Sample Output Gallery
161
+
162
+ Generated outputs are in [`examples/sample_output/`](examples/sample_output/) — Word, Excel, PDF, and Markdown for a realistic sample CDE application.
163
+
164
+ The three example notebooks tell a complete story:
165
+
166
+ | Notebook | What it demonstrates |
167
+ |---|---|
168
+ | [01_quickstart.ipynb](examples/01_quickstart.ipynb) | End-to-end workflow in 10 minutes |
169
+ | [02_full_application_walkthrough.ipynb](examples/02_full_application_walkthrough.ipynb) | Complete document generation |
170
+ | [03_intelligence_and_optimization.ipynb](examples/03_intelligence_and_optimization.ipynb) | **5.5 → 65.9 → 79.1/100** — weak→competitive pipeline transformation |
171
+
172
+ ---
173
+
174
+ ## Architecture
175
+
176
+ ```
177
+ nmtc-application-builder/
178
+ ├── nmtcapp/
179
+ │ ├── core/ Application · CDEProfile · Pipeline
180
+ │ ├── intelligence/ PipelineAnalyzer · WinProbabilityModel · RecommendationEngine
181
+ │ ├── optimizer/ PipelineOptimizer · CandidatePool · Objectives
182
+ │ ├── validation/ EligibilityCheck · CompletenessCheck · ReadinessScore
183
+ │ ├── integrations/ nmtc-mapper · nmtc-calc · cdfidata · impact-ledger
184
+ │ ├── visualization/ pipeline maps · distress heatmap · radar · alignment charts
185
+ │ ├── renderers/ Word · Excel · PDF · Markdown builders
186
+ │ ├── data/ historical awards · benchmark thresholds · schema
187
+ │ └── cli.py nmtcapp init / analyze / version
188
+ ├── examples/ 3 executed Jupyter notebooks + sample output
189
+ ├── streamlit_app/ Interactive web demo (4 pages)
190
+ ├── templates/ pipeline_template.csv · cde_profile_template.yaml
191
+ └── docs/ MkDocs documentation site
192
+ ```
193
+
194
+ ### Built on the Open-Source CDFI Analytics Stack
195
+
196
+ This library integrates six companion libraries built for the CDFI space:
197
+
198
+ | Library | Role in this project |
199
+ |---|---|
200
+ | `nmtc-mapper` | Census tract geocoding and eligibility classification (deep / severe / LIC) |
201
+ | `nmtc-calc` | NMTC leveraged deal economics (QEI → NMTCs → investor equity) |
202
+ | `cdfidata` | CDFI Fund TLR/CLR/Awards ETL and dataset loader |
203
+ | `impact-ledger` | Portfolio-level impact tracking by sector |
204
+ | `hmda-analyzer` | HMDA CRA assessment data integration |
205
+ | `cra-scraper` | Community Reinvestment Act data extraction |
206
+
207
+ ---
208
+
209
+ ## Use Cases
210
+
211
+ **CDE application teams** — Run `analyze()` on your pipeline weekly during application season. Watch your readiness score improve as you add projects and address recommendations. Generate the first draft of every section automatically.
212
+
213
+ **CDFI consultants** — Drop a client's pipeline CSV in and produce a competitive benchmark report in minutes. Show exactly where they stand vs. historical winners before committing to a full engagement.
214
+
215
+ **Researchers and policy analysts** — Query the embedded CY2020–2024 CDFI Fund award statistics. Study what differentiates winning applications across distress concentration, geographic reach, and impact intensity.
216
+
217
+ **CDEs evaluating pipeline strategy** — Use the optimizer to understand what subset of your project pipeline maximizes competitive alignment given a target allocation amount and diversity constraints.
218
+
219
+ ---
220
+
221
+ ## Limitations & Honest Disclosures
222
+
223
+ - **Not a win probability model.** Alignment score ≠ probability of receiving an allocation. The CDFI Fund does not publish rejected application data, so a calibrated probability model cannot be built from public information alone.
224
+ - **Historical patterns, not current NOFA.** Benchmarks derive from CY2020–2024 award data. CDFI Fund priorities shift — always check the current NOFA for updated criteria.
225
+ - **Approximate geographic data.** Pipeline maps use state centroids, not actual project addresses. Eligibility enrichment uses `nmtc-mapper` and falls back to embedded sample data when offline.
226
+ - **Not a substitute for expert review.** Always have a qualified CDFI practitioner or attorney review application materials before submission.
227
+ - **No investor or underwriting analysis.** This library covers competitive positioning, not deal structuring, investor sourcing, or legal compliance.
228
+
229
+ ---
230
+
231
+ ## Documentation
232
+
233
+ Full documentation at **[jaypatel1511.github.io/nmtc-application-builder](https://jaypatel1511.github.io/nmtc-application-builder/)**
234
+
235
+ - [Installation guide](https://jaypatel1511.github.io/nmtc-application-builder/installation/)
236
+ - [60-second quickstart](https://jaypatel1511.github.io/nmtc-application-builder/quickstart/)
237
+ - [Pipeline analysis workflow](https://jaypatel1511.github.io/nmtc-application-builder/workflow/pipeline-analysis/)
238
+ - [Win alignment scoring & methodology](https://jaypatel1511.github.io/nmtc-application-builder/workflow/win-alignment/)
239
+ - [Full API reference](https://jaypatel1511.github.io/nmtc-application-builder/reference/api/)
240
+ - [Honest limitations](https://jaypatel1511.github.io/nmtc-application-builder/about/limitations/)
241
+
242
+ ---
243
+
244
+ ## Contributing
245
+
246
+ Contributions welcome — bug fixes, additional data sources, visualization improvements, and documentation all help.
247
+
248
+ ```bash
249
+ git clone https://github.com/Jaypatel1511/nmtc-application-builder.git
250
+ cd nmtc-application-builder
251
+ pip install -e ".[dev]"
252
+ PYTHONPATH=. pytest tests/ -v # 544 tests, should all pass
253
+ ```
254
+
255
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on pull requests, code style, and issue reporting.
256
+
257
+ ---
258
+
259
+ ## License
260
+
261
+ MIT License — see [LICENSE](LICENSE) for details.
262
+
263
+ ---
264
+
265
+ *Built by [Jay Patel](https://github.com/Jaypatel1511) as part of an open-source CDFI analytics portfolio. Not affiliated with the CDFI Fund or the US Treasury.*
@@ -0,0 +1,213 @@
1
+ # NMTC Application Builder
2
+
3
+ **The open-source intelligence platform for competitive CDFI Fund applications.**
4
+
5
+ [![PyPI version](https://img.shields.io/pypi/v/nmtc-application-builder.svg)](https://pypi.org/project/nmtc-application-builder/)
6
+ [![Python](https://img.shields.io/pypi/pyversions/nmtc-application-builder.svg)](https://pypi.org/project/nmtc-application-builder/)
7
+ [![Tests](https://img.shields.io/badge/tests-544%20passing-brightgreen.svg)](https://github.com/Jaypatel1511/nmtc-application-builder/actions)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
+ [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://jaypatel1511.github.io/nmtc-application-builder/)
10
+
11
+ **[Documentation](https://jaypatel1511.github.io/nmtc-application-builder/) · [Streamlit Demo](https://nmtc-application-builder.streamlit.app) · [Examples](examples/) · [PyPI](https://pypi.org/project/nmtc-application-builder/)**
12
+
13
+ ---
14
+
15
+ CDEs spend months preparing NMTC allocation applications without knowing how their pipeline compares to historical winners. This library changes that — scoring your pipeline against five years of CDFI Fund award data in seconds, generating competition-ready document drafts automatically, and telling you exactly what to fix.
16
+
17
+ ```python
18
+ app = Application(cde=CDEProfile.sample(), requested_allocation=65_000_000)
19
+ app.add_pipeline(Pipeline.from_csv("pipeline.csv"))
20
+ score = app.score_win_probability()
21
+ print(f"Alignment: {score.composite_score:.0f}/100 [{score.competitive_tier}]")
22
+ # → Alignment: 66/100 [competitive]
23
+ paths = app.generate("./drafts/")
24
+ # → Word, Excel, PDF, and Markdown application package ready in ./drafts/
25
+ ```
26
+
27
+ ---
28
+
29
+ ## The Problem
30
+
31
+ CDE teams preparing NMTC allocation applications work blind. They spend weeks manually assembling pipeline data in Excel, draft narrative sections without knowing how their distress concentration or geographic diversity compares to past winners, and submit applications with no objective measure of competitiveness. The CDFI Fund receives 280–340 applications per round with a ~35% acceptance rate — yet most CDEs have no systematic way to benchmark their position before the deadline.
32
+
33
+ ## The Solution
34
+
35
+ `nmtc-application-builder` gives CDEs a programmatic intelligence layer built on five years of CDFI Fund public award data. Load your pipeline from CSV, run `analyze()`, and immediately see where you stand on every dimension the CDFI Fund scores: distress concentration, geographic diversity, sector mix, impact intensity, and pipeline quality. Get specific, numbered recommendations. Optimize your project subset automatically. Generate the Word, Excel, PDF, and Markdown drafts that go directly into your application package.
36
+
37
+ ---
38
+
39
+ ## Quickstart
40
+
41
+ ```bash
42
+ pip install nmtc-application-builder[output,viz]
43
+ ```
44
+
45
+ ```python
46
+ from nmtcapp import Application, CDEProfile, Pipeline
47
+ from nmtcapp.optimizer import OptimizationConstraints
48
+
49
+ # 1. Define your CDE
50
+ cde = CDEProfile.sample() # or CDEProfile.from_yaml("cde.yaml")
51
+
52
+ # 2. Load your pipeline
53
+ pipeline = Pipeline.from_csv("pipeline.csv") # or Pipeline.sample(n=20) for demo
54
+
55
+ # 3. Analyze
56
+ app = Application(cde=cde, requested_allocation=65_000_000)
57
+ app.add_pipeline(pipeline)
58
+ analysis = app.analyze()
59
+ analysis.summary()
60
+
61
+ # 4. Score alignment with historical winners
62
+ score = app.score_win_probability() # alignment score, not win probability
63
+ print(f"{score.composite_score:.0f}/100 [{score.competitive_tier}]")
64
+
65
+ # 5. Get quantified recommendations
66
+ recs = app.recommendations()
67
+ print(recs.summary())
68
+
69
+ # 6. Optimize your pipeline subset
70
+ result = app.optimize_pipeline(
71
+ constraints=OptimizationConstraints(max_total_qei=65_000_000, min_states=5)
72
+ )
73
+ print(f"Score: {result.alignment_score_before*100:.0f} → {result.alignment_score_after*100:.0f}")
74
+
75
+ # 7. Generate the full application package
76
+ paths = app.generate("./drafts/")
77
+ ```
78
+
79
+ Or bootstrap a starter project in 60 seconds:
80
+
81
+ ```bash
82
+ nmtcapp init my-application/
83
+ cd my-application/
84
+ jupyter notebook analysis.ipynb
85
+ ```
86
+
87
+ ---
88
+
89
+ ## What It Does
90
+
91
+ - **Pipeline ingestion** — Load from CSV or build programmatically; validates all required fields
92
+ - **NMTC eligibility enrichment** — Census tract lookup, distress level classification (deep / severe / LIC), opportunity zone and native area flags
93
+ - **Distress concentration analysis** — Deep/severe QEI percentage vs. CDFI Fund competitive thresholds (target: ≥75%)
94
+ - **Geographic diversity scoring** — State count, HHI concentration index, urban/rural split
95
+ - **Sector mix analysis** — Shannon entropy, dominant sector, high-priority sector alignment
96
+ - **Impact projection** — Jobs per $MM QEI benchmarked against historical winner distributions
97
+ - **Win alignment scoring** — 5-dimensional score (0–100) against CY2020–2024 winner patterns
98
+ - **Quantified recommendations** — Specific, numbered improvement actions per dimension with estimated score impact
99
+ - **Pipeline optimizer** — Greedy + local-search selects the best project subset for your target budget
100
+ - **Output generation** — Word, Excel, PDF, and Markdown application drafts in one call
101
+ - **Geographic visualizations** — Publication-quality pipeline maps, radar charts, and benchmark plots at 300 DPI
102
+ - **CLI** — `nmtcapp init` / `nmtcapp analyze` for quick command-line workflows
103
+
104
+ > **Methodology note:** Alignment scores measure similarity to historical winner patterns — they are not win probabilities. The CDFI Fund does not publish rejected application data, so a true probability model cannot be built from public information alone.
105
+
106
+ ---
107
+
108
+ ## Sample Output Gallery
109
+
110
+ Generated outputs are in [`examples/sample_output/`](examples/sample_output/) — Word, Excel, PDF, and Markdown for a realistic sample CDE application.
111
+
112
+ The three example notebooks tell a complete story:
113
+
114
+ | Notebook | What it demonstrates |
115
+ |---|---|
116
+ | [01_quickstart.ipynb](examples/01_quickstart.ipynb) | End-to-end workflow in 10 minutes |
117
+ | [02_full_application_walkthrough.ipynb](examples/02_full_application_walkthrough.ipynb) | Complete document generation |
118
+ | [03_intelligence_and_optimization.ipynb](examples/03_intelligence_and_optimization.ipynb) | **5.5 → 65.9 → 79.1/100** — weak→competitive pipeline transformation |
119
+
120
+ ---
121
+
122
+ ## Architecture
123
+
124
+ ```
125
+ nmtc-application-builder/
126
+ ├── nmtcapp/
127
+ │ ├── core/ Application · CDEProfile · Pipeline
128
+ │ ├── intelligence/ PipelineAnalyzer · WinProbabilityModel · RecommendationEngine
129
+ │ ├── optimizer/ PipelineOptimizer · CandidatePool · Objectives
130
+ │ ├── validation/ EligibilityCheck · CompletenessCheck · ReadinessScore
131
+ │ ├── integrations/ nmtc-mapper · nmtc-calc · cdfidata · impact-ledger
132
+ │ ├── visualization/ pipeline maps · distress heatmap · radar · alignment charts
133
+ │ ├── renderers/ Word · Excel · PDF · Markdown builders
134
+ │ ├── data/ historical awards · benchmark thresholds · schema
135
+ │ └── cli.py nmtcapp init / analyze / version
136
+ ├── examples/ 3 executed Jupyter notebooks + sample output
137
+ ├── streamlit_app/ Interactive web demo (4 pages)
138
+ ├── templates/ pipeline_template.csv · cde_profile_template.yaml
139
+ └── docs/ MkDocs documentation site
140
+ ```
141
+
142
+ ### Built on the Open-Source CDFI Analytics Stack
143
+
144
+ This library integrates six companion libraries built for the CDFI space:
145
+
146
+ | Library | Role in this project |
147
+ |---|---|
148
+ | `nmtc-mapper` | Census tract geocoding and eligibility classification (deep / severe / LIC) |
149
+ | `nmtc-calc` | NMTC leveraged deal economics (QEI → NMTCs → investor equity) |
150
+ | `cdfidata` | CDFI Fund TLR/CLR/Awards ETL and dataset loader |
151
+ | `impact-ledger` | Portfolio-level impact tracking by sector |
152
+ | `hmda-analyzer` | HMDA CRA assessment data integration |
153
+ | `cra-scraper` | Community Reinvestment Act data extraction |
154
+
155
+ ---
156
+
157
+ ## Use Cases
158
+
159
+ **CDE application teams** — Run `analyze()` on your pipeline weekly during application season. Watch your readiness score improve as you add projects and address recommendations. Generate the first draft of every section automatically.
160
+
161
+ **CDFI consultants** — Drop a client's pipeline CSV in and produce a competitive benchmark report in minutes. Show exactly where they stand vs. historical winners before committing to a full engagement.
162
+
163
+ **Researchers and policy analysts** — Query the embedded CY2020–2024 CDFI Fund award statistics. Study what differentiates winning applications across distress concentration, geographic reach, and impact intensity.
164
+
165
+ **CDEs evaluating pipeline strategy** — Use the optimizer to understand what subset of your project pipeline maximizes competitive alignment given a target allocation amount and diversity constraints.
166
+
167
+ ---
168
+
169
+ ## Limitations & Honest Disclosures
170
+
171
+ - **Not a win probability model.** Alignment score ≠ probability of receiving an allocation. The CDFI Fund does not publish rejected application data, so a calibrated probability model cannot be built from public information alone.
172
+ - **Historical patterns, not current NOFA.** Benchmarks derive from CY2020–2024 award data. CDFI Fund priorities shift — always check the current NOFA for updated criteria.
173
+ - **Approximate geographic data.** Pipeline maps use state centroids, not actual project addresses. Eligibility enrichment uses `nmtc-mapper` and falls back to embedded sample data when offline.
174
+ - **Not a substitute for expert review.** Always have a qualified CDFI practitioner or attorney review application materials before submission.
175
+ - **No investor or underwriting analysis.** This library covers competitive positioning, not deal structuring, investor sourcing, or legal compliance.
176
+
177
+ ---
178
+
179
+ ## Documentation
180
+
181
+ Full documentation at **[jaypatel1511.github.io/nmtc-application-builder](https://jaypatel1511.github.io/nmtc-application-builder/)**
182
+
183
+ - [Installation guide](https://jaypatel1511.github.io/nmtc-application-builder/installation/)
184
+ - [60-second quickstart](https://jaypatel1511.github.io/nmtc-application-builder/quickstart/)
185
+ - [Pipeline analysis workflow](https://jaypatel1511.github.io/nmtc-application-builder/workflow/pipeline-analysis/)
186
+ - [Win alignment scoring & methodology](https://jaypatel1511.github.io/nmtc-application-builder/workflow/win-alignment/)
187
+ - [Full API reference](https://jaypatel1511.github.io/nmtc-application-builder/reference/api/)
188
+ - [Honest limitations](https://jaypatel1511.github.io/nmtc-application-builder/about/limitations/)
189
+
190
+ ---
191
+
192
+ ## Contributing
193
+
194
+ Contributions welcome — bug fixes, additional data sources, visualization improvements, and documentation all help.
195
+
196
+ ```bash
197
+ git clone https://github.com/Jaypatel1511/nmtc-application-builder.git
198
+ cd nmtc-application-builder
199
+ pip install -e ".[dev]"
200
+ PYTHONPATH=. pytest tests/ -v # 544 tests, should all pass
201
+ ```
202
+
203
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on pull requests, code style, and issue reporting.
204
+
205
+ ---
206
+
207
+ ## License
208
+
209
+ MIT License — see [LICENSE](LICENSE) for details.
210
+
211
+ ---
212
+
213
+ *Built by [Jay Patel](https://github.com/Jaypatel1511) as part of an open-source CDFI analytics portfolio. Not affiliated with the CDFI Fund or the US Treasury.*