# FedComp Index

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

Federal contractor competitive intelligence. Scores every federal contractor in a state from 0 to 100 based on public award data, assigns posture classes, and provides pre-scored datasets.

This is the meta-package. It installs:

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

## Install

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

## Usage

```python
from fedcomp_index import score_contractor, load_state, lookup, PostureClass

# Score a contractor from raw award data
result = score_contractor(
    total_awards_usd=45_000_000,
    last_award_date="2025-09-15"
)
print(result.fedcomp_index)   # 65
print(result.posture_class)   # PostureClass.CLASS_1

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

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

## Posture scoring methodology

Two index drivers, no normalization:

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

Posture classes are fixed thresholds:

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

## 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 score computation |
| [fedcomp-index-data](https://pypi.org/project/fedcomp-index-data/) | Pre-scored 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, CAGE/UEI
- [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) - scoring engine
- [fedcomp-index-data](https://www.npmjs.com/package/fedcomp-index-data) - pre-scored 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
