fpds-os-analytics-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fpds_os_analytics_mcp-0.1.0/LICENSE +21 -0
- fpds_os_analytics_mcp-0.1.0/PKG-INFO +541 -0
- fpds_os_analytics_mcp-0.1.0/README.md +515 -0
- fpds_os_analytics_mcp-0.1.0/fpds_os_analytics_mcp.egg-info/PKG-INFO +541 -0
- fpds_os_analytics_mcp-0.1.0/fpds_os_analytics_mcp.egg-info/SOURCES.txt +11 -0
- fpds_os_analytics_mcp-0.1.0/fpds_os_analytics_mcp.egg-info/dependency_links.txt +1 -0
- fpds_os_analytics_mcp-0.1.0/fpds_os_analytics_mcp.egg-info/entry_points.txt +2 -0
- fpds_os_analytics_mcp-0.1.0/fpds_os_analytics_mcp.egg-info/top_level.txt +1 -0
- fpds_os_analytics_mcp-0.1.0/mcp/__init__.py +1 -0
- fpds_os_analytics_mcp-0.1.0/mcp/fpds_mcp_server.py +428 -0
- fpds_os_analytics_mcp-0.1.0/pyproject.toml +40 -0
- fpds_os_analytics_mcp-0.1.0/setup.cfg +4 -0
- fpds_os_analytics_mcp-0.1.0/tests/test_catalog_contract.py +1410 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kenosa Consulting
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,541 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fpds-os-analytics-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for the FPDS Analytics API — federal procurement intelligence for AI agents.
|
|
5
|
+
Author-email: Kenosa Consulting <oogway@kenosaconsulting.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/KenosaConsulting/fpds-os-analytics
|
|
8
|
+
Project-URL: Repository, https://github.com/KenosaConsulting/fpds-os-analytics
|
|
9
|
+
Project-URL: Documentation, https://analytics-api.kenosaconsulting.com/docs
|
|
10
|
+
Project-URL: API Key, https://kenosaconsulting.com/api
|
|
11
|
+
Keywords: mcp,fpds,federal procurement,government contracts,govcon,analytics
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
╔═══════════════════════════════════════════════════════════════════╗
|
|
29
|
+
║ ║
|
|
30
|
+
║ ███████ ██████ ██████ ███████ ║
|
|
31
|
+
║ ██ ██ ██ ██ ██ ██ Federal Procurement ║
|
|
32
|
+
║ █████ ██████ ██ ██ ███████ Data Science ║
|
|
33
|
+
║ ██ ██ ██ ██ ██ ║
|
|
34
|
+
║ ██ ██ ██████ ███████ Analytics API ║
|
|
35
|
+
║ ║
|
|
36
|
+
║ ▁▂▃▄▅▆▇ COMPETITIVE INTELLIGENCE ENGINE ▇▆▅▄▃▂▁ ║
|
|
37
|
+
║ ║
|
|
38
|
+
║ ┌───────────────────────────────────────────────────────┐ ║
|
|
39
|
+
║ │ 79 datasets · 16 dimensions · 99M+ federal actions │ ║
|
|
40
|
+
║ │ REST + MCP · MIT License · Zero config to start │ ║
|
|
41
|
+
║ └───────────────────────────────────────────────────────┘ ║
|
|
42
|
+
║ ║
|
|
43
|
+
╚═══════════════════════════════════════════════════════════════════╝
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
> **The federal government spends $700+ billion a year on contracts.
|
|
47
|
+
> Every transaction is public record.
|
|
48
|
+
> Contractors don't need raw data, they need to make decisions.**
|
|
49
|
+
|
|
50
|
+
This API turns 99 million FPDS contract actions into the
|
|
51
|
+
intelligence that wins proposals — pricing patterns, incumbent maps, market
|
|
52
|
+
entry difficulty scores, vehicle-program winners, recompete timelines, and 74
|
|
53
|
+
more analytics datasets — ready to query from a single endpoint.
|
|
54
|
+
|
|
55
|
+
No database to run. No data to download. No PhD required.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## ⚡ Three Commands to Your First Insight
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
# See what's available
|
|
63
|
+
curl -s "https://analytics-api.kenosaconsulting.com/v1/catalog" | jq '.data[].id'
|
|
64
|
+
|
|
65
|
+
# Who dominates Army IT services?
|
|
66
|
+
curl -s "https://analytics-api.kenosaconsulting.com/v1/datasets/concentration.vendor_market_leaders/rows?contracting_dept_id=9700&principal_naics_code=541512&limit=10" | jq '.data'
|
|
67
|
+
|
|
68
|
+
# What's expiring in the next 12 months?
|
|
69
|
+
curl -s "https://analytics-api.kenosaconsulting.com/v1/datasets/pipeline.recompete_watchlist/rows?contracting_dept_id=9700&remaining_months_max=12&limit=10" | jq '.data'
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That's it. You're doing market intelligence now.
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 🎯 What Problem This Solves
|
|
77
|
+
|
|
78
|
+
Every government contractor faces the same challenge: **the data is free but
|
|
79
|
+
the analysis is expensive.**
|
|
80
|
+
|
|
81
|
+
FPDS (the Federal Procurement Data System) publishes every contract action the
|
|
82
|
+
US government makes. It's public. It's comprehensive. And it's also 99 million rows
|
|
83
|
+
of coded, transaction-level records that tell you almost nothing useful unless
|
|
84
|
+
you already know what you're looking for. Try digging through over 37,000,000,000 data points and tell me if you want to go the brute force route...
|
|
85
|
+
|
|
86
|
+
Most contractors solve this by paying five- or six-figure subscriptions to
|
|
87
|
+
platforms that repackage the same public data behind login walls. Or they assign
|
|
88
|
+
a human analyst to spend weeks in spreadsheets. Or they guess.
|
|
89
|
+
|
|
90
|
+
**This API is a different approach.** We pre-compute the analytical questions
|
|
91
|
+
that actually matter for capture strategy — and serve the answers as clean,
|
|
92
|
+
filterable, documented datasets with human-readable labels, metadata, caveats,
|
|
93
|
+
and enough context for an analyst (human or AI) to draw conclusions without
|
|
94
|
+
touching raw data.
|
|
95
|
+
|
|
96
|
+
Think of it this way:
|
|
97
|
+
|
|
98
|
+
> 📖 FPDS is the Atlas. This API is GPS.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 🧬 What You Get: 14 Intelligence Packages
|
|
103
|
+
|
|
104
|
+
Each package answers a strategic question. Each contains multiple datasets
|
|
105
|
+
tuned for different grains and use cases.
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
109
|
+
│ │
|
|
110
|
+
│ PACKAGE QUESTION IT ANSWERS │
|
|
111
|
+
│ ═══════ ════════════════════ │
|
|
112
|
+
│ │
|
|
113
|
+
│ Pricing Strategy How does this customer prefer to buy? │
|
|
114
|
+
│ Vendor Concentration Who already owns this market? │
|
|
115
|
+
│ Competition Dynamics Can a new vendor actually get in? │
|
|
116
|
+
│ Industry / NAICS Demand What work is growing — and where? │
|
|
117
|
+
│ Geography Does local presence matter here? │
|
|
118
|
+
│ Set-Aside Programs Which small-biz programs get used? │
|
|
119
|
+
│ PSC Classification What exactly do they buy? │
|
|
120
|
+
│ Vehicle Mix Do I need a GWAC, Schedule, or IDIQ? │
|
|
121
|
+
│ Vehicle Programs Which exact OASIS / SEWP / MAS paths? │
|
|
122
|
+
│ Funding Flows Who funds the work vs. who buys it? │
|
|
123
|
+
│ Recompete Pipeline What contracts are expiring soon? │
|
|
124
|
+
│ Contracting Officers Who handles the buying — and how? │
|
|
125
|
+
│ Fiscal Seasonality When does this customer spend? │
|
|
126
|
+
│ Topic Intelligence What sub-markets exist in this NAICS? │
|
|
127
|
+
│ │
|
|
128
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The **Contracting Officers** package is a unique differentiator — no competing
|
|
132
|
+
platform maps individual procurement personnel to their buying behavior,
|
|
133
|
+
NAICS specialties, set-aside tendencies, and contract history. Six datasets
|
|
134
|
+
cover office rosters, per-CO year-over-year profiles, NAICS buyer maps,
|
|
135
|
+
recompete contract handlers, and human-attribution coverage per office.
|
|
136
|
+
The enhanced Recompete Pipeline now shows who created and approved each
|
|
137
|
+
expiring contract.
|
|
138
|
+
|
|
139
|
+
The **Topic Intelligence** package is the first machine-derived procurement
|
|
140
|
+
topic layer across the federal government — 24,000+ topics discovered by
|
|
141
|
+
BERTopic decomposing broad NAICS codes into the actual sub-markets
|
|
142
|
+
agencies buy. 11 datasets cover topic catalogs, NAICS/PSC decomposition,
|
|
143
|
+
set-aside and contract-type profiles, YoY trends, competitive landscape
|
|
144
|
+
(all vendors, no cap), document links to strategic plans, and 4,969
|
|
145
|
+
govwide canonical topics clustered across 30 departments.
|
|
146
|
+
|
|
147
|
+
Plus four **cross-cutting analytics** that don't belong to a single package:
|
|
148
|
+
|
|
149
|
+
| Dataset | What it tells you |
|
|
150
|
+
|---|---|
|
|
151
|
+
| **Customer 360 Profile** | One endpoint, eight analytical sections — spend trends, competition posture, incumbent map, pricing mix, vehicle preferences, recompete signals, all assembled for a single customer |
|
|
152
|
+
| **New-Entrant Cohorts** | How many new vendors enter each market per year, their first-win characteristics, set-aside paths, and 2-year survival rates |
|
|
153
|
+
| **Market Entry Difficulty** | A composite score blending HHI concentration, sole-source share, vehicle dependence, average offers received, and incumbent tenure — one number that says "how hard is this market to crack" |
|
|
154
|
+
| **Award-Size Distribution** | Median, P25, and P75 award sizes by agency × NAICS, plus under-SAT (simplified acquisition threshold) share |
|
|
155
|
+
|
|
156
|
+
**78 datasets. 16 code-lookup dimensions. Every query bounded, parameterized,
|
|
157
|
+
and documented.**
|
|
158
|
+
|
|
159
|
+
### Vehicle-program deployment note
|
|
160
|
+
|
|
161
|
+
The vehicle-program package adds three dataset surfaces:
|
|
162
|
+
`acquisition.vehicle_program_usage_fy`,
|
|
163
|
+
`acquisition.vehicle_program_summary`, and
|
|
164
|
+
`acquisition.vehicle_program_vendors`, plus the `vehicle_programs`
|
|
165
|
+
dimension. These dataset views depend on the corrected Step-4
|
|
166
|
+
`customer_intelligence.mv_fpds_vehicle_program_*_norm` materialized views.
|
|
167
|
+
If those `_norm` MVs are not present in the target database, only the
|
|
168
|
+
`vehicle_programs` dimension will be live after migration.
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## 🤖 Wire It Into Your AI — MCP Integration
|
|
173
|
+
|
|
174
|
+
The API ships with a built-in **Model Context Protocol (MCP) server** — which
|
|
175
|
+
means Claude, Cursor, Windsurf, VS Code Copilot, OpenClaw, and any MCP-compatible AI
|
|
176
|
+
assistant can query federal procurement data directly, without you writing a
|
|
177
|
+
single line of code.
|
|
178
|
+
|
|
179
|
+
**Why this matters:** Instead of copy-pasting API responses into chat windows,
|
|
180
|
+
your AI assistant becomes a procurement analyst. It can browse the catalog,
|
|
181
|
+
pick the right dataset, apply filters, interpret caveats, and explain what the
|
|
182
|
+
data means for your capture strategy — all in natural language.
|
|
183
|
+
|
|
184
|
+
### Two Ways to Connect
|
|
185
|
+
|
|
186
|
+
**Option A — Remote MCP (zero install):**
|
|
187
|
+
|
|
188
|
+
Point your AI client at the hosted endpoint. No Python, no repo clone.
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{
|
|
192
|
+
"mcpServers": {
|
|
193
|
+
"fpds-analytics": {
|
|
194
|
+
"url": "https://analytics-api.kenosaconsulting.com/v1/mcp",
|
|
195
|
+
"transport": "http"
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
**Option B — Local stdio (pip install):**
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
pip install fpds-os-analytics-mcp
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
```json
|
|
208
|
+
{
|
|
209
|
+
"mcpServers": {
|
|
210
|
+
"fpds-analytics": {
|
|
211
|
+
"command": "fpds-mcp",
|
|
212
|
+
"env": {
|
|
213
|
+
"FPDS_API_BASE_URL": "https://analytics-api.kenosaconsulting.com"
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
**No API key required** for bounded public queries. Add an `X-Api-Key` header
|
|
221
|
+
for higher rate limits and larger result sets. Get a key at
|
|
222
|
+
[kenosaconsulting.com/api](https://kenosaconsulting.com/api).
|
|
223
|
+
|
|
224
|
+
For full setup instructions including OpenClaw, Claude Desktop, Cursor, and
|
|
225
|
+
VS Code configurations, see **[docs/OPENCLAW_INTEGRATION.md](docs/OPENCLAW_INTEGRATION.md)**.
|
|
226
|
+
|
|
227
|
+
### Pre-built Skills
|
|
228
|
+
|
|
229
|
+
The repo includes 5 ready-to-use skills for common govcon activities:
|
|
230
|
+
|
|
231
|
+
| Skill | Activity |
|
|
232
|
+
|---|---|
|
|
233
|
+
| [`vendor-market-analysis`](skills/vendor-market-analysis/SKILL.md) | Competitive landscape analysis |
|
|
234
|
+
| [`recompete-pipeline`](skills/recompete-pipeline/SKILL.md) | Expiring contract watchlist |
|
|
235
|
+
| [`contracting-officer-patterns`](skills/contracting-officer-patterns/SKILL.md) | Office buying patterns + contacts |
|
|
236
|
+
| [`account-plan-builder`](skills/account-plan-builder/SKILL.md) | Structured account plan |
|
|
237
|
+
| [`naics-opportunity-scan`](skills/naics-opportunity-scan/SKILL.md) | Growth opportunities by NAICS |
|
|
238
|
+
|
|
239
|
+
See [`skills/README.md`](skills/README.md) for the full catalog.
|
|
240
|
+
|
|
241
|
+
### What Your AI Can Do Once Connected
|
|
242
|
+
|
|
243
|
+
| MCP Tool | What it does |
|
|
244
|
+
|---|---|
|
|
245
|
+
| `fpds_list_datasets` | Browse all 61 analytics datasets with descriptions |
|
|
246
|
+
| `fpds_describe_dataset` | See fields, filters, sorts, caveats, and example queries for any dataset |
|
|
247
|
+
| `fpds_query_dataset` | Query rows with filters, sorting, and pagination |
|
|
248
|
+
| `fpds_list_dimensions` | Browse code-lookup tables (agencies, NAICS, PSC, etc.) |
|
|
249
|
+
| `fpds_lookup_dimension` | Translate coded values to human-readable names |
|
|
250
|
+
| `fpds_resolve` | Search by name across agencies, offices, NAICS, PSC, departments, and vehicle programs |
|
|
251
|
+
| `fpds_customer_profile` | Get a full Customer 360 profile — eight analytical sections in one call |
|
|
252
|
+
|
|
253
|
+
**Try asking your AI:**
|
|
254
|
+
|
|
255
|
+
> "Who are the top 5 incumbent vendors for Army cybersecurity contracts?"
|
|
256
|
+
|
|
257
|
+
> "Show me NAICS codes that are growing fastest at the Department of Energy."
|
|
258
|
+
|
|
259
|
+
> "What contracts at HHS are expiring in the next 6 months and worth over $10M?"
|
|
260
|
+
|
|
261
|
+
> "Give me a competitive analysis for entering the Navy's IT services market."
|
|
262
|
+
|
|
263
|
+
The AI will pick the right dataset, apply filters, and interpret the results —
|
|
264
|
+
including caveats about data limitations, current fiscal year incompleteness,
|
|
265
|
+
and deobligation effects.
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## 🔬 The Capture Strategist's Workflow
|
|
270
|
+
|
|
271
|
+
This is the path from "I want to win federal work" to "here's exactly who to
|
|
272
|
+
target, why, and when":
|
|
273
|
+
|
|
274
|
+
```
|
|
275
|
+
Step 1 What's growing?
|
|
276
|
+
────── naics.growth_leaders → Find NAICS markets with rising demand
|
|
277
|
+
|
|
278
|
+
Step 2 Who's buying it?
|
|
279
|
+
────── naics.agency_profile_fy → Match growing markets to agencies
|
|
280
|
+
|
|
281
|
+
Step 3 Can I get in?
|
|
282
|
+
────── market.entry_difficulty_score → One number: how hard is entry?
|
|
283
|
+
competition.agency_profile_fy → Competed vs. sole-source split
|
|
284
|
+
|
|
285
|
+
Step 4 Who's already there?
|
|
286
|
+
────── concentration.vendor_market_leaders → Incumbent map with HHI
|
|
287
|
+
entrants.agency_cohort_fy → How do new vendors fare here?
|
|
288
|
+
|
|
289
|
+
Step 5 How do they buy?
|
|
290
|
+
────── pricing.agency_profile_fy → Fixed-price vs. cost-type mix
|
|
291
|
+
acquisition.agency_vehicle_mix_fy → GWAC / Schedule / IDIQ
|
|
292
|
+
|
|
293
|
+
Step 6 What's expiring?
|
|
294
|
+
────── pipeline.recompete_watchlist → Contracts ending in 6–24 months
|
|
295
|
+
pipeline.duration_profile → Typical contract lengths
|
|
296
|
+
|
|
297
|
+
Step 7 When do they spend?
|
|
298
|
+
────── seasonality.agency_month_fy → Fiscal-month obligation patterns
|
|
299
|
+
→ Q4 spike? Time your white papers accordingly
|
|
300
|
+
|
|
301
|
+
Step 8 Where's the work?
|
|
302
|
+
────── geography.city_leaders → Sub-state drill-down
|
|
303
|
+
geography.mismatch_leaders → Vendor HQ vs. performance site
|
|
304
|
+
|
|
305
|
+
Step 9 What exactly do they buy — beyond NAICS?
|
|
306
|
+
────── topics.naics_decomposition → Sub-markets within a NAICS code
|
|
307
|
+
topics.competitive_landscape → Who dominates each sub-market?
|
|
308
|
+
topics.trends → Which sub-markets are growing/declining?
|
|
309
|
+
|
|
310
|
+
Step 10 One-call summary
|
|
311
|
+
────── GET /v1/profiles/customer → Full Customer 360 in one request
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
> **The goal:** Who should we target, why them, how hard will entry be, what's
|
|
315
|
+
> expiring soon, what sub-markets are growing, and what customer-specific
|
|
316
|
+
> story should we tell in the proposal?
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
## 🎮 Use It Without Code
|
|
321
|
+
|
|
322
|
+
### With Any AI Assistant (No MCP Required)
|
|
323
|
+
|
|
324
|
+
Paste this into ChatGPT, Claude, Gemini, or any AI that can make HTTP requests:
|
|
325
|
+
|
|
326
|
+
```text
|
|
327
|
+
Use the FPDS Analytics API to help me understand federal procurement customers.
|
|
328
|
+
API base: https://analytics-api.kenosaconsulting.com
|
|
329
|
+
|
|
330
|
+
Start by calling GET /v1/ai-assistant-guide for instructions.
|
|
331
|
+
Then GET /v1/catalog to see available datasets.
|
|
332
|
+
Use only documented filters, sorts, and fields.
|
|
333
|
+
Explain what the data means for capture strategy.
|
|
334
|
+
Always include API caveats and never invent data.
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
### With CSV Export
|
|
338
|
+
|
|
339
|
+
Any dataset query supports `?format=csv` for direct spreadsheet use:
|
|
340
|
+
|
|
341
|
+
```bash
|
|
342
|
+
curl -s "https://analytics-api.kenosaconsulting.com/v1/datasets/naics.growth_leaders/rows?limit=50&format=csv" > growth_leaders.csv
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
### With the REST API Directly
|
|
346
|
+
|
|
347
|
+
Every endpoint is documented with example queries in the catalog:
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
# Describe a dataset (see fields, filters, example queries, caveats)
|
|
351
|
+
curl -s "https://analytics-api.kenosaconsulting.com/v1/datasets/competition.sole_source_hotspots" | jq
|
|
352
|
+
|
|
353
|
+
# Query with filters and sorting
|
|
354
|
+
curl -s "https://analytics-api.kenosaconsulting.com/v1/datasets/pricing.agency_profile_fy/rows?contracting_dept_id=9700&fiscal_year=2025&sort=-total_obligated&limit=25" | jq '.data'
|
|
355
|
+
|
|
356
|
+
# Look up a NAICS code by name
|
|
357
|
+
curl -s "https://analytics-api.kenosaconsulting.com/v1/dimensions/naics?q=cybersecurity" | jq '.data'
|
|
358
|
+
|
|
359
|
+
# Full customer profile in one call
|
|
360
|
+
curl -s "https://analytics-api.kenosaconsulting.com/v1/profiles/customer?contracting_dept_id=9700" | jq
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## 📊 Sample Response
|
|
366
|
+
|
|
367
|
+
```json
|
|
368
|
+
{
|
|
369
|
+
"notice": "FPDS analytics are decision-support indicators, not a complete procurement universe.",
|
|
370
|
+
"data": [
|
|
371
|
+
{
|
|
372
|
+
"contracting_dept_id": "9700",
|
|
373
|
+
"contracting_dept_name": "DEPT OF DEFENSE",
|
|
374
|
+
"department_short_name": "DoD",
|
|
375
|
+
"fiscal_year": 2025,
|
|
376
|
+
"is_current_fiscal_year_ytd": true,
|
|
377
|
+
"total_obligated": "125000000.00",
|
|
378
|
+
"distinct_naics_count": 12,
|
|
379
|
+
"top_naics_code_by_obligation": "541330",
|
|
380
|
+
"action_count": 42
|
|
381
|
+
}
|
|
382
|
+
],
|
|
383
|
+
"pagination": { "limit": 25, "next_cursor": null },
|
|
384
|
+
"meta": {
|
|
385
|
+
"dataset_id": "naics.trend_fy",
|
|
386
|
+
"source": "FPDS analytics schema",
|
|
387
|
+
"data_as_of": "2026-06-10T00:00:00Z",
|
|
388
|
+
"row_count": 1,
|
|
389
|
+
"access": "public"
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
Every response includes:
|
|
395
|
+
- **`notice`** — Reminds consumers this is analytical, not legal/procurement authority
|
|
396
|
+
- **`data`** — Human-readable labels alongside codes (no more guessing what `9700` means)
|
|
397
|
+
- **`meta.data_as_of`** — When the underlying data was last refreshed
|
|
398
|
+
- **`pagination`** — Bounded results with cursor support
|
|
399
|
+
|
|
400
|
+
---
|
|
401
|
+
|
|
402
|
+
## 📡 API Reference
|
|
403
|
+
|
|
404
|
+
| Function | Endpoint | Purpose |
|
|
405
|
+
|---|---|---|
|
|
406
|
+
| Service metadata | `GET /v1` | API version and status |
|
|
407
|
+
| Health check | `GET /v1/health` | Service and catalog health |
|
|
408
|
+
| AI assistant guide | `GET /v1/ai-assistant-guide` | Paste-ready instructions for any AI |
|
|
409
|
+
| List datasets | `GET /v1/catalog` | Browse all 78 analytics datasets |
|
|
410
|
+
| Describe dataset | `GET /v1/datasets/{id}` | Fields, filters, sorts, caveats, examples |
|
|
411
|
+
| Query rows | `GET /v1/datasets/{id}/rows` | Bounded analytics with filters and pagination |
|
|
412
|
+
| Customer 360 | `GET /v1/profiles/customer` | Eight-section customer intelligence profile |
|
|
413
|
+
| List dimensions | `GET /v1/dimensions` | Browse code-lookup tables |
|
|
414
|
+
| Query dimension | `GET /v1/dimensions/{id}` | Translate codes to names |
|
|
415
|
+
| Resolve by name | `GET /v1/dimensions/{id}?q=` | Search dimensions by name substring |
|
|
416
|
+
|
|
417
|
+
**Self-healing errors:** Send a bad filter? The error response tells you
|
|
418
|
+
exactly which filters are valid, which fields are sortable, and gives you an
|
|
419
|
+
example query that works. No more guessing.
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## 🏗️ Architecture
|
|
424
|
+
|
|
425
|
+
```
|
|
426
|
+
┌─────────────────────┐ ┌──────────────────┐ ┌───────────────┐
|
|
427
|
+
│ public.fpds_actions │ │ 26 SQL templates │ │ Materialized │
|
|
428
|
+
│ (99M+ rows) │─────▶│ in sql/ │─────▶│ Views + MVs │
|
|
429
|
+
│ Read-only source │ │ Run at refresh │ │ (analytics) │
|
|
430
|
+
└─────────────────────┘ └──────────────────┘ └───────┬───────┘
|
|
431
|
+
│
|
|
432
|
+
▼
|
|
433
|
+
┌─────────────────────┐ ┌──────────────────┐ ┌───────────────┐
|
|
434
|
+
│ MCP Server │ │ FastAPI app/ │ │ analytics_api │
|
|
435
|
+
│ (7 tools, stdio) │◀────▶│ Catalog-driven │◀────▶│ facade schema │
|
|
436
|
+
│ For AI assistants │ │ REST endpoints │ │ (read-only) │
|
|
437
|
+
└─────────────────────┘ └──────────────────┘ └───────────────┘
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
**Security boundary:** The API server connects as `fpds_analytics_api_readonly`
|
|
441
|
+
with `SELECT`-only access to the `analytics_api` facade schema. No raw tables,
|
|
442
|
+
no writes, no arbitrary SQL. Dataset IDs, filter names, sort keys, and row
|
|
443
|
+
limits are all validated against the catalog before any query is built.
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
## 📚 Documentation
|
|
448
|
+
|
|
449
|
+
| Document | What's in it |
|
|
450
|
+
|---|---|
|
|
451
|
+
| [CHANGELOG.md](CHANGELOG.md) | What changed and when — sprint by sprint |
|
|
452
|
+
| [docs/QUICKSTART.md](docs/QUICKSTART.md) | Your first API calls in 2 minutes |
|
|
453
|
+
| [docs/METHODOLOGY.md](docs/METHODOLOGY.md) | How every number is computed — source data, MVs, formulas |
|
|
454
|
+
| [docs/DATASETS.md](docs/DATASETS.md) | Field-by-field reference for all 78 datasets |
|
|
455
|
+
| [docs/API_FUNCTIONS.md](docs/API_FUNCTIONS.md) | Detailed endpoint documentation |
|
|
456
|
+
| [docs/AI_ASSISTANT_GUIDE.md](docs/AI_ASSISTANT_GUIDE.md) | Instructions for AI assistants |
|
|
457
|
+
| [docs/OPENCLAW_INTEGRATION.md](docs/OPENCLAW_INTEGRATION.md) | OpenClaw + MCP setup guide (remote endpoint + pip install) |
|
|
458
|
+
| [docs/LLM_INTEGRATIONS.md](docs/LLM_INTEGRATIONS.md) | MCP, ChatGPT, Claude, and Gemini integration guide |
|
|
459
|
+
| [docs/CAVEATS.md](docs/CAVEATS.md) | Data limitations you should know about |
|
|
460
|
+
| [openapi.yaml](openapi.yaml) | Machine-readable API contract (OpenAPI 3.1) |
|
|
461
|
+
| [SECURITY.md](SECURITY.md) | Security model and responsible disclosure |
|
|
462
|
+
|
|
463
|
+
---
|
|
464
|
+
|
|
465
|
+
## 🛠️ Developer Setup
|
|
466
|
+
|
|
467
|
+
```bash
|
|
468
|
+
git clone https://github.com/KenosaConsulting/fpds-os-analytics.git
|
|
469
|
+
cd fpds-os-analytics
|
|
470
|
+
python3 -m venv .venv && source .venv/bin/activate
|
|
471
|
+
pip install -r requirements.txt
|
|
472
|
+
python -m pytest tests -q # 78+ tests, should be green
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
The test suite validates catalog contracts, query guardrails, and API behavior
|
|
476
|
+
without a database connection. To run the API server against live data, see the
|
|
477
|
+
[deployment docs](docs/DEPLOYMENT.md).
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
|
|
481
|
+
## 📦 Repository Layout
|
|
482
|
+
|
|
483
|
+
```
|
|
484
|
+
fpds-os-analytics/
|
|
485
|
+
├── app/ FastAPI service (routes, query builder, catalog loader)
|
|
486
|
+
├── catalog/ Dataset + dimension registries (single source of truth)
|
|
487
|
+
│ ├── datasets.yaml 78 datasets with filters, sorts, fields, caveats
|
|
488
|
+
│ └── dimensions.yaml 16 code-lookup dimensions
|
|
489
|
+
├── mcp/ MCP server for AI assistants (7 tools, stdio transport)
|
|
490
|
+
├── sql/ 26 numbered database templates (MVs, views, indexes)
|
|
491
|
+
├── tests/ Guardrail + contract tests (78+ tests)
|
|
492
|
+
├── docs/ User and developer documentation
|
|
493
|
+
├── examples/ Example API calls
|
|
494
|
+
├── openapi.yaml OpenAPI 3.1 specification
|
|
495
|
+
├── Dockerfile Container image
|
|
496
|
+
└── run-local.sh Local development launcher
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
---
|
|
500
|
+
|
|
501
|
+
## ⚖️ Access & Licensing
|
|
502
|
+
|
|
503
|
+
**Open source, MIT licensed.** Use it, fork it, build on it.
|
|
504
|
+
|
|
505
|
+
Discovery endpoints are public — browse the catalog, read dataset
|
|
506
|
+
documentation, look up dimension codes, and query bounded row samples without
|
|
507
|
+
an API key. Key-authenticated access provides higher rate limits and larger
|
|
508
|
+
result sets.
|
|
509
|
+
|
|
510
|
+
The API does not expose arbitrary SQL, raw source tables, bulk database dumps,
|
|
511
|
+
or write operations. It never will.
|
|
512
|
+
|
|
513
|
+
---
|
|
514
|
+
|
|
515
|
+
## ⚠️ Caveats
|
|
516
|
+
|
|
517
|
+
This is an analytical tool, not a procurement authority.
|
|
518
|
+
|
|
519
|
+
- **FPDS obligations include deobligations and corrections** — dollar values can
|
|
520
|
+
be negative for individual transactions
|
|
521
|
+
- **Current fiscal year data is year-to-date** — flagged with
|
|
522
|
+
`is_current_fiscal_year_ytd` so you know
|
|
523
|
+
- **Vendor records exclude entries missing key fields** — coverage is high but
|
|
524
|
+
not 100%
|
|
525
|
+
- **Q4 obligation share is NULL for deobligation-heavy entities** — when an
|
|
526
|
+
entity's full-year obligations are zero or negative, the ratio is undefined
|
|
527
|
+
- **This is decision support, not legal advice** — always verify against primary
|
|
528
|
+
sources for formal procurement actions
|
|
529
|
+
|
|
530
|
+
Full details: [docs/CAVEATS.md](docs/CAVEATS.md)
|
|
531
|
+
|
|
532
|
+
---
|
|
533
|
+
|
|
534
|
+
Got down here and still couldn't find what you need? No worries! Don't hesitate to reach out with your ideas and we'll build it for you.
|
|
535
|
+
|
|
536
|
+
Phone: (305) 522-8140 | Email: nkalosakenyon@kenosaconsulting.com | Linkedin: https://www.linkedin.com/in/nate-kalosa-kenyon-84b132190/
|
|
537
|
+
|
|
538
|
+
<p align="center">
|
|
539
|
+
Built by <a href="https://kenosaconsulting.com">Kenosa Consulting</a><br/>
|
|
540
|
+
<em>Evidence-first federal intelligence.</em>
|
|
541
|
+
</p>
|