data-analyst-mcp 0.3.0 → 0.4.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 (292) hide show
  1. package/README.md +286 -262
  2. package/dist/adapters/bjs.d.ts +13 -0
  3. package/dist/adapters/bjs.js +28 -0
  4. package/dist/adapters/bjs.js.map +1 -0
  5. package/dist/adapters/cbp.d.ts +5 -0
  6. package/dist/adapters/cbp.js +64 -0
  7. package/dist/adapters/cbp.js.map +1 -0
  8. package/dist/adapters/cdc-wonder.d.ts +5 -0
  9. package/dist/adapters/cdc-wonder.js +68 -0
  10. package/dist/adapters/cdc-wonder.js.map +1 -0
  11. package/dist/adapters/cpsc.d.ts +4 -0
  12. package/dist/adapters/cpsc.js +125 -0
  13. package/dist/adapters/cpsc.js.map +1 -0
  14. package/dist/adapters/fhwa.d.ts +9 -0
  15. package/dist/adapters/fhwa.js +16 -0
  16. package/dist/adapters/fhwa.js.map +1 -0
  17. package/dist/adapters/foreign-assistance.d.ts +9 -0
  18. package/dist/adapters/foreign-assistance.js +42 -0
  19. package/dist/adapters/foreign-assistance.js.map +1 -0
  20. package/dist/adapters/hud-ahar.d.ts +3 -0
  21. package/dist/adapters/hud-ahar.js +80 -0
  22. package/dist/adapters/hud-ahar.js.map +1 -0
  23. package/dist/adapters/nces.d.ts +10 -0
  24. package/dist/adapters/nces.js +32 -0
  25. package/dist/adapters/nces.js.map +1 -0
  26. package/dist/adapters/nsf.d.ts +11 -0
  27. package/dist/adapters/nsf.js +25 -0
  28. package/dist/adapters/nsf.js.map +1 -0
  29. package/dist/adapters/onrr.d.ts +9 -0
  30. package/dist/adapters/onrr.js +35 -0
  31. package/dist/adapters/onrr.js.map +1 -0
  32. package/dist/adapters/sba.d.ts +10 -0
  33. package/dist/adapters/sba.js +134 -0
  34. package/dist/adapters/sba.js.map +1 -0
  35. package/dist/adapters/treasury-tic.d.ts +30 -0
  36. package/dist/adapters/treasury-tic.js +149 -0
  37. package/dist/adapters/treasury-tic.js.map +1 -0
  38. package/dist/adapters/uscourts.d.ts +8 -0
  39. package/dist/adapters/uscourts.js +8 -0
  40. package/dist/adapters/uscourts.js.map +1 -0
  41. package/dist/analysis/cite.d.ts +9 -1
  42. package/dist/analysis/cite.js +9 -2
  43. package/dist/analysis/cite.js.map +1 -1
  44. package/dist/bin/cli.d.ts +2 -0
  45. package/dist/bin/cli.js +17 -0
  46. package/dist/bin/cli.js.map +1 -1
  47. package/dist/core/generic-rest.js +42 -17
  48. package/dist/core/generic-rest.js.map +1 -1
  49. package/dist/core/guard.d.ts +32 -0
  50. package/dist/core/guard.js +176 -0
  51. package/dist/core/guard.js.map +1 -0
  52. package/dist/core/http.d.ts +10 -0
  53. package/dist/core/http.js +36 -7
  54. package/dist/core/http.js.map +1 -1
  55. package/dist/core/keys.d.ts +13 -3
  56. package/dist/core/keys.js +67 -7
  57. package/dist/core/keys.js.map +1 -1
  58. package/dist/core/package.d.ts +12 -3
  59. package/dist/core/package.js +56 -12
  60. package/dist/core/package.js.map +1 -1
  61. package/dist/core/secret_patterns.d.ts +6 -0
  62. package/dist/core/secret_patterns.js +20 -0
  63. package/dist/core/secret_patterns.js.map +1 -0
  64. package/dist/core/tabular.d.ts +43 -1
  65. package/dist/core/tabular.js +149 -6
  66. package/dist/core/tabular.js.map +1 -1
  67. package/dist/envelope.js +3 -1
  68. package/dist/envelope.js.map +1 -1
  69. package/dist/index.d.ts +29 -22
  70. package/dist/index.js +45 -46
  71. package/dist/index.js.map +1 -1
  72. package/dist/remote/app.js +87 -31
  73. package/dist/remote/app.js.map +1 -1
  74. package/dist/remote/oauth.js +8 -1
  75. package/dist/remote/oauth.js.map +1 -1
  76. package/dist/remote/pages.d.ts +3 -7
  77. package/dist/remote/pages.js +49 -19
  78. package/dist/remote/pages.js.map +1 -1
  79. package/dist/remote/sign.d.ts +7 -1
  80. package/dist/remote/sign.js +33 -7
  81. package/dist/remote/sign.js.map +1 -1
  82. package/dist/remote/store.js +14 -5
  83. package/dist/remote/store.js.map +1 -1
  84. package/dist/report/audit_report.js +29 -7
  85. package/dist/report/audit_report.js.map +1 -1
  86. package/dist/report/build_report.js +34 -4
  87. package/dist/report/build_report.js.map +1 -1
  88. package/dist/report/method_audit.js +10 -1
  89. package/dist/report/method_audit.js.map +1 -1
  90. package/dist/report/scan_secrets.d.ts +4 -1
  91. package/dist/report/scan_secrets.js +38 -18
  92. package/dist/report/scan_secrets.js.map +1 -1
  93. package/dist/server.d.ts +3 -1
  94. package/dist/server.js +46 -13
  95. package/dist/server.js.map +1 -1
  96. package/dist/tools.js +27 -6
  97. package/dist/tools.js.map +1 -1
  98. package/guide/WORKFLOW.md +134 -134
  99. package/guide/assets/disclaimer.txt +1 -1
  100. package/guide/assets/download_data.ps1 +164 -162
  101. package/guide/assets/download_data.sh +8 -2
  102. package/guide/assets/report_template.html +597 -597
  103. package/guide/references/routing.md +198 -171
  104. package/guide/references/style_guide.md +398 -398
  105. package/package.json +56 -56
  106. package/packs/acf/endpoints.json +114 -114
  107. package/packs/acf/policy.json +104 -104
  108. package/packs/actuaries/endpoints.json +82 -82
  109. package/packs/actuaries/policy.json +109 -109
  110. package/packs/bea/assets/download_bea.ps1 +182 -182
  111. package/packs/bea/docs/bea_api.md +461 -461
  112. package/packs/bea/docs/datasets.md +157 -157
  113. package/packs/bea/docs/report_patterns.md +112 -112
  114. package/packs/bea/policy.json +170 -170
  115. package/packs/bea/source.md +152 -152
  116. package/packs/bjs/endpoints.json +150 -0
  117. package/packs/bjs/policy.json +114 -0
  118. package/packs/bjs/source.md +98 -0
  119. package/packs/bls/assets/download_bls.ps1 +152 -152
  120. package/packs/bls/docs/analysis_patterns.md +108 -108
  121. package/packs/bls/docs/bls_api.md +73 -73
  122. package/packs/bls/docs/series_ids.md +149 -149
  123. package/packs/bls/policy.json +238 -238
  124. package/packs/bts/endpoints.json +346 -346
  125. package/packs/bts/policy.json +94 -94
  126. package/packs/cbp/endpoints.json +31 -0
  127. package/packs/cbp/policy.json +85 -0
  128. package/packs/cbp/source.md +57 -0
  129. package/packs/cdc/endpoints.json +197 -197
  130. package/packs/cdc/policy.json +83 -83
  131. package/packs/cdc/source.md +1 -1
  132. package/packs/cdc-wonder/endpoints.json +26 -0
  133. package/packs/cdc-wonder/policy.json +84 -0
  134. package/packs/cdc-wonder/source.md +53 -0
  135. package/packs/census/endpoints.json +99 -99
  136. package/packs/cfpb/endpoints.json +326 -326
  137. package/packs/cfpb/policy.json +119 -119
  138. package/packs/clinical-trials/endpoints.json +166 -166
  139. package/packs/clinical-trials/policy.json +84 -84
  140. package/packs/cms/endpoints.json +69 -69
  141. package/packs/cms/policy.json +96 -96
  142. package/packs/college-scorecard/endpoints.json +252 -252
  143. package/packs/college-scorecard/policy.json +106 -106
  144. package/packs/college-scorecard/source.md +1 -1
  145. package/packs/congress/endpoints.json +1701 -1701
  146. package/packs/congress/policy.json +117 -117
  147. package/packs/cpsc/endpoints.json +91 -0
  148. package/packs/cpsc/policy.json +91 -0
  149. package/packs/cpsc/source.md +76 -0
  150. package/packs/dhs-ohss/endpoints.json +66 -66
  151. package/packs/dhs-ohss/policy.json +107 -107
  152. package/packs/dhs-ohss/source.md +1 -1
  153. package/packs/doj-news/endpoints.json +59 -59
  154. package/packs/doj-news/policy.json +96 -96
  155. package/packs/doj-news/source.md +1 -1
  156. package/packs/dol/endpoints.json +817 -817
  157. package/packs/dol/policy.json +135 -135
  158. package/packs/eia/endpoints.json +717 -717
  159. package/packs/eia/policy.json +112 -112
  160. package/packs/epa/endpoints.json +291 -291
  161. package/packs/epa/policy.json +99 -99
  162. package/packs/epa-aqs/endpoints.json +173 -173
  163. package/packs/epa-aqs/policy.json +96 -96
  164. package/packs/fbi/endpoints.json +1841 -1841
  165. package/packs/fbi/policy.json +118 -118
  166. package/packs/fbi/source.md +3 -3
  167. package/packs/fda/endpoints.json +237 -237
  168. package/packs/fda/policy.json +121 -121
  169. package/packs/fdic/endpoints.json +416 -416
  170. package/packs/fdic/policy.json +83 -83
  171. package/packs/fec/endpoints.json +707 -707
  172. package/packs/fec/policy.json +93 -93
  173. package/packs/fed-board/endpoints.json +89 -89
  174. package/packs/fed-board/policy.json +136 -136
  175. package/packs/federal-register/endpoints.json +143 -143
  176. package/packs/federal-register/policy.json +86 -86
  177. package/packs/fema/endpoints.json +645 -645
  178. package/packs/fema/policy.json +103 -103
  179. package/packs/fhfa/endpoints.json +105 -105
  180. package/packs/fhfa/policy.json +109 -109
  181. package/packs/fhwa/endpoints.json +48 -0
  182. package/packs/fhwa/policy.json +91 -0
  183. package/packs/fhwa/source.md +59 -0
  184. package/packs/foreign-assistance/endpoints.json +166 -0
  185. package/packs/foreign-assistance/policy.json +80 -0
  186. package/packs/foreign-assistance/source.md +76 -0
  187. package/packs/fred/assets/download_fred.ps1 +122 -122
  188. package/packs/fred/docs/analysis_patterns.md +124 -124
  189. package/packs/fred/docs/fred_api.md +94 -94
  190. package/packs/fred/docs/series.md +188 -188
  191. package/packs/fred/policy.json +253 -253
  192. package/packs/fsa/endpoints.json +150 -150
  193. package/packs/fsa/policy.json +99 -99
  194. package/packs/fsa/source.md +1 -1
  195. package/packs/govinfo/endpoints.json +519 -519
  196. package/packs/gsa-calc/endpoints.json +93 -93
  197. package/packs/gsa-calc/policy.json +97 -97
  198. package/packs/hud/endpoints.json +146 -146
  199. package/packs/hud/policy.json +84 -84
  200. package/packs/hud/source.md +1 -1
  201. package/packs/hud-ahar/endpoints.json +92 -0
  202. package/packs/hud-ahar/policy.json +88 -0
  203. package/packs/hud-ahar/source.md +72 -0
  204. package/packs/ipums/docs/report_patterns.md +117 -117
  205. package/packs/irs-soi/endpoints.json +114 -114
  206. package/packs/irs-soi/policy.json +107 -107
  207. package/packs/medicaid/endpoints.json +412 -412
  208. package/packs/medicaid/policy.json +108 -108
  209. package/packs/naep/endpoints.json +217 -217
  210. package/packs/naep/policy.json +100 -100
  211. package/packs/naep/source.md +1 -1
  212. package/packs/nces/endpoints.json +101 -0
  213. package/packs/nces/policy.json +99 -0
  214. package/packs/nces/source.md +75 -0
  215. package/packs/nhtsa/endpoints.json +132 -132
  216. package/packs/nhtsa/policy.json +93 -93
  217. package/packs/nhtsa/source.md +1 -1
  218. package/packs/nih/endpoints.json +452 -452
  219. package/packs/nih/policy.json +86 -86
  220. package/packs/noaa/endpoints.json +431 -431
  221. package/packs/noaa/policy.json +95 -95
  222. package/packs/nrel/endpoints.json +327 -327
  223. package/packs/nrel/policy.json +96 -96
  224. package/packs/nsf/endpoints.json +33 -0
  225. package/packs/nsf/policy.json +83 -0
  226. package/packs/nsf/source.md +59 -0
  227. package/packs/nws/endpoints.json +271 -271
  228. package/packs/nws/policy.json +82 -82
  229. package/packs/nyfed/endpoints.json +80 -80
  230. package/packs/nyfed/policy.json +92 -92
  231. package/packs/omb/endpoints.json +460 -460
  232. package/packs/omb/policy.json +106 -106
  233. package/packs/onrr/endpoints.json +198 -0
  234. package/packs/onrr/policy.json +91 -0
  235. package/packs/onrr/source.md +55 -0
  236. package/packs/open-payments/endpoints.json +297 -297
  237. package/packs/open-payments/policy.json +101 -101
  238. package/packs/opm/assets/download_opm.ps1 +125 -125
  239. package/packs/opm/docs/fields.md +184 -184
  240. package/packs/opm/docs/opm_api.md +71 -71
  241. package/packs/opm/docs/report_patterns.md +83 -83
  242. package/packs/opm/lib/data_dictionary.csv +73 -73
  243. package/packs/pbgc/endpoints.json +483 -483
  244. package/packs/pbgc/policy.json +94 -94
  245. package/packs/philfed/endpoints.json +85 -85
  246. package/packs/philfed/policy.json +94 -94
  247. package/packs/port.json +65 -0
  248. package/packs/regulations/endpoints.json +287 -287
  249. package/packs/regulations/policy.json +86 -86
  250. package/packs/sba/endpoints.json +34 -0
  251. package/packs/sba/policy.json +86 -0
  252. package/packs/sba/source.md +60 -0
  253. package/packs/sec/endpoints.json +236 -236
  254. package/packs/sec/policy.json +86 -86
  255. package/packs/senate-lobbying/endpoints.json +553 -553
  256. package/packs/senate-lobbying/policy.json +99 -99
  257. package/packs/snapqc/endpoints.json +1426 -1426
  258. package/packs/snapqc/policy.json +92 -92
  259. package/packs/treasury/catalog.json +2267 -2267
  260. package/packs/treasury/docs/api_guide.md +245 -245
  261. package/packs/treasury/docs/datasets.md +56 -56
  262. package/packs/treasury/docs/report_patterns.md +126 -126
  263. package/packs/treasury/policy.json +159 -159
  264. package/packs/treasury/source.md +170 -165
  265. package/packs/treasury-tic/endpoints.json +77 -0
  266. package/packs/treasury-tic/policy.json +89 -0
  267. package/packs/treasury-tic/source.md +80 -0
  268. package/packs/treasury-yields/endpoints.json +226 -226
  269. package/packs/treasury-yields/policy.json +86 -86
  270. package/packs/usaspending/endpoints.json +1315 -1315
  271. package/packs/usaspending/policy.json +109 -109
  272. package/packs/uscourts/endpoints.json +22 -0
  273. package/packs/uscourts/policy.json +87 -0
  274. package/packs/uscourts/source.md +56 -0
  275. package/packs/usda-fna/policy.json +133 -133
  276. package/packs/usda-fooddata/endpoints.json +180 -180
  277. package/packs/usda-fooddata/policy.json +94 -94
  278. package/packs/usda-nass/endpoints.json +323 -323
  279. package/packs/usda-nass/policy.json +95 -95
  280. package/packs/usda-outlook/endpoints.json +86 -86
  281. package/packs/usda-outlook/policy.json +109 -109
  282. package/packs/usgs/endpoints.json +313 -313
  283. package/packs/usgs/policy.json +95 -95
  284. package/packs/usitc/endpoints.json +74 -74
  285. package/packs/usitc/policy.json +111 -111
  286. package/packs/uspto/endpoints.json +141 -141
  287. package/packs/uspto/policy.json +95 -95
  288. package/packs/uspto/source.md +1 -1
  289. package/packs/va/endpoints.json +414 -414
  290. package/packs/va/policy.json +101 -101
  291. package/packs/world-bank/endpoints.json +122 -122
  292. package/packs/world-bank/policy.json +101 -101
@@ -1,56 +1,56 @@
1
- # Which dataset answers which question
2
-
3
- Start here to pick endpoints. Each row says whether the measure is a **stock** (a level at a date:
4
- take the end-of-period value or an average) or a **flow** (an amount over a period: sum months, or
5
- read a fiscal-year-to-date row). Confirm paths and field names live with `request_schema` (`search: "<words>"`, then
6
- `search: "<endpoint>"` for its fields); details and pitfalls are in `api_guide.md` (section numbers in brackets).
7
-
8
- Units: **$** = dollars and cents; **$M** = millions of dollars; **%** = already in percent.
9
-
10
- "Rows to use" always names the column with the value (`data_type_cd` = T, not "the T row"): the same
11
- letter can be a value in two columns. Check live with `request_schema` and `search: "<endpoint> <filter JSON> values"`;
12
- each download's `data/treasury/README.md` also lists the values found in every code and description column.
13
-
14
- ## Question → endpoint
15
-
16
- | Question | Endpoint | Rows to use | Stock/flow | Units | Pitfalls |
17
- |---|---|---|---|---|---|
18
- | Total federal debt, debt held by the public, intragovernmental holdings (daily, since 1993) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ | DHP and intragov are null before 2005-03-31; the latest day lags one business day |
19
- | Debt at each fiscal year end, back to 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ | early years dated Jan 1, recent years Sep 30; definitions change over two centuries |
20
- | Debt by security type (bills, notes, bonds, TIPS, FRNs; marketable vs nonmarketable), monthly | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total ..." rows when summing | stock | $M | totals differ from Debt to the Penny by rounding and FFB debt [4.14] |
21
- | Debt subject to the statutory limit | `v1/debt/mspd/mspd_table_2` (monthly) or `v1/accounting/dts/debt_subject_to_limit` (daily) | `debt_catg_desc` | stock | $M | |
22
- | Monthly receipts, outlays, deficit (long series since FY1981) | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` = Receipts / Outlays / Deficit/Surplus (-) | flow | $M | deficit is **positive** in this table [4.3] |
23
- | Monthly receipts, outlays, deficit (since FY2015, more detail) | `v1/accounting/mts/mts_table_1` | months: the **latest** `record_date` only, `record_type_cd` = MTH; full fiscal year: September `record_date`, `classification_desc` = "Year-to-Date" (`record_type_cd` = SL, `data_type_cd` = T) | flow | $ | each release holds **two fiscal-year blocks**: `sequence_number_cd` 1.x = prior FY (as revised), 2.x = current FY, so "Year-to-Date" appears twice per release [4.8]; releases repeat prior months and revise them: never stack releases [4.5, 4.6]; deficit positive [4.3] |
24
- | Receipts by source (individual, corporate, payroll, excise, customs ...) and outlays by function (defense, Social Security, Medicare, net interest ...) | `v1/accounting/mts/mts_table_9` | September `record_date` for a full FY; `data_type_cd` = D for components, `data_type_cd` = T with `classification_desc` = "Total" for totals; `record_type_cd` = RSG for receipts, F for functions | flow (`current_fytd_*` is cumulative) | $ | Social Insurance is an S header with 3 D children; never sum all rows [4.9] |
25
- | Outlays by function and subfunction | `v1/accounting/mts/mts_table_9_outlays_functions_subfunctions` | D rows at the wanted `sequence_level_nbr` | flow | $ | |
26
- | Receipts detail (gross, refunds, net) | `v1/accounting/mts/mts_table_4` | totals: the rows with `classification_desc` starting "Total -- " (`data_type_cd` = T or `record_type_cd` = SL) | flow | $ | **D rows do not sum to the total** in Table 4 [4.9]; prefer Table 9 for receipts by source |
27
- | Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A = agency totals; D rows sum to "Total Outlays" | flow | $ | Table 5's "Total Surplus (+) or Deficit (-)" is **negative** for a deficit [4.3]; never add T rows to D rows |
28
- | Interest expense on the public debt (gross, by security type) | `v2/accounting/od/interest_expense` | `expense_catg_desc`, `expense_group_desc`, `expense_type_desc`; `month_expense_amt` per month or September `fytd_expense_amt` | flow | $ | detail rows only (no total rows): the sum of **all** rows is the total interest expense (FY2024: $1,133.0 billion). From FY2025 it includes a GAS line "Restoration of Interest" ($4.4 billion in FY2025, $0.4 billion in FY2026) that MTS Table 5 "Interest on Treasury Debt Securities (Gross)" leaves out: drop it to match MTS. Marketable TIPS interest is the sum of the TIPS lines, inflation compensation included ("Int. Expense Inflation Compensation (TIPS)"); the GAS "Inflation Compensation" line is not TIPS, so never select TIPS with a substring such as "Inflation". Marketable = the Treasury Bills, Notes, Bonds, TIPS (both TIPS lines) and FRN lines; the other public-issue lines are nonmarketable held by the public (Savings Bonds, State & Local Government (SLGS), Domestic, Foreign and REA Series) or miscellaneous (Matured Debt, Limited Payability, Recertified Agency Payments), about $8 billion in FY2026: public issues are not all marketable. Check the lines with `--values`. Two categories: INTEREST EXPENSE ON PUBLIC ISSUES (debt held by the public) and ON GOVT ACCOUNT SERIES (trust funds; intragovernmental). The GAS groups "ACCRUAL BASIS GAS EXPENSE" (zero-coupon amortized discount only) and "CASH BASIS GAS PAYMENTS" are different line items, not two versions of the same amount: keep both. Some lines are negative (premiums, collected discounts). Total = gross interest; MTS "Net Interest" (Table 9) is the budget's **net** measure (nets out trust-fund interest and other receipts): say which one is used |
29
- | Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` = "Total Interest-bearing Debt", "Total Marketable", "Treasury Bills" ... | stock (a rate at month end) | % | rows for totals and components sit side by side; "Total Marketable" leaves out TIPS and FRNs (see source.md) |
30
- | Treasury cash balance (TGA) | `v1/accounting/dts/operating_cash_balance` | before 2022-04-18: TGA / Federal Reserve Account row, `close_today_bal`; from 2022-04-18: "Treasury General Account (TGA) Closing Balance" row, `open_today_bal` | stock | $M | **format change on 2022-04-18** [4.11] |
31
- | Daily deposits and withdrawals by category (tax receipts, Social Security, Medicare, interest ...) | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg`; drop the "Total ..." account rows when summing details | flow (`transaction_today_amt`; `_mtd`, `_fytd` are cumulative) | $M | gross public debt cash issues and redemptions are in here: exclude for operating flows; category names change over time [4.12] |
32
- | Gross borrowing: debt issued and redeemed | `v1/accounting/dts/public_debt_transactions` | `transaction_type` Issues / Redemptions, `security_type` | flow | $M | |
33
- | Auction results (yields, bid-to-cover, who bought) | `v1/accounting/od/auctions_query` | completed auctions only (`auction_date` <= today, non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security: No` for nominal securities (TIPS are `security_type` Note too) | event | mixed | future auctions have null results [4.16] |
34
- | Exchange rates used for federal reporting | `v1/accounting/od/rates_of_exchange` | `country_currency_desc`; latest `effective_date` per quarter | stock | foreign units per USD | amendments create duplicate quarter rows [4.15] |
35
- | Revenue collections by channel and tax category | `v2/revenue/rcm` | `tax_category_desc`, `channel_type_desc` | flow | $ | collections, not budget receipts |
36
- | Receivables and delinquent debt owed to agencies | `v2/debt/tror` | per agency × receivable type | stock | $ | ~230 columns: select by name |
37
- | Treasury Offset Program collections | `v1/debt/treasury_offset_program` | filter by date and agency | flow | $ | 3.5 million rows: always filter |
38
- | Gifts to reduce the debt | `v2/accounting/od/gift_contributions` | one row per month | flow | $ | |
39
- | Savings bonds, I bond rates | `v2/accounting/od/sb_value`, `v1/accounting/od/i_bonds_interest_rates` | | | | **no record_date**: set `date_field` [3] |
40
- | Buybacks | `v1/accounting/od/buybacks_operations` | | event | $ | date column is `operation_date` |
41
- | Federal government balance sheet, net cost (Financial Report) | `v2/accounting/od/balance_sheets`, `v2/accounting/od/statement_net_cost` | | annual | $ | lags months |
42
-
43
- Anything else: `request_schema` for treasury with a search (`"<words>"`) lists every matching endpoint with
44
- frequency, earliest and latest date, row count and the dataset page.
45
-
46
- ## Not in Fiscal Data: say so and offer the right source
47
- - **GDP, CPI, inflation**: BEA and BLS, through the treasury spec's `context` field (CPI-U from FRED or BLS; GDP from
48
- FRED, with an annual World Bank fallback).
49
- - **Budget projections, baselines, scoring**: CBO (https://www.cbo.gov/data/budget-economic-data).
50
- - **Historical budget tables, % of GDP back to 1930, the President's budget**: OMB Historical Tables
51
- (https://www.whitehouse.gov/omb/budget/historical-tables/).
52
- - **Who holds Treasury debt (foreign holders by country)**: Treasury International Capital (TIC), not
53
- Fiscal Data; the Treasury Bulletin OFS-2 table (`v1/accounting/tb/ofs2_...`) gives ownership by sector.
54
- - **Market yields (daily Treasury par yield curve)**: the treasury-yields pack (home.treasury.gov interest-rate statistics), not this API;
55
- Fiscal Data has auction results and average rates on outstanding debt.
56
- - **State and local finances**: Census Bureau Annual Survey of State and Local Government Finances.
1
+ # Which dataset answers which question
2
+
3
+ Start here to pick endpoints. Each row says whether the measure is a **stock** (a level at a date:
4
+ take the end-of-period value or an average) or a **flow** (an amount over a period: sum months, or
5
+ read a fiscal-year-to-date row). Confirm paths and field names live with `request_schema` (`search: "<words>"`, then
6
+ `search: "<endpoint>"` for its fields); details and pitfalls are in `api_guide.md` (section numbers in brackets).
7
+
8
+ Units: **$** = dollars and cents; **$M** = millions of dollars; **%** = already in percent.
9
+
10
+ "Rows to use" always names the column with the value (`data_type_cd` = T, not "the T row"): the same
11
+ letter can be a value in two columns. Check live with `request_schema` and `search: "<endpoint> <filter JSON> values"`;
12
+ each download's `data/treasury/README.md` also lists the values found in every code and description column.
13
+
14
+ ## Question → endpoint
15
+
16
+ | Question | Endpoint | Rows to use | Stock/flow | Units | Pitfalls |
17
+ |---|---|---|---|---|---|
18
+ | Total federal debt, debt held by the public, intragovernmental holdings (daily, since 1993) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ | DHP and intragov are null before 2005-03-31; the latest day lags one business day |
19
+ | Debt at each fiscal year end, back to 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ | early years dated Jan 1, recent years Sep 30; definitions change over two centuries |
20
+ | Debt by security type (bills, notes, bonds, TIPS, FRNs; marketable vs nonmarketable), monthly | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total ..." rows when summing | stock | $M | totals differ from Debt to the Penny by rounding and FFB debt [4.14] |
21
+ | Debt subject to the statutory limit | `v1/debt/mspd/mspd_table_2` (monthly) or `v1/accounting/dts/debt_subject_to_limit` (daily) | `debt_catg_desc` | stock | $M | |
22
+ | Monthly receipts, outlays, deficit (long series since FY1981) | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` = Receipts / Outlays / Deficit/Surplus (-) | flow | $M | deficit is **positive** in this table [4.3] |
23
+ | Monthly receipts, outlays, deficit (since FY2015, more detail) | `v1/accounting/mts/mts_table_1` | months: the **latest** `record_date` only, `record_type_cd` = MTH; full fiscal year: September `record_date`, `classification_desc` = "Year-to-Date" (`record_type_cd` = SL, `data_type_cd` = T) | flow | $ | each release holds **two fiscal-year blocks**: `sequence_number_cd` 1.x = prior FY (as revised), 2.x = current FY, so "Year-to-Date" appears twice per release [4.8]; releases repeat prior months and revise them: never stack releases [4.5, 4.6]; deficit positive [4.3] |
24
+ | Receipts by source (individual, corporate, payroll, excise, customs ...) and outlays by function (defense, Social Security, Medicare, net interest ...) | `v1/accounting/mts/mts_table_9` | September `record_date` for a full FY; `data_type_cd` = D for components, `data_type_cd` = T with `classification_desc` = "Total" for totals; `record_type_cd` = RSG for receipts, F for functions | flow (`current_fytd_*` is cumulative) | $ | Social Insurance is an S header with 3 D children; never sum all rows [4.9] |
25
+ | Outlays by function and subfunction | `v1/accounting/mts/mts_table_9_outlays_functions_subfunctions` | D rows at the wanted `sequence_level_nbr` | flow | $ | |
26
+ | Receipts detail (gross, refunds, net) | `v1/accounting/mts/mts_table_4` | totals: the rows with `classification_desc` starting "Total -- " (`data_type_cd` = T or `record_type_cd` = SL) | flow | $ | **D rows do not sum to the total** in Table 4 [4.9]; prefer Table 9 for receipts by source |
27
+ | Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A = agency totals; D rows sum to "Total Outlays" | flow | $ | Table 5's "Total Surplus (+) or Deficit (-)" is **negative** for a deficit [4.3]; never add T rows to D rows |
28
+ | Interest expense on the public debt (gross, by security type) | `v2/accounting/od/interest_expense` | `expense_catg_desc`, `expense_group_desc`, `expense_type_desc`; `month_expense_amt` per month or September `fytd_expense_amt` | flow | $ | detail rows only (no total rows): the sum of **all** rows is the total interest expense (FY2024: $1,133.0 billion). From FY2025 it includes a GAS line "Restoration of Interest" ($4.4 billion in FY2025, $0.4 billion in FY2026) that MTS Table 5 "Interest on Treasury Debt Securities (Gross)" leaves out: drop it to match MTS. Marketable TIPS interest is the sum of the TIPS lines, inflation compensation included ("Int. Expense Inflation Compensation (TIPS)"); the GAS "Inflation Compensation" line is not TIPS, so never select TIPS with a substring such as "Inflation". Marketable = the Treasury Bills, Notes, Bonds, TIPS (both TIPS lines) and FRN lines; the other public-issue lines are nonmarketable held by the public (Savings Bonds, State & Local Government (SLGS), Domestic, Foreign and REA Series) or miscellaneous (Matured Debt, Limited Payability, Recertified Agency Payments), about $8 billion in FY2026: public issues are not all marketable. Check the lines with `--values`. Two categories: INTEREST EXPENSE ON PUBLIC ISSUES (debt held by the public) and ON GOVT ACCOUNT SERIES (trust funds; intragovernmental). The GAS groups "ACCRUAL BASIS GAS EXPENSE" (zero-coupon amortized discount only) and "CASH BASIS GAS PAYMENTS" are different line items, not two versions of the same amount: keep both. Some lines are negative (premiums, collected discounts). Total = gross interest; MTS "Net Interest" (Table 9) is the budget's **net** measure (nets out trust-fund interest and other receipts): say which one is used |
29
+ | Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` = "Total Interest-bearing Debt", "Total Marketable", "Treasury Bills" ... | stock (a rate at month end) | % | rows for totals and components sit side by side; "Total Marketable" leaves out TIPS and FRNs (see source.md) |
30
+ | Treasury cash balance (TGA) | `v1/accounting/dts/operating_cash_balance` | before 2022-04-18: TGA / Federal Reserve Account row, `close_today_bal`; from 2022-04-18: "Treasury General Account (TGA) Closing Balance" row, `open_today_bal` | stock | $M | **format change on 2022-04-18** [4.11] |
31
+ | Daily deposits and withdrawals by category (tax receipts, Social Security, Medicare, interest ...) | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg`; drop the "Total ..." account rows when summing details | flow (`transaction_today_amt`; `_mtd`, `_fytd` are cumulative) | $M | gross public debt cash issues and redemptions are in here: exclude for operating flows; category names change over time [4.12] |
32
+ | Gross borrowing: debt issued and redeemed | `v1/accounting/dts/public_debt_transactions` | `transaction_type` Issues / Redemptions, `security_type` | flow | $M | |
33
+ | Auction results (yields, bid-to-cover, who bought) | `v1/accounting/od/auctions_query` | completed auctions only (`auction_date` <= today, non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security: No` for nominal securities (TIPS are `security_type` Note too) | event | mixed | future auctions have null results [4.16] |
34
+ | Exchange rates used for federal reporting | `v1/accounting/od/rates_of_exchange` | `country_currency_desc`; latest `effective_date` per quarter | stock | foreign units per USD | amendments create duplicate quarter rows [4.15] |
35
+ | Revenue collections by channel and tax category | `v2/revenue/rcm` | `tax_category_desc`, `channel_type_desc` | flow | $ | collections, not budget receipts |
36
+ | Receivables and delinquent debt owed to agencies | `v2/debt/tror` | per agency × receivable type | stock | $ | ~230 columns: select by name |
37
+ | Treasury Offset Program collections | `v1/debt/treasury_offset_program` | filter by date and agency | flow | $ | 3.5 million rows: always filter |
38
+ | Gifts to reduce the debt | `v2/accounting/od/gift_contributions` | one row per month | flow | $ | |
39
+ | Savings bonds, I bond rates | `v2/accounting/od/sb_value`, `v1/accounting/od/i_bonds_interest_rates` | | | | **no record_date**: set `date_field` [3] |
40
+ | Buybacks | `v1/accounting/od/buybacks_operations` | | event | $ | date column is `operation_date` |
41
+ | Federal government balance sheet, net cost (Financial Report) | `v2/accounting/od/balance_sheets`, `v2/accounting/od/statement_net_cost` | | annual | $ | lags months |
42
+
43
+ Anything else: `request_schema` for treasury with a search (`"<words>"`) lists every matching endpoint with
44
+ frequency, earliest and latest date, row count and the dataset page.
45
+
46
+ ## Not in Fiscal Data: say so and offer the right source
47
+ - **GDP, CPI, inflation**: BEA and BLS, through the treasury spec's `context` field (CPI-U from FRED or BLS; GDP from
48
+ FRED, with an annual World Bank fallback).
49
+ - **Budget projections, baselines, scoring**: CBO (https://www.cbo.gov/data/budget-economic-data).
50
+ - **Historical budget tables, % of GDP back to 1930, the President's budget**: OMB Historical Tables
51
+ (https://www.whitehouse.gov/omb/budget/historical-tables/).
52
+ - **Who holds Treasury debt (foreign holders by country)**: Treasury International Capital (TIC), not
53
+ Fiscal Data; the Treasury Bulletin OFS-2 table (`v1/accounting/tb/ofs2_...`) gives ownership by sector.
54
+ - **Market yields (daily Treasury par yield curve)**: the treasury-yields pack (home.treasury.gov interest-rate statistics), not this API;
55
+ Fiscal Data has auction results and average rates on outstanding debt.
56
+ - **State and local finances**: Census Bureau Annual Survey of State and Local Government Finances.
@@ -1,126 +1,126 @@
1
- # Analysis and report patterns for federal fiscal data
2
-
3
- Use this file to frame the analysis, choose the critical questions, and shape the product. The aim is
4
- work a careful budget analyst would recognize: the right measure (stock or flow, gross or net), the
5
- right period (fiscal or calendar year, complete or partial), stated units and dollar basis, numbers that
6
- tie to the published statement, and limitations stated plainly.
7
-
8
- ## Typical questions and how they are framed
9
-
10
- - **Debt level and growth:** "How much has the debt grown since 2015?" Measures: total public debt
11
- outstanding and debt held by the public (Debt to the Penny) at fiscal-year ends; growth in dollars, in
12
- percent and per year (CAGR). Benchmark: the September Monthly Statement of the Public Debt.
13
- - **Deficits:** "What was the deficit in FY2025, and how does it compare?" Measures: receipts, outlays and
14
- the deficit for the fiscal year (MTS Table 1 Year-to-Date, or Table 9 totals), and against the prior
15
- year. Often as a share of GDP. Benchmark: Treasury's final MTS for September, and CBO's Monthly Budget Review.
16
- - **Fiscal year to date:** "How is FY2026 going so far?" Compare the same months of the prior year (October
17
- through the latest month), never a partial year with a full year.
18
- - **Composition:** "Where does the money come from and go?" Receipts by source and outlays by function (MTS
19
- Table 9): levels, shares of the total and changes.
20
- - **Interest costs:** "How fast is interest on the debt rising?" Measures: net interest outlays (MTS Table 9,
21
- the budget measure) or gross interest expense (`interest_expense`), the average interest rate on
22
- interest-bearing debt, and interest as a share of outlays or receipts. Decompose growth into the debt-level
23
- effect and the rate effect when asked why.
24
- - **Cash and the debt limit:** "How much cash does Treasury have?" The TGA closing balance (DTS) and debt
25
- subject to limit; mind the 2022 DTS format change.
26
- - **Borrowing and auctions:** gross issuance and redemptions (DTS), auction sizes, yields and bid-to-cover by
27
- security type and term.
28
- - **Exchange rates:** the Treasury reporting rate for a currency over time (not market rates).
29
-
30
- ## Critical questions bank
31
-
32
- Ask only the ones that would change a headline number for this request, at most four, in one round,
33
- with "Don't know — decide for me" on each and the recommended option first. Skip what the request
34
- already settles.
35
-
36
- | Choice | Ask when | Options (recommended first, typical) | How to decide empirically when the user doesn't know |
37
- |---|---|---|---|
38
- | **Period basis** | annual figures for budget flows or year-end stocks | Federal fiscal year (Oct–Sep) · Calendar year | Fiscal year for budget measures (precedent: MTS, CBO, OMB); calendar year only to match a calendar-year comparison (GDP from the World Bank, a calendar-year report) |
39
- | **Time span** | the request names no years | last 10 complete fiscal years · since 2015 (MTS API start) · longest available | 10 complete years; include the current partial year only as "year to date" against the same months a year earlier. For **change** over "the past decade / N years", compare endpoints N years apart (latest complete FY vs. latest − N, so N + 1 years shown); for lists or totals, use the N latest complete years. Name the years either way |
40
- | **Debt measure** | any debt question | Debt held by the public · Total public debt outstanding · Debt subject to limit | Held by the public for economic analysis (CBO precedent); total for "the national debt" in plain usage; report both when unsure and say how they differ |
41
- | **Dollar basis** | comparisons across more than about 3 years, or "real" growth | Nominal · Real (CPI-U, latest full fiscal year dollars) · Share of GDP | Nominal for levels people quote; add real or % of GDP when growth over a decade or more is the point; run both and say whether the conclusion changes |
42
- | **Stock: end of period or average** | yearly or monthly debt, cash, rates | End of period · Period average | End of fiscal year (matches published year-end figures); show the average as a sensitivity when the series is volatile (TGA cash) |
43
- | **Interest measure** | interest questions | Net interest (MTS, budget) · Gross interest expense (`interest_expense`) · Interest on debt held by the public only | Net interest for budget questions; gross for "what Treasury pays"; public-issues expense for market-facing costs; state the choice in notes |
44
- | **Gross or net** | receipts or outlays | Net (budget convention) · Gross | Net: it is what the MTS totals and CBO report |
45
- | **Partial latest period** | the latest fiscal year is incomplete | Fiscal year to date vs. same months last year · Exclude it · Trailing 12 months | FYTD against the same months; trailing-12-month totals for trend charts |
46
- | **Product** | the user did not ask for a report | Short answer + data (default) · Full HTML report · Data files only | The default; offer the report in one line |
47
- | **Audience and organization** | a report is wanted | Neutral analyst product · Named organization | Neutral unless the user names one |
48
-
49
- Questions that are **not** critical (decide and record them): CSV vs JSON, field selection, chart type,
50
- rounding, the exact endpoint when two give identical published totals.
51
-
52
- ## Conventions to follow
53
-
54
- **Periods and timing**
55
- - The federal fiscal year runs October 1 to September 30 and is named for the year it ends. Write
56
- "fiscal year 2025" in prose (style guide), "FY2025" only in tables and charts.
57
- - `record_date` is the reporting date (month end for the MTS, business day for the DTS and Debt to the
58
- Penny). The MTS for September is the final, full-year statement; it is published in mid-October.
59
- - Say how current the data are: "data through September 30, 2025, retrieved October 19, 2026".
60
- - Fix the cut-off in the spec (`as_of`) so reruns return the same rows.
61
-
62
- **Stocks and flows**
63
- - Stocks (debt, cash, rates): take the end-of-period value (`period_end`) or the average (`period_mean`).
64
- Never sum them.
65
- - Flows (receipts, outlays, deficit, interest): sum monthly values (`period_sum`, check `complete`), or read
66
- the September fiscal-year-to-date value. Never sum fiscal-year-to-date values across months.
67
-
68
- **Tying to published totals**
69
- - Every component breakdown must add to its published total (`check_total`), and every headline should
70
- match the official statement for the same date (the MTS, MSPD or DTS PDF, or Treasury's press summary).
71
- State the benchmark in Data and Methods. A difference above rounding means a filter or hierarchy mistake.
72
- When the downloaded table is itself the statement's total, check the internal identities instead, plus
73
- one independent publication (press release, CBO Monthly Budget Review).
74
- - MTS tables repeat history and revise it. Use the latest release for a monthly series; use the September
75
- release for a full fiscal year.
76
-
77
- **Units and signs**
78
- - MTS tables 1-9, Debt to the Penny and interest expense are in dollars; DTS, MSPD and the long MTS series
79
- (`mts_receipts_outlays_deficit_surplus`, field `mil_amt`) are in millions. Convert once,
80
- name the unit in every exhibit subtitle ("Billions of dollars").
81
- - Deficits: MTS Table 1 and the long MTS series show a deficit as positive; MTS Table 5 shows it as negative.
82
- Pick one convention for the product ("the deficit was $1.8 trillion") and state it.
83
-
84
- **Real dollars and GDP**
85
- - Deflate with the CPI-U averaged over the same fiscal year (`compute` `to_fiscal` with `how` "mean", then
86
- `deflate`), into the dollars of the latest complete fiscal year; name the index and base year in notes.
87
- - Fiscal-year GDP is the average of the four quarterly seasonally adjusted annual rates from October to
88
- September (`to_fiscal` with `freq` "Q", `how` "mean"). Calendar-year GDP (World Bank fallback) does not match fiscal-year budget totals;
89
- if only that is available, say so or use calendar-year flows.
90
- - An incomplete period (the `complete` flag is False; `to_fiscal` notes it) is provisional: say so
91
- in the text and the exhibit notes, with its coverage ("GDP for three of four quarters"). In October the
92
- latest fiscal year usually lacks GDP's July–September quarter, so its share of GDP is provisional.
93
-
94
- **Revisions and provenance**
95
- - Treasury revises some values in later releases. Record the retrieval date (it is in `data/treasury/README.md`)
96
- and note revisions when a comparison spans releases.
97
-
98
- ## Publication structure (mirrored in `build_report`, `"mode": "report"`)
99
-
100
- The default layout, the **exhibit chartbook**, runs in this order:
101
- 1. **Cover:** "Month Year", the title (with the period for trend reports), and a hero chart.
102
- 2. **At a Glance** (one page of about 300–420 words): one framing paragraph (what was examined, the measures,
103
- the period), then 3–5 bullets, each opening with a **bold lead phrase.** that names a section, followed by
104
- 2–4 sentences with the key numbers.
105
- 3. **Contents** and **List of Exhibits** (built automatically).
106
- 4. **Notes About This Report:** fiscal years; rounding; nominal or real dollars (index and base year); the
107
- data source and retrieval date; sign conventions; partial-year coverage; a pointer to Appendix A.
108
- 5. **Introduction:** a lead paragraph with the headline numbers; question-style subheadings, one per section
109
- ("How Did Interest Costs Change?"); then "What Data Were Used?" and, when updating earlier work,
110
- "How Do These Estimates Compare With Published Figures?".
111
- 6. **Thematic sections** (2–5): each opens with 1–3 summary paragraphs, then one exhibit per page with 2–4
112
- narrative paragraphs beside the chart (level, change, comparison; "see Exhibit 3").
113
- 7. **Appendix A: Data and Methods:** endpoints and rows used, filters, the cut-off date, stock/flow treatment,
114
- period basis, deflator, benchmark comparison with the published statement, revisions, limitations.
115
- 8. **About This Document** (optional).
116
-
117
- Use `"mode": "paper"` for a prose-led product with the exhibits in the running text.
118
-
119
- ## Chart forms
120
- - Trends over fiscal years: line charts (debt, interest, rates) or columns (annual deficits), at most 4–5
121
- series. Trailing-12-month lines suit monthly flows, which are very seasonal (April tax receipts).
122
- - Composition (receipts by source, outlays by function): horizontal bars for one year, sorted; stacked
123
- columns for change over time with at most about 6 groups plus "Other".
124
- - Deficits: columns with the sign convention stated; surpluses below zero if shown as negative deficits.
125
- - No dual axes, no pie charts, no 3-D. Scale amounts to billions or trillions in the exhibit CSV and name
126
- the unit in the subtitle.
1
+ # Analysis and report patterns for federal fiscal data
2
+
3
+ Use this file to frame the analysis, choose the critical questions, and shape the product. The aim is
4
+ work a careful budget analyst would recognize: the right measure (stock or flow, gross or net), the
5
+ right period (fiscal or calendar year, complete or partial), stated units and dollar basis, numbers that
6
+ tie to the published statement, and limitations stated plainly.
7
+
8
+ ## Typical questions and how they are framed
9
+
10
+ - **Debt level and growth:** "How much has the debt grown since 2015?" Measures: total public debt
11
+ outstanding and debt held by the public (Debt to the Penny) at fiscal-year ends; growth in dollars, in
12
+ percent and per year (CAGR). Benchmark: the September Monthly Statement of the Public Debt.
13
+ - **Deficits:** "What was the deficit in FY2025, and how does it compare?" Measures: receipts, outlays and
14
+ the deficit for the fiscal year (MTS Table 1 Year-to-Date, or Table 9 totals), and against the prior
15
+ year. Often as a share of GDP. Benchmark: Treasury's final MTS for September, and CBO's Monthly Budget Review.
16
+ - **Fiscal year to date:** "How is FY2026 going so far?" Compare the same months of the prior year (October
17
+ through the latest month), never a partial year with a full year.
18
+ - **Composition:** "Where does the money come from and go?" Receipts by source and outlays by function (MTS
19
+ Table 9): levels, shares of the total and changes.
20
+ - **Interest costs:** "How fast is interest on the debt rising?" Measures: net interest outlays (MTS Table 9,
21
+ the budget measure) or gross interest expense (`interest_expense`), the average interest rate on
22
+ interest-bearing debt, and interest as a share of outlays or receipts. Decompose growth into the debt-level
23
+ effect and the rate effect when asked why.
24
+ - **Cash and the debt limit:** "How much cash does Treasury have?" The TGA closing balance (DTS) and debt
25
+ subject to limit; mind the 2022 DTS format change.
26
+ - **Borrowing and auctions:** gross issuance and redemptions (DTS), auction sizes, yields and bid-to-cover by
27
+ security type and term.
28
+ - **Exchange rates:** the Treasury reporting rate for a currency over time (not market rates).
29
+
30
+ ## Critical questions bank
31
+
32
+ Ask only the ones that would change a headline number for this request, at most four, in one round,
33
+ with "Don't know — decide for me" on each and the recommended option first. Skip what the request
34
+ already settles.
35
+
36
+ | Choice | Ask when | Options (recommended first, typical) | How to decide empirically when the user doesn't know |
37
+ |---|---|---|---|
38
+ | **Period basis** | annual figures for budget flows or year-end stocks | Federal fiscal year (Oct–Sep) · Calendar year | Fiscal year for budget measures (precedent: MTS, CBO, OMB); calendar year only to match a calendar-year comparison (GDP from the World Bank, a calendar-year report) |
39
+ | **Time span** | the request names no years | last 10 complete fiscal years · since 2015 (MTS API start) · longest available | 10 complete years; include the current partial year only as "year to date" against the same months a year earlier. For **change** over "the past decade / N years", compare endpoints N years apart (latest complete FY vs. latest − N, so N + 1 years shown); for lists or totals, use the N latest complete years. Name the years either way |
40
+ | **Debt measure** | any debt question | Debt held by the public · Total public debt outstanding · Debt subject to limit | Held by the public for economic analysis (CBO precedent); total for "the national debt" in plain usage; report both when unsure and say how they differ |
41
+ | **Dollar basis** | comparisons across more than about 3 years, or "real" growth | Nominal · Real (CPI-U, latest full fiscal year dollars) · Share of GDP | Nominal for levels people quote; add real or % of GDP when growth over a decade or more is the point; run both and say whether the conclusion changes |
42
+ | **Stock: end of period or average** | yearly or monthly debt, cash, rates | End of period · Period average | End of fiscal year (matches published year-end figures); show the average as a sensitivity when the series is volatile (TGA cash) |
43
+ | **Interest measure** | interest questions | Net interest (MTS, budget) · Gross interest expense (`interest_expense`) · Interest on debt held by the public only | Net interest for budget questions; gross for "what Treasury pays"; public-issues expense for market-facing costs; state the choice in notes |
44
+ | **Gross or net** | receipts or outlays | Net (budget convention) · Gross | Net: it is what the MTS totals and CBO report |
45
+ | **Partial latest period** | the latest fiscal year is incomplete | Fiscal year to date vs. same months last year · Exclude it · Trailing 12 months | FYTD against the same months; trailing-12-month totals for trend charts |
46
+ | **Product** | the user did not ask for a report | Short answer + data (default) · Full HTML report · Data files only | The default; offer the report in one line |
47
+ | **Audience and organization** | a report is wanted | Neutral analyst product · Named organization | Neutral unless the user names one |
48
+
49
+ Questions that are **not** critical (decide and record them): CSV vs JSON, field selection, chart type,
50
+ rounding, the exact endpoint when two give identical published totals.
51
+
52
+ ## Conventions to follow
53
+
54
+ **Periods and timing**
55
+ - The federal fiscal year runs October 1 to September 30 and is named for the year it ends. Write
56
+ "fiscal year 2025" in prose (style guide), "FY2025" only in tables and charts.
57
+ - `record_date` is the reporting date (month end for the MTS, business day for the DTS and Debt to the
58
+ Penny). The MTS for September is the final, full-year statement; it is published in mid-October.
59
+ - Say how current the data are: "data through September 30, 2025, retrieved October 19, 2026".
60
+ - Fix the cut-off in the spec (`as_of`) so reruns return the same rows.
61
+
62
+ **Stocks and flows**
63
+ - Stocks (debt, cash, rates): take the end-of-period value (`period_end`) or the average (`period_mean`).
64
+ Never sum them.
65
+ - Flows (receipts, outlays, deficit, interest): sum monthly values (`period_sum`, check `complete`), or read
66
+ the September fiscal-year-to-date value. Never sum fiscal-year-to-date values across months.
67
+
68
+ **Tying to published totals**
69
+ - Every component breakdown must add to its published total (`check_total`), and every headline should
70
+ match the official statement for the same date (the MTS, MSPD or DTS PDF, or Treasury's press summary).
71
+ State the benchmark in Data and Methods. A difference above rounding means a filter or hierarchy mistake.
72
+ When the downloaded table is itself the statement's total, check the internal identities instead, plus
73
+ one independent publication (press release, CBO Monthly Budget Review).
74
+ - MTS tables repeat history and revise it. Use the latest release for a monthly series; use the September
75
+ release for a full fiscal year.
76
+
77
+ **Units and signs**
78
+ - MTS tables 1-9, Debt to the Penny and interest expense are in dollars; DTS, MSPD and the long MTS series
79
+ (`mts_receipts_outlays_deficit_surplus`, field `mil_amt`) are in millions. Convert once,
80
+ name the unit in every exhibit subtitle ("Billions of dollars").
81
+ - Deficits: MTS Table 1 and the long MTS series show a deficit as positive; MTS Table 5 shows it as negative.
82
+ Pick one convention for the product ("the deficit was $1.8 trillion") and state it.
83
+
84
+ **Real dollars and GDP**
85
+ - Deflate with the CPI-U averaged over the same fiscal year (`compute` `to_fiscal` with `how` "mean", then
86
+ `deflate`), into the dollars of the latest complete fiscal year; name the index and base year in notes.
87
+ - Fiscal-year GDP is the average of the four quarterly seasonally adjusted annual rates from October to
88
+ September (`to_fiscal` with `freq` "Q", `how` "mean"). Calendar-year GDP (World Bank fallback) does not match fiscal-year budget totals;
89
+ if only that is available, say so or use calendar-year flows.
90
+ - An incomplete period (the `complete` flag is False; `to_fiscal` notes it) is provisional: say so
91
+ in the text and the exhibit notes, with its coverage ("GDP for three of four quarters"). In October the
92
+ latest fiscal year usually lacks GDP's July–September quarter, so its share of GDP is provisional.
93
+
94
+ **Revisions and provenance**
95
+ - Treasury revises some values in later releases. Record the retrieval date (it is in `data/treasury/README.md`)
96
+ and note revisions when a comparison spans releases.
97
+
98
+ ## Publication structure (mirrored in `build_report`, `"mode": "report"`)
99
+
100
+ The default layout, the **exhibit chartbook**, runs in this order:
101
+ 1. **Cover:** "Month Year", the title (with the period for trend reports), and a hero chart.
102
+ 2. **At a Glance** (one page of about 300–420 words): one framing paragraph (what was examined, the measures,
103
+ the period), then 3–5 bullets, each opening with a **bold lead phrase.** that names a section, followed by
104
+ 2–4 sentences with the key numbers.
105
+ 3. **Contents** and **List of Exhibits** (built automatically).
106
+ 4. **Notes About This Report:** fiscal years; rounding; nominal or real dollars (index and base year); the
107
+ data source and retrieval date; sign conventions; partial-year coverage; a pointer to Appendix A.
108
+ 5. **Introduction:** a lead paragraph with the headline numbers; question-style subheadings, one per section
109
+ ("How Did Interest Costs Change?"); then "What Data Were Used?" and, when updating earlier work,
110
+ "How Do These Estimates Compare With Published Figures?".
111
+ 6. **Thematic sections** (2–5): each opens with 1–3 summary paragraphs, then one exhibit per page with 2–4
112
+ narrative paragraphs beside the chart (level, change, comparison; "see Exhibit 3").
113
+ 7. **Appendix A: Data and Methods:** endpoints and rows used, filters, the cut-off date, stock/flow treatment,
114
+ period basis, deflator, benchmark comparison with the published statement, revisions, limitations.
115
+ 8. **About This Document** (optional).
116
+
117
+ Use `"mode": "paper"` for a prose-led product with the exhibits in the running text.
118
+
119
+ ## Chart forms
120
+ - Trends over fiscal years: line charts (debt, interest, rates) or columns (annual deficits), at most 4–5
121
+ series. Trailing-12-month lines suit monthly flows, which are very seasonal (April tax receipts).
122
+ - Composition (receipts by source, outlays by function): horizontal bars for one year, sorted; stacked
123
+ columns for change over time with at most about 6 groups plus "Other".
124
+ - Deficits: columns with the sign convention stated; surpluses below zero if shown as negative deficits.
125
+ - No dual axes, no pie charts, no 3-D. Scale amounts to billions or trillions in the exhibit CSV and name
126
+ the unit in the subtitle.