# FedComp Index

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

Federal contractor competitive intelligence. Classifies every federal contractor in a state into one of four Posture Classes using two-axis thresholds on USASpending award data, then provides proximity maps, velocity tracking, and pre-classified datasets.

This is the meta-package. It installs:

- **[fedcomp-index-scoring](https://pypi.org/project/fedcomp-index-scoring/)** - posture classification engine
- **[fedcomp-index-data](https://pypi.org/project/fedcomp-index-data/)** - pre-classified contractor datasets

## Install

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

## Usage

```python
from fedcomp_index import classify, classify_contractor, load_state, lookup, PostureClass

# Classify a contractor 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

# Load pre-classified data
contractors = load_state("NV")
print(f"{len(contractors)} contractors classified")

# Look up by UEI
c = lookup("CGAKREGGN9J3")
print(c["legal_name"])        # FLEET VEHICLE SOURCE INC
print(c["posture_class"])     # Class 1
```

## Classification methodology (v1.1)

Two axes, no composite score, no weighted sum:

| 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 (base + delivery orders). Frequency counts base contracts only.

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

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

## Packages

| Package | What it does |
|---------|-------------|
| [fedcomp-index](https://pypi.org/project/fedcomp-index/) | Meta-package (this one) |
| [fedcomp-index-scoring](https://pypi.org/project/fedcomp-index-scoring/) | Posture classification engine |
| [fedcomp-index-data](https://pypi.org/project/fedcomp-index-data/) | Pre-classified contractor datasets |

## Data sources

All public federal records:
- [USASpending.gov](https://www.usaspending.gov/) - award history, dollar amounts, agencies, NAICS, PSC
- [SAM.gov](https://sam.gov/) - entity registration, certifications
- [SBA.gov](https://www.sba.gov/) - certification verification

## Datasets

- [Nevada Federal Contractors](https://huggingface.co/datasets/npetro6/nevada-federal-contractors) (HuggingFace)
- [Nevada Federal Contract Awards](https://huggingface.co/datasets/npetro6/nevada-federal-awards) (HuggingFace)
- [Nevada Federal Contractors](https://www.kaggle.com/datasets/npetro6/nevada-federal-contractors-fedcomp-index) (Kaggle)

## Also available on npm

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

- [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
