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.
@@ -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>