data-analyst-mcp 0.3.1 → 0.5.0

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 (198) hide show
  1. package/README.md +31 -6
  2. package/dist/adapters/_census_micro.js +2 -2
  3. package/dist/adapters/_census_micro.js.map +1 -1
  4. package/dist/adapters/bjs.d.ts +13 -0
  5. package/dist/adapters/bjs.js +28 -0
  6. package/dist/adapters/bjs.js.map +1 -0
  7. package/dist/adapters/cbp.d.ts +5 -0
  8. package/dist/adapters/cbp.js +64 -0
  9. package/dist/adapters/cbp.js.map +1 -0
  10. package/dist/adapters/cdc-wonder.d.ts +5 -0
  11. package/dist/adapters/cdc-wonder.js +68 -0
  12. package/dist/adapters/cdc-wonder.js.map +1 -0
  13. package/dist/adapters/cpsc.d.ts +4 -0
  14. package/dist/adapters/cpsc.js +125 -0
  15. package/dist/adapters/cpsc.js.map +1 -0
  16. package/dist/adapters/fhwa.d.ts +9 -0
  17. package/dist/adapters/fhwa.js +16 -0
  18. package/dist/adapters/fhwa.js.map +1 -0
  19. package/dist/adapters/foreign-assistance.d.ts +9 -0
  20. package/dist/adapters/foreign-assistance.js +42 -0
  21. package/dist/adapters/foreign-assistance.js.map +1 -0
  22. package/dist/adapters/hud-ahar.d.ts +3 -0
  23. package/dist/adapters/hud-ahar.js +80 -0
  24. package/dist/adapters/hud-ahar.js.map +1 -0
  25. package/dist/adapters/nces.d.ts +10 -0
  26. package/dist/adapters/nces.js +32 -0
  27. package/dist/adapters/nces.js.map +1 -0
  28. package/dist/adapters/nsf.d.ts +11 -0
  29. package/dist/adapters/nsf.js +25 -0
  30. package/dist/adapters/nsf.js.map +1 -0
  31. package/dist/adapters/onrr.d.ts +9 -0
  32. package/dist/adapters/onrr.js +35 -0
  33. package/dist/adapters/onrr.js.map +1 -0
  34. package/dist/adapters/sba.d.ts +10 -0
  35. package/dist/adapters/sba.js +134 -0
  36. package/dist/adapters/sba.js.map +1 -0
  37. package/dist/adapters/treasury-tic.d.ts +30 -0
  38. package/dist/adapters/treasury-tic.js +149 -0
  39. package/dist/adapters/treasury-tic.js.map +1 -0
  40. package/dist/adapters/uscourts.d.ts +8 -0
  41. package/dist/adapters/uscourts.js +8 -0
  42. package/dist/adapters/uscourts.js.map +1 -0
  43. package/dist/analysis/cite.d.ts +9 -1
  44. package/dist/analysis/cite.js +9 -2
  45. package/dist/analysis/cite.js.map +1 -1
  46. package/dist/analysis/compute.d.ts +22 -10
  47. package/dist/analysis/compute.js +75 -16
  48. package/dist/analysis/compute.js.map +1 -1
  49. package/dist/analysis/expr.d.ts +2 -0
  50. package/dist/analysis/expr.js +17 -0
  51. package/dist/analysis/expr.js.map +1 -1
  52. package/dist/analysis/replicate.d.ts +15 -0
  53. package/dist/analysis/replicate.js +228 -0
  54. package/dist/analysis/replicate.js.map +1 -0
  55. package/dist/analysis/rerun.js +2 -1
  56. package/dist/analysis/rerun.js.map +1 -1
  57. package/dist/analysis/table.d.ts +14 -0
  58. package/dist/analysis/table.js +79 -28
  59. package/dist/analysis/table.js.map +1 -1
  60. package/dist/analysis/tools.js +16 -4
  61. package/dist/analysis/tools.js.map +1 -1
  62. package/dist/bin/cli.d.ts +2 -0
  63. package/dist/bin/cli.js +17 -0
  64. package/dist/bin/cli.js.map +1 -1
  65. package/dist/core/generic-rest.js +42 -17
  66. package/dist/core/generic-rest.js.map +1 -1
  67. package/dist/core/guard.d.ts +32 -0
  68. package/dist/core/guard.js +176 -0
  69. package/dist/core/guard.js.map +1 -0
  70. package/dist/core/http.d.ts +10 -0
  71. package/dist/core/http.js +36 -7
  72. package/dist/core/http.js.map +1 -1
  73. package/dist/core/keys.d.ts +13 -3
  74. package/dist/core/keys.js +67 -7
  75. package/dist/core/keys.js.map +1 -1
  76. package/dist/core/package.d.ts +12 -3
  77. package/dist/core/package.js +56 -12
  78. package/dist/core/package.js.map +1 -1
  79. package/dist/core/packs.d.ts +14 -5
  80. package/dist/core/packs.js.map +1 -1
  81. package/dist/{deep/_opm_parquet.d.ts → core/parquet.d.ts} +2 -1
  82. package/dist/{deep/_opm_parquet.js → core/parquet.js} +7 -5
  83. package/dist/core/parquet.js.map +1 -0
  84. package/dist/core/secret_patterns.d.ts +6 -0
  85. package/dist/core/secret_patterns.js +20 -0
  86. package/dist/core/secret_patterns.js.map +1 -0
  87. package/dist/core/tabular.d.ts +43 -1
  88. package/dist/core/tabular.js +149 -6
  89. package/dist/core/tabular.js.map +1 -1
  90. package/dist/deep/_opm_io.js +2 -2
  91. package/dist/deep/_opm_io.js.map +1 -1
  92. package/dist/deep/bea.js +1 -0
  93. package/dist/deep/bea.js.map +1 -1
  94. package/dist/deep/fred.js +40 -9
  95. package/dist/deep/fred.js.map +1 -1
  96. package/dist/deep/ipums.js +1 -0
  97. package/dist/deep/ipums.js.map +1 -1
  98. package/dist/deep/opm.js +1 -1
  99. package/dist/deep/opm.js.map +1 -1
  100. package/dist/envelope.js +3 -1
  101. package/dist/envelope.js.map +1 -1
  102. package/dist/index.d.ts +29 -22
  103. package/dist/index.js +45 -46
  104. package/dist/index.js.map +1 -1
  105. package/dist/remote/app.js +87 -31
  106. package/dist/remote/app.js.map +1 -1
  107. package/dist/remote/oauth.js +8 -1
  108. package/dist/remote/oauth.js.map +1 -1
  109. package/dist/remote/pages.d.ts +3 -7
  110. package/dist/remote/pages.js +49 -19
  111. package/dist/remote/pages.js.map +1 -1
  112. package/dist/remote/sign.d.ts +7 -1
  113. package/dist/remote/sign.js +33 -7
  114. package/dist/remote/sign.js.map +1 -1
  115. package/dist/remote/store.js +14 -5
  116. package/dist/remote/store.js.map +1 -1
  117. package/dist/report/audit_report.js +29 -7
  118. package/dist/report/audit_report.js.map +1 -1
  119. package/dist/report/build_report.js +34 -4
  120. package/dist/report/build_report.js.map +1 -1
  121. package/dist/report/method_audit.js +3 -0
  122. package/dist/report/method_audit.js.map +1 -1
  123. package/dist/report/scan_secrets.js +2 -13
  124. package/dist/report/scan_secrets.js.map +1 -1
  125. package/dist/report/tools.js +2 -1
  126. package/dist/report/tools.js.map +1 -1
  127. package/dist/server.d.ts +3 -1
  128. package/dist/server.js +53 -17
  129. package/dist/server.js.map +1 -1
  130. package/dist/tools.d.ts +3 -1
  131. package/dist/tools.js +82 -9
  132. package/dist/tools.js.map +1 -1
  133. package/guide/WORKFLOW.md +6 -5
  134. package/guide/assets/download_data.ps1 +2 -0
  135. package/guide/assets/download_data.sh +8 -2
  136. package/guide/references/report_patterns.md +5 -2
  137. package/guide/references/report_schema.md +140 -0
  138. package/guide/references/routing.md +30 -3
  139. package/package.json +1 -1
  140. package/packs/bjs/endpoints.json +150 -0
  141. package/packs/bjs/policy.json +114 -0
  142. package/packs/bjs/source.md +98 -0
  143. package/packs/cbp/endpoints.json +31 -0
  144. package/packs/cbp/policy.json +85 -0
  145. package/packs/cbp/source.md +57 -0
  146. package/packs/cdc/source.md +1 -1
  147. package/packs/cdc-wonder/endpoints.json +26 -0
  148. package/packs/cdc-wonder/policy.json +84 -0
  149. package/packs/cdc-wonder/source.md +53 -0
  150. package/packs/census/source.md +8 -4
  151. package/packs/college-scorecard/source.md +1 -1
  152. package/packs/cpsc/endpoints.json +91 -0
  153. package/packs/cpsc/policy.json +91 -0
  154. package/packs/cpsc/source.md +76 -0
  155. package/packs/dhs-ohss/source.md +1 -1
  156. package/packs/doj-news/source.md +1 -1
  157. package/packs/fbi/source.md +3 -3
  158. package/packs/fhwa/endpoints.json +48 -0
  159. package/packs/fhwa/policy.json +91 -0
  160. package/packs/fhwa/source.md +59 -0
  161. package/packs/foreign-assistance/endpoints.json +166 -0
  162. package/packs/foreign-assistance/policy.json +80 -0
  163. package/packs/foreign-assistance/source.md +76 -0
  164. package/packs/fred/source.md +2 -1
  165. package/packs/fsa/source.md +1 -1
  166. package/packs/hud/source.md +1 -1
  167. package/packs/hud-ahar/endpoints.json +92 -0
  168. package/packs/hud-ahar/policy.json +88 -0
  169. package/packs/hud-ahar/source.md +72 -0
  170. package/packs/ipums/docs/report_patterns.md +1 -1
  171. package/packs/ipums/docs/variables.md +4 -3
  172. package/packs/ipums/source.md +10 -8
  173. package/packs/naep/source.md +1 -1
  174. package/packs/nces/endpoints.json +101 -0
  175. package/packs/nces/policy.json +99 -0
  176. package/packs/nces/source.md +75 -0
  177. package/packs/nhtsa/source.md +1 -1
  178. package/packs/nsf/endpoints.json +33 -0
  179. package/packs/nsf/policy.json +83 -0
  180. package/packs/nsf/source.md +59 -0
  181. package/packs/onrr/endpoints.json +198 -0
  182. package/packs/onrr/policy.json +91 -0
  183. package/packs/onrr/source.md +55 -0
  184. package/packs/opm/docs/opm_api.md +2 -1
  185. package/packs/opm/source.md +2 -1
  186. package/packs/port.json +65 -0
  187. package/packs/sba/endpoints.json +34 -0
  188. package/packs/sba/policy.json +86 -0
  189. package/packs/sba/source.md +60 -0
  190. package/packs/treasury/source.md +1 -1
  191. package/packs/treasury-tic/endpoints.json +77 -0
  192. package/packs/treasury-tic/policy.json +89 -0
  193. package/packs/treasury-tic/source.md +80 -0
  194. package/packs/uscourts/endpoints.json +22 -0
  195. package/packs/uscourts/policy.json +87 -0
  196. package/packs/uscourts/source.md +56 -0
  197. package/packs/uspto/source.md +1 -1
  198. package/dist/deep/_opm_parquet.js.map +0 -1
@@ -0,0 +1,166 @@
1
+ {
2
+ "base_url": "https://foreignassistance.gov",
3
+ "timeout": 180,
4
+ "endpoints": {
5
+ "by_country": {
6
+ "path": "/static/us_foreign_aid_country.csv",
7
+ "method": "GET",
8
+ "description": "U.S. foreign assistance by recipient country (and regional or worldwide programs), transaction type and fiscal year, current and constant dollars (ForeignAssistance.gov Data page, 'By Country').",
9
+ "params": {
10
+ "country": {
11
+ "in": "spec",
12
+ "desc": "keep these countries: ISO3 code (UKR) or name as published (Ukraine); a list works"
13
+ },
14
+ "fiscal_year": {
15
+ "in": "spec",
16
+ "desc": "keep these fiscal years (a year or a list)"
17
+ },
18
+ "from": {
19
+ "in": "spec",
20
+ "desc": "first fiscal year to keep"
21
+ },
22
+ "to": {
23
+ "in": "spec",
24
+ "desc": "last fiscal year to keep"
25
+ },
26
+ "transaction_type": {
27
+ "in": "spec",
28
+ "desc": "keep these transaction types: Obligations, Disbursements, Appropriated and Planned, President's Budget Requests (or their ids 2, 3, 1, 18)"
29
+ }
30
+ },
31
+ "records": "$csv",
32
+ "paging": {
33
+ "type": "none"
34
+ },
35
+ "max_rows": 300000
36
+ },
37
+ "by_dac_sector": {
38
+ "path": "/static/us_foreign_aid_dac_sector.csv",
39
+ "method": "GET",
40
+ "description": "U.S. foreign assistance by OECD DAC (international) category and sector, transaction type and fiscal year, all countries together.",
41
+ "params": {
42
+ "country": {
43
+ "in": "spec",
44
+ "desc": "keep these countries: ISO3 code (UKR) or name as published (Ukraine); a list works"
45
+ },
46
+ "fiscal_year": {
47
+ "in": "spec",
48
+ "desc": "keep these fiscal years (a year or a list)"
49
+ },
50
+ "from": {
51
+ "in": "spec",
52
+ "desc": "first fiscal year to keep"
53
+ },
54
+ "to": {
55
+ "in": "spec",
56
+ "desc": "last fiscal year to keep"
57
+ },
58
+ "transaction_type": {
59
+ "in": "spec",
60
+ "desc": "keep these transaction types: Obligations, Disbursements, Appropriated and Planned, President's Budget Requests (or their ids 2, 3, 1, 18)"
61
+ }
62
+ },
63
+ "records": "$csv",
64
+ "paging": {
65
+ "type": "none"
66
+ },
67
+ "max_rows": 300000
68
+ },
69
+ "by_usg_sector": {
70
+ "path": "/static/us_foreign_aid_usg_sector.csv",
71
+ "method": "GET",
72
+ "description": "U.S. foreign assistance by U.S. government category and sector (health, peace and security, humanitarian, economic development ...) and country, by transaction type and fiscal year.",
73
+ "params": {
74
+ "country": {
75
+ "in": "spec",
76
+ "desc": "keep these countries: ISO3 code (UKR) or name as published (Ukraine); a list works"
77
+ },
78
+ "fiscal_year": {
79
+ "in": "spec",
80
+ "desc": "keep these fiscal years (a year or a list)"
81
+ },
82
+ "from": {
83
+ "in": "spec",
84
+ "desc": "first fiscal year to keep"
85
+ },
86
+ "to": {
87
+ "in": "spec",
88
+ "desc": "last fiscal year to keep"
89
+ },
90
+ "transaction_type": {
91
+ "in": "spec",
92
+ "desc": "keep these transaction types: Obligations, Disbursements, Appropriated and Planned, President's Budget Requests (or their ids 2, 3, 1, 18)"
93
+ }
94
+ },
95
+ "records": "$csv",
96
+ "paging": {
97
+ "type": "none"
98
+ },
99
+ "max_rows": 300000
100
+ },
101
+ "by_managing_agency": {
102
+ "path": "/static/us_foreign_aid_implementing.csv",
103
+ "method": "GET",
104
+ "description": "U.S. foreign assistance by managing agency (USAID, State, Defense, HHS ...) and country, by transaction type and fiscal year.",
105
+ "params": {
106
+ "country": {
107
+ "in": "spec",
108
+ "desc": "keep these countries: ISO3 code (UKR) or name as published (Ukraine); a list works"
109
+ },
110
+ "fiscal_year": {
111
+ "in": "spec",
112
+ "desc": "keep these fiscal years (a year or a list)"
113
+ },
114
+ "from": {
115
+ "in": "spec",
116
+ "desc": "first fiscal year to keep"
117
+ },
118
+ "to": {
119
+ "in": "spec",
120
+ "desc": "last fiscal year to keep"
121
+ },
122
+ "transaction_type": {
123
+ "in": "spec",
124
+ "desc": "keep these transaction types: Obligations, Disbursements, Appropriated and Planned, President's Budget Requests (or their ids 2, 3, 1, 18)"
125
+ }
126
+ },
127
+ "records": "$csv",
128
+ "paging": {
129
+ "type": "none"
130
+ },
131
+ "max_rows": 300000
132
+ },
133
+ "by_funding_agency": {
134
+ "path": "/static/us_foreign_aid_funding.csv",
135
+ "method": "GET",
136
+ "description": "U.S. foreign assistance by funding agency and funding account (appropriation account) and country, by transaction type and fiscal year.",
137
+ "params": {
138
+ "country": {
139
+ "in": "spec",
140
+ "desc": "keep these countries: ISO3 code (UKR) or name as published (Ukraine); a list works"
141
+ },
142
+ "fiscal_year": {
143
+ "in": "spec",
144
+ "desc": "keep these fiscal years (a year or a list)"
145
+ },
146
+ "from": {
147
+ "in": "spec",
148
+ "desc": "first fiscal year to keep"
149
+ },
150
+ "to": {
151
+ "in": "spec",
152
+ "desc": "last fiscal year to keep"
153
+ },
154
+ "transaction_type": {
155
+ "in": "spec",
156
+ "desc": "keep these transaction types: Obligations, Disbursements, Appropriated and Planned, President's Budget Requests (or their ids 2, 3, 1, 18)"
157
+ }
158
+ },
159
+ "records": "$csv",
160
+ "paging": {
161
+ "type": "none"
162
+ },
163
+ "max_rows": 300000
164
+ }
165
+ }
166
+ }
@@ -0,0 +1,80 @@
1
+ {
2
+ "id": "foreign-assistance",
3
+ "title": "ForeignAssistance.gov: U.S. foreign aid by country, sector and agency",
4
+ "agency": "U.S. Department of State, Office of Foreign Assistance",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "foreign aid",
8
+ "federal spending",
9
+ "international"
10
+ ],
11
+ "keywords": [
12
+ "foreign aid",
13
+ "foreign assistance",
14
+ "foreignassistance.gov",
15
+ "usaid",
16
+ "aid to ukraine",
17
+ "aid to israel",
18
+ "military aid",
19
+ "humanitarian assistance",
20
+ "development assistance",
21
+ "global health aid",
22
+ "aid by country",
23
+ "aid by sector",
24
+ "obligations and disbursements",
25
+ "oda",
26
+ "dac sector"
27
+ ],
28
+ "questions": [
29
+ "how much U.S. foreign aid a country received by year",
30
+ "largest recipients of U.S. foreign assistance",
31
+ "foreign aid by sector (health, security, humanitarian)",
32
+ "aid managed by USAID vs State vs Defense",
33
+ "foreign assistance budget requests by account"
34
+ ],
35
+ "homepage": "https://foreignassistance.gov/",
36
+ "terms_url": "https://foreignassistance.gov/data",
37
+ "auth": {
38
+ "env": null,
39
+ "required": "none",
40
+ "placement": "none",
41
+ "signup_url": null,
42
+ "echoes_key": false
43
+ },
44
+ "limits": {
45
+ "rps": 1,
46
+ "burst": 2,
47
+ "max_rows": 300000
48
+ },
49
+ "routes": {
50
+ "manual": {
51
+ "how": "Open https://foreignassistance.gov/data (Data Download), download the CSV (By Country, By DAC Sector, By USG Sector, By Managing Agency, By Funding Agency), and upload it with ingest."
52
+ }
53
+ },
54
+ "cache": {
55
+ "mode": "run_only",
56
+ "ttl_hours": null,
57
+ "why": "Files are refreshed with the site (data last updated date shown on every page)."
58
+ },
59
+ "redistribution": {
60
+ "mode": "allowed",
61
+ "why": "U.S. government data; the site states an Open Data License."
62
+ },
63
+ "notices": [],
64
+ "retention": null,
65
+ "citation": "U.S. Department of State and USAID, ForeignAssistance.gov, {dataset}, retrieved {retrieved_long}.",
66
+ "audit_hooks": [],
67
+ "clarify": [
68
+ "Which transaction type? Obligations (commitments), Disbursements (money spent), Appropriated and Planned, or President's Budget Requests: never add them together. Default: obligations for 'how much aid', disbursements for 'how much was spent'.",
69
+ "Current or constant dollars? current_amount is nominal; constant_amount is inflation-adjusted. Default: current for one year, constant for trends.",
70
+ "Which years? Fiscal years (October-September); the latest year is incomplete until reporting closes."
71
+ ],
72
+ "formats": [
73
+ "csv"
74
+ ],
75
+ "aliases": [
76
+ "ForeignAssistance.gov",
77
+ "FA.gov",
78
+ "U.S. foreign aid"
79
+ ]
80
+ }
@@ -0,0 +1,76 @@
1
+ # ForeignAssistance.gov: U.S. foreign aid by country, sector and agency
2
+ Depth: standard. Key: none. The aggregate data files of ForeignAssistance.gov, the U.S. government's foreign
3
+ assistance reporting site (State Department and USAID). They give foreign aid by:
4
+ - recipient country or region;
5
+ - international (OECD DAC) and U.S. government sector;
6
+ - managing agency;
7
+ - funding agency and account.
8
+ Each file has transaction type (obligations, disbursements, appropriated and planned, President's budget
9
+ requests) and fiscal year, in current and constant dollars.
10
+
11
+ ## When to use
12
+ - How much U.S. aid a country received; the largest recipients; aid by sector (health, peace and security,
13
+ humanitarian, economic development, democracy); which agencies manage it; trends since the 1940s (in constant
14
+ dollars).
15
+ - Not here: award-level federal grants and contracts with recipient names (usaspending); federal budget totals
16
+ by function (omb, treasury); other donors' aid (world-bank has some ODA indicators).
17
+
18
+ ## Endpoints
19
+ All take the same filters (applied to the published file): `country` (ISO3 code like `UKR`, or the name),
20
+ `fiscal_year`, `from`/`to`, `transaction_type` (name or id).
21
+
22
+ | Endpoint | File | Columns before the amounts |
23
+ |---|---|---|
24
+ | `by_country` | us_foreign_aid_country.csv | Country Code, Country Name, Region ID, Region Name, Income Group Acronym, Income Group Name |
25
+ | `by_dac_sector` | us_foreign_aid_dac_sector.csv | International Category ID/Name, International Sector Code/Name (no country) |
26
+ | `by_usg_sector` | us_foreign_aid_usg_sector.csv | US Category ID/Name, US Sector ID/Name, Country Code/Name |
27
+ | `by_managing_agency` | us_foreign_aid_implementing.csv | Managing Agency ID/Acronym/Name, Country Code/Name |
28
+ | `by_funding_agency` | us_foreign_aid_funding.csv | Funding Agency ID/Acronym/Name, Funding Account ID/Name, Country Code/Name |
29
+
30
+ Every file then has `Transaction Type ID`, `Transaction Type Name`, `Fiscal Year`, `current_amount` and
31
+ `constant_amount`.
32
+
33
+ ## Spec examples
34
+ ```json
35
+ {"description": "U.S. aid obligations to Ukraine, FY2020-2025",
36
+ "requests": [{"name": "ukraine", "endpoint": "by_country",
37
+ "params": {"country": "UKR", "from": "2020", "to": "2025", "transaction_type": "Obligations"}}]}
38
+ ```
39
+ ```json
40
+ {"description": "Aid to Ukraine by managing agency, FY2023",
41
+ "requests": [{"name": "ukraine_agency_2023", "endpoint": "by_managing_agency",
42
+ "params": {"country": "UKR", "fiscal_year": "2023", "transaction_type": "Obligations"}}]}
43
+ ```
44
+
45
+ ## Data format and traps
46
+ - Transaction types are different measures; never add them:
47
+ - 2, Obligations: commitments made, FY1946 on.
48
+ - 3, Disbursements: money paid out, FY2001 on.
49
+ - 1, Appropriated and Planned: FY2004-2023.
50
+ - 18, President's Budget Requests: FY2005-2024.
51
+ (Ranges in the by-country file of 2026-10-30.)
52
+ - Obligations and disbursements in one year are not the same money: disbursements lag obligations.
53
+ - Dollars are whole dollars as text. `constant_amount` is inflation-adjusted and equals `current_amount` in the
54
+ latest complete year (FY2025 in the files of 2026-10-30), so it is in that year's dollars. Name the base year.
55
+ - Fiscal years run October to September. The newest year (2026 in those files) holds partial reporting or
56
+ budget figures only: do not compare it with full years.
57
+ - The country file includes regions and worldwide programs as rows (`WLD` World, `AFR` Africa Region, `ASN` Asia
58
+ Region ...). Former countries have the code `NULL` ("Soviet Union (former)"). Kosovo is `CS-KM`. Some names
59
+ contain line breaks. Drop regional rows before ranking countries, and say that regional and worldwide programs
60
+ are not attributed to countries.
61
+ - Sector and agency files split the same money by country and category: totals from different files agree
62
+ only roughly (late or unattributed reporting). Do not mix files in one sum.
63
+ - Security and military assistance appears where agencies report it (e.g. State and Defense programs): check
64
+ the managing-agency file before calling a total "civilian" or "military".
65
+
66
+ ## Access
67
+ No key. Manual only: on 2026-11-07 foreignassistance.gov answered this server's requests with HTTP 403 (a plain
68
+ browser download works), and the site's Data API at /data-api/ answered 404, its documentation listing
69
+ authentication errors. So `fetch` refuses and `manual_bundle` gives the link. The user downloads the CSV
70
+ from https://foreignassistance.gov/data (Data Download; files up to 22 MB, e.g.
71
+ https://foreignassistance.gov/static/us_foreign_aid_country.csv) and uploads it, and `ingest` applies the
72
+ filters.
73
+
74
+ ## Citation and terms
75
+ "U.S. Department of State and USAID, ForeignAssistance.gov, <file> (data last updated <date shown on the site>),
76
+ retrieved <date>." Open Data License (as stated on the site).
@@ -115,7 +115,8 @@ analyzing" first.
115
115
  - How fetch proceeds: a folder that already holds the same request is reused (also when only labels, sources
116
116
  or copyright changed: it is rebuilt from raw/; `force: true` downloads again). With a stored key it uses the
117
117
  API. Without one it takes FRED's keyless graph downloads when the request needs no key-only feature: mention
118
- once what a key adds. A key-only feature with no key fails with `key_missing`: the user stores a key with
118
+ once what a key adds. If FRED rejects the stored key or the API does not answer, the same applies: it switches to
119
+ the keyless downloads (route `api_keyless`, with a note saying why); tell the user about the key problem in one line. A key-only feature with no key fails with `key_missing`: the user stores a key with
119
120
  `npx -y data-analyst-mcp setup fred` in their own terminal; never ask for the key in chat; offer as-of
120
121
  vintages or explicit state IDs instead. A spec problem fails with `invalid_request`.
121
122
  - Manual download: `manual_bundle` writes `manual_download/INSTRUCTIONS.md`, which lists one browser link per
@@ -11,7 +11,7 @@ school and award-year quarter (from COD). Published .xls workbooks, read into ti
11
11
  - Loans originated and disbursed, and Pell/TEACH grants disbursed, by school, state and program, per award year.
12
12
  - Not here: college costs, completion, earnings and debt at graduation by institution (college-scorecard);
13
13
  federal outlays and awards for student aid (treasury, usaspending); household debt from
14
- surveys (fred for the Fed's G.19 consumer credit series); enrollment counts (IPEDS, not a pack).
14
+ surveys (fred for the Fed's G.19 consumer credit series); enrollment counts (IPEDS: nces).
15
15
 
16
16
  ## Endpoints and datasets
17
17
  | Endpoint | Returns (one row per ...) | Params | Units | Coverage |
@@ -8,7 +8,7 @@ England town, metro FMR area and state, per federal fiscal year.
8
8
  income limits (30%, 50%, 80% of area median) by household size; area median family income as HUD
9
9
  sets it; MTSP (LIHTC) limits.
10
10
  - Not here: market rents and home values from surveys (census ACS median gross rent), house price
11
- indexes (fred, FHFA), homelessness counts and public housing (not covered), mortgage complaints
11
+ indexes (fred, FHFA), homelessness counts (hud-ahar), public housing (not covered), mortgage complaints
12
12
  (cfpb). FMRs are policy values (the 40th percentile gross rent standard), not observed averages.
13
13
 
14
14
  ## Endpoints and datasets
@@ -0,0 +1,92 @@
1
+ {
2
+ "base_url": "https://www.huduser.gov/portal/sites/default/files/xls",
3
+ "timeout": 60,
4
+ "files": {
5
+ "pit_by_coc": "2007-2025-PIT-Counts-by-CoC.xlsb",
6
+ "pit_by_state": "2007-2025-PIT-Counts-by-State.xlsb",
7
+ "hic_by_coc": "2007-2025-HIC-Counts-by-CoC.xlsx",
8
+ "hic_by_state": "2007-2025-HIC-Counts-by-State.xlsx",
9
+ "veterans_by_coc": "2011-2025-PIT-Veteran-Counts-by-CoC.xlsx",
10
+ "veterans_by_state": "2011-2025-PIT-Veteran-Counts-by-State.xlsx"
11
+ },
12
+ "endpoints": {
13
+ "pit_by_coc": {
14
+ "path": "/2007-2025-PIT-Counts-by-CoC.xlsb",
15
+ "method": "GET",
16
+ "description": "Point-in-Time (PIT) counts of people experiencing homelessness by Continuum of Care (CoC), one sheet per year 2007-2025 (2025 AHAR edition). Manual: huduser.gov refuses scripts; the user downloads the workbook and uploads it.",
17
+ "params": {
18
+ "year": {"in": "spec", "required": true, "desc": "the count year, i.e. the workbook sheet to read (2007-2025)"},
19
+ "sheet": {"in": "spec", "desc": "a sheet name other than the year (the workbook's other sheets, e.g. a change table)"},
20
+ "header_row": {"in": "spec", "desc": "the header row of the sheet, 1-based (default 1)"}
21
+ },
22
+ "records": "$xls",
23
+ "paging": {"type": "none"},
24
+ "max_rows": 100000
25
+ },
26
+ "pit_by_state": {
27
+ "path": "/2007-2025-PIT-Counts-by-State.xlsb",
28
+ "method": "GET",
29
+ "description": "PIT counts of people experiencing homelessness by state (and the national total), one sheet per year 2007-2025. Manual.",
30
+ "params": {
31
+ "year": {"in": "spec", "required": true, "desc": "the count year (sheet), 2007-2025"},
32
+ "sheet": {"in": "spec", "desc": "a sheet name other than the year"},
33
+ "header_row": {"in": "spec", "desc": "the header row, 1-based (default 1)"}
34
+ },
35
+ "records": "$xls",
36
+ "paging": {"type": "none"},
37
+ "max_rows": 100000
38
+ },
39
+ "hic_by_coc": {
40
+ "path": "/2007-2025-HIC-Counts-by-CoC.xlsx",
41
+ "method": "GET",
42
+ "description": "Housing Inventory Count (HIC): beds and units for people experiencing homelessness (emergency shelter, transitional, safe haven, rapid re-housing, permanent supportive housing) by CoC, one sheet per year. Manual.",
43
+ "params": {
44
+ "year": {"in": "spec", "required": true, "desc": "the count year (sheet)"},
45
+ "sheet": {"in": "spec", "desc": "a sheet name other than the year"},
46
+ "header_row": {"in": "spec", "desc": "the header row, 1-based (default 1)"}
47
+ },
48
+ "records": "$xlsx",
49
+ "paging": {"type": "none"},
50
+ "max_rows": 100000
51
+ },
52
+ "hic_by_state": {
53
+ "path": "/2007-2025-HIC-Counts-by-State.xlsx",
54
+ "method": "GET",
55
+ "description": "Housing Inventory Count by state, one sheet per year. Manual.",
56
+ "params": {
57
+ "year": {"in": "spec", "required": true, "desc": "the count year (sheet)"},
58
+ "sheet": {"in": "spec", "desc": "a sheet name other than the year"},
59
+ "header_row": {"in": "spec", "desc": "the header row, 1-based (default 1)"}
60
+ },
61
+ "records": "$xlsx",
62
+ "paging": {"type": "none"},
63
+ "max_rows": 100000
64
+ },
65
+ "veterans_by_coc": {
66
+ "path": "/2011-2025-PIT-Veteran-Counts-by-CoC.xlsx",
67
+ "method": "GET",
68
+ "description": "PIT counts of veterans experiencing homelessness by CoC, one sheet per year 2011-2025. Manual.",
69
+ "params": {
70
+ "year": {"in": "spec", "required": true, "desc": "the count year (sheet), 2011-2025"},
71
+ "sheet": {"in": "spec", "desc": "a sheet name other than the year"},
72
+ "header_row": {"in": "spec", "desc": "the header row, 1-based (default 1)"}
73
+ },
74
+ "records": "$xlsx",
75
+ "paging": {"type": "none"},
76
+ "max_rows": 100000
77
+ },
78
+ "veterans_by_state": {
79
+ "path": "/2011-2025-PIT-Veteran-Counts-by-State.xlsx",
80
+ "method": "GET",
81
+ "description": "PIT counts of veterans experiencing homelessness by state, one sheet per year 2011-2025. Manual.",
82
+ "params": {
83
+ "year": {"in": "spec", "required": true, "desc": "the count year (sheet), 2011-2025"},
84
+ "sheet": {"in": "spec", "desc": "a sheet name other than the year"},
85
+ "header_row": {"in": "spec", "desc": "the header row, 1-based (default 1)"}
86
+ },
87
+ "records": "$xlsx",
88
+ "paging": {"type": "none"},
89
+ "max_rows": 100000
90
+ }
91
+ }
92
+ }
@@ -0,0 +1,88 @@
1
+ {
2
+ "id": "hud-ahar",
3
+ "title": "HUD Annual Homelessness Assessment Report (AHAR) data: Point-in-Time and Housing Inventory Counts",
4
+ "agency": "U.S. Department of Housing and Urban Development",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "homelessness",
8
+ "housing"
9
+ ],
10
+ "keywords": [
11
+ "homeless",
12
+ "homelessness",
13
+ "people experiencing homelessness",
14
+ "point-in-time count",
15
+ "pit count",
16
+ "ahar",
17
+ "annual homelessness assessment report",
18
+ "unsheltered",
19
+ "sheltered homeless",
20
+ "chronically homeless",
21
+ "homeless veterans",
22
+ "veteran homelessness",
23
+ "homeless youth",
24
+ "continuum of care",
25
+ "coc",
26
+ "housing inventory count",
27
+ "hic",
28
+ "shelter beds",
29
+ "emergency shelter",
30
+ "permanent supportive housing",
31
+ "rapid re-housing"
32
+ ],
33
+ "questions": [
34
+ "number of people experiencing homelessness by state",
35
+ "unsheltered homeless count in a city or Continuum of Care",
36
+ "change in homelessness since 2020",
37
+ "homeless veterans by state",
38
+ "chronically homeless individuals",
39
+ "emergency shelter and permanent supportive housing beds by CoC"
40
+ ],
41
+ "homepage": "https://www.huduser.gov/portal/datasets/ahar.html",
42
+ "terms_url": "https://www.huduser.gov/portal/datasets/ahar/2025-ahar-part-1-pit-estimates-of-homelessness-in-the-us.html",
43
+ "auth": {
44
+ "env": null,
45
+ "required": "none",
46
+ "placement": "none",
47
+ "signup_url": null,
48
+ "echoes_key": false
49
+ },
50
+ "limits": {
51
+ "rps": 1,
52
+ "burst": 2,
53
+ "max_rows": 100000
54
+ },
55
+ "routes": {
56
+ "manual": {
57
+ "how": "Open https://www.huduser.gov/portal/datasets/ahar/2025-ahar-part-1-pit-estimates-of-homelessness-in-the-us.html in a web browser and download the workbook (2007 - 2025 Point-in-Time Estimates by CoC or by State, Housing Inventory Count by CoC or State, PIT Veteran Counts); huduser.gov refuses scripts. Upload the workbook as saved (.xlsb or .xlsx) with ingest."
58
+ }
59
+ },
60
+ "cache": {
61
+ "mode": "run_only",
62
+ "ttl_hours": null,
63
+ "why": "Workbooks are replaced once a year with the new AHAR edition."
64
+ },
65
+ "redistribution": {
66
+ "mode": "allowed",
67
+ "why": "HUD's AHAR data are U.S. government works in the public domain (17 U.S.C. 105)."
68
+ },
69
+ "notices": [],
70
+ "retention": null,
71
+ "citation": "U.S. Department of Housing and Urban Development, Annual Homelessness Assessment Report (AHAR), {dataset}, HUD User, downloaded {retrieved_long}.",
72
+ "audit_hooks": [],
73
+ "clarify": [
74
+ "Which year? Each sheet is one count year (a single night in late January). Default: the latest year, with 2020 or the prior year for change.",
75
+ "Which population? Total, sheltered, unsheltered, individuals, people in families, chronically homeless, veterans, youth: these overlap. Default: total, split into sheltered and unsheltered.",
76
+ "Which geography? CoCs are HUD's planning areas (a city, a county or a balance of state), not cities or counties as such. Default: states, or the CoC that contains the place named, said as such."
77
+ ],
78
+ "formats": [
79
+ "xlsb",
80
+ "xlsx"
81
+ ],
82
+ "aliases": [
83
+ "AHAR",
84
+ "PIT count",
85
+ "Point-in-Time count",
86
+ "Housing Inventory Count"
87
+ ]
88
+ }
@@ -0,0 +1,72 @@
1
+ # HUD Annual Homelessness Assessment Report (AHAR) data: Point-in-Time and Housing Inventory Counts
2
+ Depth: standard. Key: none. Manual only. HUD's AHAR data workbooks from the 2025 AHAR Part 1 page on HUD User:
3
+ - Point-in-Time (PIT) counts of people experiencing homelessness on one night in January, by Continuum of Care
4
+ (CoC) and by state, 2007-2025.
5
+ - PIT counts of veterans, 2011-2025.
6
+ - The Housing Inventory Count (HIC) of beds and units, by CoC and by state.
7
+ The workbooks have one sheet per year. huduser.gov refuses scripts, so the user downloads the workbook and
8
+ uploads it.
9
+
10
+ ## When to use
11
+ - How many people experience homelessness in a state or CoC, sheltered vs unsheltered; individuals vs
12
+ people in families; chronically homeless; veterans; unaccompanied youth; change over time.
13
+ - Shelter and housing capacity: emergency shelter, transitional housing, safe haven, rapid re-housing and
14
+ permanent supportive housing beds by CoC or state.
15
+ - Not here: Fair Market Rents and income limits (hud, with a HUD User token); renters' cost burden and
16
+ doubled-up households (census ACS); homelessness among students (school-year counts by the Department of
17
+ Education); public housing.
18
+
19
+ ## Endpoints
20
+ Every endpoint is a workbook (fetch refuses them; `manual_bundle` gives the links, then `ingest`):
21
+
22
+ | Endpoint | Workbook (2025 edition) |
23
+ |---|---|
24
+ | `pit_by_coc` | 2007-2025-PIT-Counts-by-CoC.xlsb |
25
+ | `pit_by_state` | 2007-2025-PIT-Counts-by-State.xlsb |
26
+ | `hic_by_coc` | 2007-2025-HIC-Counts-by-CoC.xlsx |
27
+ | `hic_by_state` | 2007-2025-HIC-Counts-by-State.xlsx |
28
+ | `veterans_by_coc` | 2011-2025-PIT-Veteran-Counts-by-CoC.xlsx |
29
+ | `veterans_by_state` | 2011-2025-PIT-Veteran-Counts-by-State.xlsx |
30
+
31
+ Parameters:
32
+ - `year` (required): the sheet to read, named for the count year.
33
+ - `sheet`: any other sheet by name.
34
+ - `header_row`: the header line, 1-based (default 1).
35
+
36
+ ## Spec examples
37
+ ```json
38
+ {"description": "PIT counts by state, 2025 and 2020",
39
+ "requests": [{"name": "pit_2025", "endpoint": "pit_by_state", "params": {"year": "2025"}},
40
+ {"name": "pit_2020", "endpoint": "pit_by_state", "params": {"year": "2020"}}]}
41
+ ```
42
+
43
+ ## Data format and traps
44
+ - Read the columns before using them. The workbook layout was not checked here, because the files cannot be
45
+ downloaded by script. The pack reads the year's sheet with its header row as published; a missing sheet fails
46
+ with the list of sheet names. If the first rows are titles, set `header_row`. Columns are kept exactly as named
47
+ in the workbook, which typically embeds the year in each name, so the same measure has a different name in
48
+ each year's sheet: rename before joining years.
49
+ - The PIT count is one night in late January, not the number of people homeless over a year. HUD requires a
50
+ sheltered count every year but an unsheltered count only every other year (odd years), so a CoC's
51
+ even-year unsheltered number may be carried forward from the year before. In 2021 many CoCs did no
52
+ unsheltered count because of COVID-19, and the 2021 AHAR reported sheltered counts only: 2021 totals are not
53
+ comparable. Say which year and which population.
54
+ - Populations overlap: individuals plus people in families make up the total, while chronically homeless,
55
+ veterans and youth are subsets of it. Never add subpopulations to the total.
56
+ - CoCs are HUD's planning areas: one city, a county, several counties or a "balance of state". CoC numbers
57
+ (like "CA-500") and boundaries change; CoCs merge. Do not equate a CoC with a city without saying so. A state's
58
+ total is the sum of its CoCs.
59
+ - HIC counts beds and units on the PIT night, not people. Permanent supportive housing and rapid re-housing
60
+ beds hold formerly homeless people, who are not in the PIT count.
61
+ - Values are counts as published (numbers in the workbook). Blank cells are blanks: never fill them with 0.
62
+
63
+ ## Access
64
+ No key. Manual only: www.huduser.gov answers scripts with an empty HTTP 202 challenge (verified 2026-11-07). The
65
+ user opens https://www.huduser.gov/portal/datasets/ahar/2025-ahar-part-1-pit-estimates-of-homelessness-in-the-us.html
66
+ in a web browser, downloads the workbook (the `manual_bundle` links point at the files) and uploads it as saved;
67
+ then `ingest`. Older AHAR editions have their own pages under https://www.huduser.gov/portal/datasets/ahar.html.
68
+
69
+ ## Citation and terms
70
+ "U.S. Department of Housing and Urban Development, 2025 Annual Homelessness Assessment Report (AHAR) to Congress,
71
+ Part 1, 2007-2025 Point-in-Time Estimates by State (or by CoC; Housing Inventory Count), HUD User, downloaded
72
+ <date>." Public domain (17 U.S.C. 105).
@@ -57,7 +57,7 @@ state agencies, research institutes), so there is usually a precedent to follow
57
57
  - Report the unweighted cell size internally. Suppress or footnote cells with fewer than about 100 respondents; unstable estimates are not published.
58
58
  - **Dollars:** convert to a single year's dollars and name the year and index ("in 2023 dollars, using the CPI-U-RS"; the PCE price index is a common choice for earnings and income), with CPI99 or `adjustMonetaryValues`. CPS ASEC income is for the **previous calendar year** (ASEC 2023 means 2022 income). ACS income is for the past 12 months, and IPUMS expresses it in survey-year dollars.
59
59
  - **Top-coding:** INCWAGE is top-coded, which mostly matters for means at high education levels. Mention it.
60
- - **Sampling error:** for differences that drive conclusions, note whether they are large relative to sampling error. ACS replicate weights (REPWTP, 80) and CPS ASEC replicate weights (REPWTP, 160) give proper standard errors. CPS basic monthly files have none (REPWTP is ASEC-only) and no design variables: an SE there can only be approximate (clustered by household, `SERIAL` within month). This server does not compute standard errors yet: report which weight was used and that standard errors were not computed.
60
+ - **Sampling error:** for differences that drive conclusions, note whether they are large relative to sampling error. ACS replicate weights (REPWTP, 80) and CPS ASEC replicate weights (REPWTP, 160) give proper standard errors. CPS basic monthly files have none (REPWTP is ASEC-only) and no design variables: an SE there can only be approximate (clustered by household, `SERIAL` within month). With replicate weights in the extract, `compute`'s `replicate_se` step (method `sdr`) gives the standard errors; without them, report which weight was used and that standard errors were not computed.
61
61
 
62
62
  **Publication structure (mirrored in `build_report`, `"mode": "report"`; only when a report is asked for)**
63
63
 
@@ -51,9 +51,10 @@ The ACS starts in 2000 (large samples from 2005, group quarters from 2006). CPS
51
51
 
52
52
  Pooling several years for one estimate: either average the yearly estimates, or divide the weights by the number of years so that totals stay annual.
53
53
 
54
- **Standard errors.** Census recommends replicate weights. This server cannot compute replicate or
55
- design-based standard errors yet: report which weight was used and that standard errors were not computed.
56
- The methods below are for reference.
54
+ **Standard errors.** Census recommends replicate weights. `compute`'s `replicate_se` step computes replicate
55
+ standard errors (`"weight": "PERWT", "replicates": "REPWTP1:REPWTP80", "method": "sdr"`); filtering to a domain
56
+ before it is fine with replicates. Design-based (linearized) standard errors are not computed here: without
57
+ replicates, report which weight was used and that standard errors were not computed. The methods:
57
58
  - **USA (ACS):** request `REPWTP` to get 80 columns. They add a lot of size to multi-year extracts; a linearized SE with the automatic `STRATA` and `CLUSTER` is a fallback only: it can be far off for quantities the ACS weights are raked to (age, sex: median-age margins came out 3 to 13 times the replicate ones) and understate others. Prefer replicates; to save size, case-select a second extract with REPWTP to the areas compared.
58
59
  - **CPS ASEC:** request `REPWTP` to get 160 columns for replicate standard errors.
59
60
  - **NHIS, MEPS:** no replicate weights; Taylor linearization with the design variables (added automatically).