fedcomp-index-scoring 2026.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FedComp Index
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# FedComp Index Scoring
+
+![FedComp Index](https://fedcompindex.org/static/img/FedComp-Index-Tabularium-1.png)
+
+Federal contractor posture scoring. Scores any federal contractor from 0 to 100 based on public award data from USASpending.gov.
+
+Each contractor receives a [FedComp Index](https://fedcompindex.org/) score and a posture class:
+
+- **Class 1** (score 60+) - dominant award volume, typically $100M+ over 5 years
+- **Class 2** (score 40-59) - mid-tier, typically $5M-$100M
+- **Class 3** (below 40) - emerging or low-volume
+
+## Install
+
+```bash
+npm install fedcomp-index-scoring
+```
+
+## Usage
+
+```javascript
+const { scoreContractor, PostureClass } = require("fedcomp-index-scoring");
+
+const result = scoreContractor(15_000_000, "2025-09-15");
+
+result.fedcompIndex;   // 58
+result.postureClass;   // "Class 2"
+result.volumeDriver;   // 53
+result.recencyDriver;  // 100
+```
+
+## FedComp Index scoring methodology
+
+Two drivers, no normalization:
+
+| Driver | Weight | How it works |
+|--------|--------|-------------|
+| Award volume | 90% | log10 of total dollars won, mapped to 0-100 |
+| Award recency | 10% | Last award date, bucketed by age |
+
+The FedComp Index score is an absolute measure. A contractor scoring 60 always represents roughly the same award volume regardless of state or time period. Scores are not percentile-ranked against peers.
+
+Posture classes use fixed thresholds tied to the score:
+
+| Posture class | FedComp Index score | Typical award volume |
+|---------------|--------------------|--------------------|
+| Class 1 | 60-100 | $100M+ |
+| Class 2 | 40-59 | $5M-$100M |
+| Class 3 | 0-39 | Under $5M |
+
+Full methodology: [fedcompindex.org/methodology](https://fedcompindex.org/methodology/)
+
+See the [FedComp Index Glossary](https://github.com/npetro6/fedcomp-index-glossary) for complete terminology definitions.
+
+## Related packages
+
+| Package | What it does |
+|---------|-------------|
+| [fedcomp-index](https://www.npmjs.com/package/fedcomp-index) | Meta-package (installs both) |
+| [fedcomp-index-scoring](https://www.npmjs.com/package/fedcomp-index-scoring) | Scoring engine (this one) |
+| [fedcomp-index-data](https://www.npmjs.com/package/fedcomp-index-data) | Pre-scored contractor datasets |
+
+## Also available on PyPI
+
+```bash
+pip install fedcomp-index-scoring
+```
+
+- [fedcomp-index](https://pypi.org/project/fedcomp-index/) - meta-package
+- [fedcomp-index-scoring](https://pypi.org/project/fedcomp-index-scoring/) - scoring engine
+- [fedcomp-index-data](https://pypi.org/project/fedcomp-index-data/) - pre-scored datasets
+
+## Data sources
+
+All data is sourced from public federal records:
+
+- [USASpending.gov](https://www.usaspending.gov/) - award history, dollar amounts, agencies, NAICS codes, PSC codes
+- [SAM.gov](https://sam.gov/) - entity registration, certifications, CAGE/UEI
+- [SBA.gov](https://www.sba.gov/) - small business certification verification
+
+## Live rankings
+
+Scored contractor rankings with dossier pages, proximity maps, and spectator tracking:
+
+- [Nevada](https://fedcompindex.org/nv/) - 349 contractors scored
+
+## Datasets
+
+Pre-scored datasets available for download:
+
+- [Nevada Federal Contractors - FedComp Index](https://huggingface.co/datasets/npetro6/nevada-federal-contractors) (HuggingFace)
+- [Nevada Federal Contract Awards - Monthly](https://huggingface.co/datasets/npetro6/nevada-federal-awards) (HuggingFace)
+- [Nevada Federal Contractors - FedComp Index](https://www.kaggle.com/datasets/npetro6/nevada-federal-contractors-fedcomp-index) (Kaggle)
+- [Nevada Federal Contract Awards - Monthly](https://www.kaggle.com/datasets/npetro6/nevada-federal-awards-2026-02) (Kaggle)
+
+## Links
+
+- Website: [https://fedcompindex.org/](https://fedcompindex.org/)
+- Nevada Rankings: [https://fedcompindex.org/nv/](https://fedcompindex.org/nv/)
+- Methodology: [https://fedcompindex.org/methodology/](https://fedcompindex.org/methodology/)
+- Tabularium: [https://fedcompindex.org/tabularium/](https://fedcompindex.org/tabularium/)
+- FAQ: [https://fedcompindex.org/faq/](https://fedcompindex.org/faq/)
+- Glossary: [https://github.com/npetro6/fedcomp-index-glossary](https://github.com/npetro6/fedcomp-index-glossary)
+- Source: [https://github.com/npetro6/FedCompIndex](https://github.com/npetro6/FedCompIndex)
+- npm packages: [https://github.com/npetro6/fedcomp-index-npm](https://github.com/npetro6/fedcomp-index-npm)
+- PyPI: [https://pypi.org/project/fedcomp-index/](https://pypi.org/project/fedcomp-index/)
+- HuggingFace: [https://huggingface.co/datasets/npetro6/nevada-federal-contractors](https://huggingface.co/datasets/npetro6/nevada-federal-contractors)
+- Kaggle: [https://www.kaggle.com/datasets/npetro6/nevada-federal-contractors-fedcomp-index](https://www.kaggle.com/datasets/npetro6/nevada-federal-contractors-fedcomp-index)
+
+## Citation
+
+```bibtex
+@software{fedcomp_index,
+  title = {FedComp Index},
+  author = {FedComp Index},
+  url = {https://fedcompindex.org/},
+  year = {2026}
+}
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,17 @@
+export declare const PostureClass: {
+  readonly CLASS_1: "Class 1";
+  readonly CLASS_2: "Class 2";
+  readonly CLASS_3: "Class 3";
+};
+
+export interface FedCompResult {
+  fedcompIndex: number;
+  postureClass: string;
+  volumeDriver: number;
+  recencyDriver: number;
+}
+
+export declare function scoreContractor(
+  totalAwardsUsd: number,
+  lastAwardDate?: string | Date | null
+): FedCompResult;

package/index.js

@@ -0,0 +1,89 @@
+"use strict";
+
+/**
+ * FedComp Index Scoring - Federal contractor posture scoring.
+ *
+ * Scores federal contractors on a 0-100 scale based on public award data
+ * from USASpending.gov. Each contractor is assigned a FedComp Index score
+ * and a posture class (Class 1, Class 2, or Class 3).
+ *
+ * Methodology: https://fedcompindex.org/methodology/
+ * Data: https://huggingface.co/datasets/npetro6/nevada-federal-contractors
+ */
+
+const PostureClass = Object.freeze({
+  CLASS_1: "Class 1",
+  CLASS_2: "Class 2",
+  CLASS_3: "Class 3",
+});
+
+// Scoring constants
+const W_VOLUME = 0.9;
+const W_RECENCY = 0.1;
+const LOG_MIN = 4; // log10($10K)
+const LOG_MAX = 10; // log10($10B)
+
+function volumeDriver(totalAwardsUsd) {
+  if (typeof totalAwardsUsd !== "number" || !isFinite(totalAwardsUsd) || totalAwardsUsd <= 0) return 0;
+  const logVal = Math.log10(totalAwardsUsd);
+  return Math.max(0, Math.min(100, Math.round(((logVal - LOG_MIN) / (LOG_MAX - LOG_MIN)) * 100)));
+}
+
+function recencyDriver(lastAwardDate) {
+  if (!lastAwardDate) return 0;
+  let parsed;
+  if (typeof lastAwardDate === "string") {
+    const s = lastAwardDate.length === 7 ? lastAwardDate + "-01" : lastAwardDate;
+    parsed = new Date(s + "T00:00:00Z");
+  } else if (lastAwardDate instanceof Date) {
+    parsed = lastAwardDate;
+  } else {
+    return 0;
+  }
+  if (isNaN(parsed.getTime())) return 0;
+  const daysAgo = Math.floor((Date.now() - parsed.getTime()) / 86400000);
+  if (daysAgo <= 365) return 100;
+  if (daysAgo <= 730) return 60;
+  if (daysAgo <= 1095) return 30;
+  if (daysAgo <= 1825) return 10;
+  return 0;
+}
+
+function classify(score) {
+  if (score >= 60) return PostureClass.CLASS_1;
+  if (score >= 40) return PostureClass.CLASS_2;
+  return PostureClass.CLASS_3;
+}
+
+/**
+ * Compute the FedComp Index score and posture class for a contractor.
+ *
+ * @param {number} totalAwardsUsd - Total federal award dollars over trailing 5-year window.
+ * @param {string|Date|null} [lastAwardDate] - Date of most recent award. String "YYYY-MM-DD" or "YYYY-MM" or a Date object.
+ * @returns {{ fedcompIndex: number, postureClass: string, volumeDriver: number, recencyDriver: number }}
+ *
+ * @example
+ * const { scoreContractor } = require("fedcomp-index-scoring");
+ *
+ * const result = scoreContractor(15_000_000, "2025-09-15");
+ * console.log(result.fedcompIndex);  // 58
+ * console.log(result.postureClass);  // "Class 2"
+ */
+function scoreContractor(totalAwardsUsd, lastAwardDate) {
+  if (totalAwardsUsd !== null && typeof totalAwardsUsd === 'object') {
+    throw new TypeError('scoreContractor(totalAwardsUsd, lastAwardDate) takes two positional arguments, not an object');
+  }
+  const d1 = volumeDriver(totalAwardsUsd);
+  const d2 = recencyDriver(lastAwardDate || null);
+  const raw = d1 * W_VOLUME + d2 * W_RECENCY;
+  const fedcompIndex = Math.min(100, Math.max(0, Math.round(raw)));
+
+  return {
+    fedcompIndex,
+    postureClass: classify(fedcompIndex),
+    volumeDriver: d1,
+    recencyDriver: d2,
+  };
+}
+
+module.exports = { scoreContractor, PostureClass };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "fedcomp-index-scoring",
+  "version": "2026.3.2",
+  "description": "FedComp Index scoring engine. Computes posture scores and posture classes for federal contractors from USASpending award data.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "LICENSE"
+  ],
+  "keywords": [
+    "federal contracting",
+    "government procurement",
+    "small business",
+    "posture scoring",
+    "fedcomp index",
+    "posture class",
+    "usaspending",
+    "sam.gov",
+    "contractor scoring",
+    "federal awards",
+    "scoring algorithm",
+    "procurement",
+    "NAICS",
+    "competitive intelligence",
+    "competitive topology",
+    "obligation-verified",
+    "registration-obligation gap",
+    "NAICS corridor",
+    "proximity map",
+    "competitive radius"
+  ],
+  "author": "FedComp Index <contact@fedcompindex.org>",
+  "license": "MIT",
+  "homepage": "https://fedcompindex.org/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/npetro6/fedcomp-index-npm.git",
+    "directory": "packages/fedcomp-index-scoring"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/npetro6/FedCompIndex/issues"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://fedcompindex.org/"
+  }
+}