# 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 base contract data from USASpending.gov.

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

- **Class 1** - high volume + high frequency (systematic winners, $5M+ across 3+ base contracts)
- **Class 2** - high volume + low frequency (concentrated risk, $5M+ but fewer than 3 base contracts)
- **Class 3** - low volume + high frequency (growth pipeline, under $5M but 3+ base contracts)
- **Class 4** - low volume + low frequency (entry level, under $5M 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(base_dollars=12_000_000, base_contract_count=5)
print(cls)   # PostureClass.CLASS_1

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

# Concentrated risk: high dollars, few contracts
result = classify_contractor(base_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 |
|------|-----------|-----------------|
| Base contract dollars (5yr) | $5M | Volume of competitively won work |
| Base contract count (5yr) | 3 | Frequency of distinct wins |

"Base contracts" means definitive contracts, purchase orders, and BPA calls. Delivery orders and task orders are excluded from classification (they inflate frequency without representing separate competitions).

| Posture Class | Volume | Frequency | Profile |
|---------------|--------|-----------|---------|
| Class 1 | $5M+ | 3+ contracts | Systematic winner, repeatable pipeline |
| Class 2 | $5M+ | <3 contracts | Concentrated risk, few large awards |
| Class 3 | <$5M | 3+ contracts | Growth pipeline, building track record |
| Class 4 | <$5M | <3 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
