# FedComp Index Scoring

![FedComp Index](https://fedcompindex.org/static/img/FedComp-Index-Tabularium-1.png)

Federal contractor posture classification. Assigns every federal contractor to one of four Posture Classes using two-axis thresholds on USASpending.gov award data.

No composite score. No weighted sum. Classification is structural: total contract dollars ($5M threshold, base + delivery orders) crossed with base contract count (3 threshold).

- **Class 1** - high volume + high frequency (systematic winners, $5M+ total across 3+ base contracts)
- **Class 2** - high volume + low frequency (concentrated risk, $5M+ total but fewer than 3 base contracts)
- **Class 3** - low volume + high frequency (growth pipeline, under $5M total but 3+ base contracts)
- **Class 4** - low volume + low frequency (entry level, under $5M total and fewer than 3 base contracts)

## Install

```bash
pip install fedcomp-index
```

## Usage

```python
from fedcomp_index_scoring import classify, classify_contractor, PostureClass

# Classify from two axes
cls = classify(total_dollars=12_000_000, base_contract_count=5)
print(cls)   # PostureClass.CLASS_1

# Get a full result object
result = classify_contractor(total_dollars=12_000_000, base_contract_count=5)
print(result.posture_class)         # PostureClass.CLASS_1
print(result.total_dollars)         # 12000000
print(result.base_contract_count)   # 5

# Concentrated risk: high dollars, few contracts
result = classify_contractor(total_dollars=8_000_000, base_contract_count=1)
print(result.posture_class)   # PostureClass.CLASS_2
```

## Classification methodology (v1.1)

Two axes, no normalization, no composite score:

| Axis | Threshold | What it measures |
|------|-----------|-----------------|
| Total contract dollars (5yr) | $5M | Volume of all obligated dollars (base + delivery orders) |
| Base contract count (5yr) | 3 | Frequency of distinct base contract wins |

Volume includes all contract types: definitive contracts, purchase orders, BPA calls, delivery orders, and task orders. Frequency counts definitive contracts and purchase orders only (BPA calls, delivery orders, and task orders are excluded from frequency because they do not represent independent competitions). Obligation Density (OD) = total dollars / base contracts.

| Posture Class | Volume | Frequency | Profile |
|---------------|--------|-----------|---------|
| Class 1 | $5M+ total | 3+ base contracts | Systematic winner, repeatable pipeline |
| Class 2 | $5M+ total | <3 base contracts | Concentrated risk, few large awards |
| Class 3 | <$5M total | 3+ base contracts | Growth pipeline, building track record |
| Class 4 | <$5M total | <3 base contracts | Entry level or dormant |

## Additional metrics

Beyond classification, this package provides:

**Velocity** - cadence-based per contractor. Compares early-half vs late-half award gaps to detect accelerating, on pace, slowing, declining, or inactive patterns. Requires 2+ base contracts.

```python
from fedcomp_index_scoring import compute_velocity

v = compute_velocity(["2023-01-15", "2024-06-01", "2025-02-10"])
print(v["cadence"])   # "accelerating" / "on pace" / "slowing" / etc.
```

**Proximity Map** - inverse-frequency-squared weighting on shared NAICS/PSC codes, with scale filter (ratio^2 penalty for volume mismatches). Returns top 6 neighbors.

```python
from fedcomp_index_scoring import build_proximity_map

neighbors = build_proximity_map(
    target_codes={"541511": 12, "R425": 3},
    target_volume=8_000_000,
    candidates=[
        {"id": "ABC", "codes": {"541511", "R425"}, "volume": 6_000_000},
        {"id": "DEF", "codes": {"541511"}, "volume": 50_000_000},
    ],
)
# ABC ranks higher: shared rare code + similar scale
```

**Neighborhood Density** - fraction of a contractor's neighbors that are also neighbors of each other. Higher density = tighter competitive cluster.

```python
from fedcomp_index_scoring import neighborhood_density

d = neighborhood_density(
    neighbor_sets={"A": {"B", "C"}, "B": {"A", "C"}, "C": {"A"}},
    target_neighbors={"A", "B", "C"},
)
```

Full methodology: [fedcompindex.org/methodology](https://fedcompindex.org/methodology/)

## 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
- [SBA.gov](https://www.sba.gov/) - small business certification verification

## Live rankings

Classified contractor rankings with dossier pages, proximity maps, and velocity tracking:

- [Nevada](https://fedcompindex.org/nv/) - 348 contractors classified

## Datasets

Pre-classified 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)

## Also available on npm

```bash
npm install fedcomp-index-scoring
```

- [fedcomp-index](https://www.npmjs.com/package/fedcomp-index) - meta-package
- [fedcomp-index-scoring](https://www.npmjs.com/package/fedcomp-index-scoring) - classification engine
- [fedcomp-index-data](https://www.npmjs.com/package/fedcomp-index-data) - pre-classified datasets

## 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/)
- Source: [https://github.com/fedcompindex/FedCompIndex](https://github.com/fedcompindex/FedCompIndex)
- PyPI: [https://pypi.org/project/fedcomp-index/](https://pypi.org/project/fedcomp-index/)
- PyPI (Scoring): [https://pypi.org/project/fedcomp-index-scoring/](https://pypi.org/project/fedcomp-index-scoring/)
- PyPI (Data): [https://pypi.org/project/fedcomp-index-data/](https://pypi.org/project/fedcomp-index-data/)
- 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
